tiny-essentials 1.28.19 → 1.29.0

package/docs/v1/webTemplates/media/MediaValidator/v1/Browser.md

@@ -0,0 +1,123 @@
+# 🛡️ MediaShield: Robust Media Validation Library
+
+Welcome to **MediaShield**! This library is designed to provide security, multi-layered validation for media files (Images, Audio, and Video). 
+
+When building modern web applications, users often upload files. A common security risk is "File Spoofing," where a malicious actor renames a dangerous script (like `.exe` or `.js`) to a harmless extension (like `.jpg`). **MediaShield** prevents this by looking *inside* the file, not just at the filename.
+
+---
+
+## 🚀 Core Concept: The Two-Layer Defense
+
+MediaShield operates on a "Defense in Depth" principle. We don't just trust the file extension; we verify the actual data.
+
+1.  **Layer 1: Magic Number Validation (The Identity Check) 🔍**
+    We inspect the "Magic Numbers" (the first few bytes of a file). This tells us what the file *actually* is, regardless of its name.
+2.  **Layer 2: Structural Validation (The Integrity Check) 🏗️**
+    Once we know the identity, we ask the browser to attempt to decode the file. If the browser cannot read the internal structure (like height/width for images or duration for video), the file is considered corrupted or malicious.
+
+---
+
+## 📖 API Reference
+
+### 1. `validateMagicNumbers`
+The first line of defense. It checks the binary signature of the file.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `inputData` | `Buffer \| Uint8Array \| Blob` | The raw binary data of the file. |
+| `expectedType` | `'image' \| 'audio' \| 'video'` | The category you are expecting. |
+| `fileTypeFromBuffer` | `Function` | A callback function that identifies MIME types from buffers. |
+
+**Returns:** `Promise<string>` (The confirmed MIME type).
+**Throws:** `Error` if the signature doesn't match the expected category.
+
+---
+
+### 2. `validateImage`
+Deep structural validation specifically for images.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `inputData` | `Blob` | The image file as a Blob. |
+
+**Returns:** `Promise<ValidationResult>`
+*   **On Success:** `{ mimeType, error: null, data: { width, height, format } }`
+*   **On Failure:** `{ mimeType: null, error: "Error message" }`
+
+---
+
+### 3. `validateAudioVideo`
+Deep structural validation for multimedia containers.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `inputData` | `Blob` | The media file as a Blob. |
+| `mimeType` | `string` | The MIME type obtained from `validateMagicNumbers`. |
+
+**Returns:** `Promise<ValidationResult>`
+*   **On Success:** `{ mimeType, error: null, data: { duration } }`
+*   **On Failure:** `{ mimeType: null, error: "Error message" }`
+
+---
+
+## 🛠️ Daily Workflow: How to use it
+
+To use MediaShield in your project, you should follow this logical sequence to ensure security.
+
+### Step-by-Step Implementation Guide
+
+1.  **Step 1: Capture the File** 📥
+    Get the file from an `<input type="file">` element.
+2.  **Step 2: Run Magic Number Check** 🛡️
+    Call `validateMagicNumbers`. If this fails, stop immediately. The file is a spoof.
+3.  **Step 3: Perform Deep Validation** 🏗️
+    Based on the result of Step 2, call either `validateImage` or `validateAudioVideo`.
+4.  **Step 4: Proceed or Reject** ✅
+    If both layers pass, the file is safe to upload to your server.
+
+### 💻 Code Example
+
+Here is how you would implement the full pipeline in a real-world scenario:
+
+```javascript
+import { validateMagicNumbers, validateImage, validateAudioVideo } from 'tiny-essentials/webTemplates/media/MediaValidator/v1/Browser';
+
+async function handleFileUpload(fileBlob) {
+  try {
+    const fileDetector = async () => ({ mime: fileBlob.type });
+
+    // --- LAYER 1: Identity Check ---
+    const confirmedMime = await validateMagicNumbers({
+      inputData: fileBlob,
+      expectedType: 'image',
+      fileTypeFromBuffer: fileDetector
+    });
+    console.log(`✅ Identity confirmed: ${confirmedMime}`);
+
+    // --- LAYER 2: Structural Check ---
+    const validation = await validateImage({
+      inputData: fileBlob
+    });
+
+    if (validation.error) {
+      throw new Error(`❌ Structural validation failed: ${validation.error}`);
+    }
+
+    console.log(`🎉 File is safe! Dimensions: ${validation.data.width}x${validation.data.height}`);
+    return validation.data;
+
+  } catch (error) {
+    console.error(`🚨 Security/Validation Error: ${error.message}`);
+  }
+}
+
+// Usage
+const fileInput = document.querySelector('input[type="file"]');
+ fileInput.addEventListener('change', (e) => handleFileUpload(e.target.files[0]));
+```
+
+---
+
+## ⚠️ Security Notes
+*   **Always** perform Layer 1 validation on the client side for immediate user feedback.
+*   **Crucial:** Client-side validation is for UX and basic security. Always perform a second round of validation on your **Server/Backend** before saving files to permanent storage.

