### Proxy Command Fields Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/configuration.md

Example of setting proxy configurations using command fields like setProxy, setTabProxy, includeHost, and excludeHost.

```json
{
  "setProxy": "proxy.example.com:8080",
  "setTabProxy": "proxy2.example.com:3128",
  "includeHost": "proxy.example.com:8080",
  "excludeHost": "proxy.example.com:8080"
}
```

--------------------------------

### Container Configuration Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/configuration.md

An example of the container configuration object, showing how to assign specific proxy servers to incognito and Firefox container tabs.

```json
{
  "incognito": "proxy.example.com:8080",
  "container-1": "proxy-us.example.com:3128",
  "container-2": "proxy-eu.example.com:3128"
}
```

--------------------------------

### Complete Preferences Data Structure Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/import-export.md

A comprehensive example of the JSON structure used for exporting and importing FoxyProxy preferences, matching the full schema.

```json
{
  "mode": "pattern",
  "sync": false,
  "autoBackup": true,
  "passthrough": "127.0.0.1/8, *.local",
  "theme": "dark",
  "container": {
    "incognito": "proxy.example.com:8080"
  },
  "commands": {
    "setProxy": "proxy.example.com:8080"
  },
  "data": [
    {
      "active": true,
      "title": "My Proxy",
      "type": "socks5",
      "hostname": "proxy.example.com",
      "port": "1080",
      "username": "user",
      "password": "pass",
      "cc": "US",
      "city": "San Francisco",
      "color": "#FF5733",
      "proxyDNS": true,
      "include": [
        {
          "type": "wildcard",
          "title": "Google",
          "pattern": "*.google.com/*",
          "active": true
        }
      ],
      "exclude": [],
      "tabProxy": []
    }
  ]
}
```

--------------------------------

### Typical Usage Flow Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Illustrates a common workflow for using the App class, including loading preferences, checking browser type, interacting with preferences, and parsing URLs.

```javascript
import {pref, App} from './app.js';

// 1. Load saved preferences
await App.getPref();

// 2. Check browser type
if (App.firefox) {
  // Use Firefox-specific code paths
}

// 3. Work with current pref
console.log(pref.mode); // Current proxy mode

// 4. Compare with defaults
if (App.equal(pref, App.getDefaultPref())) {
  console.log('Using all defaults');
}

// 5. Show notification
App.notify('Operation complete', 'FoxyProxy');

// 6. Parse user input
const url = App.parseURL(userInput);
if (url.hostname) {
  // Valid URL
}
```

--------------------------------

### Install Chrome Extension

Source: https://github.com/foxyproxy/browser-extension/blob/main/README.md

To install on Chrome, navigate to chrome://extensions/, enable Developer Mode, and click 'Load Unpacked', selecting the manifest.json or src folder.

```bash
chrome://extensions/
```

--------------------------------

### Install Grunt Locally

Source: https://github.com/foxyproxy/browser-extension/blob/main/README.md

To use grunt for building, install it locally in your project using npm with the command: 'npm i -D grunt-cli'.

```bash
npm i -D grunt-cli
```

--------------------------------

### Install Firefox Temporary Add-on

Source: https://github.com/foxyproxy/browser-extension/blob/main/README.md

For Firefox, go to about:debugging#/runtime/this-firefox, click 'Load Temporary Add-on...', and select manifest.json.

```bash
about:debugging#/runtime/this-firefox
```

--------------------------------

### Menus Module: Process Example Usage

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Illustrates how the process method handles a click event for a specific menu item, mapping it to a proxy function call.

```javascript
// Click on 'Include Host > Proxy 0'
process({menuItemId: 'includeHost0'}, tab)
// → Proxy.includeHost(pref, proxy, tab, 'includeHost')
```

--------------------------------

### Menus Module: AddProxies Example Menu Item

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Example structure for a proxy submenu item, including parent ID, unique ID, and display title.

```javascript
{
  parentId: 'includeHost',
  id: 'includeHost0',
  title: '🇺🇸 US Proxy'  // Flag + title
}
```

--------------------------------

### Import Proxy List (Simple Format)

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

Example of a simple proxy list format that can be imported into FoxyProxy. Each line represents a proxy, with host and port, and optionally username and password.

```plaintext
1.2.3.4:1080
example.com:443
example.com:3128:user:pass
```

--------------------------------

### Proxy Mode Examples

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/types.md

Demonstrates different proxy mode values and their corresponding formats for applying proxy settings.

```plaintext
mode: 'disable' - Proxy disabled
mode: 'pattern' - Use pattern matching
mode: 'proxy.example.com:8080' - Single proxy
mode: 'https://pac.example.com/proxy.pac' - PAC script
```

--------------------------------

### Example FoxyProxy Exported Preferences (JSON)

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/configuration.md

This JSON object represents an example of exported FoxyProxy preferences, including proxy server details, inclusion/exclusion patterns, and general settings.

