@linxiraos/pi-tui 1.1.0 → 1.1.2

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

@@ -0,0 +1,162 @@
+import { type ImageDimensions } from "../terminal-capabilities.js";
+import type { Component } from "../tui.js";
+export interface ImageTheme {
+    fallbackColor: (str: string) => string;
+}
+export interface ImageOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    filename?: string;
+    /** Shared budget that caps how many inline images render as live graphics. */
+    budget?: ImageBudget;
+    /**
+     * Stable identity for the underlying image (e.g. `toolCallId:index`). Lets the
+     * budget hand back the same graphics id across component re-creations so a
+     * repaint replaces the placement instead of stacking a duplicate.
+     */
+    imageKey?: string;
+}
+/** Default count of inline images kept as live graphics before older ones fall back to text. */
+export declare const DEFAULT_MAX_INLINE_IMAGES = 8;
+/**
+ * Bounds how many inline images render as live terminal graphics at once.
+ *
+ * Terminal graphics protocols — Kitty especially — keep every transmitted image
+ * in a per-terminal store and re-draw placements as content scrolls; text-clear
+ * escapes (`CSI 2 J` / `CSI 3 J`) do not remove them. Unbounded, a session that
+ * shows many images piles up placements plus store memory and leaves ghosts in
+ * scrollback.
+ *
+ * The budget keeps the most recent `cap` images live and demotes older ones to
+ * their text fallback. Demotion needs a full redraw (so off-screen rows are
+ * rewritten) plus an explicit graphics purge of the demoted ids — {@link Image}
+ * reports display order via {@link observe}, and the TUI drives the purge +
+ * redraw on the frame after a new image pushes the count past the cap.
+ *
+ * `cap <= 0` disables budgeting: every image stays a live graphic.
+ */
+export declare class ImageBudget {
+    #private;
+    constructor(cap?: number, requestRender?: () => void);
+    get cap(): number;
+    get enabled(): boolean;
+    setRequestRender(requestRender: () => void): void;
+    setCap(cap: number): void;
+    /**
+     * Stable graphics id for a logical image. A non-empty `key` maps to the same
+     * id across re-creations (so repaints replace the placement); a missing key
+     * gets a fresh id every call.
+     */
+    acquireId(key?: string): number;
+    /**
+     * Begin a render pass. Called by the renderer before composing the frame.
+     * Pass `stable: true` for a partial/throwaway pass that does not walk the
+     * whole tree in display order (the resize viewport fast path): {@link observe}
+     * then replays the last committed per-id decision instead of one derived from
+     * call order, and the pass must NOT be closed with {@link endPass}.
+     */
+    beginPass(stable?: boolean): void;
+    /**
+     * Record an image in display order and report whether it must render its text
+     * fallback this frame. Called by every {@link Image} during render — including
+     * on a cache hit, so the image keeps its display-order slot.
+     *
+     * During a `stable` pass ({@link beginPass}) the call order and visible subset
+     * are not authoritative, so the decision is the committed on-terminal split
+     * (`#suppressedIds`) keyed by id — order- and partiality-independent.
+     */
+    observe(imageId: number): boolean;
+    /**
+     * End a render pass. Returns true when this frame must purge graphics and
+     * fully repaint to apply a stricter budget; read the ids via
+     * {@link takePurgeIds}.
+     */
+    endPass(): boolean;
+    /** Image ids to delete from the terminal this frame; clears the pending set. */
+    takePurgeIds(): readonly number[];
+    /** All image ids believed to be loaded in the terminal store; clears tracking. */
+    takeAllTransmittedIds(): readonly number[];
+    /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
+    shouldTransmit(imageId: number): boolean;
+    /**
+     * Record a direct-placement image's source pixel geometry so the renderer
+     * can clip its placement to the visible slice at write time; cleared when
+     * the image is purged from the terminal store.
+     */
+    registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void;
+    /**
+     * Record this frame's native-scrollback commit target (the frame-row count
+     * that is committed once the frame's writes land). Called once per rendered
+     * frame — including frames that emit no placements — so an epoch whose rows
+     * commit while its line is never rewritten is still flagged before the next
+     * re-emission.
+     */
+    observeCommitWatermark(committedTo: number): void;
+    /**
+     * End the physical-row coordinate epoch after observing its final commit
+     * watermark. Placement ids and latched archive state survive, but attachment
+     * rows do not: the next placement emit records them in the new-width frame.
+     */
+    beginPlacementCoordinateEpoch(): void;
+    /**
+     * Resolve the placement id and geometry for a direct-placement emit whose
+     * topmost attached cell sits at `attachTopFrameRow` — the first frame row
+     * the placement covers, i.e. the block's first *visible* row, not its
+     * origin (-1 when the writer has no frame-space position: alt-screen,
+     * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
+     * target in the same frame-row space (-1 when unknown).
+     *
+     * Invariant: a placement id may be re-used (Kitty replace strips that id's
+     * cells everywhere, scrollback included) only while none of the cells it
+     * attached have entered native scrollback. The epoch — the `p=` id —
+     * advances exactly when the archived flag says otherwise; rewrites with no
+     * commit progression keep replacing the same id in place.
+     */
+    resolvePlacementEmit(imageId: number, attachTopFrameRow: number, committedTo: number): {
+        placementId: number;
+        widthPx: number;
+        heightPx: number;
+    } | null;
+    /**
+     * Restart every placement epoch after a destructive history clear (`CSI 3 J`
+     * full paint). The clear destroys all placement cells — scrollback rows are
+     * gone and the replay rewrites the viewport — so no archive remains to
+     * protect. Reverting to epoch 1 lets the replay recreate every visible
+     * placement after the terminal-wide cleanup.
+     */
+    resetPlacementEpochs(): ReadonlyArray<{
+        imageId: number;
+        lastEpoch: number;
+    }>;
+    /**
+     * Queue a one-time transmit for `imageId`. No-op if already transmitted, so a
+     * 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;
+    /**
+     * True when the budget has nothing in flight: no live images observed on
+     * the last pass, no queued transmits, no pending purges, and no stricter
+     * threshold left to apply. A component-scoped frame may skip the observe
+     * pass only then — a partial tree walk would under-count display order.
+     */
+    get quiescent(): boolean;
+    /** Transmit sequences to write before this frame's placements; clears the queue. */
+    takeTransmits(): readonly string[];
+    /**
+     * Drop transmit tracking so every still-live image re-enqueues its data
+     * (`a=t`) on the next render. Recovers when the terminal dropped the original
+     * transmit — e.g. Ghostty discarding graphics sent during its post-startup
+     * window — where a placement-only replay can never bind a Unicode placeholder.
+     * Pair with a component invalidate + forced repaint so the data and placement
+     * re-emit together; keeps no base64 in budget state (the transmit-once design).
+     */
+    forgetTransmitted(): void;
+}
+export declare class Image implements Component {
+    #private;
+    constructor(base64Data: string, mimeType: string, theme: ImageTheme, options?: ImageOptions, dimensions?: ImageDimensions);
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,25 @@
+import { type Component, type Focusable } from "../tui.js";
+/**
+ * Input component - single-line text input with horizontal scrolling
+ */
+export declare class Input implements Component, Focusable {
+    #private;
+    /** Rendered before the editable area; set to "" for chrome-less embedding. */
+    prompt: string;
+    /** Render the editable value as bullets while retaining the real value internally. */
+    mask: boolean;
+    onSubmit?: (value: string) => void;
+    onEscape?: () => void;
+    /** Focusable interface - set by TUI when focus changes */
+    focused: boolean;
+    getValue(): string;
+    setValue(value: string): void;
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    getUseTerminalCursor(): boolean;
+    handleInput(data: string): void;
+    /** Apply terminal paste semantics to text from non-bracketed paste transports
+     *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
+    pasteText(text: string): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,25 @@
+import type { TUI } from "../tui.js";
+import { Text } from "./text.js";
+type ColorFn = (str: string) => string;
+/**
+ * Styles Loader message fragments without changing their visible text or width.
+ * Set `animated` for colorizers whose ANSI output changes over time.
+ */
+export type LoaderMessageColorFn = ColorFn & {
+    readonly animated?: true;
+};
+/** Animates a spinner and colorized message while asynchronous work is pending. */
+export declare class Loader extends Text {
+    #private;
+    private spinnerColorFn;
+    private messageColorFn;
+    private message;
+    constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string, spinnerFrames?: string[]);
+    render(width: number): readonly string[];
+    start(): void;
+    stop(): void;
+    /** Lifecycle teardown: stop the animation timer. Idempotent. */
+    dispose(): void;
+    setMessage(message: string): void;
+}
+export {};

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

@@ -0,0 +1,86 @@
+import type { SymbolTheme } from "../symbols.js";
+import type { Component } from "../tui.js";
+/** @internal exported for tests — must stay index-identical to the old regex scan. */
+export declare function mathStartIndex(src: string): number | undefined;
+/** @internal exported for tests — must stay index-identical to the old regex scan. */
+export declare function autolinkSchemeScanIndex(src: string): number | undefined;
+/** @internal exported for tests — must never return false for a src the built-in url regex matches. */
+export declare function urlTokenPossible(src: string): boolean;
+/** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
+export declare function clearRenderCache(): void;
+/**
+ * Default text styling for markdown content.
+ * Applied to all text unless overridden by markdown formatting.
+ */
+export interface DefaultTextStyle {
+    /** Foreground color function */
+    color?: (text: string) => string;
+    /** Background color function */
+    bgColor?: (text: string) => string;
+    /** Bold text */
+    bold?: boolean;
+    /** Italic text */
+    italic?: boolean;
+    /** Strikethrough text */
+    strikethrough?: boolean;
+    /** Underline text */
+    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.
+ */
+export interface MarkdownTheme {
+    heading: (text: string) => string;
+    link: (text: string) => string;
+    linkUrl: (text: string) => string;
+    code: (text: string) => string;
+    codeBlock: (text: string) => string;
+    codeBlockBorder: (text: string) => string;
+    quote: (text: string) => string;
+    quoteBorder: (text: string) => string;
+    hr: (text: string) => string;
+    listBullet: (text: string) => string;
+    bold: (text: string) => string;
+    italic: (text: string) => string;
+    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.
+     */
+    resolveMermaidAscii?: (source: string, maxWidth?: number) => string | null;
+    symbols: SymbolTheme;
+}
+export declare class Markdown implements Component {
+    #private;
+    setIgnoreTight(ignore: boolean): this;
+    constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
+    setText(text: string): boolean;
+    invalidate(): void;
+    get transientRenderCache(): boolean;
+    set transientRenderCache(value: boolean);
+    render(width: number): readonly string[];
+}
+/**
+ * Render inline markdown (bold, italic, code, links, strikethrough) to a styled string.
+ * Unlike the full Markdown component, this produces a single line with no block-level elements.
+ */
+export declare function renderInlineMarkdown(text: string, mdTheme: MarkdownTheme, baseColor?: (t: string) => string): string;

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

@@ -0,0 +1,62 @@
+import type { Component } from "../tui.js";
+import { Ellipsis } from "../utils.js";
+type ScrollbarMode = "auto" | "always" | "never";
+export interface ScrollViewTheme {
+    track?: (text: string) => string;
+    thumb?: (text: string) => string;
+}
+export interface ScrollViewOptions {
+    height: number;
+    /** Defaults to "auto". "auto" reserves a scrollbar column only when content overflows. */
+    scrollbar?: ScrollbarMode | boolean;
+    /** Logical row count for pre-windowed line slices. Defaults to lines.length. */
+    totalRows?: number;
+    theme?: ScrollViewTheme;
+    trackChar?: string;
+    thumbChar?: string;
+    /**
+     * Indicator appended when a row overflows `contentWidth`. Defaults to
+     * {@link Ellipsis.Unicode}. Pass {@link Ellipsis.Omit} when callers wrap
+     * lines to width themselves and only trailing padding can overflow (e.g.
+     * the plan-review overlay), so no stray `…` lands on every padded row.
+     */
+    ellipsis?: Ellipsis;
+    /**
+     * Rows moved per keystroke when {@link ScrollView.handleScrollKey} sees a
+     * Shift+Arrow (the "scroll faster" affordance). Defaults to 5.
+     */
+    fastScrollLines?: number;
+}
+/**
+ * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
+ *
+ * ScrollView owns only the row offset. Callers remain responsible for producing
+ * already-wrapped logical lines appropriate for the current render width.
+ */
+export declare class ScrollView implements Component {
+    #private;
+    constructor(lines: readonly string[], options: ScrollViewOptions);
+    setLines(lines: readonly string[]): void;
+    setTotalRows(totalRows: number | undefined): void;
+    setHeight(height: number): void;
+    setScrollbar(scrollbar: ScrollViewOptions["scrollbar"]): void;
+    getScrollOffset(): number;
+    getMaxScrollOffset(): number;
+    setScrollOffset(offset: number): void;
+    scroll(delta: number): void;
+    page(delta: number): void;
+    scrollToTop(): void;
+    scrollToBottom(): void;
+    /**
+     * Apply a standard navigation key to the viewport. Shift+Arrow scrolls by
+     * {@link ScrollViewOptions.fastScrollLines} (the "scroll faster" affordance);
+     * plain Arrow by one line; PageUp/PageDown by a page; Home/End to the ends.
+     * Returns true when the key was consumed, so callers can fall through to
+     * their own (e.g. vim-style) bindings. Generic on purpose: every ScrollView
+     * consumer gets the same scroll keys, including Shift-to-go-faster.
+     */
+    handleScrollKey(data: string): boolean;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}
+export {};

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

@@ -0,0 +1,78 @@
+import { type MouseRoutable, type SgrMouseEvent } from "../mouse.js";
+import type { SymbolTheme } from "../symbols.js";
+import type { Component } from "../tui.js";
+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;
+}
+export interface SelectListTheme {
+    selectedPrefix: (text: string) => string;
+    selectedText: (text: string) => string;
+    description: (text: string) => string;
+    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;
+}
+export interface SelectListTruncatePrimaryContext {
+    text: string;
+    maxWidth: number;
+    columnWidth: number;
+    item: SelectItem;
+    isSelected: boolean;
+}
+export interface SelectListLayoutOptions {
+    minPrimaryColumnWidth?: number;
+    maxPrimaryColumnWidth?: number;
+    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;
+    /**
+     * Cap wrapped descriptions at this many visual rows; the last kept row is
+     * ellipsized. Only meaningful with `wrapDescription`.
+     */
+    maxDescriptionRows?: number;
+}
+export declare class SelectList implements Component, MouseRoutable {
+    #private;
+    private readonly items;
+    private readonly theme;
+    private readonly layout;
+    onSelect?: (item: SelectItem) => void;
+    onCancel?: () => void;
+    onSelectionChange?: (item: SelectItem) => void;
+    constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
+    /** Refit the visible row budget (hosts clamp the list to available height). */
+    setMaxVisible(rows: number): void;
+    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;
+    routeMouse(event: SgrMouseEvent, line: number, _col: number): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+    handleInput(keyData: string): void;
+    getSelectedItem(): SelectItem | null;
+}

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

@@ -0,0 +1,129 @@
+import type { SgrMouseEvent } from "../mouse.js";
+import type { Component } from "../tui.js";
+export interface SettingItem {
+    /** Unique identifier for this setting */
+    id: string;
+    /** Display label (left side) */
+    label: string;
+    /** Optional description shown when selected */
+    description?: string;
+    /** Optional risk note shown in warning styling above the description, with a glyph on the row. */
+    warning?: string;
+    /** Current value to display (right side) */
+    currentValue: string;
+    /** If provided, Enter/Space cycles through these values */
+    values?: string[];
+    /** If provided, Enter opens this submenu. Receives current value and done callback. */
+    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;
+    value: (text: string, selected: boolean, changed: boolean) => string;
+    description: (text: string) => string;
+    /** Style for risk notes and the row warning glyph. Falls back to `description` when omitted. */
+    warning?: (text: string) => string;
+    /** Glyph marking rows that carry a `warning`. Omitted hides the row marker. */
+    warningMark?: 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, warning, and cycle values. */
+export declare function getSettingItemFilterText(item: SettingItem): string;
+export declare class SettingsList implements Component {
+    #private;
+    /** 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;
+    /** Move the selection one step for a wheel notch if the pointer is within the settings pane. */
+    handleWheelAt(delta: -1 | 1, _line: number, col: number): boolean;
+    /** 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;
+    /** Update an item's currentValue */
+    updateValue(id: string, newValue: string): void;
+    /**
+     * Replace the entire items array. Selection is preserved by item id when
+     * 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-resolves the restored item on exit.
+     */
+    setItems(items: SettingItem[]): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+    handleInput(data: string): void;
+}

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

@@ -0,0 +1,11 @@
+import type { Component } from "../tui.js";
+/**
+ * Spacer component that renders empty lines
+ */
+export declare class Spacer implements Component {
+    #private;
+    constructor(lines?: number);
+    setLines(lines: number): void;
+    invalidate(): void;
+    render(_width: number): readonly string[];
+}

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

@@ -0,0 +1,89 @@
+import type { Component } from "../tui.js";
+/** Tab definition */
+export interface Tab {
+    /** Unique identifier for the 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 {
+    /** Style for the label prefix (e.g., "Settings:") */
+    label: (text: string) => string;
+    /** Style for the currently active tab */
+    activeTab: (text: string) => string;
+    /** Style for inactive tabs */
+    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.
+ *
+ * @example
+ * ```ts
+ * const tabs = [
+ *   { id: "config", label: "Config" },
+ *   { id: "tools", label: "Tools" },
+ * ];
+ * const tabBar = new TabBar("Settings", tabs, theme);
+ * tabBar.onTabChange = (tab) => console.log(`Switched to ${tab.id}`);
+ * ```
+ */
+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;
+    /** Get the index of the currently active tab */
+    getActiveIndex(): number;
+    /** Set the active tab by index (clamped to valid range) */
+    setActiveIndex(index: number): void;
+    /**
+     * 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 non-muted tab (wraps to last tab before first) */
+    prevTab(): void;
+    invalidate(): void;
+    /**
+     * Handle keyboard input for tab navigation.
+     * @returns true if the input was handled, false otherwise
+     */
+    handleInput(data: string): boolean;
+    /**
+     * 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;
+}