@oh-my-pi/pi-tui 15.11.2 → 15.11.4

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## [Unreleased]
 
+## [15.11.4] - 2026-06-12
+### Added
+
+- Added `partialHoldTimeout` to `StdinBufferOptions` to control the maximum extra delay held for unambiguous incomplete escape sequences before they are flushed
+- Added `SettingsList.sidebarWidth` option for a fixed split-layout sidebar width
+- Added mouse pointer support APIs to `SettingsList` with `setHoverItem`, `hitTest`, `hoverTest`, and `routeSubmenuMouse` for row targeting and submenu routing
+- Added `SettingsList.setMaxVisible(rows)` and `SettingsList.handleWheel(delta)` for dynamic viewport sizing and mouse-wheel step selection
+- Added compact tab features with new `Tab.short` labels and `TabBar.selectTab(id)` for id-based activation of non-muted tabs
+- Added pointer-hover and hit-testing APIs to `TabBar` with `setHoverTab`, `tabAt`, and `hoverTab` theme
+- Added exported SGR mouse utilities `parseSgrMouse`, `SgrMouseEvent`, and `MouseRoutable`
+- Added section support to `SettingsList`: `SettingItem.heading` rows split the list into sections, PgUp/PgDn (`tui.select.pageUp`/`pageDown`) jump between sections (or page when none exist), and wide renders use a split layout — section sidebar on the left, the active section's items on the right — falling back to inline heading rows when the width cannot fit both panes. Headings are skipped by navigation, excluded from search, and styled through the optional `SettingsListTheme.heading` (which receives a `dimmed` flag for headings outside the active section) and `section`.
+- Added a host-integration surface to `SettingsList`: a `SettingsListOptions` constructor arg (`layout` to force the flat layout, `typeToSearch: false` to hand the query to a parent, `emptyText`, `hint`), `selectItem(id)`, `getSelectedItem()`, `onSelectionChange`, `hasOpenSubmenu()`, and the exported `getSettingItemFilterText` helper.
+- Added keyboard section focus to `SettingsList`: `toggleSectionFocus()` / `sectionFocused` / `hasSectionFocusTargets()` flip Up/Down between row navigation and whole-section jumps — the cursor glyph parks on the active sidebar entry (or the active heading row in the flat layout) while the row cursor hides, Enter/Esc drop focus back to the rows, and any explicit row selection (`selectItem`, wheel, filtering) exits it.
+- Added muted tabs to `TabBar` (`Tab.muted` + `TabBarTheme.mutedTab`, skipped by keyboard navigation), `setTabs(tabs, activeId?)`/`setActiveById(id)` for re-rendering the strip without firing `onTabChange`, an optional empty label (drops the `Label:` prefix), and a `showHint` switch for the trailing "(tab to cycle)" hint.
+
+### Changed
+
+- Changed `SettingsList` section-focused keyboard handling so `Up`/`Down` now jump between sections and `Enter`/`Escape` exit section focus before confirming or cancelling a setting
+- Changed `SettingsList` split layout at wide widths to render the full list in the right pane and dim items outside the active section instead of showing only the active-section rows
+- Changed `SettingsList` to omit the default hint row (and preceding blank line) when `options.hint` is set to an empty string
+- Changed tab-bar overflow handling to collapse tabs to their `short` forms before wrapping to multiple lines
+
+### Fixed
+
+- Fixed `StdinBuffer` handling of split SGR mouse reports so fragmented sequences are reassembled instead of leaking their tail bytes as literal input
+- Fixed Esc being unreliable (or seconds-slow) inside fullscreen overlays such as `/settings` on kitty-protocol terminals (Ghostty/kitty): the kitty keyboard mode stack is per-screen, so entering the alternate screen silently reverted keys to legacy encoding while the app still parsed them as kitty input. The TUI now re-pushes the active kitty flags right after `\x1b[?1049h` and pops them before `\x1b[?1049l`.
+- Fixed `StdinBuffer` tearing a buffered bare `ESC` followed by another escape sequence: the `\x1b\x1b` candidate was consumed as alt+esc before the CSI/SS3 continuation byte was ever inspected, swallowing the Esc keypress and leaking the follower's tail (`[B`, `[<35;22;17M`) as typed text into focused components. Meta-CSI chords (`\x1b\x1b[A`) now stay whole, and `ESC` + SGR mouse report is split into a real Esc keypress plus a parseable report.
+- Lowered `PARTIAL_HOLD_MAX_MS` from 500ms to 150ms so a dangling escape partial that never completes (e.g. a bare `ESC` arriving while the kitty-active flag is stale) is delivered after at most ~200ms instead of half a second.
+- Fixed deferred partial-flush behavior so pending incomplete escapes are not split across timer boundaries and can still complete when the next chunk arrives
+- Fixed kitty keyboard-mode handling of a dangling `ESC` so it can be joined with subsequent CSI mouse/kitty input instead of being emitted as a standalone sequence
+- Fixed `SettingsList` to clear section-focus state when filtering items, changing data, scrolling with the mouse wheel, or selecting by ID so stale heading focus does not persist across interactions
+- `SettingsList` now renders every state — list, open submenu, filtered results, empty — at one stable height, so interacting with a bottom-anchored settings panel no longer resizes the live terminal region on each keystroke (which forced re-anchoring and could strand stale scrollback rows).
+
+## [15.11.3] - 2026-06-11
+
+### Fixed
+
+- Fixed the root compose letting a lower child's native-scrollback live seam overwrite a higher one: the topmost seam (and its commit-safe extension) now defines the commit boundary, so a status loader below a streaming transcript can no longer cause still-mutable transcript rows to be committed as stale history ([#2328](https://github.com/can1357/oh-my-pi/pull/2328)).
+
 ## [15.11.2] - 2026-06-11
 
 ### Fixed

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