```json
{
  "mode": "pattern",
  "sync": false,
  "autoBackup": false,
  "passthrough": "127.0.0.1/8, *.local",
  "theme": "dark",
  "container": {},
  "commands": {},
  "data": [
    {
      "active": true,
      "title": "US Proxy",
      "type": "socks5",
      "hostname": "us-proxy.example.com",
      "port": "1080",
      "username": "user1",
      "password": "pass1",
      "cc": "US",
      "city": "New York",
      "color": "#FF5733",
      "proxyDNS": true,
      "include": [
        {
          "type": "wildcard",
          "title": "Google",
          "pattern": "*.google.com/*",
          "active": true
        }
      ],
      "exclude": [],
      "tabProxy": []
    }
  ]
}
```

--------------------------------

### Complete FoxyProxy Flow Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/utilities.md

Demonstrates a complete workflow in FoxyProxy, including creating a proxy, updating appearance with flags and country names, validating patterns, viewing PAC scripts, and testing URLs against proxy patterns.

```javascript
// 1. User creates new proxy
const proxy = {
  active: true,
  title: 'My Proxy',
  hostname: 'proxy.example.com',
  port: '8080',
  cc: 'US',
  color: Color.getRandom()  // Random color
};

// 2. Action updates appearance
const flag = Flag.get(proxy.cc);        // 🇺🇸
const country = Location.get(proxy.cc); // United States
Action.set(pref);

// 3. Testing patterns
Pattern.validate('*.example.com', 'wildcard', true);

// 4. User views PAC script
PAC.view('https://pac.example.com/proxy.pac');

// 5. Tester shows which proxy applies
Tester.processURL(); // Tests URL against all patterns
```

--------------------------------

### Complete On Request Flow Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/on-request.md

Illustrates the step-by-step process of the on-request API handling a navigation event, including passthrough checks, cache lookups, container checks, and pattern matching.

```javascript
// 1. User navigates to https://mail.google.com
// 2. Firefox fires proxy.onRequest

process({
  url: 'https://mail.google.com',
  tabId: 5,
  incognito: false,
  cookieStoreId: 'firefox-default'
});

// 3. Check passthrough: '127.0.0.1/8, *.local'
//    mail.google.com not in passthrough 

// 4. Check tabProxy: tabId 5 not in cache 

// 5. Check container: incognito=false, no container proxy 

// 6. Check patterns: mode='pattern'
//    Iterate through this.data:
//    - Proxy 1: include='*.google.com', exclude='google.com'
//      match(exclude): google.com matches 
//    - Proxy 2: include='*.example.com'
//      match(include): mail.google.com doesn't match 

// 7. No pattern matched: return DIRECT

// 4. Browser connects to mail.google.com directly (no proxy)
```

--------------------------------

### Example Usage Flow: Setting Proxy

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Illustrates the sequence of events when a user changes proxy settings via the popup, how messages are handled, and how the browser action button is updated.

```javascript
// 1. User changes proxy in popup
// Popup sends: {id: 'setProxy', pref: {...}, dark: true}

// 2. Proxy.onMessage() receives message
static onMessage(message) {
  const {id, pref, dark} = message;
  if (id === 'setProxy') {
    Action.dark = dark;  // Set theme
    this.set(pref, noDataChange);  // Apply proxy and update action
  }
}

// 3. Proxy.set() completes proxy configuration
// Then calls: Action.set(pref)

// 4. Action.set() updates browser action appearance
set(pref) {
  // Set colors based on mode
  if (pref.mode === 'disable') {
    browser.action.setBadgeBackgroundColor({color: this.dark ? '#444' : '#fff'});
    browser.action.setTitle({title: 'Disabled'});
    browser.action.setBadgeText({text: '⛔'});
  }
}

// 5. Browser action button updated visually

```

--------------------------------

### Authentication Flow Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/authentication.md

Illustrates the step-by-step process from user credential input to successful request completion, including browser API interactions. This flow assumes credentials are set and a proxy challenge occurs.

```javascript
// 1. User sets proxy credentials in extension options
const proxyData = [
  {
    hostname: 'proxy.example.com',
    port: '8080',
    username: 'myuser',
    password: 'mypass',
    type: 'http',
    active: true
  }
];

// 2. Proxy.set() is called with updated preferences
Proxy.set({data: proxyData, ...});

// 3. Authentication.init() is called from Proxy.set()
Authentication.init(proxyData);
// this.data = {'proxy.example.com:8080': {username: 'myuser', password: 'mypass'}}

// 4. Browser makes request through proxy
// 5. Proxy server challenges with 407 Proxy Authentication Required
// 6. webRequest.onAuthRequired fires with:
// {
//   isProxy: true,
//   requestId: 'req-12345',
//   challenger: {host: 'proxy.example.com', port: 8080}
// }

// 7. Authentication.process() looks up credentials
// Returns: {authCredentials: {username: 'myuser', password: 'mypass'}}

// 8. Browser automatically retries request with credentials
// 9. Request succeeds, onCompleted fires
// 10. Authentication.clearPending() removes requestId from pending
```

--------------------------------

### Passthrough Rules Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/types.md

Illustrates various formats for defining passthrough rules, including URL patterns, CIDR notation, and special keywords.

```plaintext
127.0.0.1/8
192.168.0.0/16
*.local
<local>
localhost
example.com
```

--------------------------------

### Tester.process()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/utilities.md

Tests a single pattern against example URLs provided in the UI. It validates the pattern and highlights matches or misses.

