zavage-software/search-with-chatgpt-powered-by-openai-extension

Files

T

golem ff61aff5b9 feat: rewrite the options page for first-time users (#23 )

Rewrites the options page for first-time users without removing any setting. Customization in a lightweight package is what sets this extension apart. Design: `docs/superpowers/specs/2026-10-18-options-page-for-first-time-users-design.md`.

**User-visible changes**
- **Layout:** the description stays as the first line, followed by a **Usage instructions** section and the **Settings** section. Each section has a heading and a divider.
- **Usage instructions:** one labelled line per way to open ChatGPT, each with a small drawing:
  - **Address bar:** `<Ctrl>+L`, then `gpt`, a space and the question. The drawing shows a ChatGPT label because the address-bar code shipped in Firefox 157.0.1 enters search mode when an engine keyword is followed by a space. I checked that in its `omni.ja`, but it still needs confirming on screen; see the checks below.
  - **Right-click:** a drawing of the menu with Ask ChatGPT highlighted.
  - **Keyboard:** key caps for the user's actual shortcut, held down. The line is hidden when no shortcut is set.
  - **Toolbar:** the hovered button with the pointer, its tooltip, the puzzle-piece Extensions button, and a selected heading.
- **Drawings:** they are HTML/CSS and inline SVG, not screenshots, so they follow light and dark themes, stay sharp, and never go stale. They are centred. The package grows from 52.8 KB to 56.5 KB.
- **Settings:**
  - **Right-click menu** (was "Context menu") and **Open ChatGPT in** stay visible.
  - Choosing **Advanced** reveals a drawing of the Ask ChatGPT submenu (Ask normally, Explain, Summarize, Debug code). It lives in the block that only shows for Advanced, so it needs no script.
  - Prompt template, temporary chat and web search move under **More options**, whose heading names them. It opens by itself on load, or when a sync changes one of them, if one of them isn't at its default.
  - **Restore defaults** is right-aligned and red.
- **Bottom of the page:**
  - The keyword/default-engine and keyboard-shortcut notes become collapsed sections with numbered steps.
  - The project links are centred, and stack on narrow panels.
- **Hotkeys:** written as `<Ctrl>+L` and `<Alt>+<Shift>+G`, including the user's actual shortcut. Mac users see `<Cmd>`, `<Option>` and `<Return>`, detected with `runtime.getPlatformInfo`, which needs no permission.
- **Docs:**
  - Keyword wording is corrected in the options page and README: Firefox adds a custom keyword alongside `gpt` instead of replacing it.
  - README and AGENTS.md use the new setting names.
  - AGENTS.md records the keep-every-setting rule, the hotkey format and the "filled in, never sent" copy rule.

These still match the original options design spec: the temporary-chat and web-search wording, and the rule that copy never says the question is sent.

No permission, search URL, privacy or packaging changes.

**Checks**
- `npm test`: lint 0 errors / 0 warnings, 61/61 unit tests, build OK.
- New tests:
  - the key formatter, including the Mac names Firefox stores (Command, MacCtrl, Alt)
  - the page's written hotkeys match the formatter
  - the keyboard drawing's key caps follow the live shortcut
- Rendered in headless Firefox 157 with the extension APIs stubbed:
  - light and dark themes
  - 680 px and 360 px wide
  - Mac key names
  - More options opening for a customised prompt template
  - both bottom sections expanded

**Manual Firefox checks (`npm run dev` → about:addons → Preferences)**
- [x] Typing `gpt` and a space shows a ChatGPT label in the address bar, as drawn. If it doesn't, the drawing drops the label and shows plain `gpt how do magnets work?`
- [x] Light and dark themes, and a narrow about:addons width
- [x] Expanding More options and the two bottom sections grows the inline panel without clipping or scrolling
- [x] The Keyboard line and its key caps disappear when the shortcut is removed, and come back showing the new keys when one is set
- [x] More options opens by itself after changing the prompt template and reopening the page
- [x] Choosing Advanced shows the submenu drawing; Simple and Off hide it
- [x] Settings still save, and Restore defaults still works

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://git.zavage.net/Zavage-Software/search-with-chatgpt-powered-by-openai-extension/pulls/23
Co-authored-by: golem <golem@zavage.net>

2026-10-18 22:53:27 -06:00

7.1 KiB

Raw Permalink Blame History

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.

7.1 KiB Raw Permalink Blame History Unescape Escape