@gajae-code/tui 0.18.11 → 0.18.12

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.18.12] - 2026-10-16
+
+### Added
+
+- Render ```svg fenced code blocks as rasterized terminal images (Kitty, iTerm2, SIXEL). SVG figures stream inline with partial source repair, theme-aware token resolution through reserved `--gjc-<palette-key>` CSS variables, and automatic fallback to plain code blocks on rasterization failure. Ported from oh-my-pi.
+
+### Fixed
+
+- TUI no longer goes blank after stop/restart cycles: `#hardwareCursorRow` is now properly reset during `stop()` to prevent stale cursor position state from corrupting viewport calculations on the next `start()`.
+
+- With `clearOnShrink` enabled, a live block that shrinks after the transcript has scrolled into history no longer leaves blank spacer rows above the pinned composer until the next resize. The contraction now clears the screen and history and replays the frame, so the viewport is filled again and no row appears twice in history.
+
+- Scrub credentials from TUI render debug dumps and write them mode 0600 beside the debug log, without following a symlink at the dump path.
+
 ## [0.18.11] - 2026-10-12
 
 ### Fixed

package/dist/types/chat/svg-figure.d.ts

@@ -0,0 +1,26 @@
+import { type ImageTheme } from "../components/image";
+import type { Component } from "../tui";
+export interface SvgFigureOptions {
+    /**
+     * Theme for rendering the image fallback text.
+     */
+    theme: ImageTheme;
+    /** CSS colors substituted for SVG theme variables and currentColor. */
+    palette: Readonly<Record<string, string>>;
+    /** The figure's rows changed outside a text update: a raster landed or rendering fell back to code. */
+    onChange: () => void;
+}
+export declare class SvgFigure implements Component {
+    #private;
+    constructor(options: SvgFigureOptions);
+    /** Feed the fence body; `final` stops streaming, while `closed` records its closing marker. */
+    update(source: string, final: boolean, closed: boolean, palette?: Readonly<Record<string, string>>): void;
+    render(width: number): string[];
+    invalidate(): void;
+    dispose(): void;
+    debugState(): Record<string, unknown>;
+    get pending(): boolean;
+    get failed(): boolean;
+    /** Whether this failure may recover when terminal raster limits change. */
+    get retryable(): boolean;
+}

package/dist/types/chat/svg-source.d.ts

@@ -0,0 +1,32 @@
+/** One run of an assistant text block: prose, or the body of a ```svg fence. */
+export type FigureSegment = {
+    readonly kind: "markdown";
+    readonly text: string;
+}
+/** `closed` once the fence's closing line arrived. */
+ | {
+    readonly kind: "svg";
+    readonly source: string;
+    readonly closed: boolean;
+};
+/** Whether `markdown` holds a ```svg fence {@link splitSvgFences} would lift. */
+export declare function hasSvgFence(markdown: string): boolean;
+/**
+ * Split `markdown` into prose and ```svg fence bodies, in order. Only
+ * top-level fences lift; an svg fence nested in another fence, a list's
+ * indented block or a blockquote stays prose. Blank prose runs are dropped.
+ * An svg fence still open at the end is the last segment, `closed: false`.
+ */
+export declare function splitSvgFences(markdown: string): FigureSegment[];
+/** Whether a Marked SVG code token's raw source contains its closing fence. */
+export declare function isClosedSvgFence(raw: string): boolean;
+/**
+ * Turn a possibly truncated SVG source into a well-formed document: cut the
+ * trailing construct still being written (a tag without its `>`, an
+ * unterminated comment, CDATA section, processing instruction or declaration,
+ * a dangling `&entity`) and close every element left open, innermost first.
+ * A complete document passes through unchanged. Returns null until the root
+ * `<svg …>` start tag is complete — before that there is nothing to draw.
+ */
+export declare function closePartialSvg(source: string): string | null;
+export declare function prepareSvg(svg: string, palette: Readonly<Record<string, string>>): string;

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