```APIDOC
## Tester.process()

### Description
Tests a single pattern against example URLs.

### Method
`static process()`

### Behavior
- Reads pattern and type from UI
- Reads URLs from textarea
- Validates pattern using Pattern.validate()
- Tests each URL against pattern regex
- Colors matches green (pass) and misses red (fail)
```

--------------------------------

### Define Managed Storage Manifest

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

Example of a native manifest file used for provisioning managed storage settings for the extension.

```json
{
  "name": "foxyproxy@eric.h.jung",
  "description": "ignored",
  "type": "storage",
  "data": {
    "mode": "disable",
    "sync": false,
    "autoBackup": false,
    "passthrough": "",
    "theme": "",
    "container": {},
    "commands": {},
    "data": []
  }
}
```

--------------------------------

### Simplified Pattern Matching Logic

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/on-request.md

This simplified example illustrates the core logic for matching URLs against include and exclude patterns to determine the appropriate proxy. It prioritizes exclude patterns.

```javascript
// Example matching logic (simplified from process())
const match = (url) => 
  patterns.some(p => new RegExp(p, 'i').test(url));

for (const item of this.data) {
  if (!match(item.exclude) && match(item.include)) {
    return proxyInfo(item);
  }
}

return {type: 'direct'};
```

--------------------------------

### Browser Storage API Usage

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/configuration.md

JavaScript examples demonstrating how to interact with browser storage APIs for saving, loading, clearing, and removing preferences. Includes local, sync, and managed storage.

```javascript
// Save preferences
browser.storage.local.set(pref)

// Load preferences
browser.storage.local.get()

// Clear all
browser.storage.local.clear()

// Remove specific keys
browser.storage.local.remove(['key1', 'key2'])

// Sync storage (Firefox)
browser.storage.sync.set(syncObject)

// Managed storage (enterprise)
browser.storage.managed.get()
```

--------------------------------

### Browser Storage Schema Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/README.md

Illustrates the expected JSON schema for storing extension preferences in browser.storage.local. This schema includes settings for proxy mode, synchronization, backups, and UI themes.

```json
{
  "mode": "string",
  "sync": "boolean",
  "autoBackup": "boolean",
  "passthrough": "string",
  "theme": "string",
  "container": "object",
  "commands": "object",
  "data": "array"
}
```

--------------------------------

### Action.set() Example: Disabled Mode

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Demonstrates setting the action to 'disable' mode. This results in a prohibition emoji badge, a white background, and a 'Disabled' tooltip.

```javascript
// mode='disable'
set({mode: 'disable', ...});
// Badge: ⛔
// Color: #fff
// Title: "Disabled"
```

--------------------------------

### Visual Example: Direct Connection

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Illustrates the browser action button's appearance for a direct connection, featuring a right arrow emoji badge, a white background, and a 'DIRECT' title.

```text
Badge: ⮕
Background: White
Title: DIRECT
```

--------------------------------

### Import Proxy List (Extended Format with SOCKS5 and Parameters)

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

An example of the extended proxy import format using SOCKS5 protocol and including parameters for title, country code, and city.

```plaintext
socks5://100.10.11.12:1080?title=China&cc=CN&city=Beijing
```

--------------------------------

### Visual Example: Pattern Mode

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Shows the browser action button's state when using pattern-based routing, indicated by a globe emoji badge, a white background, and a 'By Patterns' title.

```text
Badge: 🌐
Background: White
Title: By Patterns
```

--------------------------------

### Run Grunt Build Targets

Source: https://github.com/foxyproxy/browser-extension/blob/main/README.md

Execute grunt commands to build specific targets. Examples include 'grunt --target=chrome-standard', 'grunt --target=chrome-basic', 'grunt --target=firefox-standard', and 'grunt --target=firefox-basic'.

```bash
grunt --target=chrome-standard
```

```bash
grunt --target=chrome-basic
```

```bash
grunt --target=firefox-standard
```

```bash
grunt --target=firefox-basic
```

--------------------------------

### Visual Example: Single Proxy (US)

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Depicts the browser action button for a single proxy connection, displaying a custom badge text (e.g., 'US Proxy'), a custom background color, and a detailed tooltip with proxy information.

```text
Badge: "US Proxy"
Background: Custom color (e.g., #FF5733)
Title: US Proxy
        proxy.example.com:8080
        New York
        United States
```

--------------------------------

### Static Class Pattern Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Demonstrates the static class pattern where modules are implemented as static classes without instantiation. This is used to ensure modules act as singletons and manage module-scoped global state.

```javascript
export class Proxy {
  static async set(pref) { ... }
  static async getSettings() { ... }
  static onMessage(message) { ... }
}

// Usage: Proxy.set(pref);  // Not new Proxy().set()
```

--------------------------------

### Conditional Logic for Firefox

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Example of how to use the `App.firefox` property to execute different code paths based on whether the extension is running in Firefox or another browser like Chrome.

```javascript
if (App.firefox) {
  // Use Firefox-specific APIs
  browser.proxy.onRequest.addListener(...);
} else {
  // Use Chrome PAC script approach
}
```

--------------------------------

