search-with-chatgpt-powered-by-openai-extension/docs/superpowers/specs/2026-07-29-extension-options-design.md

Extension Options Panel — Design

• Date: 2026-07-29
• Status: Approved for planning
• Branch: feat/extension-options-panel (cut from develop @ 5edb288)

Summary

Add an options panel to the extension, reachable from about:addons → the extension's detail card → the Options tab (Windows) / Preferences tab (macOS, Linux). The panel configures two new entry points that this change also introduces: a context-menu item on selected text, and a keyboard shortcut that opens a fresh ChatGPT chat.

The existing gpt <query> address-bar search provider is not modified and does not read the settings. See Why the search provider is untouched.

New permissions: storage and menus. Both are in Firefox's no-prompt class, so the install dialog gains no new lines and data_collection_permissions: ["none"] remains truthful.

Goals

1. Ship a working options panel embedded in about:addons.
2. Ship two new entry points whose behaviour the panel controls.
3. Add no permission-warning lines to the install prompt.
4. Keep data_collection_permissions: ["none"] accurate.
5. Introduce unit testing for the pure logic, without new runtime dependencies.
6. Never promise behaviour that ChatGPT does not reliably deliver.

Non-goals

• Making the gpt <query> search provider configurable. Out of scope by decision; it requires either host permissions on chatgpt.com or a navigation-interception mechanism, both of which conflict with goals 3 and 4.
• A toolbar button.
• Named/multiple prompt templates with add-remove-reorder UI. One template only.
• Reading the page selection from the keyboard shortcut. That requires activeTab + tabs.executeScript; deliberately excluded (see Rejected alternatives).
• Migrating to Manifest V3.
• Chrome or other-browser packaging (AGENTS.md browser scope).
• User-facing error notifications. The notifications permission does generate an install warning, so every failure path degrades silently instead.

Background and constraints

The extension is currently manifest-only: no JavaScript exists, and the manifest declares no background, content_scripts, or web_accessible_resources key. Its single feature is chrome_settings_overrides.search_provider with search_url: "https://chatgpt.com?q={searchTerms}".

Why the search provider is untouched

chrome_settings_overrides.search_provider is declarative and fixed at install time. No WebExtension API can rewrite an installed engine's URL. Making gpt <query> honour the settings would require intercepting the navigation it starts, which needs host access to chatgpt.com plus webRequest or tabs — all of which add install-prompt lines. Rejected in favour of goals 3 and 4.

is_default stays false. Setting it to true triggers a second, separate consent doorhanger (webext-default-search-description) outside any permission list, plus an allowlist requirement.

ChatGPT URL parameters are undocumented

None of q, model, hints, or temporary-chat is documented by OpenAI. There is no contract and no support channel. The design is therefore resilient by construction: the URL is built from a template with no runtime dependency on any parameter being honoured, each parameter is independently removable so a user can bisect when ChatGPT ignores one, and all user-facing copy is written at hint strength. See Appendix A for the evidence behind each parameter's confidence rating.

The one parameter with quasi-official standing is q, because OpenAI's own "ChatGPT search" browser extension uses https://chatgpt.com/?q=. Build on it; treat everything else as best-effort.

q prefills but does not submit. Auto-submit was real historically but has been prefill-only since approximately November 2025, after OpenAI gated it on the Sec-Fetch-Site header as a prompt-injection mitigation. No copy in the options panel, README, or AMO listing may say the query is searched, sent, or asked — only that ChatGPT opens with the query filled in.

Architecture

Manifest stays V2. Mozilla has not announced any MV2 deprecation and commits to at least 12 months' notice. The repo is MV2 today and has no Chrome target, so migration is an orthogonal change. The code is nonetheless kept MV3-portable: ES-module background, persistent: false, no browser_style: true.

ES modules work in an MV2 background script via "background": {"scripts": [...], "type": "module"}, supported since Firefox 112 and verified empirically in Firefox 153.0.1. No background HTML shim is needed. The options page is a normal extension page and can use <script type="module"> in both the embedded and standalone surfaces.

strict_min_version becomes "112.0" — the binding floor, above storage.sync quota enforcement (79), menus (55), options_ui (55), and commands (48).

File layout

manifest.json
background/
  background.js        # registers menu + command, handles clicks. Imports lib/.