@@ -14,6 +14,8 @@ export interface SelectListTheme {
     scrollInfo: (text: string) => string;
     noMatch: (text: string) => string;
     symbols: SymbolTheme;
+    /** Hover band applied to the full row under the mouse pointer. */
+    hovered?: (text: string) => string;
 }
 export interface SelectListTruncatePrimaryContext {
     text: string;
@@ -49,6 +51,14 @@ export declare class SelectList implements Component {
     constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
     setFilter(filter: string): void;
     setSelectedIndex(index: number): void;
+    /** Resolve a 0-based rendered-line index to a filtered-item index. */
+    hitTest(line: number): number | undefined;
+    /** Highlight the item under the pointer (null clears). */
+    setHoverIndex(index: number | null): void;
+    /** Move the selection one step for a wheel notch. */
+    handleWheel(delta: -1 | 1): void;
+    /** Mouse click: select the item under the pointer and confirm it. */
+    clickItem(index: number): void;
     invalidate(): void;
     render(width: number): readonly string[];
     handleInput(keyData: string): void;

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

@@ -1,3 +1,4 @@
+import type { SgrMouseEvent } from "../mouse";
 import type { Component } from "../tui";
 export interface SettingItem {
     /** Unique identifier for this setting */
@@ -14,6 +15,8 @@ export interface SettingItem {
     submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
     /** True when the displayed setting differs from its default value. */
     changed?: boolean;
+    /** Render as a non-interactive section heading. Skipped by navigation and search. */
+    heading?: boolean;
 }
 export interface SettingsListTheme {
     label: (text: string, selected: boolean, changed: boolean) => string;
@@ -21,10 +24,84 @@ export interface SettingsListTheme {
     description: (text: string) => string;
     cursor: string;
     hint: (text: string) => string;
+    /** Style for section heading rows (dimmed when outside the active section). Falls back to `hint` when omitted. */
+    heading?: (text: string, dimmed: boolean) => string;
+    /** Style for sidebar section names in the split layout. Falls back to label/hint. */
+    section?: (text: string, active: boolean) => string;
+    /** Hover band applied to the full row under the mouse pointer. */
+    hovered?: (text: string) => string;
 }
+/** Optional behavior overrides for {@link SettingsList}. */
+export interface SettingsListOptions {
+    /**
+     * "auto" (default) renders the section sidebar layout when headings exist
+     * and the width allows; "flat" always renders inline heading rows.
+     */
+    layout?: "auto" | "flat";
+    /**
+     * When false, printable input is ignored (no internal type-to-filter) and
+     * the search status line is never rendered. Use when a parent component
+     * owns the query. Default true.
+     */
+    typeToSearch?: boolean;
+    /** Text shown when the list has no items at all. */
+    emptyText?: string;
+    /**
+     * Footer hint line (hint-styled, replaces the default navigation hint).
+     * An empty string removes the hint row and its leading blank entirely —
+     * use when the host renders its own footer.
+     */
+    hint?: string;
+    /** Fixed split-sidebar width (columns incl. indent+gap); default derives from section names. */
+    sidebarWidth?: number;
+}
+/** Searchable text for a setting item: label, id, value, description, and cycle values. */
+export declare function getSettingItemFilterText(item: SettingItem): string;
 export declare class SettingsList implements Component {
     #private;
-    constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void);
+    /** 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);
+    /** 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. */
+    selectItem(id: string): boolean;
+    /** True while keyboard focus is on the section headings instead of the setting rows. */
+    get sectionFocused(): boolean;
+    /** Whether section focus has anywhere to go: 2+ derived sections in the current view. */
+    hasSectionFocusTargets(): boolean;
+    /**
+     * Toggle keyboard focus between section headings and setting rows. While
+     * focused, Up/Down jump whole sections and Enter/Esc return to the rows.
+     * Engages only when {@link hasSectionFocusTargets}; returns the new state.
+     */
+    toggleSectionFocus(): boolean;
+    /** True while an item submenu owns input. */
+    hasOpenSubmenu(): boolean;
+    /** Resize the visible viewport (fullscreen hosts call this every render). */
+    setMaxVisible(rows: number): void;
+    /** Move the selection one step for a wheel notch. */
+    handleWheel(delta: -1 | 1): void;
+    /** Highlight the item under the pointer (null clears). */
+    setHoverItem(id: string | null): void;
+    /**
+     * Resolve a pointer position against the last rendered frame. `line` is the
+     * 0-based content-line index within this component's render output, `col`
+     * the 0-based column. Sidebar rows resolve to the section's first item.
+     */
+    hitTest(line: number, col: number): string | undefined;
+    /**
+     * Like {@link hitTest}, but only rows the pointer is visually on: sidebar
+     * jump targets are excluded so hovering section names does not light up
+     * pane rows.
+     */
+    hoverTest(line: number, col: number): string | undefined;
+    /**
+     * Route a mouse event into an open submenu (coordinates are local to this
+     * list's rendered lines). Returns false when no submenu is open; submenus
+     * that do not implement {@link MouseRoutable} consume the event silently.
+     */
+    routeSubmenuMouse(event: SgrMouseEvent, line: number, col: number): boolean;
     getSearchQuery(): string;
     hasSearchQuery(): boolean;
     clearSearch(): void;
@@ -35,7 +112,7 @@ export declare class SettingsList implements Component {
      * the previous selection still survives the active filter, otherwise
      * clamped to the last filtered item (or 0 if there are no matches).
      * An open submenu is left untouched — its lifetime is bounded by its own
-     * done callback, and `#closeSubmenu` re-clamps the restored index on exit.
+     * done callback, and `#closeSubmenu` re-resolves the restored item on exit.
      */
     setItems(items: SettingItem[]): void;
     invalidate(): void;

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

@@ -5,6 +5,10 @@ export interface Tab {
     id: string;
     /** Display label shown in the tab bar */
     label: string;
+    /** Compact form (e.g. just the icon) used when the bar must shrink to fit one line. */
+    short?: string;
+    /** Render with the muted style and skip during keyboard navigation. */
+    muted?: boolean;
 }
 /** Theme for styling the tab bar */
 export interface TabBarTheme {
@@ -16,6 +20,10 @@ export interface TabBarTheme {
     inactiveTab: (text: string) => string;
     /** Style for the hint text (e.g., "(tab to cycle)") */
     hint: (text: string) => string;
+    /** Style for muted tabs. Falls back to `inactiveTab` when omitted. */
+    mutedTab?: (text: string) => string;
+    /** Style for the tab under the mouse pointer. Falls back to `inactiveTab` when omitted. */
+    hoverTab?: (text: string) => string;
 }
 /**
  * Horizontal tab bar component.
@@ -34,6 +42,8 @@ export declare class TabBar implements Component {
     #private;
     /** Callback fired when the active tab changes */
     onTabChange?: (tab: Tab, index: number) => void;
+    /** 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);
     /** Get the currently active tab */
     getActiveTab(): Tab;
@@ -41,9 +51,19 @@ export declare class TabBar implements Component {
     getActiveIndex(): number;
     /** Set the active tab by index (clamped to valid range) */
     setActiveIndex(index: number): void;
-    /** Move to the next tab (wraps to first tab after last) */
+    /**
+     * Replace the tab set without firing onTabChange. The active tab is
+     * preserved by id when it survives the swap (or forced via `activeId`);
+     * otherwise the index is clamped.
+     */
+    setTabs(tabs: Tab[], activeId?: string): void;
+    /** Set the active tab by id without firing onTabChange. Returns false when the id is unknown. */
+    setActiveById(id: string): boolean;
+    /** Activate the tab with `id`, firing onTabChange when it changes. Muted tabs are ignored. */
+    selectTab(id: string): boolean;
+    /** Move to the next non-muted tab (wraps to first tab after last) */
     nextTab(): void;
-    /** Move to the previous tab (wraps to last tab before first) */
+    /** Move to the previous non-muted tab (wraps to last tab before first) */
     prevTab(): void;
     invalidate(): void;
     /**
@@ -51,6 +71,19 @@ export declare class TabBar implements Component {
      * @returns true if the input was handled, false otherwise
      */
     handleInput(data: string): boolean;
-    /** Render the tab bar, wrapping to multiple lines if needed */
+    /**
+     * Render the tab bar. When the full labels overflow the width, tabs are
+     * collapsed to their `short` form one by one — starting with the tabs
+     * farthest from the active one — until the bar fits on a single line.
+     * Wrapping to multiple lines is the last resort.
+     */
     render(width: number): readonly string[];
+    /**
+     * Resolve a pointer position against the last rendered frame. `line` is the
+     * 0-based line index within this component's render output, `col` the
+     * 0-based column.
+     */
+    tabAt(line: number, col: number): Tab | undefined;
+    /** Highlight the tab under the pointer (null clears). */
+    setHoverTab(id: string | null): void;
 }

package/dist/types/index.d.ts

@@ -19,6 +19,7 @@ export * from "./fuzzy";
 export * from "./keybindings";
 export * from "./keys";
 export * from "./kitty-graphics";
+export * from "./mouse";
 export * from "./stdin-buffer";
 export type * from "./symbols";
 export * from "./terminal";

package/dist/types/mouse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SGR mouse report parsing (`\x1b[<button;col;rowM` / `…m`).
+ *
+ * Mouse tracking is enabled only while a fullscreen overlay holds the
+ * alternate screen (see tui.ts MOUSE_TRACKING_ON), so consumers are
+ * fullscreen components hit-testing against their own rendered frame:
+ * the frame paints from screen row 0, hence `row`/`col` are exposed
+ * 0-based for direct indexing into rendered lines.
+ */
+/** A decoded SGR mouse report. */
+export interface SgrMouseEvent {
+    /** Raw button code (bit 32 = motion, bit 64 = wheel, low bits = button). */
+    button: number;
+    /** 0-based column of the event. */
+    col: number;
+    /** 0-based row of the event. */
+    row: number;
+    /** True for a release report (`m` suffix). */
+    release: boolean;
+    /** Wheel direction: -1 up, 1 down, null when not a wheel event. */
+    wheel: -1 | 1 | null;
+    /** True when the pointer moved (hover or drag) rather than clicked. */
+    motion: boolean;
+    /** True for a left-button press (not motion, not release, not wheel). */
+    leftClick: boolean;
+}
+/**
+ * Decode an SGR mouse report, or return null when `data` is not one.
+ * Callers on hot keypress paths should pre-check `data.startsWith("\x1b[<")`
+ * before paying for the regex.
+ */
+export declare function parseSgrMouse(data: string): SgrMouseEvent | null;
+/**
+ * Implemented by components that accept routed mouse events at frame-local
+ * coordinates. Hosts translate screen coordinates to the component's own
+ * rendered lines before forwarding.
+ */
+export interface MouseRoutable {
+    /** `line`/`col` are 0-based within the component's rendered output. */
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/dist/types/stdin-buffer.d.ts

@@ -23,6 +23,12 @@ export type StdinBufferOptions = {
      * After this time, a genuinely incomplete escape is flushed.
      */
     timeout?: number;
+    /**
+     * Maximum extra time (default: 150ms) an unambiguous escape partial — an
+     * SGR mouse prefix, or any dangling escape while the kitty keyboard
+     * protocol is active — is held past `timeout` waiting for its tail.
+     */
+    partialHoldTimeout?: number;
     /**
      * Paste-mode inactivity watchdog (default: 1000ms). If no input arrives for
      * this long while waiting for the bracketed-paste end marker, the paste is

package/dist/types/terminal.d.ts

@@ -42,6 +42,7 @@ export interface Terminal {
     get columns(): number;
     get rows(): number;
     get kittyProtocolActive(): boolean;
+    get kittyEnableSequence(): string | null;
     moveBy(lines: number): void;
     hideCursor(): void;
     showCursor(): void;
@@ -79,6 +80,7 @@ export declare function isConPTYHosted(): boolean;
 export declare class ProcessTerminal implements Terminal {
     #private;
     get kittyProtocolActive(): boolean;
+    get kittyEnableSequence(): string | null;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     onPrivateModeReport(callback: (mode: number, supported: boolean) => void): void;

package/dist/types/tui.d.ts

@@ -83,6 +83,10 @@ export interface Component {
  * of history until it finalizes. Volatile live blocks (tool previews that
  * collapse) omit it. Defaults to `liveRegionStart` when absent; a root that
  * reports no seam at all commits everything that scrolls (shell semantics).
+ *
+ * When several root children report a seam in the same frame, the topmost
+ * one (and its commit-safe extension) defines the boundary: commits are
+ * prefix-only, so everything below the first seam is already excluded.
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.11.2",
+	"version": "15.11.4",
 	"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.11.2",
-		"@oh-my-pi/pi-utils": "15.11.2",
+		"@oh-my-pi/pi-natives": "15.11.4",
+		"@oh-my-pi/pi-utils": "15.11.4",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/select-list.ts

@@ -34,6 +34,8 @@ export interface SelectListTheme {
 	scrollInfo: (text: string) => string;
 	noMatch: (text: string) => string;
 	symbols: SymbolTheme;
+	/** Hover band applied to the full row under the mouse pointer. */
+	hovered?: (text: string) => string;
 }
 
 export interface SelectListTruncatePrimaryContext {
@@ -81,6 +83,9 @@ export class SelectList implements Component {
 	#filteredItems: ReadonlyArray<SelectItem>;
 	#filterQuery = "";
 	#selectedIndex: number = 0;
+	#hoveredIndex: number | null = null;
+	/** Per-render map of 0-based output line → filtered-item index. */
+	#hitRows: (number | undefined)[] = [];
 
 	onSelect?: (item: SelectItem) => void;
 	onCancel?: () => void;
@@ -103,12 +108,43 @@ export class SelectList implements Component {
 		this.#selectedIndex = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
 	}
 
+	/** Resolve a 0-based rendered-line index to a filtered-item index. */
+	hitTest(line: number): number | undefined {
+		return this.#hitRows[line];
+	}
+
+	/** Highlight the item under the pointer (null clears). */
+	setHoverIndex(index: number | null): void {
+		this.#hoveredIndex = index;
+	}
+
+	/** Move the selection one step for a wheel notch. */
+	handleWheel(delta: -1 | 1): void {
+		if (this.#filteredItems.length === 0) return;
+		const next = clamp(this.#selectedIndex + delta, 0, this.#filteredItems.length - 1);
+		if (next === this.#selectedIndex) return;
+		this.#selectedIndex = next;
+		this.#notifySelectionChange();
+	}
+
+	/** Mouse click: select the item under the pointer and confirm it. */
+	clickItem(index: number): void {
+		const item = this.#filteredItems[index];
+		if (!item) return;
+		if (index !== this.#selectedIndex) {
+			this.#selectedIndex = index;
+			this.#notifySelectionChange();
+		}
+		this.onSelect?.(item);
+	}
+
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
 
 	render(width: number): readonly string[] {
 		const lines: string[] = [];
+		this.#hitRows = [];
 		const showSearchStatus = this.#shouldRenderSearchStatus();
 
 		// If no items match filter, show message
@@ -159,10 +195,12 @@ export class SelectList implements Component {
 		for (let i = startIndex; i < endIndex && rows.length < visualBudget; i++) {
 			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);
 			for (const row of itemRows) {
 				if (rows.length >= visualBudget) break;
-				rows.push(row);
+				this.#hitRows[rows.length] = i;
+				rows.push(hovered && this.theme.hovered ? this.theme.hovered(row) : row);
 			}
 		}