@prometheus-ai/tui 0.5.3 → 0.5.8

package/src/components/image.ts

@@ -27,6 +27,9 @@ export interface ImageOptions {
 
 const EMPTY_IDS: readonly number[] = [];
 const EMPTY_TRANSMITS: readonly string[] = [];
+// Direct placements reserve height with leading zero-width rows. Keep them
+// non-plain so transcript blank-edge trimming does not collapse image-only blocks.
+const RESERVED_IMAGE_ROW = "\x1b[0m";
 
 /** Default count of inline images kept as live graphics before older ones fall back to text. */
 export const DEFAULT_MAX_INLINE_IMAGES = 8;
@@ -73,6 +76,16 @@ export class ImageBudget {
 	#transmitted = new Set<number>();
 	/** Transmit sequences (full base64) to write once, before this frame's placements. */
 	#pendingTransmits: string[] = [];
+	// True while the in-flight pass is a partial/throwaway pass (the
+	// non-multiplexer resize viewport fast path) that walks only the visible
+	// tail, bottom-up. Such a pass cannot derive display order from observe()
+	// call order, so its suppression decisions replay the committed split below.
+	#stablePass = false;
+	// Image ids shown as text in the frame currently on the terminal: the
+	// display-order prefix [0, #onTerminal) of the last full pass, snapshotted by
+	// id so a partial pass reproduces the on-screen live/text split without a
+	// full, correctly-ordered walk.
+	#suppressedIds = new Set<number>();
 
 	constructor(cap: number = DEFAULT_MAX_INLINE_IMAGES, requestRender: () => void = () => {}) {
 		this.#cap = normalizeCap(cap);
@@ -114,18 +127,32 @@ export class ImageBudget {
 		return this.#nextId++;
 	}
 
-	/** Begin a render pass. Called by the renderer before composing the frame. */
-	beginPass(): void {
+	/**
+	 * Begin a render pass. Called by the renderer before composing the frame.
+	 * Pass `stable: true` for a partial/throwaway pass that does not walk the
+	 * whole tree in display order (the resize viewport fast path): {@link observe}
+	 * then replays the last committed per-id decision instead of one derived from
+	 * call order, and the pass must NOT be closed with {@link endPass}.
+	 */
+	beginPass(stable = false): void {
 		this.#passIds.length = 0;
-		this.#applyingReset = this.#cap > 0 && this.#planned > this.#onTerminal;
+		this.#stablePass = stable;
+		this.#applyingReset = !stable && this.#cap > 0 && this.#planned > this.#onTerminal;
 	}
 
 	/**
 	 * Record an image in display order and report whether it must render its text
 	 * fallback this frame. Called by every {@link Image} during render — including
 	 * on a cache hit, so the image keeps its display-order slot.
+	 *
+	 * During a `stable` pass ({@link beginPass}) the call order and visible subset
+	 * are not authoritative, so the decision is the committed on-terminal split
+	 * (`#suppressedIds`) keyed by id — order- and partiality-independent.
 	 */
 	observe(imageId: number): boolean {
+		if (this.#stablePass) {
+			return this.#cap > 0 && this.#suppressedIds.has(imageId);
+		}
 		const index = this.#passIds.length;
 		this.#passIds.push(imageId);
 		return this.#cap > 0 && index < this.#planned;
@@ -152,6 +179,11 @@ export class ImageBudget {
 			reset = true;
 		}
 		this.#reconcile(total);
+		// Snapshot the committed display-order suppression by id: the prefix
+		// [0, #onTerminal) is what the terminal currently shows as text. Partial
+		// passes replay this per id (see #stablePass) instead of re-deriving it
+		// from a reversed, tail-only walk.
+		this.#suppressedIds = new Set(this.#passIds.slice(0, this.#onTerminal));
 		return reset;
 	}
 
@@ -188,6 +220,26 @@ export class ImageBudget {
 		this.#pendingTransmits.push(sequence);
 	}
 
+	/** Whether a frame has image data queued but not yet written to the terminal. */
+	hasPendingTransmits(): boolean {
+		return this.#pendingTransmits.length > 0;
+	}
+
+	/**
+	 * True when the budget has nothing in flight: no live images observed on
+	 * the last pass, no queued transmits, no pending purges, and no stricter
+	 * threshold left to apply. A component-scoped frame may skip the observe
+	 * pass only then — a partial tree walk would under-count display order.
+	 */
+	get quiescent(): boolean {
+		return (
+			this.#lastTotal === 0 &&
+			this.#pendingTransmits.length === 0 &&
+			this.#purgeIds.length === 0 &&
+			this.#planned === this.#onTerminal
+		);
+	}
+
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
 	takeTransmits(): readonly string[] {
 		if (this.#pendingTransmits.length === 0) return EMPTY_TRANSMITS;
@@ -232,6 +284,10 @@ export class Image implements Component {
 	#cachedLines?: string[];
 	#cachedWidth?: number;
 	#cachedSuppressed = false;
+	// Tallest graphic placement this image has rendered. The text fallback
+	// pads itself to this height so a budget demotion never shrinks the block
+	// (its rows may already be committed to native scrollback).
+	#renderedGraphicRows = 0;
 
 	constructor(
 		base64Data: string,
@@ -254,7 +310,7 @@ export class Image implements Component {
 		this.#cachedWidth = undefined;
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const hasProtocol = TERMINAL.imageProtocol != null;
 		// observe() must run on every pass — even a cache hit — so the image keeps
 		// its display-order slot in the budget. Only graphics-capable frames count
@@ -296,17 +352,16 @@ export class Image implements Component {
 				// moves the cursor back up, then emits the image sequence.
 				lines = [];
 				for (let i = 0; i < result.rows - 1; i++) {
-					lines.push("");
+					lines.push(RESERVED_IMAGE_ROW);
 				}
 				const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
 				lines.push(moveUp + (result.sequence ?? ""));
 			} else {
-				lines = [
-					this.#theme.fallbackColor(imageFallback(this.#mimeType, this.#dimensions, this.#options.filename)),
-				];
+				lines = this.#fallbackLines();
 			}
+			this.#renderedGraphicRows = Math.max(this.#renderedGraphicRows, lines.length);
 		} else {
-			lines = [this.#theme.fallbackColor(imageFallback(this.#mimeType, this.#dimensions, this.#options.filename))];
+			lines = this.#fallbackLines();
 		}
 
 		this.#cachedLines = lines;
@@ -315,4 +370,25 @@ export class Image implements Component {
 
 		return lines;
 	}
+
+	/**
+	 * Text fallback, height-preserving once a graphic has rendered: a demoted
+	 * image must keep occupying the rows its placement used, because those
+	 * rows may already be committed to native scrollback — shrinking the block
+	 * would shift everything below it and force the renderer's commit-resync
+	 * (stale band + recommit). Reserved rows stay non-plain so blank-edge
+	 * trimming cannot collapse the block either.
+	 */
+	#fallbackLines(): string[] {
+		const fallback = this.#theme.fallbackColor(
+			imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
+		);
+		if (this.#renderedGraphicRows <= 1) return [fallback];
+		const lines: string[] = [];
+		for (let i = 0; i < this.#renderedGraphicRows - 1; i++) {
+			lines.push(RESERVED_IMAGE_ROW);
+		}
+		lines.push(fallback);
+		return lines;
+	}
 }

package/src/components/input.ts

@@ -28,6 +28,8 @@ export class Input implements Component, Focusable {
 	#value: string = "";
 	#cursor: number = 0; // Cursor position in the value
 	#useTerminalCursor = false;
+	/** Rendered before the editable area; set to "" for chrome-less embedding. */
+	prompt = "> ";
 	onSubmit?: (value: string) => void;
 	onEscape?: () => void;
 
@@ -50,6 +52,7 @@ export class Input implements Component, Focusable {
 
 	setValue(value: string): void {
 		this.#value = value;
+		// Callers seed or replace the value wholesale; typing continues at the end.
 		this.#cursor = value.length;
 	}
 
@@ -187,6 +190,12 @@ export class Input implements Component, Focusable {
 		}
 	}
 
+	/** Apply terminal paste semantics to text from non-bracketed paste transports
+	 *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
+	pasteText(text: string): void {
+		this.#handlePaste(text);
+	}
+
 	#insertCharacter(text: string): void {
 		const isWordChunk = [...segmenter.segment(text)].every(seg => getWordNavKind(seg.segment) !== "whitespace");
 		// Undo coalescing: consecutive word typing coalesces into one undo unit.
@@ -391,10 +400,10 @@ export class Input implements Component, Focusable {
 		// No cached state to invalidate currently
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		// Calculate visible window
-		const prompt = "> ";
-		const availableWidth = width - prompt.length;
+		const prompt = this.prompt;
+		const availableWidth = width - visibleWidth(prompt);
 
 		if (availableWidth <= 0) {
 			return [prompt];

package/src/components/loader.ts

@@ -3,21 +3,20 @@ 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.
+ * Loader component. Spinner frames advance at `SPINNER_ADVANCE_MS`.
  *
- * Two cadences are interleaved on a single timer:
- *   - **Render tick** (every `RENDER_INTERVAL_MS`) → asks the TUI to redraw.
- *     The TUI already throttles at 16ms (`MIN_RENDER_INTERVAL_MS`), so this
- *     is the natural upper bound; static messageColorFns produce identical
- *     output and the differ drops the no-op redraw at ~zero cost.
- *   - **Spinner advance** (every `SPINNER_ADVANCE_MS`) → bumps the spinner
- *     frame index. Decoupled from the render cadence so the spinner keeps
- *     its classic ~12.5fps step pace regardless of shimmer state.
+ * Message colorizers that are time-dependent can opt into 30fps redraws by
+ * setting `animated` to `true` on the function object.
  */
-const RENDER_INTERVAL_MS = 16;
+const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
 
+type ColorFn = (str: string) => string;
+
+export type LoaderMessageColorFn = ColorFn & {
+	readonly animated?: true;
+};
+
 export class Loader extends Text {
 	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	#currentFrame = 0;
@@ -27,8 +26,8 @@ export class Loader extends Text {
 
 	constructor(
 		ui: TUI,
-		private spinnerColorFn: (str: string) => string,
-		private messageColorFn: (str: string) => string,
+		private spinnerColorFn: ColorFn,
+		private messageColorFn: LoaderMessageColorFn,
 		private message: string = "Loading...",
 		spinnerFrames?: string[],
 	) {
@@ -40,7 +39,7 @@ export class Loader extends Text {
 		this.start();
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const lines = ["", ...super.render(width)];
 		for (let i = 0; i < lines.length; i++) {
 			const line = lines[i];
@@ -54,14 +53,17 @@ export class Loader extends Text {
 	start() {
 		this.#lastSpinnerTick = performance.now();
 		this.#updateDisplay();
+		const intervalMs = this.messageColorFn.animated === true ? RENDER_INTERVAL_MS : SPINNER_ADVANCE_MS;
 		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;
+			const elapsed = now - this.#lastSpinnerTick;
+			if (elapsed >= SPINNER_ADVANCE_MS) {
+				const steps = Math.floor(elapsed / SPINNER_ADVANCE_MS);
+				this.#currentFrame = (this.#currentFrame + steps) % this.#frames.length;
+				this.#lastSpinnerTick += steps * SPINNER_ADVANCE_MS;
 			}
 			this.#updateDisplay();
-		}, RENDER_INTERVAL_MS);
+		}, intervalMs);
 	}
 
 	stop() {
@@ -71,16 +73,28 @@ export class Loader extends Text {
 		}
 	}
 
+	/** Lifecycle teardown: stop the animation timer. Idempotent. */
+	dispose() {
+		this.stop();
+	}
+
 	setMessage(message: string) {
+		if (message === this.message) {
+			return;
+		}
 		this.message = message;
 		this.#updateDisplay();
 	}
 
 	#updateDisplay() {
 		const frame = this.#frames[this.#currentFrame];
-		this.setText(`${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`);
-		if (this.#ui) {
-			this.#ui.requestRender();
+		const text = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
+		if (this.setText(text) && this.#ui) {
+			// Component-scoped: a spinner tick changes only this component, so
+			// the TUI may reuse every other root subtree instead of re-walking
+			// the whole tree (full repaints at 12.5 Hz made huge transcripts
+			// lag as soon as the loader appeared).
+			this.#ui.requestComponentRender(this);
 		}
 	}
 }

package/src/components/markdown.ts

@@ -58,7 +58,15 @@ markdownParser.setOptions({
 // (Rust FFI) work for content/layout combinations already seen this session.
 
 const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
-const renderCache = new LRUCache<string, string[]>({ max: RENDER_CACHE_MAX });
+const EMPTY_RENDER_LINES: readonly string[] = [];
+const renderCache = new LRUCache<string, readonly string[]>({ max: RENDER_CACHE_MAX });
+
+// A reference-link definition (`[label]: dest`) resolves across the whole
+// document, so a split lex cannot reproduce it — disable the streaming fast path
+// when one is present (rare in streamed output). The label may contain
+// backslash-escaped characters (`[a\]b]: x`), so escapes are matched explicitly;
+// over-matching is safe (it only costs the fast path), under-matching is not.
+const HAS_REF_DEF = /^ {0,3}\[(?:\\.|[^\]\\])+\]:/m;
 
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export function clearRenderCache(): void {
@@ -288,10 +296,23 @@ export class Markdown implements Component {
 	/** Number of spaces used to indent code block content. */
 	#codeBlockIndent: number;
 
-	// Cache for rendered output
+	// Cache for rendered output. Cached arrays are shared and returned by
+	// reference (render contract: results are component-owned and immutable to
+	// callers); the L2 LRU may hand the same array to multiple instances.
 	#cachedText?: string;
 	#cachedWidth?: number;
-	#cachedLines?: string[];
+	#cachedLines?: readonly string[];
+	#transientRenderCache = false;
+
+	// Streaming-lex cache: the largest blank-line-bounded prefix of #text whose
+	// block tokens are frozen, plus those tokens. marked has no resumable lexer,
+	// but block tokenization is local across a "\n\n" boundary with balanced
+	// fences, so lex(prefix) ++ lex(tail) === lex(prefix+tail). On append-only
+	// growth (the streaming path) this re-lexes only the grown tail instead of the
+	// whole buffer, turning O(N^2) reveal cost into O(N). Width/theme do not affect
+	// tokenization, so this cache is independent of the render caches above.
+	#streamPrefixText?: string;
+	#streamPrefixTokens?: Token[];
 
 	constructor(
 		text: string,
@@ -311,6 +332,13 @@ export class Markdown implements Component {
 
 	setText(text: string): void {
 		this.#text = text;
+		if (!text.trim()) {
+			// Blank replacement: render() early-returns before #lexTokens can see
+			// the non-append edit, so drop the frozen stream state here or it
+			// outlives the content it indexed.
+			this.#streamPrefixText = undefined;
+			this.#streamPrefixTokens = undefined;
+		}
 		this.invalidate();
 	}
 
@@ -319,10 +347,92 @@ export class Markdown implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
 	}
+	get transientRenderCache(): boolean {
+		return this.#transientRenderCache;
+	}
+
+	set transientRenderCache(value: boolean) {
+		const next = value === true;
+		if (this.#transientRenderCache === next) return;
+		this.#transientRenderCache = next;
+		this.invalidate();
+	}
+
+	// Lex `text` into block tokens, reusing the frozen stable prefix when the text
+	// only grew (the streaming path). Falls back to a full lex whenever the prefix
+	// is no longer a prefix (non-append edit), the text carries reference-link
+	// definitions, or it contains CR (marked normalizes CRLF, which would desync
+	// raw-span offsets). Every fallback is correctness-preserving — only speed
+	// differs; the render loop sees the identical token list either way.
+	#lexTokens(text: string): Token[] {
+		const canStream = !HAS_REF_DEF.test(text) && !text.includes("\r");
+		const prefix = this.#streamPrefixText;
+		const prefixTokens = this.#streamPrefixTokens;
+		if (
+			canStream &&
+			prefix !== undefined &&
+			prefixTokens !== undefined &&
+			text.length > prefix.length &&
+			text.startsWith(prefix)
+		) {
+			const tailTokens = markdownParser.lexer(text.slice(prefix.length));
+			const tokens = [...prefixTokens, ...tailTokens];
+			this.#freezeStablePrefix(text, tokens);
+			return tokens;
+		}
+		const tokens = markdownParser.lexer(text);
+		if (canStream) {
+			this.#freezeStablePrefix(text, tokens);
+		} else {
+			this.#streamPrefixText = undefined;
+			this.#streamPrefixTokens = undefined;
+		}
+		return tokens;
+	}
+
+	// Freeze the largest run of leading blocks that end on a hard "\n\n" boundary
+	// (complete and immutable under append-only growth) so the next streaming
+	// render re-lexes only the unfrozen tail. Caller guarantees no CR / no
+	// reference definitions, so each token's `raw` is a verbatim slice of `text`
+	// and the summed offsets address `text` exactly.
+	#freezeStablePrefix(text: string, tokens: Token[]): void {
+		let pos = 0;
+		let frozenEnd = 0;
+		let frozenCount = 0;
+		for (let i = 0; i < tokens.length; i++) {
+			const raw = tokens[i].raw;
+			const end = pos + raw.length;
+			// A `space` token ending in "\n\n" closes the preceding block, but a
+			// `list` before it can still be extended by a following same-marker
+			// item across the blank line (CommonMark loose-list continuation),
+			// which marked merges into one renumbered loose list. Freezing across
+			// such a cut would keep the lists separate. Never freeze right after a
+			// list — it stays in the re-lexed tail.
+			if (raw.endsWith("\n\n") && tokens[i - 1]?.type !== "list") {
+				frozenEnd = end;
+				frozenCount = i + 1;
+			}
+			pos = end;
+		}
+		// Freeze only when the tail begins with real block content. If the next
+		// char is whitespace (an extra blank line, or an indented continuation),
+		// the block separator straddles the cut and lex(prefix)++lex(tail) would
+		// desync from a full lex — e.g. a fence followed by "\n\n\n- list". When
+		// frozenEnd is at end-of-text the next char is unknown, so defer.
+		if (frozenCount > 0 && frozenEnd < text.length) {
+			const next = text.charCodeAt(frozenEnd);
+			if (next !== 0x20 /* space */ && next !== 0x0a /* \n */) {
+				this.#streamPrefixText = text.slice(0, frozenEnd);
+				this.#streamPrefixTokens = tokens.slice(0, frozenCount);
+			}
+		}
+	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
+		// Returning the cached reference is load-bearing: parents memoize their
+		// concatenation on reference equality.
 		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
 			return this.#cachedLines;
 		}
@@ -332,12 +442,10 @@ export class Markdown implements Component {
 
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
-			const result: string[] = [];
-			// Update per-instance cache
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
-			this.#cachedLines = result;
-			return result;
+			this.#cachedLines = EMPTY_RENDER_LINES;
+			return EMPTY_RENDER_LINES;
 		}
 
 		// Replace tabs with 3 spaces for consistent rendering
@@ -355,20 +463,23 @@ export class Markdown implements Component {
 		// risk of clashing with a function that returns text verbatim.
 		// theme.heading is used as the representative theme probe — it's required
 		// by MarkdownTheme and is one of the most styling-sensitive entries.
-		const bgColorProbe = this.#defaultTextStyle?.bgColor ? this.#defaultTextStyle.bgColor("\x01") : "";
-		const headingProbe = this.#theme.heading("");
-		const cacheKey = `${normalizedText}\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${TERMINAL.textSizing ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
-		const cached = renderCache.get(cacheKey);
-		if (cached !== undefined) {
-			// Populate L1 so subsequent calls from this instance are O(1) map lookup.
-			this.#cachedText = this.#text;
-			this.#cachedWidth = width;
-			this.#cachedLines = cached;
-			return cached;
+		let cacheKey: string | undefined;
+		if (!this.transientRenderCache) {
+			const bgColorProbe = this.#defaultTextStyle?.bgColor ? this.#defaultTextStyle.bgColor("\x01") : "";
+			const headingProbe = this.#theme.heading("");
+			cacheKey = `${normalizedText}\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${TERMINAL.textSizing ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
+			const cached = renderCache.get(cacheKey);
+			if (cached !== undefined) {
+				// Populate L1 so subsequent calls from this instance are O(1) map lookup.
+				this.#cachedText = this.#text;
+				this.#cachedWidth = width;
+				this.#cachedLines = cached;
+				return cached;
+			}
 		}
 
 		// Parse markdown to HTML-like tokens
-		const tokens = markdownParser.lexer(normalizedText);
+		const tokens = this.#lexTokens(normalizedText);
 
 		// Convert tokens to styled terminal output
 		const renderedLines: string[] = [];
@@ -445,14 +556,18 @@ export class Markdown implements Component {
 		const rawResult = [...emptyLines, ...contentLines, ...emptyLines];
 		const result = rawResult.length > 0 ? rawResult : [""];
 
-		// Update L1 per-instance cache
+		// Update caches and hand the array out by reference. Callers must not
+		// mutate it (Component render contract); the L2 entry is shared across
+		// instances keyed on identical inputs.
 		this.#cachedText = this.#text;
 		this.#cachedWidth = width;
 		this.#cachedLines = result;
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		renderCache.set(cacheKey, result);
+		if (cacheKey !== undefined) {
+			renderCache.set(cacheKey, result);
+		}
 
 		return result;
 	}
@@ -604,7 +719,7 @@ export class Markdown implements Component {
 
 				const codeIndent = padding(this.#codeBlockIndent);
 				lines.push(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
-				if (this.#theme.highlightCode) {
+				if (this.#theme.highlightCode && !this.transientRenderCache) {
 					const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
 					for (const hlLine of highlightedLines) {
 						lines.push(`${codeIndent}${hlLine}`);
@@ -822,35 +937,33 @@ export class Markdown implements Component {
 		for (let i = 0; i < token.items.length; i++) {
 			const item = token.items[i];
 			const bullet = token.ordered ? `${startNumber + i}. ` : "- ";
+			// Continuation rows align under the item text, so the hang matches the
+			// actual bullet width (`10. ` is 4 cells, not 2).
+			const continuationIndent = indent + padding(bullet.length);
 
-			// Process item tokens to handle nested lists
+			// Process item tokens; nested-list lines arrive structurally tagged and
+			// already carry their own full indent.
 			const itemLines = this.#renderListItem(item.tokens || [], depth, styleContext);
 
 			if (itemLines.length > 0) {
-				// First line - check if it's a nested list
-				// A nested list will start with indent (spaces) followed by cyan bullet
-				const firstLine = itemLines[0];
-				const isNestedList = /^\s+\x1b\[36m[-\d]/.test(firstLine); // starts with spaces + cyan + bullet char
-
-				if (isNestedList) {
-					// This is a nested list, just add it as-is (already has full indent)
-					lines.push(firstLine);
+				const firstLine = itemLines[0]!;
+				if (firstLine.nested) {
+					// Nested list first - keep as-is (already has full indent)
+					lines.push(firstLine.text);
 				} else {
 					// Regular text content - add indent and bullet
-					lines.push(indent + this.#theme.listBullet(bullet) + firstLine);
+					lines.push(indent + this.#theme.listBullet(bullet) + firstLine.text);
 				}
 
 				// Rest of the lines
 				for (let j = 1; j < itemLines.length; j++) {
-					const line = itemLines[j];
-					const isNestedListLine = /^\s+\x1b\[36m[-\d]/.test(line); // starts with spaces + cyan + bullet char
-
-					if (isNestedListLine) {
+					const line = itemLines[j]!;
+					if (line.nested) {
 						// Nested list line - already has full indent
-						lines.push(line);
+						lines.push(line.text);
 					} else {
-						// Regular content - add parent indent + 2 spaces for continuation
-						lines.push(`${indent}  ${line}`);
+						// Regular content - hang under the item text
+						lines.push(continuationIndent + line.text);
 					}
 				}
 			} else {
@@ -862,50 +975,58 @@ export class Markdown implements Component {
 	}
 
 	/**
-	 * Render list item tokens, handling nested lists
-	 * Returns lines WITHOUT the parent indent (renderList will add it)
+	 * Render list item tokens, handling nested lists.
+	 * Returns lines WITHOUT the parent indent (renderList adds it); lines that
+	 * belong to a nested list are tagged `nested` so the caller never has to
+	 * sniff theme-dependent ANSI bytes to recognize them.
 	 */
-	#renderListItem(tokens: Token[], parentDepth: number, styleContext?: InlineStyleContext): string[] {
-		const lines: string[] = [];
+	#renderListItem(
+		tokens: Token[],
+		parentDepth: number,
+		styleContext?: InlineStyleContext,
+	): Array<{ text: string; nested: boolean }> {
+		const lines: Array<{ text: string; nested: boolean }> = [];
 
 		for (const token of tokens) {
 			if (token.type === "list") {
 				// Nested list - render with one additional indent level
-				// These lines will have their own indent, so we just add them as-is
+				// These lines carry their own indent, so tag them for pass-through
 				const nestedLines = this.#renderList(token as ListToken, parentDepth + 1, styleContext);
-				lines.push(...nestedLines);
+				for (const nestedLine of nestedLines) {
+					lines.push({ text: nestedLine, nested: true });
+				}
 			} else if (token.type === "text") {
 				// Text content (may have inline tokens)
 				const text =
 					token.tokens && token.tokens.length > 0
 						? this.#renderInlineTokens(token.tokens, styleContext)
 						: token.text || "";
-				lines.push(text);
+				lines.push({ text, nested: false });
 			} else if (token.type === "paragraph") {
 				// Paragraph in list item
 				const text = this.#renderInlineTokens(token.tokens || [], styleContext);
-				lines.push(text);
+				lines.push({ text, nested: false });
 			} else if (token.type === "code") {
 				// Code block in list item
 				const codeIndent = padding(this.#codeBlockIndent);
-				lines.push(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
-				if (this.#theme.highlightCode) {
+				lines.push({ text: this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`), nested: false });
+				if (this.#theme.highlightCode && !this.transientRenderCache) {
 					const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
 					for (const hlLine of highlightedLines) {
-						lines.push(`${codeIndent}${hlLine}`);
+						lines.push({ text: `${codeIndent}${hlLine}`, nested: false });
 					}
 				} else {
 					const codeLines = token.text.split("\n");
 					for (const codeLine of codeLines) {
-						lines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
+						lines.push({ text: `${codeIndent}${this.#theme.codeBlock(codeLine)}`, nested: false });
 					}
 				}
-				lines.push(this.#theme.codeBlockBorder("```"));
+				lines.push({ text: this.#theme.codeBlockBorder("```"), nested: false });
 			} else {
 				// Other token types - try to render as inline
 				const text = this.#renderInlineTokens([token], styleContext);
 				if (text) {
-					lines.push(text);
+					lines.push({ text, nested: false });
 				}
 			}
 		}