tiny-essentials 1.13.1 → 1.14.0

package/dist/v1/libs/TinyNotifications.mjs

@@ -0,0 +1,211 @@
+import { safeTextTrim } from '../basics/text.mjs';
+/**
+ * A utility class to manage browser notifications with sound and custom behavior.
+ * Useful for triggering system notifications with optional sound, avatar icon, body truncation, and click actions.
+ *
+ * @class
+ */
+class TinyNotifications {
+    /** @type {boolean} Whether notifications are currently allowed by the user. */
+    #allowed = false;
+    /** @type {boolean} Indicates whether the user has already requested permission at least once. */
+    #permissionRequested = false;
+    /** @type {HTMLAudioElement|null} Audio element to play when a notification is triggered. */
+    #audio = null;
+    /** @type {number} Maximum number of characters in the notification body. */
+    #bodyLimit = 100;
+    /** @type {string|null} Default avatar icon URL for notifications. */
+    #defaultIcon = null;
+    /** @type {(this: Notification, evt: Event) => any} Default handler when a notification is clicked. */
+    #defaultOnClick;
+    /**
+     * Constructs a new instance of TinyNotifications.
+     *
+     * @param {Object} [settings={}] - Optional settings to initialize the notification manager.
+     * @param {string|HTMLAudioElement|null} [settings.audio] - Path or URL to the audio file for notification sounds.
+     * @param {string|null} [settings.defaultIcon] - Default icon URL to be used in notifications.
+     * @param {number} [settings.bodyLimit=100] - Maximum number of characters allowed in the notification body.
+     * @param {(this: Notification, evt: Event) => any} [settings.defaultOnClick] - Default function to execute when a notification is clicked.
+     * @throws {TypeError} If any of the parameters are of an invalid type.
+     */
+    constructor({ audio = null, defaultIcon = null, bodyLimit = 100, defaultOnClick = function (event) {
+        event.preventDefault();
+        if (window.focus)
+            window.focus();
+        this.close();
+    }, } = {}) {
+        if (!(audio instanceof HTMLAudioElement) && typeof audio !== 'string' && audio !== null)
+            throw new TypeError('audio must be an instance of HTMLAudioElement or null.');
+        if (defaultIcon !== null && typeof defaultIcon !== 'string')
+            throw new TypeError('defaultIcon must be a string or null.');
+        if (!Number.isFinite(bodyLimit) || bodyLimit < 0)
+            throw new TypeError('bodyLimit must be a non-negative number.');
+        if (typeof defaultOnClick !== 'function')
+            throw new TypeError('defaultOnClick must be a function.');
+        this.#audio = typeof audio !== 'string' ? audio : new Audio(audio);
+        this.#defaultIcon = defaultIcon;
+        this.#bodyLimit = bodyLimit;
+        this.#defaultOnClick = defaultOnClick;
+    }
+    /**
+     * Requests permission from the user to show notifications.
+     * Updates the internal `#allowed` flag.
+     *
+     * @returns {Promise<boolean>} Resolves to `true` if permission is granted, otherwise `false`.
+     */
+    requestPerm() {
+        const tinyThis = this;
+        return new Promise((resolve, reject) => {
+            if (tinyThis.isCompatible()) {
+                if (Notification.permission === 'default') {
+                    Notification.requestPermission()
+                        .then((permission) => {
+                        this.#permissionRequested = true;
+                        tinyThis.#allowed = permission === 'granted';
+                        resolve(tinyThis.#allowed);
+                    })
+                        .catch(reject);
+                }
+                else {
+                    this.#permissionRequested = true;
+                    tinyThis.#allowed = Notification.permission === 'granted';
+                    resolve(tinyThis.#allowed);
+                }
+            }
+            else {
+                this.#permissionRequested = true;
+                tinyThis.#allowed = false;
+                resolve(false);
+            }
+        });
+    }
+    /**
+     * Checks if the Notification API is supported by the current browser.
+     *
+     * @returns {boolean} Returns `true` if notifications are supported, otherwise `false`.
+     */
+    isCompatible() {
+        return 'Notification' in window;
+    }
+    /**
+     * Sends a browser notification with the provided title and configuration.
+     * Truncates the body if necessary and plays a sound if configured.
+     *
+     * @param {string} title - The title of the notification.
+     * @param {NotificationOptions & { vibrate?: number[] }} [config={}] - Optional configuration for the notification.
+     * @returns {Notification|null} The created `Notification` instance, or `null` if permission is not granted.
+     * @throws {TypeError} If the title is not a string or config is not a valid object.
+     */
+    send(title, config = {}) {
+        if (!this.#permissionRequested)
+            throw new Error('You must call requestPerm() before sending a notification.');
+        if (typeof title !== 'string')
+            throw new TypeError('title must be a string.');
+        if (typeof config !== 'object' || config === null)
+            throw new TypeError('config must be a non-null object.');
+        if (!this.#allowed)
+            return null;
+        const { icon = this.#defaultIcon || undefined, vibrate = [200, 100, 200] } = config;
+        const options = { ...config };
+        if (typeof icon === 'string')
+            options.icon = icon;
+        if (Array.isArray(vibrate))
+            options.vibrate = vibrate;
+        if (typeof options.body === 'string')
+            options.body = safeTextTrim(options.body, this.#bodyLimit);
+        const notification = new Notification(title, options);
+        notification.addEventListener('show', () => {
+            if (!(this.#audio instanceof HTMLAudioElement))
+                return;
+            this.#audio.currentTime = 0;
+            this.#audio.play().catch((err) => console.error(err));
+        });
+        if (typeof this.#defaultOnClick === 'function')
+            notification.addEventListener('click', this.#defaultOnClick);
+        return notification;
+    }
+    // === Getters and Setters ===
+    /**
+     * Whether the requestPerm() method was already called.
+     * @returns {boolean}
+     */
+    wasPermissionRequested() {
+        return this.#permissionRequested;
+    }
+    /**
+     * Returns the current permission status.
+     * @returns {boolean} `true` if permission was granted, otherwise `false`.
+     */
+    isAllowed() {
+        return this.#allowed;
+    }
+    /**
+     * Gets the current notification audio.
+     * @returns {HTMLAudioElement|null} The sound element, or `null` if not set.
+     */
+    getAudio() {
+        return this.#audio;
+    }
+    /**
+     * Sets the audio element used for notification sounds.
+     * @param {HTMLAudioElement|string|null} value - A valid `HTMLAudioElement` or `null` to disable sound.
+     * @throws {TypeError} If the value is not an `HTMLAudioElement` or `null`.
+     */
+    setAudio(value) {
+        if (!(value instanceof HTMLAudioElement) && typeof value !== 'string' && value !== null)
+            throw new TypeError('sound must be an instance of HTMLAudioElement or null.');
+        this.#audio = typeof value !== 'string' ? value : new Audio(value);
+    }
+    /**
+     * Gets the maximum length of the notification body text.
+     * @returns {number} Number of characters allowed.
+     */
+    getBodyLimit() {
+        return this.#bodyLimit;
+    }
+    /**
+     * Sets the maximum number of characters allowed in the notification body.
+     * @param {number} value - A non-negative integer.
+     * @throws {TypeError} If the value is not a valid non-negative number.
+     */
+    setBodyLimit(value) {
+        if (!Number.isFinite(value) || value < 0)
+            throw new TypeError('bodyLimit must be a non-negative number.');
+        this.#bodyLimit = value;
+    }
+    /**
+     * Gets the default avatar icon URL.
+     * @returns {string|null} The URL string or `null`.
+     */
+    getDefaultAvatar() {
+        return this.#defaultIcon;
+    }
+    /**
+     * Sets the default avatar icon URL.
+     * @param {string|null} value - A string URL or `null` to disable default icon.
+     * @throws {TypeError} If the value is not a string or `null`.
+     */
+    setDefaultAvatar(value) {
+        if (!(typeof value === 'string' || value === null))
+            throw new TypeError('defaultIcon must be a string or null.');
+        this.#defaultIcon = value;
+    }
+    /**
+     * Gets the default click event handler for notifications.
+     * @returns {(this: Notification, evt: Event) => any} The current click handler function.
+     */
+    getDefaultOnClick() {
+        return this.#defaultOnClick;
+    }
+    /**
+     * Sets the default click event handler for notifications.
+     * @param {(this: Notification, evt: Event) => any} value - A function to handle the notification click event.
+     * @throws {TypeError} If the value is not a function.
+     */
+    setDefaultOnClick(value) {
+        if (typeof value !== 'function')
+            throw new TypeError('defaultOnClick must be a function.');
+        this.#defaultOnClick = value;
+    }
+}
+export default TinyNotifications;

package/docs/v1/README.md

@@ -29,9 +29,10 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🔔 **[TinyNotifyCenter](./libs/TinyNotifyCenter.md)** — A dynamic notification center class to display, manage, and interact with notifications, supporting avatars, clickable items, HTML/text modes, and clean UI controls.
 - 🍞 **[TinyToastNotify](./libs/TinyToastNotify.md)** — A lightweight toast notification system supporting positioning, timing customization, avatars, click actions, and fade-out animations.
 - 📥 **[TinyDragDropDetector](./libs/TinyDragDropDetector.md)** — A lightweight drag-and-drop detector for files, handling the full drag lifecycle (`enter`, `over`, `leave`, `drop`) with CSS hover management and safe event handling on any DOM element or the full page.
-* 📂 **[TinyUploadClicker](./libs/TinyUploadClicker.md)** — A minimal utility to bind any clickable element to a hidden file input, offering full control over styling, behavior, and upload event hooks.
-* 🧲 **[TinyDragger](./libs/TinyDragger.md)** — A flexible drag-and-drop manager with collision detection, jail constraints, vibration feedback, visual proxies, revert-on-drop, and full custom event support.
-* 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
+- 📂 **[TinyUploadClicker](./libs/TinyUploadClicker.md)** — A minimal utility to bind any clickable element to a hidden file input, offering full control over styling, behavior, and upload event hooks.
+- 🧲 **[TinyDragger](./libs/TinyDragger.md)** — A flexible drag-and-drop manager with collision detection, jail constraints, vibration feedback, visual proxies, revert-on-drop, and full custom event support.
+- 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
+- 📣 **[TinyNotifications](./libs/TinyNotifications.md)** — A browser notification utility with sound support, permission management, truncation logic, default icons, and enforced validation to ensure safe and predictable usage.
 
 ### 3. **`fileManager/`**
 * 📁 **[main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/basics/array.md

@@ -1,16 +1,18 @@
 # 📦 array.mjs
 
-A tiny utility for shuffling arrays using the good old Fisher–Yates algorithm. Simple, efficient, and perfectly random (as far as JavaScript's `Math.random()` allows, anyway).
+A minimal and handy module offering a couple of focused utilities for working with arrays — from shuffling items randomly to generating smart sort functions for object arrays. Ideal for quick scripting or modular use in larger projects.
 
-## ✨ Features
+---
+
+## `shuffleArray(items: string[]): string[]`
 
-- 📚 Uses the classic **Fisher–Yates** algorithm
-- 🔄 Shuffles arrays **in-place**
-- 🎯 Guarantees **uniform distribution** of permutations
-- 🔍 Well-documented and easy to read
-- 🧪 No dependencies — just plug and play
+🔄 A tiny utility for shuffling arrays using the good old Fisher–Yates algorithm. Simple, efficient, and perfectly random (as far as JavaScript's `Math.random()` allows, anyway).
 
-## 🚀 Usage
+- **items** — An array of strings to shuffle.
+- **Returns** — The same array instance, but now shuffled.
+
+
+### 🚀 Usage
 
 ```js
 import { shuffleArray } from './array.mjs';
@@ -23,54 +25,29 @@ console.log(fruits); // ['banana', 'cherry', 'apple', 'date'] (order will vary)
 
 > Note: The original array is shuffled in place. If you want to preserve the original order, make a copy before shuffling.
 
-## 🧠 How It Works
-
-This function implements the **Fisher–Yates shuffle** (also known as the Knuth shuffle), which runs in linear time and guarantees uniform randomness:
-
-```js
-while (currentIndex !== 0) {
-  randomIndex = Math.floor(Math.random() * currentIndex);
-  currentIndex--;
-  [items[currentIndex], items[randomIndex]] = [items[randomIndex], items[currentIndex]];
-}
-```
-
 You can find the original discussion here:  
 🔗 https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
 
-## 📁 API
-
-### `shuffleArray(items: string[]): string[]`
-
-- **items** — An array of strings to shuffle.
-- **Returns** — The same array instance, but now shuffled.
-
 ---
 
-# 📦 `arraySortPositions`
+## 📦 `arraySortPositions`
 
 🔧 **Generates a comparator function** to sort an array of objects by a specified key, with optional reverse order.
 
----
-
-## 📌 Function Signature
+### 📌 Function Signature
 
 ```js
 arraySortPositions(item: string, isReverse?: boolean): (a: Object<string|number, *>, b: Object<string|number, *>) => number
 ```
 
----
-
-## 🧠 Parameters
+### 🧠 Parameters
 
 | Name        | Type      | Default | Description                                                |
 | ----------- | --------- | ------- | ---------------------------------------------------------- |
 | `item`      | `string`  | —       | 🔑 The key to sort the objects by.                         |
 | `isReverse` | `boolean` | `false` | 🔄 If `true`, the sorting will be in **descending** order. |
 
----
-
-## 🎯 Returns
+### 🎯 Returns
 
 🧩 A **comparator function** compatible with `Array.prototype.sort()`:
 
@@ -80,9 +57,7 @@ arraySortPositions(item: string, isReverse?: boolean): (a: Object<string|number,
 
 It compares two objects based on the specified `item` key.
 
----
-
-## 💡 Examples
+### 💡 Examples
 
 ```js
 const arr = [{ pos: 2 }, { pos: 1 }, { pos: 3 }];
@@ -96,9 +71,7 @@ arr.sort(arraySortPositions('pos', true));
 // 🔽 Descending: [{ pos: 3 }, { pos: 2 }, { pos: 1 }]
 ```
 
----
-
-## 🛠️ Use Case
+### 🛠️ Use Case
 
 Great for situations where you need to **dynamically sort objects** by one of their keys, such as:
 

package/docs/v1/basics/html.md

@@ -1,4 +1,4 @@
-## 🚀 `areHtmlElsColliding()`
+### 🚀 `areHtmlElsColliding()`
 
 Check if two DOM elements are **colliding on the screen**! Perfect for games, draggable elements, UI interactions, and more.
 
@@ -11,34 +11,26 @@ It compares the bounding rectangles of both elements:
 * ✅ Checks if **rect1** is NOT entirely to the left, right, above, or below **rect2**.
 * ✅ If none of these are true, then the elements are overlapping.
 
----
-
-## 🧠 Syntax
+#### 🧠 Syntax
 
 ```javascript
 areHtmlElsColliding(elem1, elem2);
 ```
 
----
-
-## 🎯 Parameters
+#### 🎯 Parameters
 
 | Parameter | Type      | Description             |
 | --------- | --------- | ----------------------- |
 | `elem1`   | `Element` | The first DOM element.  |
 | `elem2`   | `Element` | The second DOM element. |
 
----
-
-## 🔁 Return
+#### 🔁 Return
 
 | Type      | Description                                                        |
 | --------- | ------------------------------------------------------------------ |
 | `boolean` | ✅ `true` if elements are colliding. <br>❌ `false` if they are not. |
 
----
-
-## 📦 Example
+#### 📦 Example
 
 ```javascript
 const box1 = document.getElementById('box1');
@@ -51,33 +43,115 @@ if (areHtmlElsColliding(box1, box2)) {
 }
 ```
 
----
-
-## 🚧 Limitations
+#### 🚧 Limitations
 
 * Only works with **axis-aligned elements** (rectangular shapes).
 * Does not handle rotated elements or complex shapes.
 
 ---
 
-## 📖 `readJsonBlob(file: File): Promise<any>`
+### 📖 `readBase64Blob(file: File, isDataUrl?: boolean | string): Promise<string>`
+
+Reads a file and returns its Base64 content using the FileReader API, with optional formatting as a full Data URL.
+
+#### 📥 Parameters
+
+* `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
+* `isDataUrl` *(boolean | string, optional)*:
+
+  * If `false` *(default)*: returns only the Base64 portion.
+  * If `true`: returns the original Data URL string from `FileReader`.
+  * If a string: treated as a custom MIME type for building a new Data URL.
+
+#### 📤 Returns
+
+* `Promise<string>`: Resolves with either the Base64 string or a complete Data URL, depending on `isDataUrl`.
+
+#### ⚠️ Throws
+
+* `TypeError` if:
+
+  * The result is not a string.
+  * The `isDataUrl` argument is not a boolean or a string.
+* `Error` if:
+
+  * The string is not a valid Base64 or Data URL format.
+  * The MIME string format is invalid.
+* `DOMException` if the file cannot be read by `FileReader`.
+
+#### 🧪 Example
+
+```js
+const input = document.querySelector('input[type="file"]');
+input.addEventListener('change', async () => {
+  try {
+    const base64 = await readBase64Blob(input.files[0], false);
+    console.log(base64); // Logs only the Base64 string
+  } catch (err) {
+    console.error('Error reading file:', err.message);
+  }
+});
+```
+
+---
+
+### 📖 `readFileBlob(file: File, method: 'readAsArrayBuffer' | 'readAsDataURL' | 'readAsText' | 'readAsBinaryString'): Promise<any>`
+
+Reads the contents of a file using a specified FileReader method.
+
+#### 📥 Parameters
+
+* `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
+* `method` *(string)*: The FileReader method to use:
+
+  * `'readAsArrayBuffer'` — for binary buffers
+  * `'readAsDataURL'` — for Base64 encoded data URLs
+  * `'readAsText'` — for plain text
+  * `'readAsBinaryString'` — for legacy binary string output
+
+#### 📤 Returns
+
+* `Promise<any>`: Resolves with the file content, depending on the method used.
+
+#### ⚠️ Throws
+
+* `Error` if an unexpected error occurs while resolving the result.
+* `DOMException` if `FileReader` encounters a failure during the read process.
+
+#### 🧪 Example
+
+```js
+const input = document.querySelector('input[type="file"]');
+input.addEventListener('change', async () => {
+  try {
+    const text = await readFileBlob(input.files[0], 'readAsText');
+    console.log(text); // Logs the file content as plain text
+  } catch (err) {
+    console.error('Error reading file:', err.message);
+  }
+});
+```
+
+---
+
+### 📖 `readJsonBlob(file: File): Promise<any>`
 
 Reads and parses a JSON file using the [`FileReader`](https://developer.mozilla.org/en-US/docs/Web/API/FileReader) API.
 
-### 📥 Parameters
+#### 📥 Parameters
 
 * `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
 
-### 📤 Returns
+#### 📤 Returns
 
 * `Promise<any>`: Resolves with the parsed JSON object, or rejects with an error if the content is invalid.
 
-### ⚠️ Throws
+#### ⚠️ Throws
 
 * An error if the content is not valid JSON.
 * An error if the file can't be read.
 
-### 🧪 Example
+#### 🧪 Example
 
 ```js
 const input = document.querySelector('input[type="file"]');
@@ -93,36 +167,36 @@ input.addEventListener('change', async () => {
 
 ---
 
-## 💾 `saveJsonFile(filename: string, data: any, spaces: number = 2): void`
+### 💾 `saveJsonFile(filename: string, data: any, spaces: number = 2): void`
 
 Converts a JavaScript object to JSON and triggers a download in the browser.
 
-### 📥 Parameters
+#### 📥 Parameters
 
 * `filename` *(string)*: The name of the file to save (e.g., `"data.json"`).
 * `data` *(any)*: The JavaScript object to convert to JSON.
 * `spaces` *(number)* *(optional)*: Indentation level for formatting the JSON string. Default is `2`.
 
-### 📤 Returns
+#### 📤 Returns
 
 * `void`
 
-### 📂 Behavior
+#### 📂 Behavior
 
 Creates a temporary `<a>` element, downloads the file, and cleans up the URL.
 
-### 🧪 Example
+#### 🧪 Example
 
 ```js
 const data = { name: 'Yasmin', type: 'dev' };
 saveJsonFile('yasmin.json', data);
 ```
 
-## 🌐 `fetchJson(url, options?): Promise<any>`
+### 🌐 `fetchJson(url, options?): Promise<any>`
 
 Loads and parses a JSON from a remote URL using the Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
 
-### 📥 Parameters
+#### 📥 Parameters
 
 * `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
 * `options` *(object)* *(optional)*:
@@ -134,7 +208,7 @@ Loads and parses a JSON from a remote URL using the Fetch API, with support for
   * `headers` *(object)*: Additional headers to include in the request.
   * `body` *(object)*: Request body. If the value is a plain object, it will be automatically stringified as JSON.
 
-#### `signal` (`AbortSignal` | `null`) — *optional*
+##### `signal` (`AbortSignal` | `null`) — *optional*
 
 Custom abort signal. If set:
 
@@ -142,21 +216,21 @@ Custom abort signal. If set:
 * Retry logic is **disabled**
 * Abortion is handled externally
 
-### 📤 Returns
+#### 📤 Returns
 
 * `Promise<any>`: Resolves with the parsed JSON data.
 
-### ⚠️ Throws
+#### ⚠️ Throws
 
 * `Error` if the fetch fails or exceeds the timeout
 * `Error` if the response is not `application/json`
 * `Error` if the result is not a plain JSON object
 
-## 🧠 Tip
+#### 🧠 Tip
 
 If you pass your own `signal`, this disables both `timeout` and `retries`. Use it when you're managing cancellation manually (e.g. in UI components or async workflows).
 
-### 🧪 Example
+#### 🧪 Example
 
 ```js
 const controller = new AbortController();
@@ -241,3 +315,95 @@ getHtmlElPadding(el: Element): HtmlElBoxSides
 
 * `el`: The target DOM element.
 * **Returns**: Padding values for all sides and summed horizontal (`x`) and vertical (`y`) values.
+
+---
+
+### 📄 `installWindowHiddenScript`
+
+Automatically toggles CSS classes on a given element based on the browser window or tab **visibility** and **focus** state.
+
+Perfect for UI states like dimming, pausing animations, or showing "away" statuses.
+
+#### 🧠 Features
+
+* ✅ Adds or removes custom CSS classes depending on page visibility or focus
+* ✅ Supports modern and legacy browsers (including IE9)
+* ✅ Automatically dispatches an initial state check on load
+* ✅ Allows custom **callbacks** for visibility changes (`onVisible`, `onHidden`)
+* ✅ Returns a cleanup function to remove all listeners
+
+#### 🧪 Usage
+
+```js
+import { installWindowHiddenScript } from 'tiny-essentials';
+
+const uninstall = installWindowHiddenScript({
+  element: document.getElementById('app'),
+  hiddenClass: 'is-hidden',
+  visibleClass: 'is-visible',
+  onVisible: () => console.log('Window is now visible'),
+  onHidden: () => console.log('Window is now hidden'),
+});
+
+// To remove all listeners later
+uninstall();
+```
+
+#### ⚙️ Options
+
+| Option         | Type          | Default           | Description                                                       |
+| -------------- | ------------- | ----------------- | ----------------------------------------------------------------- |
+| `element`      | `HTMLElement` | `document.body`   | The element to which the visibility classes will be applied       |
+| `hiddenClass`  | `string`      | `'windowHidden'`  | Class name to apply when the window is **not visible or blurred** |
+| `visibleClass` | `string`      | `'windowVisible'` | Class name to apply when the window is **visible or focused**     |
+| `onVisible`    | `() => void`  | `undefined`       | Optional callback fired when the window becomes visible           |
+| `onHidden`     | `() => void`  | `undefined`       | Optional callback fired when the window becomes hidden            |
+
+#### 🔄 Return Value
+
+```ts
+() => void
+```
+
+Returns a function that, when called, will:
+
+* 🧹 Remove all attached event listeners
+* ❌ Remove both visibility classes from the target element
+
+#### 🚦 Events Supported
+
+The script handles multiple events depending on browser support:
+
+* `visibilitychange`, `webkitvisibilitychange`, `mozvisibilitychange`, `msvisibilitychange`
+* `focus`, `blur`, `focusin`, `focusout`
+* `pageshow`, `pagehide`
+* IE fallback: `onfocusin`, `onfocusout`
+
+#### 🔍 Initial Trigger
+
+Immediately after installation, the script simulates a `focus` or `blur` event based on the current visibility state to **ensure the classes and callbacks are applied from the start**.
+
+#### 🧯 Uninstalling
+
+Don’t forget to call the returned function if you dynamically load/unload components or scripts:
+
+```js
+const stopWatching = installWindowHiddenScript(...);
+stopWatching(); // later
+```
+
+#### 🎨 CSS Example
+
+```css
+.windowVisible {
+  opacity: 1;
+  pointer-events: auto;
+  transition: opacity 0.3s ease;
+}
+
+.windowHidden {
+  opacity: 0.4;
+  pointer-events: none;
+  transition: opacity 0.3s ease;
+}
+```