# 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` — Firefox Manifest V2 metadata, permissions, icons, popup, options page, and Firefox/Android compatibility.
- `manifest.chrome.json` — Chrome/Chromium Manifest V3 metadata.
- `background.js` — proxy routing, proxy authentication, tab-domain tracking, and runtime message handling.
- `background-chrome.js` and `background-service-worker.js` — Chrome/Chromium PAC routing and Manifest V3 service worker.
- `browser-api.js` — Promise-based API adapter used by shared popup/options pages on Chromium.
- `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.
- `.github/workflows/release.yml` — per-push package builds, workflow artifacts, and release-triggered AMO/Chrome Web Store publishing.

## Development rules

- Keep all configuration local. Do not add telemetry, remote requests, analytics, or external script dependencies.
- Preserve the `browser.*` WebExtension API style in shared UI code. Firefox uses Manifest V2 and `proxy.onRequest`; Chromium uses Manifest V3, `chrome.proxy.settings`, and a PAC script.
- Keep the Firefox Android minimum version at 113 or newer when using the `gecko_android` manifest key.
- Keep the Firefox and Chromium manifests as separate build targets. Do not replace the Firefox proxy listener with the Chrome PAC implementation.
- 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.
- Keep publishing credentials only in GitHub Secrets. The release workflow expects AMO JWT credentials and Chrome Web Store OAuth credentials.
- Missing or incomplete store credentials must skip only that store's deployment. Keep package builds, release assets, and workflow artifacts available without store credentials.

## 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.

Build the Chrome/Chromium package with:

```sh
make build-chrome
```

The resulting ZIP is written to `web-ext-artifacts/proxyswitcherforkbywt-chrome.zip`. Chrome Android and iOS do not support ordinary extension installation.