Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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`;}