package/docs/v1/webTemplates/media/MediaValidator/v1/Node.md

@@ -0,0 +1,136 @@
+# 🛡️ Secure Media Validator
+
+A multi-layered validation toolkit designed to ensure file integrity and prevent security exploits such as **MIME-spoofing** (where a malicious file is disguised with a fake extension).
+
+## 📋 Overview
+
+When handling file uploads, simply checking a file extension (like `.jpg`) is not enough. An attacker can rename a malicious script to `image.jpg`. This project implements a two-layer defense strategy:
+
+1.  **Layer 1: Fast Binary Validation (Magic Numbers) 🔍**
+    Checks the actual file header (the first few bytes) to see if the internal signature matches the expected category.
+2.  **Layer 2: Deep Structural Validation 🏗️**
+    Forces the system to parse the internal structure of the file (metadata/frames) to ensure the file isn't just a valid header followed by corrupted or malicious data.
+
+---
+
+## 📦 Dependencies
+
+To use this toolkit, you must have the following packages installed in your project:
+
+*   `file-type`: For magic number detection.
+*   `sharp`: For deep image structural analysis.
+*   `music-metadata`: For deep audio/video container parsing.
+
+```bash
+npm install file-type sharp music-metadata
+```
+
+---
+
+## 🛠️ API Reference
+
+### 1. Layer 1: `validateMagicNumbers` 🔍
+
+This is your first line of defense. It is extremely fast because it only reads the beginning of the file.
+
+**Purpose:** To verify that the file's internal "signature" matches the category you expect (image, audio, or video).
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `buffer` | `Buffer` | The raw binary data of the uploaded file. |
+| `expectedType` | `'image' \| 'audio' \| 'video'` | The category you are expecting. |
+| `fileTypeFromBuffer` | `Function` | The `fileTypeFromBuffer` function from the `file-type` package. |
+
+**Returns:** `Promise<string>` (The confirmed MIME type).
+**Throws:** `Error` if the signature is unknown or does not match the `expectedType`.
+
+---
+
+### 2. Layer 2 (Images): `validateImage` 🖼️
+
+Once the magic numbers are confirmed, use this to inspect the image's internal structure.
+
+**Purpose:** Uses the `sharp` engine to parse the image. This detects "Polyglot" files (files that are valid in two different formats) or files with corrupted headers designed to exploit image parsers.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `buffer` | `Buffer` | The raw image buffer. |
+| `Sharp` | `SharpConstructor` | The `sharp` constructor. |
+
+**Returns:** `Promise<ValidationResult<{ data: Sharp, metadata: SharpMetadata }>>`
+
+---
+
+### 3. Layer 2 (Audio/Video): `validateAudioVideo` 🎵
+
+For media files, we need to ensure the container (like MP3 or MP4) is actually intact.
+
+**Purpose:** Uses `music-metadata` to parse the container. It ensures the file contains valid audio/video streams and a valid duration.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `buffer` | `Buffer` | The raw media buffer. |
+| `parseBuffer` | `Function` | The `parseBuffer` function from `music-metadata`. |
+
+**Returns:** `Promise<ValidationResult<IAudioMetadata>>`
+
+---
+
+## 🚀 Implementation Guide: Daily Workflow
+
+To implement this in a real-world upload service, you should follow this sequential logic. **Do not skip Layer 1**, as Layer 2 is more computationally expensive.
+
+### 🛠️ Step-by-Step Integration
+
+1.  **Receive the file** as a Buffer from your upload middleware (e.g., Multer).
+2.  **Run `validateMagicNumbers`**: If this fails, reject the upload immediately.
+3.  **Branch by Type**:
+    *   If `mimeType` starts with `image/` $\rightarrow$ Call `validateImage`.
+    *   If `mimeType` is `audio/` or `video/` $\rightarrow$ Call `validateAudioVideo`.
+4.  **Handle the Result**: If the `error` property is present in the result, reject the upload and log the security event.
+
+### 💻 Code Example
+
+```javascript
+import { validateMagicNumbers, validateImage } from 'tiny-essentials/webTemplates/media/MediaValidator/v1/Node';
+import fileType from 'file-type';
+import sharp from 'sharp';
+
+async function handleUpload(fileBuffer, userExpectedType) {
+  try {
+    // STEP 1: Fast Check
+    const mimeType = await validateMagicNumbers({
+      buffer: fileBuffer,
+      expectedType: userExpectedType,
+      fileTypeFromBuffer: fileType.fileTypeFromBuffer
+    });
+
+    // STEP 2: Deep Check (if it's an image)
+    if (mimeType.startsWith('image/')) {
+      const result = await validateImage({
+        buffer: fileBuffer,
+        Sharp: sharp
+      });
+
+      if (result.error) {
+        console.error("❌ Image Security Violation:", result.error);
+        return { success: false, message: "Invalid image structure." };
+      }
+
+      console.log("✅ Image is safe and valid:", result.metadata.format);
+      return { success: true, data: result.data };
+    }
+
+    // ... handle audio/video similarly
+    
+  } catch (error) {
+    console.error("🚨 Security Block:", error.message);
+    return { success: false, message: error.message };
+  }
+}
+```
+
+## ⚠️ Security Notes
+
+*   **Error Handling:** The `ValidationResult` object is used to prevent the application from crashing during deep parsing. Always check `if (result.error)` before accessing `result.data`.
+*   **Performance:** Layer 2 functions are CPU-intensive. Always run them in a worker thread or ensure your server has adequate resources if handling high volumes of uploads.

