Skip to content

feat(website): add a Reverse trackpad swipe setting for browsers that hide Natural scrolling - #39164

Open
JalaluddinYazdani wants to merge 1 commit into
kirodotdev:mainfrom
JalaluddinYazdani:fix/38623-reverse-trackpad-swipe
Open

JalaluddinYazdani wants to merge 1 commit into
kirodotdev:mainfrom
JalaluddinYazdani:fix/38623-reverse-trackpad-swipe

Conversation

@JalaluddinYazdani

@JalaluddinYazdani JalaluddinYazdani commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let people who turn macOS Natural scrolling off get a side-panel swipe that follows their fingers in Chrome and Firefox tabs too.

#38711 fixed the swipe direction with Natural scrolling off in Safari (which reports webkitDirectionInvertedFromDevice) and in the desktop app (which reads com.apple.swipescrolldirection). Chrome and Firefox tabs expose the macOS setting nowhere, so there the right-docked side panel (chat and Mates pages) still moves opposite to the fingers for those users. Option 1 of the decision on #38623 (comment): add a "Reverse trackpad swipe" setting, off by default.

Why it matters

Anyone with Natural scrolling off who uses the dashboard in Chrome or Firefox gets a backwards swipe: swiping left to open the panel closes it, and the reverse. There is no way to fix it today.

Not a goal

  • Detecting Natural scrolling in Chrome or Firefox. Those browsers do not expose it.
  • Changing the swipe in Safari or the desktop app. Detection already works there, and it still wins over the switch.
  • Backing the switch up to the host (DURABLE_PREF_KEYS). It describes one browser on one Mac.
  • Turning the swipe off. That is feat(website): add a setting to turn off the side panel swipe #38716.

What changed (motivation → approach → change)

  • Symptom: in Chrome or Firefox with Natural scrolling off, fingerSign gets no WebKit flag and no shell report, so it assumes Natural scrolling is on and reads the fingers backwards.
  • Approach: give fingerSign a third source for the unknown case only, a browser-local switch. The order is: the wheel's own WebKit flag, then the desktop shell, then the switch. With the switch off, nothing changes for anyone.
  • Change:
    • website/src/lib/scrollTouch.ts: REVERSE_TRACKPAD_SWIPE_KEY (kc-reverse-trackpad-swipe) and naturalScrolling(). It returns the shell's report, else false when the switch is on, else null.
    • website/src/hooks/useTrackpadSwipe.ts: the page's wheels, the relayed frame wheels, and the natural field sent when a frame is armed all use naturalScrolling() instead of shellNaturalScrolling().
    • website/src/pages/settings/DisplayPanel.tsx: a "Reverse trackpad swipe" toggle under Settings → Display → View, through usePersistedBool, off by default. It is hidden where the desktop shell reports Natural scrolling, because it would do nothing there.
    • The label and description in all 12 catalogs, plus en-XA. The settings registry is regenerated (npm run gen:settings).

Backwards compatibility

Compatible: the switch defaults to off, and off gives exactly today's fingerSign inputs.

Removes nothing: the change only adds a key, a setting row and a fallback, and every existing source keeps its precedence.

Tests

  • website/src/hooks/useTrackpadSwipe.test.ts, "the Reverse trackpad swipe switch":
    • with the switch on, an unflagged wheel (Chrome or Firefox) is read as Natural scrolling off, with finger travel [20, 40, 60];
    • the WebKit flag and the shell report still win over the switch;
    • a relayed frame wheel with inv: null goes through the switch;
    • with the switch off, behaviour is unchanged.
  • website/src/test/reverseTrackpadSwipe.test.tsx: the row starts off in a browser tab, writes '1'/'0', and flips naturalScrolling() both ways. The row is hidden, and the shell wins, when electronAPI.getNaturalScrolling reports a value.

Proof: not provable -- frontend test (prove.py runs Python only)

These runs passed locally on this branch:

  • npx vitest run on the trackpad, settings, i18n and command-palette suites: 198 files and 3354 tests, plus the 5 trackpad-swipe files with 110 tests;
  • npm run typecheck, eslint on the changed files, npm run lint:i18n and npm run i18n:check;
  • the pytest settings-registry and brand gates: 200 passed.

Manual verification

Still required on a Mac with Natural scrolling off, in Chrome:

  1. Swipe left over the chat. The panel moves backwards.
  2. Turn on Settings → Display → View → Reverse trackpad swipe.
  3. Swipe left again. The panel opens with the fingers.

In Safari the switch changes nothing.

Real-machine verification

Not run yet. It needs a Mac with Natural scrolling off and a trackpad, in Chrome. I will add the before and after results in a comment.

Screenshots / video

The real SettingsToggle with the props DisplayPanel passes, between its View-section neighbours, captured with scripted Playwright against the Vite dev server and the real stylesheet.

Off (the default), light and dark:

