---
name: browser-extension-audio-engineering
description: Build, migrate, debug, package, and release browser extensions using Manifest V3, service workers, offscreen documents, Firefox background pages, WebExtensions APIs, Web Audio, real-time EQ and DSP, storage, permissions, content scripts, cross-browser builds, CRX/XPI packaging, and store requirements. Use for goatEQ, AudioAffinityOptimizer, smartlinks, Git extensions, media controls, and privacy-sensitive browser tooling.
compatibility: Requires browser-specific testing in current Chromium and Firefox releases. Never request broader host or browser permissions than the feature requires.
license: Apache-2.0
---

# Browser extension and audio engineering

Design for browser lifecycle constraints first. Manifest V3 service workers may stop at any time; long-running audio and DOM-dependent work must live in an appropriate supported context.

## Architecture workflow

1. Identify target browsers, minimum versions, stores and required capabilities.
2. Map each responsibility to popup, options page, service worker, offscreen document, background page or content script.
3. Define message contracts and persistent state before implementation.
4. Request the smallest permissions and host patterns.
5. Implement browser-specific adapters instead of scattering feature probes.
6. Handle startup, suspension, reconnection, tab closure, navigation and permission revocation.
7. Test packed builds, not only unpacked development mode.
8. Produce separate verified Chromium and Firefox artifacts when behavior differs.

## Web Audio rules

- create and resume audio contexts only after permitted user interaction;
- track media-stream, node and context lifetimes explicitly;
- disconnect nodes and stop tracks when a tab or session ends;
- avoid clipping with gain staging and headroom;
- smooth parameter changes to prevent zipper noise;
- bound FFT and visualization work to avoid excessive CPU;
- persist presets using versioned schemas;
- never capture or transmit audio without explicit, visible user action.

## Manifest V3

Service workers orchestrate but do not provide a persistent DOM. Use offscreen documents only for supported reasons and close them when no longer needed. Reconstruct transient state from durable storage and active browser state after worker restart.

## Cross-browser behavior

Firefox and Chromium differ in background model, offscreen support, permissions, packaging and store review. Maintain shared core logic plus thin adapters. Do not ship Chromium-only APIs behind unchecked assumptions.

## Security and privacy

Avoid remote code, eval-like behavior, injected trackers and unnecessary content-script scope. Validate imported presets and messages. Treat extension storage as user-accessible, not a secret vault. Document every external request.

## Release checks

Validate manifests, permissions, icons, CSP, localization, update paths, artifact contents, source-map policy and reproducible packaging. Run smoke tests for install, update, enable/disable, browser restart and permission changes.

## Output

Return target browsers, architecture, permissions, lifecycle handling, audio graph, cross-browser differences, privacy behavior, tests, packaged artifacts, store-readiness findings and remaining browser-specific limitations.