Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): terminal wheel reports carry the pointer cell for hit-testing TUIs (#2353)

serafin-garciaf01eaf83ee25
diff --git a/.changeset/terminal-wheel-pointer-position.md b/.changeset/terminal-wheel-pointer-position.md
new file mode 100644
index 000000000..991f1cbd4
--- /dev/null
+++ b/.changeset/terminal-wheel-pointer-position.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix mouse-wheel scrolling in the desktop terminal for TUIs that hit-test mouse coordinates (opencode, bubbletea apps). The terminal's mouse-mode wheel reports were pinned to cell 1;1 — fine for claude/vim/less, which ignore the position, but coordinate-dispatching TUIs route the wheel to the component under the reported cell, and the top-left corner is never the scrollable region, so scrolling silently did nothing. Wheel reports now carry the pointer's actual cell (with a viewport-center fallback when the renderer hasn't measured yet), and SGR-pixels mode reports CSS-px coordinates. This also corrects scroll targeting in window-under-pointer TUIs: vim/neovim splits and tmux panes previously always scrolled the top-left window regardless of where the pointer was; they now scroll the hovered one, matching native terminals.
diff --git a/packages/app/src/components/TerminalPanel.dom.test.tsx b/packages/app/src/components/TerminalPanel.dom.test.tsx
index 9e007e81e..d6d5334f4 100644
--- a/packages/app/src/components/TerminalPanel.dom.test.tsx
+++ b/packages/app/src/components/TerminalPanel.dom.test.tsx
@@ -26,9 +26,10 @@ class MockTerminal {
get _core() {
return {
coreMouseService: { activeEncoding: this.mouseEncoding },
- _renderService: { dimensions: { css: { cell: { height: 17 } } } },
+ _renderService: { dimensions: { css: { cell: { width: 10, height: 17 } } } },
};
}
+ element: HTMLElement | undefined = undefined;
onDataCb: ((d: string) => void) | null = null;
keyHandler: ((e: KeyboardEvent) => boolean) | null = null;
wheelHandler: ((e: WheelEvent) => boolean) | null = null;
@@ -494,7 +495,7 @@ describe('TerminalPanel', () => {
expect(terminal.input).toHaveBeenCalledTimes(1);
const [ptyId, payload] = terminal.input.mock.calls[0] as [string, string];
expect(ptyId).toBe('pty-1');
- const downTick = '\x1b[<65;1;1M';
+ const downTick = '\x1b[<65;40;12M';
expect(payload.length).toBeGreaterThan(0);
expect(payload.length % downTick.length).toBe(0);
expect(payload.replaceAll(downTick, '')).toBe('');
@@ -503,6 +504,72 @@ describe('TerminalPanel', () => {
term.mouseEncoding = 'SGR_PIXELS';
expect(wheel({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(false);
expect(terminal.input).toHaveBeenCalledTimes(1);
+ const [, pxPayload] = terminal.input.mock.calls[0] as [string, string];
+ const pxTick = '\x1b[<65;400;204M';
+ expect(pxPayload.length).toBeGreaterThan(0);
+ expect(pxPayload.length % pxTick.length).toBe(0);
+ expect(pxPayload.replaceAll(pxTick, '')).toBe('');
+ });
+
+ test('wheel reports carry the pointer cell so hit-testing TUIs scroll the hovered component', async () => {
+ const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
+ render(<TerminalPanel bridge={bridge} />);
+ await waitFor(() => expect(lastTerm?.wheelHandler).toBeTruthy());
+ const term = lastTerm;
+ if (term?.wheelHandler == null) throw new Error('wheel handler not attached');
+ term.modes.mouseTrackingMode = 'any';
+ term.mouseEncoding = 'SGR';
+
+ const screenEl = document.createElement('div');
+ screenEl.className = 'xterm-screen';
+ screenEl.getBoundingClientRect = () => ({ left: 100, top: 50 }) as DOMRect;
+ const host = document.createElement('div');
+ host.appendChild(screenEl);
+ term.element = host;
+
+ expect(
+ term.wheelHandler({
+ deltaY: 120,
+ deltaMode: 0,
+ clientX: 605,
+ clientY: 160,
+ } as unknown as WheelEvent),
+ ).toBe(false);
+ expect(terminal.input).toHaveBeenCalledTimes(1);
+ const [, payload] = terminal.input.mock.calls[0] as [string, string];
+ const tick = '\x1b[<65;51;7M';
+ expect(payload.length).toBeGreaterThan(0);
+ expect(payload.length % tick.length).toBe(0);
+ expect(payload.replaceAll(tick, '')).toBe('');
+ });
+
+ test('pointer mapping falls back to the terminal element rect when .xterm-screen is absent', async () => {
+ const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
+ render(<TerminalPanel bridge={bridge} />);
+ await waitFor(() => expect(lastTerm?.wheelHandler).toBeTruthy());
+ const term = lastTerm;
+ if (term?.wheelHandler == null) throw new Error('wheel handler not attached');
+ term.modes.mouseTrackingMode = 'any';
+ term.mouseEncoding = 'SGR';
+
+ const host = document.createElement('div');
+ host.getBoundingClientRect = () => ({ left: 200, top: 100 }) as DOMRect;
+ term.element = host;
+
+ expect(
+ term.wheelHandler({
+ deltaY: 120,
+ deltaMode: 0,
+ clientX: 705,
+ clientY: 210,
+ } as unknown as WheelEvent),
+ ).toBe(false);
+ expect(terminal.input).toHaveBeenCalledTimes(1);
+ const [, payload] = terminal.input.mock.calls[0] as [string, string];
+ const tick = '\x1b[<65;51;7M';
+ expect(payload.length).toBeGreaterThan(0);
+ expect(payload.length % tick.length).toBe(0);
+ expect(payload.replaceAll(tick, '')).toBe('');
});
test('mode transition resets the wheel accumulator (no stale carry across apps)', async () => {
diff --git a/packages/app/src/components/TerminalPanel.tsx b/packages/app/src/components/TerminalPanel.tsx
index 114887700..5183830cb 100644
--- a/packages/app/src/components/TerminalPanel.tsx
+++ b/packages/app/src/components/TerminalPanel.tsx
@@ -22,7 +22,7 @@ import { TerminalCliMissingBanner } from './TerminalCliMissingBanner';
import { type TerminalExitInfo, TerminalExitNotice } from './TerminalExitNotice';
import { TerminalRefusalNotice } from './TerminalRefusalNotice';
import { xtermThemeForMode } from './terminal-theme';
-import { nextWheelReports, sgrWheelReport } from './terminal-wheel';
+import { nextWheelReports, sgrWheelReport, wheelReportPosition } from './terminal-wheel';
interface TerminalPanelProps {
/** Desktop bridge — the panel is rendered only on the Electron host, where
@@ -201,7 +201,9 @@ function TerminalSession({
term as unknown as {
_core?: {
coreMouseService?: { activeEncoding?: string };
- _renderService?: { dimensions?: { css?: { cell?: { height?: number } } } };
+ _renderService?: {
+ dimensions?: { css?: { cell?: { width?: number; height?: number } } };
+ };
};
}
)._core;
@@ -230,7 +232,23 @@ function TerminalSession({
{ cellHeight, sensitivity: 1.5, maxRowsPerEvent: 20, viewportRows: term.rows },
);
wheelRowAccumulator = accumulator;
- if (count > 0) bridge.terminal.input(ptyId, sgrWheelReport(button).repeat(count));
+ if (count > 0) {
+ const rect = (
+ term.element?.querySelector('.xterm-screen') ?? term.element
+ )?.getBoundingClientRect();
+ const position = wheelReportPosition(
+ rect === undefined ? undefined : event.clientX - rect.left,
+ rect === undefined ? undefined : event.clientY - rect.top,
+ {
+ cellWidth: core?._renderService?.dimensions?.css?.cell?.width,
+ cellHeight,
+ cols: term.cols,
+ rows: term.rows,
+ pixels: encoding === 'SGR_PIXELS',
+ },
+ );
+ bridge.terminal.input(ptyId, sgrWheelReport(button, position).repeat(count));
+ }
return false;
});
diff --git a/packages/app/src/components/terminal-wheel.test.ts b/packages/app/src/components/terminal-wheel.test.ts
index a31ace08c..6a34a3eb7 100644
--- a/packages/app/src/components/terminal-wheel.test.ts
+++ b/packages/app/src/components/terminal-wheel.test.ts
@@ -1,5 +1,10 @@
import { describe, expect, test } from 'bun:test';
-import { nextWheelReports, sgrWheelReport, type WheelReportOptions } from './terminal-wheel';
+import {
+ nextWheelReports,
+ sgrWheelReport,
+ type WheelReportOptions,
+ wheelReportPosition,
+} from './terminal-wheel';
const PIXEL = 0;
const LINE = 1;
@@ -93,8 +98,42 @@ describe('nextWheelReports', () => {
});
describe('sgrWheelReport', () => {
- test('encodes SGR wheel up/down press at position 1;1', () => {
- expect(sgrWheelReport(64)).toBe('\x1b[<64;1;1M');
- expect(sgrWheelReport(65)).toBe('\x1b[<65;1;1M');
+ test('encodes SGR wheel up/down press at the given position', () => {
+ expect(sgrWheelReport(64, { x: 12, y: 7 })).toBe('\x1b[<64;12;7M');
+ expect(sgrWheelReport(65, { x: 1, y: 1 })).toBe('\x1b[<65;1;1M');
+ });
+});
+
+describe('wheelReportPosition', () => {
+ const CELLS = { cellWidth: 10, cellHeight: 20, cols: 80, rows: 24, pixels: false };
+
+ test('maps pointer offset to the 1-based cell under it', () => {
+ expect(wheelReportPosition(0, 0, CELLS)).toEqual({ x: 1, y: 1 });
+ expect(wheelReportPosition(9.9, 19.9, CELLS)).toEqual({ x: 1, y: 1 });
+ expect(wheelReportPosition(10, 20, CELLS)).toEqual({ x: 2, y: 2 });
+ expect(wheelReportPosition(505, 110, CELLS)).toEqual({ x: 51, y: 6 });
+ });
+
+ test('clamps to the viewport bounds (pointer over padding/scrollbar)', () => {
+ expect(wheelReportPosition(-5, -5, CELLS)).toEqual({ x: 1, y: 1 });
+ expect(wheelReportPosition(9999, 9999, CELLS)).toEqual({ x: 80, y: 24 });
+ });
+
+ test('falls back to viewport center when the offset is unmeasurable', () => {
+ expect(wheelReportPosition(undefined, undefined, CELLS)).toEqual({ x: 40, y: 12 });
+ expect(wheelReportPosition(Number.NaN, Number.NaN, CELLS)).toEqual({ x: 40, y: 12 });
+ });
+
+ test('falls back to horizontal center when cell width is unmeasured (cells mode)', () => {
+ const noWidth = { ...CELLS, cellWidth: undefined };
+ expect(wheelReportPosition(505, 110, noWidth)).toEqual({ x: 40, y: 6 });
+ });
+
+ test('SGR_PIXELS mode reports 1-based CSS-px coordinates', () => {
+ const px = { ...CELLS, pixels: true };
+ expect(wheelReportPosition(0, 0, px)).toEqual({ x: 1, y: 1 });
+ expect(wheelReportPosition(505.7, 110.2, px)).toEqual({ x: 506, y: 111 });
+ expect(wheelReportPosition(9999, 9999, px)).toEqual({ x: 800, y: 480 });
+ expect(wheelReportPosition(undefined, undefined, px)).toEqual({ x: 400, y: 240 });
});
});
diff --git a/packages/app/src/components/terminal-wheel.ts b/packages/app/src/components/terminal-wheel.ts
index 5b0e2e136..93d9fe166 100644
--- a/packages/app/src/components/terminal-wheel.ts
+++ b/packages/app/src/components/terminal-wheel.ts
@@ -41,8 +41,57 @@ export function nextWheelReports(
};
}
-/** SGR-encoded wheel report at position 1;1 (always inside the window; mouse-
- * mode apps scroll their active region regardless of the pointer cell). */
-export function sgrWheelReport(button: WheelButton): string {
- return `\x1b[<${button};1;1M`;
+/** 1-based coordinates carried by an SGR wheel report — cells for SGR (1006),
+ * CSS px for SGR_PIXELS (1016). */
+export interface WheelReportPosition {
+ readonly x: number;
+ readonly y: number;
+}
+
+/** Cell-width stand-in when the renderer hasn't measured yet; used to compute
+ * the pixel-encoding viewport extent (clamp bound and center fallback). */
+const FALLBACK_CELL_WIDTH = 9;
+
+export function wheelReportPosition(
+ offsetX: number | undefined,
+ offsetY: number | undefined,
+ opts: {
+ readonly cellWidth: number | undefined;
+ readonly cellHeight: number;
+ readonly cols: number;
+ readonly rows: number;
+ readonly pixels: boolean;
+ },
+): WheelReportPosition {
+ const cellWidth = opts.cellWidth !== undefined && opts.cellWidth > 0 ? opts.cellWidth : undefined;
+ const clamp = (v: number, max: number) => Math.min(Math.max(v, 1), max);
+ if (opts.pixels) {
+ const maxX = Math.round((cellWidth ?? FALLBACK_CELL_WIDTH) * opts.cols);
+ const maxY = Math.round(opts.cellHeight * opts.rows);
+ return {
+ x: isFiniteNumber(offsetX) ? clamp(Math.floor(offsetX) + 1, maxX) : Math.ceil(maxX / 2),
+ y: isFiniteNumber(offsetY) ? clamp(Math.floor(offsetY) + 1, maxY) : Math.ceil(maxY / 2),
+ };
+ }
+ return {
+ x:
+ isFiniteNumber(offsetX) && cellWidth !== undefined
+ ? clamp(Math.floor(offsetX / cellWidth) + 1, opts.cols)
+ : Math.ceil(opts.cols / 2),
+ y: isFiniteNumber(offsetY)
+ ? clamp(Math.floor(offsetY / opts.cellHeight) + 1, opts.rows)
+ : Math.ceil(opts.rows / 2),
+ };
+}
+
+function isFiniteNumber(v: number | undefined): v is number {
+ return v !== undefined && Number.isFinite(v);
+}
+
+/** SGR-encoded wheel report at the given 1-based position. The position must
+ * track the pointer (or fall back to viewport center): hit-testing TUIs
+ * scroll the component under the reported cell, and a constant corner
+ * position lands outside every scrollable region. */
+export function sgrWheelReport(button: WheelButton, position: WheelReportPosition): string {
+ return `\x1b[<${button};${position.x};${position.y}M`;
}