@bomb.sh/tty 0.0.0-register.0

package/README.md

@@ -0,0 +1,227 @@
+# @bomb.sh/tty
+
+A low-level, platform-independent terminal renderer and event parser for
+JavaScript. You can use `@bomb.sh/tty` directly, or as the foundation for your
+own framework.
+
+## Features
+
+**Declarative terminal UI** — Build terminal interfaces the same way you'd build
+a web page. `@bomb.sh/tty` uses [Clay](https://github.com/nicbarker/clay) under
+the hood, giving you flexbox-like layout, pointer detection, and scroll
+containers — all rendered to the terminal as box-drawing characters and ANSI
+escape sequences.
+
+**Zero I/O** — `@bomb.sh/tty` never reads stdin or writes stdout. You feed it
+bytes and get bytes back. This makes it trivially embeddable in any framework,
+any runtime, any event loop. There are no opinions about how you do I/O, just
+pure computation.
+
+**Runs everywhere** — The entire engine is compiled to WebAssembly, so
+`@bomb.sh/tty` will run anywhere JavaScript runs with no native dependencies,
+and no build step for consumers.
+
+### Examples
+
+See this keyboard example and more in the [examples folder](examples/README.md).
+This demo uses `@bomb.sh/tty` for all layout and input parsing.
+
+#### Keyboard Events
+
+The input parser decodes raw terminal bytes into structured events. Here you can
+see each key event as the string "hello world" is typed.
+
+![Keyboard events demo](examples/keyboard/keyboard-key-events.gif)
+
+#### Pointer Events
+
+Here we see hover styles applied to UI elements in response to the pointer
+state. Clay drives the hit testing; no manual coordinate math required.
+
+![Pointer events demo](examples/keyboard/keyboard-pointer-events.gif)
+
+## Architecture
+
+`@bomb.sh/tty` does not do any I/O itself. On the ouput side, it converts UI
+elements into a raw sequence of bytes and pointer events, and on the input side,
+it converts a stream of raw bytes into structured events.
+
+### Output
+
+With every frame, the entire UI tree is packed into a flat byte array and sent
+to WASM in a single call. On the C side, Clay runs layout, render commands are
+walked into a cell buffer, and the buffer is diffed against the previous frame.
+Only the cells that actually changed produce output. The result is an ANSI
+escape sequence that can be written directly to stdout. One trip to WASM per
+frame, double buffered, and only the bytes that need to change hit the output
+stream.
+
+Because the WASM module is pure computation with no I/O, it runs anywhere
+WebAssembly does: Deno, Node, Bun, browsers, or any other runtime.
+
+```
+ TypeScript                        WASM (C)
++---------------+                +---------------------------+
+|               |  Uint32Array   |                           |
+| UI ops...     | =============> | Clay layout               |
+|               |                |   -> render commands      |
++---------------+                |   -> cell buffer (back)   |
+                                 |   -> diff against (front) |
+                                 |   -> escape bytes         |
++---------------+                |                           |
+|               | ANSI byte array|                           |
+| stdout.write  | <============= |                           |
+|               |                |                           |
++---------------+                +---------------------------+
+```
+
+### Input
+
+Raw bytes from stdin are fed into a WASM-based parser that recognizes VT/ANSI
+escape sequences, UTF-8 codepoints, and mouse protocols (VT200, SGR, urxvt). The
+parser maintains its own internal buffer so partial sequences that arrive across
+read boundaries are reassembled automatically. A lone ESC byte is held for a
+configurable latency window (default 25ms) before being emitted, giving
+multi-byte sequences time to arrive.
+
+```
+ TypeScript                        WASM (C)
++---------------+                +---------------------------+
+|               |  raw byte array|                           |
+| stdin.read    | =============> | trie match (keys/seqs)    |
+|               |                |   -> mouse protocol       |
+|               |                |   -> UTF-8 decode         |
++---------------+                |   -> ESC codes            |
+                                 |                           |
++---------------+                |                           |
+|               |  events[]      |                           |
+| KeyEvent      | <============= |                           |
+| MouseDownEvent|                |                           |
+| MouseUpEvent  |                +---------------------------+
+| MouseMoveEvent|
+| WheelEvent    |
+| ResizeEvent   |
++---------------+
+```
+
+## Usage
+
+### Rendering
+
+To render this:
+
+```
+╭───────────────╮
+│ Hello, World! │
+╰───────────────╯
+```
+
+```typescript
+import { close, createTerm, grow, open, rgba, text } from "@bomb.sh/tty";
+
+let term = await createTerm({ width: 80, height: 24 });
+
+let { output } = term.render([
+  open("root", {
+    layout: { width: grow(), height: grow(), direction: "ttb" },
+  }),
+  open("greeting", {
+    layout: { padding: { left: 1, right: 1 } },
+    border: {
+      color: rgba(0, 255, 0),
+      left: 1,
+      right: 1,
+      top: 1,
+      bottom: 1,
+    },
+    cornerRadius: { tl: 1, tr: 1, bl: 1, br: 1 },
+  }),
+  text("Hello, World!"),
+  close(),
+  close(),
+]);
+
+process.stdout.write(output);
+```
+
+### Pointer detection
+
+Pass pointer state to `render()` to have `@bomb.sh/tty` do hit detection and
+return pointer events in addition to the byte sequence.
+
+```typescript
+let { output, events } = term.render(
+  [
+    open("root", {
+      layout: { width: grow(), height: grow(), direction: "ltr" },
+    }),
+    open("sidebar", {
+      layout: { width: fixed(20), height: grow() },
+      bg: rgba(30, 30, 40),
+    }),
+    text("Sidebar"),
+    close(),
+    open("main", {
+      layout: { width: grow(), height: grow() },
+    }),
+    text("Main content"),
+    close(),
+    close(),
+  ],
+  {
+    pointer: { x: mouseX, y: mouseY, down: mouseDown },
+  },
+);
+
+for (let event of events) {
+  // { type: "pointerenter", id: "sidebar" }
+  // { type: "pointerleave", id: "sidebar" }
+  // { type: "pointerclick", id: "main" }
+  console.log(event);
+}
+
+process.stdout.write(output);
+```
+
+### Input parsing
+
+```typescript
+import { createInput } from "@bomb.sh/tty/input";
+
+let input = await createInput({ escLatency: 25 });
+
+process.stdin.setRawMode(true);
+let timer: ReturnType<typeof setTimeout> | undefined;
+
+process.stdin.on("data", (buf) => {
+  clearTimeout(timer);
+
+  let { events, pending } = input.scan(new Uint8Array(buf));
+
+  for (let event of events) {
+    dispatch(event);
+  }
+
+  // if a lone ESC is pending, wait and re-scan to flush it
+  if (pending) {
+    timer = setTimeout(() => {
+      let flush = input.scan();
+      for (let event of flush.events) {
+        dispatch(event);
+      }
+    }, pending.delay);
+  }
+});
+```
+
+## Development
+
+For local source builds, toolchain setup, and `clay` submodule instructions, see
+[BUILD.md](BUILD.md).
+
+Quick local validation:
+
+```sh
+make
+deno task test
+```

package/esm/input-native.d.ts

@@ -0,0 +1,102 @@
+export declare const EVENT_KEY = 1;
+export declare const EVENT_MOUSE = 2;
+export declare const EVENT_RESIZE = 3;
+export declare const EVENT_CURSOR = 4;
+export declare const MOD_ALT = 1;
+export declare const MOD_CTRL = 2;
+export declare const MOD_SHIFT = 4;
+export declare const MOD_MOTION = 8;
+export declare const MOD_RELEASE = 16;
+export declare const KEY_F1 = 65535;
+export declare const KEY_F2 = 65534;
+export declare const KEY_F3 = 65533;
+export declare const KEY_F4 = 65532;
+export declare const KEY_F5 = 65531;
+export declare const KEY_F6 = 65530;
+export declare const KEY_F7 = 65529;
+export declare const KEY_F8 = 65528;
+export declare const KEY_F9 = 65527;
+export declare const KEY_F10 = 65526;
+export declare const KEY_F11 = 65525;
+export declare const KEY_F12 = 65524;
+export declare const KEY_ARROW_UP = 65523;
+export declare const KEY_ARROW_DOWN = 65522;
+export declare const KEY_ARROW_LEFT = 65521;
+export declare const KEY_ARROW_RIGHT = 65520;
+export declare const KEY_HOME = 65519;
+export declare const KEY_END = 65518;
+export declare const KEY_INSERT = 65517;
+export declare const KEY_DELETE = 65516;
+export declare const KEY_PGUP = 65515;
+export declare const KEY_PGDN = 65514;
+export declare const KEY_BACKTAB = 65513;
+export declare const KEY_NUMPAD_0 = 65506;
+export declare const KEY_NUMPAD_1 = 65505;
+export declare const KEY_NUMPAD_2 = 65504;
+export declare const KEY_NUMPAD_3 = 65503;
+export declare const KEY_NUMPAD_4 = 65502;
+export declare const KEY_NUMPAD_5 = 65501;
+export declare const KEY_NUMPAD_6 = 65500;
+export declare const KEY_NUMPAD_7 = 65499;
+export declare const KEY_NUMPAD_8 = 65498;
+export declare const KEY_NUMPAD_9 = 65497;
+export declare const KEY_NUMPAD_DECIMAL = 65496;
+export declare const KEY_NUMPAD_DIVIDE = 65495;
+export declare const KEY_NUMPAD_MULTIPLY = 65494;
+export declare const KEY_NUMPAD_SUBTRACT = 65493;
+export declare const KEY_NUMPAD_ADD = 65492;
+export declare const KEY_NUMPAD_ENTER = 65491;
+export declare const KEY_NUMPAD_EQUAL = 65490;
+export declare const KEY_SHIFT_LEFT = 65489;
+export declare const KEY_SHIFT_RIGHT = 65488;
+export declare const KEY_CONTROL_LEFT = 65487;
+export declare const KEY_CONTROL_RIGHT = 65486;
+export declare const KEY_ALT_LEFT = 65485;
+export declare const KEY_ALT_RIGHT = 65484;
+export declare const KEY_SUPER_LEFT = 65483;
+export declare const KEY_SUPER_RIGHT = 65482;
+export declare const KEY_HYPER_LEFT = 65481;
+export declare const KEY_HYPER_RIGHT = 65480;
+export declare const KEY_META_LEFT = 65479;
+export declare const KEY_META_RIGHT = 65478;
+export declare const KEY_CAPS_LOCK = 65477;
+export declare const KEY_NUM_LOCK = 65476;
+export declare const KEY_SCROLL_LOCK = 65475;
+export declare const KEY_MOUSE_LEFT = 65512;
+export declare const KEY_MOUSE_RIGHT = 65511;
+export declare const KEY_MOUSE_MIDDLE = 65510;
+export declare const KEY_MOUSE_RELEASE = 65509;
+export declare const KEY_MOUSE_WHEEL_UP = 65508;
+export declare const KEY_MOUSE_WHEEL_DOWN = 65507;
+export declare const KEY_ESC = 27;
+export declare const KEY_ENTER = 13;
+export declare const KEY_TAB = 9;
+export declare const KEY_BACKSPACE = 127;
+export declare const KEY_SPACE = 32;
+export interface NativeInputEvent {
+    type: number;
+    mod: number;
+    key: number;
+    ch: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    action: number;
+    shifted: number;
+    base: number;
+    text: number[];
+}
+export declare function readEvent(view: DataView, ptr: number): NativeInputEvent;
+export interface InputNative {
+    memory: WebAssembly.Memory;
+    state: number;
+    buffer: number;
+    scan(st: number, buf: number, len: number, now: number): number;
+    count(st: number): number;
+    event(st: number, index: number): number;
+    delay(st: number): number;
+}
+export declare function createInputNative(escLatency: number): Promise<InputNative>;
+export declare const MAX_TERMINFO = 32768;
+export declare const SCAN_BUFFER_SIZE = 4096;

package/esm/input-native.js

@@ -0,0 +1,150 @@
+export const EVENT_KEY = 1;
+export const EVENT_MOUSE = 2;
+export const EVENT_RESIZE = 3;
+export const EVENT_CURSOR = 4;
+export const MOD_ALT = 1;
+export const MOD_CTRL = 2;
+export const MOD_SHIFT = 4;
+export const MOD_MOTION = 8;
+export const MOD_RELEASE = 16;
+export const KEY_F1 = 0xFFFF;
+export const KEY_F2 = 0xFFFE;
+export const KEY_F3 = 0xFFFD;
+export const KEY_F4 = 0xFFFC;
+export const KEY_F5 = 0xFFFB;
+export const KEY_F6 = 0xFFFA;
+export const KEY_F7 = 0xFFF9;
+export const KEY_F8 = 0xFFF8;
+export const KEY_F9 = 0xFFF7;
+export const KEY_F10 = 0xFFF6;
+export const KEY_F11 = 0xFFF5;
+export const KEY_F12 = 0xFFF4;
+export const KEY_ARROW_UP = 0xFFF3;
+export const KEY_ARROW_DOWN = 0xFFF2;
+export const KEY_ARROW_LEFT = 0xFFF1;
+export const KEY_ARROW_RIGHT = 0xFFF0;
+export const KEY_HOME = 0xFFEF;
+export const KEY_END = 0xFFEE;
+export const KEY_INSERT = 0xFFED;
+export const KEY_DELETE = 0xFFEC;
+export const KEY_PGUP = 0xFFEB;
+export const KEY_PGDN = 0xFFEA;
+export const KEY_BACKTAB = 0xFFE9;
+export const KEY_NUMPAD_0 = 0xFFE2;
+export const KEY_NUMPAD_1 = 0xFFE1;
+export const KEY_NUMPAD_2 = 0xFFE0;
+export const KEY_NUMPAD_3 = 0xFFDF;
+export const KEY_NUMPAD_4 = 0xFFDE;
+export const KEY_NUMPAD_5 = 0xFFDD;
+export const KEY_NUMPAD_6 = 0xFFDC;
+export const KEY_NUMPAD_7 = 0xFFDB;
+export const KEY_NUMPAD_8 = 0xFFDA;
+export const KEY_NUMPAD_9 = 0xFFD9;
+export const KEY_NUMPAD_DECIMAL = 0xFFD8;
+export const KEY_NUMPAD_DIVIDE = 0xFFD7;
+export const KEY_NUMPAD_MULTIPLY = 0xFFD6;
+export const KEY_NUMPAD_SUBTRACT = 0xFFD5;
+export const KEY_NUMPAD_ADD = 0xFFD4;
+export const KEY_NUMPAD_ENTER = 0xFFD3;
+export const KEY_NUMPAD_EQUAL = 0xFFD2;
+export const KEY_SHIFT_LEFT = 0xFFD1;
+export const KEY_SHIFT_RIGHT = 0xFFD0;
+export const KEY_CONTROL_LEFT = 0xFFCF;
+export const KEY_CONTROL_RIGHT = 0xFFCE;
+export const KEY_ALT_LEFT = 0xFFCD;
+export const KEY_ALT_RIGHT = 0xFFCC;
+export const KEY_SUPER_LEFT = 0xFFCB;
+export const KEY_SUPER_RIGHT = 0xFFCA;
+export const KEY_HYPER_LEFT = 0xFFC9;
+export const KEY_HYPER_RIGHT = 0xFFC8;
+export const KEY_META_LEFT = 0xFFC7;
+export const KEY_META_RIGHT = 0xFFC6;
+export const KEY_CAPS_LOCK = 0xFFC5;
+export const KEY_NUM_LOCK = 0xFFC4;
+export const KEY_SCROLL_LOCK = 0xFFC3;
+export const KEY_MOUSE_LEFT = 0xFFE8;
+export const KEY_MOUSE_RIGHT = 0xFFE7;
+export const KEY_MOUSE_MIDDLE = 0xFFE6;
+export const KEY_MOUSE_RELEASE = 0xFFE5;
+export const KEY_MOUSE_WHEEL_UP = 0xFFE4;
+export const KEY_MOUSE_WHEEL_DOWN = 0xFFE3;
+export const KEY_ESC = 0x1B;
+export const KEY_ENTER = 0x0D;
+export const KEY_TAB = 0x09;
+export const KEY_BACKSPACE = 0x7F;
+export const KEY_SPACE = 0x20;
+import { array, int32, offsets, struct, uint16, uint32, uint8, } from "./typedef.js";
+const MAX_TEXT_CODEPOINTS = 8;
+const InputEventLayout = struct({
+    type: uint8(),
+    mod: uint8(),
+    key: uint16(),
+    ch: uint32(),
+    x: int32(),
+    y: int32(),
+    w: int32(),
+    h: int32(),
+    action: uint8(),
+    shifted: uint32(),
+    base: uint32(),
+    text: array(uint32(), MAX_TEXT_CODEPOINTS),
+    text_len: uint8(),
+});
+const { type: OFFSET_TYPE, mod: OFFSET_MOD, key: OFFSET_KEY, ch: OFFSET_CH, x: OFFSET_X, y: OFFSET_Y, w: OFFSET_W, h: OFFSET_H, action: OFFSET_ACTION, text_len: OFFSET_TEXT_LEN, shifted: OFFSET_SHIFTED, base: OFFSET_BASE, text: OFFSET_TEXT, } = offsets(InputEventLayout);
+export function readEvent(view, ptr) {
+    let len = view.getUint8(ptr + OFFSET_TEXT_LEN);
+    let text = [];
+    for (let i = 0; i < len && i < MAX_TEXT_CODEPOINTS; i++) {
+        text.push(view.getUint32(ptr + OFFSET_TEXT + i * 4, true));
+    }
+    return {
+        type: view.getUint8(ptr + OFFSET_TYPE),
+        mod: view.getUint8(ptr + OFFSET_MOD),
+        key: view.getUint16(ptr + OFFSET_KEY, true),
+        ch: view.getUint32(ptr + OFFSET_CH, true),
+        x: view.getInt32(ptr + OFFSET_X, true),
+        y: view.getInt32(ptr + OFFSET_Y, true),
+        w: view.getInt32(ptr + OFFSET_W, true),
+        h: view.getInt32(ptr + OFFSET_H, true),
+        action: view.getUint8(ptr + OFFSET_ACTION),
+        shifted: view.getUint32(ptr + OFFSET_SHIFTED, true),
+        base: view.getUint32(ptr + OFFSET_BASE, true),
+        text,
+    };
+}
+import { compiled } from "./wasm.js";
+export async function createInputNative(escLatency) {
+    let memory = new WebAssembly.Memory({ initial: 4 });
+    let instance = await WebAssembly.instantiate(compiled, {
+        env: { memory },
+        clay: {
+            measureTextFunction() { },
+            queryScrollOffsetFunction(ret) {
+                let v = new DataView(memory.buffer);
+                v.setFloat32(ret, 0, true);
+                v.setFloat32(ret + 4, 0, true);
+            },
+        },
+    });
+    let exports = instance.exports;
+    let heap = exports.__heap_base.value;
+    let size = exports.input_size();
+    let state = exports.input_init(heap, escLatency);
+    let buffer = (heap + size + 7) & ~7;
+    return {
+        memory,
+        state,
+        buffer,
+        scan: exports.input_scan,
+        count: exports.input_count,
+        event: exports.input_event,
+        delay: exports.input_delay,
+    };
+}
+// Compiled terminfo entries are limited to 4096 bytes (legacy) or 32768
+// bytes (extended ncurses format). We use the extended limit as our upper
+// bound. See https://man7.org/linux/man-pages/man5/term.5.html
+export const MAX_TERMINFO = 32768;
+// Must match SCAN_BUFFER_SIZE in input.c — the maximum bytes input_scan()
+// can accept in a single call.
+export const SCAN_BUFFER_SIZE = 4096;

package/esm/input.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Terminal input parser.
+ *
+ * Thin wrapper around WASM `input_*` functions that decode raw VT/ANSI
+ * escape sequences into structured events. All parsing logic, state
+ * management, and buffering lives in WASM.
+ */
+/**
+ * Modifier keys held during a key or mouse event.
+ */
+export interface KeyModifiers {
+    alt?: true;
+    ctrl?: true;
+    shift?: true;
+}
+/**
+ * Physical key identity on a US PC-101 layout.
+ */
+export type KeyCode = "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" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | "," | "." | "/" | " " | "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "F9" | "F10" | "F11" | "F12" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End" | "Insert" | "Delete" | "PageUp" | "PageDown" | "Backtab" | "Backspace" | "Tab" | "Enter" | "Escape" | "Numpad0" | "Numpad1" | "Numpad2" | "Numpad3" | "Numpad4" | "Numpad5" | "Numpad6" | "Numpad7" | "Numpad8" | "Numpad9" | "NumpadDecimal" | "NumpadDivide" | "NumpadMultiply" | "NumpadSubtract" | "NumpadAdd" | "NumpadEnter" | "NumpadEqual" | "ShiftLeft" | "ShiftRight" | "ControlLeft" | "ControlRight" | "AltLeft" | "AltRight" | "SuperLeft" | "SuperRight" | "HyperLeft" | "HyperRight" | "MetaLeft" | "MetaRight" | "CapsLock" | "NumLock" | "ScrollLock";
+/**
+ * Shared key information present on all keyboard events.
+ */
+export interface KeyInfo extends KeyModifiers {
+    key: string;
+    code: KeyCode;
+}
+/**
+ * A key was pressed. Emitted at all enhancement levels.
+ * On legacy terminals, this is the only keyboard event type.
+ */
+export interface KeyDown extends KeyInfo {
+    type: "keydown";
+    shifted?: string;
+    text?: string;
+}
+/**
+ * A key is being held down (auto-repeat). Only emitted with
+ * Kitty enhancement level 2+ (report event types).
+ */
+export interface KeyRepeat extends KeyInfo {
+    type: "keyrepeat";
+    shifted?: string;
+    text?: string;
+}
+/**
+ * A key was released. Only emitted with Kitty enhancement
+ * level 2+ (report event types). Does not carry text,
+ * shifted, or base fields.
+ */
+export interface KeyUp extends KeyInfo {
+    type: "keyup";
+}
+export type KeyEvent = KeyDown | KeyRepeat | KeyUp;
+/**
+ * A mouse button was pressed.
+ */
+export interface MouseDownEvent extends KeyModifiers {
+    type: "mousedown";
+    /**
+     * Which mouse button triggered this event.
+     */
+    button: "left" | "right" | "middle";
+    /**
+     * `x` coordinate of this event
+     */
+    x: number;
+    /**
+     * `y` coordinate of this event
+     */
+    y: number;
+}
+/**
+ * A mouse button was released.
+ */
+export interface MouseUpEvent extends KeyModifiers {
+    type: "mouseup";
+    /**
+     * Which mouse button triggered this event.
+     *
+     * Note: "release" is not technically a button, but is used by
+     * `VT200` and `urxvt` protocols where the terminal reports a button
+     * release without indicating which button.
+     */
+    button: "left" | "right" | "middle" | "release";
+    /**
+     * `x` coordinate of this event
+     */
+    x: number;
+    /**
+     * `y` coordinate of this event
+     */
+    y: number;
+}
+/**
+ * Mouse movement while a button is held.
+ */
+export interface MouseMoveEvent extends KeyModifiers {
+    type: "mousemove";
+    /**
+     * Which mouse button is being held during the drag.
+     */
+    button: "left" | "right" | "middle";
+    /**
+     * Cursor column (0-based).
+     */
+    x: number;
+    /**
+     * Cursor row (0-based).
+     */
+    y: number;
+}
+/**
+ * A scroll wheel tick.
+ */
+export interface WheelEvent extends KeyModifiers {
+    type: "wheel";
+    /**
+     * Did the wheel move up or down
+     */
+    direction: "up" | "down";
+    /**
+     * Cursor column at the time of the scroll (0-based).
+     */
+    x: number;
+    /**
+     * Cursor row at the time of the scroll (0-based).
+     */
+    y: number;
+}
+/**
+ * Terminal resize notification.
+ */
+export interface ResizeEvent {
+    type: "resize";
+    /**
+     * New terminal width in columns.
+     */
+    width: number;
+    /**
+     * New terminal height in rows.
+     */
+    height: number;
+}
+/**
+ * Cursor position report (DSR response).
+ *
+ * Emitted when the terminal responds to a Device Status Report
+ * query (`\x1b[6n`) with the current cursor position.
+ */
+export interface CursorEvent {
+    type: "cursor";
+    /**
+     * Cursor row (1-based). Matches ECMA-48 DSR native format.
+     */
+    row: number;
+    /**
+     * Cursor column (1-based). Matches ECMA-48 DSR native format.
+     */
+    column: number;
+}
+import type { PointerEvent } from "./term.js";
+export type InputEvent = KeyEvent | MouseDownEvent | MouseUpEvent | MouseMoveEvent | WheelEvent | ResizeEvent | CursorEvent | PointerEvent;
+/**
+ * Result of a single scan() call.
+ *
+ * When `pending` is present, a lone ESC is buffered and the caller should
+ * re-call scan() with an empty buffer after `pending.delay` milliseconds.
+ */
+export interface ScanResult {
+    events: InputEvent[];
+    pending?: {
+        delay: number;
+    };
+}
+export interface Input {
+    /**
+     * Feed raw bytes from stdin into the parser and return any events
+     * produced. Call with no arguments to flush a pending ESC after the
+     * latency period has elapsed.
+     *
+     * @example
+     * ```ts
+     * let { events, pending } = input.scan(bytes);
+     * for (let event of events) {
+     *   dispatch(event);
+     * }
+     * if (pending) {
+     *   // there is a pending ESC event. wait for the delay
+     *   await sleep(pending.delay);
+     *
+     *   // re-scan
+     *   let flush = input.scan();
+     *
+     *   //dispatch the flushed ESC
+     *   for (let event of flush.events) {
+     *     dispatch(event)
+     *   }
+     * }
+     * ```
+     */
+    scan(bytes?: Uint8Array): ScanResult;
+}
+export interface InputOptions {
+    /**
+     * Milliseconds to wait before resolving a lone ESC byte as the Escape
+     * key rather than the start of an escape sequence. Lower values feel
+     * snappier but risk misinterpreting sequences on slow connections.
+     *
+     * For reference, Vim's `ttimeoutlen` defaults to 100ms and ncurses
+     * `ESCDELAY` defaults to 1000ms. The default of 25ms is tuned for
+     * local terminals where escape sequences arrive within microseconds.
+     *
+     * @default 25
+     */
+    escLatency?: number;
+    /**
+     * Compiled terminfo binary to load terminal-specific escape sequences.
+     *
+     * This is the format used by files like /usr/lib/terminfo/78/xterm-256color
+     * and they can be directly loaded from disk into this option.
+     *
+     * If no terminfo is provided it will use xterm capabilities as the default
+     */
+    terminfo?: Uint8Array;
+}
+export declare function createInput(options?: InputOptions): Promise<Input>;