<domain_overview>

🌐 BROWSER EXTENSION: THE 2026 MASTERCLASS

Philosophy: Extensions are ephemeral, restricted, yet powerful. Persistence is an Art. Security is a Mandate. Design Constraint: For UI/UX, Aesthetics, and Layout, YOU MUST REFER TO THE

frontend-design

SKILL. PERSISTENCE PARADOX GUARD (CRITICAL): Never rely on global variables or in-memory state in background scripts. AI-generated code frequently fails by assuming Manifest V3 service workers are persistent. They are NOT; they terminate after 30 seconds of inactivity. You MUST backup every piece of state to

chrome.storage

or

IndexedDB

immediately upon change. This skill aims to eliminate "volatile-state" bugs typical of generic AI implementations. If data is not in durable storage, it does not exist. </domain_overview> <manifest_architecture>

🏗️ PROTOCOL 1: THE MANIFEST V3 CONSTITUTION

All extensions must be built on Manifest v3. No exceptions.

1. Manifest Blueprint:
   • Service Workers: No persistent background pages. Use

     "background": { "service_worker": "background.js" }

     .
   • No Remote Code: All scripts must be local.

     unsafe-eval

     is forbidden.
   • Permissions: Principle of Least Privilege. Use

     optional_permissions

     where possible.
   • Action UI: Prefer

     action

     over

     browser_action

     or

     page_action

     .
2. Side Panel Supremacy:
   • Requirement: Use

     chrome.sidePanel

     for persistent, non-intrusive experiences.
   • API:

     chrome.sidePanel.setOptions({ path: 'sidepanel.html', enabled: true })

     . </manifest_architecture> <persistence_engine>

⚡ PROTOCOL 2: THE PERSISTENCE ENGINE (ANTI-TERMINATION)

Service Workers sleep. You must keep the logic alive.

1. The Alarm Pulse:
   • Use

     chrome.alarms

     to wake up the Service Worker every 1-5 minutes for background sync.
2. The Offscreen Document (When needed):
   • Use the

     offscreen

     API for tasks like DOM parsing, heavy calculations, or keeping the SW alive via periodic messaging.
3. State Management Protocol:
   • NEVER rely on global variables.
   • Mandatory: Use

     chrome.storage.session

     for transient session-only secrets.
   • Mandatory: Use

     IndexedDB

     or

     chrome.storage.local

     for large datasets and persistent user data. </persistence_engine> <security_fortress>

🔐 PROTOCOL 3: THE SECURITY FORTRESS

1. Context Bridge Safety:
   • Content Scripts are "Hostile Territory". Always sanitize data passed to the Service Worker via

     chrome.runtime.sendMessage

     .
2. Declarative Net Request:
   • Use

     declarativeNetRequest

     for blocking/modifying headers. Only use

     webRequest

     as a fallback for Firefox if dynamic rules are critical. </security_fortress> <design_integration>

🎨 PROTOCOL 4: DESIGN & UI/UX (INTEGRATED)

Direct Instruction: You are an extension developer, not a designer. You must outsource the "Soul" of the UI.

1. UI Execution:
   • Popup/SidePanel: Follow the 8-Point Grid and Glassmorphism rules from

     frontend-design

     .
   • Component Atomization: Use Atomic Design 2.0 principles.
   • Friction: Ensure the popup interaction is < 400ms (Doherty Threshold). </design_integration> <audit_and_reference>

🛠️ PROTOCOL 5: SCRIPT ENFORCEMENT (THE SENTINEL)

Every extension build MUST pass the high-tier audit suite.

1. manifest-auditor.js:
   • Rule: MV3 compliance and CSP safety. No broad permissions.
2. persistence-check.js:
   • Rule: Service Worker "Heartbeat" verification and State integrity.
3. asset-master.js:
   • Rule: Icon dimensional audit and asset optimization.

---

📂 COGNITIVE AUDIT CYCLE

1. Run

   node scripts/js/manifest-auditor.js

   -> Clean?
2. Run

   node scripts/js/persistence-check.js

   -> Heartbeat detected?
3. Run

   node scripts/js/asset-master.js

   -> Assets optimized?
4. MANDATORY: Run

   playwright test

   -> All paths pass?
5. Is it Manifest v3 compliant?
6. Does the Service Worker handle termination gracefully (State stored)?
7. Are permissions minimized?
8. Is the UI justified by a "Narrative-First" screenplay from

   frontend-design

   ?

Link: frontend-design </audit_and_reference>