Reverse trackpad swipe off, light
Reverse trackpad swipe off, dark

On, light and dark:

Reverse trackpad swipe on, light
Reverse trackpad swipe on, dark

The hint behind the info tip:

Reverse trackpad swipe hint, dark

Related Issues

Fixes #38623. Follows #38711. Overlaps #38716 only in the generated settings registry and the locale catalogs. Both are regenerated, so whichever PR lands second rebases and re-runs npm run gen:settings and npm run i18n:pseudo.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title

@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 18, 2026
@JalaluddinYazdani

Copy link
Copy Markdown
Contributor Author

@buluoray @bolichen97 could you review this? It implements option 1 from #38623 (a Reverse trackpad swipe switch, off by default, used only where the browser cannot detect Natural scrolling). GitHub would not let me request reviewers from a fork, hence the mention. Screenshots of the new Settings row will follow.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 129681b6684fe6d5ce4b1c2ef7e0edce847fac58 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. The new switch is off by default, and a maintainer chose this approach on #38623 (Option 1). It replaces all 3 places that read shellNaturalScrolling in useTrackpadSwipe.ts, so no copy of the bug is left behind.

What this change ships

Inventory (8 items) — 8 justified

Intent: let people with macOS Natural scrolling off get a side-panel swipe that follows their fingers in Chrome and Firefox. This is an ADDITION.

  1. A new "Reverse trackpad swipe" toggle under Settings → Display → View, off by default — justified
  2. With the toggle on, the side-panel swipe in Chrome and Firefox follows the fingers — justified
  3. Swipes passed up from embedded frames, and the natural value sent to those frames, also follow the toggle — justified
  4. The toggle is hidden where the desktop shell already reports Natural scrolling — justified
  5. A new browser-local storage key, kc-reverse-trackpad-swipe — justified
  6. The toggle can be found in the command palette and the settings search — justified
  7. The label and hint are translated in all 12 catalogs plus en-XA — justified
  8. Before-and-after screenshots under temp-screenshots/, the evidence folder the PR template names — justified

[FIRST-PRINCIPLES-REVIEWED] 129681b

Description read

[DESCRIPTION-READ] 80fba128bb15f25e03c3807c8bf36be885649caf1a448354550c35d364bc219e

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 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 129681b6684fe6d5ce4b1c2ef7e0edce847fac58 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 switch only fills the case where neither the wheel nor the desktop shell reports Natural scrolling, it is off by default, the PR removes nothing, and committed screenshots cover the new row.

[DESIGN-REVIEWED] 129681b

Description read

[DESCRIPTION-READ] 204a5f3bcc12ca6a624a4ecb58f3e97e2abd2af6db8efc0a3be7058afd18aa62

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 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

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

UX-Verdict: PASS

Five committed screenshots show every new state (off and on, light and dark, plus the tooltip). Nothing blocks. No first-time reader has seen them: this is a fork lane, so pushing the branch to this repository would run the blind read.

Notes

  • The row also shows in Safari and on Windows and Linux, where it does nothing. The tooltip admits this: "Safari and the desktop app detect it on their own, so there this switch changes nothing." Hiding the row in Safari, where the wheel flag is known, or on any platform that isn't macOS would make that sentence unnecessary.
  • The tooltip text is too long: "Turn this on if a two-finger swipe moves the side panel the opposite way to your fingers." is the only part that tells someone whether they need the switch. Cut the rest to one short line, e.g. "For Chrome or Firefox on a Mac with Natural scrolling off."

[UX-REVIEWED] 129681b

Description read

[DESCRIPTION-READ] 0b9bb5a020f867b342ddfd01a6508ffeb79dd92973ab2a48542fa1e34ead1cc6

That sha256 names everything this verdict read: the PR description, plus the 8 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 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • The hint says the switch "changes nothing" in the desktop app. That is only true on macOS. On Windows and Linux the shell never sends scroll-direction, so the row is shown and the switch does reverse the swipe. Scoping the sentence to macOS would make it accurate.

[OPUS-REVIEWED] 129681b

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings (all downgraded on adjudication)

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

Opus 5.5 adjudication downgraded every blocking finding. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

Review details

BLOCKING -- website/src/hooks/useTrackpadSwipe.ts:697 -- Refresh the direction in already-armed frames

frame.contentWindow?.postMessage({ type: FRAME_WHEEL_ARMED, on, natural: naturalScrolling() }, '*')
Trigger: In Chrome with Natural scrolling off, keep a relaying artifact open in the chat side panel, then enable Reverse trackpad swipe in another same-origin tab. The frame retains natural: null, while the host reads the updated preference for each relayed wheel.
Outcome: The frame cancels leftward swipes the host rejects, but leaves rightward panel-closing swipes uncancelled, suppressing the wrong browser gestures until the frame is rearmed.
Anchor: defect
Fix: Refresh armed frames’ natural value when the preference changes, including cross-tab storage updates.

