@gajae-code/tui 0.18.10 → 0.18.12

package/src/components/markdown.ts

@@ -1,5 +1,6 @@
 import { LRUCache } from "lru-cache/raw";
 import { Marked, marked, type Token, Tokenizer, type Tokens } from "marked";
+import { hasSvgFence, isClosedSvgFence } from "../chat/svg-source";
 import type { SymbolTheme } from "../symbols";
 import { TERMINAL } from "../terminal-capabilities";
 import type { Component } from "../tui";
@@ -327,10 +328,12 @@ export function resetMarkdownHighlightCallCount(): void {
 export const __markdownPerfCounters = {
 	lexerInvocations: 0,
 	lexedBytes: 0,
+	svgFenceDetectionCalls: 0,
 	highlightAdmissionScans: 0,
 	reset(): void {
 		this.lexerInvocations = 0;
 		this.lexedBytes = 0;
+		this.svgFenceDetectionCalls = 0;
 		this.highlightAdmissionScans = 0;
 	},
 };
@@ -420,9 +423,29 @@ export interface MarkdownTheme {
 	 * Return null to fall back to fenced code rendering.
 	 */
 	resolveMermaidAscii?: (source: string) => string | null;
+	/**
+	 * Resolve an SVG figure component by fenced block source text. Components
+	 * are retained by fence order. Return null for a stable fenced-code fallback
+	 * that disposes a previous component; return undefined for a fallback that
+	 * preserves the previous component and should be retried on the next render.
+	 */
+	resolveSvgFigure?: (source: string, context: SvgFigureResolveContext) => Component | null | undefined;
 	symbols: SymbolTheme;
 }
 
+export interface SvgFigureResolveContext {
+	/** Whether the containing message is still streaming. */
+	streaming: boolean;
+	/** The individual code fence has received its closing marker. */
+	closed: boolean;
+	/** Request a repaint after the figure's asynchronous output changes. */
+	onChange: () => void;
+	/** Available render width in terminal cells. */
+	width: number;
+	/** The component previously resolved for this fence position, if any. */
+	previous?: Component;
+}
+
 interface InlineStyleContext {
 	applyText: (text: string) => string;
 	stylePrefix: string;
@@ -496,6 +519,15 @@ export class Markdown implements Component {
 	#lastFullParseAt = 0;
 	#onStaleThrottle?: () => void;
 	#staleThrottleTimer?: ReturnType<typeof setTimeout>;
+	#mayHaveDynamicSvgFigures: boolean;
+	#svgFenceDetectionPending = false;
+	#svgResolverAvailable: boolean;
+	#hasActiveDynamicSvgFigures = false;
+	#hasRetryableSvgFigureFallback = false;
+	#cachedImageProtocol: typeof TERMINAL.imageProtocol | undefined;
+	#dynamicFigures = new Map<number, Component>();
+	#nextDynamicFigureIndex = 0;
+	#disposed = false;
 
 	constructor(
 		text: string,
@@ -506,6 +538,9 @@ export class Markdown implements Component {
 		codeBlockIndent: number = 2,
 	) {
 		this.#text = text;
+		this.#svgResolverAvailable = theme.resolveSvgFigure !== undefined;
+		if (this.#svgResolverAvailable) __markdownPerfCounters.svgFenceDetectionCalls++;
+		this.#mayHaveDynamicSvgFigures = this.#svgResolverAvailable && hasSvgFence(text);
 		this.#paddingX = paddingX;
 		this.#paddingY = paddingY;
 		this.#theme = theme;
@@ -522,7 +557,23 @@ export class Markdown implements Component {
 			this.setStreaming(options.streaming);
 		}
 		if (this.#text !== text) this.#rejectedParseKey = undefined;
+		const textChanged = this.#text !== text;
 		this.#text = text;
+		const svgResolverAvailable = this.#theme.resolveSvgFigure !== undefined;
+		const svgResolverChanged = svgResolverAvailable !== this.#svgResolverAvailable;
+		this.#svgResolverAvailable = svgResolverAvailable;
+		if (!svgResolverAvailable) {
+			this.#mayHaveDynamicSvgFigures = false;
+			this.#svgFenceDetectionPending = false;
+		} else if (this.#streaming) {
+			// Streaming writes already feed the throttled lexer; don't rescan the growing
+			// document here before that parse budget gets a chance to run.
+			if (textChanged || svgResolverChanged) this.#svgFenceDetectionPending = true;
+		} else {
+			__markdownPerfCounters.svgFenceDetectionCalls++;
+			this.#mayHaveDynamicSvgFigures = hasSvgFence(text);
+			this.#svgFenceDetectionPending = false;
+		}
 		if (this.#streaming) {
 			return;
 		}
@@ -560,9 +611,11 @@ export class Markdown implements Component {
 	}
 
 	dispose(): void {
+		this.#disposed = true;
 		this.#clearStaleThrottleTimer();
 		this.#currentParse = undefined;
 		this.#rejectedParseKey = undefined;
+		this.#disposeDynamicFiguresFrom(0);
 	}
 
 	invalidate(): void {
@@ -570,6 +623,48 @@ export class Markdown implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
 		this.#cachedAnchorSpans = undefined;
+		this.#lastFullParseAt = 0;
+		this.#clearStaleThrottleTimer();
+	}
+
+	#disposeDynamicFiguresFrom(startIndex: number): void {
+		for (const [index, component] of this.#dynamicFigures) {
+			if (index < startIndex) continue;
+			this.#dynamicFigures.delete(index);
+			component.dispose?.();
+		}
+	}
+
+	#resolveDynamicFigure(source: string, closed: boolean, width: number): Component | undefined {
+		const index = this.#nextDynamicFigureIndex++;
+		const previous = this.#dynamicFigures.get(index);
+		const component = this.#theme.resolveSvgFigure?.(source, {
+			streaming: this.#streaming,
+			closed,
+			width,
+			onChange: () => {
+				if (this.#disposed) return;
+				this.invalidate();
+				this.#onStaleThrottle?.();
+			},
+			previous,
+		});
+		if (component) {
+			if (previous && previous !== component) previous.dispose?.();
+			this.#dynamicFigures.set(index, component);
+			this.#hasActiveDynamicSvgFigures = true;
+			return component;
+		}
+		if (component === undefined) {
+			this.#hasRetryableSvgFigureFallback = true;
+			if (previous) this.#dynamicFigures.set(index, previous);
+		} else if (previous) {
+			// A stable fallback no longer needs the component or any raster data it
+			// retains. A future source change can create a fresh component.
+			this.#dynamicFigures.delete(index);
+			previous.dispose?.();
+		}
+		return undefined;
 	}
 
 	#exceedsHighlightCap(code: string): boolean {
@@ -635,13 +730,19 @@ export class Markdown implements Component {
 	}
 
 	#render(width: number, includeAnchors: boolean): { lines: string[]; spans?: Array<ViewportAnchorSpan | null> } {
+		if (!this.#mayHaveDynamicSvgFigures) this.#disposeDynamicFiguresFrom(0);
+
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
 		const copyEnabled = copyAnnotationsEnabled();
 		if (
+			!this.#hasActiveDynamicSvgFigures &&
+			!this.#hasRetryableSvgFigureFallback &&
+			!this.#svgFenceDetectionPending &&
 			this.#cachedLines &&
 			this.#cachedText === this.#text &&
 			this.#cachedWidth === width &&
+			this.#cachedImageProtocol === TERMINAL.imageProtocol &&
 			this.#cachedCopyEnabled === copyEnabled &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
 		) {
@@ -652,9 +753,12 @@ export class Markdown implements Component {
 		const contentWidth = Math.max(1, width - this.#paddingX * 2);
 
 		if (
+			!this.#hasActiveDynamicSvgFigures &&
+			!this.#hasRetryableSvgFigureFallback &&
 			this.#streaming &&
 			this.#cachedLines &&
 			this.#cachedWidth === width &&
+			this.#cachedImageProtocol === TERMINAL.imageProtocol &&
 			this.#cachedCopyEnabled === copyEnabled &&
 			this.#lastFullParseAt > 0 &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
@@ -666,9 +770,15 @@ export class Markdown implements Component {
 			}
 		}
 
+		this.#hasActiveDynamicSvgFigures = false;
+		this.#hasRetryableSvgFigureFallback = false;
+
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
 			this.#currentParse = undefined;
+			this.#mayHaveDynamicSvgFigures = false;
+			this.#svgFenceDetectionPending = false;
+			this.#disposeDynamicFiguresFrom(0);
 			const result: string[] = [];
 			// Update per-instance cache
 			this.#cachedText = this.#text;
@@ -676,6 +786,7 @@ export class Markdown implements Component {
 			this.#cachedLines = result;
 			this.#cachedCopyEnabled = copyEnabled;
 			this.#cachedAnchorSpans = includeAnchors ? [] : undefined;
+			this.#cachedImageProtocol = TERMINAL.imageProtocol;
 			return { lines: result, spans: this.#cachedAnchorSpans };
 		}
 
@@ -704,6 +815,8 @@ export class Markdown implements Component {
 		const cacheKey = `${renderContentKey}\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 cached = renderCache.get(cacheKey);
 		if (
+			!this.#mayHaveDynamicSvgFigures &&
+			!this.#svgFenceDetectionPending &&
 			cached !== undefined &&
 			cached.source === renderCacheSource &&
 			(!includeAnchors || cached.anchorSpans !== undefined)
@@ -714,6 +827,7 @@ export class Markdown implements Component {
 			const lines = this.#bindCopySource(cached.lines, copyEnabled);
 			this.#cachedLines = lines;
 			this.#cachedAnchorSpans = cached.anchorSpans;
+			this.#cachedImageProtocol = TERMINAL.imageProtocol;
 			if (!this.#streaming || this.#currentParse?.source !== normalizedText) this.#currentParse = undefined;
 			return { lines, spans: cached.anchorSpans };
 		}
@@ -732,6 +846,13 @@ export class Markdown implements Component {
 			__markdownPerfCounters.lexedBytes += normalizedText.length;
 			tokens = markdownParser.lexer(normalizedText);
 		}
+		this.#mayHaveDynamicSvgFigures =
+			this.#theme.resolveSvgFigure !== undefined &&
+			tokens.some(token => {
+				if (token.type !== "code") return false;
+				return token.lang?.trim().split(/[ \t]/, 1)[0]?.toLowerCase() === "svg";
+			});
+		this.#svgFenceDetectionPending = false;
 		if (this.#streaming && this.#text === renderedText) {
 			this.#currentParse = { source: normalizedText, tokens };
 		}
@@ -778,6 +899,7 @@ export class Markdown implements Component {
 			codeSource?: string;
 		}> = [];
 		let srcOffset = 0;
+		this.#nextDynamicFigureIndex = 0;
 
 		for (let i = 0; i < tokens.length; i++) {
 			const token = tokens[i];
@@ -810,6 +932,7 @@ export class Markdown implements Component {
 					codeTexts.length > 0 && codeTexts.every(text => text !== undefined) ? codeTexts.join("\n") : undefined,
 			});
 		}
+		this.#disposeDynamicFiguresFrom(this.#nextDynamicFigureIndex);
 
 		let wrappedLines: string[];
 		let wrappedSpans: Array<ViewportAnchorSpan | null> | undefined;
@@ -1104,17 +1227,28 @@ export class Markdown implements Component {
 		}
 		if (!this.#streaming || this.#text !== renderedText) this.#currentParse = undefined;
 
-		// Update L1 per-instance cache
-		this.#cachedText = renderedText;
-		this.#cachedWidth = width;
+		// Active figures and retryable fallbacks must render again. A stable
+		// fenced-code fallback is safe in this instance's L1 cache, but possible
+		// SVG fences stay out of shared L2 because resolver state can vary by instance.
 		const copyBoundResult = this.#bindCopySource(result, copyEnabled);
-		this.#cachedLines = copyBoundResult;
-		this.#cachedAnchorSpans = anchorSpans;
-		this.#lastFullParseAt = markdownNow();
+		if (this.#hasActiveDynamicSvgFigures || this.#hasRetryableSvgFigureFallback) {
+			this.#cachedText = undefined;
+			this.#cachedWidth = undefined;
+			this.#cachedLines = undefined;
+			this.#cachedAnchorSpans = undefined;
+			this.#cachedImageProtocol = undefined;
+		} else {
+			this.#cachedText = renderedText;
+			this.#cachedWidth = width;
+			this.#cachedLines = copyBoundResult;
+			this.#cachedAnchorSpans = anchorSpans;
+			this.#cachedImageProtocol = TERMINAL.imageProtocol;
+			this.#lastFullParseAt = markdownNow();
+		}
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		if (!this.#streaming) {
+		if (!this.#streaming && !this.#mayHaveDynamicSvgFigures) {
 			renderCache.set(cacheKey, {
 				source: renderCacheSource,
 				lines: result,
@@ -1229,6 +1363,7 @@ export class Markdown implements Component {
 		nextTokenType?: string,
 		styleContext?: InlineStyleContext,
 		units?: number[],
+		allowSvgFigure = true,
 	): string[] {
 		const lines: string[] = [];
 
@@ -1278,6 +1413,22 @@ export class Markdown implements Component {
 					}
 				}
 
+				// Handle SVG figures when available. Marked keeps the complete info
+				// string in token.lang, so match its normalized language token.
+				const language = token.lang?.trim().split(/[ \t]/, 1)[0]?.toLowerCase();
+				if (allowSvgFigure && language === "svg" && this.#theme.resolveSvgFigure) {
+					const figure = this.#resolveDynamicFigure(token.text, isClosedSvgFence(token.raw), width);
+					if (figure) {
+						// SVG figures are components that render directly
+						const figureLines = figure.render(width);
+						lines.push(...figureLines);
+						if (nextTokenType && nextTokenType !== "space") {
+							lines.push("");
+						}
+						break;
+					}
+				}
+
 				const codeIndent = padding(this.#codeBlockIndent);
 				this.#emitCodeBlock(lines, token, token.text, token.lang || "", codeIndent);
 				if (nextTokenType && nextTokenType !== "space") {
@@ -1334,6 +1485,8 @@ export class Markdown implements Component {
 						quoteContentWidth,
 						nextQuoteToken?.type,
 						quoteInlineStyleContext,
+						undefined,
+						false,
 					);
 					for (let c = 0; c < childLines.length; c++) quoteLineUnit.push(i);
 					renderedQuoteLines.push(...childLines);

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 "@gajae-code/utils";
+import {
+	$flag,
+	$pickflag,
+	getDebugLogPath,
+	logger,
+	onDefaultTabWidthChange,
+	redactCrashSecrets,
+} from "@gajae-code/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -999,6 +1006,23 @@ function createPreparationCancellation(entry: RenderPreparation): () => void {
 
 function cancelNoPreparation(): void {}
 
+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));
+}
+
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -1274,6 +1298,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 {
 		if (line.length === 0) return 0;
 		const cached = this.#lineEmitWidthCache.get(line);
@@ -5240,6 +5296,7 @@ export class TUI extends Container {
 		let usedWindowNormalize = false;
 		let stitched = false;
 		let frontierSpacerLineCount = 0;
+		let strandedContractionReplay = false;
 		if (reusedAnchor !== null && layoutPrefixEligible && !layoutPrefixBlocked) {
 			const reused = this.#reuseCachedLayoutPrefix(
 				width,
@@ -5288,7 +5345,24 @@ export class TUI extends Container {
 					!transcriptRebuildPending &&
 					frontierPreviousWidth === width &&
 					(frontierPreviousHeight === height || this.#viewportRepaintHost());
-				const minimumLineCount = preserveLiveFrontier ? prevViewportTop + height : height;
+				// Padding to the committed frontier keeps scrollback rows from being
+				// repainted, but when the contraction ends the transcript at or above that
+				// frontier the padded viewport holds nothing but spacer rows. Replay the
+				// frame instead of leaving a blank screen above the pinned component. A
+				// pinned suffix that already fills the viewport hides the spacers, so it
+				// keeps the frontier and its scrollback.
+				strandedContractionReplay =
+					preserveLiveFrontier &&
+					!heightChanged &&
+					frontierPreviousHeight === height &&
+					this.overlayStack.length === 0 &&
+					prevViewportTop > 0 &&
+					sourceTranscriptLineCount > 0 &&
+					sourceTranscriptLineCount <= prevViewportTop &&
+					newLines.length < prevViewportTop + height &&
+					newLines.length - sourceTranscriptLineCount < height;
+				const minimumLineCount =
+					preserveLiveFrontier && !strandedContractionReplay ? prevViewportTop + height : height;
 				const padded = this.#padBeforeBottomPinnedComponent(
 					newLines,
 					minimumLineCount,
@@ -5873,6 +5947,14 @@ export class TUI extends Container {
 			fullRender(true, "clearOnShrink", true);
 			return;
 		}
+		// Default (clearOnShrink off) still replays when frontier padding would leave the
+		// viewport with no transcript row, e.g. a tall live block collapsing back into
+		// history. Same scrollback erase as above, for the same duplication reason.
+		if (strandedContractionReplay) {
+			logRedraw(`stranded contraction (prev=${this.#previousLines.length}, new=${newLines.length})`);
+			fullRender(true, "stranded contraction", true);
+			return;
+		}
 
 		// Find first and last changed lines
 		let firstChanged = -1;
@@ -6334,9 +6416,6 @@ export class TUI extends Container {
 		buffer = this.#frameSynchronizedOutput(buffer);
 
 		if ($pickflag("GJC_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}`,
@@ -6360,7 +6439,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