@@ -21,6 +21,7 @@ export declare function resetMarkdownHighlightCallCount(): void;
 export declare const __markdownPerfCounters: {
     lexerInvocations: number;
     lexedBytes: number;
+    svgFenceDetectionCalls: number;
     highlightAdmissionScans: number;
     reset(): void;
 };
@@ -74,8 +75,27 @@ 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;
+}
 export declare class Markdown implements Component {
     #private;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.18.11",
+	"version": "0.18.12",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.18.11",
-		"@gajae-code/utils": "0.18.11",
+		"@gajae-code/natives": "0.18.12",
+		"@gajae-code/utils": "0.18.12",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/chat/svg-figure.ts

@@ -0,0 +1,405 @@
+/**
+ * A ```svg fence drawn as an inline terminal image. The source is rasterized
+ * off the JS thread and shown through {@link Image}; while the fence streams,
+ * each throttled revision repairs the partial source and replaces the
+ * previous raster, which stays on screen until the next one lands.
+ *
+ * Sizing is natural rather than preview-capped: the figure takes as many columns as its
+ * drawing needs — up to the full width, and a viewport-relative height. The
+ * raster is drawn at the terminal's device pixels per unit, padded to whole
+ * cells, and redrawn when the room it is shown in changes, so the terminal
+ * places it 1:1: any resampling, even 0.99×, blurs every glyph edge.
+ *
+ * Source: oh-my-pi (https://github.com/can1357/oh-my-pi)
+ */
+import type { rasterizeSvg as rasterizeSvgFn } from "@gajae-code/natives";
+import { logger } from "@gajae-code/utils";
+import { Image, type ImageTheme } from "../components/image";
+import { type CellDimensions, getCellDimensions, getImageDimensions, TERMINAL } from "../terminal-capabilities";
+import type { Component } from "../tui";
+import { closePartialSvg, prepareSvg } from "./svg-source";
+
+type NativeRasterizeSvg = typeof rasterizeSvgFn;
+let nativeRasterizeSvg: NativeRasterizeSvg | undefined;
+
+function rasterizeSvg(
+	input: Uint8Array,
+	maxWidthPx: number,
+	maxHeightPx: number,
+	cellWidthPx: number,
+	cellHeightPx: number,
+): Promise<Uint8Array> {
+	nativeRasterizeSvg ??= (require("@gajae-code/natives") as { rasterizeSvg: NativeRasterizeSvg }).rasterizeSvg;
+	return nativeRasterizeSvg(input, maxWidthPx, maxHeightPx, cellWidthPx, cellHeightPx);
+}
+
+/** Least time between rasters of a fence that is still streaming. */
+const STREAM_INTERVAL_MS = 200;
+/** Longest raster edge; the native rasterizer caps the surface at 4096² pixels. */
+const MAX_EDGE_PX = 4096;
+/** Share of the terminal's rows one figure may fill, so it fits on screen whole. */
+const MAX_VIEWPORT_SHARE = 0.8;
+
+/** Cells a figure may fill. */
+interface Limits {
+	columns: number;
+	rows: number;
+}
+
+/** One rasterized revision and the inputs that produced it. */
+interface Raster {
+	source: string;
+	/** Cell size the raster was padded to; its pixels are whole cells of it. */
+	cell: CellDimensions;
+	limits: Limits;
+	/** Base64 PNG. */
+	data: string;
+	widthPx: number;
+	heightPx: number;
+}
+
+/** Inputs of a raster attempt, successful or not. */
+interface Attempt {
+	source: string;
+	palette: Readonly<Record<string, string>>;
+	cell: CellDimensions;
+	limits: Limits;
+	final: boolean;
+	closed: boolean;
+}
+
+interface Layout {
+	width: number;
+	cell: CellDimensions;
+	limits: Limits;
+}
+
+/** Cells a figure rendered at `width` may fill: the image's width, a share of the viewport, and the raster edge cap. */
+function limitsFor(width: number, cell: CellDimensions): Limits {
+	const viewportRows = Math.floor((process.stdout.rows || 24) * MAX_VIEWPORT_SHARE);
+	return {
+		columns: Math.max(1, Math.min(Math.max(1, width - 2), Math.floor(MAX_EDGE_PX / cell.widthPx))),
+		rows: Math.max(1, Math.min(viewportRows, Math.floor(MAX_EDGE_PX / cell.heightPx))),
+	};
+}
+
+export interface SvgFigureOptions {
+	/**
+	 * Theme for rendering the image fallback text.
+	 */
+	theme: ImageTheme;
+	/** CSS colors substituted for SVG theme variables and currentColor. */
+	palette: Readonly<Record<string, string>>;
+	/** The figure's rows changed outside a text update: a raster landed or rendering fell back to code. */
+	onChange: () => void;
+}
+
+export class SvgFigure implements Component {
+	readonly #options: SvgFigureOptions;
+	#palette: Readonly<Record<string, string>>;
+	#source = "";
+	/** No more text arrives for this fence: no throttling, and a failed raster falls back to code. */
+	#final = false;
+	/** Whether the fence had its closing marker; only open fences are repaired. */
+	#closed = false;
+	#raster: Raster | undefined;
+	#attempt: Attempt | undefined;
+	/** Final source that could not be drawn; rendered as plaintext. */
+	#failed: string | undefined;
+	/** Whether retrying the failed source at different pixel limits could succeed. */
+	#failedLayoutDependent = false;
+	#rasterizing = false;
+	#startedAt = Number.NEGATIVE_INFINITY;
+	#timer: NodeJS.Timeout | undefined;
+	/** A {@link #schedule} is queued for the end of the current task. */
+	#queued = false;
+	#disposed = false;
+	/** Last render width; rasters wait for the first render to know their room. */
+	#width: number | undefined;
+	#layout: Layout | undefined;
+	#image: { raster: Raster; cell: CellDimensions; columns: number; rows: number; component: Image } | undefined;
+	#graphicsUnavailableNotified = false;
+
+	constructor(options: SvgFigureOptions) {
+		this.#options = options;
+		this.#palette = options.palette;
+	}
+
+	/** Feed the fence body; `final` stops streaming, while `closed` records its closing marker. */
+	update(source: string, final: boolean, closed: boolean, palette = this.#palette): void {
+		const sourceChanged = source !== this.#source;
+		const paletteChanged = palette !== this.#palette;
+		const closedChanged = closed !== this.#closed;
+		if (!sourceChanged && !paletteChanged && final === this.#final && !closedChanged) return;
+		if (sourceChanged || paletteChanged || closedChanged) {
+			this.#failed = undefined;
+			this.#failedLayoutDependent = false;
+		}
+		this.#source = source;
+		this.#final = final;
+		this.#closed = closed;
+		this.#palette = palette;
+		// Deferred: a block built mid-stream is marked streaming right after it
+		// is mounted, when render() was called already (e.g. by diffing); a
+		// schedule() queued before then is dropped, so the next render() starts
+		// a new one.
+		if (!this.#queued) {
+			this.#queued = true;
+			queueMicrotask(() => {
+				this.#queued = false;
+				this.#schedule();
+			});
+		}
+	}
+
+	render(width: number): string[] {
+		if (!TERMINAL.imageProtocol) {
+			clearTimeout(this.#timer);
+			this.#timer = undefined;
+			if (!this.#graphicsUnavailableNotified) {
+				this.#graphicsUnavailableNotified = true;
+				this.#options.onChange();
+			}
+			return [];
+		}
+		// Source updates may arrive while graphics are unavailable, so a restored
+		// protocol must retry even when the visible layout did not change.
+		const graphicsRestored = this.#graphicsUnavailableNotified;
+		this.#graphicsUnavailableNotified = false;
+		const cell = getCellDimensions();
+		const limits = limitsFor(width, cell);
+		const previousLayout = this.#layout;
+		const cellChanged =
+			previousLayout?.cell.widthPx !== cell.widthPx || previousLayout.cell.heightPx !== cell.heightPx;
+		const layoutChanged =
+			previousLayout === undefined ||
+			previousLayout.width !== width ||
+			cellChanged ||
+			previousLayout.limits.columns !== limits.columns ||
+			previousLayout.limits.rows !== limits.rows;
+		if (layoutChanged) {
+			this.#width = width;
+			this.#layout = { width, cell, limits };
+			if (cellChanged) this.#image?.component.invalidate();
+			this.#schedule();
+		}
+		if (graphicsRestored && !layoutChanged) this.#schedule();
+		if (!this.#raster && !this.#failed) return [];
+		if (this.failed) return [];
+		if (this.#raster) {
+			const image = this.#imageFor(this.#raster, limits, cell);
+			return image.render(width);
+		}
+		return [];
+	}
+
+	invalidate(): void {
+		this.#image?.component.invalidate();
+	}
+
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		clearTimeout(this.#timer);
+		this.#timer = undefined;
+		this.#source = "";
+		this.#attempt = undefined;
+		this.#raster = undefined;
+		this.#failed = undefined;
+		this.#failedLayoutDependent = false;
+		this.#layout = undefined;
+		this.#width = undefined;
+		this.#image = undefined;
+	}
+
+	debugState(): Record<string, unknown> {
+		return {
+			final: this.#final,
+			failed: this.#failed === this.#source,
+			raster: this.#raster ? `${this.#raster.widthPx}x${this.#raster.heightPx}` : null,
+			current: this.#raster?.source === this.#source,
+		};
+	}
+
+	/** Whether the current source and cell size have not been attempted yet. */
+	#stale(width: number): boolean {
+		const attempt = this.#attempt;
+		const cell = getCellDimensions();
+		const limits = limitsFor(width, cell);
+		if (this.#failed === this.#source) {
+			if (!this.#failedLayoutDependent || !attempt) return false;
+			return (
+				attempt.cell.widthPx !== cell.widthPx ||
+				attempt.cell.heightPx !== cell.heightPx ||
+				attempt.limits.columns !== limits.columns ||
+				attempt.limits.rows !== limits.rows
+			);
+		}
+		return (
+			attempt === undefined ||
+			attempt.source !== this.#source ||
+			attempt.palette !== this.#palette ||
+			attempt.closed !== this.#closed ||
+			attempt.cell.widthPx !== cell.widthPx ||
+			attempt.cell.heightPx !== cell.heightPx ||
+			// A streaming attempt that failed is retried once as final.
+			(this.#final && !attempt.final && this.#raster?.source !== this.#source) ||
+			((attempt.limits.columns !== limits.columns || attempt.limits.rows !== limits.rows) && this.#outgrown(limits))
+		);
+	}
+
+	/**
+	 * Whether the current raster would come out differently in `limits`. One
+	 * below both of its limits drew at its natural size and redraws only once
+	 * it no longer fits; one that filled a limit redraws whenever they change.
+	 */
+	#outgrown(limits: Limits): boolean {
+		const raster = this.#raster;
+		if (raster?.source !== this.#source) return false;
+		const columns = raster.widthPx / raster.cell.widthPx;
+		const rows = raster.heightPx / raster.cell.heightPx;
+		if (columns < raster.limits.columns && rows < raster.limits.rows) {
+			return columns > limits.columns || rows > limits.rows;
+		}
+		return raster.limits.columns !== limits.columns || raster.limits.rows !== limits.rows;
+	}
+
+	/** Start a raster when one is due: single-flight, throttled while streaming, immediate once final. */
+	#schedule(): void {
+		const width = this.#width;
+		if (this.#disposed || !TERMINAL.imageProtocol || this.#rasterizing || width === undefined) return;
+		if (this.#final && this.#timer) {
+			clearTimeout(this.#timer);
+			this.#timer = undefined;
+		}
+		if (this.#timer || !this.#stale(width)) return;
+		const wait = this.#final ? 0 : this.#startedAt + STREAM_INTERVAL_MS - performance.now();
+		if (wait > 0) {
+			this.#timer = setTimeout(() => {
+				this.#timer = undefined;
+				this.#schedule();
+			}, wait);
+			this.#timer.unref?.();
+			return;
+		}
+		void this.#rasterize(width);
+	}
+
+	async #rasterize(width: number): Promise<void> {
+		const cell = getCellDimensions();
+		const attempt: Attempt = {
+			source: this.#source,
+			palette: this.#palette,
+			cell,
+			limits: limitsFor(width, cell),
+			final: this.#final,
+			closed: this.#closed,
+		};
+		this.#attempt = attempt;
+		const svg = attempt.closed ? attempt.source : closePartialSvg(attempt.source);
+		let png: Uint8Array | undefined;
+		let layoutDependentFailure = false;
+		if (svg !== null) {
+			this.#rasterizing = true;
+			this.#startedAt = performance.now();
+			try {
+				const prepared = prepareSvg(svg, attempt.palette);
+				try {
+					png = await rasterizeSvg(
+						new TextEncoder().encode(prepared),
+						attempt.limits.columns * cell.widthPx,
+						attempt.limits.rows * cell.heightPx,
+						cell.widthPx,
+						cell.heightPx,
+					);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					layoutDependentFailure = !message.includes("Failed to parse SVG:");
+					throw error;
+				}
+			} catch (error) {
+				// A streaming prefix that does not parse yet keeps the previous raster.
+				if (attempt.final) logger.debug("SVG figure did not render", { error: String(error) });
+			} finally {
+				this.#rasterizing = false;
+			}
+		}
+		if (this.#disposed) return;
+		const data = png ? Buffer.from(png).toString("base64") : undefined;
+		const size = data ? getImageDimensions(data, "image/png") : null;
+		if (data && size) {
+			this.#show(attempt, data, size.widthPx, size.heightPx);
+		} else if (
+			attempt.final &&
+			attempt.source === this.#source &&
+			attempt.palette === this.#palette &&
+			attempt.closed === this.#closed
+		) {
+			this.#failed = attempt.source;
+			this.#failedLayoutDependent = layoutDependentFailure;
+			// Clear the raster and image on terminal failure to keep preview only while a replacement is in flight.
+			this.#raster = undefined;
+			this.#image = undefined;
+			this.#options.onChange();
+		}
+		// The source, cell size, or room moved on while this raster ran.
+		this.#schedule();
+	}
+
+	#show(attempt: Attempt, data: string, widthPx: number, heightPx: number): void {
+		if (this.#failed === attempt.source) {
+			this.#failed = undefined;
+			this.#failedLayoutDependent = false;
+		}
+		this.#raster = {
+			source: attempt.source,
+			cell: attempt.cell,
+			limits: attempt.limits,
+			data,
+			widthPx,
+			heightPx,
+		};
+		this.#options.onChange();
+	}
+
+	/**
+	 * The image for `raster` over the whole cells it was padded to. At the
+	 * cell size and room it was drawn for that box is its pixels exactly; a
+	 * raster outdated by a resize is scaled by {@link Image} until its redraw lands.
+	 */
+	#imageFor(raster: Raster, limits: Limits, cell: CellDimensions): Image {
+		const current = this.#image;
+		const columns = Math.min(limits.columns, Math.ceil(raster.widthPx / cell.widthPx));
+		const rows = Math.min(limits.rows, Math.ceil(raster.heightPx / cell.heightPx));
+		if (
+			current?.raster === raster &&
+			current.cell.widthPx === cell.widthPx &&
+			current.cell.heightPx === cell.heightPx &&
+			current.columns === columns &&
+			current.rows === rows
+		) {
+			return current.component;
+		}
+		const component = new Image(raster.data, "image/png", this.#options.theme, {
+			maxWidthCells: columns,
+			maxHeightCells: rows,
+			filename: "svg",
+			refetch: () => raster.data,
+		});
+		this.#image = { raster, cell, columns, rows, component };
+		return component;
+	}
+
+	get pending(): boolean {
+		return this.#rasterizing || (this.#final === false && this.#raster === undefined && this.#failed === undefined);
+	}
+
+	get failed(): boolean {
+		return this.#failed === this.#source;
+	}
+
+	/** Whether this failure may recover when terminal raster limits change. */
+	get retryable(): boolean {
+		return this.failed && this.#failedLayoutDependent;
+	}
+}