### Event Listener Registration

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Shows how modules register event listeners within static initialization blocks. This pattern ensures automatic registration of listeners upon module import, simplifying module setup.

```javascript
export class Proxy {
  static {
    browser.runtime.onMessage.addListener((...e) => this.onMessage(...e));
  }
}
```

--------------------------------

### Action.set() Example: Single Proxy Mode

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Illustrates setting the action for a single proxy, including custom title, hostname, port, city, country, and a specific color. The badge text is derived from the proxy title or hostname, and the tooltip displays detailed proxy information.

```javascript
// mode='proxy.example.com:8080'
set({mode: 'proxy.example.com:8080', data: [
  {
    title: 'US Proxy',
    hostname: 'proxy.example.com',
    port: 8080,
    city: 'New York',
    cc: 'US',
    color: '#FF5733'
  }
], ...});
// Badge: "US Proxy" (or first 8 chars)
// Color: #FF5733
// Title: "US Proxy\nproxy.example.com:8080\nNew York\nUnited States"
```

--------------------------------

### Container Object Example

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/types.md

Example of the container object, which assigns specific proxies to incognito tabs and Firefox multi-container tabs.

```javascript
{
  incognito: "proxy.corp.com:8080",
  "container-1": "proxy-europe.example.com:3128",
  "container-2": "proxy-asia.example.com:3128"
}
```

--------------------------------

### App.firefox

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Boolean indicating if the extension is running in Firefox. This is determined by checking if the extension URL starts with 'moz-extension:'.

```APIDOC
## Static Property: firefox

### Description
Boolean indicating if running in Firefox.

### Value
`true` if extension URL starts with 'moz-extension:', `false` otherwise

### Detection Method
Checks extension protocol rather than user agent (more reliable in custom browsers)

### Example
```javascript
if (App.firefox) {
  // Use Firefox-specific APIs
  browser.proxy.onRequest.addListener(...);
}
```
```

--------------------------------

### Extension Startup Sequence

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Outlines the sequence of events during the browser extension's startup, from manifest loading to service worker initialization and the loading of option/popup pages.

```text
1. Browser loads extension manifest
2. background.js loaded as service worker
   ├─ All module files imported
   ├─ Static initializers run
   │  ├─ Event listeners registered
   │  ├─ Default state initialized
   │  └─ Persistence heartbeat started
   └─ Ready for events

3. Options/popup pages load on demand
   ├─ HTML parsed
   ├─ CSS applied
   ├─ JavaScript modules loaded
   └─ DOM event listeners attached
```

--------------------------------

### Menus.init()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Initializes context menus by storing preferences, clearing existing menus, and calling addMenus(). It returns early if on Android.

```APIDOC
## Menus.init()

### Description
Initializes context menus from the proxy list. It stores the provided preferences object, clears any existing menus, and then calls the `addMenus()` method.

### Method
`static init(pref)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
Menus.init(preferencesObject);
```

### Response
#### Success Response (void)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### getRange

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/pattern.md

Converts an IP address and netmask into a padded string representation of the start and end of the IP range. This is useful for network segmentation and filtering.

```APIDOC
## Static Method: getRange()

### Description
Converts an IP address and netmask to start/end padded string representation.

### Method Signature
`static getRange(ip, mask)`

### Parameters
#### Path Parameters
- **ip** (string) - Yes - IP address (e.g., "10.0.0.0")
- **mask** (string) - Yes - Netmask (e.g., "255.255.255.0")

### Return Type
[string, string] - Returns an array containing the start and end of the IP range as padded strings.

### Example
```javascript
getRange('192.168.0.0', '255.255.255.0')
// Returns: ['192168000000', '192168000255']

getRange('10.0.0.0', '255.255.0.0')
// Returns: ['010000000000', '010000255255']
```
```

--------------------------------

### Menus Module: Init Method Signature

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Initializes context menus by storing the preferences object and calling addMenus. Returns early on Android.

```javascript
static init(pref)
```

--------------------------------

### Import Proxy List (Extended Format with Parameters)

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

Demonstrates the extended format for importing proxies, including various parameters like type, color, title, and authentication details passed as URL query parameters.

```plaintext
http://1.2.3.4:1080
https://example.com:443
http://user:pass@1.2.3.4?color=663300
https://example.com:443?active=false&title=Work&username=abcd&password=1234&cc=US&city=Miami
```

--------------------------------

### Static Initialization of Authentication Listeners

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/authentication.md

Sets up webRequest listeners for proxy authentication challenges, completion, and errors during module load. This code runs once when the module is initialized.

```javascript
static {
  this.data = {};
  this.pending = {};
  
  // Listen for proxy auth challenges (HTTP/HTTPS/WS/WSS)
  // Chrome: HTTP/HTTPS only
  browser.webRequest.onAuthRequired.addListener(
    e => this.process(e),
    {urls: ['<all_urls>']},
    ['blocking']
  );
  
  // Clean up pending entries on completion
  browser.webRequest.onCompleted.addListener(
    e => this.clearPending(e),
    {urls: ['<all_urls>']}
  );
  
  // Clean up pending entries on error
  browser.webRequest.onErrorOccurred.addListener(
    e => this.clearPending(e),
    {urls: ['<all_urls>']}
  );
}
```

--------------------------------

### Convert IP and Netmask to Range

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/pattern.md

Converts an IP address and netmask into a start and end string representation of the IP range. This is useful for defining network segments.

```javascript
static getRange(ip, mask)
// Returns: ['192168000000', '192168000255']

