tiny-essentials 1.13.2 → 1.15.0

package/dist/v1/TinyBasicsEs.js

@@ -2143,6 +2143,16 @@ __webpack_require__.r(__webpack_exports__);
 // EXPORTS
 __webpack_require__.d(__webpack_exports__, {
   addAiMarkerShortcut: () => (/* reexport */ addAiMarkerShortcut),
+  areElsCollBottom: () => (/* reexport */ collision_areElsCollBottom),
+  areElsCollLeft: () => (/* reexport */ collision_areElsCollLeft),
+  areElsCollPerfBottom: () => (/* reexport */ areElsCollPerfBottom),
+  areElsCollPerfLeft: () => (/* reexport */ areElsCollPerfLeft),
+  areElsCollPerfRight: () => (/* reexport */ areElsCollPerfRight),
+  areElsCollPerfTop: () => (/* reexport */ areElsCollPerfTop),
+  areElsCollRight: () => (/* reexport */ collision_areElsCollRight),
+  areElsCollTop: () => (/* reexport */ collision_areElsCollTop),
+  areElsColliding: () => (/* reexport */ collision_areElsColliding),
+  areElsPerfColliding: () => (/* reexport */ areElsPerfColliding),
   areHtmlElsColliding: () => (/* reexport */ areHtmlElsColliding),
   arraySortPositions: () => (/* reexport */ arraySortPositions),
   asyncReplace: () => (/* reexport */ asyncReplace),
@@ -2158,23 +2168,36 @@ __webpack_require__.d(__webpack_exports__, {
   formatTimer: () => (/* reexport */ formatTimer),
   genFibonacciSeq: () => (/* reexport */ genFibonacciSeq),
   getAge: () => (/* reexport */ getAge),
+  getElsCollDetails: () => (/* reexport */ getElsCollDetails),
+  getElsCollDirDepth: () => (/* reexport */ getElsCollDirDepth),
+  getElsCollOverlap: () => (/* reexport */ getElsCollOverlap),
+  getElsCollOverlapPos: () => (/* reexport */ getElsCollOverlapPos),
+  getElsColliding: () => (/* reexport */ getElsColliding),
+  getElsPerfColliding: () => (/* reexport */ getElsPerfColliding),
+  getElsRelativeCenterOffset: () => (/* reexport */ getElsRelativeCenterOffset),
   getHtmlElBorders: () => (/* reexport */ getHtmlElBorders),
   getHtmlElBordersWidth: () => (/* reexport */ getHtmlElBordersWidth),
   getHtmlElMargin: () => (/* reexport */ getHtmlElMargin),
   getHtmlElPadding: () => (/* reexport */ getHtmlElPadding),
+  getRectCenter: () => (/* reexport */ getRectCenter),
   getSimplePerc: () => (/* reexport */ getSimplePerc),
   getTimeDuration: () => (/* reexport */ getTimeDuration),
   installWindowHiddenScript: () => (/* reexport */ installWindowHiddenScript),
   isFullScreenMode: () => (/* reexport */ isFullScreenMode),
+  isInViewport: () => (/* reexport */ isInViewport),
   isJsonObject: () => (/* reexport */ isJsonObject),
   isScreenFilled: () => (/* reexport */ isScreenFilled),
+  isScrolledIntoView: () => (/* reexport */ isScrolledIntoView),
   objType: () => (/* reexport */ objType),
   offFullScreenChange: () => (/* reexport */ offFullScreenChange),
   onFullScreenChange: () => (/* reexport */ onFullScreenChange),
+  readBase64Blob: () => (/* reexport */ readBase64Blob),
+  readFileBlob: () => (/* reexport */ readFileBlob),
   readJsonBlob: () => (/* reexport */ readJsonBlob),
   reorderObjTypeOrder: () => (/* reexport */ reorderObjTypeOrder),
   requestFullScreen: () => (/* reexport */ requestFullScreen),
   ruleOfThree: () => (/* reexport */ ruleOfThree),
+  safeTextTrim: () => (/* reexport */ safeTextTrim),
   saveJsonFile: () => (/* reexport */ saveJsonFile),
   shuffleArray: () => (/* reexport */ shuffleArray),
   toTitleCase: () => (/* reexport */ toTitleCase),
@@ -2848,9 +2871,404 @@ extendObjType([
   ],
 ]);
 
+;// ./src/v1/basics/collision.mjs
+/**
+ * A direction relative to a rectangle.
+ *
+ * Represents one of the four cardinal directions from the perspective of the element.
+ *
+ * @typedef {'top' | 'bottom' | 'left' | 'right'} Dirs
+ */
+
+/**
+ * Represents all directional aspects of a collision.
+ *
+ * @typedef {Object} CollDirs
+ * @property {Dirs | 'center' | null} in - The dominant direction of entry. `'center'` if all sides are equally overlapped. `null` if no collision.
+ * @property {Dirs | null} x - The horizontal direction (`'left'` or `'right'`) the collision is biased toward, or `null`.
+ * @property {Dirs | null} y - The vertical direction (`'top'` or `'bottom'`) the collision is biased toward, or `null`.
+ */
+
+/**
+ * Indicates if a collision is in the negative direction (rect2 is outside rect1).
+ *
+ * @typedef {Object} NegCollDirs
+ * @property {Dirs | null} x - Horizontal direction of negative overlap, if any.
+ * @property {Dirs | null} y - Vertical direction of negative overlap, if any.
+ */
+
+/**
+ * Collision depth values from each side of rect2 inside rect1.
+ *
+ * Positive values indicate penetration; negative values indicate gaps.
+ *
+ * @typedef {Object} CollData
+ * @property {number} top - Depth from rect2's top into rect1.
+ * @property {number} bottom - Depth from rect2's bottom into rect1.
+ * @property {number} left - Depth from rect2's left into rect1.
+ * @property {number} right - Depth from rect2's right into rect1.
+ */
+
+/**
+ * X and Y offset representing center difference between two rectangles.
+ *
+ * Useful to measure how far one element's center is from another.
+ *
+ * @typedef {Object} CollCenter
+ * @property {number} x - Horizontal distance in pixels from rect1's center to rect2's center.
+ * @property {number} y - Vertical distance in pixels from rect1's center to rect2's center.
+ */
+
+/**
+ * Represents a rectangular area in absolute pixel values.
+ *
+ * Similar to `DOMRect`, this object describes the dimensions and position of a box
+ * in the 2D plane, typically representing an element's bounding box.
+ *
+ * @typedef {Object} ObjRect
+ * @property {number} height - The total height of the rectangle in pixels.
+ * @property {number} width - The total width of the rectangle in pixels.
+ * @property {number} top - The Y-coordinate of the top edge of the rectangle.
+ * @property {number} bottom - The Y-coordinate of the bottom edge of the rectangle.
+ * @property {number} left - The X-coordinate of the left edge of the rectangle.
+ * @property {number} right - The X-coordinate of the right edge of the rectangle.
+ */
+
+// Normal collision checks (loose overlap detection)
+
+/**
+ * Checks if rect1 is completely above rect2 (no vertical overlap).
+ *
+ * @param {ObjRect} rect1 - The bounding rectangle of the first element.
+ * @param {ObjRect} rect2 - The bounding rectangle of the second element.
+ * @returns {boolean} True if rect1 is entirely above rect2.
+ */
+const collision_areElsCollTop = (rect1, rect2) => rect1.bottom < rect2.top;
+
+/**
+ * Checks if rect1 is completely below rect2 (no vertical overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is entirely below rect2.
+ */
+const collision_areElsCollBottom = (rect1, rect2) => rect1.top > rect2.bottom;
+
+/**
+ * Checks if rect1 is completely to the left of rect2 (no horizontal overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is entirely to the left of rect2.
+ */
+const collision_areElsCollLeft = (rect1, rect2) => rect1.right < rect2.left;
+
+/**
+ * Checks if rect1 is completely to the right of rect2 (no horizontal overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is entirely to the right of rect2.
+ */
+const collision_areElsCollRight = (rect1, rect2) => rect1.left > rect2.right;
+
+// Perfect collision checks (touch included)
+
+/**
+ * Checks if rect1 is perfectly above rect2 (no vertical touch or overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is fully above or touching rect2's top.
+ */
+const areElsCollPerfTop = (rect1, rect2) => rect1.bottom <= rect2.top;
+
+/**
+ * Checks if rect1 is perfectly below rect2 (no vertical touch or overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is fully below or touching rect2's bottom.
+ */
+const areElsCollPerfBottom = (rect1, rect2) => rect1.top >= rect2.bottom;
+
+/**
+ * Checks if rect1 is perfectly to the left of rect2 (no horizontal touch or overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is fully left or touching rect2's left.
+ */
+const areElsCollPerfLeft = (rect1, rect2) => rect1.right <= rect2.left;
+
+/**
+ * Checks if rect1 is perfectly to the right of rect2 (no horizontal touch or overlap).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if rect1 is fully right or touching rect2's right.
+ */
+const areElsCollPerfRight = (rect1, rect2) => rect1.left >= rect2.right;
+
+// Main collision check
+
+/**
+ * Returns true if rect1 and rect2 are colliding (partially or fully overlapping).
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if there's any collision between rect1 and rect2.
+ */
+const collision_areElsColliding = (rect1, rect2) =>
+  !(
+    collision_areElsCollLeft(rect1, rect2) ||
+    collision_areElsCollRight(rect1, rect2) ||
+    collision_areElsCollTop(rect1, rect2) ||
+    collision_areElsCollBottom(rect1, rect2)
+  );
+
+/**
+ * Returns true if rect1 and rect2 are colliding or perfectly touching.
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {boolean} True if there's any contact or overlap.
+ */
+const areElsPerfColliding = (rect1, rect2) =>
+  !(
+    areElsCollPerfLeft(rect1, rect2) ||
+    areElsCollPerfRight(rect1, rect2) ||
+    areElsCollPerfTop(rect1, rect2) ||
+    areElsCollPerfBottom(rect1, rect2)
+  );
+
+// Collision direction guess (loose and perfect)
+
+/**
+ * Attempts to determine the direction rect1 entered rect2 based on loose overlap rules.
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {string|null} 'top' | 'bottom' | 'left' | 'right' | null
+ */
+const getElsColliding = (rect1, rect2) => {
+  if (collision_areElsCollLeft(rect1, rect2)) return 'left';
+  else if (collision_areElsCollRight(rect1, rect2)) return 'right';
+  else if (collision_areElsCollTop(rect1, rect2)) return 'top';
+  else if (collision_areElsCollBottom(rect1, rect2)) return 'bottom';
+  return null;
+};
+
+/**
+ * Attempts to determine the direction rect1 touched or entered rect2 using perfect mode.
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {'top' | 'bottom' | 'left' | 'right' | null}
+ */
+const getElsPerfColliding = (rect1, rect2) => {
+  if (areElsCollPerfLeft(rect1, rect2)) return 'left';
+  else if (areElsCollPerfRight(rect1, rect2)) return 'right';
+  else if (areElsCollPerfTop(rect1, rect2)) return 'top';
+  else if (areElsCollPerfBottom(rect1, rect2)) return 'bottom';
+  return null;
+};
+
+// Overlap Calculation
+
+/**
+ * Calculates overlap values between rect1 and rect2 in all directions.
+ *
+ * @param {ObjRect} rect1
+ * @param {ObjRect} rect2
+ * @returns {{
+ *   overlapLeft: number,
+ *   overlapRight: number,
+ *   overlapTop: number,
+ *   overlapBottom: number
+ * }} Distance of overlap from each direction (can be negative).
+ */
+const getElsCollOverlap = (rect1, rect2) => ({
+  overlapLeft: rect2.right - rect1.left,
+  overlapRight: rect1.right - rect2.left,
+  overlapTop: rect2.bottom - rect1.top,
+  overlapBottom: rect1.bottom - rect2.top,
+});
+
+/**
+ * Determines directional collision based on overlap depth.
+ *
+ * @param {Object} [settings={}]
+ * @param {number} [settings.overlapLeft]
+ * @param {number} [settings.overlapRight]
+ * @param {number} [settings.overlapTop]
+ * @param {number} [settings.overlapBottom]
+ * @returns {{ dirX: Dirs, dirY: Dirs }} Direction of strongest X/Y overlap.
+ */
+const getElsCollOverlapPos = ({
+  overlapLeft = -1,
+  overlapRight = -1,
+  overlapTop = -1,
+  overlapBottom = -1,
+} = {}) => ({
+  dirX: overlapLeft < overlapRight ? 'right' : 'left',
+  dirY: overlapTop < overlapBottom ? 'bottom' : 'top',
+});
+
+// Center utils
+
+/**
+ * Calculates the center point (X and Y) of a given Rect.
+ *
+ * @param {ObjRect} rect - The bounding rectangle of the element.
+ * @returns {{ x: number, y: number }} An object with the `x` and `y` coordinates of the center.
+ */
+const getRectCenter = (rect) => ({
+  x: rect.left + rect.width / 2,
+  y: rect.top + rect.height / 2,
+});
+
+/**
+ * Calculates the offset between the center of rect2 and the center of rect1.
+ *
+ * The values will be 0 when rect1 is perfectly centered over rect2.
+ *
+ * @param {ObjRect} rect1 - The bounding rectangle of the reference element.
+ * @param {ObjRect} rect2 - The bounding rectangle of the element being compared.
+ * @returns {{
+ *   x: number,
+ *   y: number
+ * }} An object with the X and Y offset in pixels from rect1's center to rect2's center.
+ */
+function getElsRelativeCenterOffset(rect1, rect2) {
+  const center1X = rect1.left + rect1.width / 2;
+  const center1Y = rect1.top + rect1.height / 2;
+
+  const center2X = rect2.left + rect2.width / 2;
+  const center2Y = rect2.top + rect2.height / 2;
+
+  return {
+    x: center2X - center1X,
+    y: center2Y - center1Y,
+  };
+}
+
+// Direction & Depth detection
+
+/**
+ * Detects the direction of the dominant collision between two elements
+ * and calculates how deep the overlap is in both x and y axes.
+ *
+ * @param {ObjRect} rect1 - The bounding rectangle of the first element.
+ * @param {ObjRect} rect2 - The bounding rectangle of the second element.
+ * @returns {{
+ *   inDir: Dirs | null;
+ *   dirX: Dirs | null;
+ *   dirY: Dirs | null;
+ *   depthX: number;
+ *   depthY: number;
+ * }} An object containing the collision direction and how deep the overlap is.
+ */
+function getElsCollDirDepth(rect1, rect2) {
+  if (!areElsPerfColliding(rect1, rect2))
+    return {
+      inDir: null,
+      dirX: null,
+      dirY: null,
+      depthX: 0,
+      depthY: 0,
+    };
+
+  const { overlapLeft, overlapRight, overlapTop, overlapBottom } = getElsCollOverlap(rect1, rect2);
+  const { dirX, dirY } = getElsCollOverlapPos({
+    overlapLeft,
+    overlapRight,
+    overlapTop,
+    overlapBottom,
+  });
+  const depthX = Math.min(overlapLeft, overlapRight);
+  const depthY = Math.min(overlapTop, overlapBottom);
+
+  /** @type {Dirs} */
+  let inDir;
+
+  if (depthX < depthY) inDir = dirX;
+  else inDir = dirY;
+  return { inDir, dirX, dirY, depthX, depthY };
+}
+
+// Full detail report
+
+/**
+ * Detects the collision direction and depth between two DOMRects.
+ *
+ * @param {ObjRect} rect1 - The bounding rectangle of the first element.
+ * @param {ObjRect} rect2 - The bounding rectangle of the second element.
+ * @returns {{ depth: CollData; dirs: CollDirs; isNeg: NegCollDirs; }} Collision info or null if no collision is detected.
+ */
+function getElsCollDetails(rect1, rect2) {
+  const isColliding = areElsPerfColliding(rect1, rect2);
+
+  /** @type {CollDirs} */
+  const dirs = { in: null, x: null, y: null };
+
+  /** @type {NegCollDirs} */
+  const isNeg = { y: null, x: null };
+
+  /** @type {Record<Dirs, number>} */
+  const depth = { top: 0, bottom: 0, left: 0, right: 0 };
+
+  // Depth
+  // Yes, it's actually reversed the values orders
+  const { overlapLeft, overlapRight, overlapTop, overlapBottom } = getElsCollOverlap(rect2, rect1);
+  depth.top = overlapTop;
+  depth.bottom = overlapBottom;
+  depth.left = overlapLeft;
+  depth.right = overlapRight;
+
+  // Dirs
+  /**
+   * Detect the direction with the smallest positive overlap (entry point)
+   * @type {[Dirs, number][]}
+   */
+  // @ts-ignore
+  const entries = Object.entries(depth)
+    .filter(([, val]) => val > 0)
+    .sort((a, b) => a[1] - b[1]);
+
+  // Yes, it's actually reversed the values orders here too
+  const { dirX, dirY } = getElsCollOverlapPos({
+    overlapLeft: overlapRight,
+    overlapRight: overlapLeft,
+    overlapTop: overlapBottom,
+    overlapBottom: overlapTop,
+  });
+  dirs.y = dirY;
+  dirs.x = dirX;
+
+  // isNeg
+  if (depth.bottom < 0) isNeg.y = 'bottom';
+  else if (depth.top < 0) isNeg.y = 'top';
+  if (depth.left < 0) isNeg.x = 'left';
+  else if (depth.right < 0) isNeg.x = 'right';
+
+  // Inside Dir
+  dirs.in = isColliding
+    ? depth.top === depth.bottom && depth.bottom === depth.left && depth.left === depth.right
+      ? 'center'
+      : entries.length
+        ? entries[0][0]
+        : 'top'
+    : null; // fallback in case of exact match
+
+  // Complete
+  return { dirs, depth, isNeg };
+}
+
 ;// ./src/v1/basics/html.mjs
 
 
+
 /**
  * Checks if two DOM elements are colliding on the screen.
  *
@@ -2861,44 +3279,157 @@ extendObjType([
 function areHtmlElsColliding(elem1, elem2) {
   const rect1 = elem1.getBoundingClientRect();
   const rect2 = elem2.getBoundingClientRect();
+  return collision_areElsColliding(rect1, rect2);
+}
 
-  return !(
-    rect1.right < rect2.left ||
-    rect1.left > rect2.right ||
-    rect1.bottom < rect2.top ||
-    rect1.top > rect2.bottom
-  );
+/**
+ * Checks if two DOM elements are colliding on the screen, and locks the collision
+ * until the element exits through the same side it entered.
+ *
+ * @param {Element} elem1 - First DOM element (e.g. draggable or moving element).
+ * @param {Element} elem2 - Second DOM element (e.g. a container or boundary element).
+ * @param {'top'|'bottom'|'left'|'right'} lockDirection - Direction that must be respected to unlock the collision.
+ * @param {WeakMap<Element, string>} stateMap - A shared WeakMap to track persistent entry direction per element.
+ * @returns {boolean} True if collision is still active.
+ */
+function areHtmlElsCollidingWithLock(elem1, elem2, lockDirection, stateMap) {
+  const rect1 = elem1.getBoundingClientRect();
+  const rect2 = elem2.getBoundingClientRect();
+  const isColliding = areElsColliding(rect1, rect2);
+
+  if (isColliding) {
+    // Save entry direction
+    if (!stateMap.has(elem1)) {
+      stateMap.set(elem1, lockDirection);
+    }
+    return true;
+  }
+
+  // Handle unlock logic
+  if (stateMap.has(elem1)) {
+    const lastDirection = stateMap.get(elem1);
+
+    switch (lastDirection) {
+      case 'top':
+        if (areElsCollTop(rect1, rect2)) stateMap.delete(elem1); // exited from top
+        break;
+      case 'bottom':
+        if (areElsCollBottom(rect1, rect2)) stateMap.delete(elem1); // exited from bottom
+        break;
+      case 'left':
+        if (areElsCollLeft(rect1, rect2)) stateMap.delete(elem1); // exited from left
+        break;
+      case 'right':
+        if (areElsCollRight(rect1, rect2)) stateMap.delete(elem1); // exited from right
+        break;
+    }
+
+    return stateMap.has(elem1); // still colliding (locked)
+  }
+
+  return false;
 }
 
 /**
- * Reads and parses a JSON data using FileReader.
- * Throws an error if the content is not valid JSON.
- * @param {File} file
- * @returns {Promise<any>}
+ * Reads the contents of a file using the specified FileReader method.
+ *
+ * @param {File} file - The file to be read.
+ * @param {'readAsArrayBuffer'|'readAsDataURL'|'readAsText'|'readAsBinaryString'} method -
+ *   The FileReader method to use for reading the file.
+ * @returns {Promise<any>} - A promise that resolves with the file content, according to the chosen method.
+ * @throws {Error} - If an unexpected error occurs while handling the result.
+ * @throws {DOMException} - If the FileReader encounters an error while reading the file.
  */
-function readJsonBlob(file) {
+function readFileBlob(file, method) {
   return new Promise((resolve, reject) => {
     const reader = new FileReader();
-
     reader.onload = () => {
       try {
-        // @ts-ignore
-        const result = JSON.parse(reader.result);
-        resolve(result);
+        resolve(reader.result);
       } catch (error) {
-        // @ts-ignore
-        reject(new Error(`Invalid JSON in file: ${file.name}\n${error.message}`));
+        reject(error);
       }
     };
-
     reader.onerror = () => {
-      reject(new Error(`Error reading file: ${file.name}`));
+      reject(reader.error);
     };
+    reader[method](file);
+  });
+}
 
-    reader.readAsText(file);
+/**
+ * Reads a file as a Base64 string using FileReader, and optionally formats it as a full data URL.
+ *
+ * Performs strict validation to ensure the result is a valid Base64 string or a proper data URL.
+ *
+ * @param {File} file - The file to be read.
+ * @param {boolean|string} [isDataUrl=false] - If true, returns a full data URL; if false, returns only the Base64 string;
+ *   if a string is passed, it is used as the MIME type in the data URL.
+ * @returns {Promise<string>} - A promise that resolves with the Base64 string or data URL.
+ *
+ * @throws {TypeError} - If the result is not a string or if `isDataUrl` is not a valid type.
+ * @throws {Error} - If the result does not match the expected data URL format or Base64 structure.
+ * @throws {DOMException} - If the FileReader fails to read the file.
+ */
+function readBase64Blob(file, isDataUrl = false) {
+  return new Promise((resolve, reject) => {
+    if (typeof isDataUrl !== 'string' && typeof isDataUrl !== 'boolean')
+      reject(new TypeError('The isDataUrl parameter must be a boolean or a string.'));
+    readFileBlob(file, 'readAsDataURL')
+      .then(
+        /**
+         * Ensure that the URL format is correct in the required pattern
+         * @param {string} base64Data
+         */ (base64Data) => {
+          if (typeof base64Data !== 'string')
+            throw new TypeError('Expected file content to be a string.');
+
+          const match = base64Data.match(/^data:(.+);base64,(.*)$/);
+          if (!match || !match[2])
+            throw new Error('Invalid data URL format or missing Base64 content.');
+          const [, mimeType, base64] = match;
+          if (!/^[\w/+]+=*$/.test(base64)) throw new Error('Base64 content is malformed.');
+
+          if (typeof isDataUrl === 'boolean') return resolve(isDataUrl ? base64Data : base64);
+          if (!/^[\w-]+\/[\w.+-]+$/.test(isDataUrl))
+            throw new Error(`Invalid MIME type string: ${isDataUrl}`);
+
+          return resolve(`data:${isDataUrl};base64,${base64}`);
+        },
+      )
+      .catch(reject);
   });
 }
 
+/**
+ * Reads a file and strictly validates its content as proper JSON using FileReader.
+ *
+ * Performs several checks to ensure the file contains valid, parsable JSON data.
+ *
+ * @param {File} file - The file to be read. It must contain valid JSON as plain text.
+ * @returns {Promise<Record<string|number|symbol, any>|any[]>} - A promise that resolves with the parsed JSON object.
+ *
+ * @throws {SyntaxError} - If the file content is not valid JSON syntax.
+ * @throws {TypeError} - If the result is not a string or does not represent a JSON value.
+ * @throws {Error} - If the result is empty or structurally invalid as JSON.
+ * @throws {DOMException} - If the FileReader fails to read the file.
+ */
+function readJsonBlob(file) {
+  return new Promise((resolve, reject) =>
+    readFileBlob(file, 'readAsText')
+      .then((data) => {
+        if (typeof data !== 'string') throw new TypeError('Expected file content to be a string.');
+        const trimmed = data.trim();
+        if (trimmed.length === 0) throw new Error('File is empty or contains only whitespace.');
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed !== 'object' || parsed === null)
+          throw new Error('Parsed content is not a valid JSON object or array.');
+        resolve(parsed);
+      })
+      .catch(reject),
+  );
+}
+
 /**
  * Saves a JSON object as a downloadable file.
  * @param {string} filename
@@ -3001,7 +3532,8 @@ async function fetchJson(
 
       const data = await response.json();
 
-      if (!isJsonObject(data)) throw new Error('Received invalid data instead of valid JSON.');
+      if (!Array.isArray(data) && !isJsonObject(data))
+        throw new Error('Received invalid data instead of valid JSON.');
 
       return data;
     } catch (err) {
@@ -3103,19 +3635,34 @@ const getHtmlElPadding = (el) => {
 
 /**
  * Installs a script that toggles CSS classes on a given element
- * based on the page's visibility or focus state.
+ * based on the page's visibility or focus state, and optionally
+ * triggers callbacks on visibility changes.
  *
  * @param {Object} [settings={}]
  * @param {HTMLElement} [settings.element=document.body] - The element to receive visibility classes.
  * @param {string} [settings.hiddenClass='windowHidden'] - CSS class applied when the page is hidden.
  * @param {string} [settings.visibleClass='windowVisible'] - CSS class applied when the page is visible.
+ * @param {() => void} [settings.onVisible] - Callback called when page becomes visible.
+ * @param {() => void} [settings.onHidden] - Callback called when page becomes hidden.
  * @returns {() => void} Function that removes all installed event listeners.
+ * @throws {TypeError} If any provided setting is invalid.
  */
 function installWindowHiddenScript({
   element = document.body,
   hiddenClass = 'windowHidden',
   visibleClass = 'windowVisible',
+  onVisible,
+  onHidden,
 } = {}) {
+  if (!(element instanceof HTMLElement))
+    throw new TypeError(`"element" must be an instance of HTMLElement.`);
+  if (typeof hiddenClass !== 'string') throw new TypeError(`"hiddenClass" must be a string.`);
+  if (typeof visibleClass !== 'string') throw new TypeError(`"visibleClass" must be a string.`);
+  if (onVisible !== undefined && typeof onVisible !== 'function')
+    throw new TypeError(`"onVisible" must be a function if provided.`);
+  if (onHidden !== undefined && typeof onHidden !== 'function')
+    throw new TypeError(`"onHidden" must be a function if provided.`);
+
   const removeClass = () => {
     element.classList.remove(hiddenClass);
     element.classList.remove(visibleClass);
@@ -3123,8 +3670,6 @@ function installWindowHiddenScript({
 
   /** @type {string|null} */
   let hiddenProp = null;
-  /** @type {(this: any, evt: Event) => void} */
-  let handler;
 
   const visibilityEvents = [
     'visibilitychange',
@@ -3142,7 +3687,8 @@ function installWindowHiddenScript({
     }
   }
 
-  handler = function (evt) {
+  /** @type {(this: any, evt: Event) => void} */
+  const handler = function (evt) {
     removeClass();
 
     const type = evt?.type;
@@ -3154,10 +3700,18 @@ function installWindowHiddenScript({
 
     if (visibleEvents.includes(type)) {
       element.classList.add(visibleClass);
+      onVisible?.();
     } else if (hiddenEvents.includes(type)) {
       element.classList.add(hiddenClass);
+      onHidden?.();
     } else {
-      element.classList.add(isHidden ? hiddenClass : visibleClass);
+      if (isHidden) {
+        element.classList.add(hiddenClass);
+        onHidden?.();
+      } else {
+        element.classList.add(visibleClass);
+        onVisible?.();
+      }
     }
   };
 
@@ -3194,6 +3748,7 @@ function installWindowHiddenScript({
     };
   }
 
+  // Trigger initial state
   // @ts-ignore
   const simulatedEvent = new Event(hiddenProp && document[hiddenProp] ? 'blur' : 'focus');
   handler(simulatedEvent);
@@ -3201,6 +3756,38 @@ function installWindowHiddenScript({
   return uninstall;
 }
 
+/**
+ * Checks if the given element is at least partially visible in the viewport.
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} True if the element is partially in the viewport, false otherwise.
+ */
+function isInViewport(element) {
+  const elementTop = element.offsetTop;
+  const elementBottom = elementTop + element.offsetHeight;
+
+  const viewportTop = window.scrollY;
+  const viewportBottom = viewportTop + window.innerHeight;
+
+  return elementBottom > viewportTop && elementTop < viewportBottom;
+}
+
+/**
+ * Checks if the given element is fully visible in the viewport (top and bottom).
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
+ */
+function isScrolledIntoView(element) {
+  const viewportTop = window.scrollY;
+  const viewportBottom = viewportTop + window.innerHeight;
+
+  const elemTop = element.offsetTop;
+  const elemBottom = elemTop + element.offsetHeight;
+
+  return elemBottom <= viewportBottom && elemTop >= viewportTop;
+}
+
 ;// ./src/v1/basics/fullScreen.mjs
 /**
  * Checks if the document is currently in fullscreen mode.
@@ -3556,6 +4143,48 @@ function addAiMarkerShortcut(key = 'a') {
   });
 }
 
+/**
+ * Trims a text string to a specified character limit, attempting to avoid cutting words in half.
+ * If a space is found before the limit and it's not too far from the limit (at least 60%),
+ * the cut is made at that space; otherwise, the text is hard-cut at the limit.
+ * If the input is shorter than the limit, it is returned unchanged.
+ *
+ * @param {string} text - The input text to be trimmed.
+ * @param {number} limit - The maximum number of characters allowed.
+ * @param {number} [safeCutZone=0.6] - A decimal between 0 and 1 representing the minimal acceptable position
+ *                                     (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
+ * @returns {string} - The trimmed text, possibly ending with an ellipsis ("...").
+ * @throws {TypeError} - Throws if `text` is not a string.
+ * @throws {TypeError} - Throws if `limit` is not a positive integer.
+ * @throws {TypeError} - Throws if `safeCutZone` is not a number between 0 and 1 (inclusive).
+ */
+function safeTextTrim(text, limit, safeCutZone = 0.6) {
+  if (typeof text !== 'string')
+    throw new TypeError(`Expected a string for 'text', but received ${typeof text}`);
+  if (!Number.isInteger(limit) || limit <= 0)
+    throw new TypeError(`Expected 'limit' to be a positive integer, but received ${limit}`);
+  if (typeof safeCutZone !== 'number' || safeCutZone < 0 || safeCutZone > 1)
+    throw new TypeError(
+      `Expected 'safeCutZone' to be a number between 0 and 1, but received ${safeCutZone}`,
+    );
+
+  let result = text.trim();
+  if (result.length > limit) {
+    // Try to cut the string into a space before the limit
+    const safeCut = result.lastIndexOf(' ', limit);
+
+    if (safeCut > 0 && safeCut >= limit * safeCutZone) {
+      // Only cuts where there is a space, and if the cut is not too early
+      return `${result.substring(0, safeCut).trim()}...`;
+    } else {
+      // Emergency: Cuts straight to the limit and adds "...".
+      return `${result.substring(0, limit).trim()}...`;
+    }
+  }
+
+  return result;
+}
+
 /*
 import { useEffect } from "react";
 
@@ -3593,6 +4222,7 @@ export default KeyPressHandler;
 
 
 
+
 })();
 
 window.TinyBasicsEs = __webpack_exports__;