@termuijs/core 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -89,6 +89,161 @@ interface ContrastFailure {
  */
 declare function validateThemeContrast(theme: Record<string, string>): ContrastFailure[];
 
+/**
+ * Core terminal utility functions for ANSI escape sequences.
+ * Handles layout formatting, terminal bells, and notification configurations.
+ */
+/** CSI (Control Sequence Introducer) prefix */
+declare const CSI = "\u001B[";
+/** OSC (Operating System Command) prefix */
+declare const OSC = "\u001B]";
+/** ESC character */
+declare const ESC = "\u001B";
+declare const hideCursor = "\u001B[?25l";
+declare const showCursor = "\u001B[?25h";
+declare const saveCursorPosition = "\u001B[s";
+declare const restoreCursorPosition = "\u001B[u";
+type CursorShape = 'block' | 'bar' | 'underline';
+/** DECSCUSR: CSI Ps SP q. blink toggles steady vs blinking. */
+declare function cursorShape(shape: CursorShape, blink?: boolean): string;
+declare function moveTo(col: number, row: number): string;
+declare function moveUp(n?: number): string;
+declare function moveDown(n?: number): string;
+declare function moveRight(n?: number): string;
+declare function moveLeft(n?: number): string;
+declare const requestCursorPosition = "\u001B[6n";
+declare const clearScreen = "\u001B[2J";
+declare const clearLine = "\u001B[2K";
+declare const clearLineToEnd = "\u001B[0K";
+declare const clearLineToStart = "\u001B[1K";
+declare const clearDown = "\u001B[J";
+declare const clearUp = "\u001B[1J";
+declare const enterAltScreen = "\u001B[?1049h";
+declare const exitAltScreen = "\u001B[?1049l";
+/** Begin synchronized update — terminal holds display until end marker */
+declare const beginSyncUpdate = "\u001B[?2026h";
+/** End synchronized update — terminal flushes all pending changes atomically */
+declare const endSyncUpdate = "\u001B[?2026l";
+/** Enable SGR mouse tracking (most compatible modern mode) */
+declare const enableMouse = "\u001B[?1000h\u001B[?1002h\u001B[?1006h";
+/** Disable mouse tracking */
+declare const disableMouse = "\u001B[?1000l\u001B[?1002l\u001B[?1006l";
+declare const enableBracketedPaste = "\u001B[?2004h";
+declare const disableBracketedPaste = "\u001B[?2004l";
+declare const enableFocusTracking = "\u001B[?1004h";
+declare const disableFocusTracking = "\u001B[?1004l";
+declare const reset = "\u001B[0m";
+declare const bold = "\u001B[1m";
+declare const dim = "\u001B[2m";
+declare const italic = "\u001B[3m";
+declare const underline = "\u001B[4m";
+declare const blink = "\u001B[5m";
+declare const inverse = "\u001B[7m";
+declare const strikethrough = "\u001B[9m";
+declare const resetBold = "\u001B[22m";
+declare const resetDim = "\u001B[22m";
+declare const resetItalic = "\u001B[23m";
+declare const resetUnderline = "\u001B[24m";
+declare const resetBlink = "\u001B[25m";
+declare const resetInverse = "\u001B[27m";
+declare const resetStrikethrough = "\u001B[29m";
+declare function setScrollRegion(top: number, bottom: number): string;
+declare const resetScrollRegion = "\u001B[r";
+declare function setTitle(title: string): string;
+/** OSC 8 open: ESC ] 8 ; ; <url> ST. */
+declare function hyperlinkOpen(url: string): string;
+/** OSC 8 close: ESC ] 8 ; ; ST. */
+declare const hyperlinkClose: string;
+/** The BEL control byte. */
+declare const bell$1 = "\u0007";
+/** OSC 9 desktop notification: ESC ] 9 ; <text> BEL. */
+declare function notify(text: string): string;
+/**
+ * Strip ANSI escape sequences and dangerous C0/C1 control characters from a
+ * string, while keeping printable Unicode intact.
+ *
+ * Removes:
+ *  - All ESC-introduced sequences (CSI, OSC, DCS, PM, APC, SS2/SS3, etc.)
+ *  - Bare C0 controls (0x00-0x1F) except TAB (0x09) and LF (0x0A)
+ *  - C1 controls / DEL (0x7F-0x9F)
+ *
+ * Safe for use on user-supplied or file-read strings before they are rendered
+ * to the terminal.
+ */
+declare function stripAnsiControl(str: string): string;
+/**
+ * Write text to the system clipboard via OSC 52.
+ * Supported by: xterm, iTerm2, Kitty, WezTerm, Alacritty, Windows Terminal.
+ * @param text Plain text to copy to clipboard
+ * @param stdout Target stream (default: process.stdout)
+ */
+declare function writeClipboard(text: string, stdout?: NodeJS.WriteStream): void;
+declare function readClipboard(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream): Promise<string>;
+declare const clipboard: {
+    write: typeof writeClipboard;
+    read: typeof readClipboard;
+};
+
+declare const ansi_CSI: typeof CSI;
+type ansi_CursorShape = CursorShape;
+declare const ansi_ESC: typeof ESC;
+declare const ansi_OSC: typeof OSC;
+declare const ansi_beginSyncUpdate: typeof beginSyncUpdate;
+declare const ansi_blink: typeof blink;
+declare const ansi_bold: typeof bold;
+declare const ansi_clearDown: typeof clearDown;
+declare const ansi_clearLine: typeof clearLine;
+declare const ansi_clearLineToEnd: typeof clearLineToEnd;
+declare const ansi_clearLineToStart: typeof clearLineToStart;
+declare const ansi_clearScreen: typeof clearScreen;
+declare const ansi_clearUp: typeof clearUp;
+declare const ansi_clipboard: typeof clipboard;
+declare const ansi_cursorShape: typeof cursorShape;
+declare const ansi_dim: typeof dim;
+declare const ansi_disableBracketedPaste: typeof disableBracketedPaste;
+declare const ansi_disableFocusTracking: typeof disableFocusTracking;
+declare const ansi_disableMouse: typeof disableMouse;
+declare const ansi_enableBracketedPaste: typeof enableBracketedPaste;
+declare const ansi_enableFocusTracking: typeof enableFocusTracking;
+declare const ansi_enableMouse: typeof enableMouse;
+declare const ansi_endSyncUpdate: typeof endSyncUpdate;
+declare const ansi_enterAltScreen: typeof enterAltScreen;
+declare const ansi_exitAltScreen: typeof exitAltScreen;
+declare const ansi_hideCursor: typeof hideCursor;
+declare const ansi_hyperlinkClose: typeof hyperlinkClose;
+declare const ansi_hyperlinkOpen: typeof hyperlinkOpen;
+declare const ansi_inverse: typeof inverse;
+declare const ansi_italic: typeof italic;
+declare const ansi_moveDown: typeof moveDown;
+declare const ansi_moveLeft: typeof moveLeft;
+declare const ansi_moveRight: typeof moveRight;
+declare const ansi_moveTo: typeof moveTo;
+declare const ansi_moveUp: typeof moveUp;
+declare const ansi_notify: typeof notify;
+declare const ansi_readClipboard: typeof readClipboard;
+declare const ansi_requestCursorPosition: typeof requestCursorPosition;
+declare const ansi_reset: typeof reset;
+declare const ansi_resetBlink: typeof resetBlink;
+declare const ansi_resetBold: typeof resetBold;
+declare const ansi_resetDim: typeof resetDim;
+declare const ansi_resetInverse: typeof resetInverse;
+declare const ansi_resetItalic: typeof resetItalic;
+declare const ansi_resetScrollRegion: typeof resetScrollRegion;
+declare const ansi_resetStrikethrough: typeof resetStrikethrough;
+declare const ansi_resetUnderline: typeof resetUnderline;
+declare const ansi_restoreCursorPosition: typeof restoreCursorPosition;
+declare const ansi_saveCursorPosition: typeof saveCursorPosition;
+declare const ansi_setScrollRegion: typeof setScrollRegion;
+declare const ansi_setTitle: typeof setTitle;
+declare const ansi_showCursor: typeof showCursor;
+declare const ansi_strikethrough: typeof strikethrough;
+declare const ansi_stripAnsiControl: typeof stripAnsiControl;
+declare const ansi_underline: typeof underline;
+declare const ansi_writeClipboard: typeof writeClipboard;
+declare namespace ansi {
+  export { ansi_CSI as CSI, type ansi_CursorShape as CursorShape, ansi_ESC as ESC, ansi_OSC as OSC, ansi_beginSyncUpdate as beginSyncUpdate, bell$1 as bell, ansi_blink as blink, ansi_bold as bold, ansi_clearDown as clearDown, ansi_clearLine as clearLine, ansi_clearLineToEnd as clearLineToEnd, ansi_clearLineToStart as clearLineToStart, ansi_clearScreen as clearScreen, ansi_clearUp as clearUp, ansi_clipboard as clipboard, ansi_cursorShape as cursorShape, ansi_dim as dim, ansi_disableBracketedPaste as disableBracketedPaste, ansi_disableFocusTracking as disableFocusTracking, ansi_disableMouse as disableMouse, ansi_enableBracketedPaste as enableBracketedPaste, ansi_enableFocusTracking as enableFocusTracking, ansi_enableMouse as enableMouse, ansi_endSyncUpdate as endSyncUpdate, ansi_enterAltScreen as enterAltScreen, ansi_exitAltScreen as exitAltScreen, ansi_hideCursor as hideCursor, ansi_hyperlinkClose as hyperlinkClose, ansi_hyperlinkOpen as hyperlinkOpen, ansi_inverse as inverse, ansi_italic as italic, ansi_moveDown as moveDown, ansi_moveLeft as moveLeft, ansi_moveRight as moveRight, ansi_moveTo as moveTo, ansi_moveUp as moveUp, ansi_notify as notify, ansi_readClipboard as readClipboard, ansi_requestCursorPosition as requestCursorPosition, ansi_reset as reset, ansi_resetBlink as resetBlink, ansi_resetBold as resetBold, ansi_resetDim as resetDim, ansi_resetInverse as resetInverse, ansi_resetItalic as resetItalic, ansi_resetScrollRegion as resetScrollRegion, ansi_resetStrikethrough as resetStrikethrough, ansi_resetUnderline as resetUnderline, ansi_restoreCursorPosition as restoreCursorPosition, ansi_saveCursorPosition as saveCursorPosition, ansi_setScrollRegion as setScrollRegion, ansi_setTitle as setTitle, ansi_showCursor as showCursor, ansi_strikethrough as strikethrough, ansi_stripAnsiControl as stripAnsiControl, ansi_underline as underline, ansi_writeClipboard as writeClipboard };
+}
+
 interface TerminalOptions {
     /** Override stdout stream (useful for testing) */
     stdout?: NodeJS.WriteStream;
@@ -100,6 +255,10 @@ interface TerminalOptions {
     mouse?: boolean;
     /** Use alternate screen buffer for full-screen apps */
     altScreen?: boolean;
+    /** Enable bracketed-paste mode so InputParser receives paste events. */
+    bracketedPaste?: boolean;
+    /** Debounce window in ms for resize dispatch. Default 16. */
+    resizeDebounceMs?: number;
 }
 /**
  * Terminal adapter — wraps process.stdout/stdin and manages
@@ -114,16 +273,20 @@ declare class Terminal {
     private _isRawMode;
     private _isAltScreen;
     private _isMouseEnabled;
+    private _isBracketedPasteEnabled;
     private _resizeHandlers;
     private _cleanupHandlers;
     private _originalRawMode;
+    private _resizeDebounceMs;
+    private _resizeTimer;
+    private _lastDispatchedCols;
+    private _lastDispatchedRows;
     private _resizeHandler;
     private _exitHandler;
-    private _sigintHandler;
-    private _sigtermHandler;
-    private _uncaughtExceptionHandler;
-    private _unhandledRejectionHandler;
     private _restored;
+    private _restoring;
+    private _writeQueue;
+    private _isWriting;
     constructor(options?: TerminalOptions);
     /** Current terminal width in columns */
     get cols(): number;
@@ -139,9 +302,41 @@ declare class Terminal {
     exitAltScreen(): void;
     enableMouse(): void;
     disableMouse(): void;
+    /** Emit the enable sequence (CSI ?2004h). Idempotent. */
+    enableBracketedPaste(): void;
+    /** Emit the disable sequence (CSI ?2004l). Idempotent. */
+    disableBracketedPaste(): void;
     hideCursor(): void;
     showCursor(): void;
+    /** Set the cursor shape via DECSCUSR. Default blink = true. */
+    setCursorShape(shape: CursorShape, blink?: boolean): void;
+    /** Ring the terminal bell (BEL). */
+    bell(): void;
+    /** Send an OSC 9 desktop notification. Body is appended after a separator. */
+    notify(title: string, body?: string): void;
+    /**
+     * Writes chunked string data to stdout.
+     * Enforces queue serialization to ensure atomic ANSI escape execution.
+     */
     write(data: string): void;
+    /**
+     * Writes data to stdout synchronously, bypassing the write queue.
+     * Used by the renderer during frame flush to avoid races with the
+     * async queue lifecycle. Only use for render-path output.
+     */
+    writeSync(data: string): void;
+    /**
+     * Sequentially unshifts and drains string frames to stdout safely.
+     */
+    private _processWriteQueue;
+    /**
+     * Read text from the system clipboard via OSC 52.
+     */
+    readClipboard(): Promise<string>;
+    /**
+     * Write text to the system clipboard via OSC 52.
+     */
+    writeClipboard(text: string): void;
     onResize(handler: (cols: number, rows: number) => void): () => void;
     /**
      * Restore terminal to its original state.
@@ -185,6 +380,8 @@ interface Cell {
      * - 0 for continuation cells (second half of a wide char)
      */
     width: number;
+    /** Optional OSC 8 hyperlink target for this cell. */
+    link?: string;
 }
 /** Create a blank cell with default attributes */
 declare function emptyCell(): Cell;
@@ -202,14 +399,48 @@ declare function cellsEqual(a: Cell, b: Cell): boolean;
 declare class Screen {
     private _cols;
     private _rows;
+    private _previousLines;
+    private _lastRenderedHeight;
+    get lastRenderedHeight(): number;
+    set lastRenderedHeight(value: number);
+    private _previousStyleLines;
     front: Cell[][];
     back: Cell[][];
+    /**
+     * Render epoch counter. Incremented on every swap so downstream consumers
+     * (e.g. Renderer._flush) can detect and skip stale frames from a previous
+     * epoch, preventing double-swap corruption.
+     */
+    private _epoch;
+    /** True while swap() is executing to prevent re-entrant double-swap corruption. */
+    private _swapping;
+    /** The epoch captured at the start of the current flush cycle. */
+    private _flushEpoch;
     /**
      * Stack of clipping regions. When non-empty, setCell/writeString
      * only write to cells within the topmost clip rectangle.
      */
     private _clipStack;
+    private _translateYStack;
+    private _translateY;
     constructor(cols: number, rows: number);
+    /** Retrieve a read-only copy of the cell at (x, y) from the back buffer. */
+    getCell(x: number, y: number): Readonly<Cell> | undefined;
+    /** Serialize a back-buffer row to a plain string (skips continuation cells). */
+    getLine(row: number): string;
+    /**
+     * Serialize the style attributes of a back-buffer row into a
+     * fingerprint string. When the characters are identical but the
+     * styles differ (color, bold, italic, etc.), this fingerprint
+     * changes, allowing the diff renderer to detect style-only updates.
+     */
+    getStyleLine(row: number): string;
+    /** Return the saved line string for the given row (empty before first saveLines call). */
+    getPreviousLine(row: number): string;
+    /** Return the saved style fingerprint for the given row. */
+    getPreviousStyleLine(row: number): string;
+    /** Snapshot the current back-buffer line strings for use by diffRenderer. */
+    saveLines(): void;
     get cols(): number;
     get rows(): number;
     /**
@@ -237,6 +468,8 @@ declare class Screen {
         width: number;
         height: number;
     } | null;
+    pushTranslateY(offset: number): void;
+    popTranslateY(): void;
     /**
      * Write a cell to the back buffer at position (col, row).
      */
@@ -250,8 +483,16 @@ declare class Screen {
      * Clear the back buffer to all empty cells.
      */
     clear(): void;
+    /** Current render epoch — incremented after each swap. */
+    get epoch(): number;
+    /** The epoch captured at the start of the current flush cycle. */
+    get flushEpoch(): number;
+    set flushEpoch(value: number);
     /**
      * Swap front and back buffers. Called after rendering diffs.
+     * Uses mutual exclusion to prevent double-swap corruption when
+     * _flush() is called concurrently (e.g. from duplicate setImmediate
+     * callbacks).
      */
     swap(): void;
     /**
@@ -260,12 +501,47 @@ declare class Screen {
     resize(cols: number, rows: number): void;
     /**
      * Clear the front buffer (marks everything as "needs redraw").
+     * Mutates cells in-place to avoid GC pressure from object allocation.
      */
     invalidate(): void;
+    /**
+     * Export current screen as ANSI snapshot text.
+     */
+    exportANSI(): string;
+    /**
+     * Export current screen as SVG.
+     */
+    exportSVG(): string;
     private _createGrid;
-    private _isWideCodePoint;
 }
 
+declare class RenderHook {
+    private _buffer;
+    private _isActive;
+    private _originalConsole;
+    /** Check if the hook is currently intercepting console output */
+    get isActive(): boolean;
+    /** Wrap console.log/warn/error to buffer external logs instead of writing to stdout */
+    start(): void;
+    /** Restore original console methods */
+    stop(): void;
+    /** Retrieve and clear the buffered logs */
+    flush(): string;
+    /** Write directly to process.stdout, bypassing any buffering */
+    writeRaw(text: string): void;
+}
+
+/**
+ * Render frame statistics.
+ */
+interface FrameStats {
+    /** Number of cells that differed and were redrawn this frame. */
+    cellsChanged: number;
+    /** Total bytes written to the terminal this frame. */
+    bytesWritten: number;
+    /** Wall-clock duration of the flush in milliseconds. */
+    durationMs: number;
+}
 /**
  * Differential renderer — compares front/back screen buffers and
  * outputs only the changed cells. Uses synchronized output (CSI 2026)
@@ -278,8 +554,12 @@ declare class Renderer {
     private _frameTimer;
     private _renderRequested;
     private _colorDepth;
+    private _diffRenderer;
     private _onTick;
-    constructor(terminal: Terminal, screen: Screen, fps?: number);
+    private _callbacks;
+    /** The stdout interceptor hook for buffering external logs */
+    readonly hook: RenderHook;
+    constructor(terminal: Terminal, screen: Screen, fps?: number, diffRenderer?: boolean);
     /** Change the rendering frame rate cap */
     setFPS(fps: number): void;
     /** Start the render loop */
@@ -290,19 +570,43 @@ declare class Renderer {
     requestFrame(): void;
     /** Force an immediate render (bypass frame rate) */
     renderNow(): void;
+    /** Register a per-frame profiling callback. Returns an unsubscribe function. */
+    onFrame(cb: (stats: FrameStats) => void): () => void;
     /**
      * Full-screen clear and redraw (first render or after resize).
      */
     fullRender(): void;
+    /** ANSI sequence to save cursor position */
+    private static _CURSOR_SAVE;
+    /** ANSI sequence to restore cursor position */
+    private static _CURSOR_RESTORE;
     /**
      * Core diff and flush: compare front vs back buffer,
      * emit only changed cells.
      */
     private _flush;
+    /** Style fingerprint of the last rendered cell (to suppress redundant ANSI reset/apply). */
+    private _lastStyleFingerprint;
+    /** Build a stable style fingerprint string for a cell (avoids allocation-heavy object comparison). */
+    private _styleFingerprint;
     /**
      * Generate the ANSI escape sequence to render a single cell.
+     * Skips ansiReset + re-apply when the adjacent cell has identical style.
      */
     private _renderCell;
+    /**
+     * If a span starts at a width-0 continuation cell (the second half of a
+     * wide character), adjust backward to the preceding cell so the cursor
+     * is placed at a valid column boundary.
+     */
+    private static _adjustSpanStart;
+    /**
+     * Render only the changed spans within a single row (cell-level granularity).
+     * Uses moveTo to position the cursor at the start of each changed span.
+     */
+    private _renderDiffLine;
+    private _renderLine;
+    private _emitStats;
 }
 
 /**
@@ -375,6 +679,8 @@ declare class LayerManager {
     private _layers;
     private _cols;
     private _rows;
+    private _hitWidgetGrid;
+    private _hitZGrid;
     constructor(cols: number, rows: number);
     get cols(): number;
     get rows(): number;
@@ -408,6 +714,10 @@ declare class LayerManager {
      * Write a string to a specific layer at position (col, row).
      */
     writeString(layerId: string, col: number, row: number, str: string, style?: Partial<Omit<Cell, 'char' | 'width'>>): void;
+    /**
+     * Check whether any visible layer has pending dirty changes.
+     */
+    hasDirtyLayers(): boolean;
     /**
      * Clear all cells in a specific layer.
      */
@@ -420,16 +730,31 @@ declare class LayerManager {
      * Composite all overlay layers onto the Screen's back buffer.
      * Layers are applied in z-index order (lowest first).
      * Transparent cells (empty with no colors) are skipped.
+     * Writes directly to screen.back to avoid setCell overhead
+     * (bounds/clip checks are already satisfied by dirtyRegion).
      */
     composite(screen: Screen): void;
     /**
      * Resize all layers when the terminal is resized.
      */
     resize(cols: number, rows: number): void;
+    /** Reset the hit grid. Call once at the start of each frame. */
+    clearHitGrid(): void;
+    /**
+     * Mark a rectangular region as owned by a widget at a given z-index.
+     * Higher z wins when regions overlap.
+     */
+    setHitRegion(widgetId: string, x: number, y: number, w: number, h: number, z?: number): void;
+    /** Return the topmost widget id at a cell, or null. */
+    hitTest(col: number, row: number): string | null;
     /**
      * Create an empty cell grid.
      */
     private _createGrid;
+    /**
+     * Allocate parallel hit grid and z-index grid.
+     */
+    private _allocateHitGrids;
     /**
      * Expand the dirty region of a layer to include the given cell.
      */
@@ -441,7 +766,49 @@ declare const caps: {
     readonly unicode: boolean;
     readonly motion: boolean;
     readonly ci: boolean;
+    readonly background: "light" | "dark";
+    readonly keybindingMode: "vim" | "emacs" | "default";
 };
+/**
+ * Returns `true` when animation should be suppressed.
+ *
+ * True when `caps.motion` is `false` — i.e. when `NO_MOTION=1` is set
+ * or when running in a CI environment (`CI=1`).
+ *
+ * Animated widgets **must** check this function and render their static
+ * end-state (a single final frame) when it returns `true`, rather than
+ * playing through intermediate animation frames.
+ *
+ * @example
+ * if (prefersReducedMotion()) {
+ *   renderStaticFrame();
+ * } else {
+ *   startAnimation();
+ * }
+ */
+declare function prefersReducedMotion(): boolean;
+/**
+ * Returns `true` when color output should be used.
+ *
+ * Returns `false` when `NO_COLOR=1` is set or `TERM=dumb`,
+ * as per <https://no-color.org>.
+ *
+ * All widgets that emit ANSI color codes **must** check this function
+ * and emit plain text (no escape sequences) when it returns `false`.
+ *
+ * @example
+ * if (shouldUseColor()) {
+ *   output += colorToAnsiFg(cell.fg, depth);
+ * }
+ */
+declare function shouldUseColor(): boolean;
+/**
+ * Returns `true` when the user prefers high-contrast output.
+ *
+ * Widgets that render text on colored backgrounds **may** check this
+ * to use more distinct color combinations.
+ */
+declare function prefersHighContrast(): boolean;
 
 declare const BOX: Record<string, string>;
 declare const BRAILLE_SPIN: readonly ["|", "/", "-", "\\"];
@@ -451,6 +818,15 @@ declare const BLOCK: {
     readonly partial: "-";
 };
 
+/**
+ * Triggers the terminal bell using the BEL control character (\x07).
+ * This will usually cause a system beep or a visual flash depending on
+ * the terminal emulator's configuration.
+ */
+declare function bell(): void;
+
+declare function mergeBorders(screen: Screen): void;
+
 /**
  * Keyboard event emitted when a key is pressed.
  */
@@ -490,7 +866,7 @@ declare function createKeyEvent(base: {
 /**
  * Mouse event types.
  */
-type MouseEventType = 'mousedown' | 'mouseup' | 'mousemove' | 'scroll';
+type MouseEventType = 'mousedown' | 'mouseup' | 'mousemove' | 'scroll' | 'dblclick' | 'drag' | 'dragend';
 type MouseButton = 'left' | 'middle' | 'right' | 'none';
 /**
  * Mouse event emitted when mouse activity is detected.
@@ -504,8 +880,18 @@ interface MouseEvent {
     button: MouseButton;
     /** Type of mouse event */
     type: MouseEventType;
-    /** Scroll direction (-1 = up, 1 = down) */
+    /** Vertical scroll delta: -1 = up, 1 = down. Set for vertical wheel events. */
     scrollDelta?: number;
+    /** Horizontal scroll delta: -1 = left, 1 = right. Set for horizontal wheel events. */
+    scrollDeltaX?: number;
+    /** Which axis a scroll event used. Set only for type 'scroll'. */
+    scrollAxis?: 'vertical' | 'horizontal';
+    /** Ctrl modifier held during the mouse event. SGR bit 0b10000. */
+    ctrl?: boolean;
+    /** Alt/Meta modifier held during the mouse event. SGR bit 0b1000. */
+    alt?: boolean;
+    /** Shift modifier held during the mouse event. SGR bit 0b100. */
+    shift?: boolean;
 }
 /**
  * Resize event emitted when the terminal is resized.
@@ -522,6 +908,8 @@ interface FocusEvent {
     targetId: string;
     /** Type of focus event */
     type: 'focus' | 'blur';
+    /** Monotonically increasing sequence number for ordering / staleness detection */
+    epoch?: number;
 }
 /**
  * Map of all event types to their data shapes.
@@ -536,8 +924,13 @@ interface EventMap {
     'mount': void;
     'unmount': void;
     'tick': number;
+    'paste': string;
 }
 
+interface CursorPosition {
+    row: number;
+    col: number;
+}
 /**
  * Reads raw stdin bytes and parses them into typed KeyEvent / MouseEvent objects.
  * Handles escape sequences, multi-byte keys, ctrl+key, and SGR mouse events.
@@ -548,11 +941,18 @@ declare class InputParser {
     private _handler;
     private _escapeTimeout;
     private _escapeBuffer;
+    private _isPasting;
+    private _pasteBuffer;
+    private _cursorRequests;
     constructor(stdin: NodeJS.ReadStream);
     /** Subscribe to key events */
     onKey(handler: (event: KeyEvent) => void): () => void;
     /** Subscribe to mouse events */
     onMouse(handler: (event: MouseEvent) => void): () => void;
+    /** Subscribe to terminal focus-in (true) / focus-out (false) reports. */
+    onFocusChange(handler: (focused: boolean) => void): () => void;
+    onPaste(handler: (text: string) => void): () => void;
+    requestCursorPosition(timeoutMs?: number): Promise<CursorPosition>;
     /** Start listening for input */
     start(): void;
     /** Stop listening for input */
@@ -581,6 +981,15 @@ declare const CTRL_KEYS: Record<number, string>;
  * Special single-byte key codes.
  */
 declare const SPECIAL_KEYS: Record<number, string>;
+/**
+ * Normalizes navigation key names based on the active keybinding mode.
+ * Useful for mapping vim (j/k/h/l) or emacs (ctrl+n/ctrl+p) keys to standard
+ * arrow key intents (up/down/left/right).
+ *
+ * @param keyName The raw key name from KeyEvent.name
+ * @returns The normalized directional key name, or the original key name
+ */
+declare function normalizeNavigationKey(keyName: string): string;
 
 /**
  * Parse an SGR mouse event escape sequence.
@@ -598,6 +1007,57 @@ declare function parseMouseEvent(data: string): MouseEvent | null;
  */
 declare function isMouseSequence(data: string): boolean;
 
+interface MouseGesturesOptions {
+    /** Max ms between two clicks to count as a double-click. Default 300. */
+    doubleClickMs?: number;
+}
+declare class MouseGestures {
+    private doubleClickMs;
+    private lastMouseDown;
+    private activeDragButton;
+    private wasDragging;
+    constructor(opts?: MouseGesturesOptions);
+    /**
+     * Feed a raw MouseEvent. Returns synthesized events to emit
+     * (may be empty). Does not mutate the input event.
+     */
+    feed(event: MouseEvent): MouseEvent[];
+}
+
+interface Chord {
+    keys: string[];
+    handler: () => void;
+}
+interface ChordMatcherOptions {
+    timeoutMs?: number;
+}
+declare class ChordMatcher {
+    private _bindings;
+    private _nextId;
+    private _buffer;
+    private _timeoutMs;
+    private _timer;
+    constructor(opts?: ChordMatcherOptions);
+    bind(keys: string[], handler: () => void): () => void;
+    feed(event: KeyEvent): boolean;
+    private _getMatchingBindings;
+}
+
+declare class LiveRender {
+    private readonly terminal;
+    private readonly screen;
+    constructor(terminal: Terminal, screen: Screen);
+    private getHeight;
+    /**
+     * Renders a serialized screen buffer.
+     *
+     * Widgets render into a Screen object first.
+     * Callers should serialize the Screen contents into a string
+     * before passing it to LiveRender.render().
+     */
+    render(frame: string): void;
+}
+
 /**
  * Supported border styles.
  */
@@ -628,7 +1088,7 @@ declare const BORDER_CHARS: Record<Exclude<BorderStyle, 'none' | 'custom'>, Bord
 /**
  * Get the border characters for a given style.
  */
-declare function getBorderChars(style: BorderStyle, customChars?: Partial<BorderChars>): BorderChars | null;
+declare function getBorderChars(style: BorderStyle, customChars?: Partial<BorderChars>, asciiOnly?: boolean): BorderChars | null;
 /**
  * Calculate the total space a border takes up.
  * Returns { horizontal, vertical } representing how many columns/rows
@@ -639,6 +1099,107 @@ declare function borderSize(style: BorderStyle): {
     vertical: number;
 };
 
+interface LayoutContext {
+    parentWidth: number;
+    parentHeight: number;
+    contentWidth: number;
+    contentHeight: number;
+    readonly elementWidth: number;
+    readonly elementHeight: number;
+    readonly elementX: number;
+    readonly elementY: number;
+    axis: 'horizontal' | 'vertical';
+    getGroupSize(groupId: string): number;
+}
+
+declare abstract class Pos {
+    /** List of variables this Pos depends on, e.g. ['elementSize', 'parentSize'] */
+    abstract dependencies(): string[];
+    /** Computes the final numeric coordinate */
+    abstract evaluate(ctx: LayoutContext): number;
+    /** Center the element within its parent */
+    static center(): Pos;
+    /** Anchor the element `margin` units away from the end (right/bottom) */
+    static anchorEnd(margin?: number): Pos;
+    /** Align multiple siblings as a group */
+    static align(alignment: 'start' | 'center' | 'end', groupId: string): Pos;
+}
+
+declare abstract class Dim {
+    /** List of variables this Dim depends on, e.g. ['contentWidth'] */
+    abstract dependencies(): string[];
+    /** Computes the final numeric size */
+    abstract evaluate(ctx: LayoutContext): number;
+    /** Size to the intrinsic content of the element */
+    static auto(): Dim;
+    /** Fill remaining space in the parent, minus an optional margin */
+    static fill(margin?: number): Dim;
+    /** Custom function to determine size */
+    static func(fn: (ctx: LayoutContext) => number): Dim;
+}
+
+declare enum Flex {
+    Start = "start",
+    Center = "center",
+    End = "end",
+    SpaceBetween = "space-between",
+    SpaceAround = "space-around"
+}
+declare abstract class Constraint {
+    /** Fixed length in columns/rows */
+    static Length(n: number): Constraint;
+    /** Percentage of available space (0-100) */
+    static Percentage(n: number): Constraint;
+    /** Minimum length */
+    static Min(n: number): Constraint;
+    /** Maximum length */
+    static Max(n: number): Constraint;
+    /** Fills remaining space, with a flex weight */
+    static Fill(weight?: number): Constraint;
+}
+declare class LengthConstraint extends Constraint {
+    value: number;
+    constructor(value: number);
+}
+declare class PercentageConstraint extends Constraint {
+    value: number;
+    constructor(value: number);
+}
+declare class MinConstraint extends Constraint {
+    value: number;
+    constructor(value: number);
+}
+declare class MaxConstraint extends Constraint {
+    value: number;
+    constructor(value: number);
+}
+declare class FillConstraint extends Constraint {
+    weight: number;
+    constructor(weight: number);
+}
+declare function resolveConstraints(available: number, constraints: Constraint[], flex?: Flex, gap?: number): {
+    offset: number;
+    size: number;
+}[];
+
+interface ResolvableNode {
+    id: string;
+    x?: number | Pos;
+    y?: number | Pos;
+    width?: number | Dim;
+    height?: number | Dim;
+    contentWidth: number;
+    contentHeight: number;
+    computed: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    groupId?: string;
+}
+declare function resolveLayoutVariables(nodes: ResolvableNode[], parentWidth: number, parentHeight: number): void;
+
 /**
  * Edge values (padding, margin) — top, right, bottom, left.
  */
@@ -663,13 +1224,18 @@ interface Style {
     padding?: Partial<Edges> | number;
     margin?: Partial<Edges> | number;
     border?: BorderStyle;
+    asciiOnly?: boolean;
     borderColor?: Color;
-    width?: number | string;
-    height?: number | string;
+    width?: number | string | Dim;
+    height?: number | string | Dim;
     minWidth?: number;
     minHeight?: number;
     maxWidth?: number;
     maxHeight?: number;
+    x?: number | Pos;
+    y?: number | Pos;
+    groupId?: string;
+    constraints?: Constraint[];
     flexDirection?: 'row' | 'column';
     justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around';
     alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch';
@@ -699,6 +1265,10 @@ declare function mergeStyles(base: Style, override: Style): Style;
  * Create a default (empty) style.
  */
 declare function defaultStyle(): Style;
+/**
+ * Returns true when any layout-affecting property differs between old and new style.
+ */
+declare function hasLayoutChanges(oldStyle: Style, newStyle: Style): boolean;
 /**
  * Extract the cell-level style attributes from a Style object.
  * Used when rendering text into the screen buffer.
@@ -728,6 +1298,16 @@ interface LayoutNode {
     computed: Rect;
     /** Dirty flag — true when this node needs to be re-laid-out. Foundation for layout caching. */
     _dirty: boolean;
+    /** Last container dimensions used — separate from computed so manual computed edits don't confuse sizeChanged detection */
+    _lastContainerWidth: number;
+    _lastContainerHeight: number;
+    /** Last computed dimensions — used to detect size changes in non-dirty nodes
+     *  so grandchildren are re-laid out when a parent recomputes this node's rect. */
+    _lastComputedWidth: number;
+    _lastComputedHeight: number;
+    /** Drag and drop support */
+    _draggable?: boolean;
+    _dragging?: boolean;
 }
 /**
  * Create a LayoutNode with default values.
@@ -747,52 +1327,7 @@ declare function createLayoutNode(id: string, style: Style, children?: LayoutNod
  * - gap between children
  */
 declare function computeLayout(root: LayoutNode, containerWidth: number, containerHeight: number): void;
-
-type Constraint = {
-    type: 'length';
-    value: number;
-} | {
-    type: 'percentage';
-    value: number;
-} | {
-    type: 'ratio';
-    num: number;
-    den: number;
-} | {
-    type: 'min';
-    value: number;
-} | {
-    type: 'max';
-    value: number;
-} | {
-    type: 'fill';
-    weight: number;
-};
-/** Exactly n cells. */
-declare const length: (n: number) => Constraint;
-/** n% of available space. */
-declare const percentage: (n: number) => Constraint;
-/** num/den of available space. */
-declare const ratio: (num: number, den: number) => Constraint;
-/** At least n cells. */
-declare const min: (n: number) => Constraint;
-/** At most n cells. */
-declare const max: (n: number) => Constraint;
-/** Fill remaining space with the given weight. Default weight: 1. */
-declare const fill: (weight?: number) => Constraint;
-/**
- * Split a rectangle into sub-rectangles using constraints.
- *
- * Example:
- * ```ts
- * const [header, body, footer] = splitRect(
- *     area,
- *     [length(3), fill(), length(1)],
- *     'vertical',
- * );
- * ```
- */
-declare function splitRect(rect: Rect, constraints: Constraint[], direction?: 'horizontal' | 'vertical', gap?: number): Rect[];
+declare function invalidateLayout(node: LayoutNode): void;
 
 /**
  * Strongly-typed event emitter using TypeScript generics.
@@ -841,6 +1376,7 @@ interface Focusable {
  * - Tab-order cycling (focusNext/focusPrev)
  * - Focus trapping (for modals — limits Tab to a container)
  * - Focus groups (for arrow-key navigation within a group)
+ * - 2D Spatial navigation (focusUp/Down/Left/Right)
  */
 declare class FocusManager {
     private _focusables;
@@ -861,13 +1397,30 @@ declare class FocusManager {
      * Maps groupId → ordered list of widget IDs.
      */
     private _groups;
+    /**
+     * Record of on-screen rects for widgets, used for spatial navigation.
+     */
+    private _rects;
+    /** Monotonically increasing epoch for ordered event sequencing */
+    private _epoch;
+    /** Queue of focus state changes accumulated before start() is called */
+    private _pendingQueue;
+    /** True once start() has been called — enables event emission */
+    private _started;
     /** Currently focused widget ID, or null if none */
     get currentId(): string | null;
     /** Subscribe to focus/blur events */
     on<K extends 'focus' | 'blur'>(event: K, handler: (data: FocusEvent) => void): () => void;
+    /**
+     * Enable event emission and replay any queued focus events.
+     * Call this from App.mount() after _subscribeFocusEvents().
+     */
+    start(): void;
     /**
      * Register a focusable widget.
      * Widgets are ordered by tabIndex (ascending), then insertion order.
+     * Before start() is called, events are queued rather than emitted so
+     * they are not lost when App has not yet subscribed to them.
      */
     register(focusable: Focusable): void;
     /**
@@ -933,6 +1486,17 @@ declare class FocusManager {
      * Move focus to the previous widget within the same group.
      */
     focusPrevInGroup(): boolean;
+    /** Record the on-screen rect for a widget, used for spatial navigation. */
+    setRect(id: string, rect: Rect): void;
+    private _spatialFocus;
+    /** Move focus to the nearest focusable widget above the current one. */
+    focusUp(): boolean;
+    /** Move focus to the nearest focusable widget below the current one. */
+    focusDown(): boolean;
+    /** Move focus to the nearest focusable widget to the left of the current one. */
+    focusLeft(): boolean;
+    /** Move focus to the nearest focusable widget to the right of the current one. */
+    focusRight(): boolean;
     /**
      * Get the active focusables, filtered by the current trap if any.
      */
@@ -1189,6 +1753,12 @@ interface AppOptions extends TerminalOptions {
     fps?: number;
     /** Use alternate screen (full-screen mode). Default: true */
     fullscreen?: boolean;
+    /** Merge adjacent borders into junction characters */
+    dockBorders?: boolean;
+    /** Screen mode: 'alternate' = alt screen (default), 'main' = render to main screen, 'inline' = render N rows at cursor */
+    screenMode?: 'alternate' | 'main' | 'inline';
+    /** Number of rows to render in inline mode (only used when screenMode='inline') */
+    inlineRows?: number;
     /** Enable mouse support. Default: false */
     mouse?: boolean;
     /** Force fallback (static) rendering */
@@ -1197,6 +1767,7 @@ interface AppOptions extends TerminalOptions {
     skipFallback?: boolean;
     /** Title to set on the terminal window */
     title?: string;
+    diffRenderer?: boolean;
 }
 /**
  * Widget interface that App expects for the root widget.
@@ -1216,14 +1787,6 @@ interface RootWidget {
 }
 /**
  * Application lifecycle manager.
- *
- * Manages:
- * - Terminal setup/teardown (alt screen, raw mode, cursor, mouse)
- * - Screen buffer and renderer initialization
- * - Input parsing and event dispatch
- * - Layout computation and rect sync
- * - Render loop
- * - Graceful shutdown
  */
 declare class App {
     readonly terminal: Terminal;
@@ -1239,22 +1802,30 @@ declare class App {
     private _exitResolve;
     private _unsubKey;
     private _unsubMouse;
+    private _unsubPaste;
+    private _unsubFocus;
+    private _unsubBlur;
+    private _unsubSigInt;
+    private _unsubSigTerm;
+    private _unsubUncaughtException;
+    private _unsubUnhandledRejection;
     private _widgetById;
+    private _pendingFocusState;
+    private _consecutiveRenderFailures;
+    private static readonly MAX_RENDER_FAILURES;
+    private _insertBefore;
+    private _isRenderPending;
     constructor(rootWidget: RootWidget, options?: AppOptions);
     /**
      * Start the application.
-     * Sets up the terminal, starts the render loop, and mounts the root widget.
-     * Returns a promise that resolves when exit() is called.
      */
     mount(): Promise<number>;
     /**
      * Stop the application and restore terminal state.
      */
-    unmount(): void;
+    unmount(exitCode?: number): void;
     /**
      * Create an overlay layer for rendering above normal widgets.
-     * @param id     Unique layer identifier (e.g. 'modal', 'select-dropdown', 'toast')
-     * @param zIndex Stacking order (higher = rendered on top). Default: 100
      */
     addOverlay(id: string, zIndex?: number): void;
     /**
@@ -1263,29 +1834,44 @@ declare class App {
     removeOverlay(id: string): void;
     /**
      * Request a re-render on the next frame.
-     * Skips layout + render pass when the root widget reports no dirty state.
+     * Batches rapid structural updates via setImmediate scheduling so that
+     * multiple synchronous state mutations collapse into a single render frame.
      */
     requestRender(): void;
     /**
      * Exit the app (convenience method).
      */
     exit(code?: number): void;
+    /**
+     * Read from the system clipboard.
+     */
+    readClipboard(): Promise<string>;
+    /**
+     * Write to the system clipboard.
+     */
+    writeClipboard(text: string): void;
+    /**
+     * Register a persistent line to be written above inline viewport output.
+     */
+    insertBefore(line: string): () => void;
     /**
      * Render in fallback (static) mode for non-interactive environments.
      */
     private _renderFallback;
     /**
      * Build the bubble chain for keyboard events.
-     * Returns an array: [focused widget, parent, grandparent, ..., root]
-     * Uses the cached _widgetById map for O(1) lookup instead of DFS.
      */
     private _buildBubbleChain;
     /**
      * Rebuild the widget ID cache by walking the entire widget tree.
-     * Called after syncLayout() so the map stays current.
      */
     private _buildWidgetMap;
     private _walkWidget;
+    private _handleFocusEvent;
+    private _setWidgetFocused;
+    private _subscribeFocusEvents;
+    private _applyPendingFocusState;
+    private _isFocusAwareWidget;
 }
 
 /**
@@ -1306,15 +1892,18 @@ declare function shouldUseFallback(): boolean;
  */
 declare function renderFallback(screen: Screen): string;
 
+interface InlineViewportOptions {
+    rows: number;
+}
 /**
- * Calculate the visual width of a string in terminal columns.
- *
- * - CJK characters count as 2 columns
- * - Emoji count as 2 columns
- * - Combining/zero-width characters count as 0
- * - ANSI escape sequences count as 0
- * - Regular characters count as 1
+ * Render the bottom `rows` of the provided `screen` to the terminal using plain text.
+ * Preserves scrollback by writing lines to stdout rather than taking over the alternate screen.
  */
+declare function renderInlineToTerminal(terminal: Terminal, screen: Screen, rows: number): void;
+declare function createInlineViewport(opts: InlineViewportOptions): {
+    rows: number;
+};
+
 declare function stringWidth(str: string): number;
 /**
  * Truncate a string to the given visual width, preserving ANSI codes.
@@ -1331,112 +1920,34 @@ declare function stripAnsi(str: string): string;
  */
 declare function wordWrap(str: string, width: number): string;
 
-/** CSI (Control Sequence Introducer) prefix */
-declare const CSI = "\u001B[";
-/** OSC (Operating System Command) prefix */
-declare const OSC = "\u001B]";
-/** ESC character */
-declare const ESC = "\u001B";
-declare const hideCursor = "\u001B[?25l";
-declare const showCursor = "\u001B[?25h";
-declare const saveCursorPosition = "\u001B[s";
-declare const restoreCursorPosition = "\u001B[u";
-declare function moveTo(col: number, row: number): string;
-declare function moveUp(n?: number): string;
-declare function moveDown(n?: number): string;
-declare function moveRight(n?: number): string;
-declare function moveLeft(n?: number): string;
-declare const clearScreen = "\u001B[2J";
-declare const clearLine = "\u001B[2K";
-declare const clearLineToEnd = "\u001B[0K";
-declare const clearLineToStart = "\u001B[1K";
-declare const clearDown = "\u001B[J";
-declare const clearUp = "\u001B[1J";
-declare const enterAltScreen = "\u001B[?1049h";
-declare const exitAltScreen = "\u001B[?1049l";
-/** Begin synchronized update — terminal holds display until end marker */
-declare const beginSyncUpdate = "\u001B[?2026h";
-/** End synchronized update — terminal flushes all pending changes atomically */
-declare const endSyncUpdate = "\u001B[?2026l";
-/** Enable SGR mouse tracking (most compatible modern mode) */
-declare const enableMouse = "\u001B[?1000h\u001B[?1002h\u001B[?1006h";
-/** Disable mouse tracking */
-declare const disableMouse = "\u001B[?1000l\u001B[?1002l\u001B[?1006l";
-declare const enableBracketedPaste = "\u001B[?2004h";
-declare const disableBracketedPaste = "\u001B[?2004l";
-declare const reset = "\u001B[0m";
-declare const bold = "\u001B[1m";
-declare const dim = "\u001B[2m";
-declare const italic = "\u001B[3m";
-declare const underline = "\u001B[4m";
-declare const blink = "\u001B[5m";
-declare const inverse = "\u001B[7m";
-declare const strikethrough = "\u001B[9m";
-declare const resetBold = "\u001B[22m";
-declare const resetDim = "\u001B[22m";
-declare const resetItalic = "\u001B[23m";
-declare const resetUnderline = "\u001B[24m";
-declare const resetBlink = "\u001B[25m";
-declare const resetInverse = "\u001B[27m";
-declare const resetStrikethrough = "\u001B[29m";
-declare function setScrollRegion(top: number, bottom: number): string;
-declare const resetScrollRegion = "\u001B[r";
-declare function setTitle(title: string): string;
+interface DebounceOptions {
+    /** Invoke on the leading edge of the timeout */
+    leading?: boolean;
+    /** Invoke on the trailing edge of the timeout */
+    trailing?: boolean;
+}
 /**
- * Write text to the system clipboard via OSC 52.
- * Supported by: xterm, iTerm2, Kitty, WezTerm, Alacritty, Windows Terminal.
- * @param text Plain text to copy to clipboard
- * @param stdout Target stream (default: process.stdout)
+ * Creates a debounced function that delays invoking `func` until after
+ * `wait` milliseconds have elapsed since the last time it was invoked.
+ *
+ * @param func The function to debounce
+ * @param wait The number of milliseconds to delay
+ * @param options.leading Invoke on the leading edge
+ * @param options.trailing Invoke on the trailing edge (default: true)
+ * @returns The debounced function with a `cancel()` method
+ *
+ * @example
+ * ```ts
+ * const search = debounce((query: string) => {
+ *   performSearch(query);
+ * }, 300);
+ *
+ * search('term'); // will execute 300ms after last call
+ * search.cancel(); // cancel pending execution
+ * ```
  */
-declare function writeClipboard(text: string, stdout?: NodeJS.WriteStream): void;
-
-declare const ansi_CSI: typeof CSI;
-declare const ansi_ESC: typeof ESC;
-declare const ansi_OSC: typeof OSC;
-declare const ansi_beginSyncUpdate: typeof beginSyncUpdate;
-declare const ansi_blink: typeof blink;
-declare const ansi_bold: typeof bold;
-declare const ansi_clearDown: typeof clearDown;
-declare const ansi_clearLine: typeof clearLine;
-declare const ansi_clearLineToEnd: typeof clearLineToEnd;
-declare const ansi_clearLineToStart: typeof clearLineToStart;
-declare const ansi_clearScreen: typeof clearScreen;
-declare const ansi_clearUp: typeof clearUp;
-declare const ansi_dim: typeof dim;
-declare const ansi_disableBracketedPaste: typeof disableBracketedPaste;
-declare const ansi_disableMouse: typeof disableMouse;
-declare const ansi_enableBracketedPaste: typeof enableBracketedPaste;
-declare const ansi_enableMouse: typeof enableMouse;
-declare const ansi_endSyncUpdate: typeof endSyncUpdate;
-declare const ansi_enterAltScreen: typeof enterAltScreen;
-declare const ansi_exitAltScreen: typeof exitAltScreen;
-declare const ansi_hideCursor: typeof hideCursor;
-declare const ansi_inverse: typeof inverse;
-declare const ansi_italic: typeof italic;
-declare const ansi_moveDown: typeof moveDown;
-declare const ansi_moveLeft: typeof moveLeft;
-declare const ansi_moveRight: typeof moveRight;
-declare const ansi_moveTo: typeof moveTo;
-declare const ansi_moveUp: typeof moveUp;
-declare const ansi_reset: typeof reset;
-declare const ansi_resetBlink: typeof resetBlink;
-declare const ansi_resetBold: typeof resetBold;
-declare const ansi_resetDim: typeof resetDim;
-declare const ansi_resetInverse: typeof resetInverse;
-declare const ansi_resetItalic: typeof resetItalic;
-declare const ansi_resetScrollRegion: typeof resetScrollRegion;
-declare const ansi_resetStrikethrough: typeof resetStrikethrough;
-declare const ansi_resetUnderline: typeof resetUnderline;
-declare const ansi_restoreCursorPosition: typeof restoreCursorPosition;
-declare const ansi_saveCursorPosition: typeof saveCursorPosition;
-declare const ansi_setScrollRegion: typeof setScrollRegion;
-declare const ansi_setTitle: typeof setTitle;
-declare const ansi_showCursor: typeof showCursor;
-declare const ansi_strikethrough: typeof strikethrough;
-declare const ansi_underline: typeof underline;
-declare const ansi_writeClipboard: typeof writeClipboard;
-declare namespace ansi {
-  export { ansi_CSI as CSI, ansi_ESC as ESC, ansi_OSC as OSC, ansi_beginSyncUpdate as beginSyncUpdate, ansi_blink as blink, ansi_bold as bold, ansi_clearDown as clearDown, ansi_clearLine as clearLine, ansi_clearLineToEnd as clearLineToEnd, ansi_clearLineToStart as clearLineToStart, ansi_clearScreen as clearScreen, ansi_clearUp as clearUp, ansi_dim as dim, ansi_disableBracketedPaste as disableBracketedPaste, ansi_disableMouse as disableMouse, ansi_enableBracketedPaste as enableBracketedPaste, ansi_enableMouse as enableMouse, ansi_endSyncUpdate as endSyncUpdate, ansi_enterAltScreen as enterAltScreen, ansi_exitAltScreen as exitAltScreen, ansi_hideCursor as hideCursor, ansi_inverse as inverse, ansi_italic as italic, ansi_moveDown as moveDown, ansi_moveLeft as moveLeft, ansi_moveRight as moveRight, ansi_moveTo as moveTo, ansi_moveUp as moveUp, ansi_reset as reset, ansi_resetBlink as resetBlink, ansi_resetBold as resetBold, ansi_resetDim as resetDim, ansi_resetInverse as resetInverse, ansi_resetItalic as resetItalic, ansi_resetScrollRegion as resetScrollRegion, ansi_resetStrikethrough as resetStrikethrough, ansi_resetUnderline as resetUnderline, ansi_restoreCursorPosition as restoreCursorPosition, ansi_saveCursorPosition as saveCursorPosition, ansi_setScrollRegion as setScrollRegion, ansi_setTitle as setTitle, ansi_showCursor as showCursor, ansi_strikethrough as strikethrough, ansi_underline as underline, ansi_writeClipboard as writeClipboard };
-}
+declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wait: number, options?: DebounceOptions): T & {
+    cancel: () => void;
+};
 
-export { App, type AppOptions, BLOCK, BORDER_CHARS, BOX, BRAILLE_DOTS, BRAILLE_OFFSET, BRAILLE_SPIN, type BarSet, BarSets, type BorderChars, type BorderSet, BorderSets, type BorderStyle, CTRL_KEYS, type Cell, type Color, ColorDepth, type Constraint, type ContrastFailure, ESCAPE_SEQUENCES, type Edges, EventEmitter, type EventMap, type FocusEvent, FocusManager, type Focusable, HORIZONTAL_BAR_SYMBOLS, InputParser, type KeyEvent, type Layer, LayerManager, type LayoutNode, type LineSet, LineSets, type MouseEvent, type NamedColor, type Rect, Renderer, type ResizeEvent, type RootWidget, SPECIAL_KEYS, Screen, type ScrollbarSet, ScrollbarSets, Shade, type Size, type Style, Terminal, type TerminalOptions, type TestScreen, VERTICAL_BAR_SYMBOLS, ansi, borderSize, caps, cellsEqual, colorToAnsiBg, colorToAnsiFg, colorToRgb, computeLayout, containsPoint, contrastRatio, createKeyEvent, createLayoutNode, createTestScreen, defaultStyle, detectColorDepth, emptyCell, emptyRect, fill, getBorderChars, intersectRect, isMouseSequence, length, max, mergeStyles, min, normalizeEdges, parseColor, parseMouseEvent, percentage, ratio, relativeLuminance, renderFallback, shouldUseFallback, shrinkRect, splitRect, stringWidth, stripAnsi, styleToCellAttrs, testScreenClear, testScreenGetCell, testScreenSetCell, testScreenSetString, testScreenToString, truncate, unionRect, validateThemeContrast, wcagLevel, wordWrap, writeClipboard };
+export { App, type AppOptions, BLOCK, BORDER_CHARS, BOX, BRAILLE_DOTS, BRAILLE_OFFSET, BRAILLE_SPIN, type BarSet, BarSets, type BorderChars, type BorderSet, BorderSets, type BorderStyle, CTRL_KEYS, type Cell, type Chord, ChordMatcher, type ChordMatcherOptions, type Color, ColorDepth, Constraint, type ContrastFailure, type DebounceOptions, Dim, ESCAPE_SEQUENCES, type Edges, EventEmitter, type EventMap, FillConstraint, Flex, type FocusEvent, FocusManager, type Focusable, HORIZONTAL_BAR_SYMBOLS, InputParser, type KeyEvent, type Layer, LayerManager, type LayoutNode, LengthConstraint, type LineSet, LineSets, LiveRender, MaxConstraint, MinConstraint, type MouseEvent, MouseGestures, type MouseGesturesOptions, type NamedColor, PercentageConstraint, Pos, type Rect, RenderHook, Renderer, type ResizeEvent, type ResolvableNode, type RootWidget, SPECIAL_KEYS, Screen, type ScrollbarSet, ScrollbarSets, Shade, type Size, type Style, Terminal, type TerminalOptions, type TestScreen, VERTICAL_BAR_SYMBOLS, ansi, bell, borderSize, caps, cellsEqual, clipboard, colorToAnsiBg, colorToAnsiFg, colorToRgb, computeLayout, containsPoint, contrastRatio, createInlineViewport, createKeyEvent, createLayoutNode, createTestScreen, debounce, defaultStyle, detectColorDepth, emptyCell, emptyRect, getBorderChars, hasLayoutChanges, intersectRect, invalidateLayout, isMouseSequence, mergeBorders, mergeStyles, normalizeEdges, normalizeNavigationKey, parseColor, parseMouseEvent, prefersHighContrast, prefersReducedMotion, readClipboard, relativeLuminance, renderFallback, renderInlineToTerminal, resolveConstraints, resolveLayoutVariables, shouldUseColor, shouldUseFallback, shrinkRect, stringWidth, stripAnsi, styleToCellAttrs, testScreenClear, testScreenGetCell, testScreenSetCell, testScreenSetString, testScreenToString, truncate, unionRect, validateThemeContrast, wcagLevel, wordWrap, writeClipboard };