package/docs/v1/webTemplates/multiformats/14.0/IPFSHasher.md

@@ -0,0 +1,310 @@
+# 🧬 IPFS Hasher
+
+> Generate **IPFS Content Identifiers (CIDs)** locally, in pure JavaScript, without running an IPFS node.
+
+---
+
+## 📖 Table of Contents
+
+- [What Is This?](#-what-is-this)
+- [Why Would I Use This?](#-why-would-i-use-this)
+- [Core Concepts (Read This First)](#-core-concepts-read-this-first)
+- [Quick Start](#-quick-start)
+- [API Reference](#-api-reference)
+  - [Class: `IPFSHasher`](#class-ipfshasher)
+  - [`new IPFSHasher(version)`](#new-ipfshasherversion)
+  - [`hasher.generate(data)`](#hashergeneratedata)
+  - [Type: `CIDGenerationResult`](#type-cidgenerationresult)
+- [Choosing Between v0 and v1](#-choosing-between-v0-and-v1)
+- [Error Handling](#-error-handling)
+- [Known Limitations](#-known-limitations)
+- [Project Structure](#-project-structure)
+- [FAQ](#-faq)
+
+---
+
+## 🎯 What Is This?
+
+`IPFSHasher` is a small, dependency-light utility class that turns **raw bytes into an IPFS CID**.
+
+It does **one thing**: it takes a `Uint8Array` and returns a content identifier. That is all.
+
+```text
+  ┌──────────────┐      ┌─────────────────┐      ┌──────────────────────────────┐
+  │  Your bytes  │ ───▶ │  sha2-256 hash  │ ───▶ │  CID string ("bafkrei..." )  │
+  └──────────────┘      └─────────────────┘      └──────────────────────────────┘
+```
+
+**What it does NOT do:**
+
+- ❌ It does **not** connect to the IPFS network.
+- ❌ It does **not** upload, pin, or store anything.
+- ❌ It does **not** require a running daemon.
+
+It is a pure function with a class wrapper. That makes it safe to use in build scripts, CI pipelines, browsers, and serverless functions.
+
+---
+
+## 💡 Why Would I Use This?
+
+| Use case | How this helps |
+| --- | --- |
+| 🗄️ **Content-addressable cache** | Use the CID as a cache key. Identical bytes always produce an identical key. |
+| 📦 **Build artifact verification** | Hash a build output and compare it against a published manifest. |
+| 🔍 **Duplicate detection** | Two files with the same CID have identical content. Guaranteed. |
+| 🌐 **Pre-upload preparation** | Compute the CID before uploading so you can store the reference in a database first. |
+| 🧪 **Testing IPFS integrations** | Assert that your upload code produces the expected CID, without a network. |
+
+---
+
+## 🧠 Core Concepts (Read This First)
+
+If you are new to IPFS, read this section. It will save you hours.
+
+### What is a CID?
+
+A **CID (Content Identifier)** is a self-describing hash. It contains:
+
+```text
+  bafkreiabc123...
+  │  │    │
+  │  │    └── The hash digest itself
+  │  └─────── The codec (how to interpret the bytes)
+  └────────── The version + encoding prefix
+```
+
+Because the metadata is *inside* the string, a CID is portable. Anyone can look at it and know how to verify it.
+
+### The three pieces
+
+| Piece | Meaning | Values used here |
+| --- | --- | --- |
+| **Version** | The CID format version. | `v0` or `v1` |
+| **Codec** | How to interpret the bytes. | `dag-pb` (`0x70`) or `raw` (`0x55`) |
+| **Hash** | The digest algorithm. | `sha2-256` |
+
+### The critical rule
+
+> ⚠️ **The same bytes produce different CIDs in v0 and v1.**
+>
+> This is not a bug. It is by design. v0 is locked to the `dag-pb` codec; v1 lets you choose. Different codec means a different CID.
+
+---
+
+## 🚀 Quick Start
+
+```javascript
+import { readFile } from 'node:fs/promises';
+import IPFSHasher from 'tiny-essentials/webTemplates/multiformats/14.0/IPFSHasher';
+
+// 1. Read some bytes. A Buffer IS a Uint8Array, so this works directly.
+const bytes = await readFile('./hello.txt');
+
+// 2. Create a hasher. Defaults to CIDv1.
+const hasher = new IPFSHasher('v1');
+
+// 3. Generate the CID.
+const result = await hasher.generate(bytes);
+
+console.log(result.cidString); // "bafkreifz..."
+console.log(result.version);   // "v1"
+console.log(result.codec);     // 85
+```
+
+**Expected output:**
+
+```text
+bafkreieq5jui4j25lacwomsqgvn7mq3d3h5c5c5c5c5c5c5c5c5c5c5c5c5
+v1
+85
+```
+
+---
+
+## 📚 API Reference
+
+### Class: `IPFSHasher`
+
+A stateless CID generator. Create one instance per version and reuse it.
+
+> 💡 **Why a class instead of a function?**
+> The version is the only piece of state. Storing it in a private field (`#version`) means you cannot accidentally mutate it from the outside. The class is immutable after construction.
+
+---
+
+### `new IPFSHasher(version)`
+
+Creates a new hasher.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `version` | `'v0' \| 'v1'` | `'v1'` | The CID version to generate. |
+
+**Throws:** `TypeError` if `version` is not `'v0'` or `'v1'`.
+
+```javascript
+const v1 = new IPFSHasher();       // Defaults to 'v1'
+const v0 = new IPFSHasher('v0');   // Explicit
+
+new IPFSHasher('v2');
+// TypeError: Invalid CID version. Use "v0" or "v1".
+```
+
+---
+
+### `hasher.generate(data)`
+
+Generates a CID from raw bytes.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `data` | `Uint8Array` | The raw bytes to hash. |
+
+**Returns:** `Promise<CIDGenerationResult>`
+
+**Throws:** `TypeError` if `data` is not a `Uint8Array`.
+
+```javascript
+const hasher = new IPFSHasher('v1');
+const result = await hasher.generate(new Uint8Array([1, 2, 3]));
+```
+
+> ⚠️ **`Buffer` works, `ArrayBuffer` does not.**
+> `Buffer` extends `Uint8Array`, so it passes the check. A raw `ArrayBuffer` does **not**. Wrap it first:
+>
+> ```javascript
+> const bytes = new Uint8Array(arrayBuffer);
+> ```
+
+---
+
+### Type: `CIDGenerationResult`
+
+The object resolved by `generate()`.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `cidString` | `string` | The string representation of the CID. |
+| `version` | `'v0' \| 'v1'` | The CID version that was generated. |
+| `hashAlgorithm` | `'sha256'` | The algorithm used for hashing. |
+| `codec` | `number` | The multicodec code of the content. |
+
+**Codec reference:**
+
+| Constant | Value | Used by |
+| --- | --- | --- |
+| `CODEC_DAG_PB` | `0x70` (`112`) | Always used by v0. |
+| `CODEC_RAW` | `0x55` (`85`) | Used by v1 in this project. |
+
+---
+
+## ⚖️ Choosing Between v0 and v1
+
+| | **CIDv0** | **CIDv1** |
+| --- | --- | --- |
+| **Prefix** | `Qm...` | `bafkrei...` |
+| **Encoding** | base58btc | base32 (lowercase) |
+| **Codec** | `dag-pb` (locked) | `raw` |
+| **Case sensitive** | Yes | No |
+| **Recommended for new projects** | ❌ No | ✅ **Yes** |
+
+### 👉 Recommendation
+
+**Use `v1` unless you have a specific reason not to.**
+
+Reasons to use `v1`:
+
+- ✅ It is case-insensitive, so it is safe in URLs and file names.
+- ✅ It is future-proof. The codec is explicit.
+- ✅ It is what `ipfs add --cid-version=1` produces.
+
+Reasons to use `v0`:
+
+- You must match a legacy system that only understands `Qm...` addresses.
+
+---
+
+## 🚨 Error Handling
+
+The class throws exactly one error type. Catch it explicitly.
+
+| Condition | Error | Message |
+| --- | --- | --- |
+| Invalid version in constructor | `TypeError` | `Invalid CID version. Use "v0" or "v1".` |
+| Non-`Uint8Array` in `generate()` | `TypeError` | `Expected Uint8Array, but received <type>.` |
+
+### ✅ Correct pattern
+
+```javascript
+import IPFSHasher from 'tiny-essentials/webTemplates/multiformats/14.0/IPFSHasher';
+
+try {
+  const hasher = new IPFSHasher('v1');
+  const { cidString } = await hasher.generate(new Uint8Array([1, 2, 3]));
+  console.log(cidString);
+} catch (error) {
+  if (error instanceof TypeError) {
+    console.error('Invalid input:', error.message);
+    process.exit(1);
+  }
+  throw error;
+}
+```
+
+### ❌ Anti-pattern
+
+```javascript
+// Never do this. You lose the stack trace and the error type.
+try {
+  await hasher.generate(data);
+} catch {
+  console.log('Something went wrong');
+}
+```
+
+---
+
+## ⚠️ Known Limitations
+
+Be aware of these before you file a bug report.
+
+| # | Limitation | Impact |
+| --- | --- | --- |
+| 1 | Empty input is allowed. | `new Uint8Array(0)` produces a valid CID. Validate upstream if you need to reject empty files. |
+| 2 | The error message uses `typeof data`. | When `data` is `null`, the message reads `received object`. Cosmetic only. |
+| 3 | Only `sha2-256` is supported. | Hardcoded. Adding `sha2-512` requires a code change. |
+| 4 | `ArrayBuffer` is rejected. | Wrap it: `new Uint8Array(buffer)`. |
+| 5 | No streaming. | The entire file must fit in memory. For files over ~500 MB, use a chunker. |
+| 6 | No network access. | This is intentional. Use `kubo-rpc-client` or `helia` to publish. |
+
+---
+
+## ❓ FAQ
+
+<details>
+<summary><strong>Do I need an IPFS node running?</strong></summary>
+
+No. This library is completely offline. It only does math on bytes.
+
+</details>
+
+<details>
+<summary><strong>Why does my CID start with <code>bafkrei</code> instead of <code>Qm</code>?</strong></summary>
+
+Because you are generating a CIDv1 with the `raw` codec. `Qm...` addresses are always CIDv0 with the `dag-pb` codec. Pass `'v0'` to the constructor if you need the old format.
+
+</details>
+
+<details>
+<summary><strong>Can I hash a file larger than RAM?</strong></summary>
+
+Not with this class. It requires the full `Uint8Array` in memory. For large files, use a chunker such as `ipfs-unixfs-importer`.
+
+</details>
+
+<details>
+<summary><strong>Why does <code>generate()</code> return a Promise if there is no I/O?</strong></summary>
+
+Because `sha256.digest()` from `multiformats` is asynchronous. In a browser, it can delegate to `SubtleCrypto`, which is always async. The API stays consistent across environments.
+
+</details>

package/docs/v1/webTemplates/vite/7.3/plugins/TinyVitePwaPlugin.md

@@ -0,0 +1,131 @@
+# 🚀 Tiny Vite PWA: Developer Documentation
+
+Welcome to the official guide for **`tiny-vite-pwa`**! This plugin is designed to make Progressive Web App integration seamless within a Vite-based project. It handles the "heavy lifting" of PWA requirements so you can focus on building your application.
+
+## 📋 Table of Contents
+1. [Overview](#overview)
+2. [Key Features](#key-features)
+3. [Configuration Guide](#configuration-guide)
+4. [Step-by-Step Implementation](#step-by-step-implementation)
+5. [Developer Experience (Dev vs. Prod)](#developer-experience-dev-vs-prod)
+6. [TypeScript Integration](#typescript-integration)
+
+---
+
+## 🌟 Overview
+`tiny-vite-pwa` is a lightweight Vite plugin that automates three critical PWA pillars:
+1.  **Manifest Management:** Automatically serves and bundles your `manifest.json`.
+2.  **Service Worker Lifecycle:** Bundles your Service Worker (SW) for production and provides Hot Module Replacement (HMR) during development.
+3.  **Automated Injection:** Injects the necessary `<link>` and `<script>` tags into your `index.html` automatically.
+
+---
+
+## ✨ Key Features
+
+*   📦 **Automatic Bundling:** Uses Vite's internal build engine to bundle your Service Worker as an IIFE (Immediately Invoked Function Expression), ensuring compatibility.
+*   ⚡ **Hot Module Replacement (HMR):** When you save changes to your Service Worker file, the plugin detects it and notifies the frontend via a custom event.
+*   🌐 **Global Manifest Access:** Optionally injects your manifest object into the global scope via `define`, making it accessible as `window.__TINY_PWA_MANIFEST__`.
+*   🛡️ **Cache Busting:** Automatically appends version timestamps (`?v=...`) to your manifest and SW in production to prevent stale files.
+*   🎨 **Clear Feedback:** Provides beautiful, color-coded terminal logs to track the plugin's status.
+
+---
+
+## ⚙️ Configuration Guide
+
+When using the plugin, you will pass an options object to `TinyVitePwaPlugin()`. Below are the available properties:
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `manifest` | `Object` | **Required** | The complete Web App Manifest object. |
+| `manifestPath` | `string` | **Required** | The URL path where the manifest should be served (e.g., `'/manifest.json'`). |
+| `srcDir` | `string` | **Required** | The directory where your Service Worker source file is located. |
+| `filename` | `string` | **Required** | The name of your Service Worker file (e.g., `'sw.js'`). |
+| `injectRegister` | `boolean` | `true` | If `true`, the plugin injects the SW registration script into your `<head>`. |
+| `injectManifestToGlobal` | `boolean` | `true` | If `true`, the manifest is available globally via `window.__TINY_PWA_MANIFEST__`. |
+| `swRegistrationOptions` | `Object` | `undefined` | Standard `RegistrationOptions` passed to `navigator.serviceWorker.register`. |
+
+---
+
+## 🛠️ Step-by-Step Implementation
+
+Follow these steps to integrate the plugin into your project.
+
+### 1. Prepare your Manifest
+Create your manifest object. You can keep this in a separate file or define it directly in your config.
+
+### 2. Create your Service Worker
+Place your Service Worker file (e.g., `src/sw.js`) in your source directory.
+
+### 3. Configure Vite
+Update your `vite.config.js` as follows:
+
+```javascript
+import { defineConfig } from 'vite';
+import TinyVitePwaPlugin from 'tiny-essentials/webTemplates/vite/7.3/plugins/TinyVitePwaPlugin';
+
+export default defineConfig({
+  plugins: [
+    TinyVitePwaPlugin({
+      // 1. The Manifest Object
+      manifest: {
+        name: 'My Awesome App',
+        short_name: 'App',
+        start_url: '/',
+        display: 'standalone',
+        background_color: '#ffffff',
+        theme_color: '#000000',
+        icons: [
+          { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+          { src: '/icon-512.png', sizes: '512x512', type: 'image/png' }
+        ]
+      },
+      // 2. Paths and Filenames
+      manifestPath: '/manifest.json',
+      srcDir: 'src',
+      filename: 'sw.js',
+      // 3. Optional: Registration settings
+      swRegistrationOptions: {
+        scope: '/'
+      }
+    })
+  ]
+});
+```
+
+---
+
+## 🔄 Developer Experience (Dev vs. Prod)
+
+The plugin behaves differently depending on whether you are running a development server or building for production.
+
+### 🛠️ In Development (`npm run dev`)
+*   **Manifest:** Served dynamically via a middleware.
+*   **Service Worker:** Served via Vite's transformer, allowing you to use ES6 imports inside your SW.
+*   **HMR:** If you modify your SW file, the plugin sends a `pwa:sw-updated` event to the browser.
+*   **Console:** You will see `[tiny-vite-pwa] [INFO]` logs in your terminal.
+
+### 🚀 In Production (`npm run build`)
+*   **Manifest:** Emitted as a static `.json` file in your `dist` folder.
+*   **Service Worker:** Bundled into a single, optimized IIFE file in your `dist` folder.
+*   **Cache Busting:** The plugin adds `?v=[timestamp]` to the URLs in the HTML to ensure users always get the latest version.
+
+---
+
+## 📘 TypeScript Integration
+
+If you are using TypeScript, you need to tell the compiler that `__TINY_PWA_MANIFEST__` exists on the `window` object. 
+
+Add this to your `env.d.ts` file:
+
+```typescript
+declare global {
+  interface Window {
+    /** 
+     * The Web App Manifest object injected by tiny-vite-pwa 
+     */
+    __TINY_PWA_MANIFEST__: Record<string, any>;
+  }
+}
+
+export {};
+```