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

package/CHANGELOG.md

@@ -6,6 +6,13 @@
 
 ### 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),

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-tui",
-	"version": "21.17.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.17.0",
-		"@f5-sales-demo/pi-utils": "21.17.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/terminal-capabilities.ts

@@ -230,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,
 		);
 	}
@@ -247,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);
@@ -261,6 +322,7 @@ export const TERMINAL = resolveTerminalInfo(Bun.env, process.stdout.isTTY ?? fal
 
 type MutableTerminalInfo = {
 	imageProtocol: ImageProtocol | null;
+	hyperlinks: boolean;
 };
 
 /**
@@ -270,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/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(