getRange('192.168.0.0', '255.255.255.0')
// Returns: ['010000000000', '010000255255']

getRange('10.0.0.0', '255.255.0.0')
```

--------------------------------

### Authentication.init()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/authentication.md

Initializes the authentication credentials cache from a provided array of proxy data. It processes each proxy configuration, storing valid username and password combinations keyed by hostname and port.

```APIDOC
## Authentication.init(data)

### Description
Initializes authentication credentials from proxy data array.

### Method
Static

### Parameters
#### Path Parameters
- **data** (array) - Required - Array of proxy configuration objects from pref.data

### Behavior
- Clears existing this.data cache
- Iterates through data array
- For each proxy with hostname, port, username, and password: Stores credentials keyed as `"${hostname}:${port}"`
- Ignores proxies missing any of the required fields

### Constraints
Only processes HTTP/HTTPS proxy authentication (not SOCKS)

### Example
```javascript
const proxyData = [
  {hostname: 'proxy.corp.com', port: '8080', username: 'alice', password: 'secret'},
  {hostname: 'proxy2.corp.com', port: '3128', username: 'bob', password: 'pass'}
];
Authentication.init(proxyData);
// Now this.data = {
//   'proxy.corp.com:8080': {username: 'alice', password: 'secret'},
//   'proxy2.corp.com:3128': {username: 'bob', password: 'pass'}
// }
```
```

--------------------------------

### Visual Example: Disabled Proxy

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/action.md

Represents the visual state of the browser action button when the proxy is disabled, showing a prohibition emoji badge, a white background, and a 'Disabled' title.

```text
Badge: ⛔
Background: White
Title: Disabled
```

--------------------------------

### Import Proxy List (Extended Format with PAC URL)

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

Shows how to import a proxy configuration using a PAC URL, specifying the type as 'pac' and providing a title.

```plaintext
http://pac-url.com/etc?type=pac&title=Work PAC&color=663300
```

--------------------------------

### OnRequest.init(pref)

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/on-request.md

Initializes the OnRequest class with preference settings. This method parses proxy configurations, passthrough rules, and sets the operational mode based on the provided preferences object.

```APIDOC
## OnRequest.init(pref)

### Description
Initializes OnRequest state from preferences for pattern matching. This method configures the proxy mode, passthrough rules, and proxy data based on the input preferences.

### Method
Static Method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **pref** (object) - Required - Full preferences object

### Return Type
void

### Behavior
1. Sets mode from pref.mode
2. Parses passthrough rules via Pattern.getPassthrough()
3. Determines single proxy from pref.mode or sets to false
4. Filters data to active proxies with patterns
5. Extracts and transforms proxy fields for pattern matching
6. Sets incognito/container proxies from pref.container

### Example
```javascript
const pref = {
  mode: 'pattern',
  passthrough: '127.0.0.1/8, *.local',
  data: [
    {
      active: true,
      type: 'socks5',
      hostname: 'proxy1.example.com',
      port: '1080',
      username: 'user1',
      password: 'pass1',
      include: [{pattern: '*.example.com', type: 'wildcard', active: true}],
      exclude: [{pattern: 'internal.example.com', type: 'wildcard', active: true}],
      title: 'Proxy 1'
    }
  ]
};

OnRequest.init(pref);
// OnRequest.mode = 'pattern'
// OnRequest.passthrough = regex patterns
// OnRequest.data = transformed proxy array with active patterns
```
```

--------------------------------

### Copy Manifest File (Version 8.0-8.10)

Source: https://github.com/foxyproxy/browser-extension/blob/main/README.md

For older versions (8.0-8.10) without grunt, copy the appropriate manifest file to manifest.json. For example, use 'mv manifest-chrome.json manifest.json'.

```bash
mv manifest-chrome.json manifest.json
```

--------------------------------

### Open All Proxies

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

Run this JavaScript in the developer console to expand all proxy entries in the FoxyProxy options, making them visible and easier to manage.

```javascript
document.querySelectorAll('details.proxy').forEach(i => i.open = true)
```

--------------------------------

### App.basic

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Boolean indicating if this is the FoxyProxy Basic version. This is determined by comparing the extension's manifest name with the localized string for 'FoxyProxy Basic'.

```APIDOC
## Static Property: basic

### Description
Boolean indicating if this is the FoxyProxy Basic (limited) version.

### Value
`true` if manifest name equals 'FoxyProxy Basic' localization string

### Purpose
Differentiates between Standard and Basic extension variants

### Usage
Basic version disables pattern-based proxy and related features
```

--------------------------------

### Get Random CSS Color

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/utilities.md

Use `Color.getRandom()` to obtain a random hex color code from a predefined palette of 140 distinct colors. This is useful for assigning unique colors to new proxies.

```javascript
static getRandom()

```

```javascript
const randomColor = Color.getRandom();
// Returns something like "#FF5733" or "#7CFC00"
// Used when creating new proxy with auto-assigned color

