@sayknow-cli/tui 0.7.11 → 0.7.13

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## [Unreleased]
 
-## [0.7.11] - 2026-10-22
+## [0.7.13] - 2026-10-26
 
 ## [0.7.2] - 2026-09-29
 

package/dist/types/terminal-capabilities.d.ts

@@ -203,6 +203,7 @@ export interface ImageRenderOptions {
 export declare function kittyImageId(base64Data: string): number;
 export declare function getCellDimensions(): CellDimensions;
 export declare function setCellDimensions(dims: CellDimensions): void;
+export declare function isRfc4648Base64(value: string): boolean;
 export declare function encodeKitty(base64Data: string, options?: {
     columns?: number;
     rows?: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.7.11",
+	"version": "0.7.13",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.7.11",
-		"@sayknow-cli/utils": "0.7.11",
+		"@sayknow-cli/natives": "0.7.13",
+		"@sayknow-cli/utils": "0.7.13",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/markdown.ts

@@ -1,3 +1,6 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
 import { LRUCache } from "lru-cache/raw";
 import { Marked, marked, type Token, Tokenizer, type Tokens } from "marked";
 import type { SymbolTheme } from "../symbols";
@@ -216,17 +219,78 @@ type ListToken = Token & { items: Array<{ tokens?: Token[] }>; ordered: boolean;
 type TableCellToken = { tokens?: Token[] };
 type TableToken = Token & { header: TableCellToken[]; rows: TableCellToken[][]; raw?: string };
 
+/** Relative markdown links follow the active session's process cwd and home. */
+function markdownLinkContextKey(): string {
+	let cwd = "<unavailable>";
+	let home = "<unavailable>";
+	try {
+		cwd = process.cwd();
+	} catch {}
+	try {
+		home = os.homedir();
+	} catch {}
+	return `${cwd}\x00${home}`;
+}
+
+/** Decodes valid `%XX` runs; a `%` that does not start a valid UTF-8 escape stays a literal percent sign. */
+function decodePercentEscapes(value: string): string {
+	return value.replace(/(?:%[0-9a-f]{2})+/giu, escapes => {
+		try {
+			return decodeURIComponent(escapes);
+		} catch {
+			return escapes;
+		}
+	});
+}
+
+/**
+ * Converts a local Markdown link destination to an absolute `file://` URI. The destination is a URI
+ * reference: its path may be percent-encoded, and `?` or `#` starts the query or fragment, which stay
+ * URI components instead of becoming part of the filename.
+ */
+function localFileUri(target: string): string {
+	const suffixStart = target.search(/[?#]/u);
+	const pathPart = suffixStart === -1 ? target : target.slice(0, suffixStart);
+	const suffix = suffixStart === -1 ? "" : target.slice(suffixStart);
+	const filePath = decodePercentEscapes(pathPart);
+	let absolutePath: string;
+	if (path.isAbsolute(filePath)) {
+		absolutePath = filePath;
+	} else if (filePath === "~") {
+		absolutePath = os.homedir();
+	} else if (filePath.startsWith("~/")) {
+		absolutePath = path.resolve(os.homedir(), filePath.slice(2));
+	} else {
+		absolutePath = path.resolve(process.cwd(), filePath);
+	}
+	const fileUrl = url.pathToFileURL(absolutePath);
+	return suffix ? new URL(suffix, fileUrl).href : fileUrl.href;
+}
+
 function formatHyperlink(text: string, target: string): string {
 	if (!TERMINAL.hyperlinks || !target) {
 		return text;
 	}
 
-	const safeTarget = target.replaceAll("\x1b", "").replaceAll("\x07", "");
-	if (!safeTarget) {
+	if (/[\u0000-\u001f\u007f-\u009f]/u.test(target)) {
 		return text;
 	}
 
-	return `\x1b]8;;${safeTarget}\x07${text}\x1b]8;;\x07`;
+	// `#fragment` and `//authority/path` (network-path reference) are URI references, not local paths.
+	let destination = target;
+	if (
+		!target.startsWith("#") &&
+		!target.startsWith("//") &&
+		(path.isAbsolute(target) || !/^[a-z][a-z\d+.-]*:/iu.test(target))
+	) {
+		try {
+			destination = localFileUri(target);
+		} catch {
+			return text;
+		}
+	}
+
+	return `\x1b]8;;${destination}\x07${text}\x1b]8;;\x07`;
 }
 
 function stripHtmlComments(raw: string): string {
@@ -267,6 +331,7 @@ export class Markdown implements Component {
 	#cachedWidth?: number;
 	#cachedLines?: string[];
 	#cachedAnchorSpans?: Array<ViewportAnchorSpan | null>;
+	#cachedLinkContextKey?: string;
 
 	#streaming = false;
 	#lastFullParseAt = 0;
@@ -343,6 +408,7 @@ export class Markdown implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
 		this.#cachedAnchorSpans = undefined;
+		this.#cachedLinkContextKey = undefined;
 	}
 
 	#exceedsHighlightCap(code: string): boolean {
@@ -393,10 +459,13 @@ export class Markdown implements Component {
 	#render(width: number, includeAnchors: boolean): { lines: string[]; spans?: Array<ViewportAnchorSpan | null> } {
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
+		// Only bracketed Markdown can contain a link target; plain text stays shared.
+		const linkContextKey = this.#text.includes("]") ? markdownLinkContextKey() : "";
 		if (
 			this.#cachedLines &&
 			this.#cachedText === this.#text &&
 			this.#cachedWidth === width &&
+			this.#cachedLinkContextKey === linkContextKey &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
 		) {
 			return { lines: this.#cachedLines, spans: this.#cachedAnchorSpans };
@@ -409,6 +478,7 @@ export class Markdown implements Component {
 			this.#streaming &&
 			this.#cachedLines &&
 			this.#cachedWidth === width &&
+			this.#cachedLinkContextKey === linkContextKey &&
 			this.#lastFullParseAt > 0 &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
 		) {
@@ -427,6 +497,7 @@ export class Markdown implements Component {
 			this.#cachedWidth = width;
 			this.#cachedLines = result;
 			this.#cachedAnchorSpans = includeAnchors ? [] : undefined;
+			this.#cachedLinkContextKey = linkContextKey;
 			return { lines: result, spans: this.#cachedAnchorSpans };
 		}
 
@@ -442,7 +513,8 @@ export class Markdown implements Component {
 		// and verify it on hit so hash collisions can never serve wrong output.
 		const bgColorProbe = this.#defaultTextStyle?.bgColor ? this.#defaultTextStyle.bgColor("\x01") : "";
 		const headingProbe = this.#theme.heading("");
-		const cacheKey = `${contentKey}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
+		const linkContextSuffix = linkContextKey ? `\x00${linkContextKey}` : "";
+		const cacheKey = `${contentKey}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}${linkContextSuffix}\x00${bgColorProbe}\x00${headingProbe}`;
 		const cached = renderCache.get(cacheKey);
 		if (
 			cached !== undefined &&
@@ -454,6 +526,7 @@ export class Markdown implements Component {
 			this.#cachedWidth = width;
 			this.#cachedLines = cached.lines;
 			this.#cachedAnchorSpans = cached.anchorSpans;
+			this.#cachedLinkContextKey = linkContextKey;
 			return { lines: cached.lines, spans: cached.anchorSpans };
 		}
 
@@ -620,6 +693,7 @@ export class Markdown implements Component {
 		this.#cachedWidth = width;
 		this.#cachedLines = result;
 		this.#cachedAnchorSpans = anchorSpans;
+		this.#cachedLinkContextKey = linkContextKey;
 		this.#lastFullParseAt = markdownNow();
 
 		// Update L2 module-level LRU so future instances with the same key skip

package/src/terminal-capabilities.ts

@@ -627,6 +627,39 @@ export function setCellDimensions(dims: CellDimensions): void {
 	cellDimensions = dims;
 }
 
+/**
+ * RFC 4648 base64. The alphabet excludes ESC, ST, and BEL, so a payload cannot
+ * end an APC or OSC early and smuggle a terminal escape out of an image.
+ * A linear scan, not a repeating-group regex: that regex rejects some
+ * multi-megabyte valid payloads in this runtime.
+ */
+function isBase64Alphabet(code: number): boolean {
+	return (
+		(code >= 65 && code <= 90) ||
+		(code >= 97 && code <= 122) ||
+		(code >= 48 && code <= 57) ||
+		code === 43 ||
+		code === 47
+	);
+}
+
+export function isRfc4648Base64(value: string): boolean {
+	const length = value.length;
+	if (length % 4 !== 0) return false;
+	let body = length;
+	if (length > 0 && value.charCodeAt(length - 1) === 61) {
+		body = value.charCodeAt(length - 2) === 61 ? length - 2 : length - 1;
+	}
+	for (let index = 0; index < body; index++) {
+		if (!isBase64Alphabet(value.charCodeAt(index))) return false;
+	}
+	return true;
+}
+
+function assertImageBase64(value: string): void {
+	if (!isRfc4648Base64(value)) throw new Error("Invalid RFC 4648 base64");
+}
+
 export function encodeKitty(
 	base64Data: string,
 	options: {
@@ -636,6 +669,7 @@ export function encodeKitty(
 		placementId?: number;
 	} = {},
 ): string {
+	assertImageBase64(base64Data);
 	const CHUNK_SIZE = 4096;
 
 	const params: string[] = ["a=T", "f=100", "q=2"];
@@ -711,6 +745,7 @@ export function setKittyTransmitWriter(writer: (sequence: string) => void): void
  * {@link encodeKittyPlacement} only.
  */
 export function encodeKittyTransmit(base64Data: string, imageId: number): string {
+	assertImageBase64(base64Data);
 	const CHUNK_SIZE = 4096;
 	const params = ["a=t", "f=100", "q=2", `i=${imageId}`];
 
@@ -767,6 +802,7 @@ export function encodeITerm2(
 		inline?: boolean;
 	} = {},
 ): string {
+	assertImageBase64(base64Data);
 	const params: string[] = [`inline=${options.inline !== false ? 1 : 0}`];
 
 	if (options.width !== undefined) params.push(`width=${options.width}`);
@@ -984,6 +1020,8 @@ export function renderImage(
 	if (!TERMINAL.imageProtocol) {
 		return null;
 	}
+	// An image that is not RFC 4648 base64 could close the escape early; render the text fallback.
+	if (!isRfc4648Base64(base64Data)) return null;
 
 	const cellDims = getCellDimensions();
 	const fit = calculateImageFit(imageDimensions, options, cellDims);

package/src/tui.ts

@@ -4,7 +4,14 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
-import { $flag, $pickflag, getDebugLogPath, logger, onDefaultTabWidthChange } from "@sayknow-cli/utils";
+import {
+	$flag,
+	$pickflag,
+	getDebugLogPath,
+	logger,
+	onDefaultTabWidthChange,
+	redactCrashSecrets,
+} from "@sayknow-cli/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -685,6 +692,23 @@ export interface PostRenderFrameInfo {
 	rows: number;
 }
 
+function filesystemErrorCode(error: unknown): string | undefined {
+	if (error === null || typeof error !== "object" || !("code" in error)) return undefined;
+	return typeof error.code === "string" ? error.code : undefined;
+}
+
+// JSON.stringify writes ESC as "\\u001b", and a CSI final is a letter, so a
+// following "Bearer" has no word boundary. Split that join, scrub, then restore.
+function redactTuiRenderDump(debugData: string): string {
+	const separateCsiFinal = (match: string) => `${match}\u0000`;
+	const separated = debugData
+		.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, separateCsiFinal)
+		.replace(/\\u001[bB]\[[0-9;?]*[A-Za-z]/g, separateCsiFinal);
+	return redactCrashSecrets(separated)
+		.replace(/\u001b\[[0-9;?]*[A-Za-z]\u0000/g, match => match.slice(0, -1))
+		.replace(/\\u001[bB]\[[0-9;?]*[A-Za-z]\u0000/g, match => match.slice(0, -1));
+}
+
 export type PostRenderEmitter = (frame: PostRenderFrameInfo) => string | null;
 
 export class TUI extends Container {
@@ -821,6 +845,38 @@ export class TUI extends Container {
 		fs.appendFileSync(getDebugLogPath(), message);
 	}
 
+	// Sibling of the debug log. Create the parent only when it is missing.
+	// The dump file is opened exclusive and no-follow, then written through that fd.
+	#writeRenderDebugDump(debugData: string): void {
+		const debugDir = path.dirname(getDebugLogPath());
+		if (!fs.existsSync(debugDir)) {
+			fs.mkdirSync(debugDir, { recursive: true, mode: 0o700 });
+			fs.chmodSync(debugDir, 0o700);
+		}
+		// stat follows a symlink to the real agent directory; a directory we do
+		// not own is not a place for a session frame.
+		const dirStat = fs.statSync(debugDir);
+		const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+		if (!dirStat.isDirectory() || (uid !== undefined && dirStat.uid !== uid)) return;
+
+		const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
+		const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0);
+		let fd: number;
+		try {
+			fd = fs.openSync(debugPath, flags, 0o600);
+		} catch (error) {
+			const code = filesystemErrorCode(error);
+			if (code === "EEXIST" || code === "ELOOP") return;
+			throw error;
+		}
+		try {
+			fs.writeFileSync(fd, redactTuiRenderDump(debugData));
+			fs.fchmodSync(fd, 0o600);
+		} finally {
+			fs.closeSync(fd);
+		}
+	}
+
 	#visibleWidthForDifferentialGuard(line: string): number {
 		const cached = this.#lineEmitWidthCache.get(line);
 		if (cached !== undefined) return cached;
@@ -3620,9 +3676,6 @@ export class TUI extends Container {
 		buffer += "\x1b[?2026l"; // End synchronized output
 
 		if ($pickflag("SKC_TUI_DEBUG", "PI_TUI_DEBUG")) {
-			const debugDir = "/tmp/tui";
-			fs.mkdirSync(debugDir, { recursive: true });
-			const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
 			const debugData = [
 				`firstChanged: ${firstChanged}`,
 				`viewportTop: ${viewportTop}`,
@@ -3646,7 +3699,7 @@ export class TUI extends Container {
 				"=== buffer ===",
 				JSON.stringify(buffer),
 			].join("\n");
-			fs.writeFileSync(debugPath, debugData);
+			this.#writeRenderDebugDump(debugData);
 		}
 
 		// Write entire buffer at once. Once those bytes are accepted, the painted