# [Extension Name]

A Manifest V3 browser extension. Popup, options page, content script, background worker. TypeScript end to end.

## Source of truth
GitHub. Versioned zips uploaded to Chrome Web Store via `web-ext sign` (also works for Firefox). The current store version is the source of truth for what users have.

## Tech stack
Vite 6 (with `@crxjs/vite-plugin` for MV3 HMR) + TypeScript + React 19 (for the popup + options pages). Tailwind v4. Manifest V3. Storage via `chrome.storage.local`. Cross-browser polyfilled via `webextension-polyfill`.

## Deploy
1. `npm run build` -> outputs to `dist/`
2. `cd dist && zip -r ../extension.zip .`
3. Upload to Chrome Web Store Developer Dashboard
4. (Optional) `web-ext sign --api-key=$AMO_KEY --api-secret=$AMO_SECRET` for Firefox AMO

## File map
- `src/manifest.ts` declarative manifest (compiled to JSON by crxjs)
- `src/background.ts` MV3 service worker (event-driven, NOT persistent)
- `src/content/` content scripts injected per-site
- `src/popup/` React popup
- `src/options/` React options page
- `src/lib/storage.ts` typed `chrome.storage` wrapper
- `src/lib/messaging.ts` content <-> background message types
- `vite.config.ts` with `@crxjs/vite-plugin`
- `public/icons/` 16/32/48/128 PNG icons

## .env keys
None at runtime (MV3 has no env injection). Build-time variables can be passed via Vite `define`.

## Hard rules
- MV3 background is a service worker. It can be killed at any time. Persist anything via `chrome.storage`, not module-level variables.
- Content scripts run in an isolated world. They cannot read the page's JS scope without injecting a script tag.
- `host_permissions` should be the minimum needed. Users see them at install. Asking for "all sites" tanks adoption.
- All cross-context messaging is typed via `src/lib/messaging.ts`. No raw `chrome.runtime.sendMessage` calls.
- Store icons must be 16x16, 32x32, 48x48, 128x128 PNG. Inkscape -> PNG export.
- Privacy policy URL required for any extension that handles user data.

## Recent significant changes
- 2026-05-02: Scaffolded. Locked: Vite + crxjs (HMR matters), React for popup (consistency with rest of stack), webextension-polyfill for Firefox parity.

## Next session: start here
1. Edit `src/manifest.ts` name, description, host_permissions.
2. Generate icons (Figma export or `realfavicongenerator.net` adapted).
3. `npm run dev` -> Vite watches, crxjs hot-reloads the unpacked extension.
4. Load `dist/` as unpacked extension at `chrome://extensions`.
5. Test on real sites before submitting to store.