@gajae-code/tui 0.11.1 → 0.11.2

package/dist/types/stdin-buffer.d.ts

@@ -17,6 +17,8 @@
  * MIT License - Copyright (c) 2025 opentui
  */
 import { EventEmitter } from "events";
+/** True for complete SGR mouse CSI reports. These remain control input, never text. */
+export declare function isSgrMouseSequence(sequence: string): boolean;
 export type StdinBufferOptions = {
     /**
      * Maximum time to wait for sequence completion (default: 10ms)

package/dist/types/terminal.d.ts

@@ -21,6 +21,7 @@ export type TerminalAppearance = "dark" | "light";
 export interface Terminal {
     start(onInput: (data: string) => void, onResize: () => void): void;
     stop(): void;
+    setMouseEnabled?(enabled: boolean): void;
     /**
      * Drain stdin before exiting to prevent Kitty key release events from
      * leaking to the parent shell over slow SSH connections.
@@ -69,6 +70,7 @@ export declare class ProcessTerminal implements Terminal {
     get kittyProtocolActive(): boolean;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    setMouseEnabled(enabled: boolean): void;
     start(onInput: (data: string) => void, onResize: () => void): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;

package/dist/types/tui.d.ts

@@ -8,6 +8,27 @@ type InputListener = (data: string) => InputListenerResult;
 /**
  * Component interface - all components must implement this
  */
+export type MouseEvent = {
+    kind: "wheel" | "click";
+    direction?: -1 | 1;
+    button?: 0;
+    /** Terminal cell coordinates, one-based. */
+    x: number;
+    y: number;
+    /** Focused-overlay cell coordinates, one-based when dispatched to an overlay. */
+    localX?: number;
+    localY?: number;
+};
+type OverlayMouseBounds = {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+    termWidth: number;
+    termHeight: number;
+};
+/** Parse xterm SGR mouse reports. Drag and button-release reports are ignored. */
+export declare function parseSgrMouseEvent(data: string): MouseEvent | undefined;
 export interface Component {
     /**
      * Render the component to lines for the given viewport width
@@ -19,6 +40,8 @@ export interface Component {
      * Optional handler for keyboard input when component has focus
      */
     handleInput?(data: string): void;
+    /** Optional handler for terminal mouse events when component has focus. */
+    handleMouse?(event: MouseEvent): void;
     /**
      * If true, component receives key release events (Kitty protocol).
      * Default is false - release events are filtered out.
@@ -192,6 +215,7 @@ type TuiRenderCounterSnapshot = {
  */
 export declare class TUI extends Container {
     #private;
+    private readonly options;
     terminal: Terminal;
     /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
     onDebug?: () => void;
@@ -202,8 +226,11 @@ export declare class TUI extends Container {
         options?: OverlayOptions;
         preFocus: Component | null;
         hidden: boolean;
+        mouseBounds?: OverlayMouseBounds;
     }[];
-    constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: {
+        enableMouse?: boolean;
+    });
     dispose(): void;
     get fullRedraws(): number;
     getShowHardwareCursor(): boolean;
@@ -223,6 +250,8 @@ export declare class TUI extends Container {
     resetViewportAnchorIntent(): void;
     /** Allow one semantic-neighbor reconciliation after a definitive same-transcript rebuild. */
     prepareViewportAnchorForTranscriptRebuild(): void;
+    /** Reveal a semantic viewport anchor without changing the rendered content width. */
+    revealViewportAnchor(id: ViewportAnchorId, alignment: "top" | "center" | "bottom"): boolean;
     scrollViewportPages(direction: -1 | 1): boolean;
     followLiveViewport(): boolean;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.11.1",
+	"version": "0.11.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -30,19 +30,21 @@
 		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test test/*.test.ts",
-		"test:perf": "PI_TUI_PERF_GATES=1 bun test test/perf-gates.test.ts",
+		"test:perf": "bun test test/perf-gates.test.ts test/transcript-selection-perf.test.ts",
+		"test:pty": "PI_TUI_PTY_TESTS=1 bun test test/pty/*.test.ts",
 		"fix": "biome check --write --unsafe .",
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.11.1",
-		"@gajae-code/utils": "0.11.1",
+		"@gajae-code/natives": "0.11.2",
+		"@gajae-code/utils": "0.11.2",
 		"lru-cache": "11.3.6",
-		"marked": "^18.0.3"
+		"marked": "18.0.6"
 	},
 	"devDependencies": {
 		"chalk": "^5.6.2",
-		"@xterm/headless": "^6.0.0"
+		"@xterm/headless": "^6.0.0",
+		"node-pty": "^1.0.0"
 	},
 	"engines": {
 		"bun": ">=1.3.14"

package/src/components/settings-list.ts

@@ -120,7 +120,11 @@ export class SettingsList implements Component {
 		const endIndex = Math.min(startIndex + this.#maxVisible, this.#items.length);
 
 		// Calculate max label width for alignment
-		const maxLabelWidth = Math.min(30, Math.max(...this.#items.map(item => visibleWidth(item.label))));
+		const maxLabelWidth = Math.min(
+			30,
+			Math.max(0, width - 12),
+			Math.max(...this.#items.map(item => visibleWidth(item.label))),
+		);
 
 		// Render visible items
 		for (let i = startIndex; i < endIndex; i++) {
@@ -132,13 +136,15 @@ export class SettingsList implements Component {
 			const prefixWidth = visibleWidth(prefix);
 
 			// Pad label to align values
-			const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+			const labelPadded =
+				truncateToWidth(item.label, maxLabelWidth, Ellipsis.Omit) +
+				padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
 			const labelText = this.#theme.label(labelPadded, isSelected);
 
 			// Calculate space for value
 			const separator = "  ";
 			const usedWidth = prefixWidth + maxLabelWidth + visibleWidth(separator);
-			const valueMaxWidth = width - usedWidth - 2;
+			const valueMaxWidth = Math.max(0, width - usedWidth - 2);
 
 			const valueText = this.#theme.value(
 				truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),

package/src/stdin-buffer.ts

@@ -23,6 +23,18 @@ import { EventEmitter } from "events";
 const ESC = "\x1b";
 const BRACKETED_PASTE_START = "\x1b[200~";
 const BRACKETED_PASTE_END = "\x1b[201~";
+const SGR_QUARANTINE_MAX_BYTES = 256;
+const SGR_QUARANTINE_TIMEOUT_MS = 100;
+
+/** True for complete SGR mouse CSI reports. These remain control input, never text. */
+export function isSgrMouseSequence(sequence: string): boolean {
+	return /^\x1b\[<\d+;\d+;\d+[Mm]$/.test(sequence);
+}
+
+/** True when a buffered sequence begins an SGR mouse report, valid or not. */
+function isSgrMousePrefix(sequence: string): boolean {
+	return sequence.startsWith(`${ESC}[<`);
+}
 
 function isUtf8LeadByte(byte: number): boolean {
 	return byte >= 0xc2 && byte <= 0xf4;
@@ -137,19 +149,9 @@ function isCompleteCsiSequence(data: string): "complete" | "incomplete" {
 		// Format: ESC[<B;X;Ym or ESC[<B;X;YM
 		if (payload.startsWith("<")) {
 			// Must have format: <digits;digits;digits[Mm]
-			const mouseMatch = /^<\d+;\d+;\d+[Mm]$/.test(payload);
-			if (mouseMatch) {
-				return "complete";
-			}
-			// If it ends with M or m but doesn't match the pattern, still incomplete
-			if (lastChar === "M" || lastChar === "m") {
-				// Check if we have the right structure
-				const parts = payload.slice(1, -1).split(";");
-				if (parts.length === 3 && parts.every(p => /^\d+$/.test(p))) {
-					return "complete";
-				}
-			}
-
+			// SGR-looking reports remain terminal control input even when malformed.
+			// Treat their final byte as complete so trailing user input is preserved.
+			if (lastChar === "M" || lastChar === "m") return "complete";
 			return "incomplete";
 		}
 
@@ -303,6 +305,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	#decoder = new StringDecoder("utf8");
 	#decoderHasPendingUtf8 = false;
 	#pendingSingleUtf8LeadByte: number | undefined;
+	#sgrQuarantine = false;
+	#sgrQuarantineBytes = 0;
+	#sgrQuarantineSemicolons = 0;
+	#sgrQuarantineHasDigit = false;
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
@@ -310,8 +316,8 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	}
 
 	process(data: string | Buffer): void {
-		// Clear any pending timeout
-		if (this.#timeout) {
+		// Do not cancel a bounded SGR quarantine while waiting for its final byte.
+		if (this.#timeout && !this.#sgrQuarantine) {
 			clearTimeout(this.#timeout);
 			this.#timeout = undefined;
 		}
@@ -380,6 +386,11 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			return;
 		}
 
+		if (this.#sgrQuarantine) {
+			str = this.#consumeSgrQuarantine(str);
+			if (str.length === 0) return;
+		}
+
 		this.#buffer += str;
 
 		if (this.#pasteMode) {
@@ -445,13 +456,17 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		this.#buffer = result.remainder;
 
 		for (const sequence of result.sequences) {
+			if (isSgrMousePrefix(sequence) && !isSgrMouseSequence(sequence)) continue;
 			this.#emitDataSequence(sequence);
 		}
 
 		if (this.#buffer.length > 0) {
 			this.#timeout = setTimeout(() => {
+				if (isSgrMousePrefix(this.#buffer)) {
+					this.#beginSgrQuarantine();
+					return;
+				}
 				const flushed = this.flush();
-
 				for (const sequence of flushed) {
 					this.#emitDataSequence(sequence);
 				}
@@ -459,6 +474,76 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		}
 	}
 
+	#beginSgrQuarantine(): void {
+		const suffix = this.#buffer.slice(3);
+		let semicolons = 0;
+		let hasDigit = false;
+		for (let index = 0; index < suffix.length; index += 1) {
+			const char = suffix[index]!;
+			if (/\d/u.test(char)) {
+				hasDigit = true;
+				continue;
+			}
+			if (char === ";" && hasDigit && semicolons < 2) {
+				semicolons += 1;
+				hasDigit = false;
+				continue;
+			}
+			const remainder = suffix.slice(index);
+			this.#buffer = "";
+			this.#pendingKittyPrintableCodepoint = undefined;
+			if (remainder) this.process(remainder);
+			return;
+		}
+		this.#buffer = "";
+		this.#pendingKittyPrintableCodepoint = undefined;
+		this.#sgrQuarantine = true;
+		this.#sgrQuarantineBytes = suffix.length;
+		this.#sgrQuarantineSemicolons = semicolons;
+		this.#sgrQuarantineHasDigit = hasDigit;
+		this.#timeout = setTimeout(() => this.#endSgrQuarantine(), SGR_QUARANTINE_TIMEOUT_MS);
+	}
+
+	#endSgrQuarantine(): void {
+		if (this.#timeout) clearTimeout(this.#timeout);
+		this.#timeout = undefined;
+		this.#sgrQuarantine = false;
+		this.#sgrQuarantineBytes = 0;
+		this.#sgrQuarantineSemicolons = 0;
+		this.#sgrQuarantineHasDigit = false;
+	}
+
+	#consumeSgrQuarantine(data: string): string {
+		for (let index = 0; index < data.length; index += 1) {
+			const char = data[index]!;
+			if (this.#sgrQuarantineBytes >= SGR_QUARANTINE_MAX_BYTES) {
+				let resume = index;
+				while (resume < data.length && /[\d;]/u.test(data[resume]!)) resume += 1;
+				if (resume < data.length && /[Mm]/u.test(data[resume]!)) resume += 1;
+				this.#endSgrQuarantine();
+				return data.slice(resume);
+			}
+			if (/\d/u.test(char)) {
+				this.#sgrQuarantineHasDigit = true;
+				this.#sgrQuarantineBytes += 1;
+				continue;
+			}
+			if (char === ";" && this.#sgrQuarantineHasDigit && this.#sgrQuarantineSemicolons < 2) {
+				this.#sgrQuarantineSemicolons += 1;
+				this.#sgrQuarantineHasDigit = false;
+				this.#sgrQuarantineBytes += 1;
+				continue;
+			}
+			if ((char === "M" || char === "m") && this.#sgrQuarantineSemicolons === 2 && this.#sgrQuarantineHasDigit) {
+				this.#endSgrQuarantine();
+				return data.slice(index + 1);
+			}
+			this.#endSgrQuarantine();
+			return data.slice(index);
+		}
+		return "";
+	}
+
 	#consumePendingSingleUtf8LeadAsMeta(): string | undefined {
 		const byte = this.#pendingSingleUtf8LeadByte;
 		if (byte === undefined) return undefined;
@@ -482,6 +567,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			clearTimeout(this.#timeout);
 			this.#timeout = undefined;
 		}
+		if (this.#sgrQuarantine) this.#endSgrQuarantine();
 
 		const pendingMeta = this.#consumePendingSingleUtf8LeadAsMeta();
 
@@ -489,6 +575,12 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			return pendingMeta === undefined ? [] : [pendingMeta];
 		}
 
+		if (isSgrMousePrefix(this.#buffer)) {
+			this.#buffer = "";
+			this.#pendingKittyPrintableCodepoint = undefined;
+			return pendingMeta === undefined ? [] : [pendingMeta];
+		}
+
 		const sequences = pendingMeta === undefined ? [this.#buffer] : [pendingMeta, this.#buffer];
 		this.#buffer = "";
 		this.#pendingKittyPrintableCodepoint = undefined;
@@ -504,6 +596,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		this.#pasteMode = false;
 		this.#pasteBuffer = "";
 		this.#pendingKittyPrintableCodepoint = undefined;
+		this.#sgrQuarantine = false;
+		this.#sgrQuarantineBytes = 0;
+		this.#sgrQuarantineSemicolons = 0;
+		this.#sgrQuarantineHasDigit = false;
 		// Drop any incomplete multi-byte sequence the decoder is holding so a
 		// stale partial prefix cannot combine with future input. destroy()
 		// resets the decoder by calling clear().

package/src/terminal.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import { $env, $flag } from "@gajae-code/utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
+import { isUnderTerminalMultiplexer } from "./terminal-capabilities";
 
 const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
@@ -73,6 +74,9 @@ export interface Terminal {
 
 	// Stop the terminal and restore state
 	stop(): void;
+	// Enable or disable opt-in SGR mouse reporting. Implementations that do not
+	// own a real terminal may ignore this.
+	setMouseEnabled?(enabled: boolean): void;
 
 	/**
 	 * Drain stdin before exiting to prevent Kitty key release events from
@@ -220,6 +224,8 @@ export class ProcessTerminal implements Terminal {
 	#osc11PollTimer?: Timer;
 	#mode2031DebounceTimer?: Timer;
 	#progressTimer?: ReturnType<typeof setInterval>;
+	#mouseEnabled = false;
+	#started = false;
 
 	get isProcessTerminal(): boolean {
 		return true;
@@ -237,9 +243,15 @@ export class ProcessTerminal implements Terminal {
 		this.#appearanceCallbacks.push(callback);
 	}
 
+	setMouseEnabled(enabled: boolean): void {
+		this.#mouseEnabled = enabled && !isUnderTerminalMultiplexer(Bun.env);
+		if (this.#started) this.#safeWrite(this.#mouseEnabled ? "\x1b[?1000h\x1b[?1006h" : "\x1b[?1000l\x1b[?1006l");
+	}
+
 	start(onInput: (data: string) => void, onResize: () => void): void {
 		this.#inputHandler = onInput;
 		this.#resizeHandler = onResize;
+		this.#started = true;
 
 		// Register for emergency cleanup
 		activeTerminal = this;
@@ -259,6 +271,8 @@ export class ProcessTerminal implements Terminal {
 
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
+		// SGR mouse reporting is opt-in and never enabled inside tmux or screen.
+		if (this.#mouseEnabled) this.#safeWrite("\x1b[?1000h\x1b[?1006h");
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.#resizeHandler);
@@ -690,6 +704,8 @@ export class ProcessTerminal implements Terminal {
 		}
 
 		// Disable bracketed paste mode
+		this.#started = false;
+		this.#mouseEnabled = false;
 		this.#safeWrite("\x1b[?2004l");
 		this.#safeWrite("\x1b[?1000l");
 		this.#safeWrite("\x1b[?1006l");

package/src/tui.ts

@@ -45,6 +45,44 @@ type InputListener = (data: string) => InputListenerResult;
 /**
  * Component interface - all components must implement this
  */
+export type MouseEvent = {
+	kind: "wheel" | "click";
+	direction?: -1 | 1;
+	button?: 0;
+	/** Terminal cell coordinates, one-based. */
+	x: number;
+	y: number;
+	/** Focused-overlay cell coordinates, one-based when dispatched to an overlay. */
+	localX?: number;
+	localY?: number;
+};
+
+type OverlayMouseBounds = {
+	row: number;
+	col: number;
+	width: number;
+	height: number;
+	termWidth: number;
+	termHeight: number;
+};
+
+/** Parse xterm SGR mouse reports. Drag and button-release reports are ignored. */
+export function parseSgrMouseEvent(data: string): MouseEvent | undefined {
+	const match = data.match(/^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/);
+	if (!match) return undefined;
+	const button = Number(match[1]);
+	const x = Number(match[2]);
+	const y = Number(match[3]);
+	const terminator = match[4];
+	if (![button, x, y].every(Number.isSafeInteger) || x < 1 || y < 1) return undefined;
+
+	if (button & 32 || terminator === "m") return undefined;
+	if (button === 64) return { kind: "wheel", direction: -1, x, y };
+	if (button === 65) return { kind: "wheel", direction: 1, x, y };
+	if (button === 0) return { kind: "click", button, x, y };
+	return undefined;
+}
+
 export interface Component {
 	/**
 	 * Render the component to lines for the given viewport width
@@ -58,6 +96,9 @@ export interface Component {
 	 */
 	handleInput?(data: string): void;
 
+	/** Optional handler for terminal mouse events when component has focus. */
+	handleMouse?(event: MouseEvent): void;
+
 	/**
 	 * If true, component receives key release events (Kitty protocol).
 	 * Default is false - release events are filtered out.
@@ -673,9 +714,14 @@ export class TUI extends Container {
 		options?: OverlayOptions;
 		preFocus: Component | null;
 		hidden: boolean;
+		mouseBounds?: OverlayMouseBounds;
 	}[] = [];
 
-	constructor(terminal: Terminal, showHardwareCursor?: boolean) {
+	constructor(
+		terminal: Terminal,
+		showHardwareCursor?: boolean,
+		private readonly options: { enableMouse?: boolean } = {},
+	) {
 		super();
 		this.terminal = terminal;
 		if (showHardwareCursor !== undefined) {
@@ -770,6 +816,50 @@ export class TUI extends Container {
 		if (this.#manualViewportAnchor !== null) this.#reconcileMissingViewportAnchor = true;
 	}
 
+	/** Reveal a semantic viewport anchor without changing the rendered content width. */
+	revealViewportAnchor(id: ViewportAnchorId, alignment: "top" | "center" | "bottom"): boolean {
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		const frame = this.#viewportAnchorFrame;
+		if (height <= 0 || width <= 0 || this.#previousLines.length === 0 || frame === null) return false;
+
+		const selectedRow = frame.anchors.findIndex(anchor => anchor?.id === id);
+		const selected = selectedRow < 0 ? null : frame.anchors[selectedRow];
+		if (selected === null) return false;
+
+		const desiredScreenRow = alignment === "top" ? 0 : alignment === "center" ? Math.floor(height / 2) : height - 1;
+		const targetViewportTop = Math.max(0, frame.startRow + selectedRow - desiredScreenRow);
+		this.#manualViewportAnchor = {
+			id: selected.id,
+			graphemeIndex: selected.graphemeStart,
+			cellOffset: selected.cellStart,
+			desiredScreenRow,
+		};
+		const firstCandidateRow = Math.max(0, targetViewportTop - frame.startRow);
+		const lastCandidateRow = Math.min(frame.anchors.length, targetViewportTop + height - frame.startRow);
+		const fallbacks: ManualViewportAnchor[] = [];
+		for (let row = firstCandidateRow; row < lastCandidateRow; row++) {
+			const anchor = frame.anchors[row];
+			if (anchor === null || row === selectedRow) continue;
+			fallbacks.push({
+				id: anchor.id,
+				graphemeIndex: anchor.graphemeStart,
+				cellOffset: anchor.cellStart,
+				desiredScreenRow: row + frame.startRow - targetViewportTop,
+			});
+		}
+		fallbacks.sort(
+			(a, b) =>
+				Math.abs(a.desiredScreenRow - this.#manualViewportAnchor!.desiredScreenRow) -
+				Math.abs(b.desiredScreenRow - this.#manualViewportAnchor!.desiredScreenRow),
+		);
+		this.#manualViewportFallbackAnchors = fallbacks;
+		this.#manualViewportTop = this.#viewportTopRow;
+		this.#reconcileMissingViewportAnchor = false;
+		this.requestRender();
+		return true;
+	}
+
 	scrollViewportPages(direction: -1 | 1): boolean {
 		const height = this.terminal.rows;
 		const width = this.terminal.columns;
@@ -878,7 +968,8 @@ export class TUI extends Container {
 	 * Returns a handle to control the overlay's visibility.
 	 */
 	showOverlay(component: Component, options?: OverlayOptions): OverlayHandle {
-		const entry = { component, options, preFocus: this.#focusedComponent, hidden: false };
+		const entry = { component, options, preFocus: this.#focusedComponent, hidden: false, mouseBounds: undefined };
+
 		this.overlayStack.push(entry);
 		// Only focus if overlay is actually visible
 		if (this.#isOverlayVisible(entry)) {
@@ -892,6 +983,8 @@ export class TUI extends Container {
 			hide: () => {
 				const index = this.overlayStack.indexOf(entry);
 				if (index !== -1) {
+					entry.mouseBounds = undefined;
+
 					this.overlayStack.splice(index, 1);
 					// Restore focus if this overlay had focus
 					if (this.#focusedComponent === component) {
@@ -905,6 +998,8 @@ export class TUI extends Container {
 			setHidden: (hidden: boolean) => {
 				if (entry.hidden === hidden) return;
 				entry.hidden = hidden;
+				entry.mouseBounds = undefined;
+
 				// Update focus when hiding/showing
 				if (hidden) {
 					// If this overlay had focus, move focus to next visible or preFocus
@@ -928,6 +1023,7 @@ export class TUI extends Container {
 	hideOverlay(): void {
 		const overlay = this.overlayStack.pop();
 		if (!overlay) return;
+		overlay.mouseBounds = undefined;
 		// Find topmost visible overlay, or fall back to preFocus
 		const topVisible = this.#getTopmostVisibleOverlay();
 		this.setFocus(topVisible?.component ?? overlay.preFocus);
@@ -962,11 +1058,13 @@ export class TUI extends Container {
 	override invalidate(): void {
 		super.invalidate();
 		for (const overlay of this.overlayStack) overlay.component.invalidate?.();
+		for (const overlay of this.overlayStack) overlay.mouseBounds = undefined;
 	}
 
 	start(): void {
 		this.#stopped = false;
 		this.#terminalUnavailable = false;
+		this.terminal.setMouseEnabled?.(this.options.enableMouse === true);
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => {
@@ -1371,6 +1469,44 @@ export class TUI extends Container {
 			data = current;
 		}
 
+		const mouse = parseSgrMouseEvent(data);
+		if (mouse) {
+			// Coordinates outside the current terminal cannot name a visible cell.
+			if (mouse.x > this.terminal.columns || mouse.y > this.terminal.rows) return;
+			if (mouse.kind === "wheel") this.scrollViewportPages(mouse.direction!);
+			else {
+				const focusedOverlay = this.overlayStack.find(o => o.component === this.#focusedComponent);
+				if (focusedOverlay) {
+					if (!this.#isOverlayVisible(focusedOverlay)) {
+						focusedOverlay.mouseBounds = undefined;
+						return;
+					}
+					const bounds = focusedOverlay.mouseBounds;
+					if (bounds?.termWidth !== this.terminal.columns || bounds.termHeight !== this.terminal.rows) {
+						return;
+					}
+
+					if (
+						!bounds ||
+						mouse.x < bounds.col + 1 ||
+						mouse.x > bounds.col + bounds.width ||
+						mouse.y < bounds.row + 1 ||
+						mouse.y > bounds.row + bounds.height
+					)
+						return;
+					this.#focusedComponent?.handleMouse?.({
+						...mouse,
+						localX: mouse.x - bounds.col,
+						localY: mouse.y - bounds.row,
+					});
+				} else this.#focusedComponent?.handleMouse?.(mouse);
+			}
+			this.requestRender(false, "mouse");
+			return;
+		}
+		// SGR-looking reports, including malformed reports, are terminal controls.
+		if (data.startsWith("\x1b[<")) return;
+
 		// Consume terminal cell size responses without blocking unrelated input.
 		if (this.#consumeCellSizeResponse(data)) {
 			return;
@@ -1570,6 +1706,7 @@ export class TUI extends Container {
 	#compositeOverlays(lines: string[], termWidth: number, termHeight: number): string[] {
 		if (this.overlayStack.length === 0) return lines;
 		const result = [...lines];
+		for (const entry of this.overlayStack) entry.mouseBounds = undefined;
 
 		// Pre-render all visible overlays and calculate positions
 		const rendered: { overlayLines: string[]; row: number; col: number; w: number }[] = [];
@@ -1597,6 +1734,7 @@ export class TUI extends Container {
 			const { row, col } = this.#resolveOverlayLayout(options, overlayLines.length, termWidth, termHeight);
 
 			rendered.push({ overlayLines, row, col, w: width });
+			entry.mouseBounds = { row, col, width, height: overlayLines.length, termWidth, termHeight };
 			minLinesNeeded = Math.max(minLinesNeeded, row + overlayLines.length);
 		}