Skip to content

fix(desktop): walk history on mouse Back/Forward sent as macOS swipes - #23013

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:fix/desktop-mouse-back-forward
Oct 23, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:fix/desktop-mouse-back-forward

Conversation

@unstablebrainiac

@unstablebrainiac unstablebrainiac commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: In the macOS desktop app, a mouse's Back and Forward buttons walk the dashboard's history, the way they do in Chrome.

On macOS, when a mouse's Back and Forward side buttons are handled by Logitech's Options software (Logi Options+ for an MX Master) or a utility like SensibleSideButtons, they do nothing in the desktop app. The same buttons go back and forward through the dashboard in Chrome. Reproduced on an MX Master 4.

Why it matters

Side buttons are how many desktop users go back. Anyone whose mouse software sends them as swipes loses the gesture in the app only, and the app feels broken next to the browser. The top-bar arrows and ⌘← / ⌘→ still work, but cost a trip to the corner or a hand on the keyboard.

Not a goal

  • Changing what raw buttons 4 and 5 do. Chromium already walks the history for them, in the browser and in the app.
  • Binding ⌘[ / ⌘] to history. They stay session cycling, so a Logitech profile that sends those keys keeps cycling sessions.
  • Mouse buttons on Windows and Linux. Nothing is reported there and nothing changes there.
  • The two-finger elastic page swipe. Electron reports only the legacy swipe event.
  • Moving the arrows into the View menu (feat(desktop): move Back/Forward from header arrows to View menu #14809).

What changed (motivation → approach → change)

The mouse's Back and Forward buttons now step through the dashboard's history in the macOS app.

When Logitech's Options software or a utility like SensibleSideButtons handles those buttons, macOS apps receive them as swipe gestures, not as buttons 4 and 5, so the page never sees a button press. Chrome turns the swipe into Back or Forward. Electron does not navigate for it. It only emits the window's swipe event, and the desktop shell had no listener, so the press was dropped.

The shell now listens for swipe on each dashboard window and relays a left or right swipe to the dashboard as one history step (electron/swipe-history.js, the preload's onHistoryStep, declared in types/electron-bridge.d.ts). The dashboard takes that step the way the top-bar arrows do (shell/platform/nativeHistoryStep.ts, used by the app shell). It asks about an unsaved draft first, does nothing when there is nowhere to go, and stays inert on a narrow viewport where the arrows are hidden. A swipe carries no position, so the shell reads the cursor: over a visible native browser panel the step goes to that page's own history, which is where Chromium sends plain buttons 4 and 5. The new module is listed in the packaged app's build.files, and the feature map row for route-history Back/Forward names the new entry point.

Input in the macOS app Before After
Mouse Back / Forward sent as a swipe (Logitech's Options software and similar) nothing one step back / forward, draft prompt included
Trackpad three-finger page swipe (same event) nothing the same step
Either of those over the embedded browser panel nothing that page goes back / forward
Mouse buttons 4 / 5 without that software Chromium's own Back / Forward unchanged

Backwards compatibility

Compatible: the diff adds a window listener, an optional preload method and a hook. A dashboard on an older shell finds no onHistoryStep and does nothing, and an older dashboard on this shell never listens on the new channel.

Removes nothing: no path, key, record or behaviour is taken away; the change only adds an input path to existing navigation.

Tests

  • website/electron/test/swipe-history.test.js (new): a left swipe sends Back and a right swipe sends Forward; vertical and unknown directions send nothing; nothing is sent once the window is torn down, and a webContents that throws mid-teardown is tolerated; a swipe over a browser panel steps that page and leaves the dashboard alone, and does nothing when the page has nowhere to go; the panel hit test reads the cursor in content-area coordinates, excludes the far edges, and skips a hidden panel or a destroyed page; every dashboard window arms the relay with the cursor-based hit test; the preload listens on the channel the relay sends.
  • website/electron/test/shell-contract.test.js (unchanged): its packaging allowlist check now covers swipe-history.js.
  • website/electron/test/window-lifecycle.test.js: the macOS wiring order lists the swipe listener, armed right after the splash-history guard.
  • website/src/test/nativeHistoryStep.test.tsx (new): a relayed Back and Forward walk a real BrowserRouter stack; no history move is issued with nowhere to go, or for any value but -1 and 1; a dirty draft is asked about first and a refusal keeps it; nothing is subscribed while the viewport is narrow; inert outside the desktop app.
  • website/src/test/App.navLeaveGuard.test.tsx: the dashboard subscribes when it mounts and lets go on unmount.
  • Each production change, reverted on its own, turns one of these tests red (fourteen reverts, fourteen reds).

Determinism: nativeHistoryStep.test.tsx 20/20 serial, App.navLeaveGuard.test.tsx 5/5, and both files under shuffled orders (seeds 1577, 24601, 31337) green; swipe-history.test.js 20/20. Node 24's test runner has no shuffle option, and those cases share no state: each builds its own fake window or page.

Manual verification

Reproduced and checked on Electron 44.7.2, the version the app pins, with the real dashboard from this branch in the app's window shape (a BaseWindow hosting a WebContentsView) and the app's real preload, on Linux. The page navigates Schedule, then Artifacts, then the test emits the window's swipe event, which is what Electron raises for a macOS swipe:

Swipe main this branch
left stays on Artifacts Schedule
right stays on Artifacts Artifacts
up stays on Artifacts no change

On the same build, mouse buttons 4 and 5 already step back and forward, with or without the preload, so the renderer does not swallow buttons and the lost input is the swipe.

The panel path, on the same Electron with a second WebContentsView registered as a browser panel and holding two pages: with the cursor over it, left goes back a page, right forward, a second right stays put, and the dashboard receives nothing; with the cursor off it, left reaches the dashboard and the panel stays.

Checked on a Mac with an MX Master 4, using the macOS build CI made from this change: the mouse's Back and Forward buttons now step through the dashboard's history. The browser panel path was checked only on Linux, as above.

Screenshots / video

Why no screenshot: the change adds an input path to existing navigation and changes no element, layout or string.

Related Issues

Closes #22992

Related: #8258 (desktop Back/Forward by keyboard and mouse), #5538.

Pattern harvest

Not generalizable: the defect is one macOS input that Electron reports only as a window event and the shell never listened for; there is no code shape a rule could catch.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 22, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 44c7695c5cb165efafc1aa7e9f0af1f887bac20d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The swipe is sent through the dashboard's existing guarded history step, and the shell and dashboard each check that the other side supports it.

Notes

  • The cursor hit test reads win._mcBrowserPanels and manager.getState().bounds directly. If browser-view.js changes how it stores bounds, swipes over the panel will quietly go to the dashboard. A small accessor exported from browser-view.js would keep that coupling in one place.

[DESIGN-REVIEWED] 44c7695

Description read

[DESCRIPTION-READ] 27223299a255bc12471b4fc2b88f35c9b0a7548301c1c52cc83457ebc09f4df8

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 44c7695c5cb165efafc1aa7e9f0af1f887bac20d via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Each item answers the linked defect (#22992) and reuses the existing guarded history step (useGuardedHistoryStep). Grepping "swipe" across website/electron finds no listener on base, so nothing already did this.

What this change ships

Inventory (7 items) — 5 justified

Intent: in the macOS app, a mouse's Back/Forward buttons that arrive as swipes walk the dashboard history, as they do in Chrome. This is a FIX.

  1. On macOS, mouse Back/Forward sent as a swipe now steps the dashboard back or forward, and asks about an unsaved draft first — justified
  2. The trackpad three-finger page swipe now steps history too — rides along (it is the same event and cannot be separated)
  3. A swipe with the cursor over a visible browser panel steps that page's history instead of the dashboard — rides along (declared; it matches where Chromium already sends buttons 4/5)
  4. A swipe does nothing on a narrow viewport or when there is nowhere to go — justified
  5. New preload method onHistoryStep on IPC channel history:step, optional in the bridge type — justified
  6. The packaged app's build.files lists swipe-history.js — justified
  7. The feature-map row for route-history Back/Forward names the new input and its entry points — justified

[FIRST-PRINCIPLES-REVIEWED] 44c7695

Description read

[DESCRIPTION-READ] 50fc1c2806e4ffce40f70881d59ab8ee416774a0d9864561e5385ced67317667

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of 44c7695c5cb165efafc1aa7e9f0af1f887bac20d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The PR adds an input path for mouse Back/Forward on macOS and reuses the existing guarded history step and draft prompt. It adds or changes no control, string or layout, so no screenshot is needed.

[UX-REVIEWED] 44c7695

Description read

[DESCRIPTION-READ] 0e172817be7ef96de5816a20548e2a10860a38cce81236dd8990c1d0c74179c4

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 44c7695c5cb165efafc1aa7e9f0af1f887bac20d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 44c7695

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 22, 2026
@unstablebrainiac
unstablebrainiac force-pushed the fix/desktop-mouse-back-forward branch 2 times, most recently from 0dd06b4 to 4e4e2d9 Compare October 22, 2026 23:27
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 44c7695c5cb165efafc1aa7e9f0af1f887bac20d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 44c7695

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does 4e4e2d9a68ac9dd31221130907971f7d5fe6ca86 newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

the review scope was never resolved: the generate job did not finish (it timed out, failed or was cancelled), so no leg ran; its log names the step that stopped

No [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.

With Logitech's Options software installed, a mouse's Back and Forward
buttons reach a macOS app as swipe events, not as buttons 4 and 5. Chrome
turns the swipe into history Back/Forward. Electron only emits the window's
`swipe` event, and the desktop shell had no listener, so the press did
nothing in the app.

The shell now relays a left/right swipe on each dashboard window to the
dashboard as one route-history step. The dashboard takes it through the
same guarded step as the top-bar arrows and the Cmd/Ctrl+Left/Right
chords: it asks about an unsaved draft first, does nothing with nowhere
to go, and stays inert on a narrow viewport.

Closes kirodotdev#22992
@unstablebrainiac
unstablebrainiac force-pushed the fix/desktop-mouse-back-forward branch from 4e4e2d9 to 44c7695 Compare October 23, 2026 00:14
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 23, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve. Reviewed head 44c7695.

The shell relays only left/right swipes as -1/1 (swipe-history.js#L79-L94). Over a visible browser panel it steps that page's history, with the same can-go guards. The dashboard takes the step through the existing guarded history step, so the unsaved-draft prompt still applies. The new preload method only listens on a channel the main process sends on, so the renderer gains no new capability.

The Security Scope BLOCK comment refers to an earlier head (4e4e2d9) with an identical patch, where the job timed out. The current head's Security Scope check reports nothing to scope. All other lanes passed, and every check on this head is green.

— crew-pr-reviewer (r122)

@iamwhatever
iamwhatever merged commit a37211b into kirodotdev:main Oct 23, 2026
110 of 111 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mouse Back/Forward buttons do nothing in the macOS desktop app

2 participants