docs: add JSDoc to undocumented module-level constants in background.js

[Copilot]

The six module-level constants at the top of background.js had no documentation, forcing developers to infer purpose, units, and impact from usage context alone — increasing misconfiguration risk.

Changes

• initialHostByRequest — multi-line JSDoc with @type {Map<string, {host: string, trackedAt: number}>} and lifecycle notes (cleared on completion, error, or TTL expiry)
• MAX_TRACKED_REQUESTS — inline doc noting LRU eviction trigger
• REQUEST_TRACK_TTL_MS — inline doc with explicit millisecond unit; 1000 → 1_000 for readability
• STORAGE_KEY — inline doc identifying the browser.storage.sync key
• exceptionDomains — multi-line JSDoc with @type {Set<string>}, startup population, and storage.onChanged sync
• DEFAULT_ACCEPT_LANGUAGE — multi-line JSDoc noting fallback role and RFC 4647 syntax

All comments follow the existing style established by ACCEPT_LANGUAGE_BY_TLD (no dash in @param, consistent block formatting).

/**
 * Tracks the hostname of the first request for each active requestId.
 * Cleared on request completion, error, or TTL expiry.
 * @type {Map<string, {host: string, trackedAt: number}>}
 */
const initialHostByRequest = new Map();

/** Maximum number of concurrent request IDs tracked before LRU eviction. */
const MAX_TRACKED_REQUESTS = 1000;

/** Time-to-live for a tracked request entry, in milliseconds (60 s). */
const REQUEST_TRACK_TTL_MS = 60 * 1_000;

/** `browser.storage.sync` key under which exception domains are persisted. */
const STORAGE_KEY = "exceptionDomains";

/**
 * In-memory set of root domains excluded from redirect blocking and header spoofing.
 * Populated at startup and kept in sync via `storage.onChanged`.
 * @type {Set<string>}
 */
const exceptionDomains = new Set();

/**
 * Fallback Accept-Language value used when no TLD-specific mapping is found.
 * Follows RFC 4647 syntax.
 */
const DEFAULT_ACCEPT_LANGUAGE = "en-US,en;q=0.9";

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[PATCH] Module-level constants in background.js lack JSDoc comments</issue_title>
<issue_description>Category: documentation
Severity: patch
File(s): background.js (l.1–10)

Description

The top-level configuration constants (MAX_TRACKED_REQUESTS, REQUEST_TRACK_TTL_MS, STORAGE_KEY, DEFAULT_ACCEPT_LANGUAGE) have no JSDoc or inline comments explaining their purpose, units, or impact. Developers modifying the extension must infer intent from usage context alone, increasing the risk of misconfiguration (e.g. misunderstanding that REQUEST_TRACK_TTL_MS is in milliseconds, or the effect of lowering MAX_TRACKED_REQUESTS).

ACCEPT_LANGUAGE_BY_TLD already has a thorough JSDoc block — the other constants should follow the same standard.

Problematic code example

const initialHostByRequest = new Map();
const MAX_TRACKED_REQUESTS = 1000;
const REQUEST_TRACK_TTL_MS = 60 * 1000;
const STORAGE_KEY = "exceptionDomains";
const exceptionDomains = new Set();
const DEFAULT_ACCEPT_LANGUAGE = "en-US,en;q=0.9";

Suggested fix

/**
 * Tracks the hostname of the first request for each active requestId.
 * Cleared on request completion, error, or TTL expiry.
 * @type {Map<string, {host: string, trackedAt: number}>}
 */
const initialHostByRequest = new Map();

/** Maximum number of concurrent request IDs tracked before LRU eviction. */
const MAX_TRACKED_REQUESTS = 1000;

/** Time-to-live for a tracked request entry, in milliseconds (default: 60 s). */
const REQUEST_TRACK_TTL_MS = 60 * 1_000;

/** `browser.storage.sync` key under which exception domains are persisted. */
const STORAGE_KEY = "exceptionDomains";

/**
 * In-memory set of root domains excluded from redirect blocking and header spoofing.
 * Populated at startup and kept in sync via `storage.onChanged`.
 * @type {Set<string>}
 */
const exceptionDomains = new Set();

/**
 * Fallback Accept-Language value used when no TLD-specific mapping is found.
 * Follows RFC 4647 syntax.
 */
const DEFAULT_ACCEPT_LANGUAGE = "en-US,en;q=0.9";

Acceptance criteria

• All six module-level constants have JSDoc or inline comments
• Units are explicit for time-based values (milliseconds)
• Comments follow the existing JSDoc style in the file</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [PATCH] Module-level constants in background.js lack JSDoc comments #142

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR improves readability of the extension’s background script by adding clarifying JSDoc/comments around request tracking, storage keys, and Accept-Language defaults, plus a minor constant formatting tweak.

Changes:

• Added JSDoc/type annotations and explanatory comments for key globals (initialHostByRequest, exceptionDomains, etc.).
• Clarified constant intent (TTL meaning, storage key purpose, Accept-Language fallback).
• Reformatted the TTL constant to use numeric separators (60 * 1_000).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.