@oh-my-pi/pi-tui 17.4.2 → 18.0.0

package/src/components/markdown.ts

@@ -1165,6 +1165,15 @@ export interface DefaultTextStyle {
 	underline?: boolean;
 }
 
+/**
+ * Stateful incremental code highlighter carrying parser state across pushes.
+ * Produced per streaming fence by {@link MarkdownTheme.createHighlightStream}.
+ */
+export interface HighlightStreamSession {
+	/** Highlight the next chunk and advance parser state. */
+	push(chunk: string): string;
+}
+
 /**
  * Theme functions for markdown elements.
  * Each function takes text and returns styled text with ANSI codes.
@@ -1185,6 +1194,14 @@ export interface MarkdownTheme {
 	strikethrough: (text: string) => string;
 	underline: (text: string) => string;
 	highlightCode?: (code: string, lang?: string) => string[];
+	/**
+	 * Create a stateful incremental highlighter for one streaming code fence.
+	 * `push` receives newline-terminated complete lines (only the final push
+	 * may omit the trailing newline) and must return highlighted ANSI text for
+	 * exactly the pushed chunk, byte-identical to highlighting the concatenated
+	 * text through `highlightCode`. Return null when `lang` is unsupported.
+	 */
+	createHighlightStream?: (lang?: string) => HighlightStreamSession | null;
 	/**
 	 * Resolve a mermaid ASCII rendering by fenced block source text.
 	 * Return null to fall back to fenced code rendering.
@@ -1455,10 +1472,21 @@ interface StreamPrefixLineCache extends RenderSignature {
 	lines: readonly string[];
 	tables: readonly TableRenderSpec[];
 }
-interface StreamingDiffLineCache extends RenderSignature {
+interface StreamingHighlightCache extends RenderSignature {
 	lang: string | undefined;
 	text: string;
 	lines: readonly string[];
+	stream: HighlightStreamSession;
+}
+
+/**
+ * Split a highlight-stream push result (newline-terminated lines) into
+ * per-line strings, dropping the empty tail produced by the final newline.
+ */
+function splitPushedHighlightLines(pushed: string): string[] {
+	const lines = pushed.split("\n");
+	lines.pop();
+	return lines;
 }
 
 interface TableLayoutLock {
@@ -1532,11 +1560,14 @@ export class Markdown
 	// True while #renderStreamingContentLines renders the frozen token range:
 	// frozen code blocks highlight even in transient mode so their bytes match
 	// the finalized render (they render once into the prefix line cache, so
-	// the FFI cost is amortized). The volatile tail normally stays
-	// unhighlighted; streaming diff fences line-highlight completed rows so
-	// semantic colors reach native scrollback before rows leave the viewport.
+	// the FFI cost is amortized). In the volatile tail, an open fence
+	// incrementally highlights its completed lines through a stateful
+	// highlight stream (falling back to per-line highlighting for diff-family
+	// fences when the theme lacks one) so semantic colors reach native
+	// scrollback before rows leave the viewport; only the trailing partial
+	// line stays unhighlighted.
 	#renderingFrozenPrefix = false;
-	#streamingDiffLineCache?: StreamingDiffLineCache;
+	#streamingHighlightCache?: StreamingHighlightCache;
 	#activeRenderSignature?: RenderSignature;
 	// Streaming tables may grow naturally while wholly repaintable. Once any
 	// physical row of a table enters native scrollback, its current column widths
@@ -1548,9 +1579,19 @@ export class Markdown
 	#activeTableRenderSpecs?: TableRenderSpec[];
 
 	#ignoreTight = false;
+	// Width-independent mutation counter for the width-epoch leading-stability
+	// checks (getNativeScrollbackWidthEpochRevision): a Markdown that precedes an
+	// epoch source (startup changelog before the transcript, a thinking block
+	// before the streaming answer) would otherwise be validated by comparing
+	// width-dependent row counts, which conflates reflow with mutation and fails
+	// resolution on every width change. Bumped by every content-shape mutation.
+	#widthEpochRevision = 0;
 
 	setIgnoreTight(ignore: boolean): this {
-		if (this.#ignoreTight !== ignore) this.#clearTableLayouts();
+		if (this.#ignoreTight !== ignore) {
+			this.#clearTableLayouts();
+			this.#widthEpochRevision++;
+		}
 		this.#ignoreTight = ignore;
 		this.invalidate();
 		return this;
@@ -1591,10 +1632,15 @@ export class Markdown
 			this.#streamPrefixLineCache = undefined;
 			this.#settledExposedText = undefined;
 		}
+		this.#widthEpochRevision++;
 		this.invalidate();
 		return true;
 	}
 
+	getNativeScrollbackWidthEpochRevision(): number {
+		return this.#widthEpochRevision;
+	}
+
 	invalidate(): void {
 		this.#cachedText = undefined;
 		this.#cachedWidth = undefined;
@@ -1608,6 +1654,7 @@ export class Markdown
 		const next = value === true;
 		if (this.#transientRenderCache === next) return;
 		this.#transientRenderCache = next;
+		this.#widthEpochRevision++;
 		this.invalidate();
 	}
 
@@ -2137,17 +2184,15 @@ export class Markdown
 		const bodyLines: RenderedLine[] = [];
 		const tokenText = "text" in token && typeof token.text === "string" ? token.text : "";
 		const lang = "lang" in token && typeof token.lang === "string" ? token.lang : undefined;
-		const normalizedLang = lang?.toLowerCase();
-		const canStreamDiff =
-			this.transientRenderCache &&
-			!this.#renderingFrozenPrefix &&
-			this.#theme.highlightCode &&
-			(normalizedLang === "diff" || normalizedLang === "patch" || normalizedLang === "udiff");
 		const addBodyLine = (line: string): void => {
 			bodyLines.push(renderedLine(literalCode ? line : codeIndent + line, literalCode));
 		};
 
-		if (this.#theme.highlightCode && (!this.transientRenderCache || this.#renderingFrozenPrefix)) {
+		const streaming = this.transientRenderCache && !this.#renderingFrozenPrefix;
+		if (this.#theme.highlightCode && (!streaming || this.#codeTokenHasClosingFence(token))) {
+			// Finalized content — or a fence that closed mid-stream, which
+			// highlights through the same whole-block call the finalized render
+			// uses so rows entering native scrollback byte-match it.
 			const highlightedLines = this.#theme.highlightCode(tokenText, lang);
 			for (const hlLine of highlightedLines) {
 				addBodyLine(hlLine);
@@ -2155,18 +2200,18 @@ export class Markdown
 			return bodyLines;
 		}
 
-		if (canStreamDiff) {
-			const closedFence = this.#codeTokenHasClosingFence(token);
+		if (streaming && this.#theme.highlightCode) {
+			// Open fence: highlight completed lines incrementally so semantic
+			// colors reach native scrollback before rows leave the viewport;
+			// only the trailing partial line stays unhighlighted.
 			const lineEnd = tokenText.lastIndexOf("\n");
-			if (closedFence || lineEnd >= 0) {
-				const completedText = closedFence ? tokenText : tokenText.slice(0, lineEnd);
-				for (const hlLine of this.#highlightStreamingDiffLines(completedText, lang)) {
+			const completedLines = lineEnd >= 0 ? this.#highlightStreamingLines(tokenText.slice(0, lineEnd), lang) : null;
+			if (completedLines) {
+				for (const hlLine of completedLines) {
 					addBodyLine(hlLine);
 				}
-				if (!closedFence) {
-					for (const codeLine of tokenText.slice(lineEnd + 1).split("\n")) {
-						addBodyLine(this.#theme.codeBlock(codeLine));
-					}
+				for (const codeLine of tokenText.slice(lineEnd + 1).split("\n")) {
+					addBodyLine(this.#theme.codeBlock(codeLine));
 				}
 				return bodyLines;
 			}
@@ -2209,11 +2254,17 @@ export class Markdown
 		return false;
 	}
 
-	#highlightStreamingDiffLines(completedText: string, lang: string | undefined): readonly string[] {
-		const highlightCode = this.#theme.highlightCode;
-		if (!highlightCode) return [];
+	/**
+	 * Highlight the completed (newline-terminated) prefix of a streaming code
+	 * fence. Uses a stateful per-fence highlight stream so each render pushes
+	 * only the newly completed lines, with output byte-identical to the
+	 * whole-block `highlightCode` the finalized render performs. Returns null
+	 * when no stream is available for `lang` (caller falls back to plain
+	 * code-block styling).
+	 */
+	#highlightStreamingLines(completedText: string, lang: string | undefined): readonly string[] | null {
 		const signature = this.#activeRenderSignature;
-		const cache = this.#streamingDiffLineCache;
+		const cache = this.#streamingHighlightCache;
 		if (
 			signature &&
 			cache &&
@@ -2233,25 +2284,49 @@ export class Markdown
 			cache.headingProbe === signature.headingProbe
 		) {
 			if (completedText.length === cache.text.length) return cache.lines;
-			const lines = cache.lines.slice();
+			// Invariant: the stream has consumed `cache.text + "\n"`, so pushing
+			// the added lines with a trailing newline advances it to
+			// `completedText + "\n"` — every fed line stays newline-terminated.
 			const addedText = completedText.slice(cache.text.length + 1);
-			for (const codeLine of addedText.split("\n")) {
-				lines.push(...highlightCode(codeLine, lang));
-			}
-			this.#streamingDiffLineCache = { ...signature, lang, text: completedText, lines };
+			const lines = cache.lines.concat(splitPushedHighlightLines(cache.stream.push(`${addedText}\n`)));
+			this.#streamingHighlightCache = { ...signature, lang, text: completedText, lines, stream: cache.stream };
 			return lines;
 		}
 
-		const lines: string[] = [];
-		for (const codeLine of completedText.split("\n")) {
-			lines.push(...highlightCode(codeLine, lang));
-		}
+		const stream = this.#createHighlightStream(lang);
+		if (!stream) return null;
+		const lines = splitPushedHighlightLines(stream.push(`${completedText}\n`));
 		if (signature) {
-			this.#streamingDiffLineCache = { ...signature, lang, text: completedText, lines };
+			this.#streamingHighlightCache = { ...signature, lang, text: completedText, lines, stream };
 		}
 		return lines;
 	}
 
+	/**
+	 * Resolve a highlight stream for `lang`. Prefers the theme's stateful
+	 * factory; without one, emulates a stream via per-line `highlightCode` for
+	 * diff-family fences only — that grammar is line-local, so per-line output
+	 * matches the whole-block render (other grammars carry cross-line state
+	 * and would diverge).
+	 */
+	#createHighlightStream(lang: string | undefined): HighlightStreamSession | null {
+		const factory = this.#theme.createHighlightStream;
+		if (factory) return factory(lang);
+		const highlightCode = this.#theme.highlightCode;
+		if (!highlightCode) return null;
+		const normalizedLang = lang?.toLowerCase();
+		if (normalizedLang !== "diff" && normalizedLang !== "patch" && normalizedLang !== "udiff") return null;
+		return {
+			push: chunk => {
+				const lines = chunk.split("\n");
+				const trailing = lines.pop() ?? "";
+				let out = "";
+				for (const line of lines) out += `${highlightCode(line, lang).join("\n")}\n`;
+				return trailing ? out + highlightCode(trailing, lang).join("\n") : out;
+			},
+		};
+	}
+
 	#renderEmptyPaddingLines(signature: RenderSignature): string[] {
 		const emptyLine = padding(signature.width);
 		const emptyLines: string[] = [];

package/src/components/select-list.ts

@@ -27,6 +27,8 @@ export interface SelectItem {
 	value: string;
 	label: string;
 	description?: string;
+	/** Optional type-indicator glyph rendered in an aligned column before the label */
+	icon?: string;
 	/** Dim hint text shown inline after cursor when this item is selected */
 	hint?: string;
 }
@@ -38,6 +40,8 @@ export interface SelectListTheme {
 	scrollInfo: (text: string) => string;
 	noMatch: (text: string) => string;
 	symbols: SymbolTheme;
+	/** Style for the type-icon column on unselected rows. Defaults to plain text. */
+	icon?: (text: string) => string;
 	/** Hover band applied to the full row under the mouse pointer. */
 	hovered?: (text: string) => string;
 }
@@ -64,12 +68,18 @@ export interface SelectListLayoutOptions {
 	 * wrap unevenly.
 	 */
 	wrapDescription?: boolean;
+	/**
+	 * Cap wrapped descriptions at this many visual rows; the last kept row is
+	 * ellipsized. Only meaningful with `wrapDescription`.
+	 */
+	maxDescriptionRows?: number;
 }
 
 type SelectItemLayout =
 	| {
 			kind: "description";
 			prefix: string;
+			iconCell: string;
 			truncatedValue: string;
 			spacing: string;
 			descriptionSingleLine: string;
@@ -79,6 +89,7 @@ type SelectItemLayout =
 	| {
 			kind: "primary";
 			prefix: string;
+			iconCell: string;
 			truncatedValue: string;
 			spacing: "";
 	  };
@@ -172,6 +183,7 @@ export class SelectList implements Component, MouseRoutable {
 		}
 
 		const primaryColumnWidth = this.#getPrimaryColumnWidth();
+		const iconColumnWidth = this.#getIconColumnWidth();
 		const wrapEnabled = this.layout.wrapDescription === true;
 		// `maxVisible` is the picker's visual row budget. For non-wrap layouts
 		// every item is one row, so the budget matches the original item count.
@@ -190,7 +202,9 @@ export class SelectList implements Component, MouseRoutable {
 				rowCounts[i] = 0;
 				continue;
 			}
-			rowCounts[i] = wrapEnabled ? this.#computeItemRowCount(item, conservativeRowWidth, primaryColumnWidth) : 1;
+			rowCounts[i] = wrapEnabled
+				? this.#computeItemRowCount(item, conservativeRowWidth, primaryColumnWidth, iconColumnWidth)
+				: 1;
 			visualTotal += rowCounts[i];
 		}
 
@@ -211,7 +225,13 @@ export class SelectList implements Component, MouseRoutable {
 			const item = this.#filteredItems[i];
 			if (!item) continue;
 			const hovered = this.theme.hovered !== undefined && i === this.#hoveredIndex && i !== this.#selectedIndex;
-			const itemRows = this.#renderItem(item, i === this.#selectedIndex, rowWidth, primaryColumnWidth);
+			const itemRows = this.#renderItem(
+				item,
+				i === this.#selectedIndex,
+				rowWidth,
+				primaryColumnWidth,
+				iconColumnWidth,
+			);
 			for (const row of itemRows) {
 				if (rows.length >= visualBudget) break;
 				this.#hitRows[rows.length] = i;
@@ -280,25 +300,33 @@ export class SelectList implements Component, MouseRoutable {
 		}
 	}
 
-	#renderItem(item: SelectItem, isSelected: boolean, width: number, primaryColumnWidth: number): string[] {
-		const layout = this.#computeItemLayout(item, isSelected, width, primaryColumnWidth);
+	#renderItem(
+		item: SelectItem,
+		isSelected: boolean,
+		width: number,
+		primaryColumnWidth: number,
+		iconColumnWidth: number,
+	): string[] {
+		const layout = this.#computeItemLayout(item, isSelected, width, primaryColumnWidth, iconColumnWidth);
 		const { prefix, truncatedValue, spacing } = layout;
+		const iconCell =
+			layout.iconCell && !isSelected && this.theme.icon ? this.theme.icon(layout.iconCell) : layout.iconCell;
 
 		if (layout.kind === "description") {
 			const { descriptionSingleLine, descriptionStart, remainingWidth } = layout;
 			if (this.layout.wrapDescription) {
-				const wrapped = wrapTextWithAnsi(descriptionSingleLine, remainingWidth);
+				const wrapped = this.#wrapDescription(descriptionSingleLine, remainingWidth);
 				if (wrapped.length === 0) wrapped.push("");
 				const indent = padding(descriptionStart);
 				const first = wrapped[0] ?? "";
 				if (isSelected) {
-					const rows = [this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${first}`)];
+					const rows = [this.theme.selectedText(`${prefix}${iconCell}${truncatedValue}${spacing}${first}`)];
 					for (let i = 1; i < wrapped.length; i++) {
 						rows.push(this.theme.selectedText(`${indent}${wrapped[i]}`));
 					}
 					return rows;
 				}
-				const rows = [prefix + truncatedValue + this.theme.description(spacing + first)];
+				const rows = [prefix + iconCell + truncatedValue + this.theme.description(spacing + first)];
 				for (let i = 1; i < wrapped.length; i++) {
 					rows.push(this.theme.description(`${indent}${wrapped[i]}`));
 				}
@@ -307,25 +335,34 @@ export class SelectList implements Component, MouseRoutable {
 
 			const truncatedDesc = truncateToWidth(descriptionSingleLine, remainingWidth, Ellipsis.Omit);
 			if (isSelected) {
-				return [this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`)];
+				return [this.theme.selectedText(`${prefix}${iconCell}${truncatedValue}${spacing}${truncatedDesc}`)];
 			}
-			return [prefix + truncatedValue + this.theme.description(spacing + truncatedDesc)];
+			return [prefix + iconCell + truncatedValue + this.theme.description(spacing + truncatedDesc)];
 		}
 
 		if (isSelected) {
-			return [this.theme.selectedText(`${prefix}${truncatedValue}`)];
+			return [this.theme.selectedText(`${prefix}${iconCell}${truncatedValue}`)];
 		}
-		return [prefix + truncatedValue];
+		return [prefix + iconCell + truncatedValue];
 	}
 
-	#computeItemRowCount(item: SelectItem, width: number, primaryColumnWidth: number): number {
+	#computeItemRowCount(item: SelectItem, width: number, primaryColumnWidth: number, iconColumnWidth: number): number {
 		// Selection style does not change row count; pass isSelected=false to
 		// keep the cheap path uniform for items outside the visible window.
-		const layout = this.#computeItemLayout(item, false, width, primaryColumnWidth);
+		const layout = this.#computeItemLayout(item, false, width, primaryColumnWidth, iconColumnWidth);
 		if (layout.kind !== "description") return 1;
-		const wrapped = wrapTextWithAnsi(layout.descriptionSingleLine, layout.remainingWidth);
+		const wrapped = this.#wrapDescription(layout.descriptionSingleLine, layout.remainingWidth);
 		return Math.max(1, wrapped.length);
 	}
+	/** Wrap a description, capping it at `maxDescriptionRows` with a trailing ellipsis. */
+	#wrapDescription(description: string, width: number): string[] {
+		const wrapped = wrapTextWithAnsi(description, width);
+		const cap = this.layout.maxDescriptionRows;
+		if (cap === undefined || cap < 1 || wrapped.length <= cap) return wrapped;
+		const kept = wrapped.slice(0, cap);
+		kept[cap - 1] = truncateToWidth(`${kept[cap - 1]} …`, width, Ellipsis.Unicode);
+		return kept;
+	}
 
 	/**
 	 * Pick a contiguous window of items containing `selectedIndex` such that
@@ -380,10 +417,15 @@ export class SelectList implements Component, MouseRoutable {
 		isSelected: boolean,
 		width: number,
 		primaryColumnWidth: number,
+		iconColumnWidth: number,
 	): SelectItemLayout {
 		const cursor = this.theme.symbols?.cursor ?? DEFAULT_CURSOR_SYMBOL;
 		const prefix = isSelected ? `${cursor} ` : padding(visibleWidth(cursor) + 1);
-		const prefixWidth = visibleWidth(prefix);
+		// Icon column: every row reserves the same width so labels stay aligned
+		// whether or not an individual item carries an icon.
+		const iconWidth = item.icon ? visibleWidth(item.icon) : 0;
+		const iconCell = iconColumnWidth > 0 ? (item.icon ?? "") + padding(iconColumnWidth - iconWidth + 1) : "";
+		const prefixWidth = visibleWidth(prefix) + (iconColumnWidth > 0 ? iconColumnWidth + 1 : 0);
 		const descriptionSingleLine = item.description ? sanitizeSingleLine(item.description) : undefined;
 
 		if (descriptionSingleLine && width > 40) {
@@ -399,6 +441,7 @@ export class SelectList implements Component, MouseRoutable {
 				return {
 					kind: "description",
 					prefix,
+					iconCell,
 					truncatedValue,
 					spacing,
 					descriptionSingleLine,
@@ -413,11 +456,20 @@ export class SelectList implements Component, MouseRoutable {
 		return {
 			kind: "primary",
 			prefix,
+			iconCell,
 			truncatedValue,
 			spacing: "",
 		};
 	}
 
+	#getIconColumnWidth(): number {
+		let widest = 0;
+		for (const item of this.#filteredItems) {
+			if (item.icon) widest = Math.max(widest, visibleWidth(item.icon));
+		}
+		return widest;
+	}
+
 	#getPrimaryColumnWidth(): number {
 		const { min, max } = this.#getPrimaryColumnBounds();
 		const widestPrimary = this.#filteredItems.reduce((widest, item) => {

package/src/keybindings.ts

@@ -27,6 +27,7 @@ export interface Keybindings {
 	"tui.editor.yank": true;
 	"tui.editor.yankPop": true;
 	"tui.editor.undo": true;
+	"tui.editor.spellingSuggestions": true;
 	// Generic input actions
 	"tui.input.newLine": true;
 	"tui.input.submit": true;
@@ -118,6 +119,10 @@ export const TUI_KEYBINDINGS = {
 	"tui.editor.yank": { defaultKeys: "ctrl+y", description: "Yank" },
 	"tui.editor.yankPop": { defaultKeys: "alt+y", description: "Yank pop" },
 	"tui.editor.undo": { defaultKeys: ["ctrl+-", "ctrl+_"], description: "Undo" },
+	"tui.editor.spellingSuggestions": {
+		defaultKeys: "ctrl+.",
+		description: "Show spelling replacements",
+	},
 	"tui.input.newLine": { defaultKeys: ["shift+enter", "ctrl+j"], description: "Insert newline" },
 	"tui.input.submit": { defaultKeys: "enter", description: "Submit input" },
 	"tui.input.tab": { defaultKeys: "tab", description: "Tab / autocomplete" },

package/src/terminal-capabilities.ts

@@ -129,7 +129,13 @@ export class TerminalInfo {
 		if (this.imageProtocol === ImageProtocol.Sixel) {
 			return hasSixelDcsStart(line);
 		}
-		return hasNeedleBefore(line, this.imageProtocol, 64) || hasNeedleBefore(line, KITTY_PLACEHOLDER, 64);
+		// 512-unit window: placeholder cells can sit deep in a composed row —
+		// the composer attachment band prefixes each thumbnail row with border
+		// SGRs and stacks cards side by side, so the first placeholder of a
+		// later card starts hundreds of units in. Rows past the window would
+		// silently lose the verbatim image-line path (no truncation, no SGR
+		// coalescing) that placeholder grids and placement APCs rely on.
+		return hasNeedleBefore(line, this.imageProtocol, 512) || hasNeedleBefore(line, KITTY_PLACEHOLDER, 512);
 	}
 
 	formatNotification(message: string | TerminalNotification): string {