tiny-essentials 1.28.19 → 1.29.0

package/docs/v1/libs/sw/service/plugins/GlobBypassPlugin.md

@@ -0,0 +1,229 @@
+# 🧩 GlobBypassPlugin
+
+A `TinyServiceWorkerEngine` plugin that skips router validation for requests whose pathname matches a set of glob patterns.
+
+---
+
+## 📖 Table of Contents
+
+- [What is this?](#-what-is-this)
+- [Why would I use it?](#-why-would-i-use-it)
+- [Quick Start](#-quick-start)
+- [How It Works](#-how-it-works)
+- [Daily Recipes](#-daily-recipes)
+- [Security Notes](#-security-notes)
+- [FAQ](#-faq)
+
+---
+
+## 🤔 What is this?
+
+`GlobBypassPlugin` is a plugin for **`TinyServiceWorkerEngine`**.
+
+A service worker engine usually intercepts every `fetch` event and runs a
+**router validation** pipeline before letting the request continue. That is
+great for your application routes, but it is annoying for static assets,
+generated files, or anything that should simply pass through untouched.
+
+This plugin lets you declare **glob patterns**. When an intercepted request
+matches one of those patterns, the plugin marks the response as:
+
+```js
+response.continueCheck = false; // stop the validation pipeline
+response.needValidation = false; // do not require validation
+```
+
+In other words: **the request is short-circuited and allowed through.**
+
+---
+
+## 🎯 Why would I use it?
+
+| Scenario | Without this plugin | With this plugin |
+| --- | --- | --- |
+| Dev server serving `*.css` | Router validates every asset | CSS bypasses the router |
+| Source maps in development | 404 noise in the console | Ignored via `exclude` |
+| Third-party CDN requests | Validated and rejected | Skipped with `sameOriginOnly` |
+| Production safety | Bypass rules leak to prod | Blocked with `devOnly: true` |
+
+---
+
+## 🚀 Quick Start
+
+```js
+import TinyServiceWorkerEngine from 'tiny-essentials/libs/sw/service/TinyServiceWorkerEngine';
+import GlobBypassPlugin from 'tiny-essentials/libs/sw/service/plugins/GlobBypassPlugin';
+
+const engine = new TinyServiceWorkerEngine();
+
+// Register the plugin on the engine.
+engine.installPlugin(GlobBypassPlugin, {
+  patterns: ['**/*.css', '**/*.js', '**/*.{png,jpg,svg}'],
+  exclude: [],
+  sameOriginOnly: true,
+  devOnly: false,
+});
+```
+
+That is the whole setup. Every request whose pathname matches `**/*.css`,
+`**/*.js`, or one of the image extensions now bypasses router validation.
+
+---
+
+## ⚙️ Options Reference
+
+The second argument of the plugin is the options object.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `patterns` | `string[]` | ✅ **Yes** | — | Glob patterns that trigger the bypass. |
+| `exclude` | `string[]` | ❌ No | `[]` | Glob patterns that cancel the bypass. |
+| `sameOriginOnly` | `boolean` | ❌ No | `true` | When `true`, only same-origin requests are evaluated. |
+| `devOnly` | `boolean` | ❌ No | `false` | When `true`, the bypass is only registered. |
+
+### `patterns` — required
+
+An array of glob strings. Each entry is compiled once with `compileGlobRegExp()`
+and registered on the engine.
+
+```js
+{ patterns: ['**/*.css', '**/*.map'] }
+```
+
+### `exclude` — optional
+
+An array of glob strings. Exclusion patterns are compiled **once**, before the
+request loop, and tested against `fetchObj.url.pathname`.
+
+```js
+{ patterns: ['**/*.js'], exclude: ['**/no.js', '**/nope.js'] }
+```
+
+### `sameOriginOnly` — optional, default `true`
+
+When `true`, cross-origin requests are ignored and fall back to the normal
+router validation.
+
+```js
+{ patterns: ['**/*.css'], sameOriginOnly: false } // also bypass CDN requests
+```
+
+### `devOnly` — optional, default `false`
+
+When `true`, the plugin registers nothing. Use it to keep development shortcuts out of production.
+
+```js
+{ patterns: ['**/*.map'], devOnly: true }
+```
+
+---
+
+## 🔍 How It Works
+
+```text
+        fetch event
+             │
+             ▼
+  ┌──────────────────────────┐
+  │ Does the pathname match  │
+  │   a `patterns` entry?    │──No──▶ normal router validation
+  └───────────┬──────────────┘
+              │ Yes
+              ▼
+  ┌──────────────────────────┐
+  │ sameOriginOnly is true   │
+  │  AND request is cross-   │──Yes─▶ normal router validation
+  │        origin?           │
+  └───────────┬──────────────┘
+              │ No
+              ▼
+  ┌──────────────────────────┐
+  │ Does the pathname match  │
+  │   an `exclude` entry?    │──Yes─▶ normal router validation
+  └───────────┬──────────────┘
+              │ No
+              ▼
+  ┌──────────────────────────┐
+  │  continueCheck  = false  │
+  │  needValidation = false  │
+  │  code           = 200    │
+  └──────────────────────────┘
+```
+
+**Step by step:**
+
+1. The plugin validates the engine instance and every option.
+2. If `devOnly` is `true` and the environment is not a dev build, it stops here.
+3. All `exclude` patterns are compiled into `RegExp` objects **once** (performance).
+4. For each entry in `patterns`, the plugin calls
+   `engine.addFetchRegExpListener(regex.source, callback)`.
+5. Inside the callback, the origin and exclusion checks run per request.
+6. If nothing stopped the request, the response is short-circuited.
+
+---
+
+## 🍳 Daily Recipes
+
+### 1. Bypass a single file
+
+```js
+{ patterns: ['**/sw.js'] }
+```
+
+### 2. Bypass by file extension
+
+```js
+{ patterns: ['**/*.{css,scss,less}'] }
+```
+
+### 3. Bypass everything except the service worker
+
+```js
+{ patterns: ['**'], exclude: ['**/sw.js'] }
+```
+
+### 4. Development-only bypass
+
+```js
+{ patterns: ['**/*.map'], devOnly: true }
+```
+
+### 5. Include cross-origin requests
+
+```js
+{ patterns: ['**/api/**'], sameOriginOnly: false }
+```
+
+### 6. Multiple independent rules
+
+Register the plugin more than once with different option sets:
+
+```js
+engine.use(GlobBypassPlugin, { patterns: ['**/*.css'] });
+engine.use(GlobBypassPlugin, { patterns: ['**/*.map'], devOnly: true });
+```
+
+---
+
+## 🔐 Security Notes
+
+- **`sameOriginOnly` defaults to `true` on purpose.** Setting it to `false`
+  means cross-origin requests can also skip validation. Only do this when you
+  fully control the target origins.
+- **`devOnly` is your safety net.** Any bypass that exists only to make
+  development easier should use `devOnly: true`.
+- **`exclude` is evaluated per request, not per pattern.** A typo in an
+  exclusion pattern fails silently: the request is bypassed instead of blocked.
+
+---
+
+## ❓ FAQ
+
+**Does this plugin download anything?**
+No. It only registers listeners on the engine.
+
+**Can I register it twice?**
+Yes. Each call creates an independent rule set.
+
+**What happens if `patterns` is an empty array?**
+Nothing is registered. No error is thrown.

package/docs/v1/libs/sw/service/plugins/GlobCachePlugin.md

@@ -0,0 +1,91 @@
+# 🚀 GlobCachePlugin Documentation
+
+Welcome to the official documentation for the **GlobCachePlugin**. This plugin is designed for the `TinyServiceWorkerEngine` ecosystem. It provides an easy and efficient way to manage runtime caching by using **glob patterns** (like `**/*.js`) instead of writing complex Regular Expressions manually.
+
+## 📝 Overview
+
+The `GlobCachePlugin` intercepts network requests that match your specified patterns. It checks if a valid response is already stored in the `CacheStorage`.
+- If a match is found in the cache, the plugin serves the cached response immediately.
+- If no match is found, it fetches the resource from the network and automatically saves it to the cache for future use.
+
+---
+
+## ✨ Key Features
+
+*   🔍 **Glob Pattern Matching**: Use simple patterns to include or exclude specific files.
+*   🛡️ **Exclusion Rules**: Easily prevent specific files (like `sw.js` or API calls) from being cached.
+*   🌐 **Origin Control**: Option to restrict caching strictly to the same origin to improve security.
+*   ⚡ **Automated Caching**: Automatically handles `cache.put()` for successful `GET` requests (Status 200).
+*   🛠️ **Non-Blocking**: If a caching error occurs, the plugin logs the error but allows the engine to continue operating to prevent site breakage.
+
+---
+
+## 📦 Configuration (Options)
+
+When initializing the plugin, you must provide a configuration object. Below is the detailed breakdown of the `GlobCacheOptions` type.
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :---: | :---: | :--- |
+| `patterns` | `string[]` | **Yes** | N/A | An array of glob patterns to include (e.g., `['**/*.png']`). |
+| `cacheName` | `string` | **Yes** | N/A | The unique name for the `CacheStorage` bucket. |
+| `exclude` | `string[]` | No | `[]` | An array of glob patterns to ignore (e.g., `['**/api/**']`). |
+| `sameOriginOnly` | `boolean` | No | `true` | If `true`, only requests from the same origin will be cached. |
+
+---
+
+## 🚀 Daily Usage Guide
+
+### 1. Basic Implementation
+To use the plugin, pass your `TinyServiceWorkerEngine` instance and the configuration object into the plugin function.
+
+```javascript
+import GlobCachePlugin from 'tiny-essentials/libs/sw/service/plugins/GlobCachePlugin';
+
+// Example configuration
+const cacheOptions = {
+  patterns: ['**/*.{js,css,png,jpg}'], // Cache scripts, styles, and images
+  cacheName: 'static-assets-v1',
+  exclude: ['**/vendor/**'], // Do not cache anything in the vendor folder
+  sameOriginOnly: true       // Only cache files from our own domain
+};
+
+// Registering the plugin within your engine setup
+engineInstance.installPlugin(GlobCachePlugin, cacheOptions);
+```
+
+### 2. Advanced Filtering Example
+If you want to cache everything except for specific configuration files and ensure you are only caching assets from your own domain:
+
+```javascript
+import GlobCachePlugin from 'tiny-essentials/libs/sw/service/plugins/GlobCachePlugin';
+
+const advancedOptions = {
+  patterns: ['**/*'], 
+  exclude: ['**/config.json', '**/auth/**'],
+  cacheName: 'app-cache',
+  sameOriginOnly: true
+};
+
+engineInstance.installPlugin(GlobCachePlugin, advancedOptions);
+```
+
+---
+
+## ⚠️ Technical Constraints & Logic
+
+To ensure the stability of your application, please keep the following technical behaviors in mind:
+
+1.  **Method Restriction**: The plugin only caches `GET` requests. It will not attempt to cache `POST`, `PUT`, or `DELETE` requests.
+2.  **Status Requirement**: Only responses with a `status === 200` are stored in the cache.
+3.  **Response Cloning**: The plugin uses `.clone()` when saving to the cache. This is necessary because a response body can only be read once.
+4.  **Error Handling**: If `caches.open` or `cache.match` fails, an error is logged to the console: `[GlobCachePlugin] Error during cache operation...`. The request will then proceed to the network normally.
+
+---
+
+## 🛠 Troubleshooting
+
+| Issue | Possible Cause | Solution |
+| :--- | :--- | :--- |
+| **Files not caching** | Patterns might be incorrect. | Verify your glob syntax (e.g., use `**/*` for recursive matching). |
+| **TypeError on startup** | Missing `cacheName` or `patterns`. | Ensure all required properties are present in your options object. |
+| **CORS Errors** | `sameOriginOnly` is `true`. | If you need to cache external assets (like Google Fonts), set `sameOriginOnly: false`. |

package/docs/v1/libs/sw/service/plugins/Ping.md

@@ -0,0 +1,36 @@
+# 📡 TinyPingPwa
+
+A lightweight utility to verify that the `TinyServiceWorkerEngine` is communicating correctly.
+
+### 🚀 Quick Usage
+
+1.  **Register the plugin:**
+    ```javascript
+    import TinyPingPwa from 'tiny-essentials/libs/sw/service/plugins/Ping';
+    engineInstance.installPlugin(TinyPingPwa);
+    ```
+
+2.  **Send a test message:**
+    ```javascript
+    import TinyServiceWorker from 'tiny-essentials/libs/sw/browser/TinyServiceWorker';
+
+    const swManager = new TinyServiceWorker({
+        id: 'web-manager',
+        swUrl: '/sw.js',
+        version: '1.0.0',
+        debugMode: import.meta.env.DEV,
+        useLogColors: true,
+    });
+
+    swManager.on('pong', ({ data }) => console.log(data.msg));
+
+    swManager.register({ type: import.meta.env.DEV ? 'module' : 'classic' }).then(() => {
+        swManager.emit('ping');
+    });
+    ```
+
+### ✅ Expected Result
+
+When a `'ping'` is sent, the plugin will respond with:
+*   **Type:** `'pong'`
+*   **Data:** `{ msg: 'mio! :3' }`

package/docs/v1/libs/sw/service/plugins/TabManager.md

@@ -0,0 +1,64 @@
+# 🚀 TabManager Plugin Documentation
+
+The **TabManager Plugin** is a robust synchronization system designed for Progressive Web Apps (PWAs). It allows your application to maintain a "Single Source of Truth" regarding all open browser tabs. By leveraging a **Service Worker** as a central coordinator, it enables real-time communication, data persistence via **IndexedDB**, and advanced control over tab lifecycles.
+
+---
+
+## 🏗️ Architecture Overview
+
+The system operates using a **Client-Server model** where the "Server" is the Service Worker.
+
+1.  **The Brain (Service Worker Side):** 🧠
+    *   Located in: `tiny-essentials/libs/sw/service/plugins/TabManager`
+    *   **Responsibility:** Maintains the master registry of all tabs, persists data to `IndexedDB`, handles "ghost" tab reconciliation, and broadcasts updates to all connected clients.
+2.  **The Controller (Client/Main Thread Side):** 🎮
+    *   Located in: `tiny-essentials/libs/sw/browser/plugins/TabManager`
+    *   **Responsibility:** Automatically reports the tab's status (URL, Title, Focus) to the SW, listens for lifecycle events (closing, navigating), and provides a clean API for the developer to interact with other tabs.
+
+---
+
+## 🛠️ Getting Started
+
+### 1. Installation (Service Worker)
+To enable the TabManager, you must install the plugin into your `TinyServiceWorkerEngine`.
+
+```javascript
+import TinyTabManagerPlugin from 'tiny-essentials/libs/sw/service/plugins/TabManager';
+
+// Inside your Service Worker initialization
+swManager.installPlugin(TinyTabManagerPlugin);
+```
+
+### 2. Initialization (Main Thread)
+In your web application (the client side), you need to connect to the Service Worker using the `TinySwTabsLayer`.
+
+```javascript
+import TinyTabManagerPlugin from 'tiny-essentials/libs/sw/browser/plugins/TabManager';
+
+// Assuming 'sw' is your TinyServiceWorker instance
+const tabManager = swManager.installPlugin(TinyTabManagerPlugin);
+
+// Now you can use the tabManager instance to control tabs!
+```
+
+---
+
+## ⚙️ Technical Deep-Dive (For Developers)
+
+### 🛡️ Permission System
+To ensure user privacy and control, the plugin implements a granular permission system. When a tab registers itself, it can opt-out of certain management actions. These permissions are stored per `clientId`.
+
+*   **`allowFocusTracking`**: If `false`, the Service Worker will not update the `isFocused` status for this tab.
+*   **`allowTabClosing`**: If `false`, remote commands to close this tab (via `tab:close_single` or `tab:close_multiple`) will be rejected with a "Permission denied" reason.
+
+### 🔄 Ghost Tab Reconciliation
+One of the biggest challenges in PWA development is when a user closes a tab or the browser crashes, preventing the `unregister` message from being sent.
+
+**How this plugin solves it:**
+The Service Worker performs a **Reconciliation** every time a new tab registers or an unregistration occurs. It uses `sw.clients.matchAll()` to compare the "Master Registry" in `IndexedDB` against the *actual* active browser clients. If a tab exists in the registry but is no longer a valid browser client, it is automatically purged.
+
+### 📦 Persistence Layer
+The plugin uses **IndexedDB** (`TinySwTabsDB`) to ensure that the tab registry survives page reloads and browser restarts. This ensures that even if the Service Worker is woken up after a period of inactivity, it still knows which tabs were previously active.
+
+### 🚦 Concurrency Management
+To prevent race conditions (e.g., two tabs trying to update the registry at the exact same millisecond), the Service Worker uses a `TinyPromiseQueue`. All database operations are queued to ensure data integrity.

package/docs/v1/libs/sw/service/plugins/ViteFileDetector.md

@@ -0,0 +1,92 @@
+# 🚀 Vite File Detector Plugin
+
+A specialized plugin for the `TinyServiceWorkerEngine` designed to identify and bypass Vite-specific network requests. This ensures that during development, Vite's internal processes (like Hot Module Replacement) are not interrupted by the Service Worker.
+
+## 📝 Overview
+
+When developing with **Vite**, the development server uses specific URL patterns to handle module loading and Hot Module Replacement (HMR). If a Service Worker attempts to intercept and validate these requests, it can break the development experience.
+
+The `ViteFileDetectorPlugin` solves this by listening to all fetch events and telling the engine to "bypass" any URL that matches Vite's internal patterns.
+
+---
+
+## 🛠 Configuration
+
+When you install the plugin, you can pass an optional configuration object. If no options are provided, it uses the `DEFAULT_OPTIONS`.
+
+### `ViteFileDetectorOptions`
+
+| Property | Type | Description | Default Value |
+| :--- | :--- | :--- | :--- |
+| `paths` | `(string \| RegExp)[]` | An array of strings or Regular Expressions. Any URL matching these patterns will be bypassed. | `['/@vite', '/@react', '/node_modules']` |
+| `srcPath` | `string` | The base path for your source directory. | `'/src'` |
+| `manifestPath` | `string` | The path to your application's manifest file. | `'/manifest.json'` |
+| `maxCachedUrls` | `number` | Maximum amount of detected URLs kept in the persistent cache. When the limit is reached, the oldest entries are evicted before the new one is written. Use `Infinity` to keep every URL forever. | `1000` |
+
+> **Note:** `srcPath` and `manifestPath` are appended to `paths` internally. The final matching list is always `[...paths, srcPath, manifestPath]`.
+
+### Validation
+
+The configuration is validated while the plugin is installed. Invalid values throw immediately instead of failing silently during a fetch event.
+
+| Thrown Error | Condition |
+| :--- | :--- |
+| `TypeError` | The plugin was installed without a valid `TinyServiceWorkerEngine` instance. |
+| `TypeError` | `paths` is not an array. |
+| `TypeError` | An item inside `paths` (or `srcPath` / `manifestPath`) is neither a `string` nor a `RegExp`. |
+| `TypeError` | `maxCachedUrls` is not a number. |
+| `RangeError` | `maxCachedUrls` is not a positive integer and is not `Infinity`. |
+
+### 🗃️ Persistent Cache
+
+Every detected URL is stored in a `TinySetMapDatabase` set named `logged-urls`. This keeps the "File detected" log at one entry per URL, even after the Service Worker restarts.
+
+*   **Deduplication:** a URL that is already cached is skipped and produces no new log.
+*   **Eviction:** before a new URL is written, the oldest entries are removed until the cache has room for it, so the cache never holds more than `maxCachedUrls` entries.
+*   **Serialized writes:** all cache mutations run through an internal promise queue. This prevents two detections that resolve in the same tick from reading the same `size` and pushing the cache above `maxCachedUrls`.
+*   **Isolation:** the whole detector, including the cache, only runs in development mode (`import.meta.env.DEV`).
+
+---
+
+## 🚀 Daily Usage
+
+### 1. Installation
+
+To use the plugin, you must have an active instance of `TinyServiceWorkerEngine`. You install the plugin using the engine's installation method.
+
+```javascript
+import TinyServiceWorkerEngine from 'tiny-essentials/libs/sw/service/TinyServiceWorkerEngine';
+import ViteFileDetectorPlugin from 'tiny-essentials/libs/sw/service/plugins/ViteFileDetectorPlugin';
+
+// 1. Initialize your engine
+const engine = new TinyServiceWorkerEngine();
+
+// 2. Install the Vite Detector Plugin
+// You can pass custom paths if your project structure is non-standard
+engine.installPlugin(ViteFileDetectorPlugin, {
+  paths: ['/@vite', '/@my-custom-tool'],
+  srcPath: '/app/src',
+  manifestPath: '/public/manifest.json',
+  maxCachedUrls: 500
+});
+```
+
+### 2. Typical Workflow
+
+1.  **Development Mode:** The plugin only activates if `import.meta.env.DEV` is true. This means it will **not** add overhead to your production build.
+2.  **Request Interception:** When the browser requests a file (e.g., `/@vite/client`), the plugin checks the URL against your `paths`.
+3.  **Bypass Execution:** If a match is found, the plugin instructs the engine to:
+    *   Stop further checks (`continueCheck = false`).
+    *   Skip validation (`needValidation = false`).
+    *   Return a successful status (`code = 200`).
+4.  **Cache Lookup:** The URL is compared against the persistent cache. If it was already detected before, the workflow stops here.
+5.  **Cache Write:** The oldest entries are evicted when the limit is reached, the URL is stored, and the message `File detected: <url>` is logged with the `warn` level. Failures inside this step are logged with the `error` level and never break the response.
+
+---
+
+## ⚠️ Important Notes
+
+*   **Environment Specific:** This plugin is strictly for **Development environments**. It uses `import.meta.env.DEV` to ensure production performance is not affected.
+*   **Path Matching:** It is recommended to use specific paths to avoid accidentally bypassing important application files.
+*   **Cache Size:** `maxCachedUrls` only controls how many URLs are remembered for logging. A low value means the same URL can be logged again after it is evicted. Use `Infinity` if the log must never repeat.
+*   **Log Levels:** Successful detections use the `warn` level, while cache failures use the `error` level. Filter by these levels if the console becomes noisy.