```

--------------------------------

### Module Export Patterns

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Examples of different module export patterns, including exporting a single class, an exported constant, or re-exporting from other modules. This follows the Module Export Pattern for clear code organization.

```javascript
export class Proxy { ... }           // Single class
export const pref = { ... };         // Exported constant
export {App} from './app.js';        // Re-export
```

--------------------------------

### Get Default Preferences Copy

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Returns a new, unfettered copy of the default preferences object. Use this when you need a clean set of defaults without modifying the module's global `pref` object.

```javascript
static getDefaultPref()
```

--------------------------------

### Setting a Proxy Configuration

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/README.md

Loads current preferences, modifies the proxy mode, and applies the new settings using the Proxy.set method. Ensure preferences are loaded before modification.

```javascript
import {Proxy} from './proxy.js';

// Load current preferences
const pref = await browser.storage.local.get();

// Change proxy mode
pref.mode = 'proxy.example.com:8080';

// Apply the proxy
await Proxy.set(pref);
```

--------------------------------

### Get Browser Proxy Settings

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/proxy.md

Retrieves current proxy settings and control level from the browser API. Returns null on Chrome if the extension doesn't control proxy settings, or an empty object on Android.

```javascript
static async getSettings()
```

```javascript
const settings = await Proxy.getSettings();
if (settings && settings.levelOfControl === 'controlled_by_this_extension') {
  // We control the proxy
}
```

--------------------------------

### Proxy.getSettings()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/proxy.md

Retrieves the current proxy settings and the level of control the extension has over them from the browser's API.

```APIDOC
## Proxy.getSettings()

### Description
Retrieves current proxy settings and control level from the browser API. Returns the settings object if the extension controls the proxy, null on Chrome if not controlled, or an empty object on Android.

### Method
`static async getSettings()`

### Parameters
None

### Request Example
```javascript
const settings = await Proxy.getSettings();
if (settings && settings.levelOfControl === 'controlled_by_this_extension') {
  // We control the proxy
}
```

### Response
#### Success Response (object|null)
- **levelOfControl** (string) - Indicates the control level: 'controlled_by_this_extension', 'controllable_by_this_extension', or other values.
- **value** (object) - The current proxy configuration.
Returns null on Chrome if proxy.settings is not controlled by this extension. Returns an empty object on Android.

#### Response Example
```json
{
  "levelOfControl": "controlled_by_this_extension",
  "value": {
    "mode": "direct"
  }
}
```
```

--------------------------------

### FoxyProxy Architecture Diagram

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Illustrates the layered architecture of the FoxyProxy browser extension, from the UI to the browser/platform layer.

```text
┌─────────────────────────────────────────┐
│         Browser Extension UI             │
│  (popup.html, options.html, menus, etc.) │
└────────────┬────────────────────────────┘
             │
┌────────────▼──────────────────────────────┐
│    Extension Logic (JavaScript Modules)   │
│  - Proxy management (proxy.js)            │
│  - Pattern matching (pattern.js)          │
│  - Authentication (authentication.js)     │
│  - Import/Export (import-export.js)       │
│  - User interaction (menus, commands)     │
└────────────┬──────────────────────────────┘
             │
┌────────────▼──────────────────────────────┐
│      Browser Native APIs (WebExtensions)  │
│  - browser.proxy.settings (set proxies)   │
│  - browser.storage (persist data)         │
│  - browser.proxy.onRequest (route reqs)   │
│  - browser.webRequest (intercept reqs)    │
│  - browser.contextMenus (context menu)    │
└────────────┬──────────────────────────────┘
             │
┌────────────▼──────────────────────────────┐
│         Browser/Platform Layer            │
│  - Firefox, Chrome, Edge, Chromium        │
└──────────────────────────────────────────┘
```

--------------------------------

### Get Country Name from ISO Country Code

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/utilities.md

The `Location.get()` method retrieves the full country name corresponding to a two-letter ISO 3166-1 country code. It returns an empty string if the code is not found or is empty.

```javascript
static get(cc = '')

```

```javascript
Location.get('US')    // → "United States"
Location.get('GB')    // → "United Kingdom"
Location.get('JP')    // → "Japan"
Location.get('XX')    // → "" (not found)
Location.get('')      // → "" (empty)

```

--------------------------------

### Default Preferences Template

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Defines the structure and default values for FoxyProxy preferences. Used for initializing extension storage.

```javascript
export const pref = {
  mode: 'disable',
  sync: false,
  autoBackup: false,
  passthrough: '',
  theme: '',
  container: {},
  commands: {},
  data: []
}
```

--------------------------------

### Passthrough String Formats

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/configuration.md

Examples of global proxy bypass rules using various formats including domain, wildcard domain, local keyword, CIDR notation, and port patterns. Separators can be whitespace, commas, or semicolons.

```text
192.168.0.0/16, 10.0.0.0/8, *.local, localhost
```

```text
127.0.0.1/8; example.com; <local>
```

```text
example.com example2.com 127.0.0.1/8
```

--------------------------------

### Browser Action Visual States

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Illustrates the different visual states of the extension icon badge and tooltip.

```text
Visual States:
- Disabled: ⛔ (red circle)
- Direct:   ⮕ (arrow)
- Pattern:  🌐 (globe)
- Single Proxy: Proxy title/name
```

--------------------------------

### Menus.process()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Handles clicks on context menu items by determining the action type from the menu ID and executing the corresponding proxy operation.

```APIDOC
## Menus.process()

