# Repository Guidelines

## Project Structure & Module Organization

This is a Firefox WebExtension (Manifest V2) with npm-based development tooling.

- `manifest.json` defines the extension metadata, the ChatGPT search provider,
  the background script, the options panel, and the keyboard command.
- `lib/` holds pure logic with no browser dependencies: `defaults.js`,
  `build-url.js`, and `settings.js`. This is the unit-tested core.
- `background/background.js` is an ES-module background script that registers
  the context menu and the keyboard command.
- `options/` is the options panel rendered inline in `about:addons`.
- `test/` holds `node:test` unit tests. Excluded from the packaged ZIP.
- `icons/` contains size-specific PNG artwork named `powered-by-openai-icon-<size>x<size>.png`.
- `web-ext-config.mjs` controls linting, local execution, and ZIP packaging.
- `docs/superpowers/` holds specs and plans. Excluded from the packaged ZIP.
- `.gitea/workflows/firefox-extension.yml` validates pull requests and protected branches.
- `README.md`, `CHANGELOG.md`, and `LICENSE.txt` cover usage, releases, and licensing.

## Browser Scope

Firefox Desktop is the only current implementation and release target. Do not add Chrome, Brave, Chromium, or other browser packaging—or modify the sibling Chrome repository—unless a task explicitly requests it. Future ports remain desirable, so prefer standard WebExtension APIs where they preserve Firefox behavior and isolate unavoidable Firefox-specific code.

## Build, Test, and Development Commands

- `npm ci` installs the exact dependencies from `package-lock.json`; use Node.js 22 or newer.
- `npm run dev` launches a temporary Firefox profile with automatic extension reload.
- `npm run lint` runs strict Mozilla extension validation.
- `npm run test:unit` runs the `node:test` unit tests over `test/`.
- `npm run build` creates the unsigned ZIP under `web-ext-artifacts/`.
- `npm test` runs lint, unit tests, and build together; run it before every pull request.

## Coding Style & Naming Conventions

Use two-space indentation in JSON, YAML, and JavaScript configuration. Preserve logical key grouping in `manifest.json`. Use lowercase, hyphenated filenames and include dimensions in icon names. Keep changes focused and avoid adding runtime dependencies without a concrete need.

## Options Page

- Keep every setting. Customization in a lightweight extension is what sets
  this one apart, so simplify wording and layout, but never remove a setting
  without the maintainer's agreement. Less-used settings can sit under
  **More options**.
- Write hotkeys as `<Ctrl>+L`: named keys in angle brackets, single characters
  plain. `options/shortcut.js` swaps in Mac key names.
- Say that ChatGPT opens with the text filled in, never that the text is sent,
  searched, or asked. The options design spec explains why.

## Testing Guidelines

Unit tests cover the pure logic in `lib/` via `node:test`; automated checks
otherwise cover manifest validation and packaging, not browser behaviour. Note
`node --test` exits 0 when it discovers no test files, so confirm a non-zero
test count rather than trusting the exit code alone.

After `npm test`, use `npm run dev` and confirm:

- `gpt <query>` opens ChatGPT, the provider stays non-default, and Firefox
  search settings can configure it.
- The Options/Preferences tab renders the drawings, every setting (including
  those under More options), and Restore defaults,
  in both light and dark themes and at a narrow window width, and values
  persist across a restart. Expanding and collapsing More options and the
  collapsed sections resizes the inline panel without clipping or scrolling.
- **Right-click menu → Simple** shows the direct **Ask ChatGPT** item only for
  selected text. **Advanced** shows the contextual submenu; selection takes
  precedence over links. **Off** hides the menu. Switch modes without restarting
  and confirm Alt+Shift+G still works in every mode. Restore defaults returns
  to Simple with Translate hidden, and preferences persist across a restart.
- Enable Translate and check Ask each time, preferred language, Enter, Escape,
  and Cancel. Confirm long selections require consent before shortening and
  link URLs are never shortened. Check concurrent dialogs retain separate data.
- `Alt+Shift+G` acts on the selection and opens a blank chat when nothing is
  selected or on a restricted page such as `about:config`. Press the key to test
  this — `commands.getAll()` reports a shortcut as registered even when Firefox
  has silently overridden it. The injected snippet is gated on
  `document.hasFocus()`, so cover all four frame cases:
  - Select in the top frame → the top-frame text arrives.
  - Select inside an iframe → the iframe text arrives.
  - Select in the top frame, *then* select inside an iframe → the iframe text
    arrives. `hasFocus()` is true for a focused frame and all its ancestors, so
    if the stale top-frame text arrives instead, exclude ancestors by also
    checking that `document.activeElement` is not the frame element.
  - Press `Ctrl+F`, find a term, then press the shortcut without clicking back
    into the page → a blank chat is expected. Firefox leaves focus in the
    findbar, so no content frame reports focus. This is a deliberate trade: a
    stale cross-origin frame silently seeding the prompt was the worse failure.
- Click the **Ask ChatGPT** toolbar button with no selection, a top-frame
  selection, and an iframe selection after a stale top-frame selection.
  Check restricted-page fallback, right-click menu Off, saved prompt and opening
  preferences, and consent before shortening long selections. Test both the
  pinned toolbar button and its entry in Firefox’s extensions menu.

Inspect ZIP contents whenever packaging rules or assets change; `test/` and
`docs/` must never appear, not even as empty directory entries.

Gitea Actions runs checks for every pull request and pushes to `develop` and
`main`. Only successful `main` pushes upload an unsigned build artifact; CI does
not publish to AMO.

## Commit & Pull Request Guidelines

Recent history uses short, lowercase prefixes such as `doc:` and `build:` (for example, `doc: fix git url`). Follow `<type>: <concise summary>` and keep each commit focused.

Pull requests should explain the user-visible effect, list manual Firefox checks, and link the relevant issue. Include screenshots for icons or browser-visible metadata. Explicitly call out permission, search URL, privacy, and packaging changes.

## Security & Privacy

Do not commit credentials or API keys. New permissions, telemetry, intermediary servers, or data collection require explicit justification and matching privacy documentation.

Permissions are deliberately limited to `storage`, `menus`, and `activeTab`,
which add no line to Firefox's install prompt. Do not add `tabs`,
`notifications`, `webNavigation`, or any host permission without re-reading
`docs/superpowers/specs/2026-07-29-extension-options-design.md` — each was
considered and rejected there, and Appendix B records a feature rejected on
security grounds that must not be revived without clearing the bar documented
with it.