🛡️ Tab Session Guardian

An offline-first, high-performance Chrome Extension for intelligent multi-window tab management, coupled with the Edge-Based Nonce Authentication Protocol (EBNAP) for hardware-level security.

---

📌 1. Executive Overview

Tab Session Guardian is a local-first browser productivity and resilience platform designed for secure tab session orchestration and reliable startup restoration. It runs with zero cloud dependency for core extension operations and avoids transmitting browsing session telemetry off-device.

Core Pillars

1. Software Layer — Manifest V3 Chrome Extension for multi-window tab capture/restore, live workspace tracking, hotkey-driven actions, and automated archive cleanup.
2. Security Layer — EBNAP for edge-level nonce-based challenge-response identity verification in LAN/hardware integration scenarios (ESP32-focused).

---

🚀 2. Key Features

• Intelligent Multi-Window Management — Save and restore complex window layouts with tab group awareness.
• Continuous Workspace Tracking — Debounced state persistence (300ms) across tab/window lifecycle events.
• Crash-Safe Startup Restoration — Restores last active state or startup-tagged session without startup window termination loops.
• 4-Day Auto-Purge Engine — Cleans ephemeral Closed Window sessions after 96 hours when no custom user tags exist.
• Instant Popup UX — Responsive interaction pipeline with asynchronous storage access decoupling.
• Manifest V3 Security Posture — Strict CSP, guarded runtime messaging, and safe text rendering.

---

📂 3. Monorepo Structure & Build Pipeline

tabGards/
├── manifest.json
├── background.js
├── content.js
├── shared/
│   └── storage.ts
├── the pop ui ui/
│   ├── src/app/App.tsx
│   ├── public/
│   │   ├── background.js
│   │   ├── content.js
│   │   └── manifest.json
│   └── vite.config.ts
├── the tab manager dashboared ui/
│   ├── src/app/App.tsx
│   ├── src/styles/index.css
│   └── vite.config.ts
└── dist/
    ├── index.html
    ├── background.js
    ├── content.js
    ├── manifest.json
    └── dashboard/
        └── index.html

Build Commands

Run from repository root:

# Build Popup UI
npm run build --prefix "the pop ui ui"

# Build Dashboard UI
npm run build --prefix "the tab manager dashboared ui"

Output	Path
Unified extension bundle	dist/
Popup entrypoint	dist/index.html
Dashboard entrypoint	dist/dashboard/index.html

---

🔐 4. Security Hardening & EBNAP Integration

4.1 Extension Security Architecture

Control	Implementation
Manifest V3 CSP	script-src 'self'; object-src 'self'
Background message guarding	sender.id !== chrome.runtime.id requests are rejected
XSS mitigation	Dynamic values rendered as safe text nodes (no dangerouslySetInnerHTML)

4.2 Edge-Based Nonce Authentication Protocol (EBNAP)

For hardware integrations, EBNAP mitigates replay and spoofing risk in local/LAN environments.

• Entropy Source: ESP32 TRNG-generated 32-bit nonce component.
• Dynamic Nonce:

$$ N_{edge} = \mathrm{TRNG}_{32}() \oplus \mathrm{SystemUptime}_{ms} $$

• Auth Validation: HMAC-SHA256 tag over secret + nonce + payload.
• Freshness Gate:

$$ TTL \le 5000,\mathrm{ms} $$

• Single-Use Defense: Sliding nonce cache blocks replay.
• Performance Target: Handshake RTT < 25 ms, peak RAM ~14.2 KB.

---

⚙️ 5. Core Engines & Automation

5.1 4-Day Auto-Purge Expiration Engine

• Alarm Name: tabguardian_closed_window_cleanup
• Schedule: Every 60 minutes
• Purge Rule: Session is deleted only when all conditions are true:
  • Tagged as Closed Window (case-insensitive)
  • No custom user tags
  • Session age > 96 hours
• Exemption Rule: Any user tag customization promotes the session to persistent collection behavior.

