tiny-essentials 1.16.2 → 1.17.0

package/dist/v1/TinyUploadClicker.js

@@ -3599,20 +3599,22 @@ function saveJsonFile(filename, data, spaces = 2) {
 }
 
 /**
- * Loads and parses a JSON from a remote URL using Fetch API.
- *
- * @param {string} url - The full URL to fetch JSON from.
- * @param {Object} [options] - Optional settings.
- * @param {string} [options.method="GET"] - HTTP method to use (GET, POST, etc.).
- * @param {any} [options.body] - Request body (only for methods like POST, PUT).
- * @param {number} [options.timeout=0] - Timeout in milliseconds (ignored if signal is provided).
- * @param {number} [options.retries=0] - Number of retry attempts (ignored if signal is provided).
- * @param {Headers|Record<string, *>} [options.headers={}] - Additional headers.
- * @param {AbortSignal|null} [options.signal] - External AbortSignal; disables timeout and retries.
- * @returns {Promise<*>} Parsed JSON object.
- * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
+ * @typedef {Object} FetchTemplateOptions
+ * @property {string} [method="GET"] - HTTP method to use (GET, POST, etc.).
+ * @property {any} [body] - Request body (only for methods like POST, PUT).
+ * @property {number} [timeout=0] - Timeout in milliseconds (ignored if signal is provided).
+ * @property {number} [retries=0] - Number of retry attempts (ignored if signal is provided).
+ * @property {Headers|Record<string, *>} [headers={}] - Additional headers.
+ * @property {AbortSignal|null} [signal] - External AbortSignal; disables timeout and retries.
+ */
+
+/**
+ * @param {string} url - The full URL to fetch data from.
+ * @param {FetchTemplateOptions} [options] - Optional settings.
+ * @returns {Promise<Response>} Result data.
+ * @throws {Error} Throws if fetch fails, times out.
  */
