@oh-my-pi/pi-tui 18.0.7 → 18.0.9

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [18.0.9] - 2026-08-28
+
+### Added
+
+- Exported TuiDebugServer for programmatic headless control
+- Added debug demonstration script to examples
+- Added an `OMP_TUI_DEBUG` Unix socket for headless TUI driving and structured inspection.
+
+### Changed
+
+- Inline hex colors now render with VS Code-style colored backgrounds and automatically selected black or white text for readability, alongside the color swatch.
+- LaTeX text formatting commands such as \textbf, \textit, \textsl, and \emph now render as terminal bold or italic text.
+
+### Fixed
+
+- Fixed inline color swatches rendering incorrectly inside highlighted lines.
+- Fixed terminal resizing in tmux panes and Windows consoles duplicating the current in-progress turn in scrollback.
+
+## [18.0.8] - 2026-08-27
+
+### Added
+
+- `ProcessTerminal` accepts a `conpty` option to force ConPTY-hosted behavior on or off, keeping terminal tests hermetic on WSL where live env detection would otherwise flip kitty-keyboard flags and write chunking ([#9887](https://github.com/can1357/oh-my-pi/issues/9887)).
+
+### Fixed
+
+- Fixed pending-work animations repeatedly composing expensive frames without applying their full render cost to CPU backpressure.
+- Fixed unfinished live viewport rows entering tmux pane history and duplicating streamed output ([#9780](https://github.com/can1357/oh-my-pi/issues/9780)).
+
 ## [18.0.7] - 2026-08-26
 
 ### Breaking Changes

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

@@ -19,6 +19,8 @@ export declare class Box implements Component {
     children: Component[];
     setIgnoreTight(ignore: boolean): this;
     constructor(paddingX?: number, paddingY?: number, bgFn?: (text: string) => string, border?: BoxBorder);
+    /** Return container layout and child-count state for debug inspection. */
+    debugState(): Record<string, unknown>;
     addChild(component: Component): void;
     removeChild(component: Component): void;
     clear(): void;

package/dist/types/components/cancellable-loader.d.ts

@@ -16,6 +16,8 @@ export declare class CancellableLoader extends Loader {
     get signal(): AbortSignal;
     /** Whether the loader was aborted */
     get aborted(): boolean;
+    /** Return loader state including whether cancellation was requested. */
+    debugState(): Record<string, unknown>;
     handleInput(data: string): void;
     dispose(): void;
 }

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

@@ -92,6 +92,10 @@ export declare class Editor implements Component, Focusable {
     onAutocompleteCancel?: () => void;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
+    /** Return bounded editor content, cursor, and transient child state for debug inspection. */
+    debugState(): Record<string, unknown>;
+    /** Expose the active autocomplete list to the debug tree walker. */
+    get debugChildren(): readonly Component[];
     setTheme(theme: EditorTheme): void;
     setAutocompleteProvider(provider: AutocompleteProvider): void;
     /** Install prose assistance without changing command/file autocomplete. */

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

@@ -157,6 +157,8 @@ export declare class ImageBudget {
 export declare class Image implements Component {
     #private;
     constructor(base64Data: string, mimeType: string, theme: ImageTheme, options?: ImageOptions, dimensions?: ImageDimensions);
+    /** Return source metadata without exposing the encoded image buffer. */
+    debugState(): Record<string, unknown>;
     invalidate(): void;
     render(width: number): readonly string[];
 }

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

@@ -13,6 +13,8 @@ export declare class Input implements Component, Focusable {
     /** Focusable interface - set by TUI when focus changes */
     focused: boolean;
     getValue(): string;
+    /** Return bounded input content and cursor state for debug inspection. */
+    debugState(): Record<string, unknown>;
     setValue(value: string): void;
     setUseTerminalCursor(useTerminalCursor: boolean): void;
     getUseTerminalCursor(): boolean;

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

@@ -15,6 +15,8 @@ export declare class Loader extends Text {
     private messageColorFn;
     private message;
     constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string | (() => string), spinnerFrames?: string[]);
+    /** Return the current message and animation state for debug inspection. */
+    debugState(): Record<string, unknown>;
     render(width: number): readonly string[];
     start(): void;
     stop(): void;

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

@@ -79,6 +79,8 @@ export declare class Markdown implements Component {
     #private;
     setIgnoreTight(ignore: boolean): this;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
+    /** Return bounded source text and layout state for debug inspection. */
+    debugState(): Record<string, unknown>;
     setText(text: string): boolean;
     invalidate(): void;
     /**

package/dist/types/components/scroll-view.d.ts

@@ -36,6 +36,8 @@ export interface ScrollViewOptions {
 export declare class ScrollView implements Component {
     #private;
     constructor(lines: readonly string[], options: ScrollViewOptions);
+    /** Return viewport, content, and scroll position state for debug inspection. */
+    debugState(): Record<string, unknown>;
     setLines(lines: readonly string[]): void;
     setTotalRows(totalRows: number | undefined): void;
     setHeight(height: number): void;

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

@@ -58,6 +58,8 @@ export declare class SelectList implements Component, MouseRoutable {
     onCancel?: () => void;
     onSelectionChange?: (item: SelectItem) => void;
     constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
+    /** Return item, selection, and filter state for debug inspection. */
+    debugState(): Record<string, unknown>;
     /** Refit the visible row budget (hosts clamp the list to available height). */
     setMaxVisible(rows: number): void;
     setFilter(filter: string): void;

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

@@ -68,6 +68,10 @@ export declare class SettingsList implements Component {
     /** Fired when the selected item changes (navigation, filtering, or setItems). */
     onSelectionChange?: (item: SettingItem | undefined) => void;
     constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void, options?: SettingsListOptions);
+    /** Return item, selection, filter, and submenu state for debug inspection. */
+    debugState(): Record<string, unknown>;
+    /** Expose the active submenu to the debug tree walker. */
+    get debugChildren(): readonly Component[];
     /** The currently selected item, or undefined when empty or on a heading. */
     getSelectedItem(): SettingItem | undefined;
     /** Move selection to the item with `id`. Returns false when it is not visible. */

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

@@ -5,6 +5,8 @@ import type { Component } from "../tui.js";
 export declare class Spacer implements Component {
     #private;
     constructor(lines?: number);
+    /** Return the spacer height for debug inspection. */
+    debugState(): Record<string, unknown>;
     setLines(lines: number): void;
     invalidate(): void;
     render(_width: number): readonly string[];

package/dist/types/components/tab-bar.d.ts

@@ -45,6 +45,8 @@ export declare class TabBar implements Component {
     /** Render the trailing "(tab to cycle)" hint. Disable when the host folds the hint into its own footer. */
     showHint: boolean;
     constructor(label: string, tabs: Tab[], theme: TabBarTheme, initialIndex?: number);
+    /** Return tab identities and active-tab state for debug inspection. */
+    debugState(): Record<string, unknown>;
     /** Get the currently active tab */
     getActiveTab(): Tab;
     /** Get the index of the currently active tab */

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

@@ -12,6 +12,8 @@ export declare class Text implements Component {
     #private;
     setIgnoreTight(ignore: boolean): this;
     constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
+    /** Return bounded text and layout state for debug inspection. */
+    debugState(): Record<string, unknown>;
     getText(): string;
     setText(text: string): boolean;
     setCustomBgFn(customBgFn?: (text: string) => string): void;

package/dist/types/components/truncated-text.d.ts

@@ -5,6 +5,8 @@ import type { Component } from "../tui.js";
 export declare class TruncatedText implements Component {
     #private;
     constructor(text: string, paddingX?: number, paddingY?: number);
+    /** Return bounded source text and the last-known truncation state. */
+    debugState(): Record<string, unknown>;
     invalidate(): void;
     render(width: number): readonly string[];
 }

package/dist/types/debug-server.d.ts

@@ -0,0 +1,27 @@
+import { type TUI } from "./tui.js";
+export interface TuiDebugTreeNode {
+    kind: string;
+    id?: string;
+    rect?: [x: number, y: number, w: number, h: number];
+    focused?: boolean;
+    focusable?: boolean;
+    hidden?: boolean;
+    children?: TuiDebugTreeNode[];
+}
+export interface TuiDebugOverlayNode {
+    overlay: number;
+    band?: unknown;
+    hidden?: boolean;
+    root: TuiDebugTreeNode;
+}
+export interface TuiDebugTree {
+    root: TuiDebugTreeNode;
+    overlays: TuiDebugOverlayNode[];
+}
+/** NDJSON debug and input server enabled by the `OMP_TUI_DEBUG` socket path. */
+export declare class TuiDebugServer {
+    #private;
+    constructor(tui: TUI, path: string);
+    start(): void;
+    stop(): void;
+}

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./components/spacer.js";
 export * from "./components/tab-bar.js";
 export * from "./components/text.js";
 export * from "./components/truncated-text.js";
+export * from "./debug-server.js";
 export * from "./deccara.js";
 export * from "./desktop-notify.js";
 export type * from "./editor-component.js";

package/dist/types/latex-to-unicode.d.ts

@@ -1,8 +1,8 @@
 /**
- * Math font command names (`\mathbf`, `\mathbb`, …) whose single brace argument
- * restyles glyphs. Exported for the display block engine (`latex-block`), which
- * re-wraps inline runs inside these commands when their argument contains 2-D
- * layout (fractions, matrices) so styling survives box boundaries.
+ * Math font and text-style command names whose single brace argument
+ * is rendered with the corresponding style. Exported for the display block
+ * engine, which re-wraps inline runs inside these commands when their argument
+ * contains 2-D layout so styling survives box boundaries.
  */
 export declare const MATH_FONT_COMMANDS: ReadonlySet<string>;
 /**

package/dist/types/terminal.d.ts

@@ -172,11 +172,22 @@ export interface Terminal {
  * single predicate.
  */
 export declare function isConPTYHosted(): boolean;
+/** Construction-time overrides for {@link ProcessTerminal}. */
+export interface ProcessTerminalOptions {
+    /**
+     * Force ConPTY-hosted behavior on or off. Defaults to live detection via
+     * {@link isConPTYHosted}. Tests set this so the kitty-flag and write-chunking
+     * paths stay hermetic regardless of the ambient WSL env (`WSL_DISTRO_NAME` /
+     * `WSL_INTEROP`) — the suite must behave identically on WSL and on CI.
+     */
+    conpty?: boolean;
+}
 /**
  * Real terminal using process.stdin/stdout
  */
 export declare class ProcessTerminal implements Terminal {
     #private;
+    constructor(options?: ProcessTerminalOptions);
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
     get keyboardEnhancementEnterSequence(): string | null;

package/dist/types/tui.d.ts

@@ -76,6 +76,14 @@ export interface TUIStartOptions {
  * which leading rows survived.
  */
 export interface Component {
+    /** Stable identifier surfaced in the debug tree as kind#id. */
+    debugId?: string;
+    /** Override for the tree node kind (default: constructor.name). */
+    debugKind?: string;
+    /** Widget state for the debug `values`/`tree` ops. JSON-serializable. */
+    debugState?(): Record<string, unknown>;
+    /** Children for the debug tree when not already exposed as a public `children` array. */
+    debugChildren?: readonly Component[];
     /**
      * Render the component to an array of physical rows at the given width.
      * The result is component-owned and `readonly` to the caller; an unchanged
@@ -292,9 +300,31 @@ export declare class TUI extends Container {
      * positive report, disabled on a negative one.
      */
     get synchronizedOutput(): boolean;
+    /**
+     * Cost in milliseconds of the most recently completed frame.
+     *
+     * Animation components use this to apply proportional backpressure after
+     * their render request is asynchronously composed and written.
+     */
+    get lastFrameCostMs(): number;
     setFocus(component: Component | null): void;
     /** Component currently receiving keyboard input, if any. */
     getFocused(): Component | null;
+    /** Last viewport successfully written by the renderer, for debug inspection. */
+    getDebugPaint(): {
+        lines: readonly string[];
+        windowTop: number;
+        altScreen: boolean;
+        cursor?: {
+            x: number;
+            y: number;
+            visible?: boolean;
+        };
+    } | undefined;
+    /** Render the current root document at the live terminal width for debug inspection. */
+    getDebugDocument(): readonly string[];
+    /** Feed debug and test input through the same pipeline as terminal stdin. */
+    injectDebugInput(data: string): void;
     /**
      * Show an overlay component with configurable positioning and sizing.
      * Returns a handle to control the overlay's visibility.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.0.7",
+	"version": "18.0.9",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.0.7",
-		"@oh-my-pi/pi-utils": "18.0.7"
+		"@oh-my-pi/pi-natives": "18.0.9",
+		"@oh-my-pi/pi-utils": "18.0.9"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/components/box.ts

@@ -59,6 +59,16 @@ export class Box implements Component {
 		this.#bgFn = bgFn;
 		this.#border = border;
 	}
+	/** Return container layout and child-count state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		return {
+			childCount: this.children.length,
+			paddingX: this.#paddingX,
+			paddingY: this.#paddingY,
+			bordered: this.#border !== undefined,
+			ignoreTight: this.#ignoreTight,
+		};
+	}
 
 	addChild(component: Component): void {
 		this.children.push(component);

package/src/components/cancellable-loader.ts

@@ -25,6 +25,13 @@ export class CancellableLoader extends Loader {
 	get aborted(): boolean {
 		return this.#abortController.signal.aborted;
 	}
+	/** Return loader state including whether cancellation was requested. */
+	override debugState(): Record<string, unknown> {
+		return {
+			...super.debugState(),
+			cancelled: this.aborted,
+		};
+	}
 
 	handleInput(data: string): void {
 		const kb = getKeybindings();

package/src/components/editor.ts

@@ -595,6 +595,34 @@ export class Editor implements Component, Focusable {
 		this.#theme = theme;
 		this.borderColor = theme.borderColor;
 	}
+	/** Return bounded editor content, cursor, and transient child state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		const lines = this.#state.lines;
+		let textLength = Math.max(0, lines.length - 1);
+		let textPreview = "";
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i] ?? "";
+			textLength += line.length;
+			if (textPreview.length >= 120) continue;
+			if (i > 0) textPreview += "\n";
+			textPreview += line.slice(0, 120 - textPreview.length);
+		}
+		return {
+			textPreview,
+			textLength,
+			previewTruncated: textLength > 120,
+			cursorLine: this.#state.cursorLine,
+			cursorCol: this.#state.cursorCol,
+			lineCount: lines.length,
+			selection: null,
+			placeholderActive: false,
+		};
+	}
+
+	/** Expose the active autocomplete list to the debug tree walker. */
+	get debugChildren(): readonly Component[] {
+		return this.#autocompleteList ? [this.#autocompleteList] : [];
+	}
 
 	setTheme(theme: EditorTheme): void {
 		this.#theme = theme;

package/src/components/image.ts

@@ -505,6 +505,17 @@ export class Image implements Component {
 		this.#budget = options.budget;
 		this.#imageId = options.budget ? options.budget.acquireId(options.imageKey) : undefined;
 	}
+	/** Return source metadata without exposing the encoded image buffer. */
+	debugState(): Record<string, unknown> {
+		return {
+			mimeType: this.#mimeType,
+			widthPx: this.#dimensions.widthPx,
+			heightPx: this.#dimensions.heightPx,
+			filename: this.#options.filename ?? null,
+			imageId: this.#imageId ?? null,
+			suppressed: this.#cachedSuppressed,
+		};
+	}
 
 	invalidate(): void {
 		this.#cachedLines = undefined;

package/src/components/input.ts

@@ -51,6 +51,19 @@ export class Input implements Component, Focusable {
 	getValue(): string {
 		return this.#value;
 	}
+	/** Return bounded input content and cursor state for debug inspection. */
+	debugState(): Record<string, unknown> {
+		return {
+			textPreview: this.#value.slice(0, 120),
+			textLength: this.#value.length,
+			previewTruncated: this.#value.length > 120,
+			cursor: this.#cursor,
+			cursorLine: 0,
+			selection: null,
+			placeholderActive: false,
+			masked: this.mask,
+		};
+	}
 
 	setValue(value: string): void {
 		this.#value = value;

package/src/components/loader.ts

@@ -5,6 +5,7 @@ import { Text } from "./text";
 const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
 const RENDER_BACKPRESSURE_MULTIPLIER = 9;
+const MAX_BACKPRESSURE_FRAME_COST_MS = 200;
 
 type ColorFn = (str: string) => string;
 
@@ -53,6 +54,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);
@@ -139,12 +150,17 @@ export class Loader extends Text {
 				this.#requestPaint();
 			}
 
-			const frameCostMs = performance.now() - startedAt;
+			const completedFrameCostMs = this.#ui?.lastFrameCostMs ?? 0;
+			const requestCostMs = performance.now() - startedAt;
 			if (this.#intervalId !== timer) return;
-			const cadenceDelayMs = Math.max(0, intervalMs - frameCostMs);
-			// Idle for nine times the paint cost to keep animation at or below
-			// 10% CPU, even when a slow ConPTY write exceeds the normal cadence.
-			const backpressureDelayMs = frameCostMs * RENDER_BACKPRESSURE_MULTIPLIER;
+			const cadenceDelayMs = Math.max(0, intervalMs - requestCostMs);
+			// Idle for nine times the full frame cost to keep animation at or
+			// below 10% CPU even though requestComponentRender() only enqueues.
+			const boundedFrameCostMs = Math.min(
+				MAX_BACKPRESSURE_FRAME_COST_MS,
+				Math.max(completedFrameCostMs, requestCostMs),
+			);
+			const backpressureDelayMs = boundedFrameCostMs * RENDER_BACKPRESSURE_MULTIPLIER;
 			this.#scheduleTick(intervalMs, Math.max(cadenceDelayMs, backpressureDelayMs));
 		}, delayMs);
 		this.#intervalId = timer;

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;