lib/
  defaults.js          # DEFAULT_SETTINGS — single source of truth
  build-url.js         # PURE: (settings, rawQuery) -> url string
  settings.js          # mergeSettings() pure; load()/save() wrap browser.storage
                       #   load()  -> storage.sync.get() piped through mergeSettings()
                       #   save()  -> storage.sync.set(), debounced by the caller
options/
  options.html
  options.css
  options.js
test/
  build-url.test.js
  settings.test.js
docs/superpowers/specs/
  2026-07-29-extension-options-design.md

lib/build-url.js and lib/defaults.js have zero browser dependencies, so node:test imports them directly with no stubbing. lib/settings.js separates the pure mergeSettings() from the browser.storage I/O for the same reason; only mergeSettings() is unit-tested.

lib/ ships inside the ZIP because the background script imports it at runtime. test/ and docs/ must not ship — see Packaging.

Manifest additions

"permissions": ["storage", "menus"],
"background": {
  "scripts": ["background/background.js"],
  "type": "module",
  "persistent": false
},
"options_ui": {
  "page": "options/options.html",
  "open_in_tab": false,
  "browser_style": false
},
"commands": {
  "new-chat": {
    "suggested_key": { "default": "Alt+Shift+G" },
    "description": "Open a new ChatGPT chat"
  }
}

browser_specific_settings.gecko gains "strict_min_version": "112.0". The existing id and data_collection_permissions are unchanged.

browser_style: false is set explicitly. Omitting it is not equivalent — it defaults to true in MV2. Setting it false means the panel renders identically if the extension ever moves to MV3, where browser_style: true is unsupported.

menus is the canonical Firefox permission name; contextMenus is a cross-browser alias. Use menus and access the API as browser.menus.

Alt+Shift+G is deliberate. Ctrl+Shift+G is Firefox's Find Previous — it would validate, display in about:addons, and never fire.

Settings

Stored as individual keys in browser.storage.sync.

Key	Type	Default	Maps to
model	string	""	model=<value>, omitted when empty
temporaryChat	boolean	false	temporary-chat=true when set
webSearch	boolean	false	hints=search when set
openIn	"new-tab" | "background-tab" | "new-window"	"new-tab"	tab/window creation
promptTemplate	string	"{query}"	wraps the selection

Defaults reproduce today's behaviour exactly: an empty model and both toggles off mean the only parameter sent is q.

Model

A free-text field, not a dropdown. No authoritative slug list exists and every published one has rotted (gpt-4 → o1-preview → gpt-4o → gpt-5-thinking → auto/instant/thinking). A curated dropdown would be wrong within a quarter, and each stale entry fails silently to the account default.

• Label: Model (experimental)
• Placeholder: auto
• Help text: "ChatGPT may ignore this and use your account default. Leave blank to always use your account default."
• Default is empty, not auto, so the default configuration sends no model parameter and matches current behaviour.

Temporary chat

• Label: Request a temporary chat
• Help text: "ChatGPT may not honour this. Check ChatGPT's own indicator before sending anything sensitive."
• Default off.
• The words private, incognito, and secure must not appear near this setting. Reports indicate chats can revert to permanent after the first message, and OpenAI is actively reworking the feature's semantics.

Web search

• Label: Ask ChatGPT to use web search (hint only)
• Help text: "A hint to ChatGPT's interface, not a guarantee."
• Default off. The value is hard-coded to search; no mode dropdown.

Open in

• Label: Open in
• Options: A new tab / A new background tab / A new window
• Default A new tab.

Prompt template

• Label: Prompt template
• Default {query}
• Help text: "{query} is replaced with your selected text."

Panel behaviour

Auto-save on change with a transient "Saved" indicator; no Save button. Writes are debounced at 400 ms so typing in a text field cannot approach any write-rate quota.

A Restore defaults button resets every key to DEFAULT_SETTINGS.

The panel subscribes to browser.storage.sync.onChanged and updates its controls live, so a remote sync landing while the panel is open does not get clobbered by stale field values.

The embedded surface inside about:addons is narrow and inherits that page's layout. The panel must therefore be responsive down to roughly 400 px, must not depend on window sizing, and must remain usable as a standalone page — the extensions.htmlaboutaddons.inline-options.enabled pref can degrade it to a tab. Because browser_style is off, the panel is hand-styled and must support dark theme via prefers-color-scheme; about:addons follows the system theme.

