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

package/CHANGELOG.md

@@ -6,6 +6,24 @@
 
 ### Fixed
 
+- Added conservative runtime OSC 8 capability control, safe Markdown link extraction and targets,
+  ST normalization, and physical-wrap link isolation. Semantically ported from
+  [can1357/oh-my-pi#10196](https://github.com/can1357/oh-my-pi/pull/10196),
+  [#5887](https://github.com/can1357/oh-my-pi/pull/5887),
+  [#6282](https://github.com/can1357/oh-my-pi/pull/6282), and
+  [#11086](https://github.com/can1357/oh-my-pi/pull/11086)
+  ([#3758](https://github.com/f5-sales-demo/xcsh/issues/3758)).
+- 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.18.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.18.0",
+		"@f5-sales-demo/pi-utils": "21.18.0",
 		"marked": "^18.0"
 	},
 	"devDependencies": {

package/src/components/markdown.ts

@@ -1,3 +1,5 @@
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
 import { Marked, type Token, type TokenizerExtension, type Tokens } from "marked";
 import { renderLatex } from "../latex";
 import type { SymbolTheme } from "../symbols";
@@ -147,6 +149,74 @@ const markdownParser = new Marked({ gfm: true, async: false }).use({
 	extensions: [...LATEX_MARKDOWN_EXTENSIONS],
 });
 
+const OSC8_SEQUENCE_RE = /\x1b\]8;[^\x07\x1b]*(?:\x07|\x1b\\)/gu;
+const OSC8_ST_PREFIX_RE = /(\x1b\]8;[^\x07\x1b]*)\x1b\\/gu;
+const UNSAFE_URI_BYTES_RE = /[\x00-\x1f\x7f-\x9f]/u;
+
+function normalizeOsc8Terminators(text: string): string {
+	return text.replace(OSC8_ST_PREFIX_RE, "$1\x07");
+}
+
+function plainInlineTokens(tokens: readonly Token[] | undefined): string {
+	if (!tokens) return "";
+	let result = "";
+	for (const token of tokens) {
+		const nestedTokens = (token as Token & { tokens?: Token[] }).tokens;
+		if (token.type === "image") continue;
+		if (token.type === "codespan") {
+			result += token.text;
+			continue;
+		}
+		if (token.type === "br") {
+			result += " ";
+			continue;
+		}
+		if (token.type === "text" || token.type === "escape") {
+			result += nestedTokens?.length ? plainInlineTokens(nestedTokens) : token.text;
+			continue;
+		}
+		result += plainInlineTokens(nestedTokens);
+	}
+	return result;
+}
+
+/** A hyperlink exactly as the configured Markdown lexer resolves it. */
+export interface MarkdownLink {
+	text: string;
+	href: string;
+}
+
+/** Extract rendered links in document order, retaining duplicates and excluding code and images. */
+export function extractMarkdownLinks(text: string): MarkdownLink[] {
+	const links: MarkdownLink[] = [];
+	const walk = (tokens: readonly Token[] | undefined): void => {
+		if (!tokens) return;
+		for (const token of tokens) {
+			if (token.type === "code" || token.type === "codespan" || token.type === "image") continue;
+			if (token.type === "link") {
+				const link = token as Tokens.Link;
+				if (typeof link.href === "string" && link.href.length > 0) {
+					const label = plainInlineTokens(link.tokens).replace(/\s+/gu, " ").trim();
+					links.push({ text: label || link.href, href: link.href });
+				}
+				continue;
+			}
+			const nested = token as unknown as {
+				tokens?: Token[];
+				items?: Array<{ tokens?: Token[] }>;
+				header?: Array<{ tokens?: Token[] }>;
+				rows?: Array<Array<{ tokens?: Token[] }>>;
+			};
+			walk(nested.tokens);
+			if (nested.items) for (const item of nested.items) walk(item.tokens);
+			if (nested.header) for (const cell of nested.header) walk(cell.tokens);
+			if (nested.rows) for (const row of nested.rows) for (const cell of row) walk(cell.tokens);
+		}
+	};
+	walk(markdownParser.lexer(normalizeOsc8Terminators(text)));
+	return links;
+}
+
 /**
  * Default text styling for markdown content.
  * Applied to all text unless overridden by markdown formatting.
@@ -172,6 +242,8 @@ export interface MarkdownOptions {
 	codeBlockIndent?: number;
 	/** Resolve and render Markdown image tokens. */
 	mediaOptions?: MarkdownMediaOptions;
+	/** Session cwd used to turn relative Markdown paths into lexical file:// targets. */
+	linkBasePath?: string;
 }
 
 /** Default text styling for markdown content. */
@@ -243,17 +315,44 @@ function isImageToken(token: Token): token is Tokens.Image {
 	);
 }
 
-function formatHyperlink(text: string, target: string): string {
+function safeHyperlinkTarget(target: string, linkBasePath?: string): string | undefined {
+	if (!target || UNSAFE_URI_BYTES_RE.test(target)) return undefined;
+	try {
+		if (UNSAFE_URI_BYTES_RE.test(decodeURIComponent(target))) return undefined;
+	} catch {
+		return undefined;
+	}
+	try {
+		const absolute = new URL(target);
+		return absolute.protocol === "http:" || absolute.protocol === "https:" || absolute.protocol === "file:"
+			? absolute.href
+			: undefined;
+	} catch {
+		if (!linkBasePath || /^(?:#|\?|\/\/)/u.test(target)) return undefined;
+		const suffixIndex = target.search(/[?#]/u);
+		const rawPath = suffixIndex < 0 ? target : target.slice(0, suffixIndex);
+		const suffix = suffixIndex < 0 ? "" : target.slice(suffixIndex);
+		if (!rawPath) return undefined;
+		try {
+			return `${pathToFileURL(path.resolve(linkBasePath, decodeURIComponent(rawPath))).href}${suffix}`;
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+function formatHyperlink(text: string, target: string, linkBasePath?: string): string {
 	if (!TERMINAL.hyperlinks || !target) {
 		return text;
 	}
 
-	const safeTarget = target.replaceAll("\x1b", "").replaceAll("\x07", "");
+	const safeTarget = safeHyperlinkTarget(target, linkBasePath);
 	if (!safeTarget) {
 		return text;
 	}
 
-	return `\x1b]8;;${safeTarget}\x07${text}\x1b]8;;\x07`;
+	const safeLabel = text.replace(OSC8_SEQUENCE_RE, "");
+	return `\x1b]8;;${safeTarget}\x07${safeLabel}\x1b]8;;\x07`;
 }
 
 export class Markdown implements Component {
@@ -267,6 +366,7 @@ export class Markdown implements Component {
 	#codeBlockIndent: number;
 	#mediaOptions?: MarkdownMediaOptions;
 	#renderLatex: boolean;
+	#linkBasePath?: string;
 	#mediaCache = new Map<
 		string,
 		{ status: "pending" } | { status: "loaded"; media: ResolvedMarkdownMedia } | { status: "error"; message: string }
@@ -318,6 +418,7 @@ export class Markdown implements Component {
 		this.#codeBlockIndent = Math.max(0, Math.floor(options.codeBlockIndent ?? 2));
 		this.#mediaOptions = options.mediaOptions;
 		this.#renderLatex = options.renderLatex !== false;
+		this.#linkBasePath = options.linkBasePath;
 	}
 
 	setText(text: string): void {
@@ -351,7 +452,7 @@ export class Markdown implements Component {
 		}
 
 		// Replace tabs with 3 spaces for consistent rendering
-		const normalizedText = replaceTabs(this.#text);
+		const normalizedText = normalizeOsc8Terminators(replaceTabs(this.#text));
 
 		// Parse markdown to HTML-like tokens
 		const tokens = markdownParser.lexer(normalizedText);
@@ -820,7 +921,7 @@ export class Markdown implements Component {
 				case "link": {
 					const linkText = this.#renderInlineTokens(token.tokens || [], resolvedStyleContext);
 					const styledLinkText = this.#theme.link(this.#theme.underline(linkText));
-					const clickableLinkText = formatHyperlink(styledLinkText, token.href);
+					const clickableLinkText = formatHyperlink(styledLinkText, token.href, this.#linkBasePath);
 					// If link text matches href, only show the link once
 					// Compare raw text (token.text) not styled text (linkText) since linkText has ANSI codes
 					// For mailto: links, strip the prefix before comparing (autolinked emails have
@@ -830,7 +931,8 @@ export class Markdown implements Component {
 						result += clickableLinkText + stylePrefix;
 					else {
 						const styledLinkUrl = this.#theme.linkUrl(` (${token.href})`);
-						result += clickableLinkText + formatHyperlink(styledLinkUrl, token.href) + stylePrefix;
+						result +=
+							clickableLinkText + formatHyperlink(styledLinkUrl, token.href, this.#linkBasePath) + stylePrefix;
 					}
 					break;
 				}

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));
 	}
 }
@@ -174,13 +230,14 @@ export function resolveTerminalId(env: NodeJS.ProcessEnv): TerminalId {
 /** Resolve terminal capabilities from an explicit environment and stdout TTY state. */
 export function resolveTerminalInfo(env: NodeJS.ProcessEnv, stdoutIsTTY: boolean): TerminalInfo {
 	const terminal = getTerminalInfo(resolveTerminalId(env));
+	const hyperlinks = shouldEnableTerminalHyperlinks(env, stdoutIsTTY, terminal.id);
 	const forcedImageProtocol = getForcedImageProtocol(env);
 	if (forcedImageProtocol !== undefined) {
 		return new TerminalInfo(
 			terminal.id,
 			forcedImageProtocol,
 			terminal.trueColor,
-			terminal.hyperlinks,
+			hyperlinks,
 			terminal.notifyProtocol,
 		);
 	}
@@ -191,12 +248,72 @@ export function resolveTerminalInfo(env: NodeJS.ProcessEnv, stdoutIsTTY: boolean
 				terminal.id,
 				fallbackImageProtocol,
 				terminal.trueColor,
-				terminal.hyperlinks,
+				hyperlinks,
 				terminal.notifyProtocol,
 			);
 		}
 	}
-	return terminal;
+	return new TerminalInfo(
+		terminal.id,
+		terminal.imageProtocol,
+		terminal.trueColor,
+		hyperlinks,
+		terminal.notifyProtocol,
+	);
+}
+
+function versionAtLeast(raw: string | undefined, major: number, minor: number, patch = 0): boolean {
+	if (!raw) return false;
+	const match = /^(\d+)\.(\d+)(?:\.(\d+))?/u.exec(raw.trim());
+	if (!match) return false;
+	const actual = [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+	const wanted = [major, minor, patch];
+	for (let index = 0; index < wanted.length; index++) {
+		if (actual[index] !== wanted[index]) return actual[index]! > wanted[index]!;
+	}
+	return true;
+}
+
+function localCommandVersion(env: NodeJS.ProcessEnv, command: "herdr" | "tmux"): string | undefined {
+	if (env !== Bun.env) return undefined;
+	try {
+		const result = Bun.spawnSync([command, command === "tmux" ? "-V" : "--version"], {
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		if (result.exitCode !== 0) return undefined;
+		return /(\d+\.\d+(?:\.\d+)?(?:[-+._A-Za-z0-9]*)?)/u.exec(result.stdout.toString())?.[1];
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Resolve the immutable startup OSC 8 capability snapshot.
+ *
+ * Unknown terminals and lossy multiplexers are deliberately conservative.
+ * Herdr and tmux are enabled only at versions that preserve OSC 8 spans.
+ */
+function shouldEnableTerminalHyperlinks(
+	env: NodeJS.ProcessEnv,
+	stdoutIsTTY: boolean,
+	terminalId: TerminalId = resolveTerminalId(env),
+): boolean {
+	if (!stdoutIsTTY || env.NO_COLOR) return false;
+	if (env.STY || env.ZELLIJ) return false;
+	if (isInsideHerdr(env)) return versionAtLeast(env.HERDR_VERSION ?? localCommandVersion(env, "herdr"), 0, 7, 5);
+	if (env.TMUX) {
+		const declaredVersion =
+			env.TMUX_VERSION ?? (env.TERM_PROGRAM?.toLowerCase() === "tmux" ? env.TERM_PROGRAM_VERSION : undefined);
+		return versionAtLeast(declaredVersion ?? localCommandVersion(env, "tmux"), 3, 4);
+	}
+	const term = env.TERM?.toLowerCase() ?? "";
+	if (term.startsWith("screen") || term.startsWith("tmux") || term.startsWith("zellij")) return false;
+	if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) {
+		return terminalId !== "base" && terminalId !== "trueColor";
+	}
+	return terminalId !== "base" && terminalId !== "trueColor";
 }
 
 export const TERMINAL_ID: TerminalId = resolveTerminalId(Bun.env);
@@ -205,6 +322,7 @@ export const TERMINAL = resolveTerminalInfo(Bun.env, process.stdout.isTTY ?? fal
 
 type MutableTerminalInfo = {
 	imageProtocol: ImageProtocol | null;
+	hyperlinks: boolean;
 };
 
 /**
@@ -214,6 +332,11 @@ export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): v
 	(TERMINAL as unknown as MutableTerminalInfo).imageProtocol = imageProtocol;
 }
 
+/** Override OSC 8 hyperlink emission after applying the user's policy. */
+export function setTerminalHyperlinks(enabled: boolean): void {
+	(TERMINAL as unknown as MutableTerminalInfo).hyperlinks = enabled;
+}
+
 export function getTerminalInfo(terminalId: TerminalId): TerminalInfo {
 	return KNOWN_TERMINALS[terminalId];
 }

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

package/src/utils.ts

@@ -24,22 +24,8 @@ export function truncateToWidth(
 	return nativeTruncateToWidth(text, maxWidth, ellipsisKind, pad, getDefaultTabWidth());
 }
 
-const OSC8_RE = /\x1b\]8;;([^\x07]*)\x07/g;
-
-function fixOsc8Boundaries(lines: string[]): string[] {
-	let activeUrl: string | null = null;
-	return lines.map(line => {
-		const prefix = activeUrl !== null ? `\x1b]8;;${activeUrl}\x07` : "";
-		for (const match of line.matchAll(OSC8_RE)) {
-			activeUrl = match[1] === "" ? null : match[1];
-		}
-		const suffix = activeUrl !== null ? `\x1b]8;;\x07` : "";
-		return prefix + line + suffix;
-	});
-}
-
 export function wrapTextWithAnsi(text: string, width: number): string[] {
-	return fixOsc8Boundaries(nativeWrapTextWithAnsi(text, width, getDefaultTabWidth()));
+	return nativeWrapTextWithAnsi(text, width, getDefaultTabWidth());
 }
 
 export function extractSegments(