feat: add advanced context actions and optional translation

docs/advanced-context-menu-verification.md

@@ -0,0 +1,65 @@
+# Advanced context menu verification
+
+Implemented against the approved 2026-10-05 spec and plan. Implementation was verified in the feature checkout. PR preparation commits
+the extension changes separately from unrelated local notes. No release or
+permission change is included.
+
+## Automated checks
+
+- `npm test`: strict lint with zero errors, notices, or warnings; 10 discovered
+  test files passed; unsigned ZIP built successfully.
+- Direct execution of each test file: **60 individual tests passed**.
+- ZIP inspection: dialog assets present; no docs, tests, or execution scratch.
+- `git diff --check`: clean.
+- Regression checks cover legacy preference migration, partial-save preservation,
+  context priority, dedicated prompts, literal substitutions, URL rejection,
+  Unicode budgets, truncation consent, dialogs, menu updates, and frame focus.
+
+## Actual Firefox 157 checks
+
+Temporary Firefox launched through `npm run dev`; interactions automated using
+Marionette in a temporary profile. No user's browsing profile was modified.
+
+- Native selection, link, linked-selection, and page-background menus displayed
+  the intended action groups.
+- Extension dialog handoff acknowledged; language input received initial focus;
+  Spanish translation opened the correctly constructed ChatGPT URL.
+- Concurrent dialogs held separate selections. Cancel and actual Escape key
+  dispatch opened no ChatGPT tab. Empty language submission was blocked.
+- Long selection displayed consent; Continue opened an 8,000-character URL.
+- Settings reflected storage updates. Narrow light/dark settings screenshots
+  were inspected and showed no horizontal overflow.
+- Extension reload preserved configured preferences.
+
+Not verified: physical shortcut presses in the user's desktop session (headless
+WebDriver key attempts did not trigger the command), full browser restart,
+forced background suspension/wakeup, all editable-field cases, dialog-window
+creation failure on the native desktop, and the complete AGENTS.md manual matrix.
+The shortcut's frame-selection logic is covered by an executable regression test,
+including stale parent selection and restricted-page failure.
+
+## Independent review
+
+A fresh reviewer found no blocking defect. Its partial-save contract finding
+was reclassified as important and fixed with a failing-then-passing regression.
+One minor remains: if a direct launch fails but a retry dialog opens, the dialog
+says it is ready rather than explaining the original failure. Continue retries.
+
+## Execution decisions
+
+- Worked in the existing feature checkout with a backup at
+  `/tmp/chatgpt-advanced-baseline`; this preserves prior uncommitted work but
+  means new work shares that checkout.
+- Deferred implementation commits to avoid sweeping unrelated changes into them;
+  review uses the saved baseline instead of task commit ranges.
+- Target languages must be single-line text of at most 100 Unicode code points;
+  unusual control-character labels are rejected.
+- Menu-open visibility uses permission-free Firefox context labels. Source data
+  is read only at invocation. Whitespace-only selections may show a group but
+  cannot trigger a nonempty-source action.
+- Partial settings updates retain their original contract so unrelated settings
+  cannot be reset; the extra regression test protects that contract.
+- Prior shortcut-editor behavior and other unrelated dirty changes were kept;
+  their preexisting limitations are outside this change.
+- ChatGPT honoring hints or retrieving a URL remains external behavior, described
+  as best effort rather than guaranteed.

docs/future-issue-proposals.md