URL construction

buildChatGptUrl(settings, rawQuery) -> string in lib/build-url.js. Pure.

BASE           = "https://chatgpt.com/"
MAX_URL_CHARS  = 8000

The root path is mandatory. chatgpt.com/search?q= began returning 404 in mid-2025; the root form is what OpenAI's own extension uses.

Algorithm

1. Build the prompt. Let q = String(rawQuery ?? "").trim().

   • If q === "" → prompt = "" (the template is ignored entirely).
   • Else if the template contains {query} → replace every occurrence (replaceAll).
   • Else if the trimmed template is empty → prompt = q.
   • Else → prompt = trimmedTemplate + " " + q (template treated as a prefix; the selection is never silently discarded).

2. Measure the non-q budget. Build a URL from BASE, append model, temporary-chat, and hints per the rules below, and record baseLength = url.href.length.

3. Fit the prompt. If prompt !== "", find the largest number of code points of prompt (via binary search over Array.from(prompt), so surrogate pairs are never split) whose resulting full URL length is <= MAX_URL_CHARS. Truncation operates on the decoded string and encoding happens afterwards, so a percent-escape can never be severed. If the kept text contains whitespace within its final 10%, cut at the last such whitespace instead, for a cleaner break.

4. Assemble in final order. Build a fresh URL and set parameters in this order, matching the most-cited working examples: q (if non-empty), then model, temporary-chat, hints.

   Measuring in step 2 without q and assembling with q first is safe: total serialized length is independent of parameter order, since reordering only swaps which separator is ? and which are &, never how many there are.

5. Return url.href.

Parameter rules

• q — set only when the fitted prompt is non-empty. Never emit q= with an empty value.
• model — set to settings.model.trim() only when that is non-empty.
• temporary-chat — set to the string "true" only when temporaryChat is true.
• hints — set to the string "search" only when webSearch is true.

q is the parameter to send. ChatGPT canonicalises it to prompt= internally; prompt= is the first fallback to try should q ever stop working. Never send both.

Data flow

1. Trigger. browser.menus.onClicked supplies info.selectionText, or browser.commands.onCommand supplies no query.
2. settings = await load() — load() already pipes the raw storage.sync.get() result through mergeSettings(), so callers always receive a complete, validated settings object and never need to merge again.
3. url = buildChatGptUrl(settings, query).
4. Open per settings.openIn:
   • new-tab → browser.tabs.create({ url, active: true })
   • background-tab → browser.tabs.create({ url, active: false })
   • new-window → browser.windows.create({ url })

tabs.create and windows.create require no permissions. The created Tab object's url/title must not be read — that would require the tabs permission, which carries an install warning.

The menu item is registered with contexts: ["selection"], so Firefox shows it only when text is selected.

Error handling

Every path resolves to something useful. No path shows an error to the user.

Case	Behaviour
Selection empty or whitespace	Omit q entirely; open a blank chat with the other settings applied.
Prompt exceeds the URL budget	Truncate per step 3 above. Never sever a percent-escape or split a surrogate pair.
storage.sync rejects (quota, or a sanitized backend error)	try/catch → fall back to DEFAULT_SETTINGS. Never block opening ChatGPT. Do not branch on error type: Firefox sanitizes all non-quota backend errors to "An unexpected error occurred".
Fresh or signed-out profile returns {}	mergeSettings layers stored values over DEFAULT_SETTINGS, so {} yields defaults.
Template lacks {query}	Treat as a prefix and append.
Template has several {query}	Replace all occurrences.
model blank or whitespace	Omit the parameter.
Stored settings corrupt or partial	mergeSettings drops unknown keys and falls back to default on wrong type or out-of-range enum.
Background event page wakes and re-registers	menus.removeAll() before menus.create(), so re-registration is idempotent.
windows.create fails	Fall back to tabs.create.
browser.commands undefined	Guard before subscribing. The API does not exist on Firefox for Android.

storage.sync needs no capability probe: it works with no Mozilla account, silently behaving as local storage, and syncs later if the user signs in and has Add-ons sync enabled. The gecko.id (already present) is required and must never change — synced data is keyed by extension ID.

Testing

Unit — node --test

test/build-url.test.js:

