@sayknow-cli/tui 0.3.10 → 0.3.12

package/dist/types/components/image.d.ts

@@ -7,10 +7,12 @@ export interface ImageOptions {
     maxWidthCells?: number;
     maxHeightCells?: number;
     filename?: string;
+    refetch?: () => string;
 }
 export declare class Image implements Component {
     #private;
     constructor(base64Data: string, mimeType: string, theme: ImageTheme, options?: ImageOptions, dimensions?: ImageDimensions);
     invalidate(): void;
+    get retainedBase64DataForTest(): string | undefined;
     render(width: number): string[];
 }

package/dist/types/components/markdown.d.ts

@@ -13,6 +13,7 @@ export declare const __markdownPerfCounters: {
 };
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
+export declare function getRenderCacheRetainedBytes(): number;
 /**
  * Default text styling for markdown content.
  * Applied to all text unless overridden by markdown formatting.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.10",
+	"version": "0.3.12",
 	"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.3.10",
-		"@sayknow-cli/utils": "0.3.10",
+		"@sayknow-cli/natives": "0.3.12",
+		"@sayknow-cli/utils": "0.3.12",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/image.ts

@@ -28,10 +28,11 @@ export interface ImageOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	filename?: string;
+	refetch?: () => string;
 }
 
 export class Image implements Component {
-	#base64Data: string;
+	#base64Data?: string;
 	#mimeType: string;
 	#dimensions: ImageDimensions;
 	#theme: ImageTheme;
@@ -63,6 +64,22 @@ export class Image implements Component {
 		this.#cachedWidth = undefined;
 	}
 
+	get retainedBase64DataForTest(): string | undefined {
+		return this.#base64Data;
+	}
+
+	#fallbackLines(): string[] {
+		const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
+		return [this.#theme.fallbackColor(fallback)];
+	}
+
+	#getBase64Data(): string | undefined {
+		if (this.#base64Data) return this.#base64Data;
+		const refetched = this.#options.refetch?.();
+		if (refetched) this.#base64Data = refetched;
+		return this.#base64Data;
+	}
+
 	render(width: number): string[] {
 		if (this.#cachedLines && this.#cachedWidth === width) {
 			return this.#cachedLines;
@@ -74,46 +91,50 @@ export class Image implements Component {
 		let lines: string[];
 
 		if (TERMINAL.imageProtocol) {
-			if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
-				this.#kittyImageId ??= kittyImageId(this.#base64Data);
-			}
-			const result = renderImage(this.#base64Data, this.#dimensions, {
-				maxWidthCells: maxWidth,
-				maxHeightCells: this.#options.maxHeightCells,
-				imageId: this.#kittyImageId,
-				placementId: this.#kittyPlacementId,
-			});
-
-			if (result) {
-				// Return `rows` lines so the TUI accounts for the image height.
-				if (result.cursorNeutral) {
-					// Kitty a=p,C=1 placements neither move the cursor nor carry
-					// pixel data, so the escape lives on the FIRST row — the image
-					// anchors to that cell and no cursor-up trick is needed (the
-					// old CUU approach clamped at the viewport top edge and placed
-					// the image over transcript text when partially scrolled out).
-					lines = [result.sequence];
-					for (let i = 0; i < result.rows - 1; i++) {
-						lines.push("");
+			const base64Data = this.#getBase64Data();
+			if (!base64Data) {
+				lines = this.#fallbackLines();
+			} else {
+				if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+					this.#kittyImageId ??= kittyImageId(base64Data);
+				}
+				const result = renderImage(base64Data, this.#dimensions, {
+					maxWidthCells: maxWidth,
+					maxHeightCells: this.#options.maxHeightCells,
+					imageId: this.#kittyImageId,
+					placementId: this.#kittyPlacementId,
+				});
+
+				if (result) {
+					// Return `rows` lines so the TUI accounts for the image height.
+					if (result.cursorNeutral) {
+						// Kitty a=p,C=1 placements neither move the cursor nor carry
+						// pixel data, so the escape lives on the FIRST row — the image
+						// anchors to that cell and no cursor-up trick is needed (the
+						// old CUU approach clamped at the viewport top edge and placed
+						// the image over transcript text when partially scrolled out).
+						lines = [result.sequence];
+						for (let i = 0; i < result.rows - 1; i++) {
+							lines.push("");
+						}
+					} else {
+						// iTerm2/SIXEL draw at the cursor and advance it: reserve
+						// rows-1 blank lines (TUI clears them), then move the cursor
+						// up and draw from the last line.
+						lines = [];
+						for (let i = 0; i < result.rows - 1; i++) {
+							lines.push("");
+						}
+						const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
+						lines.push(moveUp + result.sequence);
 					}
+					this.#base64Data = undefined;
 				} else {
-					// iTerm2/SIXEL draw at the cursor and advance it: reserve
-					// rows-1 blank lines (TUI clears them), then move the cursor
-					// up and draw from the last line.
-					lines = [];
-					for (let i = 0; i < result.rows - 1; i++) {
-						lines.push("");
-					}
-					const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
-					lines.push(moveUp + result.sequence);
+					lines = this.#fallbackLines();
 				}
-			} else {
-				const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
-				lines = [this.#theme.fallbackColor(fallback)];
 			}
 		} else {
-			const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
-			lines = [this.#theme.fallbackColor(fallback)];
+			lines = this.#fallbackLines();
 		}
 
 		this.#cachedLines = lines;

package/src/components/markdown.ts

@@ -55,6 +55,13 @@ export function __setMarkdownNowForTest(now: (() => number) | undefined): void {
 // prefix on every chunk. Bounded LRU; cleared on theme change via clearRenderCache().
 const HIGHLIGHT_CACHE_MAX = 512;
 const highlightCache = new LRUCache<string, string[]>({ max: HIGHLIGHT_CACHE_MAX });
+
+function renderedLinesBytes(lines: readonly string[]): number {
+	let bytes = 0;
+	for (const line of lines) bytes += Buffer.byteLength(line, "utf8");
+	return bytes;
+}
+
 // F18: cap synchronous (Rust FFI) syntax highlighting so a single huge fenced block
 // cannot stall the UI thread; oversized blocks render plain with a sanitized marker.
 const MAX_HIGHLIGHT_BYTES = 200_000;
@@ -96,6 +103,17 @@ export function clearRenderCache(): void {
 	highlightCache.clear();
 }
 
+export function getRenderCacheRetainedBytes(): number {
+	let bytes = 0;
+	for (const entry of renderCache.values()) {
+		bytes += Buffer.byteLength(entry.source, "utf8");
+		bytes += renderedLinesBytes(entry.lines);
+	}
+	for (const entry of parseCache.values()) bytes += Buffer.byteLength(entry.source, "utf8");
+	for (const lines of highlightCache.values()) bytes += renderedLinesBytes(lines);
+	return bytes;
+}
+
 // Stable numeric IDs for structural theme/style objects (no ID field on type).
 // Symbol-keyed so the id travels with the object and is invisible to consumers.
 const kObjectId = Symbol("markdown.objectId");
@@ -180,6 +198,29 @@ function formatHyperlink(text: string, target: string): string {
 	return `\x1b]8;;${safeTarget}\x07${text}\x1b]8;;\x07`;
 }
 
+function stripHtmlComments(raw: string): string {
+	let result = "";
+	let index = 0;
+
+	while (index < raw.length) {
+		const start = raw.indexOf("<!--", index);
+		if (start < 0) {
+			result += raw.slice(index);
+			break;
+		}
+
+		result += raw.slice(index, start);
+		const end = raw.indexOf("-->", start + 4);
+		if (end < 0) {
+			result += raw.slice(start);
+			break;
+		}
+		index = end + 3;
+	}
+
+	return result;
+}
+
 export class Markdown implements Component {
 	#text: string;
 	#paddingX: number; // Left/right padding
@@ -654,12 +695,15 @@ export class Markdown implements Component {
 				}
 				break;
 
-			case "html":
-				// Render HTML as plain text (escaped for terminal)
-				if ("raw" in token && typeof token.raw === "string") {
-					lines.push(this.#applyDefaultStyle(token.raw.trim()));
+			case "html": {
+				// HTML comments are invisible markup (React/SSR text separators often emit "<!-- -->").
+				// Keep other HTML-like model text visible as plain terminal text.
+				const visibleHtml = "raw" in token && typeof token.raw === "string" ? stripHtmlComments(token.raw) : "";
+				if (visibleHtml.trim().length > 0) {
+					lines.push(this.#applyDefaultStyle(visibleHtml.trim()));
 				}
 				break;
+			}
 
 			case "space":
 				// Space tokens represent blank lines in markdown
@@ -745,12 +789,14 @@ export class Markdown implements Component {
 					break;
 				}
 
-				case "html":
-					// Render inline HTML as plain text
-					if ("raw" in token && typeof token.raw === "string") {
-						result += applyTextWithNewlines(token.raw);
+				case "html": {
+					// HTML comments are markup-only separators; keep other inline HTML visible as text.
+					const visibleHtml = "raw" in token && typeof token.raw === "string" ? stripHtmlComments(token.raw) : "";
+					if (visibleHtml.trim().length > 0) {
+						result += applyTextWithNewlines(visibleHtml);
 					}
 					break;
+				}
 
 				default:
 					// Handle any other inline token types as plain text
@@ -1091,6 +1137,11 @@ export function renderInlineMarkdown(text: string, mdTheme: MarkdownTheme, baseC
 					return `${applyText(prefix)}${content}`;
 				})
 				.join(applyText(" "));
+		} else if (token.type === "html" && "raw" in token && typeof token.raw === "string") {
+			const visibleHtml = stripHtmlComments(token.raw);
+			if (visibleHtml.trim().length > 0) {
+				result += applyText(visibleHtml);
+			}
 		} else if ("text" in token && typeof token.text === "string") {
 			result += applyText(token.text);
 		}
@@ -1127,6 +1178,13 @@ function renderInlineTokens(tokens: Token[], mdTheme: MarkdownTheme, applyText:
 				result += mdTheme.link(mdTheme.underline(linkText)) + styleReset;
 				break;
 			}
+			case "html": {
+				const visibleHtml = "raw" in token && typeof token.raw === "string" ? stripHtmlComments(token.raw) : "";
+				if (visibleHtml.trim().length > 0) {
+					result += applyText(visibleHtml);
+				}
+				break;
+			}
 			default:
 				if ("text" in token && typeof token.text === "string") {
 					result += applyText(token.text);

package/src/tui.ts

@@ -1616,7 +1616,7 @@ export class TUI extends Container {
 		this.#hardwareCursorRow = cursorToRow;
 		buffer += cursorSeq;
 		buffer += "\x1b[?2026l";
-		if (!this.#writeTerminal(buffer)) return false;
+		if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, lines.length)) return false;
 
 		if (this.#debugRedraw) {
 			const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (lines=${lines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
@@ -1761,7 +1761,7 @@ export class TUI extends Container {
 			this.#hardwareCursorRow = toRow;
 			buffer += seq;
 			buffer += "\x1b[?2026l"; // End synchronized output
-			if (!this.#writeTerminal(buffer)) return;
+			if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
 			// Reset max lines when clearing, otherwise track growth
 			if (clear) {
 				this.#maxLinesRendered = newLines.length;
@@ -1811,7 +1811,7 @@ export class TUI extends Container {
 			this.#hardwareCursorRow = cursorToRow;
 			buffer += cursorSeq;
 			buffer += "\x1b[?2026l";
-			if (!this.#writeTerminal(buffer)) return;
+			if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
 
 			if (this.#debugRedraw) {
 				const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (prev=${this.#previousLines.length}, new=${newLines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
@@ -1963,7 +1963,7 @@ export class TUI extends Container {
 				this.#hardwareCursorRow = toRow;
 				buffer += seq;
 				buffer += "\x1b[?2026l";
-				if (!this.#writeTerminal(buffer)) return;
+				if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
 			}
 			this.#previousLines = newLines;
 			this.#previousWidth = width;
@@ -2108,7 +2108,7 @@ export class TUI extends Container {
 		}
 
 		// Write entire buffer at once
-		if (!this.#writeTerminal(buffer)) return;
+		if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
 
 		// Track cursor position for next render.
 		// cursorRow tracks end of content (for viewport calculation).
@@ -2163,19 +2163,28 @@ export class TUI extends Container {
 		return { seq, toRow: targetRow };
 	}
 
+	#writeRenderBufferAndReanchorImeCursor(
+		buffer: string,
+		cursorPos: { row: number; col: number } | null,
+		totalLines: number,
+	): boolean {
+		if (!this.#writeTerminal(buffer)) return false;
+		if (!this.#imeCursorActive) return true;
+		return this.#writeCursorPosition(cursorPos, totalLines);
+	}
+
 	/**
 	 * Write the hardware cursor position to the terminal as a standalone
 	 * synchronized output block. Use when there is no surrounding render buffer
 	 * to embed the sequences into.
 	 */
-	#writeCursorPosition(cursorPos: { row: number; col: number } | null, totalLines: number): void {
+	#writeCursorPosition(cursorPos: { row: number; col: number } | null, totalLines: number): boolean {
 		if (!cursorPos || totalLines <= 0) {
-			this.#hideCursor();
-			return;
+			return this.#hideCursor();
 		}
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
 		this.#hardwareCursorRow = toRow;
 		// No \x1b[?2026h/l wrapper: synchronized output flushes terminal state and discards macOS IME composition.
-		this.#writeTerminal(seq);
+		return this.#writeTerminal(seq);
 	}
 }