5.2 Continuous Workspace Auto-Tracking

• Debounce Window: 300 ms
• Event Triggers: chrome.tabs.onUpdated, onRemoved, onCreated, and chrome.windows.onCreated
• Storage Target: tabguardian_last_active_state
• Outcome: Reliable restore path for "Restore Last Active" startup behavior.

---

🎨 6. UI/UX Specifications & Hotkey Gateway

6.1 Design Theme

• Aesthetic: Dark cyberpunk glassmorphism
• Primary Palette:
  • Background cards: #0F1319
  • Borders: #1F2A38
  • Accent neon purple: #8B5CF6
• Animation Style: GPU-friendly transitions and pulse-based interaction cues.

6.2 Hotkey Specifications

Shortcut	Action
Alt + Shift + S	Instant multi-window session snapshot
Alt + W	Close active browser tab
Alt + T	Focus/open TabGuardian dashboard (content-script gateway)
Ctrl + Shift + D	Open dashboard command binding
Alt + Shift + G	Open extension popup

---

📥 7. Installation & Deployment Guide

🌐 Chromium-Based Browsers (Chrome, Edge, Brave, Arc)

If you prefer to load the compiled assets manually into any Chromium framework, follow these steps:

1. Open your browser and navigate to chrome://extensions/ (or edge://extensions/) in your URL bar.
2. Enable the Developer mode toggle switch located in the top-right corner.
3. Click the Load unpacked button located in the top-left toolbar.
4. Open your extracted workspace folder, navigate to browser_exten/Ui/, and select the newly generated dist directory.

---

🦊 Mozilla Firefox

⚠️ Implementation Warning: Automated command-line injection tools trigger external developer debugging hooks within Gecko architectures. This forces a permanent and visually disruptive "Browser is under remote control" warning banner across your top viewport.

For a completely clean, pristine, and warning-free installation inside Firefox, execute these manual activation steps:

1. Open Mozilla Firefox normally from your desktop deployment or taskbar shortcut.
2. In the URL address bar at the top, type exactly about:debugging and press Enter.
3. On the left-hand vertical menu pane, click on This Firefox.
4. Locate the Temporary Extensions section block and click the Load Temporary Add-on... button.
5. An OS-native file explorer window will pop up. Navigate directly into your compiled production folder within your extracted repository path:

   \browser_exten\Ui\dist\
   

📸 Screenshots

---

🛠️ 8. Technical Problem-Solving & Bug Fix Log

Issue	Root Cause	Resolution
Chrome startup crash loop	Startup window was being removed too early, dropping to zero windows	Reused initial startup window and replaced placeholder tab safely
History “Delete All” leakage	Shared delete path affected unrelated storage domains	Isolated deletion pipelines for history, collections, and vault
Popup interaction freeze	Storage-bound click handlers blocked smooth UI updates	Decoupled selection state from async storage with in-memory derivation
Dropdown clipping/submergence	Layering and overflow constraints on card containers	Elevated layering (z-50), visible overflow, and click-capture backdrop

---

🏁 9. Build, Load, and Distribution Status

Local Build + Load Workflow

# 1) Build both UIs
npm run build --prefix "the pop ui ui"
npm run build --prefix "the tab manager dashboared ui"

# 2) In Chrome, open: chrome://extensions
# 3) Enable Developer Mode
# 4) Click "Load unpacked" and select the dist/ folder

Status Checkpoint	State
Manifest compliance	✅ Manifest V3
Distribution target	✅ dist/
Core startup restore path	✅ Implemented
Auto-cleanup scheduler	✅ Implemented

---

📚 Additional Documentation

• FULL_PROJECT_DOCUMENTATION.md
• SETTINGS_DOCUMENTATION.md
• TEST_AND_OPTIMIZATION_REPORT.md
• LATEST_UPDATES of pop up ui.md
• ANIMATION_AND_FAVORITES_DOCS of task manager dashboard ui.md