• Defaults + a simple query → exactly https://chatgpt.com/?q=hello
• Each parameter appears only when its setting is enabled
• All four URL-affecting settings together (model, temporaryChat, webSearch, promptTemplate), with parameters in the specified order. openIn never influences the URL and must not appear in these assertions.
• Encoding of &, #, ?, =, +, spaces, newlines, emoji, CJK
• {query} substitution: present, absent (prefix fallback), multiple occurrences, empty template
• Empty / whitespace-only query → no q parameter at all
• Truncation: result <= MAX_URL_CHARS; no severed percent-escape; no split surrogate pair (assert with an emoji at the boundary); whitespace-boundary preference
• model empty and whitespace-only → no model key

test/settings.test.js — mergeSettings with: {}, null, undefined, missing keys, unknown keys, wrong types, out-of-range openIn value.

Manual

Retain the three existing regression checks from AGENTS.md: gpt <query> opens ChatGPT, the provider stays non-default, and it remains configurable in Firefox search settings.

Add:

• The Options/Preferences tab appears on the extension's detail card in about:addons, and all five settings controls plus Restore defaults render correctly — in both light and dark theme, and at a narrow width
• The page is also usable standalone via browser.runtime.openOptionsPage()
• Settings persist across a browser restart
• The context-menu item appears only when text is selected, and is absent otherwise
• Alt+Shift+G opens a new chat, appears under about:addons → gear → Manage Extension Shortcuts, and can be rebound
• Each of the three openIn values behaves correctly
• A packaged build's install prompt gains no new lines. This cannot be checked with npm run dev — install prompts are suppressed for temporary installs. Use a packaged build.
• unzip -l web-ext-artifacts/*.zip shows no test/ or docs/ entries, not even empty directory entries

Parameter reality check

One pass in a real, logged-in Firefox profile to record which parameters are actually honoured on this extension's navigation path: does q prefill only or also submit; is model respected alongside q; does temporary-chat produce a temporary chat and does it survive the first message; does hints=search engage web search.

No further desk research substitutes for this. The outcome adjusts the help text, not the architecture — every label is already written at hint strength, so a negative result requires no redesign.

Packaging

web-ext-config.mjs — add to ignoreFiles:

"docs", "docs/**", "test", "test/**",

Both forms per directory are required. A glob alone removes the files but leaves an empty directory entry in the ZIP; web-ext's own code pairs the bare name with the glob for exactly this reason.

.gitea/ and .agents/ need no entries — web-ext ignores all dotfiles and dot-directories by default. web-ext-artifacts/** is likewise already redundant; it stays as-is to keep this diff focused.

web-ext lint scans lib/ and test/ with the same file filter as build. With lint.warningsAsErrors: true, one addons-linter warning in a test file is a hard CI failure. Adding test/ to ignoreFiles fixes linting and packaging together — it is one lever, not two.

web-ext-config.mjs must keep its .mjs extension. web-ext rejects a .js config file outright.

Tooling

package.json:

"type": "module",                 // NEW — required, see below
"scripts": {
  "test:unit": "node --test",     // NEW
  "test": "npm run lint && npm run test:unit && npm run build"
}

"type": "module" is required, not stylistic. Without it, node --test importing an ES-module lib/*.js relies on Node's module-syntax detection, which:

• emits a permanent MODULE_TYPELESS_PACKAGE_JSON warning on every run, and
• fails outright on Node 22.0–22.6, since detection only became default in 22.7. engines.node says >=22 and CI pins the bare major "22", leaving the patch to runner resolution — so without this field the project declares support for a range in which its own suite does not run.

Using .mjs for test files only does not fix this; the typeless lib/*.js is the ambiguous file. Adding "type": "module" was verified not to break web-ext lint or web-ext build on web-ext 10.5.0, which never consults the consumer package's type field.

Ordering is lint → unit → build, so unit failures prevent a ZIP from being produced. The existing .gitea workflow calls npm test and needs no edit.

node --test exits 0 when it discovers zero test files. CI would go green on a misconfigured path, so acceptance must assert a non-zero test count, not merely a zero exit code.

Note for implementers: local Node here is v26.5.0 while CI pins 22. Local green does not imply CI green.

Documentation changes

• README — an Options section listing the five settings and how to reach the panel (referring to "Options (Windows) / Preferences (macOS, Linux)", since Firefox's label is platform-dependent). Privacy section amended: settings are stored in the user's own browser profile and, only if that user has Firefox Sync with Add-ons enabled, synced end-to-end encrypted through their own Mozilla account. Do not write "never leaves your device" unconditionally. Nothing reaches Zavage Software, so the zero-data-collection claim stands.
• AGENTS.md — update Project Structure for the new directories, Build/Test commands for test:unit, and the Testing Guidelines manual checklist.
• CHANGELOG.md — entry for the release.
• Version — manifest.json 1.0 → 1.1; package.json 1.0.0 → 1.1.0.

Rejected alternatives

Alternative	Why rejected
Rewrite the gpt keyword's navigation to honour settings	Needs host access to chatgpt.com plus webRequest/tabs; adds install-prompt lines.
Point search_url at a bundled extension page that redirects	Firefox requires an http(s) search URL; also a visible redirect flash. Not pursued.
Keyboard shortcut reads the page selection	Requires activeTab + tabs.executeScript. No lighter route exists — a declared <all_urls> content script is strictly worse. Excluded by decision; revisitable as its own change.
background.page HTML shim for ES modules	Works, but unnecessary once background.type: "module" was confirmed for MV2.
background.scripts without type	Classic scripts; an import statement fails with a compile-time SyntaxError and silently kills the script.
Curated model dropdown	Slug lists rot within a quarter and every stale entry fails silently to the account default.
Migrate to MV3 now	Orthogonal, larger diff. Mozilla has announced no MV2 sunset and promises ≥12 months' notice.
Toast/notification on failure	The notifications permission adds an install warning. All failure paths degrade silently instead.

Risks

1. Any ChatGPT parameter may stop working without notice. Mitigated by hint-strength copy everywhere, independently removable parameters, and no architectural dependence on any of them. The /search path's silent move to 404 in mid-2025 is the precedent.
2. model may never work alongside q. An unresolved report says q forces the account default; no 2026 source positively confirms otherwise. The setting is labelled experimental and defaults to empty, so the default configuration is unaffected either way.
3. Alt+Shift+G may collide with an OS or window-manager hotkey. Verified clear of Firefox's own keyset and DevTools only; no registry of other add-ons' shortcuts exists. Mitigated by the context menu remaining a full-featured path and by documenting Manage Extension Shortcuts.
4. MV2's long-term future is not guaranteed. The strongest Mozilla commitment is dated March 2024 and nothing newer restates it. Mitigated by keeping the code MV3-portable.

Appendix A: Verification findings

Established 2026-07-29 by parallel research with adversarial verification; 64 findings, one overturned by its skeptic. Browser claims were verified by loading real test extensions into Firefox 153.0.1. Repo claims were verified by running commands against copies under /tmp; the repo itself was unmodified.

Confirmed empirically in Firefox 153.0.1

• MV2 background: {scripts, type: "module"} loads real ES modules. Supported since Firefox 112 (bug 1811443); Firefox's manifest schema puts no min_manifest_version on type.
• MV2 background: {scripts} without type fails on import with "SyntaxError: import declarations may only appear at top level of a module".
• options_ui.open_in_tab: false renders inside about:addons (inline-options-browser), gated on extensions.htmlaboutaddons.inline-options.enabled, which ships true.
• The tab label is platform-dependent: preferences-addon-button = { PLATFORM() -> [windows] Options *[other] Preferences }.
• Options pages support <script type="module"> in both surfaces.

Confirmed from Firefox source

• PERMISSIONS_WITH_MESSAGE (26 entries) is the authoritative list of API permissions that add a warning line. storage, menus, and activeTab are all absent; tabs is present. Caveat established by the overturned finding: it is one of five independent install-prompt inputs (API permissions, host permissions, DATA_COLLECTION_PERMISSIONS, site permissions, unsigned warning), so it is not a complete account of install-time warnings.
• A fresh install always shows a prompt; the no-prompt early-return is gated on type == "update". This extension's prompt today is "Add …" + the data-collection line + the private-windows checkbox — unchanged by this work.
• Install prompts are suppressed for temporary/unpacked installs.
• storage.sync throws only for a temporary add-on ID (enforceNoTemporaryAddon); the explicit gecko.id satisfies it. No account check exists anywhere in the path — the backing store is a plain profile-local storage-sync-v2.sqlite. Quotas: 102400 total / 8192 per item / 512 items. Non-quota backend errors are sanitized to "An unexpected error occurred".
• Sync transport is per-extension encrypted BSOs over the user's own Firefox Account; extension IDs are hidden behind random GUIDs.
• Ctrl+G is key_findAgain and Ctrl+Shift+G is key_findPrevious. Alt+Shift+G is unused by browser-sets.inc and DevTools.
• tabs.create / windows.create declare no permissions; only Tab.url/title/favIconUrl require tabs.
• commands is version_added: false on Firefox for Android.
• options_ui.browser_style is deprecated in MV3 only (default flipped in Firefox 115, unsupported in 118). Legal in MV2, where it defaults to true.

Confirmed empirically against the repo

• npx web-ext lint → 0 errors / 0 warnings / 0 notices, exit 0. Green baseline.
• lint and build share one FileFilter; eval() planted in lib/ produced DANGEROUS_EVAL and exit 1.
• web-ext's default ignore list includes '**/.*' and '**/.*/**/*', so dotfiles never ship. Confirmed: .gitea/ and a planted .agents/note.md were both absent from a build with no dotfile entries in ignoreFiles.
• test/ and docs/ do ship by default. With only "test/**", empty test/ and docs/ directory entries remained in the ZIP; adding the bare names removed them.
• The current shipped ZIP contains only manifest.json, LICENSE.txt, and icons/ — packaging hygiene is a property to preserve, not a bug to fix.
• node --test with no "type" field: passes on Node 26.5.0 but warns MODULE_TYPELESS_PACKAGE_JSON; with --no-experimental-detect-module (pre-22.7 behaviour) it fails with "Cannot use import statement outside a module".
• .mjs for tests only moves the warning to the typeless lib/*.js.
• Adding "type": "module": node --test clean, web-ext lint 0/0/0, web-ext build succeeded.
• node --test with zero discovered tests: tests 0, exit 0.
• Local Node v26.5.0, npm 12.0.1, web-ext 10.5.0. CI pins node-version "22".

ChatGPT parameters — confidence ratings

Parameter	Rating	Basis
q prefills	Solid	Dated 2026 sources; maintained tooling; OpenAI's own extension uses it; a live probe returned HTTP 200 with all parameters preserved.
q auto-submits	Refuted	Prefill-only in every dated report since 2025-11-11. Tenable TRA-2025-22 documents OpenAI gating auto-submit on Sec-Fetch-Site.
model honoured alongside q	Uncertain	An unresolved 2024-12-28 report says q forces GPT-4o regardless; counter-evidence exists from 2024–2025; no 2026 source positively confirms. Maintained tooling grades it experimental.
Valid model slugs	Uncertain	No authoritative list; sightings rot (gpt-4, o1-preview, gpt-4o, gpt-5-thinking, auto, instant, thinking).
temporary-chat=true	Uncertain	Community-confirmed originally; multiple reports of it not applying or reverting after the first message; OpenAI reworking the feature.
hints=search is a hint only	Confirmed	Multiple independent sources; "a frontend user interface hint, not a backend trigger".
hints=search still functions	Uncertain	Freshest positive source is provably recycling stale material; freshest negative is 2025-11-11. Costs nothing to append and degrades to a normal chat.
Stable set of hints values	Refuted	Published value sets contradict each other; only search has cross-source corroboration.
Officially documented by OpenAI	Refuted	No documentation for any parameter; primary community threads have zero staff replies.
/search path	Refuted	Began returning 404 mid-2025.
q canonicalises to prompt=	Confirmed	Dated 2026 reports; prompt= is the fallback if q dies.
Combining all four	Structurally safe	Nothing errors or gets stripped. But "the URL loads" is not "the parameter was honoured".

Unresolved

• Whether Firefox search-provider navigations land in the favoured Sec-Fetch-Site: none bucket for auto-submit. Inference from the Fetch Metadata spec, contradicted by a dated report of a default-search string losing auto-submit. Settled only by the manual parameter reality check.
• Whether Firefox enforces Chrome-style storage.sync write-rate quotas. The constants exist in the schema but no rate-limiting logic appears in the Rust backend. Made moot by debouncing writes.
• Whether Alt+Shift+G collides with OS-level or other-add-on shortcuts.