From dc5bd8e00d53b7966c43e92244cac019c7dbbc29 Mon Sep 17 00:00:00 2001 From: golem Date: Sat, 1 Aug 2026 22:53:26 -0600 Subject: [PATCH] doc: document options panel, entry points, and the ChatGPT prefill limitation Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 48 +++++++++++++++++++++++++++++++++++++++++++----- CHANGELOG.md | 19 +++++++++++++++++++ README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 113 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9a2c2f9..38ca2ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,11 +2,19 @@ ## Project Structure & Module Organization -This is a manifest-only Firefox WebExtension with npm-based development tooling. +This is a Firefox WebExtension (Manifest V2) with npm-based development tooling. -- `manifest.json` defines the extension metadata and ChatGPT search provider. +- `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-x.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. @@ -19,8 +27,9 @@ Firefox Desktop is the only current implementation and release target. Do not ad - `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 and build checks together; run it before every pull request. +- `npm test` runs lint, unit tests, and build together; run it before every pull request. ## Coding Style & Naming Conventions @@ -28,9 +37,30 @@ Use two-space indentation in JSON, YAML, and JavaScript configuration. Preserve ## Testing Guidelines -Automated checks cover manifest validation and packaging, not browser behavior. After `npm test`, use `npm run dev` and confirm `gpt ` opens ChatGPT, the provider stays non-default, and Firefox search settings can configure it. Inspect ZIP contents whenever packaging rules or assets change. +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. -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. +After `npm test`, use `npm run dev` and confirm: + +- `gpt ` opens ChatGPT, the provider stays non-default, and Firefox + search settings can configure it. +- The Options/Preferences tab renders all five settings plus Restore defaults, + in both light and dark themes and at a narrow window width, and values + persist across a restart. +- The right-click **Ask ChatGPT** item appears only when text is selected. +- `Alt+Shift+G` acts on the selection, including a selection inside an iframe, + 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. + +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 @@ -41,3 +71,11 @@ Pull requests should explain the user-visible effect, list manual Firefox checks ## 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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 20bf935..a5e06d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,25 @@ All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version). +## [1.1.0] (2026-07-30) + +Adds an options panel and two new ways to reach ChatGPT. + + * Options panel in `about:addons` with five settings: model (experimental), + temporary chat, web-search hint, where results open, and a prompt template. + * Right-click selected text and choose "Ask ChatGPT" to open ChatGPT with that + text filled in. + * Keyboard shortcut `Alt+Shift+G` does the same for the current selection, and + opens an empty chat when nothing is selected. Rebindable via Manage Extension + Shortcuts. + * Documented that ChatGPT no longer submits prompts passed in a URL, so a + second Enter is needed. This is an upstream change to chatgpt.com. + * `gpt ` address-bar search is unchanged. + * The options panel, right-click item, and keyboard shortcut require Firefox + 112 or newer. Older versions keep the `gpt ` search unchanged. + * Permissions added: storage, menus, activeTab. None of them adds a line to + Firefox's install prompt. + ## [1.0.0]) (2024-06-09) First release of software. diff --git a/README.md b/README.md index ec0b98a..c764ea0 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,46 @@ This is an unofficial extension provided by Zavage Software Inc. See `LICENSE.txt` for licensing terms. +## Options + +Open `about:addons`, select this extension, and choose the **Options** tab +(**Preferences** on macOS and Linux). Available settings: + +- **Model** *(experimental)* — a model slug such as `auto`. ChatGPT may ignore + it and use your account default; leave blank to always use the account + default. +- **Request a temporary chat** — asks ChatGPT not to save the conversation. + ChatGPT may not honour this; check its own indicator before relying on it. +- **Ask ChatGPT to use web search** — a hint to ChatGPT's interface, not a + guarantee. +- **Open in** — a new tab, a new background tab, or a new window. +- **Prompt template** — wraps your text, for example `Explain simply: {query}`. + +These settings apply to the new entry points: selecting text and choosing +**Ask ChatGPT** from the right-click menu, or pressing +Alt+Shift+G. Rebind the shortcut under +**Manage Extension Shortcuts** in the Add-ons gear menu. + +The `gpt ` address-bar search is unchanged and does not read these +settings. + +The options panel, the right-click item, and the keyboard shortcut require +Firefox 112 or newer. On older versions the extension still installs and the +`gpt ` address-bar search still works; only these newer features are +inactive. + +## Why you press Enter twice + +ChatGPT no longer submits prompts that are passed to it in a URL — it fills them +into the composer and waits. So `gpt ` opens ChatGPT with your query +filled in, and you press Enter there to send it. + +This is a change OpenAI made to chatgpt.com, not a fault in this extension, and +it is outside our control. It was a deliberate security measure: automatically +running a prompt that arrived in a link let malicious links execute instructions +in a signed-in ChatGPT session. The extra keypress is the checkpoint that +prevents that. No API key, server, or intermediary is involved either way. + ## Browser Support Firefox Desktop is the current development and release target. Chrome, Brave, @@ -44,4 +84,14 @@ configured in Firefox search settings. ## Privacy Policy -This extension collects zero user data. +This extension has no server, no API key, and no intermediary. Nothing is +reported to Zavage Software. + +- Your settings are stored in your own browser profile. If you use Firefox Sync + with **Add-ons** enabled, they sync end-to-end encrypted through your own + Mozilla account. +- When you choose **Ask ChatGPT** or press the shortcut, the text you selected + is placed in the chatgpt.com URL the extension opens for you. It goes nowhere + else. +- The extension reads a page's selected text only at the moment you invoke it, + and never reads page addresses or titles.