### Description
Handles context menu item clicks. It extracts the `menuItemId` from the `info` object to determine the action and the proxy index, then calls the appropriate method in `Proxy.js` or `OnRequest.js`.

### Method
`static async process(info, tab)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Example click on 'Include Host > Proxy 0'
Menus.process({ menuItemId: 'includeHost0' }, currentTab);
// This would trigger Proxy.includeHost(pref, proxy, tab, 'includeHost');
```

### Response
#### Success Response (void)
This method is asynchronous and handles actions internally; it does not return a specific value upon successful execution of an action.

#### Response Example
None
```

--------------------------------

### Menus Module: Process Method Signature

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Handles clicks on context menu items by determining the action and calling the appropriate proxy or request handling method.

```javascript
static async process(info, tab)
```

--------------------------------

### Menus.addMenus()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Builds and registers all context menu items based on active, non-PAC proxies. It dynamically creates menu items for pattern features and tab proxy options, including submenus for each proxy.

```APIDOC
## Menus.addMenus()

### Description
Builds and registers all context menu items. It filters proxies, constructs menu items based on browser and feature availability (like pattern features and tab proxy options), and adds submenus for each proxy.

### Method
`static addMenus(data)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
Menus.addMenus(proxyDataArray);
```

### Response
#### Success Response (void)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Process Context Menu Click

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Handles the logic when a user right-clicks and selects a context menu item. It extracts proxy data and calls the Proxy.includeHost function.

```javascript
// User right-clicks on a page
// → contextMenus.onClicked fires
// → Menus.process(info, tab) called

process({menuItemId: 'includeHost0'}, tab) {
  // Extract proxy index: 0
  const proxy = this.data[0];
  
  // Call Proxy.includeHost()
  Proxy.includeHost(pref, proxy, tab, 'includeHost');
  
  // Result: Added pattern to proxy.include
  // Proxy reapplied on next request
}
```

--------------------------------

### Initialize Authentication Credentials

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/authentication.md

Initializes the authentication data cache from an array of proxy configurations. It processes proxies with hostname, port, username, and password, ignoring others. This method is intended for HTTP/HTTPS proxies only.

```javascript
const proxyData = [
  {hostname: 'proxy.corp.com', port: '8080', username: 'alice', password: 'secret'},
  {hostname: 'proxy2.corp.com', port: '3128', username: 'bob', password: 'pass'}
];
Authentication.init(proxyData);
// Now this.data = {
//   'proxy.corp.com:8080': {username: 'alice', password: 'secret'},
//   'proxy2.corp.com:3128': {username: 'bob', password: 'pass'}
// }

```

--------------------------------

### Manifest Keyboard Commands Configuration

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Defines the available keyboard commands and their descriptions within the browser extension's manifest.json file. These commands are user-configurable in browser settings.

```json
{
  "commands": {
    "proxyByPatterns": {
      "description": "__MSG_proxyByPatterns__"
    },
    "disable": {
      "description": "__MSG_disable__"
    },
    "setProxy": {
      "description": "__MSG_setProxy__"
    },
    "includeHost": {
      "description": "__MSG_includeHost__"
    },
    "excludeHost": {
      "description": "__MSG_excludeHost__"
    },
    "setTabProxy": {
      "description": "__MSG_setTabProxy__"
    },
    "unsetTabProxy": {
      "description": "__MSG_unsetTabProxy__"
    }
  }
}
```

--------------------------------

### Load User Preferences

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Asynchronously loads user preferences from the browser's local storage and updates the module's `pref` object. This operation is asynchronous due to storage access.

```javascript
static async getPref() {
  await App.getPref();
  console.log(pref.mode); // Current saved mode
}
```

--------------------------------

### Module Dependency Graph

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Visualizes the dependencies between different JavaScript modules in the FoxyProxy browser extension, showing the entry points and their relationships.

```text
background.js (entry point)
├── proxy.js (core)
│   ├── app.js
│   ├── authentication.js
│   ├── on-request.js
│   ├── pattern.js
│   ├── action.js
│   └── menus.js
├── authentication.js
├── on-request.js (Firefox)
├── pattern.js
├── action.js
├── menus.js
└── commands.js

options.js (options page)
├── app.js
├── proxy.js
├── proxies.js
├── pattern.js
├── import-export.js
├── location.js
├── flag.js
├── color.js
├── pac.js
├── tester.js
└── [UI modules]

popup.js (popup UI)
├── app.js
├── proxy.js
├── location.js
├── flag.js
└── [UI modules]

log.js (log tab)
├── pattern.js
├── flag.js
└── popup.js
```

--------------------------------

### Authentication.process()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/authentication.md

Handles incoming authentication challenges from the webRequest API. It checks for pending requests to prevent loops and returns credentials if found, or a cancellation signal.

