@linxiraos/pi-tui 1.0.0

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,69 @@
+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;
+    /** 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;
+    /** 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;
+}
+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,123 @@
+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;
+    /** 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;
+    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;
+    /** 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;
+}

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

@@ -0,0 +1,27 @@
+import type { Component } from "../tui.js";
+/**
+ * Text component - displays multi-line text with word wrapping.
+ *
+ * Foreground colors may be supplied lazily via {@link setStyleFn} instead of
+ * baked into `text`: the styler runs at render time, so a caller that
+ * invalidates the component on a theme change (see the coding-agent's
+ * `onThemeChange` handler) re-resolves the color against the now-active theme
+ * rather than replaying the palette active when the component was constructed.
+ */
+export declare class Text implements Component {
+    #private;
+    setIgnoreTight(ignore: boolean): this;
+    constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
+    getText(): string;
+    setText(text: string): boolean;
+    setCustomBgFn(customBgFn?: (text: string) => string): void;
+    /**
+     * Supply a foreground styler applied to the text at render time (e.g. a
+     * theme color resolver). Unlike baking the color into `text`, the styler
+     * re-runs on every render, so invalidating the component after a theme
+     * change re-resolves the color against the active theme.
+     */
+    setStyleFn(styleFn?: (text: string) => string): this;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,10 @@
+import type { Component } from "../tui.js";
+/**
+ * Text component that truncates to fit viewport width
+ */
+export declare class TruncatedText implements Component {
+    #private;
+    constructor(text: string, paddingX?: number, paddingY?: number);
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/deccara.d.ts

@@ -0,0 +1,49 @@
+/** DECSACE — select the rectangle change extent so DECCARA fills a rectangle. */
+export declare const DECSACE_RECT = "\u001B[2*x";
+/** DECSACE — restore the default (stream) change extent. */
+export declare const DECSACE_DEFAULT = "\u001B[*x";
+/**
+ * Encode a single DECCARA rectangle. `top`/`bottom` are 1-based inclusive screen
+ * rows, `left`/`right` 1-based inclusive columns, `sgr` the raw SGR parameter
+ * list to apply (e.g. `48;2;10;20;30`, `48;5;4`, `41`).
+ */
+export declare function encodeDeccara(top: number, left: number, bottom: number, right: number, sgr: string): string;
+/** Where to cut a fillable line and the background to paint over the remainder. */
+export interface BgFillAnalysis {
+    /** Byte index where droppable trailing background padding begins (0 = whole line). */
+    cut: number;
+    /** 0-based column where the trailing padding begins (DECCARA left = leftCol + 1). */
+    leftCol: number;
+    /** SGR parameter list of the background covering the trailing region. */
+    bg: string;
+}
+/**
+ * Decide whether `line` (a final, width-fit, reset-terminated ANSI string) is a
+ * full-width background fill whose trailing padding can be replaced by a DECCARA
+ * rectangle. Returns `null` unless it can *prove* the dropped bytes are literal
+ * trailing spaces under a single, constant, non-default background span (or the
+ * entire row is background-styled spaces).
+ *
+ * Conservative by construction: any OSC sequence (hyperlinks/images), any
+ * non-SGR CSI, a partial row, an inconsistent or default trailing background, or
+ * a malformed escape all yield `null` so the caller keeps the exact original.
+ */
+export declare function analyzeBgFillLine(line: string, width: number): BgFillAnalysis | null;
+/** Per-frame plan: the (possibly shortened) row strings and the DECCARA batch. */
+export interface DeccaraPlan {
+    /** Row strings to write, parallel to the input. Optimized rows are shortened. */
+    texts: string[];
+    /** DECSACE-wrapped rectangle batch to emit after the rows, or `""` if none. */
+    sequence: string;
+}
+/**
+ * Plan DECCARA rectangles for a contiguous block of visible rows.
+ *
+ * `lines[k]` is the final ANSI string for screen row `firstScreenRow + k`
+ * (0-based). For each fillable row the trailing background padding is removed
+ * (the row's cells are cleared/erased by the caller, then repainted by the
+ * rectangle), and vertically adjacent rows with an identical left/right/bg span
+ * coalesce into one rectangle. Rectangles are emitted only when they save more
+ * bytes than they cost, so the result never exceeds the original byte count.
+ */
+export declare function planDeccaraFills(lines: string[], width: number, firstScreenRow?: number): DeccaraPlan;

package/dist/types/desktop-notify.d.ts

@@ -0,0 +1,52 @@
+import type { TerminalId, TerminalNotification } from "./terminal-capabilities.js";
+/** Resolved notifier binary used to fan a notification out to D-Bus. */
+export type DesktopNotifierKind = "notify-send" | "gdbus";
+export interface DesktopNotifier {
+    kind: DesktopNotifierKind;
+    path: string;
+}
+/**
+ * Whether the current process can reach a freedesktop notification daemon:
+ * Linux platform plus either a session bus address in env or the
+ * systemd user-bus socket at `$XDG_RUNTIME_DIR/bus`. Caller is still responsible for
+ * resolving a delivery binary via {@link resolveDesktopNotifier}.
+ */
+export declare function hasLinuxDesktopSession(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, fileExists?: (path: string) => boolean): boolean;
+/**
+ * Whether `sendNotification` should also dispatch a D-Bus toast for this
+ * terminal. Returns true only when (1) the chosen `notifyProtocol` is BEL,
+ * which cannot carry arbitrary toast text, (2) the host exposes a Linux desktop
+ * session, and (3) the user has not opted out via `PI_NO_DESKTOP_NOTIFY=1`.
+ * Terminals that genuinely speak OSC 9 / OSC 99 pass
+ * `notifyProtocolIsBell=false` and are filtered before the D-Bus fallback can
+ * run. Pure helper for tests and the singleton path.
+ */
+export declare function shouldDeliverDesktopNotification(_terminalId: TerminalId, notifyProtocolIsBell: boolean, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
+/** Reset the cached notifier resolution. Tests only. */
+export declare function resetDesktopNotifierCache(): void;
+/**
+ * Locate a libnotify-compatible delivery binary on `PATH`, preferring
+ * `notify-send` (one-shot, no marshalling) and falling back to `gdbus call`
+ * for hosts where libnotify is not installed but GLib is. Result is cached so
+ * repeated notifications do not hit `$which` again.
+ */
+export declare function resolveDesktopNotifier(): DesktopNotifier | null;
+/**
+ * Build the argv that delivers `message` through the resolved notifier. Pure
+ * helper so tests assert exact wire shape without spawning a child. Notes:
+ * - `notify-send` accepts title + body positionally and a numeric expire
+ *   timeout (`-t`); urgency is a flag.
+ * - `gdbus call ... Notify` takes the freedesktop signature
+ *   `s u s s s as a{sv} i`: app_name, replaces_id, app_icon, summary, body,
+ *   actions, hints, expire_timeout. We feed hints with the urgency byte so
+ *   the daemon classifies the toast identically to `notify-send`.
+ */
+export declare function buildDesktopNotifyCommand(notifier: DesktopNotifier, message: string | TerminalNotification): string[];
+/**
+ * Fire-and-forget D-Bus desktop notification. Resolves a notifier, spawns it
+ * with stdio fully detached, and never throws — terminal notifications are
+ * best-effort and must not block the renderer or interleave bytes onto
+ * stdout. Caller is responsible for the gating check
+ * ({@link shouldDeliverDesktopNotification}).
+ */
+export declare function sendDesktopNotification(message: string | TerminalNotification): void;

package/dist/types/editor-component.d.ts

@@ -0,0 +1,38 @@
+import type { AutocompleteProvider } from "./autocomplete.js";
+import type { Component } from "./tui.js";
+/**
+ * Interface for custom editor components.
+ *
+ * This allows extensions to provide their own editor implementation
+ * (e.g., vim mode, emacs mode, custom keybindings) while maintaining
+ * compatibility with the core application.
+ */
+export interface EditorComponent extends Component {
+    /** Get the current text content */
+    getText(): string;
+    /** Set the text content */
+    setText(text: string): void;
+    /** Handle raw terminal input (key presses, paste sequences, etc.) */
+    handleInput(data: string): void;
+    /** Called when user submits (e.g., Enter key) */
+    onSubmit?: (text: string) => void;
+    /** Programmatically trigger submission (optional, e.g. for voice submit). */
+    submit?(): void;
+    /** Called when text changes */
+    onChange?: (text: string) => void;
+    /** Add text to history for up/down navigation */
+    addToHistory?(text: string): void;
+    /** Insert text at current cursor position */
+    insertTextAtCursor?(text: string): void;
+    /**
+     * Get text with any markers expanded (e.g., paste markers).
+     * Falls back to getText() if not implemented.
+     */
+    getExpandedText?(): string;
+    /** Set the autocomplete provider */
+    setAutocompleteProvider?(provider: AutocompleteProvider): void;
+    /** Border color function */
+    borderColor?: (str: string) => string;
+    /** Set horizontal padding */
+    setPaddingX?(padding: number): void;
+}

package/dist/types/fuzzy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Fuzzy matching utilities.
+ *
+ * Matching is deliberately word-local for normal words. This keeps a query like
+ * "image provider" from matching a long setting description only because the
+ * letters i-m-a-g-e appear somewhere in order across unrelated words.
+ *
+ * Lower score = better match.
+ */
+export interface FuzzyMatch {
+    matches: boolean;
+    score: number;
+}
+export interface FuzzyFilterResult<T> {
+    item: T;
+    score: number;
+}
+export declare function fuzzyMatch(query: string, text: string): FuzzyMatch;
+/**
+ * A text prepared once for repeated fuzzy matching.
+ *
+ * `fuzzyMatch` builds a search index per call; the module cache only admits
+ * texts up to {@link MAX_CACHED_TEXT_LEN}, so long corpora (session or
+ * transcript search) rebuild the index on every keystroke — the dominant cost
+ * when a selector re-filters a stable candidate list as the user types. Build
+ * one `FuzzyText` per candidate and call {@link match} per query instead; the
+ * index lives exactly as long as the caller's reference.
+ */
+export declare class FuzzyText {
+    #private;
+    constructor(text: string);
+    /** Match `query` (space-separated tokens; all must match) against the prepared text. */
+    match(query: string): FuzzyMatch;
+}
+/**
+ * Filter and sort items by fuzzy match quality (best matches first).
+ * Supports space-separated tokens: all tokens must match.
+ */
+export declare function fuzzyRank<T>(items: T[], query: string, getText: (item: T) => string): FuzzyFilterResult<T>[];
+export declare function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[];
+/**
+ * Clear the fuzzy search-index cache. Intended for tests/benchmarks so a fresh
+ * cold-start typing session can be measured on demand; not part of the supported
+ * TUI API.
+ *
+ * @internal
+ */
+export declare function resetFuzzyIndexCache(): void;

package/dist/types/index.d.ts

@@ -0,0 +1,32 @@
+export * from "./autocomplete.js";
+export * from "./components/box.js";
+export * from "./components/cancellable-loader.js";
+export * from "./components/editor.js";
+export * from "./components/image.js";
+export * from "./components/input.js";
+export * from "./components/loader.js";
+export * from "./components/markdown.js";
+export * from "./components/scroll-view.js";
+export * from "./components/select-list.js";
+export * from "./components/settings-list.js";
+export * from "./components/spacer.js";
+export * from "./components/tab-bar.js";
+export * from "./components/text.js";
+export * from "./components/truncated-text.js";
+export * from "./deccara.js";
+export * from "./desktop-notify.js";
+export type * from "./editor-component.js";
+export * from "./fuzzy.js";
+export * from "./keybindings.js";
+export * from "./keys.js";
+export * from "./kitty-graphics.js";
+export * from "./latex-block.js";
+export * from "./latex-to-unicode.js";
+export * from "./mouse.js";
+export * from "./stdin-buffer.js";
+export type * from "./symbols.js";
+export * from "./terminal.js";
+export * from "./terminal-capabilities.js";
+export * from "./ttyid.js";
+export * from "./tui.js";
+export * from "./utils.js";