[BLOCK-MERGE-DOWNGRADED] 129681b
[GPT-REVIEWED] 129681b

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

LOW: needs Chrome or Firefox with Natural scrolling off, and the switch flipped once while a relaying frame is already armed. Hosts arm frames only at effect start (useTrackpadSwipe.ts:700) and on the frame's hello (:707-711), and the frame keeps natural until it is re-armed (widgetSrcdoc.ts:449-453). It is visible and corrects itself once the frame reloads or the host remounts (:700/:710).
The real fix is a separate subscription for this one path (a storage listener plus a same-tab change signal that re-arms every frame), and every reader of the arm protocol carries it from then on. For a misread that happens once, while the user is setting the switch up, and that fixes itself, that cost is larger than the harm.

[ADJUDICATION] 129681b6684fe6d5ce4b1c2ef7e0edce847fac58 total=1 uphold=0 downgrade=1
DOWNGRADE F1 website/src/hooks/useTrackpadSwipe.ts:697 reason=disproportionate-remedy
[GPT-ADJUDICATED] 129681b6684fe6d5ce4b1c2ef7e0edce847fac58

@bolichen97

Copy link
Copy Markdown
Contributor

@JalaluddinYazdani I approved the held CI runs on 68bdb15. Two checks are red:

  • Frontend Ratchets & i18n: the find_ui index is stale, because this PR changes its inputs. Run npm run gen:ui in website/ and commit the result.
  • PR Policy (Screenshot Evidence): the new Settings switch is a visible UI change, so the body needs a screenshot or a short recording of it. Saving the body re-runs the check.

On the design: #38623 asked a maintainer to pick between the options, and so far nobody has picked one on the issue. Since this PR adds a new user setting, I've flagged it for a maintainer call. I'll do the code review once the checks above are green.

AI-assisted, sent by Bolin Review bot

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 18, 2026
@JalaluddinYazdani
JalaluddinYazdani force-pushed the fix/38623-reverse-trackpad-swipe branch from 68bdb15 to 129681b Compare November 18, 2026 18:49
@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer design sign-off from @bolichen97: option 1 from #38623 is the direction we want. A "Reverse trackpad swipe" setting, off by default, fixes the swipe for people with Natural scrolling off in Chrome and Firefox. Safari and the desktop app keep detecting it on their own, and detection still wins over the switch.

I'll do the code review and approve once the checks on the current head are green.

AI-assisted, sent by Bolin Review bot

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

@JalaluddinYazdani thanks for the gen:ui fix. Two things on 129681b:

  • Bundle Size Gate: first-load-0 is 1003.1 KB, over its 1003.0 KB budget by 130 bytes. The new Settings switch lands in the first-load chunk. Either move it behind the Settings page's lazy boundary, or bump the first-load-0 entry in CHUNK_BUDGETS (scripts/check-bundle-size.mjs) with a comment and a line in the PR body.
  • Opus 5.5 Review came back "review incomplete" (no verdict, not a finding). I re-ran Fast Gate so it runs again.

Design sign-off is already on the PR; I'll approve once these are green.

AI-assisted, sent by Bolin Review bot

@bolichen97

Copy link
Copy Markdown
Contributor

Bundle Size Gate: first-load-0 is a few bytes over the old 1003.0 KB ceiling. Main raised that ceiling to 1053 KB in #39203 a few hours ago, so a rebase onto current main should clear it with no other change.

AI-assisted, sent by Bolin Review bot

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 18, 2026
… hide Natural scrolling

Chrome and Firefox tabs do not expose macOS Natural scrolling, so with it
off the side-panel swipe still ran backwards there after kirodotdev#38711. A new
browser-local switch in Settings > Display (off by default) supplies the
missing answer: lib/scrollTouch naturalScrolling() reads the desktop
shell's report first, then the switch (on = Natural scrolling off). The
wheel's own webkitDirectionInvertedFromDevice still wins, so Safari and
the desktop app are unchanged; the row is hidden where the shell reports
the setting. The frame wheel relay gets the same value when armed.

Fixes kirodotdev#38623
@JalaluddinYazdani
JalaluddinYazdani force-pushed the fix/38623-reverse-trackpad-swipe branch from 129681b to 3ec42d1 Compare November 18, 2026 21:31
@bolichen97

Copy link
Copy Markdown
Contributor

@JalaluddinYazdani the one red on 3ec42d1 is Backend Tests (3.12, 8): test_bare_session_handle_guard.py::test_no_test_builds_a_bare_session_handle_directly. That one isn't from this PR. Main broke it in #38978 and fixed it in #39262, but this PR's test merge was built on the older main. Please rebase onto current main and push. Your design sign-off stands, and I'll approve as soon as the new head is green.

AI-assisted, sent by Bolin Review bot

This branch has not been deployed

No deployments
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) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Trackpad swipe moves the side panel the wrong way when macOS natural scrolling is off

2 participants