@prometheus-ai/tui 0.5.0

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/editor-component.d.ts

@@ -0,0 +1,36 @@
+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;
+    /** 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,15 @@
+/**
+ * Fuzzy matching utilities.
+ * Matches if all query characters appear in order (not necessarily consecutive).
+ * Lower score = better match.
+ */
+export interface FuzzyMatch {
+    matches: boolean;
+    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 fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[];

package/dist/types/index.d.ts

@@ -0,0 +1,28 @@
+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 type * from "./editor-component";
+export * from "./fuzzy";
+export * from "./keybindings";
+export * from "./keys";
+export * from "./kitty-graphics";
+export * from "./stdin-buffer";
+export type * from "./symbols";
+export * from "./terminal";
+export * from "./terminal-capabilities";
+export * from "./ttyid";
+export * from "./tui";
+export * from "./utils";

package/dist/types/keybindings.d.ts

@@ -0,0 +1,189 @@
+import { type KeyId } from "./keys";
+/**
+ * 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.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"];
+        readonly description: "Delete word backward";
+    };
+    readonly "tui.editor.deleteWordForward": {
+        readonly defaultKeys: ["alt+delete", "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.input.newLine": {
+        readonly defaultKeys: "shift+enter";
+        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 class KeybindingsManager {
+    #private;
+    constructor(definitions: KeybindingDefinitions, userBindings?: KeybindingsConfig);
+    matches(data: string, 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;

package/dist/types/keys.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Keyboard input handling for terminal applications.
+ *
+ * Supports both legacy terminal sequences and Kitty keyboard protocol.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ * Reference: https://github.com/sst/opentui/blob/7da92b4088aebfe27b9f691c04163a48821e49fd/packages/core/src/lib/parse.keypress.ts
+ *
+ * Symbol keys are also supported, however some ctrl+symbol combos
+ * overlap with ASCII codes, e.g. ctrl+[ = ESC.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#legacy-ctrl-mapping-of-ascii-keys
+ * Those can still be * used for ctrl+shift combos
+ *
+ * API:
+ * - matchesKey(data, keyId) - Check if input matches a key identifier
+ * - parseKey(data) - Parse input and return the key identifier
+ * - Key - Helper object for creating typed key identifiers
+ * - setKittyProtocolActive(active) - Set global Kitty protocol state
+ * - isKittyProtocolActive() - Query global Kitty protocol state
+ */
+import type { KeyEventType } from "@prometheus-ai/natives";
+declare function isWindowsTerminalSession(): boolean;
+/**
+ * Raw 0x08 (BS) is ambiguous in legacy terminals.
+ *
+ * - Windows Terminal uses it for Ctrl+Backspace.
+ * - Some legacy terminals and tmux setups send it for plain Backspace.
+ *
+ * Prefer explicit Kitty / CSI-u / modifyOtherKeys sequences whenever they are
+ * available. Fall back to a Windows Terminal heuristic only for raw BS bytes.
+ */
+declare function matchesRawBackspace(data: string, expectedModifier: number): boolean;
+export { isWindowsTerminalSession, matchesRawBackspace };
+/**
+ * Set the global Kitty keyboard protocol state.
+ * Called by ProcessTerminal after detecting protocol support.
+ */
+export declare function setKittyProtocolActive(active: boolean): void;
+/**
+ * Query whether Kitty keyboard protocol is currently active.
+ */
+export declare function isKittyProtocolActive(): boolean;
+type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
+type SpecialKey = "escape" | "esc" | "enter" | "return" | "tab" | "space" | "backspace" | "delete" | "insert" | "clear" | "home" | "end" | "pageUp" | "pageDown" | "up" | "down" | "left" | "right" | "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12";
+type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+type ModifierName = "ctrl" | "shift" | "alt" | "super";
+type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+    [M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
+}[RemainingModifiers];
+/**
+ * Union type of all valid key identifiers.
+ * Provides autocomplete and catches typos at compile time.
+ */
+export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
+/**
+ * Typed helper for constructing key identifiers with autocomplete.
+ *
+ * The runtime values are just the canonical key-name strings (so `Key.enter`
+ * is literally `"enter"`); the value of `Key` over a bag of magic strings is
+ * that each property is typed to the exact `KeyId` literal it produces and the
+ * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
+ * is `"ctrl+c"`, not just `string`). This mirrors the upstream
+ * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
+ * scope alias (`@mariozechner`, `@earendil-works`, `@prometheus`) keep working
+ * once the specifier shim remaps them to this package.
+ */
+export declare const Key: {
+    readonly escape: "escape";
+    readonly esc: "esc";
+    readonly enter: "enter";
+    readonly return: "return";
+    readonly tab: "tab";
+    readonly space: "space";
+    readonly backspace: "backspace";
+    readonly delete: "delete";
+    readonly insert: "insert";
+    readonly clear: "clear";
+    readonly home: "home";
+    readonly end: "end";
+    readonly pageUp: "pageUp";
+    readonly pageDown: "pageDown";
+    readonly up: "up";
+    readonly down: "down";
+    readonly left: "left";
+    readonly right: "right";
+    readonly f1: "f1";
+    readonly f2: "f2";
+    readonly f3: "f3";
+    readonly f4: "f4";
+    readonly f5: "f5";
+    readonly f6: "f6";
+    readonly f7: "f7";
+    readonly f8: "f8";
+    readonly f9: "f9";
+    readonly f10: "f10";
+    readonly f11: "f11";
+    readonly f12: "f12";
+    readonly backtick: "`";
+    readonly hyphen: "-";
+    readonly equals: "=";
+    readonly leftbracket: "[";
+    readonly rightbracket: "]";
+    readonly backslash: "\\";
+    readonly semicolon: ";";
+    readonly quote: "'";
+    readonly comma: ",";
+    readonly period: ".";
+    readonly slash: "/";
+    readonly exclamation: "!";
+    readonly at: "@";
+    readonly hash: "#";
+    readonly dollar: "$";
+    readonly percent: "%";
+    readonly caret: "^";
+    readonly ampersand: "&";
+    readonly asterisk: "*";
+    readonly leftparen: "(";
+    readonly rightparen: ")";
+    readonly underscore: "_";
+    readonly plus: "+";
+    readonly pipe: "|";
+    readonly tilde: "~";
+    readonly leftbrace: "{";
+    readonly rightbrace: "}";
+    readonly colon: ":";
+    readonly lessthan: "<";
+    readonly greaterthan: ">";
+    readonly question: "?";
+    readonly ctrl: <K extends BaseKey>(key: K) => `ctrl+${K}`;
+    readonly shift: <K extends BaseKey>(key: K) => `shift+${K}`;
+    readonly alt: <K extends BaseKey>(key: K) => `alt+${K}`;
+    readonly super: <K extends BaseKey>(key: K) => `super+${K}`;
+    readonly ctrlShift: <K extends BaseKey>(key: K) => `ctrl+shift+${K}`;
+    readonly shiftCtrl: <K extends BaseKey>(key: K) => `shift+ctrl+${K}`;
+    readonly ctrlAlt: <K extends BaseKey>(key: K) => `ctrl+alt+${K}`;
+    readonly altCtrl: <K extends BaseKey>(key: K) => `alt+ctrl+${K}`;
+    readonly shiftAlt: <K extends BaseKey>(key: K) => `shift+alt+${K}`;
+    readonly altShift: <K extends BaseKey>(key: K) => `alt+shift+${K}`;
+    readonly ctrlSuper: <K extends BaseKey>(key: K) => `ctrl+super+${K}`;
+    readonly superCtrl: <K extends BaseKey>(key: K) => `super+ctrl+${K}`;
+    readonly shiftSuper: <K extends BaseKey>(key: K) => `shift+super+${K}`;
+    readonly superShift: <K extends BaseKey>(key: K) => `super+shift+${K}`;
+    readonly altSuper: <K extends BaseKey>(key: K) => `alt+super+${K}`;
+    readonly superAlt: <K extends BaseKey>(key: K) => `super+alt+${K}`;
+    readonly ctrlShiftAlt: <K extends BaseKey>(key: K) => `ctrl+shift+alt+${K}`;
+    readonly ctrlShiftSuper: <K extends BaseKey>(key: K) => `ctrl+shift+super+${K}`;
+};
+interface ParsedKittySequence {
+    codepoint: number;
+    shiftedKey?: number;
+    baseLayoutKey?: number;
+    modifier: number;
+    eventType?: KeyEventType;
+}
+/**
+ * Check if the input is a key release event.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Returns false if Kitty protocol is not active.
+ */
+export declare function isKeyRelease(data: string): boolean;
+/**
+ * Check if the input is a key repeat event.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Returns false if Kitty protocol is not active.
+ */
+export declare function isKeyRepeat(data: string): boolean;
+export declare function parseKittySequence(data: string): ParsedKittySequence | null;
+/**
+ * Extract printable text from raw terminal input.
+ *
+ * Handles Kitty CSI-u text-producing keys so text-entry components can treat
+ * keypad digits, keypad operators, and shifted symbols the same as direct character input.
+ */
+export declare function extractPrintableText(data: string): string | undefined;
+/**
+ * Decode terminal input into the printable character it represents.
+ *
+ * Tries Kitty CSI-u first, then falls back to xterm modifyOtherKeys. Returns
+ * undefined for control sequences and modifier-only events.
+ */
+export declare function decodePrintableKey(data: string): string | undefined;
+/**
+ * Match input data against a key identifier string.
+ *
+ * Supported key identifiers:
+ * - Single keys: "escape", "tab", "enter", "backspace", "delete", "home", "end", "space"
+ * - Arrow keys: "up", "down", "left", "right"
+ * - Ctrl combinations: "ctrl+c", "ctrl+z", etc.
+ * - Shift combinations: "shift+tab", "shift+enter"
+ * - Alt combinations: "alt+enter", "alt+backspace"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x"
+ *
+ * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p")
+ *
+ * @param data - Raw input data from terminal
+ * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
+ */
+export declare function matchesKey(data: string, keyId: KeyId): boolean;
+/**
+ * Parse terminal input and return a normalized key identifier.
+ *
+ * Returns key names like "escape", "ctrl+c", "shift+tab", "alt+enter".
+ * Returns undefined if the input is not a recognized key sequence.
+ *
+ * @param data - Raw input data from terminal
+ */
+export declare function parseKey(data: string): string | undefined;

package/dist/types/kill-ring.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Ring buffer for Emacs-style kill/yank operations.
+ *
+ * Tracks killed (deleted) text entries. Consecutive kills can accumulate
+ * into a single entry. Supports yank (paste most recent) and yank-pop
+ * (cycle through older entries).
+ */
+export declare class KillRing {
+    #private;
+    /**
+     * Add text to the kill ring.
+     *
+     * @param text - The killed text to add
+     * @param opts - Push options
+     * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
+     * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
+     */
+    push(text: string, opts: {
+        prepend: boolean;
+        accumulate?: boolean;
+    }): void;
+    /** Get most recent entry without modifying the ring. */
+    peek(): string | undefined;
+    /** Move last entry to front (for yank-pop cycling). */
+    rotate(): void;
+    get length(): number;
+}

package/dist/types/kitty-graphics.d.ts

@@ -0,0 +1,94 @@
+/** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
+export declare const KITTY_PLACEHOLDER = "\uDBFB\uDEEE";
+/** Largest row/column index expressible with the diacritic table (one cell each). */
+export declare const KITTY_PLACEHOLDER_MAX_CELLS: number;
+export type KittyTransmissionMedium = "direct" | "temp-file";
+export interface KittyGraphicsFeatures {
+    /** Display images via Unicode placeholders instead of direct `a=p` placement. */
+    unicodePlaceholders: boolean;
+    /** How image data reaches the terminal: in-band base64 or a temp file. */
+    transmissionMedium: KittyTransmissionMedium;
+}
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PROMETHEUS_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PROMETHEUS_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export declare function detectKittyUnicodePlaceholdersSupport(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function getKittyGraphics(): Readonly<KittyGraphicsFeatures>;
+export declare function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void;
+/**
+ * Whether temp-file transmission may be promoted at runtime: forced via env,
+ * disabled via env, otherwise auto (local sessions only — a temp file written
+ * locally is not readable by a terminal on the far side of an SSH link).
+ */
+export declare function kittyTempFileAllowed(): boolean;
+/** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
+export declare function kittyPlaceholdersFit(columns: number, rows: number): boolean;
+/** True when the base64 payload is a PNG (kitty `f=100` / temp-file path only). */
+export declare function isPngBase64(base64Data: string): boolean;
+/**
+ * Virtual placement APC (`a=p,U=1`): tells the terminal that placeholder cells
+ * carrying image id `i` should display the transmitted image, scaled to fit the
+ * `c`×`r` cell box. Re-emitting with a stable `placementId` replaces in place.
+ */
+export declare function encodeKittyVirtualPlacement(opts: {
+    imageId: number;
+    placementId?: number;
+    columns: number;
+    rows: number;
+}): string;
+/**
+ * Build the placeholder cell grid as one string per row. The image id is carried
+ * in each row's foreground color and the placement id (if any) in its underline
+ * color; every cell names its explicit row+column diacritic (robust to slicing,
+ * unlike left-inheritance). Returns exactly `rows` strings.
+ */
+export declare function encodeKittyPlaceholderGrid(opts: {
+    imageId: number;
+    placementId?: number;
+    columns: number;
+    rows: number;
+}): string[];
+/**
+ * Full placeholder render: the virtual-placement APC prefixes line 0, and every
+ * line carries placeholder cells. Returns exactly `rows` lines (no cursor moves).
+ */
+export declare function renderKittyPlaceholderLines(opts: {
+    imageId: number;
+    placementId?: number;
+    columns: number;
+    rows: number;
+}): string[];
+/**
+ * Transmit a PNG via a temp file (`t=t`): decode the base64 to bytes once, write
+ * them to a temp file, and send the base64-encoded file path as payload. Returns
+ * the APC string, or `null` on any failure (caller falls back to direct base64).
+ *
+ * Synchronous filesystem writes are mandated by the synchronous render pipeline
+ * (`Image.render` → `renderImage` are sync); there is no async seam here.
+ */
+export declare function encodeKittyTempFileTransmit(base64Png: string, imageId: number): string | null;
+/**
+ * Encode a temp-file support probe: write a tiny PNG to a temp file and ask the
+ * terminal to query it (`a=q,t=t`). A conforming terminal replies
+ * `ESC _ G i=<probeId>;OK ESC \`. Returns the query APC plus a `cleanup` that
+ * removes the probe file (best-effort; kitty self-deletes the magic-named file).
+ * Returns `null` if the temp file cannot be written.
+ */
+export declare function encodeKittyTempFileProbe(probeId: number): {
+    sequence: string;
+    cleanup: () => void;
+} | null;