-async function fetchJson(
+async function fetchTemplate(
   url,
   { method = 'GET', body, timeout = 0, retries = 0, headers = {}, signal = null } = {},
 ) {
@@ -3671,17 +3673,7 @@ async function fetchJson(
       if (timer) clearTimeout(timer);
 
       if (!response.ok) throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
-
-      const contentType = response.headers.get('content-type') || '';
-      if (!contentType.includes('application/json'))
-        throw new Error(`Unexpected content-type: ${contentType}`);
-
-      const data = await response.json();
-
-      if (!Array.isArray(data) && !isJsonObject(data))
-        throw new Error('Received invalid data instead of valid JSON.');
-
-      return data;
+      return response;
     } catch (err) {
       lastError = /** @type {Error} */ (err);
       if (signal) break; // if an external signal came, it does not retry
@@ -3695,6 +3687,63 @@ async function fetchJson(
   );
 }
 
+/**
+ * Loads and parses a JSON from a remote URL using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch JSON from.
+ * @param {Object} [options] - Optional settings.
+ * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
+ * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
+ */
+async function fetchJson(url, options) {
+  return new Promise((resolve, reject) => {
+    fetchTemplate(url, options)
+      .then(async (res) => {
+        const contentType = res.headers.get('content-type') || '';
+        if (!contentType.includes('application/json'))
+          throw new Error(`Unexpected content-type: ${contentType}`);
+
+        const data = await res.json();
+
+        if (!Array.isArray(data) && !isJsonObject(data))
+          throw new Error('Received invalid data instead of valid JSON.');
+
+        return resolve(data);
+      })
+      .catch(reject);
+  });
+}
+
+/**
+ * Loads a remote file as a Blob using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {Object} [options] - Optional fetch options.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @returns {Promise<Blob>} - The fetched file as a Blob.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ */
+async function fetchBlob(url, allowedMimeTypes, options) {
+  return new Promise((resolve, reject) => {
+    fetchTemplate(url, options)
+      .then(async (res) => {
+        const contentType = res.headers.get('content-type') || '';
+
+        if (
+          Array.isArray(allowedMimeTypes) &&
+          allowedMimeTypes.length > 0 &&
+          !allowedMimeTypes.some((type) => contentType.includes(type))
+        ) {
+          throw new Error(`Blocked MIME type: ${contentType}`);
+        }
+
+        const data = await res.blob();
+        return resolve(data);
+      })
+      .catch(reject);
+  });
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -4281,6 +4330,21 @@ const {
  * @typedef {Element|Window} ElementAndWindow
  */
 
+/**
+ * Represents a raw DOM element/window/document or an instance of TinyHtml.
+ * This type is used to abstract interactions with both plain elements
+ * and wrapped elements via the TinyHtml class.
+ *
+ * @typedef {ElementAndWinAndDoc|TinyHtml} TinyElementAndWinAndDoc
+ */
+
+/**
+ * Represents a value that can be either a DOM Element, or the global Window object, or the document object.
+ * Useful for functions that operate generically on scrollable or measurable targets.
+ *
+ * @typedef {Element|Window|Document} ElementAndWinAndDoc
+ */
+
 /**
  * A parameter type used for filtering or matching elements.
  * It can be:
@@ -4297,7 +4361,7 @@ const {
  * Elements accepted as constructor values for TinyHtml.
  * These include common DOM elements and root containers.
  *
- * @typedef {Window|Element|Document} ConstructorElValues
+ * @typedef {Window|Element|Document|Text} ConstructorElValues
  */
 
 /**
@@ -4418,40 +4482,114 @@ class TinyHtml_TinyHtml {
 
   static Utils = { ...collision_namespaceObject };
 
+  /**
+   * Creates a new DOM element with the specified tag name and options, then wraps it in a TinyHtml instance.
+   *
+   * @param {string} tagName - The tag name of the element to create (e.g., 'div', 'span').
+   * @param {ElementCreationOptions} ops - Optional settings for creating the element.
+   * @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM element.
+   * @throws {TypeError} If tagName is not a string or ops is not an object.
+   */
+  static createElement(tagName, ops) {
+    if (typeof tagName !== 'string')
+      throw new TypeError(`[TinyHtml] createElement(): The tagName must be a string.`);
+    if (typeof ops !== 'undefined' && typeof ops !== 'object')
+      throw new TypeError(`[TinyHtml] createElement(): The ops must be a object.`);
+    return new TinyHtml_TinyHtml(document.createElement(tagName, ops));
+  }
+
+  /**
+   * Creates a new TinyHtml instance that wraps a DOM TextNode.
+   *
+   * This method is useful when you want to insert raw text content into the DOM
+   * without it being interpreted as HTML. The returned instance behaves like any
+   * other TinyHtml element and can be appended or manipulated as needed.
+   *
+   * @param {string} value - The plain text content to be wrapped in a TextNode.
+   * @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM TextNode.
+   * @throws {TypeError} If the provided value is not a string.
+   */
+  static createTextNode(value) {
+    if (typeof value !== 'string')
+      throw new TypeError(`[TinyHtml] createTextNode(): The value must be a string.`);
+    return new TinyHtml_TinyHtml(document.createTextNode(value));
+  }
+
+  /**
+   * Creates an HTMLElement or TextNode from an HTML string.
+   * Supports both elements and plain text.
+   *
+   * @param {string} htmlString - The HTML string to convert.
+   * @returns {TinyHtml} - A single HTMLElement or TextNode.
+   */
+  static createElementFromHTML(htmlString) {
+    const template = document.createElement('template');
+    htmlString = htmlString.trim();
+
+    // If it's only text (e.g., no "<" tag), return a TextNode
+    if (!htmlString.startsWith('<')) {
+      return TinyHtml_TinyHtml.createTextNode(htmlString);
+    }
+
+    template.innerHTML = htmlString;
+    if (!(template.content.firstChild instanceof Element)) throw new Error('');
+    return new TinyHtml_TinyHtml(template.content.firstChild);
+  }
+
   /**
    * Queries the document for the first element matching the CSS selector and wraps it in a TinyHtml instance.
    *
    * @param {string} selector - A valid CSS selector string.
-   * @returns {TinyHtml} A TinyHtml instance wrapping the matched element.
-   * @throws {Error} If no element matches the selector.
+   * @param {Document|Element} elem - Target element.
+   * @returns {TinyHtml|null} A TinyHtml instance wrapping the matched element.
    */
-  static query(selector) {
-    const newEl = document.querySelector(selector);
-    if (!newEl) throw new Error(`[TinyHtml] query(): No element found for selector "${selector}".`);
+  static query(selector, elem = document) {
+    const newEl = elem.querySelector(selector);
+    if (!newEl) return null;
     return new TinyHtml_TinyHtml(newEl);
   }
 
+  /**
+   * Queries the element for the first element matching the CSS selector and wraps it in a TinyHtml instance.
+   *
+   * @param {string} selector - A valid CSS selector string.
+   * @returns {TinyHtml|null} A TinyHtml instance wrapping the matched element.
+   */
+  querySelector(selector) {
+    return TinyHtml_TinyHtml.query(selector, TinyHtml_TinyHtml._preElem(this, 'query'));
+  }
+
   /**
    * Queries the document for all elements matching the CSS selector and wraps them in TinyHtml instances.
    *
    * @param {string} selector - A valid CSS selector string.
+   * @param {Document|Element} elem - Target element.
    * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
    */
-  static queryAll(selector) {
-    const newEls = document.querySelectorAll(selector);
+  static queryAll(selector, elem = document) {
+    const newEls = elem.querySelectorAll(selector);
     return TinyHtml_TinyHtml.toTinyElm([...newEls]);
   }
 
+  /**
+   * Queries the element for all elements matching the CSS selector and wraps them in TinyHtml instances.
+   *
+   * @param {string} selector - A valid CSS selector string.
+   * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
+   */
+  querySelectorAll(selector) {
+    return TinyHtml_TinyHtml.queryAll(selector, TinyHtml_TinyHtml._preElem(this, 'queryAll'));
+  }
+
   /**
    * Retrieves an element by its ID and wraps it in a TinyHtml instance.
    *
    * @param {string} selector - The ID of the element to retrieve.
-   * @returns {TinyHtml} A TinyHtml instance wrapping the found element.
-   * @throws {Error} If no element is found with the specified ID.
+   * @returns {TinyHtml|null} A TinyHtml instance wrapping the found element.
    */
   static getById(selector) {
     const newEl = document.getElementById(selector);
-    if (!newEl) throw new Error(`[TinyHtml] getById(): No element found with ID "${selector}".`);
+    if (!newEl) return null;
     return new TinyHtml_TinyHtml(newEl);
   }
 
@@ -4459,13 +4597,24 @@ class TinyHtml_TinyHtml {
    * Retrieves all elements with the specified class name and wraps them in TinyHtml instances.
    *
    * @param {string} selector - The class name to search for.
+   * @param {Document|Element} elem - Target element.
    * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
    */
-  static getByClassName(selector) {
-    const newEls = document.getElementsByClassName(selector);
+  static getByClassName(selector, elem = document) {
+    const newEls = elem.getElementsByClassName(selector);
     return TinyHtml_TinyHtml.toTinyElm([...newEls]);
   }
 
+  /**
+   * Retrieves all elements with the specified class name and wraps them in TinyHtml instances.
+   *
+   * @param {string} selector - The class name to search for.
+   * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+   */
+  getElementsByClassName(selector) {
+    return TinyHtml_TinyHtml.getByClassName(selector, TinyHtml_TinyHtml._preElem(this, 'getByClassName'));
+  }
+
   /**
    * Retrieves all elements with the specified name attribute and wraps them in TinyHtml instances.
    *
@@ -4483,13 +4632,30 @@ class TinyHtml_TinyHtml {
    *
    * @param {string} localName - The local name (tag) of the elements to search for.
    * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
+   * @param {Document|Element} elem - Target element.
    * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
    */
-  static getByTagNameNS(localName, namespaceURI = 'http://www.w3.org/1999/xhtml') {
-    const newEls = document.getElementsByTagNameNS(namespaceURI, localName);
+  static getByTagNameNS(localName, namespaceURI = 'http://www.w3.org/1999/xhtml', elem = document) {
+    const newEls = elem.getElementsByTagNameNS(namespaceURI, localName);
     return TinyHtml_TinyHtml.toTinyElm([...newEls]);
   }
 
+  /**
+   * Retrieves all elements with the specified local tag name within the given namespace URI,
+   * and wraps them in TinyHtml instances.
+   *
+   * @param {string} localName - The local name (tag) of the elements to search for.
+   * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
+   * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+   */
+  getElementsByTagNameNS(localName, namespaceURI = 'http://www.w3.org/1999/xhtml') {
+    return TinyHtml_TinyHtml.getByTagNameNS(
+      localName,
+      namespaceURI,
+      TinyHtml_TinyHtml._preElem(this, 'getByTagNameNS'),
+    );
+  }
+
   //////////////////////////////////////////////////////////////////
 
   /**
@@ -4770,6 +4936,45 @@ class TinyHtml_TinyHtml {
     return TinyHtml_TinyHtml._preElemTemplate(elems, where, [Element, Window], ['Element', 'Window']);
   }
 
+  /**
+   * Ensures the input is returned as an array.
+   * Useful to normalize operations across multiple or single element/window/document elements.
+   *
+   * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/window element or array of html elements.
+   * @param {string} where - The method or context name where validation is being called.
+   * @returns {ElementAndWindow[]} - Always returns an array of element/window elements.
+   * @readonly
+   */
+  static _preElemsAndWinAndDoc(elems, where) {
+    const result = TinyHtml_TinyHtml._preElemsTemplate(
+      elems,
+      where,
+      [Element, Window, Document],
+      ['Element', 'Window', 'Document'],
+    );
+    return result.map((elem) => (!(elem instanceof Document) ? elem : elem.documentElement));
+  }
+
+  /**
+   * Ensures the input is returned as an single element/window/document element.
+   * Useful to normalize operations across multiple or single element/window/document elements.
+   *
+   * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/window element or array of html elements.
+   * @param {string} where - The method or context name where validation is being called.
+   * @returns {ElementAndWindow} - Always returns an single element/window element.
+   * @readonly
+   */
+  static _preElemAndWinAndDoc(elems, where) {
+    const result = TinyHtml_TinyHtml._preElemTemplate(
+      elems,
+      where,
+      [Element, Window, Document],
+      ['Element', 'Window', 'Document'],
+    );
+    if (result instanceof Document) return result.documentElement;
+    return result;
+  }
+
   /**
    * Normalizes and converts one or more DOM elements (or TinyHtml instances)
    * into an array of `TinyHtml` instances.
@@ -5116,12 +5321,13 @@ class TinyHtml_TinyHtml {
    * @param {string} key - The key under which the data will be stored.
    * @param {any} value - The value to store.
    * @param {boolean} [isPrivate=false] - Whether to store the data in the private store.
-   * @returns {void}
+   * @returns {TinyElement}
    */
   static setData(el, key, value, isPrivate = false) {
     const data = TinyHtml_TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('setData', el);
     if (typeof key !== 'string') throw new TypeError('The key must be a string.');
     data[key] = value;
+    return el;
   }
 
   /**
@@ -5130,7 +5336,7 @@ class TinyHtml_TinyHtml {
    * @param {string} key - The key under which the data will be stored.
    * @param {any} value - The value to store.
    * @param {boolean} [isPrivate=false] - Whether to store the data in the private store.
-   * @returns {void}
+   * @returns {TinyElement}
    */
   setData(key, value, isPrivate = false) {
     return TinyHtml_TinyHtml.setData(this, key, value, isPrivate);
@@ -5477,18 +5683,21 @@ class TinyHtml_TinyHtml {
   /**
    * Appends child elements or strings to the end of the target element(s).
    *
-   * @param {TinyElement | TinyElement[]} el - The target element(s) to receive children.
+   * @param {TinyElement} el - The target element(s) to receive children.
    * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
+   * @returns {TinyElement}
    */
   static append(el, ...children) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'append');
     elem.append(...TinyHtml_TinyHtml._appendChecker('append', ...children));
+    return el;
   }
 
   /**
    * Appends child elements or strings to the end of the target element(s).
    *
    * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
+   * @returns {TinyElement}
    */
   append(...children) {
     return TinyHtml_TinyHtml.append(this, ...children);
@@ -5497,18 +5706,21 @@ class TinyHtml_TinyHtml {
   /**
    * Prepends child elements or strings to the beginning of the target element(s).
    *
-   * @param {TinyElement | TinyElement[]} el - The target element(s) to receive children.
+   * @param {TinyElement} el - The target element(s) to receive children.
    * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
+   * @returns {TinyElement}
    */
   static prepend(el, ...children) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'prepend');
     elem.prepend(...TinyHtml_TinyHtml._appendChecker('prepend', ...children));
+    return el;
   }
 
   /**
    * Prepends child elements or strings to the beginning of the target element(s).
    *
    * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
+   * @returns {TinyElement}
    */
   prepend(...children) {
     return TinyHtml_TinyHtml.prepend(this, ...children);
@@ -5517,18 +5729,21 @@ class TinyHtml_TinyHtml {
   /**
    * Inserts elements or strings immediately before the target element(s) in the DOM.
    *
-   * @param {TinyElement | TinyElement[]} el - The target element(s) before which new content is inserted.
+   * @param {TinyElement} el - The target element(s) before which new content is inserted.
    * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
+   * @returns {TinyElement}
    */
   static before(el, ...children) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'before');
     elem.before(...TinyHtml_TinyHtml._appendChecker('before', ...children));
+    return el;
   }
 
   /**
    * Inserts elements or strings immediately before the target element(s) in the DOM.
    *
    * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
+   * @returns {TinyElement}
    */
   before(...children) {
     return TinyHtml_TinyHtml.before(this, ...children);
@@ -5537,18 +5752,21 @@ class TinyHtml_TinyHtml {
   /**
    * Inserts elements or strings immediately after the target element(s) in the DOM.
    *
-   * @param {TinyElement | TinyElement[]} el - The target element(s) after which new content is inserted.
+   * @param {TinyElement} el - The target element(s) after which new content is inserted.
    * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
+   * @returns {TinyElement}
    */
   static after(el, ...children) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'after');
     elem.after(...TinyHtml_TinyHtml._appendChecker('after', ...children));
+    return el;
   }
 
   /**
    * Inserts elements or strings immediately after the target element(s) in the DOM.
    *
    * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
+   * @returns {TinyElement}
    */
   after(...children) {
     return TinyHtml_TinyHtml.after(this, ...children);
@@ -5557,18 +5775,21 @@ class TinyHtml_TinyHtml {
   /**
    * Replaces the target element(s) in the DOM with new elements or text.
    *
-   * @param {TinyElement | TinyElement[]} el - The element(s) to be replaced.
+   * @param {TinyElement} el - The element(s) to be replaced.
    * @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
+   * @returns {TinyElement}
    */
   static replaceWith(el, ...newNodes) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'replaceWith');
     elem.replaceWith(...TinyHtml_TinyHtml._appendChecker('replaceWith', ...newNodes));
+    return el;
   }
 
   /**
    * Replaces the target element(s) in the DOM with new elements or text.
    *
    * @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
+   * @returns {TinyElement}
    */
   replaceWith(...newNodes) {
     return TinyHtml_TinyHtml.replaceWith(this, ...newNodes);
@@ -5579,6 +5800,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyNode | TinyNode[]} el - The element(s) to append.
    * @param {TinyNode | TinyNode[]} targets - Target element(s) where content will be appended.
+   * @returns {TinyNode|TinyNode[]}
    */
   static appendTo(el, targets) {
     const elems = TinyHtml_TinyHtml._preNodeElems(el, 'appendTo');
@@ -5588,12 +5810,14 @@ class TinyHtml_TinyHtml {
         target.appendChild(i === tars.length - 1 ? elem : elem.cloneNode(true)),
       );
     });
+    return el;
   }
 
   /**
    * Appends the given element(s) to each target element in sequence.
    *
    * @param {TinyNode | TinyNode[]} targets - Target element(s) where content will be appended.
+   * @returns {TinyNode|TinyNode[]}
    */
   appendTo(targets) {
     return TinyHtml_TinyHtml.appendTo(this, targets);
@@ -5604,6 +5828,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyElement | TinyElement[]} el - The element(s) to prepend.
    * @param {TinyElement | TinyElement[]} targets - Target element(s) where content will be prepended.
+   * @returns {TinyElement|TinyElement[]}
    */
   static prependTo(el, targets) {
     const elems = TinyHtml_TinyHtml._preElems(el, 'prependTo');
@@ -5614,12 +5839,14 @@ class TinyHtml_TinyHtml {
         .reverse()
         .forEach((elem) => target.prepend(i === tars.length - 1 ? elem : elem.cloneNode(true)));
     });
+    return el;
   }
 
   /**
    * Prepends the given element(s) to each target element in sequence.
    *
    * @param {TinyElement | TinyElement[]} targets - Target element(s) where content will be prepended.
+   * @returns {TinyElement|TinyElement[]}
    */
   prependTo(targets) {
     return TinyHtml_TinyHtml.prependTo(this, targets);
@@ -5631,6 +5858,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyNode | TinyNode[]} el - The element(s) to insert.
    * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
    * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert before, defaults to target.
+   * @returns {TinyNode|TinyNode[]}
    */
   static insertBefore(el, target, child = null) {
     const elem = TinyHtml_TinyHtml._preNodeElem(el, 'insertBefore');
@@ -5638,6 +5866,7 @@ class TinyHtml_TinyHtml {
     const childNode = TinyHtml_TinyHtml._preNodeElemWithNull(child, 'insertBefore');
     if (!targ.parentNode) throw new Error('');
     targ.parentNode.insertBefore(elem, childNode || targ);
+    return el;
   }
 
   /**
@@ -5645,6 +5874,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
    * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert before, defaults to target.
+   * @returns {TinyNode|TinyNode[]}
    */
   insertBefore(target, child) {
     return TinyHtml_TinyHtml.insertBefore(this, target, child);
@@ -5656,6 +5886,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyNode | TinyNode[]} el - The element(s) to insert.
    * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
    * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert after, defaults to target.
+   * @returns {TinyNode|TinyNode[]}
    */
   static insertAfter(el, target, child = null) {
     const elem = TinyHtml_TinyHtml._preNodeElem(el, 'insertAfter');
@@ -5663,6 +5894,7 @@ class TinyHtml_TinyHtml {
     const childNode = TinyHtml_TinyHtml._preNodeElemWithNull(child, 'insertBefore');
     if (!targ.parentNode) throw new Error('');
     targ.parentNode.insertBefore(elem, childNode || targ.nextSibling);
+    return el;
   }
 
   /**
@@ -5670,6 +5902,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
    * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert after, defaults to target.
+   * @returns {TinyNode|TinyNode[]}
    */
   insertAfter(target, child) {
     return TinyHtml_TinyHtml.insertAfter(this, target, child);
@@ -5681,6 +5914,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyNode | TinyNode[]} el - The new element(s) to insert.
    * @param {TinyNode | TinyNode[]} targets - The elements to be replaced.
+   * @returns {TinyNode|TinyNode[]}
    */
   static replaceAll(el, targets) {
     const elems = TinyHtml_TinyHtml._preNodeElems(el, 'replaceAll');
@@ -5692,6 +5926,7 @@ class TinyHtml_TinyHtml {
           parent.replaceChild(i === tars.length - 1 ? elem : elem.cloneNode(true), target);
       });
     });
+    return el;
   }
 
   /**
@@ -5699,6 +5934,7 @@ class TinyHtml_TinyHtml {
    * If multiple targets exist, the inserted elements are cloned accordingly.
    *
    * @param {TinyNode | TinyNode[]} targets - The elements to be replaced.
+   * @returns {TinyNode|TinyNode[]}
    */
   replaceAll(targets) {
     return TinyHtml_TinyHtml.replaceAll(this, targets);
@@ -5722,7 +5958,12 @@ class TinyHtml_TinyHtml {
       throw new Error(
         `[TinyHtml] You are trying to put a TinyHtml inside another TinyHtml in constructor.`,
       );
-    if (!(el instanceof Element) && !(el instanceof Window) && !(el instanceof Document))
+    if (
+      !(el instanceof Element) &&
+      !(el instanceof Window) &&
+      !(el instanceof Document) &&
+      !(el instanceof Text)
+    )
       throw new Error(`[TinyHtml] Invalid Target in constructor.`);
     this.#el = el;
   }
@@ -6172,6 +6413,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyHtmlElement|TinyHtmlElement[]} el - The element to inspect.
    * @param {string|Object} prop - The property name or an object with key-value pairs
    * @param {string|null} [value=null] - The value to set (if `prop` is a string)
+   * @returns {TinyHtmlElement|TinyHtmlElement[]}
    */
   static setStyle(el, prop, value = null) {
     TinyHtml_TinyHtml._preHtmlElems(el, 'setStyle').forEach((elem) => {
@@ -6184,6 +6426,7 @@ class TinyHtml_TinyHtml {
         }
       } else elem.style.setProperty(TinyHtml_TinyHtml.toStyleKc(prop), value);
     });
+    return el;
   }
 
   /**
@@ -6194,6 +6437,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {string|Object} prop - The property name or an object with key-value pairs
    * @param {string|null} [value=null] - The value to set (if `prop` is a string)
+   * @returns {TinyHtmlElement|TinyHtmlElement[]}
    */
   setStyle(prop, value) {
     return TinyHtml_TinyHtml.setStyle(this, prop, value);
@@ -6289,6 +6533,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyHtmlElement|TinyHtmlElement[]} el - A single element or an array of elements.
    * @param {string|string[]} prop - A property name or an array of property names to remove.
+   * @returns {TinyHtmlElement|TinyHtmlElement[]}
    */
   static removeStyle(el, prop) {
     TinyHtml_TinyHtml._preHtmlElems(el, 'removeStyle').forEach((elem) => {
@@ -6298,12 +6543,14 @@ class TinyHtml_TinyHtml {
         }
       } else elem.style.removeProperty(TinyHtml_TinyHtml.toStyleKc(prop));
     });
+    return el;
   }
 
   /**
    * Removes one or more inline CSS properties from the given element(s).
    *
    * @param {string|string[]} prop - A property name or an array of property names to remove.
+   * @returns {TinyHtmlElement|TinyHtmlElement[]}
    */
   removeStyle(prop) {
     return TinyHtml_TinyHtml.removeStyle(this, prop);
@@ -6318,6 +6565,7 @@ class TinyHtml_TinyHtml {
    * @param {string} prop - The CSS property to toggle.
    * @param {string} val1 - The first value (used as "current" check).
    * @param {string} val2 - The second value (used as the "alternative").
+   * @returns {TinyHtmlElement|TinyHtmlElement[]}
    */
   static toggleStyle(el, prop, val1, val2) {
     TinyHtml_TinyHtml._preHtmlElems(el, 'toggleStyle').forEach((elem) => {
@@ -6325,6 +6573,7 @@ class TinyHtml_TinyHtml {
       const newVal = current === TinyHtml_TinyHtml.toStyleKc(val1) ? val2 : val1;
       TinyHtml_TinyHtml.setStyle(elem, prop, newVal);
     });
+    return el;
   }
 
   /**
@@ -6335,6 +6584,7 @@ class TinyHtml_TinyHtml {
    * @param {string} prop - The CSS property to toggle.
    * @param {string} val1 - The first value (used as "current" check).
    * @param {string} val2 - The second value (used as the "alternative").
+   * @returns {TinyHtmlElement|TinyHtmlElement[]}
    */
   toggleStyle(prop, val1, val2) {
     return TinyHtml_TinyHtml.toggleStyle(this, prop, val1, val2);
@@ -6344,14 +6594,16 @@ class TinyHtml_TinyHtml {
    * Removes all inline styles (`style` attribute) from the given element(s).
    *
    * @param {TinyElement|TinyElement[]} el - A single element or an array of elements.
+   * @returns {TinyElement|TinyElement[]}
    */
   static clearStyle(el) {
     TinyHtml_TinyHtml._preElems(el, 'clearStyle').forEach((elem) => elem.removeAttribute('style'));
+    return el;
   }
 
   /**
    * Removes all inline styles (`style` attribute) from the given element(s).
-   *
+   * @returns {TinyElement|TinyElement[]}
    */
   clearStyle() {
     return TinyHtml_TinyHtml.clearStyle(this);
@@ -6363,14 +6615,17 @@ class TinyHtml_TinyHtml {
    * Focus the element.
    *
    * @param {TinyHtmlElement} el - The element or a selector string.
+   * @returns {TinyHtmlElement}
    */
   static focus(el) {
     const elem = TinyHtml_TinyHtml._preHtmlElem(el, 'focus');
     elem.focus();
+    return el;
   }
 
   /**
    * Focus the element.
+   * @returns {TinyHtmlElement}
    */
   focus() {
     return TinyHtml_TinyHtml.focus(this);
@@ -6380,19 +6635,46 @@ class TinyHtml_TinyHtml {
    * Blur the element.
    *
    * @param {TinyHtmlElement} el - The element or a selector string.
+   * @returns {TinyHtmlElement}
    */
   static blur(el) {
     const elem = TinyHtml_TinyHtml._preHtmlElem(el, 'blur');
     elem.blur();
+    return el;
   }
 
   /**
    * Blur the element.
+   * @returns {TinyHtmlElement}
    */
   blur() {
     return TinyHtml_TinyHtml.blur(this);
   }
 
+  /**
+   * Interprets a value as a boolean `true` if it matches a common truthy representation.
+   *
+   * This method checks if the input is any of the common forms used to represent `true`,
+   * such as the string `'true'`, `'1'`, `'on'`, the boolean `true`, or the number `1`.
+   *
+   * @param {string|boolean|number} [value] - The value to interpret as boolean.
+   * @returns {boolean} `true` if the value represents a truthy state, otherwise `false`.
+   */
+  static boolCheck(value) {
+    if (
+      typeof value !== 'undefined' &&
+      (value === 'true' ||
+        value === '1' ||
+        value === true ||
+        value === 'on' ||
+        (typeof value === 'number' && value > 0))
+    ) {
+      return true;
+    } else {
+      return false;
+    }
+  }
+
   //////////////////////////////////////////////////////////////////////
 
   /**
@@ -6445,16 +6727,40 @@ class TinyHtml_TinyHtml {
     return window.innerWidth || document.documentElement.clientWidth;
   }
 
+  /**
+   * Checks if the page is currently scrolled to the very top.
+   *
+   * This method compares the current vertical scroll position with the total document height.
+   * It's useful for detecting if the user has reached the top of the page.
+   *
+   * @returns {boolean} `true` if the page is scrolled to the top, otherwise `false`.
+   */
+  static isPageTop() {
+    return window.scrollY === 0;
+  }
+
+  /**
+   * Checks if the page is currently scrolled to the very bottom.
+   *
+   * This method uses the `scrollY` and `innerHeight` properties to determine if the
+   * user has reached the end of the document.
+   *
+   * @returns {boolean} `true` if the page is scrolled to the bottom, otherwise `false`.
+   */
+  static isPageBottom() {
+    return window.innerHeight + window.scrollY >= document.body.offsetHeight;
+  }
+
   /**
    * Gets the width or height of an element based on the box model.
-   * @param {TinyElementAndWindow} el - The element or window.
+   * @param {TinyElementAndWinAndDoc} el - The element or window.
    * @param {"width"|"height"} type - Dimension type.
    * @param {"content"|"padding"|"border"|"margin"} [extra='content'] - Box model context.
    * @returns {number} - Computed dimension.
    * @throws {TypeError} If `type` or `extra` is not a string.
    */
   static getDimension(el, type, extra = 'content') {
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'getDimension');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'getDimension');
     if (typeof type !== 'string') throw new TypeError('The type must be a string.');
     if (typeof extra !== 'string') throw new TypeError('The extra must be a string.');
 
@@ -6542,17 +6848,20 @@ class TinyHtml_TinyHtml {
    * @param {TinyHtmlElement} el - Target element.
    * @param {string|number} value - Height value.
    * @throws {TypeError} If `value` is neither a string nor number.
+   * @returns {TinyHtmlElement}
    */
   static setHeight(el, value) {
     const elem = TinyHtml_TinyHtml._preHtmlElem(el, 'setHeight');
     if (typeof value !== 'number' && typeof value !== 'string')
       throw new TypeError('The value must be a string or number.');
     elem.style.height = typeof value === 'number' ? `${value}px` : value;
+    return el;
   }
 
   /**
    * Sets the height of the element.
    * @param {string|number} value - Height value.
+   * @returns {TinyHtmlElement}
    */
   setHeight(value) {
     return TinyHtml_TinyHtml.setHeight(this, value);
@@ -6563,17 +6872,20 @@ class TinyHtml_TinyHtml {
    * @param {TinyHtmlElement} el - Target element.
    * @param {string|number} value - Width value.
    * @throws {TypeError} If `value` is neither a string nor number.
+   * @returns {TinyHtmlElement}
    */
   static setWidth(el, value) {
     const elem = TinyHtml_TinyHtml._preHtmlElem(el, 'setWidth');
     if (typeof value !== 'number' && typeof value !== 'string')
       throw new TypeError('The value must be a string or number.');
     elem.style.width = typeof value === 'number' ? `${value}px` : value;
+    return el;
   }
 
   /**
    * Sets the width of the element.
    * @param {string|number} value - Width value.
+   * @returns {TinyHtmlElement}
    */
   setWidth(value) {
     return TinyHtml_TinyHtml.setWidth(this, value);
@@ -6581,11 +6893,11 @@ class TinyHtml_TinyHtml {
 
   /**
    * Returns content box height.
-   * @param {TinyElementAndWindow} el - Target element.
+   * @param {TinyElementAndWinAndDoc} el - Target element.
    * @returns {number}
    */
   static height(el) {
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'height');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'height');
     return TinyHtml_TinyHtml.getDimension(elem, 'height', 'content');
   }
 
@@ -6599,11 +6911,11 @@ class TinyHtml_TinyHtml {
 
   /**
    * Returns content box width.
-   * @param {TinyElementAndWindow} el - Target element.
+   * @param {TinyElementAndWinAndDoc} el - Target element.
    * @returns {number}
    */
   static width(el) {
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'width');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'width');
     return TinyHtml_TinyHtml.getDimension(elem, 'width', 'content');
   }
 
@@ -6617,11 +6929,11 @@ class TinyHtml_TinyHtml {
 
   /**
    * Returns padding box height.
-   * @param {TinyElementAndWindow} el - Target element.
+   * @param {TinyElementAndWinAndDoc} el - Target element.
    * @returns {number}
    */
   static innerHeight(el) {
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'innerHeight');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'innerHeight');
     return TinyHtml_TinyHtml.getDimension(elem, 'height', 'padding');
   }
 
@@ -6635,11 +6947,11 @@ class TinyHtml_TinyHtml {
 
   /**
    * Returns padding box width.
-   * @param {TinyElementAndWindow} el - Target element.
+   * @param {TinyElementAndWinAndDoc} el - Target element.
    * @returns {number}
    */
   static innerWidth(el) {
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'innerWidth');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'innerWidth');
     return TinyHtml_TinyHtml.getDimension(elem, 'width', 'padding');
   }
 
@@ -6653,14 +6965,14 @@ class TinyHtml_TinyHtml {
 
   /**
    * Returns outer height of the element, optionally including margin.
-   * @param {TinyElementAndWindow} el - Target element.
+   * @param {TinyElementAndWinAndDoc} el - Target element.
    * @param {boolean} [includeMargin=false] - Whether to include margin.
    * @returns {number}
    */
   static outerHeight(el, includeMargin = false) {
     if (typeof includeMargin !== 'boolean')
       throw new TypeError('The "includeMargin" must be a boolean.');
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'outerHeight');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'outerHeight');
     return TinyHtml_TinyHtml.getDimension(elem, 'height', includeMargin ? 'margin' : 'border');
   }
 
@@ -6675,14 +6987,14 @@ class TinyHtml_TinyHtml {
 
   /**
    * Returns outer width of the element, optionally including margin.
-   * @param {TinyElementAndWindow} el - Target element.
+   * @param {TinyElementAndWinAndDoc} el - Target element.
    * @param {boolean} [includeMargin=false] - Whether to include margin.
    * @returns {number}
    */
   static outerWidth(el, includeMargin = false) {
     if (typeof includeMargin !== 'boolean')
       throw new TypeError('The "includeMargin" must be a boolean.');
-    const elem = TinyHtml_TinyHtml._preElemAndWindow(el, 'outerWidth');
+    const elem = TinyHtml_TinyHtml._preElemAndWinAndDoc(el, 'outerWidth');
     return TinyHtml_TinyHtml.getDimension(elem, 'width', includeMargin ? 'margin' : 'border');
   }
 
@@ -6855,6 +7167,7 @@ class TinyHtml_TinyHtml {
    * Sets the vertical scroll position.
    * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
    * @param {number} value - Scroll top value.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
    */
   static setScrollTop(el, value) {
     if (typeof value !== 'number') throw new TypeError('ScrollTop value must be a number.');
@@ -6868,11 +7181,13 @@ class TinyHtml_TinyHtml {
         elem.scrollTop = value;
       }
     });
+    return el;
   }
 
   /**
    * Sets the vertical scroll position.
    * @param {number} value - Scroll top value.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
    */
   setScrollTop(value) {
     return TinyHtml_TinyHtml.setScrollTop(this, value);
@@ -6882,6 +7197,7 @@ class TinyHtml_TinyHtml {
    * Sets the horizontal scroll position.
    * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
    * @param {number} value - Scroll left value.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
    */
   static setScrollLeft(el, value) {
     if (typeof value !== 'number') throw new TypeError('ScrollLeft value must be a number.');
@@ -6895,11 +7211,13 @@ class TinyHtml_TinyHtml {
         elem.scrollLeft = value;
       }
     });
+    return el;
   }
 
   /**
    * Sets the horizontal scroll position.
    * @param {number} value - Scroll left value.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
    */
   setScrollLeft(value) {
     return TinyHtml_TinyHtml.setScrollLeft(this, value);
@@ -7030,15 +7348,16 @@ class TinyHtml_TinyHtml {
 
   /**
    * Adds one or more CSS class names to the element.
-   * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => void} - One or more class names to add.
+   * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to add.
    */
   static addClass(el, ...args) {
     TinyHtml_TinyHtml._preElems(el, 'addClass').forEach((elem) => elem.classList.add(...args));
+    return el;
   }
 
   /**
    * Adds one or more CSS class names to the element.
-   * @type {(...tokens: string[]) => void} - One or more class names to add.
+   * @type {(...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to add.
    */
   addClass(...args) {
     return TinyHtml_TinyHtml.addClass(this, ...args);
@@ -7046,15 +7365,16 @@ class TinyHtml_TinyHtml {
 
   /**
    * Removes one or more CSS class names from the element.
-   * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => void} - One or more class names to remove.
+   * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to remove.
    */
   static removeClass(el, ...args) {
     TinyHtml_TinyHtml._preElems(el, 'removeClass').forEach((elem) => elem.classList.remove(...args));
+    return el;
   }
 
   /**
    * Removes one or more CSS class names from the element.
-   * @type {(...tokens: string[]) => void} - One or more class names to remove.
+   * @type {(...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to remove.
    */
   removeClass(...args) {
     return TinyHtml_TinyHtml.removeClass(this, ...args);
@@ -7264,15 +7584,18 @@ class TinyHtml_TinyHtml {
    * Set text content of elements.
    * @param {TinyElement|TinyElement[]} el
    * @param {string} value
+   * @returns {TinyElement|TinyElement[]}
    */
   static setText(el, value) {
     if (typeof value !== 'string') throw new Error('Value is not a valid string.');
     TinyHtml_TinyHtml._preElems(el, 'setText').forEach((el) => (el.textContent = value));
+    return el;
   }
 
   /**
    * Set text content of the element.
    * @param {string} value
+   * @returns {TinyElement|TinyElement[]}
    */
   setText(value) {
     return TinyHtml_TinyHtml.setText(this, value);
@@ -7281,13 +7604,16 @@ class TinyHtml_TinyHtml {
   /**
    * Remove all child nodes from each element.
    * @param {TinyElement|TinyElement[]} el
+   * @returns {TinyElement|TinyElement[]}
    */
   static empty(el) {
     TinyHtml_TinyHtml._preElems(el, 'empty').forEach((el) => (el.textContent = ''));
+    return el;
   }
 
   /**
    * Remove all child nodes of the element.
+   * @returns {TinyElement|TinyElement[]}
    */
   empty() {
     return TinyHtml_TinyHtml.empty(this);
@@ -7295,35 +7621,40 @@ class TinyHtml_TinyHtml {
 
   /**
    * Get the innerHTML of the element.
-   * @param {TinyElement|TinyElement[]} el
+   * @param {TinyElement} el
+   * @param {GetHTMLOptions} [ops]
    * @returns {string}
    */
-  static html(el) {
+  static html(el, ops) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'html');
-    return elem.innerHTML;
+    return elem.getHTML(ops);
   }
 
   /**
    * Get the innerHTML of the element.
+   * @param {GetHTMLOptions} [ops]
    * @returns {string}
    */
-  html() {
-    return TinyHtml_TinyHtml.html(this);
+  html(ops) {
+    return TinyHtml_TinyHtml.html(this, ops);
   }
 
   /**
    * Set the innerHTML of each element.
    * @param {TinyElement|TinyElement[]} el
    * @param {string} value
+   * @returns {TinyElement|TinyElement[]}
    */
   static setHtml(el, value) {
     if (typeof value !== 'string') throw new Error('Value is not a valid string.');
     TinyHtml_TinyHtml._preElems(el, 'setHtml').forEach((el) => (el.innerHTML = value));
+    return el;
   }
 
   /**
    * Set the innerHTML of the element.
    * @param {string} value
+   * @returns {TinyElement|TinyElement[]}
    */
   setHtml(value) {
     return TinyHtml_TinyHtml.setHtml(this, value);
@@ -7457,6 +7788,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyInputElement|TinyInputElement[]} el - Target element.
    * @param {SetValueList|((el: InputElement, val: SetValueList) => SetValueList)} value - The value to assign or a function that returns it.
    * @throws {Error} If the computed value is not a valid string or boolean.
+   * @returns {TinyInputElement|TinyInputElement[]}
    */
   static setVal(el, value) {
     TinyHtml_TinyHtml._preInputElems(el, 'setVal').forEach((elem) => {
@@ -7496,6 +7828,7 @@ class TinyHtml_TinyHtml {
         if (typeof valToSet === 'string') elem.value = valToSet;
       }
     });
+    return el;
   }
 
   /**
@@ -7503,6 +7836,7 @@ class TinyHtml_TinyHtml {
    * Accepts strings, numbers, booleans or arrays of these values, or a callback function that computes them.
    *
    * @param {SetValueList|((el: InputElement, val: SetValueList) => SetValueList)} value - The value to assign or a function that returns it.
+   * @returns {TinyInputElement|TinyInputElement[]}
    * @throws {Error} If the computed value is not a valid string or boolean.
    */
   setVal(value) {
@@ -7772,6 +8106,7 @@ class TinyHtml_TinyHtml {
    * @param {string} event - The event type (e.g. 'click', 'keydown').
    * @param {EventRegistryHandle} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options] - Optional event listener options.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static on(el, event, handler, options) {
     if (typeof event !== 'string') throw new TypeError('The event name must be a string.');
@@ -7784,6 +8119,7 @@ class TinyHtml_TinyHtml {
       if (!Array.isArray(events[event])) events[event] = [];
       events[event].push({ handler, options });
     });
+    return el;
   }
 
   /**
@@ -7792,6 +8128,7 @@ class TinyHtml_TinyHtml {
    * @param {string} event - The event type (e.g. 'click', 'keydown').
    * @param {EventRegistryHandle} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options] - Optional event listener options.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   on(event, handler, options) {
     return TinyHtml_TinyHtml.on(this, event, handler, options);
@@ -7804,6 +8141,7 @@ class TinyHtml_TinyHtml {
    * @param {string} event - The event type (e.g. 'click', 'keydown').
    * @param {EventRegistryHandle} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options={}] - Optional event listener options.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static once(el, event, handler, options = {}) {
     if (typeof event !== 'string') throw new TypeError('The event name must be a string.');
@@ -7821,6 +8159,7 @@ class TinyHtml_TinyHtml {
         typeof options === 'boolean' ? options : { ...options, once: true },
       );
     });
+    return el;
   }
 
   /**
@@ -7829,6 +8168,7 @@ class TinyHtml_TinyHtml {
    * @param {string} event - The event type (e.g. 'click', 'keydown').
    * @param {EventRegistryHandle} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options={}] - Optional event listener options.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   once(event, handler, options = {}) {
     return TinyHtml_TinyHtml.once(this, event, handler, options);
@@ -7841,6 +8181,7 @@ class TinyHtml_TinyHtml {
    * @param {string} event - The event type.
    * @param {EventRegistryHandle} handler - The function originally bound to the event.
    * @param {boolean|EventListenerOptions} [options] - Optional listener options.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static off(el, event, handler, options) {
     if (typeof event !== 'string') throw new TypeError('The event name must be a string.');
@@ -7853,6 +8194,7 @@ class TinyHtml_TinyHtml {
         if (events[event].length === 0) delete events[event];
       }
     });
+    return el;
   }
 
   /**
@@ -7861,6 +8203,7 @@ class TinyHtml_TinyHtml {
    * @param {string} event - The event type.
    * @param {EventRegistryHandle} handler - The function originally bound to the event.
    * @param {boolean|EventListenerOptions} [options] - Optional listener options.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   off(event, handler, options) {
     return TinyHtml_TinyHtml.off(this, event, handler, options);
@@ -7871,6 +8214,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
    * @param {string} event - The event type to remove (e.g. 'click').
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static offAll(el, event) {
     if (typeof event !== 'string') throw new TypeError('The event name must be a string.');
@@ -7883,12 +8227,14 @@ class TinyHtml_TinyHtml {
         delete events[event];
       }
     });
+    return el;
   }
 
   /**
    * Removes all event listeners of a specific type from the element.
    *
    * @param {string} event - The event type to remove (e.g. 'click').
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   offAll(event) {
     return TinyHtml_TinyHtml.offAll(this, event);
@@ -7900,6 +8246,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
    * @param {((handler: EventListenerOrEventListenerObject, event: string) => boolean)|null} [filterFn=null] -
    *        Optional filter function to selectively remove specific handlers.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static offAllTypes(el, filterFn = null) {
     if (filterFn !== null && typeof filterFn !== 'function')
@@ -7918,6 +8265,7 @@ class TinyHtml_TinyHtml {
 
       __eventRegistry.delete(elem);
     });
+    return el;
   }
 
   /**
@@ -7925,6 +8273,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {((handler: EventListenerOrEventListenerObject, event: string) => boolean)|null} [filterFn=null] -
    *        Optional filter function to selectively remove specific handlers.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   offAllTypes(filterFn = null) {
     return TinyHtml_TinyHtml.offAllTypes(this, filterFn);
@@ -7936,6 +8285,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyEventTarget|TinyEventTarget[]} el - Target element where the event should be triggered.
    * @param {string} event - Name of the event to trigger.
    * @param {Event|CustomEvent|CustomEventInit} [payload] - Optional event object or data to pass.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static trigger(el, event, payload = {}) {
     if (typeof event !== 'string') throw new TypeError('The event name must be a string.');
@@ -7951,6 +8301,7 @@ class TinyHtml_TinyHtml {
 
       elem.dispatchEvent(evt);
     });
+    return el;
   }
 
   /**
@@ -7958,6 +8309,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {string} event - Name of the event to trigger.
    * @param {Event|CustomEvent|CustomEventInit} [payload] - Optional event object or data to pass.
+   * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   trigger(event, payload = {}) {
     return TinyHtml_TinyHtml.trigger(this, event, payload);
@@ -8000,6 +8352,7 @@ class TinyHtml_TinyHtml {
    * @param {TinyElement|TinyElement[]} el
    * @param {string} name
    * @param {string|null} [value=null]
+   * @returns {TinyElement|TinyElement[]}
    */
   static setAttr(el, name, value = null) {
     if (typeof name !== 'string') throw new TypeError('The "name" must be a string.');
@@ -8009,12 +8362,14 @@ class TinyHtml_TinyHtml {
       if (value === null) elem.removeAttribute(name);
       else elem.setAttribute(name, value);
     });
+    return el;
   }
 
   /**
    * Set an attribute on an element.
    * @param {string} name
    * @param {string|null} [value=null]
+   * @returns {TinyElement|TinyElement[]}
    */
   setAttr(name, value) {
     return TinyHtml_TinyHtml.setAttr(this, name, value);
@@ -8024,15 +8379,18 @@ class TinyHtml_TinyHtml {
    * Remove attribute(s) from an element.
    * @param {TinyElement|TinyElement[]} el
    * @param {string} name Space-separated list of attributes.
+   * @returns {TinyElement|TinyElement[]}
    */
   static removeAttr(el, name) {
     if (typeof name !== 'string') throw new TypeError('The "name" must be a string.');
     TinyHtml_TinyHtml._preElems(el, 'removeAttr').forEach((elem) => elem.removeAttribute(name));
+    return el;
   }
 
   /**
    * Remove attribute(s) from an element.
    * @param {string} name Space-separated list of attributes.
+   * @returns {TinyElement|TinyElement[]}
    */
   removeAttr(name) {
     return TinyHtml_TinyHtml.removeAttr(this, name);
@@ -8087,6 +8445,7 @@ class TinyHtml_TinyHtml {
    * Set a property on an element.
    * @param {TinyElement|TinyElement[]} el
    * @param {string} name
+   * @returns {TinyElement|TinyElement[]}
    */
   static addProp(el, name) {
     if (typeof name !== 'string') throw new TypeError('The "name" must be a string.');
@@ -8096,11 +8455,13 @@ class TinyHtml_TinyHtml {
       // @ts-ignore
       elem[name] = true;
     });
+    return el;
   }
 
   /**
    * Set a property on an element.
    * @param {string} name
+   * @returns {TinyElement|TinyElement[]}
    */
   addProp(name) {
     return TinyHtml_TinyHtml.addProp(this, name);
@@ -8110,6 +8471,7 @@ class TinyHtml_TinyHtml {
    * Remove a property from an element.
    * @param {TinyElement|TinyElement[]} el
    * @param {string} name
+   * @returns {TinyElement|TinyElement[]}
    */
   static removeProp(el, name) {
     if (typeof name !== 'string') throw new TypeError('The "name" must be a string.');
@@ -8119,11 +8481,13 @@ class TinyHtml_TinyHtml {
       // @ts-ignore
       elem[name] = false;
     });
+    return el;
   }
 
   /**
    * Remove a property from an element.
    * @param {string} name
+   * @returns {TinyElement|TinyElement[]}
    */
   removeProp(name) {
     return TinyHtml_TinyHtml.removeProp(this, name);
@@ -8164,13 +8528,16 @@ class TinyHtml_TinyHtml {
   /**
    * Removes an element from the DOM.
    * @param {TinyElement|TinyElement[]} el - The DOM element or selector to remove.
+   * @returns {TinyElement|TinyElement[]}
    */
   static remove(el) {
     TinyHtml_TinyHtml._preElems(el, 'remove').forEach((elem) => elem.remove());
+    return el;
   }
 
   /**
    * Removes the element from the DOM.
+   * @returns {TinyElement|TinyElement[]}
    */
   remove() {
     return TinyHtml_TinyHtml.remove(this);
@@ -8514,6 +8881,14 @@ class TinyHtml_TinyHtml {
    */
   static isInViewport(el) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'isInViewport');
+    if (
+      !elem.checkVisibility({
+        contentVisibilityAuto: false,
+        opacityProperty: false,
+        visibilityProperty: false,
+      })
+    )
+      return false;
     const elementTop = TinyHtml_TinyHtml.offset(elem).top;
     const elementBottom = elementTop + TinyHtml_TinyHtml.outerHeight(elem);
 
@@ -8540,6 +8915,14 @@ class TinyHtml_TinyHtml {
    */
   static isScrolledIntoView(el) {
     const elem = TinyHtml_TinyHtml._preElem(el, 'isScrolledIntoView');
+    if (
+      !elem.checkVisibility({
+        contentVisibilityAuto: false,
+        opacityProperty: false,
+        visibilityProperty: false,
+      })
+    )
+      return false;
     const docViewTop = TinyHtml_TinyHtml.scrollTop(window);
     const docViewBottom = docViewTop + TinyHtml_TinyHtml.height(window);
 
@@ -8557,6 +8940,111 @@ class TinyHtml_TinyHtml {
   isScrolledIntoView() {
     return TinyHtml_TinyHtml.isScrolledIntoView(this);
   }
+
+  /**
+   * Checks if the given element is at least partially visible within the boundaries of a container.
+   *
+   * @param {TinyElement} el - The DOM element to check.
+   * @param {TinyElement} cont - The container element acting as the viewport.
+   * @returns {boolean} True if the element is partially visible within the container, false otherwise.
+   */
+  static isInContainer(el, cont) {
+    const elem = TinyHtml_TinyHtml._preElem(el, 'isInContainer');
+    const container = TinyHtml_TinyHtml._preElem(cont, 'isInContainer');
+
+    if (
+      !elem.checkVisibility({
+        contentVisibilityAuto: false,
+        opacityProperty: false,
+        visibilityProperty: false,
+      })
+    )
+      return false;
+    const elemRect = elem.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+
+    const verticallyVisible =
+      elemRect.bottom > containerRect.top && elemRect.top < containerRect.bottom;
+
+    const horizontallyVisible =
+      elemRect.right > containerRect.left && elemRect.left < containerRect.right;
+
+    return verticallyVisible && horizontallyVisible;
+  }
+
+  /**
+   * Checks if the given element is at least partially visible within the boundaries of a container.
+   *
+   * @param {TinyElement} cont - The container element acting as the viewport.
+   * @returns {boolean} True if the element is partially visible within the container, false otherwise.
+   */
+  isInContainer(cont) {
+    return TinyHtml_TinyHtml.isInContainer(this, cont);
+  }
+
+  /**
+   * Checks if the given element is fully visible within the boundaries of a container (top and bottom).
+   *
+   * @param {TinyElement} el - The DOM element to check.
+   * @param {TinyElement} cont - The container element acting as the viewport.
+   * @returns {boolean} True if the element is fully visible within the container, false otherwise.
+   */
+  static isFullyInContainer(el, cont) {
+    const elem = TinyHtml_TinyHtml._preElem(el, 'isScrolledIntoView');
+    const container = TinyHtml_TinyHtml._preElem(cont, 'isInContainer');
+
+    if (
+      !elem.checkVisibility({
+        contentVisibilityAuto: false,
+        opacityProperty: false,
+        visibilityProperty: false,
+      })
+    )
+      return false;
+    const elemRect = elem.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+
+    const isFullyVisible =
+      elemRect.top >= containerRect.top &&
+      elemRect.bottom <= containerRect.bottom &&
+      elemRect.left >= containerRect.left &&
+      elemRect.right <= containerRect.right;
+
+    return isFullyVisible;
+  }
+
+  /**
+   * Checks if the given element is fully visible within the boundaries of a container (top and bottom).
+   *
+   * @param {TinyElement} cont - The container element acting as the viewport.
+   * @returns {boolean} True if the element is fully visible within the container, false otherwise.
+   */
+  isFullyInContainer(cont) {
+    return TinyHtml_TinyHtml.isFullyInContainer(this, cont);
+  }
+
+  /**
+   * Checks if an element has scrollable content.
+   *
+   * @param {TinyElement} el - The DOM element to check.
+   * @returns {{ v: boolean, h: boolean }} - True if scroll is needed in that direction.
+   */
+  static hasScroll(el) {
+    const elem = TinyHtml_TinyHtml._preElem(el, 'hasScroll');
+    return {
+      v: elem.scrollHeight > elem.clientHeight,
+      h: elem.scrollWidth > elem.clientWidth,
+    };
+  }
+
+  /**
+   * Checks if an element has scrollable content.
+   *
+   * @returns {{ v: boolean, h: boolean }} - True if scroll is needed in that direction.
+   */
+  hasScroll() {
+    return TinyHtml_TinyHtml.hasScroll(this);
+  }
 }
 
 /* harmony default export */ const libs_TinyHtml = (TinyHtml_TinyHtml);
@@ -10327,7 +10815,985 @@ class TinyDragger {
 
 /* harmony default export */ const libs_TinyDragger = ((/* unused pure expression or super */ null && (TinyDragger)));
 
-;// ./src/v1/index.mjs
+;// ./src/v1/libs/TinySmartScroller.mjs
+
+
+
+/**
+ * Represents the dimensions of a DOM element.
+ *
+ * @typedef {Object} NodeSizes
+ * @property {number} height - The height of the element in pixels.
+ * @property {number} width - The width of the element in pixels.
+ */
+
+/**
+ * A callback function that receives node size change data and optionally returns a modified NodeSizes object.
+ *
+ * @callback NodeSizesEvent
+ * @param {Element} elem - The DOM element whose size is being tracked.
+ * @param {{ old: NodeSizes, now: NodeSizes }} sizes - The old and new size measurements of the element.
+ * @param {{ old: number, now: number }} elemAmount - The number of matching elements before and after the update.
+ * @returns {NodeSizes|undefined} A modified NodeSizes object to override the default measurement, or undefined to use the original.
+ */
+
+/**
+ * A generic scroll-related event listener callback function.
+ *
+ * @callback ScrollListenersFunc
+ * @param {any} payload - The data payload passed when the scroll event is triggered. The type may vary depending on the event.
+ * @returns {void}
+ */
+
+/**
+ * TinySmartScroller is a utility class designed to enhance and manage scroll behaviors within containers or the window.
+ *
+ * It enables advanced scroll monitoring, auto-scrolling to bottom, preserving scroll position during DOM changes,
+ * and detecting visibility changes of elements. This is particularly useful for dynamic UIs like chat applications,
+ * feed viewers, or live content containers.
+ *
+ * Features:
+ * - Detects when the scroll reaches the top, bottom, or custom boundaries
+ * - Supports automatic scrolling to the bottom unless the user scrolls away
+ * - Observes DOM mutations and resizes, and adapts scroll position accordingly
+ * - Emits scroll-related events such as 'onScrollBoundary', 'onAutoScroll', and 'onScrollPause'
+ * - Includes customizable scroll correction filters for layout shift mitigation
+ * - Handles media element load events (e.g. `<img>`, `<iframe>`, `<video>`) to prevent sudden scroll jumps
+ *
+ * This class is **not framework-dependent** and works with vanilla DOM elements and the window object.
+ */
+class TinySmartScroller {
+  static Utils = { ...collision_namespaceObject, TinyHtml: libs_TinyHtml };
+
+  /** @type {WeakMap<Element, NodeSizes>} */
+  #oldSizes = new WeakMap();
+  /** @type {WeakMap<Element, NodeSizes>} */
+  #newSizes = new WeakMap();
+
+  /** @type {WeakMap<Element, boolean>} */
+  #newVisibles = new WeakMap();
+  /** @type {WeakMap<Element, boolean>} */
+  #oldVisibles = new WeakMap();
+
+  /** @type {WeakMap<Element, boolean>} */
+  #newVisiblesByTime = new WeakMap();
+  /** @type {WeakMap<Element, boolean>} */
+  #oldVisiblesByTime = new WeakMap();
+
+  /** @type {Record<string, ScrollListenersFunc[]>} */
+  #scrollListeners = {};
+
+  /** @type {ResizeObserver|null} */
+  #resizeObserver = null;
+  /** @type {MutationObserver|null} */
+  #mutationObserver = null;
+
+  /** @type {Set<string>} */
+  #loadTags = new Set(['IMG', 'IFRAME', 'VIDEO']);
+
+  /** @type {null|EventListenerOrEventListenerObject} */
+  #handler = null;
+
+  #isAtBottom = false;
+  #isAtTop = false;
+  #isAtCustomTop = false;
+  #isAtCustomBottom = false;
+
+  #querySelector = '';
+  #useWindow = false;
+  #destroyed = false;
+  #scrollPaused = false;
+  #autoScrollBottom = false;
+  #observeMutations = false;
+  #preserveScrollOnLayoutShift = false;
+  #debounceTime = 0;
+  #elemAmount = 0;
+  #elemOldAmount = 0;
+  #lastKnownScrollBottomOffset = 0;
+  #extraScrollBoundary = 0;
+
+  /** @type {Set<string>} */
+  #attributeFilter;
+
+  /** @type {Element} */
+  #target;
+
+  /** @type {Set<NodeSizesEvent>} */
+  #sizeFilter = new Set();
+
+  /**
+   * Creates a new instance of TinySmartScroller, attaching scroll and resize observers to manage
+   * automatic scroll behaviors, layout shift correction, and visibility tracking.
+   *
+   * @param {Element|Window} target - The scroll container to monitor. Can be an element or `window`.
+   * @param {Object} [options={}] - Optional settings to configure scroll behavior.
+   * @param {number} [options.extraScrollBoundary=0] - Extra margin in pixels to extend scroll boundary detection.
+   * @param {boolean} [options.autoScrollBottom=true] - Whether to auto-scroll to bottom on layout updates.
+   * @param {boolean} [options.observeMutations=true] - Enables MutationObserver to detect DOM changes.
+   * @param {boolean} [options.preserveScrollOnLayoutShift=true] - Prevents scroll jumps when layout changes.
+   * @param {number} [options.debounceTime=100] - Debounce time in milliseconds for scroll events.
+   * @param {string|null} [options.querySelector=null] - Optional CSS selector to filter observed child nodes.
+   * @param {string[]|Set<string>|null} [options.attributeFilter=['class', 'style', 'src', 'data-*', 'height', 'width']]
+   *     - Which attributes to observe for changes.
+   */
+  constructor(
+    target,
+    {
+      extraScrollBoundary = 0,
+      autoScrollBottom = true,
+      observeMutations = true,
+      preserveScrollOnLayoutShift = true,
+      debounceTime = 100,
+      querySelector = null,
+      attributeFilter = ['class', 'style', 'src', 'data-*', 'height', 'width'],
+    } = {},
+  ) {
+    // === target ===
+    if (!(target instanceof Element || target === window))
+      throw new TypeError(
+        `TinySmartScroller: 'target' must be a DOM Element or 'window', but got ${typeof target}`,
+      );
+    // === extraScrollBoundary ===
+    if (typeof extraScrollBoundary !== 'number' || Number.isNaN(extraScrollBoundary))
+      throw new TypeError(
+        `TinySmartScroller: 'extraScrollBoundary' must be a valid number, received ${extraScrollBoundary}`,
+      );
+    // === autoScrollBottom ===
+    if (typeof autoScrollBottom !== 'boolean')
+      throw new TypeError(
+        `TinySmartScroller: 'autoScrollBottom' must be a boolean, received ${typeof autoScrollBottom}`,
+      );
+    // === observeMutations ===
+    if (typeof observeMutations !== 'boolean')
+      throw new TypeError(
+        `TinySmartScroller: 'observeMutations' must be a boolean, received ${typeof observeMutations}`,
+      );
+    // === preserveScrollOnLayoutShift ===
+    if (typeof preserveScrollOnLayoutShift !== 'boolean')
+      throw new TypeError(
+        `TinySmartScroller: 'preserveScrollOnLayoutShift' must be a boolean, received ${typeof preserveScrollOnLayoutShift}`,
+      );
+    // === debounceTime ===
+    if (typeof debounceTime !== 'number' || debounceTime < 0 || Number.isNaN(debounceTime))
+      throw new TypeError(
+        `TinySmartScroller: 'debounceTime' must be a non-negative number, received ${debounceTime}`,
+      );
+    // === querySelector ===
+    if (querySelector !== null && typeof querySelector !== 'string')
+      throw new TypeError(
+        `TinySmartScroller: 'querySelector' must be a string or null, received ${typeof querySelector}`,
+      );
+    // === attributeFilter ===
+    const isValidAttrList =
+      attributeFilter === null || Array.isArray(attributeFilter) || attributeFilter instanceof Set;
+    if (!isValidAttrList)
+      throw new TypeError(
+        `TinySmartScroller: 'attributeFilter' must be an array, Set, or null. Got ${typeof attributeFilter}`,
+      );
+
+    // Start values
+    this.#target = target instanceof Window ? document.documentElement : target;
+    this.#useWindow = target instanceof Window;
+    this.#autoScrollBottom = autoScrollBottom;
+    this.#observeMutations = observeMutations;
+    this.#preserveScrollOnLayoutShift = preserveScrollOnLayoutShift;
+    this.#debounceTime = debounceTime;
+    this.#extraScrollBoundary = extraScrollBoundary;
+    this.#querySelector = querySelector || '';
+    this.#attributeFilter = new Set(attributeFilter || undefined);
+
+    // Bind scroll
+    /** @type {NodeJS.Timeout} */
+    let timeout;
+    this.#handler = () => {
+      this._scrollDataUpdater();
+      clearTimeout(timeout);
+      timeout = setTimeout(() => this._onScroll(), this.#debounceTime);
+    };
+    (this.#useWindow ? window : this.#target).addEventListener('scroll', this.#handler, {
+      passive: true,
+    });
+
+    // Mutations
+    if (this.#observeMutations) {
+      this._observeMutations();
+      this._observeResizes(this.#target.children);
+    }
+
+    this._scrollDataUpdater();
+  }
+
+  /**
+   * Returns a size difference callback that only reacts when height changes, filtered by tag name.
+   *
+   * @param {string[]} filter - List of tag names to allow. If empty, all tags are accepted.
+   * @returns {NodeSizesEvent} A function that compares previous and current height, returning height delta.
+   */
+  getSimpleOnHeight(filter = []) {
+    if (!Array.isArray(filter))
+      throw new TypeError('getSimpleOnHeight(filter): filter must be an array of tag names');
+    return (elem, sizes, amounts) => {
+      if ((filter.length > 0 && !filter.includes(elem.tagName)) || amounts.now !== amounts.old)
+        return;
+      const oldSize = sizes.old;
+      const newSize = sizes.now;
+      const height = newSize.height - oldSize.height;
+      return { height, width: 0 };
+    };
+  }
+
+  /**
+   * Adds a height difference callback to the size filter system.
+   *
+   * @param {string[]} filter - List of tag names to allow.
+   * @returns {NodeSizesEvent} The added size difference callback.
+   */
+  addSimpleOnHeight(filter) {
+    if (!Array.isArray(filter))
+      throw new TypeError('addSimpleOnHeight(filter): filter must be an array of tag names');
+    const result = this.getSimpleOnHeight(filter);
+    this.onSize(result);
+    return result;
+  }
+
+  /**
+   * Returns a list of all currently tracked load tags.
+   *
+   * @returns {string[]} Array of tag names.
+   */
+  getLoadTags() {
+    return Array.from(this.#loadTags);
+  }
+
+  /**
+   * Adds a new tag to the set of load tags.
+   *
+   * @param {string} tag - The tag name to add (e.g., 'IMG').
+   */
+  addLoadTag(tag) {
+    if (typeof tag !== 'string') throw new TypeError('addLoadTag(tag): tag must be a string');
+    this.#loadTags.add(tag.toUpperCase());
+  }
+
+  /**
+   * Removes a tag from the set of load tags.
+   *
+   * @param {string} tag - The tag name to remove.
+   */
+  removeLoadTag(tag) {
+    if (typeof tag !== 'string') throw new TypeError('removeLoadTag(tag): tag must be a string');
+    this.#loadTags.delete(tag.toUpperCase());
+  }
+
+  /**
+   * Checks whether a tag is tracked as a load tag.
+   *
+   * @param {string} tag - The tag name to check.
+   * @returns {boolean} True if the tag is being tracked.
+   */
+  hasLoadTag(tag) {
+    if (typeof tag !== 'string') throw new TypeError('hasLoadTag(tag): tag must be a string');
+    return this.#loadTags.has(tag.toUpperCase());
+  }
+
+  /**
+   * Clears the set of load tags. If `addDefault` is true, it will reset to the default tags: 'IMG', 'IFRAME', and 'VIDEO'.
+   *
+   * @param {boolean} [addDefault=false] - Whether to restore the default tags after clearing.
+   * @throws {TypeError} If `addDefault` is not a boolean.
+   */
+  resetLoadTags(addDefault = false) {
+    if (typeof addDefault !== 'boolean')
+      throw new TypeError('resetLoadTags(addDefault): addDefault must be a boolean');
+    this.#loadTags.clear();
+    if (!addDefault) return;
+    this.#loadTags.add('IMG');
+    this.#loadTags.add('IFRAME');
+    this.#loadTags.add('VIDEO');
+  }
+
+  /**
+   * Returns a list of all currently tracked attribute filters.
+   *
+   * @returns {string[]} Array of attribute names.
+   */
+  getAttributeFilters() {
+    return Array.from(this.#attributeFilter);
+  }
+
+  /**
+   * Adds an attribute to the filter list.
+   *
+   * @param {string} attr - The attribute name to add.
+   */
+  addAttributeFilter(attr) {
+    if (typeof attr !== 'string')
+      throw new TypeError('addAttributeFilter(attr): attr must be a string');
+    this.#attributeFilter.add(attr);
+  }
+
+  /**
+   * Removes an attribute from the filter list.
+   *
+   * @param {string} attr - The attribute name to remove.
+   */
+  removeAttributeFilter(attr) {
+    if (typeof attr !== 'string')
+      throw new TypeError('removeAttributeFilter(attr): attr must be a string');
+    this.#attributeFilter.delete(attr);
+  }
+
+  /**
+   * Checks whether a specific attribute is being filtered.
+   *
+   * @param {string} attr - The attribute name to check.
+   * @returns {boolean} True if the attribute is being filtered.
+   */
+  hasAttributeFilter(attr) {
+    if (typeof attr !== 'string')
+      throw new TypeError('hasAttributeFilter(attr): attr must be a string');
+    return this.#attributeFilter.has(attr);
+  }
+
+  /**
+   * Clears the set of observed attribute filters. If `addDefault` is true, it will reset to the default attributes:
+   * 'class', 'style', 'src', 'data-*', 'height', and 'width'.
+   *
+   * @param {boolean} [addDefault=false] - Whether to restore the default attribute filters after clearing.
+   * @throws {TypeError} If `addDefault` is not a boolean.
+   */
+  resetAttributeFilters(addDefault = false) {
+    if (typeof addDefault !== 'boolean')
+      throw new TypeError('resetAttributeFilters(addDefault): addDefault must be a boolean');
+    this.#attributeFilter.clear();
+    if (!addDefault) return;
+    ['class', 'style', 'src', 'data-*', 'height', 'width'].forEach((attr) =>
+      this.#attributeFilter.add(attr),
+    );
+  }
+
+  /**
+   * Registers a custom node size change handler to the internal size filter set.
+   *
+   * @param {NodeSizesEvent} handler - Function that compares old and new sizes.
+   */
+  onSize(handler) {
+    if (this.#destroyed) return;
+    if (typeof handler !== 'function')
+      throw new TypeError('onSize(handler): handler must be a function');
+    this.#sizeFilter.add(handler);
+  }
+
+  /**
+   * Unregisters a previously registered size handler from the internal filter set.
+   *
+   * @param {NodeSizesEvent} handler - The handler function to remove.
+   */
+  offSize(handler) {
+    if (this.#destroyed) return;
+    if (typeof handler !== 'function')
+      throw new TypeError('offSize(handler): handler must be a function');
+    this.#sizeFilter.delete(handler);
+  }
+
+  /**
+   * Adds a scroll-related event listener.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {ScrollListenersFunc} handler - Callback function to be called when event fires.
+   */
+  on(event, handler) {
+    if (this.#destroyed) return;
+    if (typeof event !== 'string')
+      throw new TypeError('on(event, handler): event name must be a string');
+    if (typeof handler !== 'function')
+      throw new TypeError('on(event, handler): handler must be a function');
+
+    if (!this.#scrollListeners[event]) this.#scrollListeners[event] = [];
+    this.#scrollListeners[event].push(handler);
+  }
+
+  /**
+   * Removes a previously registered scroll-related event listener.
+   *
+   * @param {string} event - The name of the event to remove the handler from.
+   * @param {ScrollListenersFunc} handler - The specific callback function to remove.
+   */
+  off(event, handler) {
+    if (this.#destroyed) return;
+    if (typeof event !== 'string')
+      throw new TypeError('off(event, handler): event name must be a string');
+    if (typeof handler !== 'function')
+      throw new TypeError('off(event, handler): handler must be a function');
+
+    const listeners = this.#scrollListeners[event];
+    if (!Array.isArray(listeners)) return;
+
+    const index = listeners.indexOf(handler);
+    if (index !== -1) listeners.splice(index, 1);
+
+    // Optionally clean up empty arrays (optional)
+    if (listeners.length === 0) delete this.#scrollListeners[event];
+  }
+
+  /**
+   * Checks which elements inside the target are currently visible and updates internal maps.
+   *
+   * @returns {Map<Element, { oldIsVisible: boolean; isVisible: boolean }>} Visibility comparison results.
+   */
+  _scrollDataUpdater() {
+    const results = new Map();
+    this.#target.querySelectorAll(this.#querySelector || '*').forEach((target) => {
+      const oldIsVisible = this.#newVisibles.get(target) ?? false;
+      this.#oldVisibles.set(target, oldIsVisible);
+
+      const isVisible = libs_TinyHtml.isInContainer(this.#target, target);
+      this.#newVisibles.set(target, isVisible);
+
+      results.set(target, { oldIsVisible, isVisible });
+    });
+    return results;
+  }
+
+  /**
+   * Emits a scroll-related event to all registered listeners.
+   *
+   * @param {string} event - Event name.
+   * @param {*} [payload] - Optional event data payload.
+   */
+  _emit(event, payload) {
+    if (this.#destroyed) return;
+    if (typeof event !== 'string')
+      throw new TypeError('_emit(event, payload): event name must be a string');
+    (this.#scrollListeners[event] || []).forEach((fn) => fn(payload));
+  }
+
+  /**
+   * Handles scroll events, calculates position-related statuses, and emits appropriate events.
+   */
+  _onScroll() {
+    if (this.#destroyed) return;
+    // Get values
+    const scrollCache = this._scrollDataUpdater();
+    const el = this.#target;
+    const scrollTop = el.scrollTop;
+    const scrollHeight = el.scrollHeight;
+    const clientHeight = el.clientHeight;
+
+    // Prepare sroll values
+    const scrollResult = { scrollTop, scrollHeight, clientHeight };
+    let atResult = null;
+    let atCustomResult = null;
+
+    const atTop = scrollTop === 0;
+    const atBottom = scrollTop + clientHeight >= scrollHeight - 1;
+
+    const atCustomTop = scrollTop <= 0 + this.#extraScrollBoundary;
+    const atCustomBottom = scrollTop + clientHeight >= scrollHeight - 1 - this.#extraScrollBoundary;
+
+    // Scroll results
+    if (atTop && atBottom) atResult = 'all';
+    else if (atTop) atResult = 'top';
+    else if (atBottom) atResult = 'bottom';
+
+    if (atCustomTop && atCustomBottom) atCustomResult = 'all';
+    else if (atCustomTop) atCustomResult = 'top';
+    else if (atCustomBottom) atCustomResult = 'bottom';
+
+    this.#isAtTop = atTop;
+    this.#isAtBottom = atBottom;
+
+    this.#isAtCustomTop = atCustomTop;
+    this.#isAtCustomBottom = atCustomBottom;
+
+    this.#scrollPaused = !(this.#autoScrollBottom && this.#isAtBottom);
+
+    this.#lastKnownScrollBottomOffset = scrollHeight - scrollTop - clientHeight;
+
+    // Send results
+    this._emit('onScrollBoundary', { status: atResult, ...scrollResult, scrollCache });
+    this._emit('onExtraScrollBoundary', { status: atCustomResult, ...scrollResult, scrollCache });
+
+    if (!this.#scrollPaused) {
+      this._emit('onAutoScroll', { ...scrollResult, scrollCache });
+    } else {
+      this._emit('onScrollPause', { ...scrollResult, scrollCache });
+    }
+  }
+
+  /**
+   * Attempts to correct the scroll position when layout shifts happen, preserving the user position if needed.
+   *
+   * @param {Element[]} [targets=[]] - List of elements involved in the size change.
+   */
+  _fixScroll(targets = []) {
+    if (this.#destroyed) return;
+    // === Validation ===
+    if (!Array.isArray(targets))
+      throw new TypeError('_fixScroll: targets must be an array of Elements');
+
+    // Get Scroll data
+    const prevScrollHeight = this.#target.scrollHeight;
+    const prevScrollTop = this.#target.scrollTop;
+    const prevBottomOffset =
+      this.#target.scrollHeight - this.#target.scrollTop - this.#target.clientHeight;
+
+    // Get new size
+    const newScrollHeight = this.#target.scrollHeight;
+    const heightDelta = newScrollHeight - prevScrollHeight;
+
+    /** @type {() => NodeSizes} */
+    const calculateScrollSize = () => {
+      // Run size getter
+      const scrollSize = { height: 0, width: 0 };
+      for (const target of targets) {
+        const tgOs = this.#oldSizes.get(target) || { height: 0, width: 0 };
+        const tgNs = this.#newSizes.get(target) || { height: 0, width: 0 };
+        this.#sizeFilter.forEach((fn) => {
+          /** @type {NodeSizes| undefined} */
+          const sizes = fn(
+            target,
+            { old: tgOs, now: tgNs },
+            { old: this.#elemOldAmount, now: this.#elemAmount },
+          );
+
+          // Fix size
+          if (this.#newVisibles.get(target) || this.#newVisiblesByTime.get(target)) {
+            if (typeof sizes !== 'undefined' && typeof sizes !== 'object')
+              throw new Error('_fixScroll: size filter must return an object or undefined');
+            if (typeof sizes === 'undefined') return;
+            scrollSize.height = sizes.height;
+            scrollSize.width = sizes.width;
+          }
+        });
+      }
+
+      // Checker
+      if (typeof scrollSize.height !== 'number' && scrollSize.height < 0)
+        throw new Error('_fixScroll: invalid scrollSize.height value');
+      if (typeof scrollSize.width !== 'number' && scrollSize.width < 0)
+        throw new Error('_fixScroll: invalid scrollSize.width value');
+
+      if (scrollSize.height !== 0 || scrollSize.width !== 0) {
+        for (const target of targets) {
+          this.#newVisiblesByTime.set(target, this.#newVisibles.get(target) ?? false);
+          this.#oldVisiblesByTime.set(target, this.#oldVisibles.get(target) ?? false);
+        }
+      }
+
+      return scrollSize;
+    };
+
+    // Fix scroll size
+    if (
+      this.#elemOldAmount > 0 &&
+      libs_TinyHtml.hasScroll(this.#target).v &&
+      this.#autoScrollBottom &&
+      this.#preserveScrollOnLayoutShift &&
+      !this.#isAtBottom &&
+      !this.#isAtTop
+    ) {
+      const scrollSize = calculateScrollSize();
+      // Complete
+      this.#target.scrollTop = prevScrollTop + heightDelta + scrollSize.height;
+      if (scrollSize.width > 0)
+        this.#target.scrollLeft = this.#target.scrollLeft + scrollSize.width;
+    }
+
+    // Normal stuff
+    else if (!this.#scrollPaused && this.#autoScrollBottom) {
+      calculateScrollSize();
+      this.scrollToBottom();
+    } else if (!this.#autoScrollBottom && !this.#isAtBottom) {
+      calculateScrollSize();
+      this.#target.scrollTop =
+        this.#target.scrollHeight - this.#target.clientHeight - prevBottomOffset;
+    }
+  }
+  /**
+   * Sets up a MutationObserver to watch for DOM changes and react accordingly to maintain scroll consistency.
+   */
+  _observeMutations() {
+    this.#mutationObserver = new MutationObserver((mutations) => {
+      if (this.#destroyed) return;
+      this._scrollDataUpdater();
+      this.#elemOldAmount = this.#elemAmount;
+      this.#elemAmount = this.#target.childElementCount;
+
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (!(node instanceof Element) || node.nodeType !== 1) return;
+
+          this._observeResizes([node]);
+          this._listenLoadEvents(node);
+
+          if (this.#querySelector) {
+            const children = node.querySelectorAll(this.#querySelector);
+            this._observeResizes(children);
+            this._listenLoadEvents(children);
+          }
+        });
+      });
+
+      this._fixScroll();
+    });
+
+    // Install observer
+    this.#mutationObserver.observe(this.#target, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter:
+        this.#attributeFilter.size > 0 ? Array.from(this.#attributeFilter) : undefined,
+    });
+  }
+
+  /**
+   * Adds a ResizeObserver to monitor elements' size changes and trigger layout adjustments.
+   *
+   * @param {NodeListOf<Element>|Element[]|HTMLCollection} elements - Elements to observe.
+   */
+  _observeResizes(elements) {
+    // Add resize observer
+    if (!this.#resizeObserver) {
+      this.#resizeObserver = new ResizeObserver((entries) => {
+        if (this.#destroyed) return;
+        this._scrollDataUpdater();
+        /** @type {Element[]} */
+        const targets = [];
+        for (const entry of entries) {
+          // Target
+          const target = entry.target;
+
+          // Update old size
+          const oldSize = this.#newSizes.get(target);
+          if (oldSize) this.#oldSizes.set(target, oldSize);
+
+          // Set new size
+          const { width, height } = entry.contentRect;
+          this.#newSizes.set(target, { width, height });
+          targets.push(target);
+        }
+
+        // Animation frame
+        this._fixScroll(targets);
+      });
+    }
+
+    // Execute observer
+    Array.from(elements).forEach((el) => {
+      if (!this.#resizeObserver)
+        throw new Error('_observeResizes: ResizeObserver instance is not initialized');
+      this.#resizeObserver.observe(el);
+    });
+  }
+
+  /**
+   * Listens for media/content load events (e.g., images, iframes, videos) to trigger scroll updates.
+   *
+   * @param {NodeListOf<Element>|Element} elements - Target element(s) to listen on.
+   */
+  _listenLoadEvents(elements) {
+    if (this.#destroyed) return;
+    const list = elements instanceof NodeList ? Array.from(elements) : [elements];
+
+    list.forEach((el) => {
+      if (this.#loadTags.has(el.tagName)) {
+        // @ts-ignore
+        if (!el.complete) {
+          el.addEventListener('load', () => {
+            this._scrollDataUpdater();
+            if (!this.#scrollPaused && this.#autoScrollBottom) {
+              this.scrollToBottom();
+            }
+          });
+        }
+      }
+    });
+  }
+
+  /**
+   * Returns the internal scroll container element being monitored.
+   *
+   * @returns {Element} The DOM element used as the scroll container target.
+   */
+  get target() {
+    return this.#target;
+  }
+
+  /**
+   * Returns the previous size of a given element, or undefined if not tracked.
+   *
+   * @param {Element} el - The DOM element to query.
+   * @returns {NodeSizes|null} The old size, or undefined.
+   */
+  getOldSize(el) {
+    return this.#oldSizes.get(el) ?? null;
+  }
+
+  /**
+   * Returns the current size of a given element, or undefined if not tracked.
+   *
+   * @param {Element} el - The DOM element to query.
+   * @returns {NodeSizes|null} The new size, or undefined.
+   */
+  getNewSize(el) {
+    return this.#newSizes.get(el) ?? null;
+  }
+
+  /**
+   * Returns whether the given element was visible in the last scroll update.
+   *
+   * @param {Element} el - The DOM element to check.
+   * @returns {boolean} True if visible, false if not, or undefined if not tracked.
+   */
+  wasVisible(el) {
+    return this.#oldVisibles.get(el) ?? false;
+  }
+
+  /**
+   * Returns whether the given element is currently visible.
+   *
+   * @param {Element} el - The DOM element to check.
+   * @returns {boolean} True if visible, false if not, or undefined if not tracked.
+   */
+  isVisible(el) {
+    return this.#newVisibles.get(el) ?? false;
+  }
+
+  /**
+   * Returns whether the element was visible in the last time-based visibility check.
+   *
+   * @param {Element} el - The DOM element to check.
+   * @returns {boolean} Visibility state from the previous timed check.
+   */
+  wasTimedVisible(el) {
+    return this.#oldVisiblesByTime.get(el) ?? false;
+  }
+
+  /**
+   * Returns whether the element is currently visible in the time-based check.
+   *
+   * @param {Element} el - The DOM element to check.
+   * @returns {boolean} Visibility state from the current timed check.
+   */
+  isTimedVisible(el) {
+    return this.#newVisiblesByTime.get(el) ?? false;
+  }
+
+  /**
+   * Sets the extra scroll boundary margin used when determining if the user is at a "custom" bottom or top.
+   *
+   * @param {number} value - Pixels of additional margin to use.
+   */
+  setExtraScrollBoundary(value) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+      throw new TypeError('setExtraScrollBoundary(value): value must be a valid number');
+    this.#extraScrollBoundary = value;
+  }
+
+  /**
+   * Returns the current extra scroll boundary setting.
+   *
+   * @returns {number}
+   */
+  getExtraScrollBoundary() {
+    return this.#extraScrollBoundary;
+  }
+
+  /**
+   * Returns the last known distance (in pixels) from the bottom of the scroll container.
+   *
+   * @returns {number}
+   */
+  getLastKnownScrollBottomOffset() {
+    return this.#lastKnownScrollBottomOffset;
+  }
+
+  /**
+   * Forces the scroll position to move to the very bottom of the target.
+   */
+  scrollToBottom() {
+    this.#target.scrollTop = this.#target.scrollHeight;
+  }
+
+  /**
+   * Forces the scroll position to move to the very top of the target.
+   */
+  scrollToTop() {
+    this.#target.scrollTop = 0;
+  }
+
+  /**
+   * Checks if the user is within the defined extra scroll boundary from the bottom.
+   *
+   * @returns {boolean}
+   */
+  isUserAtCustomBottom() {
+    return this.#isAtCustomBottom;
+  }
+
+  /**
+   * Checks if the user is within the defined extra scroll boundary from the top.
+   *
+   * @returns {boolean}
+   */
+  isUserAtCustomTop() {
+    return this.#isAtCustomTop;
+  }
+
+  /**
+   * Returns true if the user is currently scrolled to the bottom of the element.
+   *
+   * @returns {boolean}
+   */
+  isUserAtBottom() {
+    return this.#isAtBottom;
+  }
+
+  /**
+   * Returns true if the user is currently scrolled to the top of the element.
+   *
+   * @returns {boolean}
+   */
+  isUserAtTop() {
+    return this.#isAtTop;
+  }
+
+  /**
+   * Returns true if automatic scrolling is currently paused.
+   *
+   * @returns {boolean}
+   */
+  isScrollPaused() {
+    return this.#scrollPaused;
+  }
+
+  /**
+   * Returns whether the target is the window object.
+   *
+   * @returns {boolean} True if the scroll target is window, false otherwise.
+   */
+  isWindow() {
+    return this.#useWindow;
+  }
+
+  /**
+   * Returns whether the instance has been destroyed.
+   *
+   * @returns {boolean} True if the instance is destroyed, false otherwise.
+   */
+  isDestroyed() {
+    return this.#destroyed;
+  }
+
+  /**
+   * Returns whether auto-scroll-to-bottom is enabled.
+   *
+   * @returns {boolean} True if auto-scroll is active, false otherwise.
+   */
+  getAutoScrollBottom() {
+    return this.#autoScrollBottom;
+  }
+
+  /**
+   * Returns whether MutationObserver is enabled.
+   *
+   * @returns {boolean} True if mutation observation is active, false otherwise.
+   */
+  getObserveMutations() {
+    return this.#observeMutations;
+  }
+
+  /**
+   * Returns whether layout shift protection is enabled.
+   *
+   * @returns {boolean} True if scroll preservation is active, false otherwise.
+   */
+  getPreserveScrollOnLayoutShift() {
+    return this.#preserveScrollOnLayoutShift;
+  }
+
+  /**
+   * Returns the debounce delay in milliseconds used for scroll events.
+   *
+   * @returns {number} Debounce delay time.
+   */
+  getDebounceTime() {
+    return this.#debounceTime;
+  }
+
+  /**
+   * Returns the current number of matching elements observed inside the scroll target.
+   *
+   * @returns {number} Current count of matching elements.
+   */
+  getElemAmount() {
+    return this.#elemAmount;
+  }
+
+  /**
+   * Returns the previous known count of matching elements from the last update.
+   *
+   * @returns {number} Previous count of matching elements.
+   */
+  getPrevElemAmount() {
+    return this.#elemOldAmount;
+  }
+
+  /**
+   * Returns the query selector string used to filter observed elements.
+   *
+   * @returns {string} The CSS selector string, or an empty string if none was provided.
+   */
+  getQuerySelector() {
+    return this.#querySelector;
+  }
+
+  /**
+   * Disconnects all listeners, observers, and clears memory structures.
+   * Once destroyed, this instance should no longer be used.
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+
+    // Disconnects MutationObserver
+    if (this.#mutationObserver) {
+      this.#mutationObserver.disconnect();
+      this.#mutationObserver = null;
+    }
+
+    // Disconnect ResizeObserver
+    if (this.#resizeObserver) {
+      this.#resizeObserver.disconnect();
+      this.#resizeObserver = null;
+    }
+
+    // Removes scroll listener
+    const target = this.#useWindow ? window : this.#target;
+    if (this.#handler) target.removeEventListener('scroll', this.#handler);
+
+    // Clean the WeakMaps
+    this.#oldSizes = new WeakMap();
+    this.#newSizes = new WeakMap();
+    this.#newVisibles = new WeakMap();
+    this.#oldVisibles = new WeakMap();
+    this.#newVisiblesByTime = new WeakMap();
+    this.#oldVisiblesByTime = new WeakMap();
+
+    // Cleans listeners and filters
+    this.#scrollListeners = {};
+    this.#sizeFilter.clear();
+    this.#loadTags.clear();
+  }
+}
+
+/* harmony default export */ const libs_TinySmartScroller = ((/* unused pure expression or super */ null && (TinySmartScroller)));
+
+;// ./src/v1/index.mjs
+
+