Agentic UI: Add a right-click context menu to the Studio browser

[shaunandrews]

Related issues

• Related to Agentic UI: add a native text context menu #4388 (the same problem in the chat panel)

How AI was used in this PR

AI wrote the implementation and tests from a scope I set. I reviewed the approach and tested it against a running site.

Proposed Changes

Right clicking in Studio's in-app web browser does nothing. This PR introduces an OS-native right-click contextual menu in the Studio browser. This enables users to right click on text, images, and more to copy elements, open the dev tools, and more — including the ability to start annotating for Studio Code.

• Annotate Element comes first: right-click anything in your site and start an annotation on it directly, without switching into picking mode first. It only appears while the annotation inspector is actually attached to the page, so it's never offered on a page where nothing would happen.
• On a link — Open Link in Browser, Copy Link Address. Opening goes to the real browser, matching what already happens when a previewed page tries to open a popup.
• On an image — Copy Image, Copy Image Address, Open Image in Browser. Only for images that actually loaded; a broken image has nothing to copy.
• On a selection — Copy, and on macOS Look Up "…", which opens the system Dictionary panel.
• In a form field — Cut, Copy, Paste, Select All, as the field's state allows. On ordinary page text only Copy is offered, since Select All would highlight the whole document and Cut/Paste mean nothing there.
• Always — Inspect Element. Not limited to development builds: inspecting the page you're building is the point of the preview, and Electron keeps DevTools available when packaged.

Nothing appears greyed out that could simply be absent. Right-clicking plain text gets you two items, not a wall of them.

Back/Forward/Reload are deliberately absent — the preview's own toolbar already has them, and adding them here made every right-click longer without adding a capability.

Known cosmetic limitation: Look Up placement

On macOS the dictionary panel opens with the right definition but in the wrong
place — it and its floating copy of the word land offset from the actual
selection. macOS anchors the panel to a selection rect the guest page reports in
its own coordinate space, and nothing translates it by the <webview>'s offset
within the window, so the panel and its text shift together.

This isn't fixable from our side: showDefinitionForSelection() takes no
position argument, and we don't place the panel. It's the same class of problem
Electron now warns about generally — its <webview> docs say the tag is
"undergoing dramatic architectural changes" that affect "the stability of
webviews, including rendering", and recommend WebContentsView instead.

Shipping it anyway: the definition is correct, the misplacement is cosmetic, and
having Look Up is more useful than not. The alternative (dict://, which opens
Dictionary.app) is accurate but a worse experience than an inline panel. The
call site carries a comment so the next person doesn't re-derive this. Note the
chat panel's Look Up (#4388) is unaffected — it runs on the host renderer, where
there's no guest offset.

Deliberately not included, both worth their own PR:

• Save Image As / Save Link As — needs a download flow (downloadURL, a will-download handler, a save dialog) with its own error and overwrite handling.
• Spellcheck suggestions in preview form fields — params.misspelledWord and dictionarySuggestions are available, but the spellchecker isn't configured anywhere in the app yet, so this needs setSpellCheckerLanguages and a decision about which languages to load.

This is desktop-only by nature: in the browser builds the preview is a cross-origin <iframe> and Chrome's own menu already works there.

Testing Instructions

Main-process change, so it needs a full app restart — rs / hot reload won't pick it up.

1. Start a site and open the preview panel.
2. Right-click plain page text — just Annotate Element and Inspect Element. No Back/Forward, no Select All.
3. Right-click any element and choose Annotate Element — the annotation popup opens on that exact element, without having pressed Annotate first. Add a comment and save; the marker appears on it and the count goes up, so "Submit annotations" works as usual.
4. Right-click a link — Open Link in Browser, Copy Link Address.
   • Open Link in Browser should open your actual browser, not navigate the preview.
   • Copy Link Address should paste the URL.
5. Right-click an image (a media item, or the site logo) — Copy Image, Copy Image Address, Open Image in Browser. Copy Image should paste as an image into something that accepts one; Open Image in Browser should open the file itself in your browser.
6. Select text in the page and right-click it — Copy, plus Look Up "…" on macOS. Look Up should open the system Dictionary panel with the correct definition. Expect it to appear offset from the selection — see the known limitation above; that's not a regression to report.
7. Right-click a form field (a comment box, or the WP admin login) — Cut/Copy/Paste/Select All as applicable. Paste only shows when the field can accept it.
8. Choose Inspect Element — DevTools opens on that node. Worth confirming in a packaged build too, since it's no longer dev-only.
9. Right-click during a page load (before the inspector re-attaches) — Annotate Element should be absent rather than present and inert.

Unit tests: npm test -- apps/studio/src/tests/preview-context-menu.test.ts

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

Notes for reviewers:

• The browser items are entirely main-process: one new module plus a few lines in the existing web-contents-created block in index.ts.
• Annotate Element needs a little more: the guest page's inspector script records which element was right-clicked (its own contextmenu listener always runs before the menu is even requested), so no coordinates have to survive the trip out to the main process and back. The renderer pushes inspector readiness to main as plain state, which can't race the click that opens the menu.
• Unlike Agentic UI: add a native text context menu #4388, the main process can own this menu outright — everything it needs is already in ContextMenuParams, so nothing has to be asked of a renderer.
• apps/studio and apps/ui typecheck clean, eslint clean, 10 new unit tests, both full suites pass (160 files, 1111 tests).
• npm run typecheck currently fails in apps/cli on @earendil-works/pi-ai. That's pre-existing on trunk (stale node_modules after the recent packages/common bump), not from this branch. npm install clears it.

[wpmobilebot]

📊 Performance Test Results

Comparing 8d0e42d vs trunk

app-size

Metric	trunk	8d0e42d	Diff	Change
App Size (Mac)	1378.85 MB	1378.86 MB	+0.01 MB	⚪ 0.0%

site-editor

Metric	trunk	8d0e42d	Diff	Change
load	1067 ms	1064 ms	3 ms	⚪ 0.0%

site-startup

Metric	trunk	8d0e42d	Diff	Change
siteCreation	6990 ms	6991 ms	+1 ms	⚪ 0.0%
siteStartup	2389 ms	2385 ms	4 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)