search-with-chatgpt-powered-by-openai-extension/docs/superpowers/plans/2026-10-05-advanced-context-menu.md

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.