@oh-my-pi/pi-tui 15.10.8 → 15.10.9

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [15.10.9] - 2026-06-09
+
+### Added
+
+- Added a `wrapDescription` option to `SelectListLayoutOptions`. When enabled, long descriptions wrap onto continuation rows indented under the description column instead of being silently truncated. The slash-command/skill autocomplete picker now opts in so descriptions like the bundled skills' remain fully readable at normal terminal widths. `maxVisible` becomes the picker's visual row budget so the popup height stays bounded even when items wrap (a single 5-row description with `maxVisible=3` clips with the scrollbar carrying the offscreen tail). Navigation stays item-to-item, the narrow-width fallback (`width <= 40`) is unchanged, and the `ScrollView` scrollbar tracks visual rows so the thumb stays correct when items wrap unevenly. ([#2169](https://github.com/can1357/oh-my-pi/issues/2169))
+
+### Fixed
+
+- Fixed Ghostty's first inline image in a fresh TUI session sometimes rendering as an empty placeholder block by holding the initial Kitty graphics paint until the terminal startup settle window has passed. Direct Kitty placements also keep their zero-width reservation rows non-plain so image-only transcript blocks do not collapse when blank-edge trimming runs.
+
 ## [15.10.8] - 2026-06-09
 
 ### Fixed

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

@@ -73,6 +73,8 @@ export declare class ImageBudget {
      * repeated call (e.g. a width-change re-render) never re-sends the data.
      */
     enqueueTransmit(imageId: number, sequence: string): void;
+    /** Whether a frame has image data queued but not yet written to the terminal. */
+    hasPendingTransmits(): boolean;
     /** Transmit sequences to write before this frame's placements; clears the queue. */
     takeTransmits(): readonly string[];
 }

package/dist/types/components/select-list.d.ts

@@ -28,6 +28,14 @@ export interface SelectListLayoutOptions {
     truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
     /** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
     overflowSearch?: boolean;
+    /**
+     * Wrap long descriptions onto continuation rows indented under the
+     * description column instead of truncating. Defaults to false so existing
+     * single-line consumers are unaffected. Navigation remains item-to-item;
+     * the scrollbar tracks visual rows so the thumb stays correct when items
+     * wrap unevenly.
+     */
+    wrapDescription?: boolean;
 }
 export declare class SelectList implements Component {
     #private;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.10.8",
+	"version": "15.10.9",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.10.8",
-		"@oh-my-pi/pi-utils": "15.10.8",
+		"@oh-my-pi/pi-natives": "15.10.9",
+		"@oh-my-pi/pi-utils": "15.10.9",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/editor.ts

@@ -27,6 +27,7 @@ const SLASH_COMMAND_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
 	minPrimaryColumnWidth: 12,
 	maxPrimaryColumnWidth: 32,
 	overflowSearch: false,
+	wrapDescription: true,
 };
 
 function sanitizeLoadedText(text: string): string {

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;
@@ -188,6 +191,11 @@ 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;
+	}
+
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
 	takeTransmits(): readonly string[] {
 		if (this.#pendingTransmits.length === 0) return EMPTY_TRANSMITS;
@@ -296,7 +304,7 @@ 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 ?? ""));

package/src/components/select-list.ts

@@ -3,7 +3,7 @@ import { getKeybindings } from "../keybindings";
 import { extractPrintableText } from "../keys";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
-import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 import { ScrollView } from "./scroll-view";
 
 const DEFAULT_PRIMARY_COLUMN_WIDTH = 32;
@@ -50,8 +50,33 @@ export interface SelectListLayoutOptions {
 	truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
 	/** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
 	overflowSearch?: boolean;
+	/**
+	 * Wrap long descriptions onto continuation rows indented under the
+	 * description column instead of truncating. Defaults to false so existing
+	 * single-line consumers are unaffected. Navigation remains item-to-item;
+	 * the scrollbar tracks visual rows so the thumb stays correct when items
+	 * wrap unevenly.
+	 */
+	wrapDescription?: boolean;
 }
 
+type SelectItemLayout =
+	| {
+			kind: "description";
+			prefix: string;
+			truncatedValue: string;
+			spacing: string;
+			descriptionSingleLine: string;
+			descriptionStart: number;
+			remainingWidth: number;
+	  }
+	| {
+			kind: "primary";
+			prefix: string;
+			truncatedValue: string;
+			spacing: "";
+	  };
+
 export class SelectList implements Component {
 	#filteredItems: ReadonlyArray<SelectItem>;
 	#filterQuery = "";
@@ -96,34 +121,58 @@ export class SelectList implements Component {
 		}
 
 		const primaryColumnWidth = this.#getPrimaryColumnWidth();
+		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.
+		const visualBudget = this.maxVisible;
+
+		// Compute per-item visual row counts at the conservative width (i.e.
+		// assume the scrollbar column might be reserved). For non-wrap layouts
+		// every count is 1, so visualTotal == #filteredItems and overflow falls
+		// back to the original `N > maxVisible` predicate exactly.
+		const conservativeRowWidth = Math.max(0, width - 1);
+		const rowCounts = new Array<number>(this.#filteredItems.length);
+		let visualTotal = 0;
+		for (let i = 0; i < this.#filteredItems.length; i++) {
+			const item = this.#filteredItems[i];
+			if (!item) {
+				rowCounts[i] = 0;
+				continue;
+			}
+			rowCounts[i] = wrapEnabled ? this.#computeItemRowCount(item, conservativeRowWidth, primaryColumnWidth) : 1;
+			visualTotal += rowCounts[i];
+		}
 
-		// Calculate visible range with scrolling
-		const startIndex = Math.max(
-			0,
-			Math.min(this.#selectedIndex - Math.floor(this.maxVisible / 2), this.#filteredItems.length - this.maxVisible),
-		);
-		const endIndex = Math.min(startIndex + this.maxVisible, this.#filteredItems.length);
-
-		// Render visible items
-		const overflow = this.#filteredItems.length > this.maxVisible;
+		const overflow = visualTotal > visualBudget;
 		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+
+		// Pick a window centered on the selected item that fits in visualBudget
+		// rows. Falls through to the original item-count window when every row
+		// count is 1.
+		const { startIndex, endIndex, visualOffset } = this.#pickWindow(rowCounts, visualBudget);
+
+		// Render visible items. Cap rows at the budget so a single item that
+		// wraps to more than `visualBudget` rows (pathological — e.g. a 5-row
+		// description with maxVisible=3) still keeps the popup bounded; the
+		// scrollbar carries the offscreen rows.
 		const rows: string[] = [];
-		for (let i = startIndex; i < endIndex; i++) {
+		for (let i = startIndex; i < endIndex && rows.length < visualBudget; i++) {
 			const item = this.#filteredItems[i];
 			if (!item) continue;
-
-			const isSelected = i === this.#selectedIndex;
-			const descriptionText = item.description ? sanitizeSingleLine(item.description) : undefined;
-			rows.push(this.#renderItem(item, isSelected, rowWidth, descriptionText, primaryColumnWidth));
+			const itemRows = this.#renderItem(item, i === this.#selectedIndex, rowWidth, primaryColumnWidth);
+			for (const row of itemRows) {
+				if (rows.length >= visualBudget) break;
+				rows.push(row);
+			}
 		}
 
 		const sv = new ScrollView(rows, {
 			height: rows.length,
 			scrollbar: "auto",
-			totalRows: this.#filteredItems.length,
+			totalRows: visualTotal,
 			theme: { track: t => this.theme.scrollInfo(t), thumb: t => this.theme.selectedPrefix(t) },
 		});
-		sv.setScrollOffset(startIndex);
+		sv.setScrollOffset(visualOffset);
 		lines.push(...sv.render(width));
 
 		// Add search status when relevant (scrollbar now indicates overflow)
@@ -178,17 +227,112 @@ export class SelectList implements Component {
 		}
 	}
 
-	#renderItem(
+	#renderItem(item: SelectItem, isSelected: boolean, width: number, primaryColumnWidth: number): string[] {
+		const layout = this.#computeItemLayout(item, isSelected, width, primaryColumnWidth);
+		const { prefix, truncatedValue, spacing } = layout;
+
+		if (layout.kind === "description") {
+			const { descriptionSingleLine, descriptionStart, remainingWidth } = layout;
+			if (this.layout.wrapDescription) {
+				const wrapped = wrapTextWithAnsi(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}`)];
+					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)];
+				for (let i = 1; i < wrapped.length; i++) {
+					rows.push(this.theme.description(`${indent}${wrapped[i]}`));
+				}
+				return rows;
+			}
+
+			const truncatedDesc = truncateToWidth(descriptionSingleLine, remainingWidth, Ellipsis.Omit);
+			if (isSelected) {
+				return [this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`)];
+			}
+			return [prefix + truncatedValue + this.theme.description(spacing + truncatedDesc)];
+		}
+
+		if (isSelected) {
+			return [this.theme.selectedText(`${prefix}${truncatedValue}`)];
+		}
+		return [prefix + truncatedValue];
+	}
+
+	#computeItemRowCount(item: SelectItem, width: number, primaryColumnWidth: 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);
+		if (layout.kind !== "description") return 1;
+		const wrapped = wrapTextWithAnsi(layout.descriptionSingleLine, layout.remainingWidth);
+		return Math.max(1, wrapped.length);
+	}
+
+	/**
+	 * Pick a contiguous window of items containing `selectedIndex` such that
+	 * their visual rows fit within `budget`. Centers the selection roughly
+	 * mid-window: first expands up by ⌊budget/2⌋ rows, then fills downward,
+	 * then back upward with any remaining budget. For non-wrap layouts (every
+	 * `rowCounts[i] === 1`) this resolves to the same `[start, start+maxVisible)`
+	 * window the prior arithmetic produced.
+	 */
+	#pickWindow(
+		rowCounts: ReadonlyArray<number>,
+		budget: number,
+	): { startIndex: number; endIndex: number; visualOffset: number } {
+		const n = rowCounts.length;
+		const selected = Math.max(0, Math.min(this.#selectedIndex, n - 1));
+		if (n === 0) return { startIndex: 0, endIndex: 0, visualOffset: 0 };
+
+		const half = Math.floor(budget / 2);
+		let lo = selected;
+		let rowsAboveSelected = 0;
+		// Step 1: expand upward up to `half` rows above the selection so it
+		// lands near the visual middle, matching the prior centering.
+		while (lo > 0 && rowsAboveSelected + (rowCounts[lo - 1] ?? 0) <= half) {
+			lo--;
+			rowsAboveSelected += rowCounts[lo] ?? 0;
+		}
+
+		// Step 2: expand downward until the budget is filled. The selected
+		// item's own rows are always counted; if it alone exceeds `budget`
+		// the surplus is clipped at render time and the scrollbar carries it.
+		let hi = selected + 1;
+		let used = rowsAboveSelected + (rowCounts[selected] ?? 0);
+		while (hi < n && used + (rowCounts[hi] ?? 0) <= budget) {
+			used += rowCounts[hi] ?? 0;
+			hi++;
+		}
+
+		// Step 3: if room remains (selection sat near the bottom), keep
+		// expanding upward.
+		while (lo > 0 && used + (rowCounts[lo - 1] ?? 0) <= budget) {
+			lo--;
+			used += rowCounts[lo] ?? 0;
+		}
+
+		let visualOffset = 0;
+		for (let i = 0; i < lo; i++) visualOffset += rowCounts[i] ?? 0;
+		return { startIndex: lo, endIndex: hi, visualOffset };
+	}
+
+	#computeItemLayout(
 		item: SelectItem,
 		isSelected: boolean,
 		width: number,
-		descriptionSingleLine: string | undefined,
 		primaryColumnWidth: number,
-	): string {
+	): SelectItemLayout {
 		const prefix = isSelected
 			? `${this.theme.symbols.cursor} `
 			: padding(visibleWidth(this.theme.symbols.cursor) + 1);
 		const prefixWidth = visibleWidth(prefix);
+		const descriptionSingleLine = item.description ? sanitizeSingleLine(item.description) : undefined;
 
 		if (descriptionSingleLine && width > 40) {
 			const effectivePrimaryColumnWidth = Math.max(1, Math.min(primaryColumnWidth, width - prefixWidth - 4));
@@ -200,23 +344,26 @@ export class SelectList implements Component {
 			const remainingWidth = width - descriptionStart - 2; // -2 for safety
 
 			if (remainingWidth > MIN_DESCRIPTION_WIDTH) {
-				const truncatedDesc = truncateToWidth(descriptionSingleLine, remainingWidth, Ellipsis.Omit);
-				if (isSelected) {
-					return this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`);
-				}
-
-				const descText = this.theme.description(spacing + truncatedDesc);
-				return prefix + truncatedValue + descText;
+				return {
+					kind: "description",
+					prefix,
+					truncatedValue,
+					spacing,
+					descriptionSingleLine,
+					descriptionStart,
+					remainingWidth,
+				};
 			}
 		}
 
-		const maxWidth = width - prefixWidth - 2;
-		const truncatedValue = this.#truncatePrimary(item, isSelected, maxWidth, maxWidth);
-		if (isSelected) {
-			return this.theme.selectedText(`${prefix}${truncatedValue}`);
-		}
-
-		return prefix + truncatedValue;
+		const fallbackMax = width - prefixWidth - 2;
+		const truncatedValue = this.#truncatePrimary(item, isSelected, fallbackMax, fallbackMax);
+		return {
+			kind: "primary",
+			prefix,
+			truncatedValue,
+			spacing: "",
+		};
 	}
 
 	#getPrimaryColumnWidth(): number {

package/src/tui.ts

@@ -494,6 +494,10 @@ export class TUI extends Container {
 	// arrives (issue #2088). Coalescing every SIGWINCH inside this window into
 	// a single forced render lets the multiplexer settle first.
 	static readonly #MULTIPLEXER_RESIZE_DEBOUNCE_MS = 50;
+	// Ghostty can drop Kitty graphics commands sent during its first post-startup
+	// settle window, leaving only Unicode placeholder cells. Hold the first image
+	// paint until that window has passed; later images render normally.
+	static readonly #GHOSTTY_INITIAL_IMAGE_DELAY_MS = 100;
 	// Post-paint settle window for ConPTY hosts. The `sessionReplace` /
 	// `historyRebuild` / `overlayRebuild` intents drive `#emitFullPaint` over
 	// a transcript that overflows the viewport, scroll-pushing everything past
@@ -560,6 +564,9 @@ export class TUI extends Container {
 	// Caps how many inline images render as live graphics; older ones fall back
 	// to text via a purge + full redraw. Cap is configured by the host app.
 	#imageBudget = new ImageBudget(DEFAULT_MAX_INLINE_IMAGES, () => this.requestRender());
+	#ghosttyInitialImageDelayDone = false;
+	#ghosttyInitialImageDelayTimer: RenderTimer | undefined;
+	#ghosttyImageReadyAtMs = 0;
 	#clearScrollbackOnNextRender = false;
 	#forceViewportRepaintOnNextRender = false;
 	#allowUnknownViewportMutationOnNextRender = false;
@@ -889,6 +896,8 @@ export class TUI extends Container {
 
 	start(options?: TUIStartOptions): void {
 		this.#stopped = false;
+		this.#ghosttyInitialImageDelayDone = false;
+		this.#ghosttyImageReadyAtMs = this.#renderScheduler.now() + TUI.#GHOSTTY_INITIAL_IMAGE_DELAY_MS;
 		// A DECRQM report for mode 2026 is authoritative: enable synchronized
 		// output when the terminal reports support (upgrading conservatively
 		// defaulted-off hosts like zellij/tmux-master/foot) and disable it when
@@ -1127,6 +1136,10 @@ export class TUI extends Container {
 			this.#renderTimer.cancel();
 			this.#renderTimer = undefined;
 		}
+		if (this.#ghosttyInitialImageDelayTimer) {
+			this.#ghosttyInitialImageDelayTimer.cancel();
+			this.#ghosttyInitialImageDelayTimer = undefined;
+		}
 		if (this.#multiplexerResizeTimer) {
 			this.#multiplexerResizeTimer.cancel();
 			this.#multiplexerResizeTimer = undefined;
@@ -1371,6 +1384,32 @@ export class TUI extends Container {
 		}
 		this.#postFullPaintSettleUntilMs = 0;
 	}
+
+	#maybeDeferGhosttyInitialImagePaint(): boolean {
+		if (this.#ghosttyInitialImageDelayDone) return false;
+		if (TERMINAL.id !== "ghostty" || TERMINAL.imageProtocol !== ImageProtocol.Kitty) {
+			this.#ghosttyInitialImageDelayDone = true;
+			return false;
+		}
+		if (!this.#imageBudget.hasPendingTransmits()) return false;
+		if (this.#ghosttyInitialImageDelayTimer) return true;
+
+		const delayMs = Math.max(0, this.#ghosttyImageReadyAtMs - this.#renderScheduler.now());
+		if (delayMs === 0) {
+			this.#ghosttyInitialImageDelayDone = true;
+			return false;
+		}
+
+		this.#ghosttyInitialImageDelayTimer = this.#renderScheduler.scheduleRender(() => {
+			this.#ghosttyInitialImageDelayTimer = undefined;
+			this.#ghosttyInitialImageDelayDone = true;
+			if (this.#stopped) return;
+			this.#lastRenderAt = this.#renderScheduler.now();
+			this.#doRender();
+			if (this.#renderRequested) this.#scheduleRender();
+		}, delayMs);
+		return true;
+	}
 	#prepareForcedRender(clearScrollback: boolean): void {
 		const geometryChanged =
 			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
@@ -1984,6 +2023,7 @@ export class TUI extends Container {
 		// paints, so subsequent frames re-emit only the tiny placement sequence.
 		// `a=t` produces no display, so writing it ahead of the synchronized paint
 		// is artifact-free.
+		if (this.#maybeDeferGhosttyInitialImagePaint()) return;
 		const imageTransmits = this.#imageBudget.takeTransmits();
 		if (imageTransmits.length > 0) {
 			let transmitBuffer = "";