docs: update README and AGENTS to reflect MV2 architecture, context menu quick actions, options, and release workflow

AGENTS.md

@@ -1,49 +1,89 @@
-# Repository Guidelines
+# Contributor Guide & Philosophy
 
-## Project Structure & Module Organization
+This add-on helps you collect and filter links from archive.org `https://archive.org/download/*` pages, then copy them or send them to an aria2 RPC server. The project is Firefox-first, docs-first, and aims to stay lean and privacy‑respecting.
 
-- Root: `manifest.json`, `package.json` (when added), config files.
+## Architecture Overview
-- `src/`: extension code.
-  - `background/`: RPC, messaging, and long‑lived tasks.
-  - `content/`: archive.org DOM parsing on `/download/*` pages.
-  - `popup/` and `options/`: UI, settings, and actions.
-  - `lib/`: shared utils (filters, size/date parsing, aria2 client).
-- `assets/`: icons and static resources.
-- `tests/`: unit (`tests/unit`) and e2e (`tests/e2e`).
-- Note: initial repo is docs-first; scaffolding will create these paths.
 
-## Build, Test, and Development Commands
+- Manifest: Firefox Manifest V2 (for stability and background script support).
+- Background (MV2, non-module): `src/background/index.js` handles messaging, context menu, on-demand content script injection, and delegates aria2 calls to globals from `src/lib/aria2-bg.js`.
+- Content script: `src/content/collect.js` scrapes the download listing DOM and returns items `{ url, name, type, sizeText?, dateText? }`.
+- Popup UI: `src/popup/*` lets users filter by name/type (string or regex), size, and date, preview matches, copy links, or send to aria2.
+- Options page: `src/options/*` manages aria2 endpoint/secret, “Default Action” (download vs copy), and an “Include metadata in All” toggle; includes a connection test for aria2 with HTTPS‑Only hints.
+- Shared utils: `src/lib/filters.js` (matchers, size/date parsing) and `src/lib/aria2.js` (JSON‑RPC helpers). `src/lib/aria2-bg.js` exposes background‑safe helpers on `globalThis`.
 
-- Install: `npm install` (after `package.json` lands).
+### Messaging and Flow
-- Dev (Firefox): `npx web-ext run --source-dir .` or `npm run dev`.
-- Build: `npx web-ext build -o -a dist` or `npm run build` → `dist/`.
-- Lint/Format: `npm run lint` and `npm run format`.
-- Tests: `npm test` (Jest). E2E via Playwright: `npm run test:e2e`.
 
-## Coding Style & Naming Conventions
+- Popup → Content: try `collectLinks` first; if no receiver exists, Popup → Background → inject content → retry collect.
+- Popup → Background: `aria2.send` wraps `aria2.addUri` calls (batch) and keeps secrets out of page context.
+- Context menu: parent "Collect links…" with a dynamic submenu built per page ("Download/Copy All" and top file types).
 
-- Language: JavaScript (ES2020+) or TypeScript (preferred for new modules).
+### Storage Keys
-- Indentation: 2 spaces; max line length 100; use semicolons.
-- Filenames: kebab-case (`filters-utils.ts`, `aria2-client.ts`). UI components: PascalCase.
-- Identifiers: camelCase; UPPER_SNAKE_CASE for constants; verbs for functions.
-- Tools: ESLint + Prettier. Run `npm run lint` before pushing.
 
-## Testing Guidelines
+- `aria2`: `{ endpoint, secret }` in `browser.storage.local`.
+- `prefs`: `{ defaultAction: 'download'|'copy', allIncludeMeta: boolean }`.
+- `lastCollected`/`lastItems`: background stores the last collection stats and items to support quick actions and badges.
 
-- Framework: Jest for unit tests; Playwright for e2e (popup/content behaviors).
+## Design Principles
-- Location: unit under `tests/unit/**/*.spec.(js|ts)`; e2e under `tests/e2e/**`.
-- Coverage: target ≥ 80% lines for core filters and RPC client.
-- Focus: filename/type regex, size/date filters, clipboard, and `aria2.addUri` payloads.
 
-## Commit & Pull Request Guidelines
+- Firefox-first: target Firefox with MV2; revisit MV3 later if appropriate.
+- Minimal footprint: no heavy frameworks; keep UI simple and dependency‑light.
+- Privacy by default: no analytics; tokens stored in `storage.local`; users own their data.
+- Robust UX: inject content on demand; show actionable error messages (e.g., HTTPS‑Only hints).
+- Clear boundaries: background mediates network and privileged actions; content stays read‑only.
+- Docs-first: keep README and this guide authoritative; code mirrors described behaviors.
 
-- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`). Use imperative mood.
+## Repository Layout (current)
-- PRs: concise description, motivation, screenshots/GIFs for UI, test plan, and linked issues.
-- Scope: keep PRs small and focused; update docs when behavior changes.
 
-## Security & Configuration Tips
+- Root: `manifest.json`, `package.json`, `LICENSE`, `README.md`, `.env.example`, `releases/`, `scripts/`.
+- `src/`
+  - `background/index.js`
+  - `content/collect.js`
+  - `popup/` (`index.html`, `index.js`, `styles.css`)
+  - `options/` (`index.html`, `index.js`, `styles.css`)
+  - `lib/` (`filters.js`, `aria2.js`, `aria2-bg.js`)
 
-- Do not commit secrets. Store aria2 RPC token in `browser.storage.local`.
+Note: There is no `tests/` directory yet. See “Testing” below for priorities.
-- Prefer HTTPS for remote RPC; if self-signed, document trust steps locally only.
+
-- Provide examples as `config.example.json`; ignore local overrides in `.gitignore`.
+## Development
+
+- Install: `npm install`
+- Dev (Firefox): `npm run dev` (starts Firefox with `web-ext run`)
+- Build: `npm run build` → artifacts in `dist/`
+- Lint (AMO): `npm run lint:fx`
+- Local release: see “Release & Signing”
+
+## Coding Style
+
+- Language: JavaScript (ES2020+). TypeScript may be introduced later; keep modules TS‑friendly.
+- Conventions: 2 spaces; max line length ~100; semicolons; kebab-case filenames; camelCase identifiers; UPPER_SNAKE_CASE for constants; verbs for functions.
+- Dependencies: keep minimal; prefer DOM APIs and small modules in `src/lib`.
+- Structure: small functions, early returns for clarity; avoid incidental coupling between popup/background/content.
+
+## Testing
+
+Tests are not yet implemented. Priorities when adding tests:
+
+- Unit (Jest): `src/lib/filters.js` (matchers, size/date parsing) and `src/lib/aria2.js` (payloads, token handling).
+- Integration (web‑ext + Playwright): popup filtering behavior on a fixture page; content collector DOM parsing; context menu quick actions update and badge counts.
+- Coverage targets: ≥80% for filters and aria2 client.
+
+Suggested scripts (future): `npm test`, `npm run test:e2e` with Playwright.
+
+## Security & Permissions
+
+- Do not commit secrets; use `.env` only for local signing. The aria2 secret is stored in `browser.storage.local`.
+- Prefer HTTPS for remote aria2 RPC. For self‑signed certs, document local trust steps only.
+- Manifest host permissions include `archive.org` and wildcard entries to allow non‑local RPC endpoints. If repackaging, scope these down to intended hosts.
+- Firefox HTTPS‑Only Mode can upgrade `http://` to `https://` for non‑local hosts; the options page surfaces guidance.
+
+## Release & Signing
+
+- Add‑on ID and updates: `applications.gecko.id = "archive-org-link-grabber@jordanwages.com"` and `applications.gecko.update_url` points to the self‑hosted updates JSON.
+- Scripts: `release:prepare:*` (syncs `manifest.json`), `release:sign` (creates XPI under `releases/<version>/`).
+- Secrets: set `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` locally (see `.env.example`); never commit them.
+
+## Commit & PR Guidelines
+
+- Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`.
+- Keep PRs small and focused; include motivation, UX screenshots for UI changes, test plan, and linked issues.
 

README.md

@@ -1,6 +1,6 @@
 # Archive.org Link Grabber (Firefox WebExtension)
 
-Add-on for Firefox that enhances archive.org download pages (https://archive.org/download/*) so you can filter file links (by type, name, size, or date), copy them to the clipboard (one URL per line), or send them directly to an aria2 RPC server.
+Add-on for Firefox that enhances archive.org download pages (https://archive.org/download/*) so you can filter file links (by type, name, size, or date), copy them to the clipboard (one URL per line), or send them directly to an aria2 RPC server. It also adds context‑menu quick actions on archive.org pages.
 
 > Status: README/spec first. Implementation details below describe the intended behavior and structure.
 
@@ -14,6 +14,7 @@ Add-on for Firefox that enhances archive.org download pages (https://archive.org
 - Send to aria2: forward links to a configured aria2 JSON-RPC endpoint using a secret token.
 - Per-site parsing: targets archive.org collection download listings under `/download/*`.
 - Persistent settings: stores filter presets and aria2 config in extension storage.
+- Context menu: "Collect links…" with dynamic quick actions on archive.org pages. It offers "Download/Copy All" and type‑specific actions for the most common file types on the page.
 
 ## Demo Workflow
 
@@ -27,6 +28,9 @@ Add-on for Firefox that enhances archive.org download pages (https://archive.org
 5. Choose an action:
    - Copy: copies selected URLs to the clipboard, one per line.
    - Send to aria2: pushes to your configured aria2 RPC server using `aria2.addUri`.
+   - Or use the page’s context menu: right‑click → "Collect links…" for quick "All" or top‑type actions.
+
+Tip: The browser action badge shows counts when collecting/sending via context menu quick actions.
 
 ## Regex and Matching
 
@@ -74,7 +78,7 @@ The extension will require:
 - `https://archive.org/*` host permission to read and parse download pages.
 - `storage` to persist settings and presets.
 - `clipboardWrite` to copy links.
-- Host permission for your aria2 endpoint (e.g., `http://localhost:6800/*` or your remote URL). Optional permissions may be requested at runtime.
+- Host permission for your aria2 endpoint (e.g., `http://localhost:6800/*` or your remote URL). The manifest currently includes wildcard entries to support non‑local RPC during development; when repackaging, consider scoping to intended hosts.
 
 ## Parsing Strategy
 
@@ -82,7 +86,17 @@ The extension will require:
 - It scrapes the file listing table/DOM and builds a dataset with name, URL, size, and date.
 - Type is derived from filename extension (and may use content-type hints if available on the page).
 - The popup UI queries this dataset, applies filters, and displays the results.
-- A background script handles aria2 RPC calls to avoid CORS issues and keep secrets out of content scope.
+- The background script handles aria2 RPC calls to avoid CORS issues and keep secrets out of content scope.
+- If the content script isn’t present yet, the background injects it on demand and retries collection.
+
+## Options
+
+Open the Options page (from the popup link or `about:addons`):
+
+- Default Action: choose whether quick actions Download via aria2 or Copy to clipboard.
+- Include metadata in “All”: include archive.org’s metadata files in the “All” quick action.
+- aria2 endpoint and secret: persisted to `browser.storage.local`.
+- Test Connection: calls `aria2.getVersion` and surfaces guidance for Firefox HTTPS‑Only Mode when using non‑local HTTP endpoints.
 
 ## Installation (Temporary in Firefox)
 
@@ -119,10 +133,16 @@ For development, make changes and click “Reload” in `about:debugging` to pic
 
 ## Development Notes
 
-- Tech stack: Standard WebExtension (manifest v3 when supported in Firefox; otherwise v2), with content script + background/service worker + popup UI.
+- Tech stack: Standard WebExtension. Currently Manifest V2 in Firefox, with content script + background script + popup UI.
 - Storage: `browser.storage.local` for settings and aria2 configs; no analytics.
 - Code style: keep dependencies minimal; prefer modern, framework-light UI for the popup.
 
+### Architecture specifics
+
+- Background is a non‑module MV2 script. `src/lib/aria2-bg.js` exposes `addUri`, `addUrisBatch`, and `getVersion` on `globalThis` for background use.
+- Context menu parent: "Collect links…" appears on archive.org `/download/*` pages; submenu is rebuilt dynamically for top file types per page.
+- BrowserAction badges show counts and state after collecting, copying, or sending.
+
 ## Contributing
 
 Issues and PRs are welcome. If proposing new filters or aria2 options, please include example pages and expected behaviors.
@@ -146,4 +166,4 @@ This project is not affiliated with archive.org or aria2. Use responsibly and re
   - Artifacts land in `releases/<version>/`
 - Self-hosted updates: `releases/updates.json` is tracked; update with the new version and `update_link` like `https://add-ons.jordanwages.com/archive-org-link-grabber/releases/<version>/archive-org-link-grabber-<version>.xpi`.
 
-Notes: Keep AMO secrets local. CI is optional. You can tag releases with `git tag vX.Y.Z` and push tags if desired.
+Notes: Keep AMO secrets local (see `.env.example`). CI is optional. You can tag releases with `git tag vX.Y.Z` and push tags if desired.