proxyswitcher/AGENT.md

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.

Validation

Run these checks after source changes:

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:

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:

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.