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>
This commit is contained in:
golem
@@ -0,0 +1,125 @@
|
||||
# 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
|
||||
|
||||
1. **Description**, no heading: "This extension adds ChatGPT as a Firefox
|
||||
search engine."
|
||||
2. **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.
|
||||
3. **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.
|
||||
4. Two collapsed sections:
|
||||
- **Use your own keyword or make ChatGPT your default search engine**, as
|
||||
numbered steps.
|
||||
- **Change the keyboard shortcut**.
|
||||
5. 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](2026-07-29-extension-options-design.md):
|
||||
- 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:
|
||||
1. Copy `options/`, `lib/`, and `icons/` to a scratch folder.
|
||||
2. Add a script before `options.js` that defines a stand-in `browser` with
|
||||
`runtime.getPlatformInfo`, `commands`, and `storage`.
|
||||
3. Serve the folder on localhost.
|
||||
4. 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.
|
||||
Reference in New Issue
Block a user