@gajae-code/tui 0.11.1 → 0.11.3

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.11.3] - 2026-07-19
+### Fixed
+
+- Suppressed slash-command and skill autocomplete inside line-local single-backtick code spans while preserving path completion and ordinary slash matching outside literals (#2619).
+
 ## [0.11.0] - 2026-07-15
 ### Fixed
 

package/dist/types/autocomplete.d.ts

@@ -1,4 +1,5 @@
 export declare function getSlashCommandMatchRank(query: string, commandName: string): number;
+export declare function isInsideInlineCodeSpan(text: string): boolean;
 export declare function extractSlashCommandTokenPrefix(text: string): string | null;
 export interface AutocompleteItem {
     value: string;

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.3",
 	"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.3",
+		"@gajae-code/utils": "0.11.3",
 		"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/autocomplete.ts

@@ -190,10 +190,38 @@ function normalizeSlashCommandText(value: string): string {
 		.replace(/\s+/g, " ");
 }
 const NON_COMMAND_SLASH_PREFIX_PRECEDERS = new Set(["/", "\\", ":", ".", "~"]);
+function findOpenInlineCodeSpanStart(text: string): number | null {
+	let openDelimiter: number | null = null;
+
+	for (let i = 0; i < text.length; ) {
+		if (text[i] !== "`") {
+			i += 1;
+			continue;
+		}
+
+		let runEnd = i + 1;
+		while (text[runEnd] === "`") runEnd += 1;
+		if (runEnd - i !== 1) {
+			i = runEnd;
+			continue;
+		}
+
+		let backslashCount = 0;
+		for (let j = i - 1; j >= 0 && text[j] === "\\"; j -= 1) backslashCount += 1;
+		if (backslashCount % 2 === 0) openDelimiter = openDelimiter === null ? i : null;
+		i = runEnd;
+	}
+
+	return openDelimiter;
+}
+export function isInsideInlineCodeSpan(text: string): boolean {
+	return findOpenInlineCodeSpanStart(text) !== null;
+}
 
 export function extractSlashCommandTokenPrefix(text: string): string | null {
 	const slashIndex = text.lastIndexOf("/");
 	if (slashIndex === -1) return null;
+	if (isInsideInlineCodeSpan(text.slice(0, slashIndex + 1))) return null;
 
 	const token = text.slice(slashIndex);
 	if (/[\s]/.test(token)) return null;
@@ -556,7 +584,9 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		}
 
 		const lastDelimiterIndex = findLastDelimiter(text);
-		const pathPrefix = lastDelimiterIndex === -1 ? text : text.slice(lastDelimiterIndex + 1);
+		const inlineCodeStart = findOpenInlineCodeSpanStart(text);
+		const prefixStart = Math.max(lastDelimiterIndex, inlineCodeStart ?? -1);
+		const pathPrefix = prefixStart === -1 ? text : text.slice(prefixStart + 1);
 
 		// For forced extraction (Tab key), always return something
 		if (forceExtract) {

package/src/components/editor.ts

@@ -3,6 +3,7 @@ import {
 	type AutocompleteProvider,
 	type CombinedAutocompleteProvider,
 	extractSlashCommandTokenPrefix,
+	isInsideInlineCodeSpan,
 } from "../autocomplete";
 import { BracketedPasteHandler } from "../bracketed-paste";
 import { getKeybindings, type KeybindingsManager } from "../keybindings";
@@ -459,6 +460,7 @@ export class Editor implements Component, Focusable {
 	#autocompleteState: "regular" | "force" | null = null;
 	#autocompletePrefix: string = "";
 	#autocompleteRequestId: number = 0;
+	#autocompleteOrigin?: { docVersion: number; cursorLine: number; cursorCol: number };
 	#autocompleteMaxVisible: number = 5;
 	onAutocompleteUpdate?: () => void;
 
@@ -1201,6 +1203,11 @@ export class Editor implements Component, Focusable {
 
 				// If Tab was pressed, always apply the selection
 				if (kb.matches(data, "tui.input.tab")) {
+					if (!this.#isAutocompleteSelectionCurrent()) {
+						this.#cancelAutocomplete();
+						this.#handleTabCompletion();
+						return;
+					}
 					const selected = this.#autocompleteList.getSelectedItem();
 					if (selected && this.#autocompleteProvider) {
 						const shouldChainSlashCommandAutocomplete = this.#isSlashCommandNameAutocompleteSelection();
@@ -1234,36 +1241,38 @@ export class Editor implements Component, Focusable {
 				}
 
 				// If Enter was pressed on a slash command, apply completion and submit
-				if ((kb.matches(data, "tui.input.submit") || data === "\n") && this.#autocompletePrefix.startsWith("/")) {
-					// Check for stale autocomplete state due to debounce
-					const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
-					const currentTextBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					if (!currentTextBeforeCursor.endsWith(this.#autocompletePrefix)) {
-						// Autocomplete is stale - cancel and fall through to normal submission
+				if (
+					(kb.matches(data, "tui.input.submit") || data === "\n") &&
+					this.#autocompleteState === "regular" &&
+					this.#autocompletePrefix.startsWith("/")
+				) {
+					const selected = this.#autocompleteList.getSelectedItem();
+					if (!this.#isAutocompleteSelectionCurrent()) {
 						this.#cancelAutocomplete();
-					} else {
-						const selected = this.#autocompleteList.getSelectedItem();
-						if (selected && this.#autocompleteProvider) {
-							const result = this.#autocompleteProvider.applyCompletion(
-								this.#state.lines,
-								this.#state.cursorLine,
-								this.#state.cursorCol,
-								selected,
-								this.#autocompletePrefix,
-							);
+					} else if (selected && this.#autocompleteProvider) {
+						const result = this.#autocompleteProvider.applyCompletion(
+							this.#state.lines,
+							this.#state.cursorLine,
+							this.#state.cursorCol,
+							selected,
+							this.#autocompletePrefix,
+						);
 
-							this.#state.lines = result.lines;
-							this.#bumpDocumentVersion();
-							this.#state.cursorLine = result.cursorLine;
-							this.#setCursorCol(result.cursorCol);
-							result.onApplied?.();
-						}
+						this.#state.lines = result.lines;
+						this.#bumpDocumentVersion();
+						this.#state.cursorLine = result.cursorLine;
+						this.#setCursorCol(result.cursorCol);
+						result.onApplied?.();
 						this.#cancelAutocomplete();
 					}
 					// Don't return - fall through to submission logic
 				}
 				// If Enter was pressed on a file path, apply completion
 				else if (kb.matches(data, "tui.input.submit") || data === "\n") {
+					if (!this.#isAutocompleteSelectionCurrent()) {
+						this.#cancelAutocomplete();
+						return;
+					}
 					const selected = this.#autocompleteList.getSelectedItem();
 					if (selected && this.#autocompleteProvider) {
 						const result = this.#autocompleteProvider.applyCompletion(
@@ -1863,9 +1872,17 @@ export class Editor implements Component, Focusable {
 
 		// Check if we should trigger or update autocomplete
 		if (!this.#autocompleteState) {
-			// Auto-trigger for slash command tokens.
-			if (char === "/" && (this.#isAtStartOfSubmittedMessage() || this.#isInSlashTokenContext())) {
-				this.#tryTriggerAutocomplete();
+			// Auto-trigger slash commands, or path-only completion inside inline code.
+			if (char === "/") {
+				const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+				const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
+				if (this.#isInSubmittedSlashCommandContext()) {
+					this.#tryTriggerAutocomplete();
+				} else if (isInsideInlineCodeSpan(textBeforeCursor)) {
+					this.#forceFileAutocomplete();
+				} else if (this.#isInSlashTokenContext()) {
+					this.#tryTriggerAutocomplete();
+				}
 			}
 			// Auto-trigger for "@" file reference (fuzzy search)
 			else if (char === "@") {
@@ -2771,14 +2788,6 @@ export class Editor implements Component, Focusable {
 		return true;
 	}
 
-	// Slash commands execute only when the submitted prompt starts with the command.
-	#isAtStartOfSubmittedMessage(): boolean {
-		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
-		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
-
-		return this.#hasOnlyWhitespaceBeforeCursorLine() && (beforeCursor.trim() === "" || beforeCursor.trim() === "/");
-	}
-
 	#isInSubmittedSlashCommandContext(): boolean {
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
@@ -2794,6 +2803,30 @@ export class Editor implements Component, Focusable {
 	#isInSlashTokenContext(): boolean {
 		return this.#getSlashTokenBeforeCursor() !== null;
 	}
+	#isAutocompleteSelectionCurrent(): boolean {
+		if (!this.#isAutocompleteOriginCurrent()) return false;
+		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+		const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
+		if (!textBeforeCursor.endsWith(this.#autocompletePrefix)) return false;
+		if (this.#autocompleteState !== "regular" || !this.#autocompletePrefix.startsWith("/")) return true;
+		return extractSlashCommandTokenPrefix(textBeforeCursor) === this.#autocompletePrefix;
+	}
+	#captureAutocompleteOrigin(): { docVersion: number; cursorLine: number; cursorCol: number } {
+		return {
+			docVersion: this.#docVersion,
+			cursorLine: this.#state.cursorLine,
+			cursorCol: this.#state.cursorCol,
+		};
+	}
+
+	#isAutocompleteOriginCurrent(origin = this.#autocompleteOrigin): boolean {
+		return (
+			origin !== undefined &&
+			origin.docVersion === this.#docVersion &&
+			origin.cursorLine === this.#state.cursorLine &&
+			origin.cursorCol === this.#state.cursorCol
+		);
+	}
 
 	#isSlashCommandNameAutocompleteSelection(): boolean {
 		if (this.#autocompleteState !== "regular") {
@@ -2835,6 +2868,7 @@ export class Editor implements Component, Focusable {
 			}
 		}
 
+		const origin = this.#captureAutocompleteOrigin();
 		const requestId = ++this.#autocompleteRequestId;
 
 		const suggestions = await this.#autocompleteProvider.getSuggestions(
@@ -2842,12 +2876,13 @@ export class Editor implements Component, Focusable {
 			this.#state.cursorLine,
 			this.#state.cursorCol,
 		);
-		if (requestId !== this.#autocompleteRequestId) return;
+		if (requestId !== this.#autocompleteRequestId || !this.#isAutocompleteOriginCurrent(origin)) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "regular";
+			this.#autocompleteOrigin = origin;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();
@@ -2907,13 +2942,14 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			return;
 		}
 
+		const origin = this.#captureAutocompleteOrigin();
 		const requestId = ++this.#autocompleteRequestId;
 		const suggestions = await provider.getForceFileSuggestions(
 			this.#state.lines,
 			this.#state.cursorLine,
 			this.#state.cursorCol,
 		);
-		if (requestId !== this.#autocompleteRequestId) return;
+		if (requestId !== this.#autocompleteRequestId || !this.#isAutocompleteOriginCurrent(origin)) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
 			// If there's exactly one suggestion and this was an explicit Tab press, apply it immediately
@@ -2941,6 +2977,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "force";
+			this.#autocompleteOrigin = origin;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();
@@ -2955,6 +2992,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 		this.#autocompleteRequestId += 1;
 		this.#autocompleteState = null;
 		this.#autocompleteList = undefined;
+		this.#autocompleteOrigin = undefined;
 		this.#autocompletePrefix = "";
 		if (notifyCancel && wasAutocompleting) {
 			this.onAutocompleteCancel?.();
@@ -2974,6 +3012,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			return;
 		}
 
+		const origin = this.#captureAutocompleteOrigin();
 		const requestId = ++this.#autocompleteRequestId;
 
 		const suggestions = await this.#autocompleteProvider.getSuggestions(
@@ -2981,12 +3020,13 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			this.#state.cursorLine,
 			this.#state.cursorCol,
 		);
-		if (requestId !== this.#autocompleteRequestId) return;
+		if (requestId !== this.#autocompleteRequestId || !this.#isAutocompleteOriginCurrent(origin)) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
 			this.#autocompletePrefix = suggestions.prefix;
 			// Always create new SelectList to ensure update
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
+			this.#autocompleteOrigin = origin;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();

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);
 		}