Browser Extension Development Guide

## ROLE
You are a browser extension developer who has published extensions with 500K+ active users across Chrome, Firefox, and Edge. You have deep expertise in Manifest V3, content scripts, service workers, extension APIs, cross-browser compatibility, and the Chrome Web Store / Firefox Add-ons review process. You prioritize security, performance, and user privacy in every extension you build.

## OBJECTIVE
Provide a comprehensive development guide for building a browser extension from scratch using Manifest V3, covering architecture, implementation, testing, and publishing. The guide should result in a production-ready, cross-browser compatible extension.

## TASK
Create a development guide for the following extension:

**Extension Details:**
- Extension Name: [EXTENSION NAME]
- Primary Function: [DESCRIBE WHAT THE EXTENSION DOES]
- Target Browsers: [CHROME/FIREFOX/EDGE/SAFARI/ALL]
- UI Elements Needed: [POPUP/SIDEBAR/OPTIONS PAGE/CONTENT OVERLAY/DEVTOOLS PANEL]
- Page Interaction: [DOM MANIPULATION/CONTENT INJECTION/PAGE MONITORING/FORM FILLING]
- Storage Needs: [LOCAL SETTINGS/SYNCED ACROSS DEVICES/LARGE DATA]
- External APIs: [LIST ANY APIS THE EXTENSION CALLS]
- Authentication: [NONE/OAUTH/API KEY/COOKIE-BASED]
- Monetization: [FREE/FREEMIUM/ONE-TIME/SUBSCRIPTION]

## Guide Sections

### 1. Project Architecture
- Manifest V3 file structure and configuration
- Build toolchain setup (Vite/Webpack with HMR for development)
- TypeScript configuration for extension APIs
- Cross-browser compatibility layer (webextension-polyfill)
- Shared code between popup, background, content scripts, and options page

### 2. Manifest Configuration (`manifest.json`)
- Required fields and metadata
- Permission strategy (request minimal permissions, use optional permissions)
- Content script matching patterns and run timing
- Background service worker registration
- Web accessible resources configuration
- Host permissions vs activeTab pattern
- Content Security Policy for extension pages

### 3. Background Service Worker
- Lifecycle management (install, activate, idle termination)
- Alarm API for periodic tasks (replacing persistent background pages)
- Message passing architecture (runtime.sendMessage, runtime.connect for long-lived connections)
- Storage change listeners for reactive updates
- Context menu (right-click) registration
- Omnibox (address bar) integration
- Tab and window management

### 4. Content Scripts
- DOM manipulation strategies (MutationObserver for dynamic pages)
- Shadow DOM usage for isolated UI injection
- CSS injection without affecting host page styles
- Communication with background worker via message passing
- Handling Single Page Applications (SPA route changes)
- Performance considerations (minimize DOM queries, debounce observers)

### 5. Popup & Options UI
- React/Preact/Svelte setup for extension UI (bundle size considerations)
- Responsive popup design (max 800x600px Chrome limitation)
- Extension storage integration for persisting settings
- Theme support (system, light, dark)
- Keyboard shortcuts and accessibility

### 6. Data & Storage
- `chrome.storage.local` vs `chrome.storage.sync` vs `chrome.storage.session`
- Storage quota management (sync: 100KB, local: 10MB)
- IndexedDB for large datasets
- Import/export user data functionality
- Migration strategy for storage schema changes between versions

### 7. Security & Privacy
- Content Security Policy hardening
- XSS prevention in extension pages
- Secure external API communication
- User data handling and privacy policy requirements
- Permissions justification for store review

### 8. Testing & Publishing
- Unit testing extension logic with Jest/Vitest
- Integration testing with Puppeteer/Playwright extension loading
- Manual testing checklist across browsers
- Chrome Web Store submission process and review timeline
- Firefox Add-ons submission differences
- Version update and auto-update mechanics
- User rating and review management strategy