Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(windows): route precision-touchpad scroll to pan, mouse wheel to zoom

review2bbb5d7f459b
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index ccfd62d60..ec1de3387 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -57,7 +57,12 @@ import {
} from '../nodes/TerminalNode'
import { solveFitPadding } from './fit-view'
import { FloatingEdge } from './FloatingEdge'
-import { MacWheelGestureRouter, trackpadRoutingEnabled } from './wheel-gesture'
+import {
+ MacWheelGestureRouter,
+ trackpadRoutingEnabled,
+ trackpadRoutingSupported,
+ wheelGestureReporting
+} from './wheel-gesture'
import { isBrowserRuntime } from '@renderer/bridge/runtime'
import { WheelZoomBurstLimiter, clampWheelZoomSpeed, nextWheelZoom } from './wheel-zoom'
import { canCopyFilesToClipboard, selectedLocalFilePaths } from './canvas-file-copy'
@@ -5028,7 +5033,11 @@ export function Canvas() {
const wheelZoomSpeed = clampWheelZoomSpeed(settings.wheelZoomSpeed)
// The escape hatch, resolved ONCE: the router and React Flow's panOnScroll below must agree, or
// a gesture neither of them pans is a gesture that does nothing.
- const trackpadRouting = trackpadRoutingEnabled(isMac, settings.trackpadPan)
+ // macOS and Windows (heuristic there — see trackpadRoutingSupported); never Linux.
+ const trackpadRouting = trackpadRoutingEnabled(
+ trackpadRoutingSupported({ mac: isMac, windows: isWindowsPlatform() }),
+ settings.trackpadPan
+ )
useEffect(() => {
const wrap = flowWrapRef.current
if (!wrap) return
@@ -5036,7 +5045,7 @@ export function Canvas() {
// router routes by device FACT instead of delta-shape guessing — a precise-pixel mouse
// (MX Master) zooms while the trackpad pans, both settings on. The browser (Server Edition)
// has no such stream: reporting stays off and the router keeps its heuristics.
- const gestureReporting = isMac && !isBrowserRuntime()
+ const gestureReporting = wheelGestureReporting({ mac: isMac, browser: isBrowserRuntime() })
const wheelRouting = new MacWheelGestureRouter(gestureReporting)
const offGesture = gestureReporting
? window.nodeTerminal.onCanvasTrackpadGesture?.((active) => wheelRouting.noteGesture(active))
diff --git a/src/renderer/canvas/wheel-gesture.test.ts b/src/renderer/canvas/wheel-gesture.test.ts
index 61fc79b18..3a93a0bec 100644
--- a/src/renderer/canvas/wheel-gesture.test.ts
+++ b/src/renderer/canvas/wheel-gesture.test.ts
@@ -1,5 +1,10 @@
import { describe, expect, it } from 'vitest'
-import { MacWheelGestureRouter, trackpadRoutingEnabled } from './wheel-gesture'
+import {
+ MacWheelGestureRouter,
+ trackpadRoutingEnabled,
+ trackpadRoutingSupported,
+ wheelGestureReporting
+} from './wheel-gesture'
const gesture = (
deltaY: number,
@@ -140,3 +145,45 @@ describe('MacWheelGestureRouter with main-process gesture reporting', () => {
expect(router.shouldPan(gesture(6.25), true, 1000)).toBe(true)
})
})
+
+describe('Windows routing (heuristic, no gesture reporting)', () => {
+ const win = { mac: false, windows: true }
+ const routing = (trackpadPan: boolean): boolean =>
+ trackpadRoutingEnabled(trackpadRoutingSupported(win), trackpadPan)
+
+ it('is on for macOS and Windows viewers only, and the escape hatch still turns it off', () => {
+ expect(routing(true)).toBe(true)
+ expect(routing(false)).toBe(false)
+ expect(trackpadRoutingSupported({ mac: true, windows: false })).toBe(true)
+ expect(trackpadRoutingSupported({ mac: false, windows: false })).toBe(false)
+ })
+
+ it('never turns on main-process gesture reporting off the macOS desktop', () => {
+ expect(wheelGestureReporting({ mac: false, browser: false })).toBe(false)
+ expect(wheelGestureReporting({ mac: true, browser: true })).toBe(false)
+ expect(wheelGestureReporting({ mac: true, browser: false })).toBe(true)
+ })
+
+ it('a notched Windows mouse wheel (deltaY 100, wheelDeltaY ±120) stays on the zoom path', () => {
+ const router = new MacWheelGestureRouter()
+ expect(router.destination(gesture(100, { wheelDeltaY: -120 }), routing(true), no, 1000)).toBe('native')
+ // 125% display scaling: deltaY 125, still a 120 notch.
+ expect(router.destination(gesture(-125, { wheelDeltaY: 120 }), routing(true), no, 1100)).toBe('native')
+ // Two notches coalesced into one packet.
+ expect(router.destination(gesture(200, { wheelDeltaY: -240 }), routing(true), no, 1200)).toBe('native')
+ })
+
+ it('precision-touchpad packets pan, and stay sticky across a quantized 120 packet', () => {
+ const router = new MacWheelGestureRouter()
+ expect(router.destination(gesture(13.5, { wheelDeltaY: -16 }), routing(true), no, 1000)).toBe('flow-pan')
+ expect(router.destination(gesture(8, { deltaX: 3, wheelDeltaY: -9 }), routing(true), no, 1040)).toBe('flow-pan')
+ expect(router.destination(gesture(100, { wheelDeltaY: -120 }), routing(true), no, 1080)).toBe('flow-pan')
+ // Over a terminal/native scroller it scrolls that surface instead.
+ expect(router.destination(gesture(7.5, { wheelDeltaY: -9 }), routing(true), yes, 1100)).toBe('native')
+ })
+
+ it('pinch (ctrl+wheel) never pans on Windows', () => {
+ const router = new MacWheelGestureRouter()
+ expect(router.destination(gesture(3.2, { ctrlKey: true }), routing(true), no, 1000)).toBe('native')
+ })
+})
diff --git a/src/renderer/canvas/wheel-gesture.ts b/src/renderer/canvas/wheel-gesture.ts
index b278fc01e..a960e33b4 100644
--- a/src/renderer/canvas/wheel-gesture.ts
+++ b/src/renderer/canvas/wheel-gesture.ts
@@ -20,6 +20,24 @@ export type MacWheelDestination = 'flow-pan' | 'native'
export const trackpadRoutingEnabled = (mac: boolean, trackpadPan: boolean): boolean =>
mac && trackpadPan
+/**
+ * Which viewers get the router at all (the first argument to `trackpadRoutingEnabled` — still
+ * named `mac` throughout this file for history). macOS and Windows: Chromium on Windows reports a
+ * precision touchpad as small/fractional pixel deltas whose `wheelDeltaY` is not a multiple of
+ * 120, and a notched mouse as `wheelDeltaY` = ±120·n — the same split the heuristics below already
+ * draw. Linux stays off (libinput/X11 deltas were never measured), so its row is hidden.
+ */
+export const trackpadRoutingSupported = (viewer: { mac: boolean; windows: boolean }): boolean =>
+ viewer.mac || viewer.windows
+
+/**
+ * Main-process gesture REPORTING is macOS-desktop only: it rides the gestureScrollBegin/End events
+ * macOS wraps every trackpad scroll in (main/trackpad-gesture.ts). Windows — desktop included —
+ * and every browser tab keep the delta-shape heuristics.
+ */
+export const wheelGestureReporting = (viewer: { mac: boolean; browser: boolean }): boolean =>
+ viewer.mac && !viewer.browser
+
const TRACKPAD_SEQUENCE_MS = 500
const MOUSE_WHEEL_NOTCH = 120
const LARGE_PIXEL_DELTA = 40
diff --git a/src/renderer/components/settings/sections/BehaviorSection.tsx b/src/renderer/components/settings/sections/BehaviorSection.tsx
index 93462c681..2f2075a55 100644
--- a/src/renderer/components/settings/sections/BehaviorSection.tsx
+++ b/src/renderer/components/settings/sections/BehaviorSection.tsx
@@ -7,7 +7,8 @@ import { NumberField } from '@renderer/ui/NumberField'
import { Select } from '@renderer/ui/Select'
import { SegmentedPill } from '@renderer/ui/SegmentedPill'
import { Input } from '@renderer/ui/Input'
-import { hintLabel } from '@shared/platform-utils'
+import { hintLabel, isMacPlatform, isWindowsPlatform } from '@shared/platform-utils'
+import { trackpadRoutingSupported } from '@renderer/canvas/wheel-gesture'
import { clampWheelZoomSpeed } from '@renderer/canvas/wheel-zoom'
import { DEFAULT_WORKTREE_PATH_TEMPLATE } from '@shared/worktree'
@@ -75,7 +76,7 @@ const ROWS = {
},
trackpadPan: {
title: 'Trackpad scroll pans',
- keywords: ['trackpad', 'pan', 'scroll', 'zoom', 'magic', 'mouse', 'two-finger', 'macos']
+ keywords: ['trackpad', 'pan', 'scroll', 'zoom', 'magic', 'mouse', 'two-finger', 'macos', 'windows', 'touchpad']
},
dragMode: {
title: 'Canvas left-drag',
@@ -397,21 +398,23 @@ export function BehaviorSection({ isActive }: { isActive: boolean }): React.JSX.
/>
</SearchableRow>
</div>
- <SearchableRow {...ROWS.trackpadPan}>
- <FieldRow
- label="Trackpad scroll pans"
- description={hintLabel(
- 'macOS: a two-finger trackpad scroll pans the canvas even with wheel zoom on. The desktop app tells mouse and trackpad apart directly, so a wheel mouse still zooms; in the browser (Server Edition) detection is heuristic — turn off there if a precise-pixel mouse (Magic Mouse, MX) pans when you meant to zoom.'
- )}
- control={
- <Switch
- checked={settings.trackpadPan}
- onChange={(v) => update({ trackpadPan: v })}
- ariaLabel="Trackpad scroll pans"
- />
- }
- />
- </SearchableRow>
+ {trackpadRoutingSupported({ mac: isMacPlatform(), windows: isWindowsPlatform() }) && (
+ <SearchableRow {...ROWS.trackpadPan}>
+ <FieldRow
+ label="Trackpad scroll pans"
+ description={hintLabel(
+ 'A two-finger trackpad scroll pans the canvas even with wheel zoom on, while a wheel mouse still zooms. The macOS desktop app tells mouse and trackpad apart directly; on Windows and in the browser (Server Edition) detection is heuristic — turn off if a smooth-scrolling mouse (Magic Mouse, MX) pans when you meant to zoom.'
+ )}
+ control={
+ <Switch
+ checked={settings.trackpadPan}
+ onChange={(v) => update({ trackpadPan: v })}
+ ariaLabel="Trackpad scroll pans"
+ />
+ }
+ />
+ </SearchableRow>
+ )}
<SearchableRow {...ROWS.dragMode}>
<FieldRow
label="Canvas left-drag"