@sayknow-cli/tui 0.3.7 → 0.3.9

package/src/components/image.ts

@@ -1,12 +1,25 @@
 import {
 	getImageDimensions,
 	type ImageDimensions,
+	ImageProtocol,
 	imageFallback,
+	kittyImageId,
 	renderImage,
 	TERMINAL,
 } from "../terminal-capabilities";
 import type { Component } from "../tui";
 
+// Monotonic placement id allocator (kitty `p=`). Each Image instance keeps a
+// stable placement id so diff-renderer repaints replace its own placement
+// instead of stacking new copies, while two components showing identical
+// content (same image id) still coexist as distinct placements.
+let nextPlacementId = 1;
+function allocatePlacementId(): number {
+	const id = nextPlacementId;
+	nextPlacementId = nextPlacementId >= 0x7fffffff ? 1 : nextPlacementId + 1;
+	return id;
+}
+
 export interface ImageTheme {
 	fallbackColor: (str: string) => string;
 }
@@ -26,6 +39,10 @@ export class Image implements Component {
 
 	#cachedLines?: string[];
 	#cachedWidth?: number;
+	// Kitty graphics: content-derived image id + per-instance placement id.
+	// Computed lazily so non-kitty terminals never pay the hash cost.
+	#kittyImageId?: number;
+	readonly #kittyPlacementId = allocatePlacementId();
 
 	constructor(
 		base64Data: string,
@@ -57,22 +74,39 @@ 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 TUI accounts for image height
-				// First (rows-1) lines are empty (TUI clears them)
-				// Last line: move cursor back up, then output image sequence
-				lines = [];
-				for (let i = 0; i < result.rows - 1; i++) {
-					lines.push("");
+				// 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);
 				}
-				// Move cursor up to first row, then output image
-				const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
-				lines.push(moveUp + result.sequence);
 			} else {
 				const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
 				lines = [this.#theme.fallbackColor(fallback)];

package/src/components/loader.ts

@@ -1,34 +1,32 @@
+import { type AnimationRegistration, registerAnimationCallback } from "../animation-scheduler";
 import type { TUI } from "../tui";
 import { sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
-/**
- * Loader component that drives display refresh at ~60fps so callers whose
- * message colorizer is time-dependent (e.g. shimmer/KITT) animate smoothly.
- *
- * Two cadences are interleaved on a single timer:
- *   - **Recompute tick** (every `RENDER_INTERVAL_MS`) → recomposes the spinner +
- *     colorized message every 16ms. A redraw is requested only when that composed
- *     text actually changed since the last tick (`#lastDisplayed`), so animated
- *     colorizers (shimmer/KITT) and spinner-frame advances still repaint, while
- *     static loaders skip the redundant no-op render requests between advances.
- *   - **Spinner advance** (every `SPINNER_ADVANCE_MS`) → bumps the spinner
- *     frame index. Decoupled from the recompute cadence so the spinner keeps
- *     its classic ~12.5fps step pace regardless of shimmer state.
- *
- * The animation timer is `unref`'d so an active loader never keeps the event
- * loop alive on its own.
- */
-const RENDER_INTERVAL_MS = 16;
 const SPINNER_ADVANCE_MS = 80;
 
+export interface LoaderOptions {
+	timeDependentColor?: boolean;
+}
+
+/** Test-only performance counters for advisory baseline tests. */
+export const __loaderPerfCounters = {
+	liveIntervals: 0,
+	startedIntervals: 0,
+	reset(): void {
+		this.liveIntervals = 0;
+		this.startedIntervals = 0;
+	},
+};
+
 export class Loader extends Text {
 	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	#currentFrame = 0;
-	#intervalId?: NodeJS.Timeout;
+	#animation?: AnimationRegistration;
 	#ui: TUI | null = null;
 	#lastSpinnerTick = 0;
 	#lastDisplayed?: string;
+	#timeDependentColor: boolean;
 
 	constructor(
 		ui: TUI,
@@ -36,9 +34,11 @@ export class Loader extends Text {
 		private messageColorFn: (str: string) => string,
 		private message: string = "Loading...",
 		spinnerFrames?: string[],
+		options: LoaderOptions = {},
 	) {
 		super("", 1, 0);
 		this.#ui = ui;
+		this.#timeDependentColor = options.timeDependentColor ?? false;
 		if (spinnerFrames && spinnerFrames.length > 0) {
 			this.#frames = spinnerFrames;
 		}
@@ -57,24 +57,28 @@ export class Loader extends Text {
 	}
 
 	start() {
+		if (this.#animation) return;
 		this.#lastSpinnerTick = performance.now();
 		this.#updateDisplay();
-		this.#intervalId = setInterval(() => {
-			const now = performance.now();
-			if (now - this.#lastSpinnerTick >= SPINNER_ADVANCE_MS) {
-				this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
-				this.#lastSpinnerTick = now;
-			}
-			this.#updateDisplay();
-		}, RENDER_INTERVAL_MS);
-		// Don't let the animation timer keep the event loop alive on its own.
-		this.#intervalId?.unref?.();
+		__loaderPerfCounters.liveIntervals += 1;
+		__loaderPerfCounters.startedIntervals += 1;
+		this.#animation = registerAnimationCallback(
+			now => {
+				if (now - this.#lastSpinnerTick >= SPINNER_ADVANCE_MS) {
+					this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
+					this.#lastSpinnerTick = now;
+				}
+				this.#updateDisplay();
+			},
+			this.#timeDependentColor ? 16 : 80,
+		);
 	}
 
 	stop() {
-		if (this.#intervalId) {
-			clearInterval(this.#intervalId);
-			this.#intervalId = undefined;
+		if (this.#animation) {
+			this.#animation.unregister();
+			__loaderPerfCounters.liveIntervals = Math.max(0, __loaderPerfCounters.liveIntervals - 1);
+			this.#animation = undefined;
 		}
 	}
 
@@ -90,11 +94,6 @@ export class Loader extends Text {
 	#updateDisplay() {
 		const frame = this.#frames[this.#currentFrame];
 		const next = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
-		// Only touch the component and ask the TUI to repaint when the rendered
-		// text actually changed. Time-dependent colorizers (shimmer/KITT) produce
-		// new text every tick and still animate; static loaders skip the ~16ms
-		// no-op render requests between 80ms spinner advances. Output is unchanged
-		// because a suppressed frame would have produced a no-op write anyway.
 		if (next === this.#lastDisplayed) return;
 		this.#lastDisplayed = next;
 		this.setText(next);

package/src/components/markdown.ts

@@ -42,6 +42,13 @@ const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
 const renderCache = new LRUCache<string, { source: string; lines: string[] }>({ max: RENDER_CACHE_MAX });
 const PARSE_CACHE_MAX = 128;
 const parseCache = new LRUCache<string, { source: string; tokens: Token[] }>({ max: PARSE_CACHE_MAX });
+const MARKDOWN_STREAM_THROTTLE_MS = 64;
+let markdownNow = (): number => performance.now();
+
+/** Test-only clock seam for streaming throttle tests. */
+export function __setMarkdownNowForTest(now: (() => number) | undefined): void {
+	markdownNow = now ?? (() => performance.now());
+}
 
 // Per-code-block highlight cache (F3): keyed by theme + lang + code so streaming
 // appends only highlight new/changed blocks instead of re-highlighting the whole
@@ -61,6 +68,16 @@ export function resetMarkdownHighlightCallCount(): void {
 	highlightCallCount = 0;
 }
 
+/** Test-only performance counters for advisory baseline tests. */
+export const __markdownPerfCounters = {
+	lexerInvocations: 0,
+	lexedBytes: 0,
+	reset(): void {
+		this.lexerInvocations = 0;
+		this.lexedBytes = 0;
+	},
+};
+
 // Full-content 64-bit wyhash over every byte (no lossy sampling). Cache hits
 // additionally verify entry.source against the normalized text, so even a
 // hash collision can never return another message's render.
@@ -178,6 +195,11 @@ export class Markdown implements Component {
 	#cachedWidth?: number;
 	#cachedLines?: string[];
 
+	#streaming = false;
+	#lastFullParseAt = 0;
+	#onStaleThrottle?: () => void;
+	#staleThrottleTimer?: ReturnType<typeof setTimeout>;
+
 	constructor(
 		text: string,
 		paddingX: number,
@@ -194,11 +216,55 @@ export class Markdown implements Component {
 		this.#codeBlockIndent = Math.max(0, Math.floor(codeBlockIndent));
 	}
 
-	setText(text: string): void {
+	setOnStaleThrottle(callback: (() => void) | undefined): void {
+		this.#onStaleThrottle = callback;
+	}
+
+	setText(text: string, options?: { streaming?: boolean }): void {
+		if (options?.streaming !== undefined) {
+			this.setStreaming(options.streaming);
+		}
 		this.#text = text;
+		if (this.#streaming) {
+			return;
+		}
 		this.invalidate();
 	}
 
+	setStreaming(streaming: boolean): void {
+		if (this.#streaming === streaming) return;
+		this.#streaming = streaming;
+		if (!streaming) {
+			this.#clearStaleThrottleTimer();
+			this.#lastFullParseAt = 0;
+			this.invalidate();
+		}
+	}
+
+	#clearStaleThrottleTimer(): void {
+		if (!this.#staleThrottleTimer) return;
+		clearTimeout(this.#staleThrottleTimer);
+		this.#staleThrottleTimer = undefined;
+	}
+
+	#armStaleThrottleTimer(remainingMs: number): void {
+		if (!this.#onStaleThrottle || this.#staleThrottleTimer || this.#cachedText === this.#text) return;
+		this.#staleThrottleTimer = setTimeout(
+			() => {
+				this.#staleThrottleTimer = undefined;
+				if (this.#streaming && this.#cachedText !== this.#text) {
+					this.#onStaleThrottle?.();
+				}
+			},
+			Math.max(0, remainingMs),
+		);
+		this.#staleThrottleTimer.unref?.();
+	}
+
+	dispose(): void {
+		this.#clearStaleThrottleTimer();
+	}
+
 	invalidate(): void {
 		this.#cachedText = undefined;
 		this.#cachedWidth = undefined;
@@ -256,6 +322,14 @@ export class Markdown implements Component {
 		// Calculate available width for content (subtract horizontal padding)
 		const contentWidth = Math.max(1, width - this.#paddingX * 2);
 
+		if (this.#streaming && this.#cachedLines && this.#cachedWidth === width && this.#lastFullParseAt > 0) {
+			const elapsedMs = markdownNow() - this.#lastFullParseAt;
+			if (elapsedMs < MARKDOWN_STREAM_THROTTLE_MS) {
+				this.#armStaleThrottleTimer(MARKDOWN_STREAM_THROTTLE_MS - elapsedMs);
+				return this.#cachedLines;
+			}
+		}
+
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
 			const result: string[] = [];
@@ -268,7 +342,7 @@ export class Markdown implements Component {
 
 		// Replace tabs with 3 spaces for consistent rendering
 		const normalizedText = replaceTabs(this.#text);
-
+		this.#clearStaleThrottleTimer();
 		const contentKey = markdownContentKey(normalizedText);
 
 		// L2: module-level LRU — survives component disposal/recreation across
@@ -296,6 +370,8 @@ export class Markdown implements Component {
 		if (cachedParse !== undefined && cachedParse.source === normalizedText) {
 			tokens = cachedParse.tokens;
 		} else {
+			__markdownPerfCounters.lexerInvocations += 1;
+			__markdownPerfCounters.lexedBytes += normalizedText.length;
 			tokens = markdownParser.lexer(normalizedText);
 			parseCache.set(contentKey, { source: normalizedText, tokens });
 		}
@@ -361,6 +437,7 @@ export class Markdown implements Component {
 		this.#cachedText = this.#text;
 		this.#cachedWidth = width;
 		this.#cachedLines = result;
+		this.#lastFullParseAt = markdownNow();
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.

package/src/components/settings-list.ts

@@ -213,9 +213,11 @@ export class SettingsList implements Component {
 
 	#closeSubmenu(): void {
 		this.#submenuComponent = null;
-		// Restore selection to the item that opened the submenu
+		// Restore selection to the item that opened the submenu, clamped against
+		// the current list because callers may replace items while the submenu is open.
 		if (this.#submenuItemIndex !== null) {
-			this.#selectedIndex = this.#submenuItemIndex;
+			this.#selectedIndex =
+				this.#items.length === 0 ? 0 : Math.min(this.#submenuItemIndex, Math.max(0, this.#items.length - 1));
 			this.#submenuItemIndex = null;
 			this.#notifySelectionChange();
 		}

package/src/index.ts

@@ -1,5 +1,6 @@
 // Core TUI interfaces and classes
 
+export * from "./animation-scheduler";
 // Autocomplete support
 export * from "./autocomplete";
 // Components

package/src/stdin-buffer.ts

@@ -24,6 +24,39 @@ const ESC = "\x1b";
 const BRACKETED_PASTE_START = "\x1b[200~";
 const BRACKETED_PASTE_END = "\x1b[201~";
 
+function isUtf8LeadByte(byte: number): boolean {
+	return byte >= 0xc2 && byte <= 0xf4;
+}
+
+function endsWithIncompleteUtf8Sequence(data: Buffer): boolean {
+	if (data.length === 0) return false;
+
+	let index = data.length - 1;
+	let continuationCount = 0;
+	while (index >= 0) {
+		const byte = data[index]!;
+		if (byte < 0x80 || byte > 0xbf) break;
+		continuationCount++;
+		index--;
+	}
+
+	if (index < 0) {
+		return continuationCount > 0;
+	}
+
+	const lead = data[index]!;
+	let expectedLength = 0;
+	if (lead >= 0xc2 && lead <= 0xdf) expectedLength = 2;
+	else if (lead >= 0xe0 && lead <= 0xef) expectedLength = 3;
+	else if (lead >= 0xf0 && lead <= 0xf4) expectedLength = 4;
+
+	return expectedLength > 0 && continuationCount + 1 < expectedLength;
+}
+
+function legacyMetaSequence(byte: number): string {
+	return `\x1b${String.fromCharCode(byte - 128)}`;
+}
+
 /**
  * Check if a string is a complete escape sequence or needs more data
  */
@@ -268,6 +301,8 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	// split across two stdin events) reassemble correctly instead of emitting
 	// U+FFFD. Reset on clear()/destroy(); never finalized on normal flush.
 	#decoder = new StringDecoder("utf8");
+	#decoderHasPendingUtf8 = false;
+	#pendingSingleUtf8LeadByte: number | undefined;
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
@@ -286,22 +321,51 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		let str: string;
 		let decodedFromBuffer = false;
 		if (Buffer.isBuffer(data)) {
-			// Legacy 8-bit meta: an isolated high byte (0x80-0xFF) is treated
-			// as ESC + (byte - 128) for Alt/meta compatibility, BEFORE UTF-8
-			// decoding. This is the one documented exception to UTF-8 boundary
-			// decoding — a lone high byte that is also a valid UTF-8 lead byte
-			// is still read as meta — so such a byte is never fed to the decoder.
-			if (data.length === 1 && data[0]! > 127) {
-				const byte = data[0]! - 128;
-				str = `\x1b${String.fromCharCode(byte)}`;
+			let bytes = data;
+			const hadPendingUtf8 = this.#decoderHasPendingUtf8 || this.#pendingSingleUtf8LeadByte !== undefined;
+
+			if (this.#pendingSingleUtf8LeadByte !== undefined) {
+				const nextByte = data[0];
+				if (nextByte !== undefined && nextByte >= 0x80 && nextByte <= 0xbf) {
+					bytes = Buffer.concat([Buffer.from([this.#pendingSingleUtf8LeadByte]), data]);
+					this.#pendingSingleUtf8LeadByte = undefined;
+				} else {
+					const pendingMeta = this.#consumePendingSingleUtf8LeadAsMeta();
+					if (pendingMeta !== undefined) {
+						this.#emitDataSequence(pendingMeta);
+					}
+				}
+			}
+
+			if (bytes.length === 1 && bytes[0]! > 127 && !this.#decoderHasPendingUtf8) {
+				const byte = bytes[0]!;
+				if (isUtf8LeadByte(byte)) {
+					this.#pendingSingleUtf8LeadByte = byte;
+					this.#decoderHasPendingUtf8 = true;
+					this.#timeout = setTimeout(() => {
+						const sequence = this.#consumePendingSingleUtf8LeadAsMeta();
+						if (sequence !== undefined) {
+							this.#emitDataSequence(sequence);
+						}
+					}, this.#timeoutMs);
+					return;
+				}
+				str = legacyMetaSequence(byte);
 			} else {
 				// Decode through the persistent StringDecoder so a multi-byte
 				// sequence split across chunks (e.g. a 3-byte Korean syllable)
 				// is reassembled instead of emitting U+FFFD.
-				str = this.#decoder.write(data);
+				str = this.#decoder.write(bytes);
 				decodedFromBuffer = true;
+				const allContinuationBytes = bytes.every(byte => byte >= 0x80 && byte <= 0xbf);
+				this.#decoderHasPendingUtf8 =
+					endsWithIncompleteUtf8Sequence(bytes) && !(hadPendingUtf8 && str.length > 0 && allContinuationBytes);
 			}
 		} else {
+			const pendingMeta = this.#consumePendingSingleUtf8LeadAsMeta();
+			if (pendingMeta !== undefined) {
+				this.#emitDataSequence(pendingMeta);
+			}
 			str = data;
 		}
 
@@ -348,6 +412,9 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 				for (const sequence of result.sequences) {
 					this.#emitDataSequence(sequence);
 				}
+				if (result.remainder.length > 0) {
+					this.#emitDataSequence(result.remainder);
+				}
 			}
 
 			this.#pendingKittyPrintableCodepoint = undefined;
@@ -392,6 +459,13 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		}
 	}
 
+	#consumePendingSingleUtf8LeadAsMeta(): string | undefined {
+		const byte = this.#pendingSingleUtf8LeadByte;
+		if (byte === undefined) return undefined;
+		this.#pendingSingleUtf8LeadByte = undefined;
+		this.#decoderHasPendingUtf8 = false;
+		return legacyMetaSequence(byte);
+	}
 	#emitDataSequence(sequence: string): void {
 		const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
 		if (rawCodepoint !== undefined && rawCodepoint === this.#pendingKittyPrintableCodepoint) {
@@ -409,11 +483,13 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			this.#timeout = undefined;
 		}
 
+		const pendingMeta = this.#consumePendingSingleUtf8LeadAsMeta();
+
 		if (this.#buffer.length === 0) {
-			return [];
+			return pendingMeta === undefined ? [] : [pendingMeta];
 		}
 
-		const sequences = [this.#buffer];
+		const sequences = pendingMeta === undefined ? [this.#buffer] : [pendingMeta, this.#buffer];
 		this.#buffer = "";
 		this.#pendingKittyPrintableCodepoint = undefined;
 		return sequences;
@@ -432,6 +508,8 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		// stale partial prefix cannot combine with future input. destroy()
 		// resets the decoder by calling clear().
 		this.#decoder = new StringDecoder("utf8");
+		this.#decoderHasPendingUtf8 = false;
+		this.#pendingSingleUtf8LeadByte = undefined;
 	}
 
 	getBuffer(): string {