@oh-my-pi/pi-tui 18.0.8 → 18.0.10

package/src/components/loader.ts

@@ -1,9 +1,10 @@
 import type { TUI } from "../tui";
-import { getPaddingX, sliceByColumn, visibleWidth } from "../utils";
+import { getPaddingX, padding, sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
 const RENDER_INTERVAL_MS = 1000 / 30;
-const SPINNER_ADVANCE_MS = 80;
+/** Milliseconds between spinner-frame advances; exported so time-derived spinners elsewhere tick at the Loader cadence. */
+export const SPINNER_ADVANCE_MS = 80;
 const RENDER_BACKPRESSURE_MULTIPLIER = 9;
 const MAX_BACKPRESSURE_FRAME_COST_MS = 200;
 
@@ -28,6 +29,7 @@ export class Loader extends Text {
 	#layout?: readonly { leading: string; content: string; trailing: string }[];
 	#layoutFrames: readonly string[];
 	#layoutFrame: string;
+	#trailer?: () => string | undefined;
 
 	constructor(
 		ui: TUI,
@@ -54,6 +56,16 @@ export class Loader extends Text {
 		this.#layoutFrame = this.#layoutFrames[0];
 		this.start();
 	}
+	/** Return the current message and animation state for debug inspection. */
+	override debugState(): Record<string, unknown> {
+		const message = this.#resolveMessage();
+		return {
+			message: message.slice(0, 120),
+			messageLength: message.length,
+			running: this.#intervalId !== undefined,
+			frame: this.#currentFrame,
+		};
+	}
 
 	override render(width: number): readonly string[] {
 		const source = super.render(width);
@@ -92,6 +104,15 @@ export class Loader extends Text {
 				lines.push(`${leading}${content ? this.messageColorFn(content) : ""}${trailing}`);
 			}
 		}
+		if (this.#trailer && lines.length > 1) {
+			const trailer = this.#trailer();
+			if (trailer) {
+				// Text pads rows to full width; drop that pad before docking right.
+				const body = lines[1].trimEnd();
+				const gap = width - visibleWidth(body) - visibleWidth(trailer);
+				if (gap >= 2) lines[1] = body + padding(gap) + trailer;
+			}
+		}
 		return lines;
 	}
 
@@ -114,6 +135,12 @@ export class Loader extends Text {
 	dispose() {
 		this.stop();
 	}
+	/** Install a lazy right-docked suffix for the spinner row (e.g. a styled
+	 * session title). Re-evaluated every paint; dropped when the row leaves
+	 * less than a two-cell gap. */
+	setTrailer(trailer: (() => string | undefined) | undefined): void {
+		this.#trailer = trailer;
+	}
 
 	setMessage(message: string) {
 		if (message === this.message) {

package/src/components/markdown.ts

@@ -1539,12 +1539,28 @@ function classifyHexColor(hex: string, strict: boolean): boolean {
 	return true;
 }
 
-/** ANSI-painted `glyph` for `#${hex}`, or "" when the color can't be encoded. */
-function colorSwatch(hex: string, glyph: string): string {
-	const ansi = Bun.color(`#${hex}`, TERMINAL.trueColor ? "ansi-16m" : "ansi-256");
-	// Reset only the foreground (\x1b[39m) so an enclosing background/decoration
-	// applied later by the line renderer survives across the swatch.
-	return ansi ? `${ansi}${glyph}\x1b[39m ` : "";
+/** Black-or-white foreground legible on `#${hex}` used as a fill. VS Code's
+ *  rule (Color.isLighter): YIQ brightness (r·299 + g·587 + b·114)/1000 ≥ 128
+ *  → dark text, else light. */
+function swatchContrastFg(hex: string): string {
+	const rgba = Bun.color(`#${hex}`, "{rgba}");
+	if (!rgba) return "";
+	const light = (rgba.r * 299 + rgba.g * 587 + rgba.b * 114) / 1000 >= 128;
+	if (TERMINAL.trueColor) return light ? "\x1b[38;2;0;0;0m" : "\x1b[38;2;255;255;255m";
+	return light ? "\x1b[38;5;16m" : "\x1b[38;5;231m";
+}
+
+/** Chip glyph + `text` (the `#hex` mention) painted onto the color itself:
+ *  a fg-painted chip, then the token with the color as background and a
+ *  YIQ-contrast foreground (VS Code's color-picker rule). Returns "" when the
+ *  color can't be encoded. Foreground closes with \x1b[39m and background with
+ *  a standalone \x1b[49m so line-level backgrounds re-open themselves via
+ *  applyBackgroundToLine / Theme.bgFill. */
+function colorSwatch(hex: string, glyph: string, text: string): string {
+	const fg = Bun.color(`#${hex}`, TERMINAL.trueColor ? "ansi-16m" : "ansi-256");
+	if (!fg) return "";
+	const bg = fg.replace("[38;", "[48;");
+	return `${fg}${glyph}\x1b[39m ${bg}${swatchContrastFg(hex)}${text}\x1b[39m\x1b[49m`;
 }
 
 /**
@@ -1560,10 +1576,10 @@ function renderTextWithSwatches(text: string, applySegment: (t: string) => strin
 		const match = HEX_COLOR_REGEX.exec(text);
 		if (match === null) break;
 		if (!classifyHexColor(match[1], true)) continue;
-		const swatch = colorSwatch(match[1], glyph);
+		const swatch = colorSwatch(match[1], glyph, match[0]);
 		if (!swatch) continue;
 		if (match.index > last) result += applySegment(text.slice(last, match.index));
-		result += swatch + applySegment(match[0]);
+		result += swatch;
 		last = match.index + match[0].length;
 	}
 	if (last === 0) return applySegment(text);
@@ -1575,7 +1591,7 @@ function renderTextWithSwatches(text: string, applySegment: (t: string) => strin
 function codespanSwatch(code: string, glyph: string): string {
 	const match = HEX_COLOR_EXACT_REGEX.exec(code.trim());
 	if (!match || !classifyHexColor(match[1], false)) return "";
-	return colorSwatch(match[1], glyph);
+	return colorSwatch(match[1], glyph, match[0]);
 }
 
 interface RenderSignature {
@@ -1757,6 +1773,18 @@ export class Markdown implements Component {
 		this.#defaultTextStyle = defaultTextStyle;
 		this.#codeBlockIndent = Math.max(0, Math.floor(codeBlockIndent));
 	}
+	/** Return bounded source text and layout state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		return {
+			textPreview: this.#text.slice(0, 120),
+			textLength: this.#text.length,
+			previewTruncated: this.#text.length > 120,
+			paddingX: this.#paddingX,
+			paddingY: this.#paddingY,
+			codeBlockIndent: this.#codeBlockIndent,
+			ignoreTight: this.#ignoreTight,
+		};
+	}
 
 	setText(text: string): boolean {
 		// Identical re-emit (throttled tick): fully normalized already.
@@ -3118,7 +3146,8 @@ export class Markdown implements Component {
 
 				case "codespan": {
 					markHtmlItemWhenContent(token.text);
-					result += codespanSwatch(token.text, swatchGlyph) + this.#theme.code(token.text) + stylePrefix;
+					const painted = codespanSwatch(token.text, swatchGlyph);
+					result += (painted || this.#theme.code(token.text)) + stylePrefix;
 					break;
 				}
 

package/src/components/scroll-view.ts

@@ -79,6 +79,18 @@ export class ScrollView implements Component {
 		this.#fastScrollLines = Math.max(1, Math.trunc(options.fastScrollLines ?? 5));
 		this.#clampScrollOffset();
 	}
+	/** Return viewport, content, and scroll position state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		return {
+			scrollOffset: this.#scrollOffset,
+			maxScrollOffset: this.getMaxScrollOffset(),
+			height: this.#height,
+			rowCount,
+			bufferedLineCount: this.#lines.length,
+			scrollbar: this.#scrollbar,
+		};
+	}
 
 	setLines(lines: readonly string[]): void {
 		this.#lines = [...lines];

package/src/components/select-list.ts

@@ -116,6 +116,19 @@ export class SelectList implements Component, MouseRoutable {
 		this.#maxVisible = Math.max(1, Math.trunc(maxVisible));
 		this.#filteredItems = items;
 	}
+	/** Return item, selection, and filter state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		const selected = this.#filteredItems[this.#selectedIndex];
+		return {
+			itemCount: this.items.length,
+			filteredItemCount: this.#filteredItems.length,
+			selectedIndex: this.#filteredItems.length > 0 ? this.#selectedIndex : -1,
+			selectedItemId: selected?.value ?? null,
+			selectedItemLabel: selected?.label ?? null,
+			filterText: this.#filterQuery,
+			maxVisible: this.#maxVisible,
+		};
+	}
 
 	/** Refit the visible row budget (hosts clamp the list to available height). */
 	setMaxVisible(rows: number): void {

package/src/components/settings-list.ts

@@ -142,6 +142,25 @@ export class SettingsList implements Component {
 		this.#selectedIndex = this.#firstSelectableIndex();
 		this.#lastNotifiedSelectionId = this.getSelectedItem()?.id;
 	}
+	/** Return item, selection, filter, and submenu state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		const selected = this.getSelectedItem();
+		return {
+			itemCount: this.#items.length,
+			filteredItemCount: this.#filteredItems.length,
+			selectedIndex: this.#filteredItems.length > 0 ? this.#selectedIndex : -1,
+			selectedItemId: selected?.id ?? null,
+			selectedItemLabel: selected?.label ?? null,
+			filterText: this.#filterQuery,
+			sectionFocused: this.#sectionFocus,
+			submenuOpen: this.#submenuComponent !== null,
+		};
+	}
+
+	/** Expose the active submenu to the debug tree walker. */
+	get debugChildren(): readonly Component[] {
+		return this.#submenuComponent ? [this.#submenuComponent] : [];
+	}
 
 	/** The currently selected item, or undefined when empty or on a heading. */
 	getSelectedItem(): SettingItem | undefined {

package/src/components/spacer.ts

@@ -10,6 +10,10 @@ export class Spacer implements Component {
 	constructor(lines: number = 1) {
 		this.#lines = lines;
 	}
+	/** Return the spacer height for debug inspection. */
+	debugState(): Record<string, unknown> {
+		return { height: this.#lines };
+	}
 
 	setLines(lines: number): void {
 		if (lines === this.#lines) return;

package/src/components/tab-bar.ts

@@ -74,6 +74,17 @@ export class TabBar implements Component {
 		this.#theme = theme;
 		this.#activeIndex = initialIndex;
 	}
+	/** Return tab identities and active-tab state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		const active = this.#tabs[this.#activeIndex];
+		return {
+			label: this.#label,
+			tabs: this.#tabs.map(tab => ({ id: tab.id, label: tab.label })),
+			activeIndex: this.#tabs.length > 0 ? this.#activeIndex : -1,
+			activeTabId: active?.id ?? null,
+			activeTabLabel: active?.label ?? null,
+		};
+	}
 
 	/** Get the currently active tab */
 	getActiveTab(): Tab {

package/src/components/text.ts

@@ -46,6 +46,17 @@ export class Text implements Component {
 		this.#paddingY = paddingY;
 		this.#customBgFn = customBgFn;
 	}
+	/** Return bounded text and layout state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		return {
+			textPreview: this.#text.slice(0, 120),
+			textLength: this.#text.length,
+			previewTruncated: this.#text.length > 120,
+			paddingX: this.#paddingX,
+			paddingY: this.#paddingY,
+			ignoreTight: this.#ignoreTight,
+		};
+	}
 
 	getText(): string {
 		return this.#text;

package/src/components/truncated-text.ts

@@ -1,5 +1,5 @@
 import type { Component } from "../tui";
-import { padding, truncateToWidth } from "../utils";
+import { padding, truncateToWidth, visibleWidth } from "../utils";
 
 /**
  * Text component that truncates to fit viewport width
@@ -16,6 +16,20 @@ export class TruncatedText implements Component {
 		this.#paddingX = paddingX;
 		this.#paddingY = paddingY;
 	}
+	/** Return bounded source text and the last-known truncation state. */
+	debugState(): Record<string, unknown> {
+		const newlineIndex = this.#text.indexOf("\n");
+		const firstLine = newlineIndex === -1 ? this.#text : this.#text.slice(0, newlineIndex);
+		const availableWidth = Math.max(1, this.#cachedWidth - this.#paddingX * 2);
+		return {
+			textPreview: this.#text.slice(0, 120),
+			textLength: this.#text.length,
+			previewTruncated: this.#text.length > 120,
+			truncated: newlineIndex !== -1 || (this.#cachedWidth >= 0 && visibleWidth(firstLine) > availableWidth),
+			paddingX: this.#paddingX,
+			paddingY: this.#paddingY,
+		};
+	}
 
 	invalidate(): void {
 		this.#cachedWidth = -1;