# Repository Guidelines

## Project Structure & Module Organization

- Root: `manifest.json`, `package.json` (when added), config files.
- `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

- Install: `npm install` (after `package.json` lands).
- 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

- Language: JavaScript (ES2020+) or TypeScript (preferred for new modules).
- 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

- Framework: Jest for unit tests; Playwright for e2e (popup/content behaviors).
- 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

- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`). Use imperative mood.
- 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

- Do not commit secrets. Store aria2 RPC token in `browser.storage.local`.
- Prefer HTTPS for remote RPC; if self-signed, document trust steps locally only.
- Provide examples as `config.example.json`; ignore local overrides in `.gitignore`.