@linxiraos/pi-tui 1.1.0 → 1.1.2

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,33 @@
+export * from "./autocomplete.js";
+export * from "./components/box.js";
+export * from "./components/cancellable-loader.js";
+export * from "./components/composer/index.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";

package/dist/types/keybindings.d.ts

@@ -0,0 +1,202 @@
+import { type KeyId } from "./keys.js";
+/**
+ * Global keybinding registry.
+ * Downstream packages can add keybindings via declaration merging.
+ */
+export interface Keybindings {
+    "tui.editor.cursorUp": true;
+    "tui.editor.cursorDown": true;
+    "tui.editor.cursorLeft": true;
+    "tui.editor.cursorRight": true;
+    "tui.editor.cursorWordLeft": true;
+    "tui.editor.cursorWordRight": true;
+    "tui.editor.cursorLineStart": true;
+    "tui.editor.cursorLineEnd": true;
+    "tui.editor.jumpForward": true;
+    "tui.editor.jumpBackward": true;
+    "tui.editor.pageUp": true;
+    "tui.editor.pageDown": true;
+    "tui.editor.deleteCharBackward": true;
+    "tui.editor.deleteCharForward": true;
+    "tui.editor.deleteWordBackward": true;
+    "tui.editor.deleteWordForward": true;
+    "tui.editor.deleteToLineStart": true;
+    "tui.editor.deleteToLineEnd": true;
+    "tui.editor.yank": true;
+    "tui.editor.yankPop": true;
+    "tui.editor.undo": true;
+    "tui.editor.spellingSuggestions": true;
+    "tui.input.newLine": true;
+    "tui.input.submit": true;
+    "tui.input.tab": true;
+    "tui.input.copy": true;
+    "tui.select.up": true;
+    "tui.select.down": true;
+    "tui.select.pageUp": true;
+    "tui.select.pageDown": true;
+    "tui.select.confirm": true;
+    "tui.select.cancel": true;
+}
+export type Keybinding = keyof Keybindings;
+export type { KeyId };
+export interface KeybindingDefinition {
+    defaultKeys: KeyId | KeyId[];
+    description?: string;
+}
+export type KeybindingDefinitions = Record<string, KeybindingDefinition>;
+export type KeybindingsConfig = Record<string, KeyId | KeyId[] | undefined>;
+export declare const TUI_KEYBINDINGS: {
+    readonly "tui.editor.cursorUp": {
+        readonly defaultKeys: "up";
+        readonly description: "Move cursor up";
+    };
+    readonly "tui.editor.cursorDown": {
+        readonly defaultKeys: "down";
+        readonly description: "Move cursor down";
+    };
+    readonly "tui.editor.cursorLeft": {
+        readonly defaultKeys: ["left", "ctrl+b"];
+        readonly description: "Move cursor left";
+    };
+    readonly "tui.editor.cursorRight": {
+        readonly defaultKeys: ["right", "ctrl+f"];
+        readonly description: "Move cursor right";
+    };
+    readonly "tui.editor.cursorWordLeft": {
+        readonly defaultKeys: ["alt+left", "ctrl+left", "alt+b"];
+        readonly description: "Move cursor word left";
+    };
+    readonly "tui.editor.cursorWordRight": {
+        readonly defaultKeys: ["alt+right", "ctrl+right", "alt+f"];
+        readonly description: "Move cursor word right";
+    };
+    readonly "tui.editor.cursorLineStart": {
+        readonly defaultKeys: ["home", "ctrl+a"];
+        readonly description: "Move to line start";
+    };
+    readonly "tui.editor.cursorLineEnd": {
+        readonly defaultKeys: ["end", "ctrl+e"];
+        readonly description: "Move to line end";
+    };
+    readonly "tui.editor.jumpForward": {
+        readonly defaultKeys: "ctrl+]";
+        readonly description: "Jump forward to character";
+    };
+    readonly "tui.editor.jumpBackward": {
+        readonly defaultKeys: "ctrl+alt+]";
+        readonly description: "Jump backward to character";
+    };
+    readonly "tui.editor.pageUp": {
+        readonly defaultKeys: "pageUp";
+        readonly description: "Page up";
+    };
+    readonly "tui.editor.pageDown": {
+        readonly defaultKeys: "pageDown";
+        readonly description: "Page down";
+    };
+    readonly "tui.editor.deleteCharBackward": {
+        readonly defaultKeys: "backspace";
+        readonly description: "Delete character backward";
+    };
+    readonly "tui.editor.deleteCharForward": {
+        readonly defaultKeys: ["delete", "ctrl+d"];
+        readonly description: "Delete character forward";
+    };
+    readonly "tui.editor.deleteWordBackward": {
+        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"];
+        readonly description: "Delete word backward";
+    };
+    readonly "tui.editor.deleteWordForward": {
+        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly description: "Delete word forward";
+    };
+    readonly "tui.editor.deleteToLineStart": {
+        readonly defaultKeys: "ctrl+u";
+        readonly description: "Delete to line start";
+    };
+    readonly "tui.editor.deleteToLineEnd": {
+        readonly defaultKeys: "ctrl+k";
+        readonly description: "Delete to line end";
+    };
+    readonly "tui.editor.yank": {
+        readonly defaultKeys: "ctrl+y";
+        readonly description: "Yank";
+    };
+    readonly "tui.editor.yankPop": {
+        readonly defaultKeys: "alt+y";
+        readonly description: "Yank pop";
+    };
+    readonly "tui.editor.undo": {
+        readonly defaultKeys: ["ctrl+-", "ctrl+_"];
+        readonly description: "Undo";
+    };
+    readonly "tui.editor.spellingSuggestions": {
+        readonly defaultKeys: "ctrl+.";
+        readonly description: "Show spelling replacements";
+    };
+    readonly "tui.input.newLine": {
+        readonly defaultKeys: ["shift+enter", "ctrl+j"];
+        readonly description: "Insert newline";
+    };
+    readonly "tui.input.submit": {
+        readonly defaultKeys: "enter";
+        readonly description: "Submit input";
+    };
+    readonly "tui.input.tab": {
+        readonly defaultKeys: "tab";
+        readonly description: "Tab / autocomplete";
+    };
+    readonly "tui.input.copy": {
+        readonly defaultKeys: "ctrl+c";
+        readonly description: "Copy selection";
+    };
+    readonly "tui.select.up": {
+        readonly defaultKeys: "up";
+        readonly description: "Move selection up";
+    };
+    readonly "tui.select.down": {
+        readonly defaultKeys: "down";
+        readonly description: "Move selection down";
+    };
+    readonly "tui.select.pageUp": {
+        readonly defaultKeys: "pageUp";
+        readonly description: "Selection page up";
+    };
+    readonly "tui.select.pageDown": {
+        readonly defaultKeys: "pageDown";
+        readonly description: "Selection page down";
+    };
+    readonly "tui.select.confirm": {
+        readonly defaultKeys: "enter";
+        readonly description: "Confirm selection";
+    };
+    readonly "tui.select.cancel": {
+        readonly defaultKeys: ["escape", "ctrl+c"];
+        readonly description: "Cancel selection";
+    };
+};
+export interface KeybindingConflict {
+    key: KeyId;
+    keybindings: string[];
+}
+export declare function canonicalKeyId(key: string): string;
+export declare function addKeyAliases(keys: Set<string>, key: KeyId): void;
+export declare class KeybindingsManager {
+    #private;
+    constructor(definitions: KeybindingDefinitions, userBindings?: KeybindingsConfig);
+    matches(data: string, keybinding: Keybinding): boolean;
+    /**
+     * Set-lookup variant of {@link matches} for hot input paths: the caller
+     * parses `data` once (`parseKey` + `canonicalKeyId`) and probes many
+     * bindings without re-parsing the raw sequence per probe.
+     */
+    matchesCanonical(canonical: string | undefined, keybinding: Keybinding): boolean;
+    getKeys(keybinding: Keybinding): KeyId[];
+    getDefinition(keybinding: Keybinding): KeybindingDefinition;
+    getConflicts(): KeybindingConflict[];
+    setUserBindings(userBindings: KeybindingsConfig): void;
+    getUserBindings(): KeybindingsConfig;
+    getResolvedBindings(): KeybindingsConfig;
+}
+export declare function setKeybindings(keybindings: KeybindingsManager): void;
+export declare function getKeybindings(): KeybindingsManager;