/browser-extension

name: browser-extension
description: Master specialized skill for building 2025/2026-grade browser extensions. Deep expertise in Manifest v3, Service Worker persistence (Alarms, Offscreen API), Side Panel API, and Cross-Browser compatibility.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash

<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](skills/browser-extension/scripts/js/manifest-auditor.js):**

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

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

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

3. **[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) </audit_and_reference>