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

5.0 KiB

Raw Blame History

Options page for first-time users

Status: implemented on feat/options-page-cleanup (PR #23).

Goal

Make the options page usable by people who are not comfortable with computers, without losing any setting. Customization in a lightweight extension is what sets this one apart, so the page simplifies wording and layout, never features.

Layout

Description, no heading: "This extension adds ChatGPT as a Firefox search engine."
Usage instructions: one labelled line per way to open ChatGPT, each with one drawing:
- Address bar
- Right-click
- Keyboard (hidden when no shortcut is assigned)
- Toolbar
A small tip follows: ChatGPT opens with the text filled in, press <Enter> if it isn't sent, and sign-in may be needed.
Settings:
- Visible: Right-click menu (renamed from "Context menu"), its Translate sub-settings, and Open ChatGPT in.
- Choosing Advanced reveals a drawing of the Ask ChatGPT submenu. It sits in the block that only shows for Advanced, so it previews the one setting newcomers find hardest to picture, at no cost to anyone else.
- Under More options: prompt template, temporary chat, and web search. The summary names all three. The section opens on load, or when a sync changes one of them, if any differs from its default. That way a customised setting never looks lost.
- Restore defaults sits on the right in red, because it discards every customised setting at once.
Two collapsed sections:
- Use your own keyword or make ChatGPT your default search engine, as numbered steps.
- Change the keyboard shortcut.
Project links, centred, stacked on narrow panels.

Drawings, not screenshots

Each drawing is HTML, CSS, and a little inline SVG. The only image is the bundled extension icon. The drawings are aria-hidden; the text next to them carries the instructions.

Real screenshots were considered and rejected for the page:

they go stale when Firefox redesigns its address bar or menus;
the right-click menu looks different on Windows, macOS, and Linux;
they need separate light and dark versions;
they must be bundled, since loading them remotely would repeat the problem fixed in #20.

Size was not the issue. Screenshots would have added roughly 50–150 KB. The whole rewrite, drawings included, added under 4 KB; the package went from 52.8 KB to 56.5 KB. Real screenshots belong on the AMO listing instead, which has none.

The address-bar drawing shows a ChatGPT label after gpt and a space. The basis is the code shipped in Firefox 157.0.1, read from its omni.ja; it has not yet been checked on screen:

UrlbarProviderAliasEngines gives keyword results a keyword payload;
UrlbarInputBase.onFirstResult enters search mode for such a result.

If Firefox shows no label, the drawing should show plain text instead.

The keyboard drawing draws key caps for the user's actual shortcut, which options/shortcut.js builds from commands.getAll().

Hotkeys

Hotkeys are written as <Ctrl>+L: named keys in angle brackets, single characters plain. This is the maintainer's own convention from the AMO listing. It applies to the static text and to the live shortcut.

On macOS the page uses Mac key names, detected with runtime.getPlatformInfo(), which needs no permission:

Ctrl and Command become Cmd; Firefox reads a manifest's Ctrl as Command there (ShortcutUtils.chromeModifierKeyMap).
MacCtrl becomes Ctrl.
Alt becomes Option.
Enter becomes Return.

Shortcuts set in Firefox's shortcut editor on macOS are stored with MacCtrl, Alt, Command, and Shift (addon-shortcuts.mjs, getShortcutForEvent).

Copy rules kept

These come from the options design:

Copy says ChatGPT opens with the text filled in, never that it is sent, searched, or asked.
The temporary-chat label and warning are unchanged, with no "private", "incognito", or "secure" near them.
Web search stays labelled as a hint.

Testing

npm test covers:

the key formatter, including the macOS key names;
the static hotkeys in options.html matching the formatter;
the key caps drawn for the live shortcut.

Manual checks are listed in AGENTS.md.

To preview the page outside the extension:

Copy options/, lib/, and icons/ to a scratch folder.
Add a script before options.js that defines a stand-in browser with runtime.getPlatformInfo, commands, and storage.
Serve the folder on localhost.
Run firefox --headless -no-remote -profile <tmp> --screenshot out.png --window-size=680,1600 <url>.

For dark mode, give the throwaway profile layout.css.prefers-color-scheme.content-override = 0 and ui.systemUsesDarkTheme = 1. This renders with Firefox's own engine, but not inside about:addons.

Not in scope

Screenshots and an updated description for the AMO listing.
Pinning the toolbar button by default (browser_action.default_area).
Rewriting the README's hotkeys in the <Alt>+<Shift>+G style.

5.0 KiB Raw Blame History Unescape Escape