# 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.