@f5-sales-demo/pi-tui 21.16.0 → 21.17.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@
 
 ### Fixed
 
+- Added shared SGR mouse routing and fullscreen alternate-screen ownership for interactive overlays,
+  including horizontal-wheel filtering, Herdr-safe redraw behavior, and idempotent mouse/screen
+  restoration. Semantically ported from [can1357/oh-my-pi#3402](https://github.com/can1357/oh-my-pi/pull/3402),
+  [#7810](https://github.com/can1357/oh-my-pi/pull/7810),
+  [#8433](https://github.com/can1357/oh-my-pi/pull/8433), and
+  [#11045](https://github.com/can1357/oh-my-pi/pull/11045)
+  ([#3748](https://github.com/f5-sales-demo/xcsh/issues/3748)).
+- Delivered structured completion, request, and error notifications to validated Herdr panes while
+  preserving existing terminal fallbacks and explicit Kitty graphics negotiation. Semantically
+  ported from [can1357/oh-my-pi#11054](https://github.com/can1357/oh-my-pi/pull/11054)
+  ([#3748](https://github.com/f5-sales-demo/xcsh/issues/3748)).
 - Bounded oversized ANSI-heavy render rows before width measurement while preserving visible text,
   complete OSC 66 payloads, and reset semantics. Semantically ported from
   [can1357/oh-my-pi#2047](https://github.com/can1357/oh-my-pi/pull/2047)

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-tui",
-	"version": "21.16.0",
+	"version": "21.17.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@f5-sales-demo/pi-natives": "21.16.0",
-		"@f5-sales-demo/pi-utils": "21.16.0",
+		"@f5-sales-demo/pi-natives": "21.17.0",
+		"@f5-sales-demo/pi-utils": "21.17.0",
 		"marked": "^18.0"
 	},
 	"devDependencies": {

package/src/components/select-list.ts

@@ -1,4 +1,5 @@
 import { getKeybindings } from "../keybindings";
+import { type MouseRoutable, routeSelectListMouse, type SgrMouseEvent } from "../mouse";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
@@ -31,6 +32,7 @@ export interface SelectListTheme {
 	scrollInfo: (text: string) => string;
 	noMatch: (text: string) => string;
 	symbols: SymbolTheme;
+	hovered?: (text: string) => string;
 }
 
 export interface SelectListTruncatePrimaryContext {
@@ -47,9 +49,11 @@ export interface SelectListLayoutOptions {
 	truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
 }
 
-export class SelectList implements Component {
+export class SelectList implements Component, MouseRoutable {
 	#filteredItems: ReadonlyArray<SelectItem>;
 	#selectedIndex: number = 0;
+	#hoveredIndex: number | null = null;
+	#hitRows: (number | undefined)[] = [];
 
 	onSelect?: (item: SelectItem) => void;
 	onCancel?: () => void;
@@ -74,12 +78,43 @@ export class SelectList implements Component {
 		this.#selectedIndex = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
 	}
 
+	hitTest(line: number): number | undefined {
+		return this.#hitRows[line];
+	}
+
+	setHoverIndex(index: number | null): void {
+		this.#hoveredIndex = index;
+	}
+
+	handleWheel(delta: -1 | 1): void {
+		if (this.#filteredItems.length === 0) return;
+		const next = clamp(this.#selectedIndex + delta, 0, this.#filteredItems.length - 1);
+		if (next === this.#selectedIndex) return;
+		this.#selectedIndex = next;
+		this.#notifySelectionChange();
+	}
+
+	clickItem(index: number): void {
+		const item = this.#filteredItems[index];
+		if (!item) return;
+		if (index !== this.#selectedIndex) {
+			this.#selectedIndex = index;
+			this.#notifySelectionChange();
+		}
+		this.onSelect?.(item);
+	}
+
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		routeSelectListMouse(this, event, line);
+	}
+
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
 
 	render(width: number): string[] {
 		const lines: string[] = [];
+		this.#hitRows = [];
 
 		// If no items match filter, show message
 		if (this.#filteredItems.length === 0) {
@@ -103,7 +138,11 @@ export class SelectList implements Component {
 
 			const isSelected = i === this.#selectedIndex;
 			const descriptionText = item.description ? sanitizeSingleLine(item.description) : undefined;
-			lines.push(this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth));
+			const rendered = this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth);
+			this.#hitRows[lines.length] = i;
+			lines.push(
+				!isSelected && i === this.#hoveredIndex && this.theme.hovered ? this.theme.hovered(rendered) : rendered,
+			);
 		}
 
 		// Add scroll indicators if needed

package/src/index.ts

@@ -53,6 +53,7 @@ export * from "./keys";
 export { type RenderLatexOptions, renderLatex } from "./latex";
 // Media playback state machine
 export * from "./media-playback";
+export * from "./mouse";
 // Mermaid diagram support
 // Input buffering for batch splitting
 export * from "./stdin-buffer";
@@ -61,6 +62,7 @@ export type * from "./symbols";
 export * from "./terminal";
 // Terminal image support
 export * from "./terminal-capabilities";
+export * from "./terminal-multiplexer";
 // TTY ID
 export * from "./ttyid";
 export * from "./tui";

package/src/mouse.ts

@@ -0,0 +1,61 @@
+/** Decoded SGR mouse report with zero-based coordinates. */
+export interface SgrMouseEvent {
+	button: number;
+	col: number;
+	row: number;
+	release: boolean;
+	wheel: -1 | 1 | null;
+	motion: boolean;
+	leftClick: boolean;
+}
+
+export function parseSgrMouse(data: string): SgrMouseEvent | null {
+	const match = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(data);
+	if (!match) return null;
+	const button = Number(match[1]);
+	const col = Number(match[2]) - 1;
+	const row = Number(match[3]) - 1;
+	const release = match[4] === "m";
+	// SGR 66/67 are horizontal wheel reports. They must not move vertical lists.
+	const wheel = button & 64 && !(button & 2) ? ((button & 1 ? 1 : -1) as -1 | 1) : null;
+	const motion = (button & 32) !== 0 && wheel === null;
+	const leftClick = !release && wheel === null && !motion && (button & 3) === 0;
+	return { button, col, row, release, wheel, motion, leftClick };
+}
+
+export type SgrMouseHandler = (event: SgrMouseEvent) => boolean | undefined;
+
+export function routeSgrMouseInput(data: string, handler: SgrMouseHandler): boolean {
+	if (!data.startsWith("\x1b[<")) return false;
+	const event = parseSgrMouse(data);
+	if (!event) return false;
+	return handler(event) !== false;
+}
+
+export interface SelectListMouseTarget {
+	handleWheel(delta: -1 | 1): void;
+	hitTest(line: number): number | undefined;
+	setHoverIndex(index: number | null): void;
+	clickItem(index: number): void;
+}
+
+export function routeSelectListMouse(target: SelectListMouseTarget, event: SgrMouseEvent, line: number): boolean {
+	if (event.wheel !== null) {
+		target.handleWheel(event.wheel);
+		return true;
+	}
+	const index = target.hitTest(line);
+	if (event.motion) {
+		target.setHoverIndex(index ?? null);
+		return true;
+	}
+	if (event.leftClick && index !== undefined) {
+		target.clickItem(index);
+		return true;
+	}
+	return false;
+}
+
+export interface MouseRoutable {
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/src/terminal-capabilities.ts

@@ -1,5 +1,6 @@
 import { encodeSixel } from "@f5-sales-demo/pi-natives";
 import { $env } from "@f5-sales-demo/pi-utils";
+import { isInsideHerdr } from "./terminal-multiplexer";
 
 export enum ImageProtocol {
 	Kitty = "\x1b_G",
@@ -15,6 +16,59 @@ export enum NotifyProtocol {
 
 export type TerminalId = "kitty" | "ghostty" | "wezterm" | "iterm2" | "vscode" | "alacritty" | "base" | "trueColor";
 
+export interface TerminalNotification {
+	title?: string;
+	body?: string;
+	type?: string | string[];
+}
+
+const DEFAULT_NOTIFICATION_TITLE = "xcsh";
+const HERDR_PANE_ID_PATTERN = /^[0-9A-Za-z:_-]{1,64}$/u;
+const HERDR_USAGE_TOKENS = new Set(["help", "--help", "-h"]);
+
+function notificationTitleAndBody(message: string | TerminalNotification): { title: string; body: string } {
+	if (typeof message === "string") return { title: DEFAULT_NOTIFICATION_TITLE, body: message };
+	return { title: message.title?.trim() || DEFAULT_NOTIFICATION_TITLE, body: message.body ?? "" };
+}
+
+function notificationToLine(message: TerminalNotification): string {
+	if (message.title && message.body) return `${message.title}: ${message.body}`;
+	return message.title ?? message.body ?? "";
+}
+
+export function buildHerdrNotificationCommand(
+	message: string | TerminalNotification,
+	env: NodeJS.ProcessEnv = Bun.env,
+): string[] | null {
+	if (!isInsideHerdr(env)) return null;
+	const paneId = env.HERDR_PANE_ID?.trim();
+	if (!paneId || !HERDR_PANE_ID_PATTERN.test(paneId)) return null;
+	const parsed = notificationTitleAndBody(message);
+	const title = HERDR_USAGE_TOKENS.has(parsed.title) ? DEFAULT_NOTIFICATION_TITLE : parsed.title;
+	const types = typeof message === "string" ? [] : [message.type ?? []].flat();
+	const sound =
+		types.includes("ask") || types.includes("error") ? "request" : types.includes("completion") ? "done" : "none";
+	return ["herdr", "notification", "show", title, "--body", parsed.body, "--sound", sound];
+}
+
+function sendHerdrNotification(message: string | TerminalNotification, env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const cmd = buildHerdrNotificationCommand(message, env);
+	if (!cmd) return false;
+	if (!Bun.which(cmd[0]!, { PATH: env.PATH })) return false;
+	try {
+		const child = Bun.spawn({
+			cmd,
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 const SIXEL_DCS_START_REGEX = /\x1bP(?:[0-9;]*)q/u;
 /** Terminal capability details used for rendering and protocol selection. */
 export class TerminalInfo {
@@ -40,15 +94,17 @@ export class TerminalInfo {
 		return false;
 	}
 
-	formatNotification(message: string): string {
+	formatNotification(message: string | TerminalNotification): string {
 		if (this.notifyProtocol === NotifyProtocol.Bell) {
 			return NotifyProtocol.Bell;
 		}
-		return `${this.notifyProtocol}${message}\x1b\\`;
+		const line = typeof message === "string" ? message : notificationToLine(message);
+		return `${this.notifyProtocol}${line}\x1b\\`;
 	}
 
-	sendNotification(message: string): void {
+	sendNotification(message: string | TerminalNotification): void {
 		if (isNotificationSuppressed()) return;
+		if (sendHerdrNotification(message)) return;
 		process.stdout.write(this.formatNotification(message));
 	}
 }

package/src/terminal-multiplexer.ts

@@ -0,0 +1,12 @@
+/** True when this process is running inside a Herdr pane. */
+export function isInsideHerdr(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (env.HERDR_ENV === "1") return true;
+	return Boolean(env.HERDR_PANE_ID || env.HERDR_TAB_ID || env.HERDR_WORKSPACE_ID);
+}
+
+/** Detect terminal multiplexers that own the current screen grid and scrollback. */
+export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (env.TMUX || env.STY || env.ZELLIJ || isInsideHerdr(env)) return true;
+	const term = env.TERM?.toLowerCase() ?? "";
+	return term.startsWith("tmux") || term.startsWith("screen");
+}

package/src/terminal.ts

@@ -12,6 +12,19 @@ import { StdinBuffer } from "./stdin-buffer";
 let activeTerminal: ProcessTerminal | null = null;
 // Track if a terminal was ever started (for emergency restore logic)
 let terminalEverStarted = false;
+let alternateScreenActive = false;
+const EMERGENCY_MOUSE_RESTORE = "\x1b[?1006l\x1b[?1003l\x1b[?1000l";
+
+/** Track alternate-screen ownership so crash cleanup does not disturb the normal screen. */
+export function setAlternateScreenActive(active: boolean): void {
+	alternateScreenActive = active;
+}
+
+function emergencyScreenRestoreSequence(): string {
+	const sequence = `${EMERGENCY_MOUSE_RESTORE}${alternateScreenActive ? "\x1b[?1049l" : ""}`;
+	alternateScreenActive = false;
+	return sequence;
+}
 
 const STD_INPUT_HANDLE = -10;
 const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
@@ -24,12 +37,14 @@ export function emergencyTerminalRestore(): void {
 		const terminal = activeTerminal;
 		if (terminal) {
 			terminal.stop();
+			process.stdout.write(emergencyScreenRestoreSequence());
 			terminal.showCursor();
 		} else if (terminalEverStarted) {
 			// Blind restore only if we know a terminal was started but lost track of it
 			// This avoids writing escape sequences for non-TUI commands (grep, commit, etc.)
 			process.stdout.write(
-				"\x1b[?2004l" + // Disable bracketed paste
+				emergencyScreenRestoreSequence() +
+					"\x1b[?2004l" + // Disable bracketed paste
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
 					"\x1b[>4;0m" + // Disable modifyOtherKeys fallback

package/src/tui.ts

@@ -5,14 +5,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { $flag, getDebugLogPath } from "@f5-sales-demo/pi-utils";
 import { isKeyRelease, matchesKey } from "./keys";
-import type { Terminal } from "./terminal";
+import { type MouseRoutable, routeSgrMouseInput } from "./mouse";
+import { setAlternateScreenActive, type Terminal } from "./terminal";
 import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL } from "./terminal-capabilities";
+import { isInsideTerminalMultiplexer } from "./terminal-multiplexer";
 import { extractSegments, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils";
 
 const SEGMENT_RESET = "\x1b[0m";
 const LINE_FIT_MIN_SOURCE_CODE_UNITS = 4096;
 const LINE_FIT_MAX_SOURCE_CODE_UNITS = 65_536;
 const LINE_FIT_SOURCE_WIDTH_MULTIPLIER = 64;
+const MOUSE_TRACKING_ON = "\x1b[?1000h\x1b[?1003h\x1b[?1006h";
+const MOUSE_TRACKING_OFF = "\x1b[?1006l\x1b[?1003l\x1b[?1000l";
 
 function ansiSequenceEnd(line: string, start: number): number {
 	const next = line.charCodeAt(start + 1);
@@ -186,7 +190,7 @@ function isTermuxSession(): boolean {
 
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
 function isMultiplexer() {
-	return Boolean(Bun.env.TMUX || Bun.env.STY || Bun.env.ZELLIJ);
+	return isInsideTerminalMultiplexer();
 }
 
 /**
@@ -194,6 +198,10 @@ function isMultiplexer() {
  * Values can be absolute numbers or percentage strings (e.g., "50%").
  */
 export interface OverlayOptions {
+	/** Borrow the alternate screen and render this overlay as a full viewport. */
+	fullscreen?: boolean;
+	/** Enable SGR mouse reporting while fullscreen. Defaults to true. */
+	mouseTracking?: boolean;
 	// === Sizing ===
 	/** Width in columns, or percentage of terminal width (e.g., "50%") */
 	width?: SizeValue;
@@ -313,6 +321,11 @@ export class TUI extends Container {
 	#maxLinesRendered = 0; // High-water line count used for clear-on-shrink policy
 	#fullRedrawCount = 0;
 	#stopped = false;
+	#fullscreenActive = false;
+	#mouseTrackingActive = false;
+	#fullscreenLines: string[] = [];
+	#fullscreenWidth = 0;
+	#fullscreenHeight = 0;
 	#viewportObservers = new Map<number, { callback: (visible: boolean) => void; visible: boolean }>();
 	#nextViewportObserverId = 1;
 
@@ -679,6 +692,7 @@ export class TUI extends Container {
 	stop(): void {
 		this.#clearSixelProbeState();
 		this.#stopped = true;
+		this.#leaveFullscreen();
 		// Move cursor to the end of the content to prevent overwriting/artifacts on exit
 		if (this.#previousLines.length > 0) {
 			const targetRow = this.#previousLines.length; // Line after the last content
@@ -771,6 +785,21 @@ export class TUI extends Container {
 			}
 		}
 
+		const focusedComponent = this.#focusedComponent as (Component & Partial<MouseRoutable>) | null;
+		const routeMouse = focusedComponent?.routeMouse;
+		if (
+			this.#fullscreenActive &&
+			focusedComponent &&
+			typeof routeMouse === "function" &&
+			routeSgrMouseInput(data, event => {
+				routeMouse.call(focusedComponent, event, event.row, event.col);
+				return true;
+			})
+		) {
+			this.requestRender();
+			return;
+		}
+
 		// Pass input to focused component (including Ctrl+C)
 		// The focused component can decide how to handle Ctrl+C
 		if (this.#focusedComponent?.handleInput) {
@@ -1126,6 +1155,27 @@ export class TUI extends Container {
 		if (this.#stopped) return;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
+		const topOverlay = this.#getTopmostVisibleOverlay();
+		const wantFullscreen = topOverlay?.options?.fullscreen === true;
+		const wantMouse = wantFullscreen && topOverlay.options?.mouseTracking !== false;
+		if (wantFullscreen && topOverlay) {
+			if (!this.#fullscreenActive) {
+				this.terminal.write(`\x1b[?1049h${wantMouse ? MOUSE_TRACKING_ON : ""}`);
+				setAlternateScreenActive(true);
+				this.#fullscreenActive = true;
+				this.#mouseTrackingActive = wantMouse;
+				this.#fullscreenLines = [];
+			} else if (wantMouse !== this.#mouseTrackingActive) {
+				this.terminal.write(wantMouse ? MOUSE_TRACKING_ON : MOUSE_TRACKING_OFF);
+				this.#mouseTrackingActive = wantMouse;
+			}
+			this.#renderFullscreen(topOverlay.component, width, height);
+			return;
+		}
+		const restoredFromFullscreen = this.#fullscreenActive;
+		if (restoredFromFullscreen) {
+			this.#leaveFullscreen();
+		}
 		let viewportTop = Math.max(0, this.#maxLinesRendered - height);
 		let prevViewportTop = this.#viewportTopRow;
 		let hardwareCursorRow = this.#hardwareCursorRow;
@@ -1164,11 +1214,11 @@ export class TUI extends Container {
 		const heightChanged = this.#previousHeight !== 0 && this.#previousHeight !== height;
 
 		// Helper to clear scrollback and viewport and render all new lines
-		const fullRender = (clear: boolean): void => {
+		const fullRender = (clear: boolean, preserveScrollback = false): void => {
 			this.#fullRedrawCount += 1;
 			let buffer = "\x1b[?2026h"; // Begin synchronized output
 			// Skip clearing scrollback (3J) in multiplexers — users actively navigate scrollback history
-			if (clear) buffer += isMultiplexer() ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
+			if (clear) buffer += isMultiplexer() || preserveScrollback ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
 			const reset = SEGMENT_RESET;
 			for (let i = 0; i < newLines.length; i++) {
 				if (i > 0) buffer += "\r\n";
@@ -1210,7 +1260,7 @@ export class TUI extends Container {
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
 			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			fullRender(true);
+			fullRender(true, restoredFromFullscreen);
 			return;
 		}
 
@@ -1219,7 +1269,7 @@ export class TUI extends Container {
 		// In that environment, a full redraw causes the entire history to replay on every toggle.
 		if (heightChanged && !isTermuxSession() && !isMultiplexer()) {
 			logRedraw(`terminal height changed (${this.#previousHeight} -> ${height})`);
-			fullRender(true);
+			fullRender(true, restoredFromFullscreen);
 			return;
 		}
 
@@ -1423,6 +1473,47 @@ export class TUI extends Container {
 		this.#previousHeight = height;
 	}
 
+	#renderFullscreen(component: Component, width: number, height: number): void {
+		const rendered = component
+			.render(width)
+			.slice(0, height)
+			.map(line => {
+				const withoutCursor = line.replaceAll(CURSOR_MARKER, "");
+				return visibleWidth(withoutCursor) > width ? sliceByColumn(withoutCursor, 0, width, true) : withoutCursor;
+			});
+		const frame = Array.from({ length: height }, (_, row) => rendered[row] ?? "");
+		if (
+			frame.length === this.#fullscreenLines.length &&
+			width === this.#fullscreenWidth &&
+			height === this.#fullscreenHeight &&
+			frame.every((line, row) => line === this.#fullscreenLines[row])
+		) {
+			return;
+		}
+		let buffer = "\x1b[?2026h\x1b[H";
+		for (let row = 0; row < height; row++) {
+			if (row > 0) buffer += "\r\n";
+			buffer += `\x1b[2K${frame[row]}${SEGMENT_RESET}`;
+		}
+		buffer += "\x1b[?2026l";
+		this.terminal.hideCursor();
+		this.terminal.write(buffer);
+		this.#fullscreenLines = frame;
+		this.#fullscreenWidth = width;
+		this.#fullscreenHeight = height;
+	}
+
+	#leaveFullscreen(): void {
+		if (!this.#fullscreenActive) return;
+		this.terminal.write(`${this.#mouseTrackingActive ? MOUSE_TRACKING_OFF : ""}\x1b[?1049l`);
+		setAlternateScreenActive(false);
+		this.#fullscreenActive = false;
+		this.#mouseTrackingActive = false;
+		this.#fullscreenLines = [];
+		this.#fullscreenWidth = 0;
+		this.#fullscreenHeight = 0;
+	}
+
 	/**
 	 * Position the hardware cursor for IME candidate window.
 	 * @param cursorPos The cursor position extracted from rendered output, or null