Local Echo
diff --git a/src/web/public/settings-ui.js b/src/web/public/settings-ui.js
index e0562c3a..8341d23b 100644
--- a/src/web/public/settings-ui.js
+++ b/src/web/public/settings-ui.js
@@ -337,6 +337,8 @@ Object.assign(CodemanApp.prototype, {
document.getElementById('appSettingsTunnelEnabled').checked = settings.tunnelEnabled ?? false;
this.loadTunnelStatus();
document.getElementById('appSettingsLocalEcho').checked = settings.localEchoEnabled ?? MobileDetection.isTouchDevice();
+ document.getElementById('appSettingsTerminalWheelLocal').checked =
+ settings.terminalWheelLocalScrollback ?? defaults.terminalWheelLocalScrollback ?? false;
document.getElementById('appSettingsCjkInput').checked = settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false;
document.getElementById('appSettingsExtendedKeyboardBar').checked = settings.extendedKeyboardBar ?? false;
document.getElementById('appSettingsTabTwoRows').checked = settings.tabTwoRows ?? defaults.tabTwoRows ?? false;
@@ -1436,6 +1438,7 @@ Object.assign(CodemanApp.prototype, {
imageWatcherEnabled: document.getElementById('appSettingsImageWatcherEnabled').checked,
tunnelEnabled: document.getElementById('appSettingsTunnelEnabled').checked,
localEchoEnabled: document.getElementById('appSettingsLocalEcho').checked,
+ terminalWheelLocalScrollback: document.getElementById('appSettingsTerminalWheelLocal').checked,
cjkInputEnabled: document.getElementById('appSettingsCjkInput').checked,
webglRendererEnabled: document.getElementById('appSettingsWebglRenderer').checked,
extendedKeyboardBar: document.getElementById('appSettingsExtendedKeyboardBar').checked,
@@ -1609,6 +1612,7 @@ Object.assign(CodemanApp.prototype, {
showPlanUsageLimits: _pul,
showAttachmentsButton: _ahb,
webglRendererEnabled: _wgl,
+ terminalWheelLocalScrollback: _twls,
...serverSettings
} = settings;
try {
@@ -1775,6 +1779,7 @@ Object.assign(CodemanApp.prototype, {
ralphTrackerEnabled: false,
tabTwoRows: false,
cjkInputEnabled: false,
+ terminalWheelLocalScrollback: false, // mobile scrolls via touch, not wheel
webglRendererEnabled: false, // mobile always uses the DOM renderer
skin: 'daylight-blue',
};
@@ -2149,6 +2154,7 @@ Object.assign(CodemanApp.prototype, {
'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
'skin', 'showPlanUsageLimits', 'showAttachmentsButton', 'webglRendererEnabled',
+ 'terminalWheelLocalScrollback',
]);
// The plan-usage chip is a PER-DEVICE display setting (default OFF): desktop
// can show it while mobile stays hidden. It used to sync, so an older
diff --git a/src/web/public/terminal-ui.js b/src/web/public/terminal-ui.js
index 53b54bfa..05d2fead 100644
--- a/src/web/public/terminal-ui.js
+++ b/src/web/public/terminal-ui.js
@@ -385,7 +385,7 @@ Object.assign(CodemanApp.prototype, {
'wheel',
(ev) => {
ev.preventDefault();
- const lines = Math.round(ev.deltaY / 25) || (ev.deltaY > 0 ? 1 : -1);
+ const lines = this._wheelScrollLines(ev);
if (this._shouldForwardWheelToApp(ev)) {
this._sendSyntheticSgrWheel(ev.clientX, ev.clientY, lines);
return;
@@ -2520,8 +2520,25 @@ Object.assign(CodemanApp.prototype, {
// unknown version is treated as older). Gemini is a strip mode too but its
// wheel behavior is unverified, so it keeps the local wheel — taps/clicks
// are still forwarded for it (harmless no-ops at worst).
+ // Wheel delta → whole scroll lines. macOS trackpads turn Shift+two-finger
+ // scroll into a HORIZONTAL wheel (deltaY≈0, deltaX carries the magnitude), and
+ // Shift routes the wheel to local scrollback (_shouldForwardWheelToApp returns
+ // false on Shift). So under Shift, read whichever axis dominates — otherwise
+ // deltaY≈0 collapses to a fixed ±1 line/tick and the gesture can't page through
+ // history on a trackpad (issue #154). Non-Shift and mouse-wheel paths are
+ // unchanged (they carry deltaY). The `|| ±1` keeps sub-25px deltas moving.
+ _wheelScrollLines(ev) {
+ const delta = ev.shiftKey && Math.abs(ev.deltaX) > Math.abs(ev.deltaY) ? ev.deltaX : ev.deltaY;
+ return Math.round(delta / 25) || (delta > 0 ? 1 : -1);
+ },
+
_shouldForwardWheelToApp(ev) {
if (ev.shiftKey) return false;
+ // Opt-out (App Settings → Input → "Wheel scrolls local history"): pin the
+ // plain wheel to xterm's own scrollback like pre-#144, for users who prefer
+ // it over forwarding the wheel to the CLI's transcript (issue #154). Cheap —
+ // loadAppSettingsFromStorage() is cache-backed.
+ if (this.loadAppSettingsFromStorage?.()?.terminalWheelLocalScrollback) return false;
const mode = this.terminal?.modes?.mouseTrackingMode;
if (mode && mode !== 'none') return false;
const session = this.sessions?.get(this.activeSessionId);
@@ -2535,12 +2552,13 @@ Object.assign(CodemanApp.prototype, {
},
// Encode wheel ticks as SGR reports (button 64 = up, 65 = down) at the pointer
- // cell. Reports are coalesced into one PTY write per ~40ms: a trackpad emits
- // dozens of wheel events per second and each _sendInputAsync becomes a tmux
- // send-keys on the server — unbatched, a single flick would spawn a process
- // storm. Per-event tick count is capped (Claude applies its own scroll-speed
- // multiplier and acceleration on top), and the queue is bounded so a wild
- // scroll can't build a backlog that keeps scrolling after the finger stops.
+ // cell. Reports are coalesced into one fire-and-forget write per ~40ms: a
+ // trackpad emits dozens of wheel events per second and each send becomes a
+ // tmux send-keys on the server — unbatched, a single flick would spawn a
+ // process storm. Per-event tick count is capped (Claude applies its own
+ // scroll-speed multiplier and acceleration on top), and the queue is bounded
+ // so a wild scroll can't build a backlog that keeps scrolling after the finger
+ // stops. Flushed via _sendInputEphemeral — loss-tolerant, off the durable queue.
_sendSyntheticSgrWheel(clientX, clientY, lines) {
if (!this.activeSessionId || !lines) return;
const pos = this._clientPointToCell(clientX, clientY);
@@ -2558,7 +2576,10 @@ Object.assign(CodemanApp.prototype, {
this._wheelSgrFlushTimer = null;
const data = this._wheelSgrQueue;
this._wheelSgrQueue = '';
- if (data && this.activeSessionId) this._sendInputAsync(this.activeSessionId, data);
+ // Ephemeral (fire-and-forget): wheel reports are loss-tolerant, so they skip
+ // the durable seq/ACK queue — no localStorage churn, no "Nb queued" flicker
+ // in the connection indicator on every scroll tick.
+ if (data && this.activeSessionId) this._sendInputEphemeral(this.activeSessionId, data);
},
// Desktop counterpart of the touchend tap branch: hand-encode an SGR report
diff --git a/test/terminal-touch-tap.test.ts b/test/terminal-touch-tap.test.ts
index 49862e74..7c4ad557 100644
--- a/test/terminal-touch-tap.test.ts
+++ b/test/terminal-touch-tap.test.ts
@@ -370,12 +370,54 @@ describe('terminal touch tap mouse guard', () => {
expect(app._shouldForwardWheelToApp({ shiftKey: false })).toBe(false);
});
+ it('wheel: the local-scrollback opt-out pins the plain wheel to local scrollback (issue #154)', () => {
+ const { app } = loadTerminalUiHarness();
+ app.activeSessionId = 'sess-1';
+ app.sessions = new Map([['sess-1', { mode: 'claude', cliVersion: '2.1.187' }]]);
+ app.terminal = {
+ modes: { mouseTrackingMode: 'none' },
+ buffer: { active: { viewportY: 50, baseY: 50 } },
+ };
+
+ // Default (setting absent) forwards the plain wheel to the CLI transcript.
+ expect(app._shouldForwardWheelToApp({ shiftKey: false })).toBe(true);
+
+ // Opt-out ON → the plain wheel stays on xterm's own scrollback (pre-#144).
+ app.loadAppSettingsFromStorage = () => ({ terminalWheelLocalScrollback: true });
+ expect(app._shouldForwardWheelToApp({ shiftKey: false })).toBe(false);
+
+ // OFF again → forwarding resumes.
+ app.loadAppSettingsFromStorage = () => ({ terminalWheelLocalScrollback: false });
+ expect(app._shouldForwardWheelToApp({ shiftKey: false })).toBe(true);
+ });
+
+ it('wheel: reads the dominant axis under Shift so a macOS trackpad can page scrollback (issue #154)', () => {
+ const { app } = loadTerminalUiHarness();
+
+ // Plain vertical wheel: unchanged, driven by deltaY.
+ expect(app._wheelScrollLines({ shiftKey: false, deltaX: 0, deltaY: 100 })).toBe(4);
+ expect(app._wheelScrollLines({ shiftKey: false, deltaX: 0, deltaY: -50 })).toBe(-2);
+
+ // Shift on a macOS trackpad: deltaY≈0, deltaX carries direction+magnitude.
+ // Old code collapsed this to a fixed -1; now it tracks the horizontal delta.
+ expect(app._wheelScrollLines({ shiftKey: true, deltaX: -100, deltaY: 0 })).toBe(-4); // scroll up
+ expect(app._wheelScrollLines({ shiftKey: true, deltaX: 75, deltaY: 0 })).toBe(3); // scroll down
+
+ // Shift with a real vertical wheel (mouse): deltaY dominates, deltaX ignored.
+ expect(app._wheelScrollLines({ shiftKey: true, deltaX: 2, deltaY: 100 })).toBe(4);
+
+ // Sub-25px delta still nudges one line in the gesture's direction.
+ expect(app._wheelScrollLines({ shiftKey: true, deltaX: -5, deltaY: 0 })).toBe(-1);
+ });
+
it('wheel: encodes SGR 64/65 ticks, caps per event, and coalesces into one flush', () => {
const { app } = loadTerminalUiHarness();
const sent: Array<{ id: string; data: string }> = [];
app.activeSessionId = 'sess-1';
app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
- app._sendInputAsync = (id: string, data: string) => sent.push({ id, data });
+ // Wheel reports flush via the ephemeral (fire-and-forget) path, not the
+ // durable queue — so they never show in the pending-bytes indicator (#154).
+ app._sendInputEphemeral = (id: string, data: string) => sent.push({ id, data });
app.terminal = {
cols: 80,
rows: 24,