jeopi-tui 16.2.13

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

@@ -0,0 +1,68 @@
+import { type MouseRoutable, type SgrMouseEvent } from "../mouse";
+import type { SymbolTheme } from "../symbols";
+import type { Component } from "../tui";
+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 maxVisible;
+    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);
+    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";
+import type { Component } from "../tui";
+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";
+/**
+ * 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";
+/** 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,14 @@
+import type { Component } from "../tui";
+/**
+ * Text component - displays multi-line text with word wrapping
+ */
+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;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,10 @@
+import type { Component } from "../tui";
+/**
+ * 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,51 @@
+import type { TerminalId, TerminalNotification } from "./terminal-capabilities";
+/** 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 + a session bus address in env. Caller is still responsible
+ * for resolving a delivery binary via {@link resolveDesktopNotifier}.
+ */
+export declare function hasLinuxDesktopSession(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): 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";
+import type { Component } from "./tui";
+/**
+ * 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,32 @@
+/**
+ * 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;
+/**
+ * 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";
+export * from "./components/box";
+export * from "./components/cancellable-loader";
+export * from "./components/editor";
+export * from "./components/image";
+export * from "./components/input";
+export * from "./components/loader";
+export * from "./components/markdown";
+export * from "./components/scroll-view";
+export * from "./components/select-list";
+export * from "./components/settings-list";
+export * from "./components/spacer";
+export * from "./components/tab-bar";
+export * from "./components/text";
+export * from "./components/truncated-text";
+export * from "./deccara";
+export * from "./desktop-notify";
+export type * from "./editor-component";
+export * from "./fuzzy";
+export * from "./keybindings";
+export * from "./keys";
+export * from "./kitty-graphics";
+export * from "./latex-block";
+export * from "./latex-to-unicode";
+export * from "./mouse";
+export * from "./stdin-buffer";
+export type * from "./symbols";
+export * from "./terminal";
+export * from "./terminal-capabilities";
+export * from "./ttyid";
+export * from "./tui";
+export * from "./utils";