# AGENTS.md: Browser extension (WXT)

## Commands
`pnpm dev` (Chrome) · `pnpm dev:firefox` · `pnpm build` · `pnpm zip` · `pnpm compile` (typecheck) · `pnpm test` (Vitest with WXT's testing plugin)

## Structure
- Entrypoints in `entrypoints/`: `background.ts` (`defineBackground`), `*.content.ts` (`defineContentScript({ matches, main })`), `popup/`, `options/`, `sidepanel/`. WXT generates the manifest from these plus `wxt.config.ts`; don't hand-write `manifest.json`.
- Shared code in `utils/`, `components/`; auto-imports are enabled.

## Rules
- Use the `browser` API (WXT's polyfilled global), not `chrome.*`, for cross-browser support.
- The background is a service worker in MV3: no long-lived globals; persist state with `storage.defineItem('local:settings', { fallback })` from WXT storage.
- Messaging through a typed wrapper (e.g., `@webext-core/messaging`) with defined message types; validate data from content scripts.
- Content scripts: inject UI with `createShadowRootUi` to avoid CSS conflicts; clean up on `ctx.onInvalidated`. Never `innerHTML` page-controlled text.
- Permissions: request the minimum in `wxt.config.ts` (`manifest.permissions`, `host_permissions`); prefer `activeTab` and optional permissions requested at runtime.
- No remote code: everything ships in the bundle (store policies forbid remotely hosted code).
- Fetch external APIs from the background, not content scripts, and keep API keys out of the extension when possible (use your backend).

## Don't
Don't upload to the Chrome Web Store or Firefox Add-ons from the agent.

## Done
Typecheck, tests, and `pnpm build` pass for Chrome and Firefox.