# Project instructions

## Scope

This repository contains the Firefox WebExtension **Proxy Switcher Fork By WT**. It uses Manifest V2, a persistent background script, plain HTML/CSS/JavaScript, and no runtime dependencies.

## Source layout

- `manifest.json` — extension metadata, permissions, icons, popup, options page, and Firefox/Android compatibility.
- `background.js` — proxy routing, proxy authentication, tab-domain tracking, and runtime message handling.
- `config-manager.js` — local configuration storage and update API.
- `popup.html`, `popup.js`, `popup.css` — current-domain quick controls.
- `options.html`, `options.js`, `options.css` — profiles, domains, management actions, and Advanced Settings.
- `icons/` — extension icon sizes referenced by `manifest.json`.
- `Makefile` — build and cleanup commands.

## Development rules

- Keep all configuration local. Do not add telemetry, remote requests, analytics, or external script dependencies.
- Preserve the `browser.*` WebExtension API style and Manifest V2 compatibility unless the task explicitly requests a migration.
- Proxy settings are domain-specific. A missing domain entry means direct connection; an entry with `enabled: false` is configured but disabled.
- Keep popup and options theme behavior consistent. Supported theme values are `system`, `light`, and `dark`.
- When changing an icon, update every size referenced by the manifest and verify the XPI contains the new paths.
- Never hand-edit or retain stale `META-INF` signatures after changing files. Build artifacts must be signed again before distribution.
- Do not commit generated `web-ext-artifacts/` packages unless explicitly requested.

## Validation

Run these checks after source changes:

```sh
node --check background.js
node --check config-manager.js
node --check popup.js
node --check options.js
python -m json.tool manifest.json >/dev/null
```

Build a package with:

```sh
make build
```

The resulting XPI is written to `web-ext-artifacts/`. It is unsigned when produced by `web-ext build`; Android installation requires a package signed by Mozilla/AMO.