@imsovikde/source-grab 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to SourceGrab will be documented in this file.
+
+## [1.0.0] - 2026-07-24
+
+### Added
+- Real-time resource capture via Chrome webRequest API
+- Deep scan mode using Chrome DevTools Protocol (CDP)
+- Category-based filtering (Images, Scripts, Stylesheets, Fonts, Media, SVG, PDF, Documents)
+- Search by filename or URL
+- Sort by load order, file size, file type, alphabetical, newest
+- Size range filtering
+- Select All / Deselect All
+- Individual file download with exact filename matching
+- Batch ZIP download with timestamped filenames
+- Copy filenames to clipboard
+- Auto-scroll page to discover lazy-loaded content
+- Data persistence across tab switches and panel close/reopen
+- Master clear button in header
+- Custom dropdown menus (no native selects)
+- Glassmorphism header and footer dock
+- Spring physics button animations
+- Recording indicator with pulse animation
+- Empty state with contextual messages
+- Toast notification system
+- Responsive narrow-width layout

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Souvik Dey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+<div align="center">
+
+# 🌐 SourceGrab
+
+**Capture every file your browser loads — in real-time.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-E0977A.svg)](LICENSE)
+[![Chrome MV3](https://img.shields.io/badge/Chrome-Extension%20MV3-4285F4.svg?logo=googlechrome&logoColor=white)]()
+[![Release](https://img.shields.io/badge/Release-v1.0.0-8CBA80.svg)](https://github.com/imsovikde/source-grab/releases/latest)
+[![GitHub Package](https://img.shields.io/badge/GitHub%20Package-v1.0.0-4285F4.svg?logo=github)](https://github.com/imsovikde/source-grab/pkgs/npm/source-grab)
+[![CI Build](https://img.shields.io/badge/CI-Passing-brightgreen.svg)](https://github.com/imsovikde/source-grab/actions)
+[![AI Agents Ready](https://img.shields.io/badge/AGENTS.md-Ready-C9C2E8.svg)](AGENTS.md)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-E8C766.svg)]()
+[![Vanilla ES Modules](https://img.shields.io/badge/Code-Vanilla%20ES%20Modules-A8C8E0.svg)]()
+
+A high-performance Manifest V3 Chrome Extension that continuously intercepts, catalogs, and downloads every network resource loaded by any active web tab using a **Three-Layer Interception Engine** powered by the **Chrome DevTools Protocol (CDP)**.
+
+[⚡ Live Landing Page](https://source-grab.vercel.app/) • [📦 Download v1.0.0 Package](https://github.com/imsovikde/source-grab/releases/tag/v1.0.0) • [📖 Architecture Docs](ARCHITECTURE.md) • [💬 Support Center](SUPPORT.md)
+
+</div>
+
+---
+
+## 📖 Executive Summary & Vision
+
+Extracting assets from modern dynamic websites often requires opening DevTools, repeatedly scrolling to trigger lazy-loaded images, right-clicking elements individually, or missing background Blobs and Web Worker streams entirely. 
+
+**SourceGrab** solves this by replicating the combined power of Chrome DevTools' **Network** and **Sources** panels inside a persistent side panel UI. It intercepts files as they travel across the browser pipeline, categorizes them automatically, allows copy-to-clipboard of file names, and enables bulk downloads individually or as compressed `.zip` archives while preserving original website path structures.
+
+> [!NOTE]
+> **SourceGrab operates 100% locally inside your browser.** No network data, URLs, or captured files leave your device.
+
+---
+
+## 🎯 Target Audiences & Key Use Cases
+
+| User Persona | Core Problem Solved | Primary SourceGrab Feature |
+|---|---|---|
+| 💻 **Web Developers** | Asset auditing & network payload inspection | Real-time CDP capture & category filtering |
+| 🎨 **UI/UX Designers** | Extracting reference SVGs, fonts, and high-res images | One-click SVG filter & filename copying |
+| 🧪 **QA Engineers** | Verifying loaded network assets match build manifests | Size sorting & total count tracking |
+| 📚 **Archivists & Researchers** | Capturing complete single-page offline asset snapshots | Timestamped ZIP bundle download |
+| ⚡ **Content Scrapers** | Bulk saving media without manual right-click saving | Auto-scroll lazy-load capture engine |
+
+---
+
+## ✨ Comprehensive Feature Matrix
+
+### 1. 🔍 Three-Layer Interception Pipeline
+- **Layer 1 (Passive `webRequest`):** Listens to `chrome.webRequest.onBeforeRequest`, `onResponseStarted`, and `onCompleted` events to index standard HTTP/HTTPS traffic.
+- **Layer 2 (MAIN-World DOM & Fetch Hook):** Overrides `window.fetch` and `XMLHttpRequest`, attaches `MutationObserver` for dynamically injected DOM nodes, and hooks Shadow DOM elements.
+- **Layer 3 (Chrome DevTools Protocol - CDP Deep Scan):** Connects `chrome.debugger` to capture raw response bodies, data URIs, Web Workers, inline Blobs, and stream buffers invisible to standard network listeners.
+
+### 2. 🏷️ Category Filtering & Real-Time Search
+- Instant one-click filter buttons for **Images**, **SVG**, **PDF**, **Scripts**, **Stylesheets**, **Fonts**, **Media**, **Documents**, and **Other**.
+- Live search bar supporting instant filtering by filename substring or full URL path.
+- Sorting controls: **Load Order**, **File Size**, **File Type**, **Alphabetical**, and **Newest First**.
+
+### 3. 📦 Dual Download Engine & ZIP Export
+- **Individual File Download:** Triggers Chrome native downloads while preserving website directory hierarchy (`SourceGrab/<hostname>/<path>/<filename>`).
+- **Timestamped ZIP Packaging:** Generates compressed `.zip` archives directly in browser memory formatted as `SourceGrab-YYYY-MM-DD_HH-mm-ss.zip`.
+- **Concurrency Control:** Queue manager caps active downloads at 5 concurrent streams with automatic 3-retry backoff.
+
+### 4. 📋 One-Click Copy Filenames
+- Filter your view (e.g., all SVG files) and click **Copy** in the dock.
+- Copies all visible filenames (with file extensions) to the system clipboard, separated by line breaks.
+
+### 5. 🔄 Auto-Scroll & Lazy Content Discovery
+- Toggles automated incremental page scrolling to trigger `IntersectionObserver` lazy-loaded images, infinite-scroll JSON requests, and video stream segments.
+
+### 6. 💾 Multi-Tab Storage Isolation & Service Worker Safety
+- Uses `chrome.storage.local` indexed by tab ID (`registry_${tabId}`) ensuring captured data survives sidepanel toggling, tab switching, and Chrome service worker restarts.
+
+### 7. 🎨 Premium Glassmorphic Side Panel UI
+- Designed with **Space Grotesk** (display titles) and **Outfit** (UI body) Google Fonts.
+- Squircle content cards (20px border radius) and pill controls (999px border radius).
+- Smooth spring-physics animations without performance-heavy backdrop blurs.
+
+---
+
+## ⚡ Installation & Setup Guide
+
+### 1. Developer Sideload Guide (Unpacked Extension)
+
+> [!IMPORTANT]
+> SourceGrab is built using pure Vanilla ES Modules. No `npm install`, Node.js build, or Webpack bundling step is required to run the extension in Chrome!
+
+1. **Clone the Repository:**
+   ```bash
+   git clone https://github.com/imsovikde/source-grab.git
+   cd source-grab
+   ```
+
+2. **Open Chrome Extensions Page:**
+   Navigate to `chrome://extensions` in your Google Chrome browser.
+
+3. **Enable Developer Mode:**
+   Toggle the **Developer mode** switch in the top-right corner of the page.
+
+4. **Load Unpacked Extension:**
+   - Click the **Load unpacked** button in the top-left toolbar.
+   - Select the cloned `source-grab` root folder.
+
+5. **Open Side Panel:**
+   - Click the extension icon in your Chrome toolbar or open the Chrome Side Panel.
+   - Select **SourceGrab** from the panel dropdown.
+   - Click **Start** to begin capturing resources in real-time!
+
+---
+
+### 2. Installing `@imsovikde/source-grab` via npm
+
+Because `@imsovikde/source-grab` is published to **GitHub Packages (`npm.pkg.github.com`)**, npm needs to know which registry handles the `@imsovikde` scope.
+
+#### Step 1: Configure `.npmrc`
+Create a `.npmrc` file in your project directory (or user directory `~/.npmrc`) with the following scope rule:
+
+```ini
+@imsovikde:registry=https://npm.pkg.github.com
+```
+
+#### Step 2: Run npm Install
+```bash
+npm install @imsovikde/source-grab@1.0.0
+```
+
+> [!TIP]
+> If you have a GitHub Personal Access Token (`read:packages`), you can authenticate by adding `//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN` to your `.npmrc`.
+
+---
+
+## 🛠️ Project Directory Tree
+
+```
+source-grab/
+├── manifest.json                  # Manifest V3 extension configuration
+├── package.json                   # Project metadata & packaging scripts
+├── design-tokens.css              # Central CSS variables & theme tokens
+├── AGENTS.md                      # AI coding agent development guidelines
+├── ARCHITECTURE.md                # System architecture & Mermaid flow diagrams
+├── SUPPORT.md                     # Troubleshooting & user support guide
+├── GOVERNANCE.md                  # Project maintainership & RFC standards
+├── LICENSE                        # Permissive MIT License
+├── README.md                      # Product page & main documentation
+├── CHANGELOG.md                   # Version history log
+├── CODE_OF_CONDUCT.md             # Contributor Covenant v2.1
+├── CONTRIBUTING.md                # Developer contribution guidelines
+├── SECURITY.md                    # Vulnerability disclosure policy
+├── PRD.md                         # Product Requirements Document
+├── TRD.md                         # Technical Requirements Document
+├── .github/                       # GitHub workflow & community templates
+│   ├── CODEOWNERS                 # Maintainer code mapping
+│   ├── DEPENDABOT.yml             # Weekly dependency security config
+│   ├── FUNDING.yml                # Maintainer sponsorship config
+│   ├── PULL_REQUEST_TEMPLATE.md   # PR review checklist
+│   ├── ISSUE_TEMPLATE/            # Bug report & feature templates
+│   └── workflows/                 # CI & Release Actions
+│       ├── ci.yml                 # Extension build verification
+│       ├── release.yml            # Release ZIP automation workflow
+│       └── publish-package.yml    # GitHub Packages npm publication
+├── background/                    # Service Worker & Data Engine
+│   ├── service-worker.js          # Central event & messaging hub
+│   ├── capture-registry.js        # Local storage registry manager
+│   ├── debugger-capture.js        # CDP debugger deep-scan driver
+│   └── download-engine.js         # Downloader & ZIP builder
+├── content-scripts/               # DOM Hooks & Injectors
+│   ├── main-world-hook.js         # Fetch/XHR/DOM overrides
+│   ├── isolated-bridge.js         # Content script message bridge
+│   └── auto-scroll.js             # Automated page scroll driver
+├── sidepanel/                     # User Interface Shell
+│   ├── index.html                 # Main side panel markup
+│   ├── app.js                     # Main UI controller & storage listeners
+│   ├── styles.css                 # Glassmorphic component styles
+│   ├── components/                # UI Component Modules
+│   │   ├── bottom-dock.js         # 8-button dock controller
+│   │   ├── file-list.js           # Virtual scroll file list
+│   │   ├── file-list-item.js      # Individual list item DOM renderer
+│   │   ├── filter-bar.js          # Category filter buttons
+│   │   ├── stats-header.js        # Resource counters
+│   │   ├── recording-indicator.js # Animated capture status pill
+│   │   ├── progress-overlay.js    # Batch download overlay
+│   │   └── empty-state.js         # Contextual empty state renderer
+│   └── utils/                     # Side panel helper modules
+│       ├── clipboard.js           # Copy to clipboard helper
+│       ├── format.js              # Bytes & time formatters
+│       └── virtual-scroll.js      # High-performance 60fps list engine
+├── icons/                         # 450+ Vector SVG Icon Set
+└── docs/                          # Vercel / Cloudflare Landing Page
+    ├── index.html                 # Responsive self-contained landing page
+    ├── robots.txt                 # Search engine crawling rules
+    └── sitemap.xml                # SEO Sitemap index
+```
+
+---
+
+## 📐 Architecture & Data Flow
+
+```mermaid
+flowchart TD
+    subgraph Active Browser Tab
+        PAGE[Web Page DOM]
+        MWH[MAIN World Script Hook]
+    end
+
+    subgraph Service Worker Layer
+        SW[background/service-worker.js]
+        REG[capture-registry.js]
+        CDP[debugger-capture.js]
+        DL[download-engine.js]
+    end
+
+    subgraph Storage API
+        LOCAL[(chrome.storage.local)]
+        SESSION[(chrome.storage.session)]
+    end
+
+    subgraph Sidepanel UI
+        APP[sidepanel/app.js]
+        LIST[VirtualScroll Engine]
+        DOCK[Persistent Bottom Dock]
+    end
+
+    PAGE -->|webRequest events| SW
+    PAGE -->|Fetch/DOM Overrides| MWH
+    MWH -->|postMessage| SW
+    CDP -->|CDP Network events| SW
+    SW --> REG
+    REG -->|Persist Tab Registry| LOCAL
+    SW -->|Capture State| SESSION
+    LOCAL -->|storage.onChanged| APP
+    SESSION -->|storage.onChanged| APP
+    APP --> LIST
+    APP --> DOCK
+    DOCK -->|Action Dispatch| DL
+```
+
+For complete technical specifications, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+## ❓ Frequently Asked Questions (FAQ)
+
+> [!TIP]
+> Need help or found an issue? Check our [SUPPORT.md](SUPPORT.md) guide or submit a [Bug Report](https://github.com/imsovikde/source-grab/issues/new?template=bug_report.md).
+
+### Q: Why does `npm install` fail with 404 Not Found?
+**A:** By default, `npm` queries `https://registry.npmjs.org`. Because `@imsovikde/source-grab` is hosted on **GitHub Packages (`https://npm.pkg.github.com`)**, you must configure `.npmrc` with `@imsovikde:registry=https://npm.pkg.github.com` before running `npm install`.
+
+### Q: Why does SourceGrab request Debugger permissions?
+**A:** The Chrome Debugger permission enables **Chrome DevTools Protocol (CDP)** deep scanning. This allows SourceGrab to inspect data URLs, inline Blobs, Web Worker responses, and stream buffers that standard extension network listeners miss.
+
+### Q: Why doesn't SourceGrab capture files on `chrome://` pages?
+**A:** Google Chrome security policies strictly restrict extensions from injecting scripts or attaching debuggers to internal system pages (`chrome://`, `chrome-extension://`, or the Chrome Web Store).
+
+### Q: Are my captured files or browsing data sent to an external server?
+**A:** **No.** SourceGrab runs 100% locally within your Chrome browser. It contains zero analytics, tracking scripts, or external network requests.
+
+### Q: How does the ZIP download work?
+**A:** SourceGrab compiles selected resource buffers into an uncompressed/STORE ZIP file in browser memory using a custom binary encoder, triggering a single `.zip` file save dialog.
+
+---
+
+## 🛡️ Native GitHub Community & Documentation Index
+
+- 🤖 **[AGENTS.md](AGENTS.md)** — AI coding agent development guidelines.
+- 📐 **[ARCHITECTURE.md](ARCHITECTURE.md)** — System architecture & data pipeline specs.
+- 🤝 **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution protocols & standards.
+- ⚖️ **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — Community standards (Contributor Covenant v2.1).
+- 🛡️ **[SECURITY.md](SECURITY.md)** — Security policies & vulnerability reporting.
+- 🛠️ **[SUPPORT.md](SUPPORT.md)** — User help center & FAQs.
+- 👥 **[GOVERNANCE.md](GOVERNANCE.md)** — Maintainer roles & RFC process.
+- 📜 **[LICENSE](LICENSE)** — Permissive MIT License.
+- 📋 **[CHANGELOG.md](CHANGELOG.md)** — Complete version release history.
+- 📄 **[PRD.md](PRD.md)** — Product Requirements Document.
+- 📄 **[TRD.md](TRD.md)** — Technical Requirements Document.
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/imsovikde">Souvik Dey</a></sub>
+</div>

package/background/capture-registry.js

@@ -0,0 +1,306 @@
+// background/capture-registry.js
+// v1.1 — Uses chrome.storage.local for persistent registry data
+
+export class CaptureRegistry {
+  constructor() {
+    this.memoryCache = new Map(); // Map<tabId, { resources: Map<normalizedUrl, ResourceEntry>, nextIndex: number }>
+    this.writeTimeouts = new Map();
+    this.pendingFlush = new Set(); // Track tabs that need flushing
+  }
+
+  async init() {
+    try {
+      const data = await chrome.storage.local.get(null);
+      for (const [key, value] of Object.entries(data)) {
+        if (key.startsWith('registry_')) {
+          const tabId = parseInt(key.replace('registry_', ''), 10);
+          const resources = new Map();
+          if (value && value.resources) {
+            for (const [url, entry] of Object.entries(value.resources)) {
+              resources.set(url, entry);
+            }
+          }
+          this.memoryCache.set(tabId, { resources, nextIndex: value.nextIndex || 0 });
+        }
+      }
+    } catch (e) {
+      console.error('Failed to init CaptureRegistry:', e);
+    }
+  }
+
+  normalizeUrl(url) {
+    try {
+      // Skip data: and blob: URLs — just return as-is
+      if (url.startsWith('data:') || url.startsWith('blob:')) return url;
+
+      const parsed = new URL(url);
+      parsed.hash = '';
+
+      const ignoreParams = ['_t', '_ts', 'timestamp', 'v', 'ver', '_v', 'cb', 'cache', '_', '_=', 't', 'nocache', 'rand', 'random'];
+      const params = Array.from(parsed.searchParams.keys());
+      for (const p of params) {
+        if (ignoreParams.includes(p.toLowerCase())) {
+          parsed.searchParams.delete(p);
+        }
+      }
+
+      const sortedParams = Array.from(parsed.searchParams.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+      parsed.search = new URLSearchParams(sortedParams).toString();
+      parsed.hostname = parsed.hostname.toLowerCase();
+
+      let result = parsed.toString();
+      if (result.endsWith('/') && parsed.pathname !== '/') {
+        result = result.slice(0, -1);
+      }
+      return result;
+    } catch (e) {
+      return url;
+    }
+  }
+
+  extractFilename(url) {
+    try {
+      // Handle data: URLs
+      if (url.startsWith('data:')) {
+        const mimeMatch = url.match(/^data:([^;,]+)/);
+        const mime = mimeMatch ? mimeMatch[1] : 'application/octet-stream';
+        const extMap = {
+          'image/svg+xml': 'inline.svg', 'image/png': 'inline.png',
+          'image/jpeg': 'inline.jpg', 'image/gif': 'inline.gif',
+          'image/webp': 'inline.webp', 'application/pdf': 'inline.pdf',
+          'text/css': 'inline.css', 'text/javascript': 'inline.js',
+          'application/javascript': 'inline.js'
+        };
+        return extMap[mime] || 'inline-data';
+      }
+
+      const parsed = new URL(url);
+      let pathname = parsed.pathname;
+      if (pathname.endsWith('/')) pathname = pathname.slice(0, -1);
+      const parts = pathname.split('/');
+      let lastPart = parts[parts.length - 1];
+      if (!lastPart) return 'index';
+      return decodeURIComponent(lastPart);
+    } catch (e) {
+      return 'unknown';
+    }
+  }
+
+  extractExtension(filename) {
+    // Strip query string remnants from filename
+    const clean = filename.split('?')[0].split('#')[0];
+    const parts = clean.split('.');
+    if (parts.length > 1) {
+      return parts[parts.length - 1].toLowerCase();
+    }
+    return '';
+  }
+
+  categorize(url, mimeType, resourceType) {
+    const filename = this.extractFilename(url);
+    const ext = this.extractExtension(filename);
+
+    // Priority 1: Extension-based
+    if (ext === 'svg' || mimeType?.includes('image/svg+xml')) return 'svg';
+    if (ext === 'pdf' || mimeType?.includes('application/pdf')) return 'pdf';
+
+    const images = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'ico', 'bmp', 'tiff', 'tif', 'heic', 'heif', 'jxl'];
+    if (images.includes(ext) || (mimeType?.startsWith('image/') && !mimeType?.includes('svg'))) return 'images';
+
+    const scripts = ['js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx'];
+    if (scripts.includes(ext) || mimeType?.includes('javascript') || mimeType?.includes('ecmascript')) return 'scripts';
+
+    if (ext === 'css' || mimeType?.includes('text/css')) return 'stylesheets';
+
+    const fonts = ['woff', 'woff2', 'ttf', 'otf', 'eot'];
+    if (fonts.includes(ext) || mimeType?.includes('font/') || mimeType?.includes('application/font')) return 'fonts';
+
+    const media = ['mp4', 'webm', 'ogg', 'ogv', 'mp3', 'wav', 'flac', 'aac', 'm4a', 'avi', 'mov', 'mkv', 'm3u8'];
+    if (media.includes(ext) || mimeType?.startsWith('video/') || mimeType?.startsWith('audio/')) return 'media';
+
+    const documents = ['html', 'htm', 'json', 'xml', 'xhtml', 'txt', 'csv', 'md', 'yaml', 'yml', 'toml'];
+    if (documents.includes(ext) || mimeType?.includes('text/html') || mimeType?.includes('application/json') || mimeType?.includes('text/xml') || mimeType?.includes('text/plain')) return 'documents';
+
+    // Priority 2: webRequest resourceType fallback
+    if (resourceType) {
+      if (resourceType === 'image') return 'images';
+      if (resourceType === 'script') return 'scripts';
+      if (resourceType === 'stylesheet') return 'stylesheets';
+      if (resourceType === 'font') return 'fonts';
+      if (resourceType === 'media') return 'media';
+      if (resourceType === 'main_frame' || resourceType === 'sub_frame') return 'documents';
+    }
+
+    return 'other';
+  }
+
+  async upsert(tabId, partialData) {
+    if (!partialData.url) return;
+
+    // Skip chrome-extension:// and chrome:// URLs
+    if (partialData.url.startsWith('chrome-extension://') || partialData.url.startsWith('chrome://')) return;
+
+    if (!this.memoryCache.has(tabId)) {
+      this.memoryCache.set(tabId, { resources: new Map(), nextIndex: 0 });
+    }
+
+    const tabState = this.memoryCache.get(tabId);
+    const normalizedUrl = this.normalizeUrl(partialData.url);
+
+    let entry = tabState.resources.get(normalizedUrl);
+    if (!entry) {
+      const filename = partialData.filename || this.extractFilename(partialData.url);
+      entry = {
+        url: normalizedUrl,
+        originalUrl: partialData.url,
+        filename,
+        extension: this.extractExtension(filename),
+        category: 'other',
+        mimeType: null,
+        size: null,
+        statusCode: null,
+        timestamp: Date.now(),
+        source: 'other',
+        domContext: null,
+        status: 'requested',
+        downloadState: 'none',
+        isNew: true,
+        index: tabState.nextIndex++,
+        requestId: null,
+        frameId: null
+      };
+      tabState.resources.set(normalizedUrl, entry);
+    }
+
+    // Merge partial data, preserving originalUrl
+    const oldOriginalUrl = entry.originalUrl;
+    Object.assign(entry, partialData, {
+      url: normalizedUrl,
+      originalUrl: oldOriginalUrl || partialData.url
+    });
+
+    // Re-derive filename and category after merge
+    if (!entry.filename || entry.filename === 'unknown') {
+      entry.filename = this.extractFilename(entry.originalUrl);
+      entry.extension = this.extractExtension(entry.filename);
+    }
+    entry.category = this.categorize(entry.originalUrl, entry.mimeType, entry.resourceType);
+
+    this.debouncedSave(tabId);
+  }
+
+  debouncedSave(tabId) {
+    this.pendingFlush.add(tabId);
+    if (this.writeTimeouts.has(tabId)) return;
+
+    this.writeTimeouts.set(tabId, setTimeout(async () => {
+      this.writeTimeouts.delete(tabId);
+      this.pendingFlush.delete(tabId);
+      await this.flushTab(tabId);
+    }, 100));
+  }
+
+  async flushTab(tabId) {
+    const tabState = this.memoryCache.get(tabId);
+    if (!tabState) return;
+    const obj = Object.fromEntries(tabState.resources);
+    const dataToSave = {
+      [`registry_${tabId}`]: { resources: obj, nextIndex: tabState.nextIndex }
+    };
+    try {
+      await chrome.storage.local.set(dataToSave);
+    } catch (e) {
+      console.error('CaptureRegistry save error:', e);
+    }
+  }
+
+  // Flush all pending writes immediately (called on service worker suspend)
+  async flushAll() {
+    for (const tabId of this.pendingFlush) {
+      if (this.writeTimeouts.has(tabId)) {
+        clearTimeout(this.writeTimeouts.get(tabId));
+        this.writeTimeouts.delete(tabId);
+      }
+      await this.flushTab(tabId);
+    }
+    this.pendingFlush.clear();
+  }
+
+  async getAll(tabId) {
+    const tabState = this.memoryCache.get(tabId);
+    if (!tabState) return [];
+    return Array.from(tabState.resources.values()).sort((a, b) => a.index - b.index);
+  }
+
+  async getStats(tabId) {
+    const entries = await this.getAll(tabId);
+    const stats = {
+      total: entries.length,
+      byCategory: { images: 0, svg: 0, pdf: 0, scripts: 0, stylesheets: 0, fonts: 0, media: 0, documents: 0, other: 0 },
+      newSinceLastBatch: 0
+    };
+
+    for (const entry of entries) {
+      if (stats.byCategory[entry.category] !== undefined) {
+        stats.byCategory[entry.category]++;
+      } else {
+        stats.byCategory.other++;
+      }
+      if (entry.isNew) {
+        stats.newSinceLastBatch++;
+      }
+    }
+
+    return stats;
+  }
+
+  async markBatchDownloaded(tabId, urls, batchId) {
+    const tabState = this.memoryCache.get(tabId);
+    if (!tabState) return;
+
+    for (const u of urls) {
+      const normalized = this.normalizeUrl(u);
+      const entry = tabState.resources.get(normalized);
+      if (entry) {
+        entry.downloadState = 'completed';
+        entry.isNew = false;
+      }
+    }
+    this.debouncedSave(tabId);
+  }
+
+  async clear(tabId) {
+    this.memoryCache.delete(tabId);
+    if (this.writeTimeouts.has(tabId)) {
+      clearTimeout(this.writeTimeouts.get(tabId));
+      this.writeTimeouts.delete(tabId);
+    }
+    this.pendingFlush.delete(tabId);
+    await chrome.storage.local.remove(`registry_${tabId}`);
+  }
+
+  // Clear ALL registries (browser close cleanup)
+  async clearAll() {
+    const data = await chrome.storage.local.get(null);
+    const keysToRemove = Object.keys(data).filter(k => k.startsWith('registry_'));
+    if (keysToRemove.length > 0) {
+      await chrome.storage.local.remove(keysToRemove);
+    }
+    this.memoryCache.clear();
+    for (const [tabId, timeout] of this.writeTimeouts) {
+      clearTimeout(timeout);
+    }
+    this.writeTimeouts.clear();
+    this.pendingFlush.clear();
+  }
+
+  async addNavigationMarker(tabId, url) {
+    await this.upsert(tabId, {
+      url: url,
+      mimeType: 'text/html',
+      source: 'webRequest',
+      status: 'completed',
+      filename: this.extractFilename(url) || 'index.html',
+    });
+  }
+}