@@ -0,0 +1,149 @@
+# Future issue proposals
+
+Drafts for consideration, not filed issues or committed release milestones.
+Firefox Desktop remains the only target. Suggested order starts with named
+prompt actions; research tasks can run independently.
+
+## 1. Add named prompt actions
+
+**Priority:** High. **Type:** Enhancement.
+
+The extension currently supports one global prompt template. Let users save
+several named actions such as Explain, Summarize, Translate, and Rewrite.
+
+Acceptance criteria:
+- Create, edit, reorder, and delete actions in settings.
+- Choose an action from a compact selection context submenu.
+- Preserve the existing template and shortcut behavior during migration.
+- Treat templates as text, never executable code; validate limits and handle
+  storage sync quota failures visibly.
+- Test placeholder substitution with arbitrary selected text.
+
+## 2. Add link and page context actions
+
+**Priority:** Medium. **Type:** Enhancement.
+
+Selection context already exists. Add explicit actions for a clicked link and
+the current page, initially passing the URL rather than extracting full text.
+Sending a URL does not guarantee ChatGPT can access or summarize its contents.
+
+Acceptance criteria:
+- Clearly identify whether the action shares selected text, a link, or a page URL.
+- Do not include page metadata automatically in existing selection actions.
+- Handle restricted pages and unsupported URL schemes gracefully.
+- Review URLs containing private query data and update privacy documentation
+  for the new data flow before release.
+- Assess permissions against the existing design spec; full-page extraction
+  is a separate proposal requiring explicit scope and permission review.
+
+## 3. Add a toolbar quick-launch popup
+
+**Priority:** Medium. **Type:** Enhancement.
+
+Provide a prompt field, access to named actions, and a link to settings from
+the toolbar. Reuse the existing URL builder and open-location preferences.
+
+Acceptance criteria:
+- Keyboard-accessible prompt entry and launch action.
+- Empty input opens a blank chat.
+- Named actions appear when available; the popup can ship independently.
+- Works in light/dark themes and a narrow popup.
+- No automatic page capture; any selection action is explicit.
+
+## 4. Investigate advanced address-bar commands
+
+**Priority:** Medium. **Type:** Research, followed by enhancement if viable.
+
+Investigate an omnibox entry point that reads saved settings and recognizes
+commands such as `!search` and `!temp`. The current search provider uses a
+static URL and does not read extension preferences.
+
+Acceptance criteria:
+- Verify interaction with the installed engine and its user-customized keyword.
+- Document any difference between Firefox's search keyword and the extension's
+  manifest-declared omnibox keyword; do not promise runtime keyword editing.
+- Specify escaping so users can search for literal command text.
+- Preserve ordinary address-bar searches and open-location behavior.
+- Keep search/temporary options labeled as hints where not guaranteed.
+- Defer `!think` until model/effort research establishes a working mechanism;
+  adding “think harder” to a prompt is not an effort-setting implementation.
+- Do not reintroduce auto-submit; review Appendix B of the existing design spec.
+
+Reference: [Mozilla omnibox API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/omnibox).
+
+## 5. Add settings export and import
+
+**Priority:** Medium. **Type:** Enhancement.
+
+Settings already use `browser.storage.sync`. Add portable JSON backup and
+restore, including named actions if that feature ships.
+
+Acceptance criteria:
+- Export a versioned settings document without account or browsing data.
+- Validate file size, schema, field types, and supported versions before writing.
+- Preview replacement and require an explicit import action.
+- Reject invalid input without changing current settings.
+- Handle old versions, unknown fields, and storage failures predictably.
+- Do not imply that Firefox-owned engine keywords or shortcuts are backed up.
+
+## 6. Evaluate Firefox Manifest V3 migration
+
+**Priority:** Low until a concrete benefit or requirement is identified.
+**Type:** Research/maintenance.
+
+Evaluate MV3 separately from user features. The existing options framework,
+normal launch, temporary-chat hint, and web-search hint do not need to be
+reimplemented as a bundled milestone. MV3 does not establish model control.
+
+Acceptance criteria:
+- Document Firefox-specific benefits, costs, and minimum supported version.
+- Audit background lifecycle, script injection, permissions, search provider,
+  options, and packaging against Mozilla's migration guide.
+- If proceeding, preserve settings and verify all existing Firefox workflows.
+- No Chromium packaging or sibling-repository changes.
+
+Reference: [Firefox MV3 migration guide](https://extensionworkshop.com/documentation/develop/manifest-v3-migration-guide/).
+
+## 7. Investigate optional Firefox Containers integration
+
+**Priority:** Low. **Type:** Research.
+
+Explore opening ChatGPT in a user-selected existing container for account
+separation. Keep integration opt-in and justify any additional permissions.
+
+Acceptance criteria:
+- Verify the permission requirements for listing containers and opening tabs
+  in them; the contextualIdentities API documents contextualIdentities and
+  cookies permissions.
+- Review the existing permission design before implementation.
+- Handle missing/deleted containers, denied permissions, disabled containers,
+  and private browsing without silently switching accounts.
+- Determine which entry points can honor the preference; do not promise that
+  the static Firefox search provider can use it.
+- Explain that containers separate sessions; they do not make chats temporary.
+
+Reference: [Mozilla contextualIdentities API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/contextualIdentities).
+
+## 8. Research reliable ChatGPT model and thinking-effort selection
+
+**Priority:** High interest; blocked on evidence of a reliable mechanism.
+**Type:** Research, not a promised feature.
+
+User testing did not achieve the requested behavior using the temporary URL
+probe with `prompt`, `model=gpt-5-6-thinking`, `hints=search`, and
+`thinking_effort=extended`. This does not independently establish which fields
+were ignored. Earlier model URL tests also failed to switch the selected model.
+
+Acceptance criteria:
+- Record a reproducible browser test and observable evidence of the actual
+  selected model/effort; a URL parameter or model self-report is insufficient.
+- Verify identifiers and distinguish URL prefill from conversation POST data.
+- Prefer a documented integration; document maintenance and permission costs
+  before considering page automation or internal endpoints.
+- Do not introduce controls claiming success without verified behavior.
+- Treat a public-API implementation as a separate product decision, including
+  authentication, billing, privacy, and its different user experience.
+- Remove the temporary URL test UI before release once investigation is done.
+
+Shared release constraint: preserve user submission in ChatGPT and the current
+minimal-permission approach unless a separately reviewed change justifies more.

docs/superpowers/plans/2026-10-05-advanced-context-menu.md

@@ -0,0 +1,166 @@
+# Advanced Context Menu Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add optional contextual prompt presets and opt-in translation while preserving the existing simple action.
+
+**Architecture:** Pure modules define settings, actions, and launch preparation. Firefox adapters register menus and open tabs/windows; a packaged dialog handles language entry, truncation consent, and errors. Direct and dialog launches share preparation and opening code.
+
+**Tech Stack:** Firefox Desktop MV2 WebExtensions, ES modules, vanilla HTML/CSS, node:test, web-ext; Node.js 22+.
+
+**Spec:** `docs/superpowers/specs/2026-10-05-advanced-context-menu-design.md`
+
+## Global Constraints
+
+- Firefox Desktop remains the only target.
+- Preserve the current `storage`, `menus`, and `activeTab` permissions.
+- No new host permissions, telemetry, intermediary service, runtime dependency, or API key is part of this design.
+- Retain the current 8,000-character serialized URL budget.
+- Users still review and submit in ChatGPT; no auto-submit or internal ChatGPT request modification.
+- Options remain inline in `about:addons` and use existing visual styles.
+- Preserve existing uncommitted changes; they are the working baseline, not disposable noise. Review the working tree before creating an isolated execution checkout; do not branch from HEAD alone and lose that baseline.
+- Stage task-specific changes only. Many target files already contain prior work: inspect each staged diff and avoid committing unrelated hunks.
+
+## Review Focus
+
+- A selection inside a link must expose selection actions only (Task 2/5).
+- A repeated `{query}` template must remain intact while budgeting repeated source text (Task 3).
+- A language containing `&` or non-BMP characters must display literally and obey the 100-code-point limit (Task 1/5/6).
+- Background suspension or two simultaneous translation dialogs must not mix or lose an acknowledged request (Task 4).
+- Cancel, duplicate Enter, and a failed launch must never send twice or report success prematurely (Task 4).
+
+## File map and contracts
+
+- Modify `lib/defaults.js`, `lib/settings.js`: new defaults and legacy migration.
+- Create `lib/actions.js`: context selection, action IDs, prompt rendering, language labels.
+- Modify `lib/build-url.js`: retain URL encoding, expose untruncated prompt serialization.
+- Create `lib/prepare-action.js`: pure validation and length decisions.
+- Create `background/open-chat.js`: tab/window opening with fallback.
+- Create `background/dialogs.js`: initial request handoff to packaged dialog.
+- Create `background/menus.js`: menu registration and visibility updates.
+- Modify `background/background.js`: compose modules and route entry points.
+- Create `dialog/action.html`, `dialog/action.css`, `dialog/action.js`, `dialog/controller.js`: accessible dialog shell and controller.
+- Modify `options/options.html`, `options/options.js`; create `options/menu-settings.js`: new controls, dependencies, validation.
+- Tests mirror these responsibilities under `test/`; docs changes remain in README/CHANGELOG.
+
+Shared data types (plain JavaScript objects, documented with JSDoc):
+
+`ActionRequest = { actionId, source, settings, language? }`, where settings is a
+sanitized snapshot, source is a string, and actionId is one of `ask`, `explain`,
+`summarize`, `debug`, `translate`, `ask-link`, `review-link`, `ask-page`,
+`summarize-page`. Only `ask` permits an empty source (blank-chat shortcut).
+
+`Preparation = {kind:'ready',url} | {kind:'language'} |
+{kind:'shortened',url} | {kind:'error',message}`.
+
+## Task 1: Settings schema and migration
+
+**Files:** Modify `lib/defaults.js`, `lib/settings.js`, `test/settings.test.js`.
+
+**Interfaces:** Preserve `mergeSettings(stored)`, `load()`, `save(partial)`.
+New keys: contextMenuMode (`off|simple|advanced`, default simple), showTranslate
+(false), translationMode (`ask|preferred`, default ask), translationLanguage
+(empty). Export `normalizeLanguage(value) -> string` from settings: trim,
+return empty on invalid type or more than 100 code points.
+
+- [ ] Add failing assertions for `mergeSettings({showContextMenu:false}).contextMenuMode === 'off'`, absent legacy => simple, valid new mode wins over legacy, invalid new mode falls back through legacy, and unknown keys are removed.
+- [ ] Add assertions that 100 emoji are accepted, 101 rejected, whitespace trims, and wrong language/mode/boolean types default. Update existing expected setting shapes without dropping their coverage.
+- [ ] Run `node --test test/settings.test.js`; confirm new assertions fail for the intended missing behavior.
+- [ ] Implement defaults and migration. `load()` requests both new keys and legacy `showContextMenu`; save writes normalized new keys, not a legacy boolean. Do not delete old data as an initialization side effect.
+- [ ] Run `node --test test/settings.test.js`; require nonzero passing tests. Verify load against a fake storage containing only the legacy key.
+- [ ] Review/stage only this task and commit `feat: migrate context menu and translation preferences`.
+
+## Task 2: Context and dedicated prompt definitions
+
+**Files:** Create `lib/actions.js`, `test/actions.test.js`.
+
+**Interfaces:** `getContext(info) -> {kind:'selection'|'link'|'page',source}|null`;
+`getActions(context,settings) -> [{id,title}]`; `renderPrompt(request,sourceOverride=request.source) -> string`.
+`getContext` accepts menu event data, prioritizes nonblank selection then link,
+then page URL, and excludes password inputs and media-only contexts. Empty
+editable fields get no page group. Link/page URL validation belongs to Task 3.
+
+- [ ] Add tests asserting linked selection chooses selection, empty selection chooses link, media-only and password contexts return null, and page background uses pageUrl. Selection order must be ask/explain/summarize/debug, with translate appended only when enabled.
+- [ ] Add prompt assertions: default action applies the saved template; Explain/Debug ignore it; Translate includes the language; link-safety prompt asks for evidence/uncertainty and never claims completed checks. Preserve literal `$&`, `$$`, backticks, Unicode and braces in source text. Escape `&` in menu language labels.
+- [ ] Run `node --test test/actions.test.js`; confirm intended failures.
+- [ ] Implement fixed action definitions and dedicated prompts matching the spec table. Extract/reuse existing literal template replacement instead of implementing conflicting replacement semantics. Blank `ask` renders empty even with a nonempty template.
+- [ ] Run `node --test test/actions.test.js test/build-url.test.js`; expect all passing.
+- [ ] Commit reviewed task hunks as `feat: define contextual prompt actions`.
+
+## Task 3: Safe action preparation and length decisions
+
+**Files:** Modify `lib/build-url.js`; create `lib/prepare-action.js`, `test/prepare-action.test.js`; extend `test/build-url.test.js`.
+
+**Interfaces:** `serializePrompt(settings,prompt) -> string` encodes an already
+rendered prompt without truncating. Keep legacy `buildChatGptUrl` compatibility
+for existing tests until routing is replaced. `prepareAction(request) -> Preparation`
+uses Task 2 rendering, Task 1 normalization, and `MAX_URL_CHARS`.
+
+- [ ] Add assertions for ready URLs <=8000, translation needing a language, invalid/credential-bearing/non-HTTP URLs producing error, and oversized URLs producing error rather than shortened. Accepted URL source must survive unchanged within decoded prompt.
+- [ ] Add budget tests for repeated `{query}`, emoji, whitespace boundaries, hint overhead, oversized instructions, and the shortening marker. Every shortened result retains all fixed instructions and substitutes only a shortened source; a small source remains byte-identical after decoding.
+- [ ] Run `node --test test/prepare-action.test.js`; confirm failures.
+- [ ] Implement validation and binary search over source code points, measuring the fully rendered/encoded prompt each time. Reserve the marker `[Selected text shortened]` only when shortening. Prefer a late whitespace boundary as in existing builder. Reject unknown action IDs and missing required sources.
+- [ ] Run `node --test test/prepare-action.test.js test/build-url.test.js test/actions.test.js`; require passing assertions and nonzero discovery.
+- [ ] Commit reviewed changes as `feat: prepare actions with explicit truncation decisions`.
+
+## Task 4: Launch helper and reliable extension dialogs
+
+**Files:** Create `background/open-chat.js`, `background/dialogs.js`, `dialog/action.html`, `dialog/action.css`, `dialog/action.js`, `dialog/controller.js`, `test/open-chat.test.js`, `test/dialog.test.js`.
+
+**Interfaces:** `openChat(browser,url,openIn) -> Promise<void>` rejects after
+final failure. `showActionDialog(browser,payload) -> Promise<void>` transfers
+`payload={request,preparation}` to the dialog. `initializeDialog({browser,document,window})`
+owns UI and launch after handoff, using Tasks 1–3 and openChat.
+
+- [ ] Write boundary tests: new-window fallback opens a tab, background-tab uses active:false, final failure rejects; language whitespace blocks submit, Cancel/Escape never launch, double submit launches once, rejected launch permits retry, shortening requires explicit consent.
+- [ ] Write handoff tests with two opaque IDs and distinct sources: wrong sender/ID cannot claim data; after acknowledgment clearing background state does not affect dialog completion; closed/uninitialized dialogs release requests and show retry rather than processing missing data.
+- [ ] Run `node --test test/open-chat.test.js test/dialog.test.js`; confirm failures.
+- [ ] Implement tab/window helper and dialog shell. Use runtime extension-page messaging plus a random request ID, verify sender extension URL and associated tab ID, transfer a structured snapshot, acknowledge receipt, then release background payload. Keep launch handling active through handshake; register listeners before opening. Apply a finite 15-second initialization timeout, with clear retry copy; never time out user language entry after handoff. No selected content in URLs, logs, or storage.
+- [ ] Implement dialog controller: validate language, rerun preparation, show shortening confirmation if needed, disable launch controls while pending, show errors/retry, close only after success. Use textContent for all source-derived UI. Window creation falls back to an extension tab; closing that surface cancels. Use the same shell for direct-launch error messages.
+- [ ] Run boundary tests and manually probe actual Firefox event-page handoff/idle behavior before accepting this task. If lifecycle assumptions fail, correct the handoff design within the approved no-persistence/no-permission constraints before wiring menus.
+- [ ] Commit task-specific files as `feat: add action dialogs and shared launch handling`.
+
+## Task 5: Register adaptive menus and route the shortcut
+
+**Files:** Create `background/menus.js`, `test/menus.test.js`; modify `background/background.js`.
+
+**Interfaces:** `initializeMenus({browser,load,onAction})` registers menus,
+storage listener, onShown/onClicked, and serializes rebuilding. onAction receives
+an ActionRequest. `runAction(request)` in background uses prepareAction then
+openChat for ready or showActionDialog otherwise; errors use dialog feedback.
+
+- [ ] Add tests: Off has no root, Simple has one selection-only direct action, Advanced has one root with correct children; onShown reveals exactly one context group and refreshes; selection over link wins; live translation/mode changes rebuild without races.
+- [ ] Add assertions that unexpected/stale item IDs or mismatched click contexts do not launch, preferred-language labels escape ampersands, and click creates one settings/source snapshot. Verify shortcut invokes `ask` independently of menu mode, including empty selection.
+- [ ] Run `node --test test/menus.test.js`; confirm failures.
+- [ ] Implement adapter using existing serialized removeAll/create pattern, namespaced stable IDs and visibility updates. Verify current Firefox menu APIs from Mozilla primary docs at execution time. Preserve the shortcut's focused-frame selection contract and existing fallback behavior; do not expand page-reading scope.
+- [ ] Route both entry points through shared preparation, including truncation consent for Simple and shortcut. Remove obsolete menu listeners to prevent duplicates.
+- [ ] Run all unit tests. Manually check AGENTS.md frame cases; if the existing ancestor-focus bug is reproduced, make the focused-frame guard correction with a regression check before claiming shortcut preservation.
+- [ ] Commit reviewed changes as `feat: wire simple and advanced context menus`.
+
+## Task 6: Options UI, release cleanup, and complete verification
+
+**Files:** Modify `options/options.html`, `options/options.js`, `options/options.css` if needed; create `options/menu-settings.js`, `test/menu-settings.test.js`; modify `README.md`, `CHANGELOG.md`.
+
+**Interfaces:** `initializeMenuSettings({document,onChange}) -> {render(settings),collect()}`
+owns context/translation controls. Existing options renderer delegates these
+keys rather than assuming every preference maps to a checkbox/text input.
+
+- [ ] Write UI boundary tests for Off/Simple/Advanced dependent visibility, opt-in translation, preferred-language validation, retaining hidden preferences, migration display, and Restore defaults. Assert language length uses code points rather than HTML UTF-16 maxlength alone.
+- [ ] Run `node --test test/menu-settings.test.js`; confirm failures.
+- [ ] Add controls with approved exact labels, reuse existing styles and debounce/save behavior. Invalid preferred language displays inline guidance; launch behavior remains dialog fallback. Preserve active input against storage echoes. Update restore/shortcut copy that assumes five settings or a checkbox.
+- [ ] Remove temporary URL-test HTML and handler. Update README/CHANGELOG and privacy section to describe URL sharing, menu modes, opt-in translation, length consent, and unchanged address-bar behavior.
+- [ ] Run `npm test`; require lint with zero warnings, nonzero passing unit tests, and a successful ZIP build. Inspect ZIP entries for new dialog assets and absence of any `docs/` or `test/` entries; do not alter packaging exclusions unless inspection finds a defect.
+- [ ] Run `npm run dev` and execute every manual check from the approved spec and AGENTS.md, including light/dark/narrow settings/dialogs, keyboard focus/cancellation, concurrent requests, idle/wakeup, long selection, URL rejection, menu precedence, restart persistence, and all shortcut frame cases. Record actual observed results; ask for user assistance if native interaction is unavailable rather than counting a headless launch as behavioral coverage.
+- [ ] Run `git diff --check`, review permissions/search URL/package changes, and commit only reviewed task hunks as `feat: expose advanced menu preferences and usage guidance`.
+
+## Completion and review
+
+Execution must begin with a baseline snapshot/status review and the appropriate
+isolation skill; unresolved existing work must not be overwritten. No release,
+AMO upload, push, or merge is authorized by this plan. Finish with a review of
+the complete change and a report of automated and actual Firefox checks,
+including any checks still requiring user interaction.
+
+Plan self-review: spec sections map to Tasks 1–6; all five Review Focus cases
+are assigned tests. Shared signatures use the ActionRequest/Preparation types
+above. Lifecycle handoff is intentionally verified before entry-point wiring.