fix(desktop): route mouse thumb buttons to the in-app browser

[akosbalogh]

Fixes #4839

What changed

Mouse thumb (side) buttons — back = button 3, forward = button 4 — now navigate the in-app browser's history when the pointer is over the preview <webview>, instead of navigating the host T3 Code app (threads/agents view).

Why

The preview is an Electron <webview> whose WebContents is driven by PreviewManager. When the pointer merely hovers the guest page (the guest isn't focused), Chromium routes thumb-button history navigation to the focused WebContents — the host app renderer — so pressing back/forward over the browser sent the app router back instead of the browser. This was intermittent ("sometimes") because it depended on which surface held focus.

Note app-command is Windows/Linux-only and Electron never auto-navigates on it, and this repo has no handler — so that path is deliberately untouched. The DOM-level path is the mechanism here.

How

• PickPreload.ts (runs inside every preview guest): capture-phase listeners for the thumb buttons preventDefault() + stopImmediatePropagation() on mousedown/mouseup/auxclick to suppress Chromium's default navigation, and forward an explicit { direction } over a new MOUSE_NAVIGATE_CHANNEL IPC. Guarded by event.isTrusted so automation-injected events are unaffected.
• Manager.ts: attachListeners registers a mouseNavigate handler that drives that tab's history via the existing wc.navigationHistory.goBack()/goForward() (guarded by canGoBack()/canGoForward()), mirroring the existing UI back/forward path. Registered/torn down alongside the existing HUMAN_INPUT_CHANNEL listener.
• GuestProtocol.ts: new MOUSE_NAVIGATE_CHANNEL constant.

Suppression in the guest is unconditional, so the host app never navigates while the cursor is over the browser — even when the browser has no back history.

Testing

• New unit test in Manager.test.ts asserting the IPC handler drives goBack/goForward, ignores unknown payloads, and does nothing when history is exhausted.
• Manually exercised on macOS against a dev build: with the main-process handler instrumented, the guest was confirmed to receive and forward both directions with the correct tab id, and the preview navigated its own history.
• apps/desktop typecheck, lint, format pass locally. Repo-wide vp check reports 0 errors and the desktop suite passes 368/368 — worth noting since CI on this PR is still sitting at action_required pending maintainer approval, so none of it has run here.

🤖 Generated with Claude Code

---

Note

Low Risk
Localized preview input/navigation wiring with validation and history guards; no auth, data, or broad architectural changes.

Overview
Mouse thumb buttons (back / forward) over the preview webview now move that tab’s browser history instead of the host app router when the guest isn’t focused.

PickPreload intercepts trusted thumb-button events in capture phase, blocks Chromium’s default routing, and sends { direction } on preview:mouse-navigate. PreviewManager handles that IPC like existing guest channels and calls navigationHistory.goBack() / goForward() only when canGoBack / canGoForward allow it.

A unit test covers back/forward, invalid payloads, and no-op when history is exhausted.

^{Reviewed by Cursor Bugbot for commit deb168a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0dc2f95d-435f-40a2-8825-4f0f8fbd0cc2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved

This is a targeted bug fix for mouse thumb button navigation in the in-app browser. The changes follow existing patterns in the codebase, include comprehensive tests, and are self-contained within the preview system without touching sensitive areas.

^{You can customize Macroscope's approvability policy. Learn more.}