```APIDOC
## Authentication.process(e)

### Description
Handles authentication challenges from the webRequest API.

### Method
Static

### Parameters
#### Path Parameters
- **e** (object) - Required - webRequest.onAuthRequired event object

### Event Properties Used
- **isProxy** (boolean) - true for Proxy-Authenticate challenge, false for WWW-Authenticate
- **requestId** (string) - Unique request identifier
- **challenger** (object) - {host, port} of the proxy server

### Returns
- `{authCredentials: {username, password}}` if credentials found and not pending
- `{cancel: true}` if request already pending (prevent loop)
- undefined (no response) if no credentials found

### Behavior
1. Returns early if not a proxy authentication challenge (isProxy=false)
2. Sends message to log.js for logging
3. Checks if requestId is in pending cache:
   - If yes: Returns {cancel: true} to stop the request
   - If no: Marks requestId in pending, looks up credentials
4. Returns authCredentials or undefined based on lookup

### Side Effects
- Sends message with id='onAuthRequired' to log.js
- Updates this.pending cache

### Example
```javascript
// Event from proxy server authentication challenge
const event = {
  isProxy: true,
  requestId: '123',
  challenger: {host: 'proxy.corp.com', port: 8080}
};
const result = Authentication.process(event);
// Returns: {authCredentials: {username: 'alice', password: 'secret'}}
```
```

--------------------------------

### On-Request Routing Decision Flow (Firefox)

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/ARCHITECTURE.md

Explains the per-request routing logic in Firefox, including checks for passthrough rules, tab proxies, and global patterns.

```text
Browser makes HTTP/HTTPS request
    ↓
Firefox fires proxy.onRequest event
    ↓
OnRequest.process(requestDetails) called
    ↓
Check passthrough rules → return DIRECT if match
Check tab proxy patterns → return if match
Check container proxy → return if match
Check global patterns → return first match
    ↓
Return ProxyInfo object or undefined
    ↓
Browser connects through returned proxy
```

--------------------------------

### set(pref, mode)

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/menus-commands.md

Activates a specific proxy mode via keyboard shortcut. This method updates the proxy mode, saves it to storage, and can optionally trigger proxy updates.

```APIDOC
## Static Method: set(pref, mode)

### Description
Activates a proxy mode using the provided preferences and mode string. This method updates the current proxy mode, saves the change to `browser.storage.local`, and can trigger proxy updates.

### Method Signature
`static set(pref, mode)`

### Parameters
#### Path Parameters
* **pref** (object) - Required - The preferences object.
* **mode** (string) - Required - The new proxy mode to activate. Accepted values are 'disable', 'direct', 'pattern', or 'host:port'.

### Return Type
`void`

### Behavior
1. Updates `pref.mode` to the new value.
2. Saves the new mode to `browser.storage.local`.
3. Calls `Proxy.set(pref, true)` with `noDataChange=true` to potentially skip menu and auth updates for performance.

### Example
```javascript
set(pref, 'pattern')  // Activate pattern mode
set(pref, 'disable')  // Disable proxy
```
```

--------------------------------

### Browser Storage Structure for Preferences

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/app.md

Shows the exact structure of preferences as saved in `browser.storage.local`, detailing fields like proxy mode, sync settings, and container configurations.

```javascript
// Saved to browser.storage.local
{
  mode: "disable",
  sync: false,
  autoBackup: false,
  passthrough: "",
  theme: "dark",
  container: { incognito: "proxy1:8080" },
  commands: { setProxy: "proxy1:8080" },
  data: [
    {
      active: true,
      title: "Proxy 1",
      hostname: "proxy1.example.com",
      port: "8080",
      ...
    }
  ]
}
```

--------------------------------

### ImportExport.init()

Source: https://github.com/foxyproxy/browser-extension/blob/main/_autodocs/api-reference/import-export.md

Initializes the ImportExport functionality by attaching event listeners to UI elements for file input and export actions. It requires the preferences object and a callback function to be executed after a successful import.

```APIDOC
## Static Method: init()

Initializes ImportExport by attaching event listeners to UI elements.

### Method Signature
```javascript
static init(pref, callback)
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **pref** (object) - Required - Preferences object reference (mutated during import)
- **callback** (function) - Required - Function to call after successful import

### Return Type
void

### Behavior
- Stores callback reference
- Attaches 'change' listener to element with id='file'
- Attaches 'click' listener to element with id='export'

### Example
```javascript
const pref = {...};
ImportExport.init(pref, () => {
  browser.storage.local.set(pref);
  console.log('Import complete');
});
```
```

--------------------------------

### Configure Enterprise Policies for Chrome and Firefox

Source: https://github.com/foxyproxy/browser-extension/blob/main/src/content/help.html

JSON policy templates for managing FoxyProxy extensions via enterprise policy files.

```json
{

  "3rdparty": {
    "extensions": {
      "gcknhkkoolaabfmlnjonogaaifnjlfnp": {
        "mode": "pattern",
        "data": []
      }
    }
  }

}
```

```json
{
  "policies": {
    "3rdparty": {
      "Extensions": {
        "foxyproxy@eric.h.jung": {
          "mode": "pattern",
          "data": []
        }
      }
    }
  }
}
```