@linxiraos/pi-tui 1.1.0 → 1.1.2

package/dist/types/keys.d.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 "@linxiraos/pi-natives";
+/** Whether the local process is running directly under Windows Terminal. */
+export declare function isWindowsTerminalSession(): boolean;
+/**
+ * Match ambiguous legacy Backspace bytes against an expected modifier mask.
+ *
+ * Windows Terminal encodes Ctrl+Backspace as raw `0x08` (BS) and plain
+ * Backspace as `0x7f` (DEL). Remote/container sessions lose terminal identity,
+ * and multiplexers (tmux/screen/Zellij) inherit `WT_SESSION` while emitting
+ * raw `0x08` for plain Backspace themselves, so the automatic heuristic is
+ * limited to direct Windows Terminal sessions. `PI_TUI_RAW_BACKSPACE_IS_CTRL=1`
+ * explicitly opts into the mapping everywhere.
+ */
+export declare function matchesRawBackspace(data: string, expectedModifier: number): boolean;
+/**
+ * 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`, `@oh-my-pi`) 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;
+export {};

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

@@ -0,0 +1,20 @@
+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,76 @@
+/**
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE), with
+ * runtime feature state and env overrides.
+ *
+ * Unicode placeholders let a transmitted image be displayed by writing ordinary
+ * text cells — the placeholder char U+10EEEE plus row/column combining
+ * diacritics — instead of a cursor-positioned `a=p` direct placement. The image
+ * then participates in the normal text grid, so it survives horizontal slicing,
+ * reflow and overlapping draws (each cell names its own row+column, so a sliced
+ * row still maps to the correct sub-region). See kitty
+ * `docs/graphics-protocol.rst` "Unicode placeholders for relative placements".
+ *
+ * This module is intentionally free of `./terminal-capabilities` imports so the
+ * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
+ * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
+ */
+/** 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 interface KittyGraphicsFeatures {
+    /** Display images via Unicode placeholders instead of direct `a=p` placement. */
+    unicodePlaceholders: boolean;
+}
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Kitty and Ghostty advertise placeholder support directly. A tmux session
+ * cannot use cursor-positioned placements because the outer terminal does not
+ * know pane scroll/reflow state, so an explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
+ * also opts into placeholders there — matching `timg -pk`. Automatic tmux
+ * fallback stays off because the unknown outer terminal may render U+10EEEE as
+ * literal PUA boxes (#1877).
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
+ * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.
+ */
+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 a `columns`×`rows` placeholder grid fits within the diacritic table. */
+export declare function kittyPlaceholdersFit(columns: number, rows: number): 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[];

package/dist/types/latex-block.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render a display LaTeX math fragment to lines with full 2-D layout: stacked
+ * fractions, stretchy delimiters, matrix grids, operator limits, drawn
+ * radicals. Top-level source newlines and `\\` become vertical rows (so a
+ * `lhs =` line stays above its block). Inline math should use `latexToUnicode`
+ * instead — fractions there stay single-line.
+ */
+export declare function latexToBlock(src: string): string[];

package/dist/types/latex-to-unicode.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Math font command names (`\mathbf`, `\mathbb`, …) whose single brace argument
+ * restyles glyphs. Exported for the display block engine (`latex-block`), which
+ * re-wraps inline runs inside these commands when their argument contains 2-D
+ * layout (fractions, matrices) so styling survives box boundaries.
+ */
+export declare const MATH_FONT_COMMANDS: ReadonlySet<string>;
+/**
+ * Painter for a LaTeX color scope (optional model + spec, e.g. `rgb`/`1,0,0` or
+ * `red`): returns a function that paints already-rendered text with the scope's
+ * foreground, re-asserting it after embedded foreground resets so nested color
+ * runs restore to the scope color; null when the color cannot be resolved. Used
+ * by the display block engine (`latex-block`) to paint structural glyphs
+ * (fraction bars, stretched delimiters, matrix brackets) inside
+ * `\color`/`\textcolor` scopes.
+ */
+export declare function latexColorScope(model: string | null, spec: string): ((text: string) => string) | null;
+/**
+ * Convert a bare LaTeX math fragment (no surrounding `$`/`\(` delimiters) to its
+ * best-effort Unicode rendering. Unknown commands degrade to their bare name;
+ * `\\` becomes a newline. Always returns a string (never throws).
+ */
+export declare function latexToUnicode(src: string): string;
+/**
+ * True when `env` is a math environment safe to auto-render without `$`/`\[`
+ * delimiters. The trailing `*` of starred variants (`align*`, `equation*`) is
+ * ignored; text-mode environments (`tabular`, `itemize`, …) return false.
+ */
+export declare function isBareMathEnvironment(env: string): boolean;
+/**
+ * Scan prose for math spans — `$$…$$`, `\[…\]` (display) and `$…$`, `\(…\)`
+ * (inline) — and replace each with its Unicode rendering, leaving everything
+ * else verbatim. Newlines inside a span collapse to spaces so the result stays
+ * single-line-safe.
+ *
+ * Inline `$…$` uses pandoc's anti-currency heuristics: the opener must not be
+ * followed by whitespace, the closer must not be preceded by whitespace nor
+ * followed by a digit, and `\$` is treated as a literal dollar — so "$5 and
+ * $10" is left untouched.
+ */
+export declare function renderMathInText(text: string): string;
+/**
+ * Index of the `$` that closes an inline math span opened at `open` (the index
+ * of the opening `$`), or -1 when the run is not inline math. Applies pandoc's
+ * anti-currency heuristics: the opener must not be followed by whitespace, the
+ * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
+ * literal dollar, and the span may not span a newline. Shared by
+ * `renderMathInText` and the markdown math tokenizer so the rule has one home.
+ */
+export declare function inlineMathSpanEnd(text: string, open: number): number;

package/dist/types/loop-watchdog.d.ts

@@ -0,0 +1,49 @@
+export interface LoopWatchdogOptions {
+    /** How far ahead each probe tick is scheduled, in ms. Default 250. */
+    intervalMs?: number;
+    /** A tick later than this past its deadline counts as a block. Default 250. */
+    thresholdMs?: number;
+    /** Overshoot beyond this is suppressed only when the process burned negligible CPU. Default 60_000. */
+    sleepMs?: number;
+    /** Monotonic clock source; injectable for tests. Default `performance.now`. */
+    now?: () => number;
+    /** Process CPU time in ms; injectable for tests. Default `process.cpuUsage`. */
+    cpuNow?: () => number;
+    /** Timer source; injectable for tests. Default `setTimeout`. */
+    schedule?: (cb: () => void, ms: number) => LoopWatchdogTimer;
+}
+/**
+ * Timer handle the watchdog arms. `cancel`, when present, is invoked on stop()
+ * so a stopped watchdog leaves no armed timer to wake the loop even once.
+ */
+interface LoopWatchdogTimer {
+    unref?(): void;
+    cancel?(): void;
+}
+/**
+ * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
+ * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
+ * the loop was blocked that long. The overshoot is logged once on the rising
+ * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
+ * active during the elapsed interval via {@link takeRecentLoopPhase} — which
+ * survives the synchronous push/pop the instrumented hot paths do before this
+ * delayed tick can run — so the stall names its cause instead of "unknown".
+ *
+ * The handle is `unref`'d so the probe never keeps the process alive, and stop()
+ * cancels the armed timer when the handle exposes `cancel` (the default
+ * `setTimeout` handle does, via `clearTimeout`). The `#generation` guard remains
+ * as a fallback for injected handles that cannot cancel.
+ *
+ * A long overshoot is classified by CPU time rather than by duration. System
+ * sleep and a CPU-bound wedge both produce an arbitrarily large gap, so duration
+ * alone cannot tell them apart, and suppressing on duration discards exactly the
+ * worst stalls. Only a gap the process spent negligible CPU on is treated as
+ * sleep. CPU accounting is process-wide, so worker activity errs toward logging.
+ */
+export declare class LoopWatchdog {
+    #private;
+    constructor(options?: LoopWatchdogOptions);
+    start(): void;
+    stop(): void;
+}
+export {};

package/dist/types/mouse.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SGR mouse report parsing (`\x1b[<button;col;rowM` / `…m`).
+ *
+ * Mouse tracking is enabled only while a fullscreen overlay holds the
+ * alternate screen (see tui.ts MOUSE_TRACKING_ON), so consumers are
+ * fullscreen components hit-testing against their own rendered frame:
+ * the frame paints from screen row 0, hence `row`/`col` are exposed
+ * 0-based for direct indexing into rendered lines.
+ */
+/** A decoded SGR mouse report. */
+export interface SgrMouseEvent {
+    /** Raw button code (bit 32 = motion, bit 64 = wheel, low bits = button). */
+    button: number;
+    /** 0-based column of the event. */
+    col: number;
+    /** 0-based row of the event. */
+    row: number;
+    /** True for a release report (`m` suffix). */
+    release: boolean;
+    /** Wheel direction: -1 up, 1 down, null when not a wheel event. */
+    wheel: -1 | 1 | null;
+    /** True when the pointer moved (hover or drag) rather than clicked. */
+    motion: boolean;
+    /** True for a left-button press (not motion, not release, not wheel). */
+    leftClick: boolean;
+}
+/**
+ * Decode an SGR mouse report, or return null when `data` is not one.
+ * Callers on hot keypress paths should pre-check `data.startsWith("\x1b[<")`
+ * before paying for the regex.
+ */
+export declare function parseSgrMouse(data: string): SgrMouseEvent | null;
+/** Handler invoked with a decoded SGR event; returning `false` reports unhandled. */
+export type SgrMouseHandler = (event: SgrMouseEvent) => boolean | undefined;
+/**
+ * Decode an SGR mouse report and forward it to `handler`. Returns `false` when
+ * `data` is not an SGR mouse report (or fails to parse), so callers can fall
+ * through to other input handling. Centralizes the repeated
+ * `data.startsWith("\x1b[<")` + `parseSgrMouse()` pattern.
+ */
+export declare function routeSgrMouseInput(data: string, handler: SgrMouseHandler): boolean;
+/**
+ * Structural view of a SelectList-like target for mouse routing. Declared here
+ * (rather than importing the component) to keep this core module free of any
+ * component-to-core import cycle.
+ */
+export interface SelectListMouseTarget {
+    handleWheel(delta: -1 | 1): void;
+    hitTest(line: number): number | undefined;
+    setHoverIndex(index: number | null): void;
+    clickItem(index: number): void;
+}
+/**
+ * Route a decoded mouse event against a SelectList-like target at the given
+ * 0-based frame-local `line`. Centralizes the repeated wheel/hit-test/hover/
+ * click pattern. Returns `true` when the event was consumed.
+ */
+export declare function routeSelectListMouse(target: SelectListMouseTarget, event: SgrMouseEvent, line: number): boolean;
+/**
+ * Implemented by components that accept routed mouse events at frame-local
+ * coordinates. Hosts translate screen coordinates to the component's own
+ * rendered lines before forwarding.
+ */
+export interface MouseRoutable {
+    /** `line`/`col` are 0-based within the component's rendered output. */
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/dist/types/stdin-buffer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * StdinBuffer buffers input and emits complete sequences.
+ *
+ * This is necessary because stdin data events can arrive in partial chunks,
+ * especially for escape sequences like mouse events. Without buffering,
+ * partial sequences can be misinterpreted as regular keypresses.
+ *
+ * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
+ * - Event 1: `\x1b`
+ * - Event 2: `[<35`
+ * - Event 3: `;20;5m`
+ *
+ * The buffer accumulates these until a complete sequence is detected.
+ * Call the `process()` method to feed input data.
+ *
+ * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
+ * MIT License - Copyright (c) 2025 opentui
+ */
+import { EventEmitter } from "events";
+export type StdinBufferOptions = {
+    /**
+     * Maximum time to wait for sequence completion (default: 75ms).
+     * After this time, a genuinely incomplete escape is flushed.
+     */
+    timeout?: number;
+    /**
+     * Maximum extra time (default: 150ms) an unambiguous escape partial — an
+     * SGR mouse prefix, or any dangling escape while the kitty keyboard
+     * protocol is active — is held past `timeout` waiting for its tail.
+     */
+    partialHoldTimeout?: number;
+    /**
+     * Paste-mode inactivity watchdog (default: 1000ms). If no input arrives for
+     * this long while waiting for the bracketed-paste end marker, the paste is
+     * assumed truncated: accumulated bytes are delivered and input recovers.
+     */
+    pasteTimeout?: number;
+    /**
+     * Paste-mode byte cap (default: 64 MiB). Exceeding it aborts paste mode the
+     * same way, bounding memory when the end marker never arrives.
+     */
+    pasteByteLimit?: number;
+};
+export type StdinBufferEventMap = {
+    data: [string];
+    paste: [string];
+};
+/**
+ * Buffers stdin input and emits complete sequences via the 'data' event.
+ * Handles partial escape sequences that arrive across multiple chunks.
+ */
+export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
+    #private;
+    constructor(options?: StdinBufferOptions);
+    process(data: string | Buffer): void;
+    flush(): string[];
+    clear(): void;
+    getBuffer(): string;
+    destroy(): void;
+}

package/dist/types/symbols.d.ts

@@ -0,0 +1,25 @@
+export interface BoxSymbols {
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+    teeDown: string;
+    teeUp: string;
+    teeLeft: string;
+    teeRight: string;
+    cross: string;
+}
+export interface SymbolTheme {
+    cursor: string;
+    inputCursor: string;
+    boxRound: Omit<BoxSymbols, "teeDown" | "teeUp" | "teeLeft" | "teeRight" | "cross">;
+    boxSharp: BoxSymbols;
+    table: BoxSymbols;
+    quoteBorder: string;
+    hrChar: string;
+    /** Chip glyph drawn (painted with the referenced color) before inline hex colors. */
+    colorSwatch?: string;
+    spinnerFrames: string[];
+}