<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. </domainoverview> <manifestarchitecture>

🏗️ 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": { "serviceworker": "background.js" }. No Remote Code: All scripts must be local. unsafe-eval is forbidden. Permissions: Principle of Least Privilege. Use optionalpermissions where possible. Action UI: Prefer action over browseraction or pageaction.

1. Side Panel Supremacy:

Requirement: Use chrome.sidePanel for persistent, non-intrusive experiences. API: chrome.sidePanel.setOptions({ path: 'sidepanel.html', enabled: true }). </manifestarchitecture> <persistenceengine>

⚡ 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.

1. The Offscreen Document (When needed):

* Use the offscreen API for tasks like DOM parsing, heavy calculations, or keeping the SW alive via periodic messaging.

1. 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. </persistenceengine> <securityfortress>

🔐 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.

1. Declarative Net Request:

* Use declarativeNetRequest for blocking/modifying headers. Only use webRequest as a fallback for Firefox if dynamic rules are critical. </securityfortress> <designintegration>

🎨 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). </designintegration> <auditand_reference>

🛠️ PROTOCOL 5: SCRIPT ENFORCEMENT (THE SENTINEL)

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

1. [manifest-auditor.js](skills/browser-extension/scripts/js/manifest-auditor.js):

* Rule: MV3 compliance and CSP safety. No broad permissions.

1. [persistence-check.js](skills/browser-extension/scripts/js/persistence-check.js):

* Rule: Service Worker "Heartbeat" verification and State integrity.

1. [asset-master.js](skills/browser-extension/scripts/js/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](skills/frontend-design/SKILL.md)

</auditandreference>