ghostty-web 0.3.0 → 0.4.0-next.0.g9e4e126

package/dist/index.d.ts

@@ -13,7 +13,9 @@ export declare class CanvasRenderer {
     private cursorBlinkInterval?;
     private lastCursorPosition;
     private lastViewportY;
+    private currentBuffer;
     private selectionManager?;
+    private currentSelectionCoords;
     private hoveredHyperlinkId;
     private previousHoveredHyperlinkId;
     private hoveredLinkRange;
@@ -34,13 +36,28 @@ export declare class CanvasRenderer {
      */
     render(buffer: IRenderable, forceAll?: boolean, viewportY?: number, scrollbackProvider?: IScrollbackProvider, scrollbarOpacity?: number): void;
     /**
-     * Render a single line
+     * Render a single line using two-pass approach:
+     * 1. First pass: Draw all cell backgrounds
+     * 2. Second pass: Draw all cell text and decorations
+     *
+     * This two-pass approach is necessary for proper rendering of complex scripts
+     * like Devanagari where diacritics (like vowel sign ि) can extend LEFT of the
+     * base character into the previous cell's visual area. If we draw backgrounds
+     * and text in a single pass (cell by cell), the background of cell N would
+     * cover any left-extending portions of graphemes from cell N-1.
      */
     private renderLine;
     /**
-     * Render a single cell
+     * Render a cell's background only (Pass 1 of two-pass rendering)
+     * Selection highlighting is integrated here to avoid z-order issues with
+     * complex glyphs (like Devanagari) that extend outside their cell bounds.
+     */
+    private renderCellBackground;
+    /**
+     * Render a cell's text and decorations (Pass 2 of two-pass rendering)
+     * Selection foreground color is applied here to match the selection background.
      */
-    private renderCell;
+    private renderCellText;
     /**
      * Render cursor
      */
@@ -82,9 +99,14 @@ export declare class CanvasRenderer {
      */
     getCanvas(): HTMLCanvasElement;
     /**
-     * Set selection manager (for rendering selection overlay)
+     * Set selection manager (for rendering selection)
      */
     setSelectionManager(manager: SelectionManager): void;
+    /**
+     * Check if a cell at (x, y) is within the current selection.
+     * Uses cached selection coordinates for performance.
+     */
+    private isInSelection;
     /**
      * Set the currently hovered hyperlink ID for rendering underlines
      */
@@ -111,10 +133,6 @@ export declare class CanvasRenderer {
      * Clear entire canvas
      */
     clear(): void;
-    /**
-     * Render selection overlay
-     */
-    private renderSelection;
     /**
      * Cleanup resources
      */
@@ -144,6 +162,15 @@ export declare interface Cursor {
     visible: boolean;
 }
 
+/**
+ * Dirty state from RenderState
+ */
+declare enum DirtyState {
+    NONE = 0,
+    PARTIAL = 1,
+    FULL = 2
+}
+
 export declare class EventEmitter<T> {
     private listeners;
     fire(arg: T): void;
@@ -212,23 +239,10 @@ export declare class Ghostty {
     private exports;
     private memory;
     constructor(wasmInstance: WebAssembly.Instance);
-    /**
-     * Get current memory buffer (may change when memory grows)
-     */
-    private getBuffer;
-    /**
-     * Create a key encoder instance
-     */
     createKeyEncoder(): KeyEncoder;
-    /**
-     * Create a terminal emulator instance
-     */
     createTerminal(cols?: number, rows?: number, config?: GhosttyTerminalConfig): GhosttyTerminal;
-    /**
-     * Load Ghostty WASM from URL or file path
-     * If no path is provided, attempts to load from common default locations
-     */
     static load(wasmPath?: string): Promise<Ghostty>;
+    private static loadFromPath;
 }
 
 /**
@@ -245,25 +259,16 @@ export declare interface GhosttyCell {
     flags: number;
     width: number;
     hyperlink_id: number;
+    grapheme_len: number;
 }
 
 /**
- * GhosttyTerminal - Wraps the WASM terminal emulator
+ * GhosttyTerminal - High-performance terminal emulator
  *
- * Provides a TypeScript-friendly interface to Ghostty's complete
- * terminal implementation via WASM.
- *
- * @example
- * ```typescript
- * const ghostty = await Ghostty.load('./ghostty-vt.wasm');
- * const term = ghostty.createTerminal(80, 24);
- *
- * term.write('Hello\x1b[31m Red\x1b[0m\n');
- * const cursor = term.getCursor();
- * const cells = term.getLine(0);
- *
- * term.free();
- * ```
+ * Uses Ghostty's native RenderState for optimal performance:
+ * - ONE call to update all state (renderStateUpdate)
+ * - ONE call to get all cells (getViewport)
+ * - No per-row WASM boundary crossings!
  */
 export declare class GhosttyTerminal {
     private exports;
@@ -271,186 +276,145 @@ export declare class GhosttyTerminal {
     private handle;
     private _cols;
     private _rows;
-    /**
-     * Size of ghostty_cell_t in bytes (16 bytes in WASM)
-     * Structure: codepoint(u32) + fg_rgb(3xu8) + bg_rgb(3xu8) + flags(u8) + width(u8) + hyperlink_id(u16) + padding(u32)
-     */
+    /** Size of GhosttyCell in WASM (16 bytes) */
     private static readonly CELL_SIZE;
-    /**
-     * Create a new terminal.
-     *
-     * @param exports WASM exports
-     * @param memory WASM memory
-     * @param cols Number of columns (default: 80)
-     * @param rows Number of rows (default: 24)
-     * @param config Optional terminal configuration (colors, scrollback)
-     * @throws Error if allocation fails
-     */
+    /** Reusable buffer for viewport operations */
+    private viewportBufferPtr;
+    private viewportBufferSize;
+    /** Cell pool for zero-allocation rendering */
+    private cellPool;
     constructor(exports: GhosttyWasmExports, memory: WebAssembly.Memory, cols?: number, rows?: number, config?: GhosttyTerminalConfig);
-    /**
-     * Free the terminal. Must be called to prevent memory leaks.
-     */
+    get cols(): number;
+    get rows(): number;
+    write(data: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
     free(): void;
     /**
-     * Write data to terminal (parses VT sequences and updates screen).
+     * Update render state from terminal.
      *
-     * @param data UTF-8 string or Uint8Array
+     * This syncs the RenderState with the current Terminal state.
+     * The dirty state (full/partial/none) is stored in the WASM RenderState
+     * and can be queried via isRowDirty(). When dirty==full, isRowDirty()
+     * returns true for ALL rows.
      *
-     * @example
-     * ```typescript
-     * term.write('Hello, World!\n');
-     * term.write('\x1b[1;31mBold Red\x1b[0m\n');
-     * term.write(new Uint8Array([0x1b, 0x5b, 0x41])); // Up arrow
-     * ```
-     */
-    write(data: string | Uint8Array): void;
-    /**
-     * Resize the terminal.
+     * The WASM layer automatically detects screen switches (normal <-> alternate)
+     * and returns FULL dirty state when switching screens (e.g., vim exit).
      *
-     * @param cols New column count
-     * @param rows New row count
+     * Safe to call multiple times - dirty state persists until markClean().
      */
-    resize(cols: number, rows: number): void;
+    update(): DirtyState;
     /**
-     * Get terminal dimensions.
+     * Get cursor state from render state.
+     * Ensures render state is fresh by calling update().
      */
-    get cols(): number;
-    get rows(): number;
+    getCursor(): RenderStateCursor;
     /**
-     * Get terminal dimensions (for IRenderable compatibility)
+     * Get default colors from render state
      */
-    getDimensions(): {
-        cols: number;
-        rows: number;
-    };
+    getColors(): RenderStateColors;
     /**
-     * Get cursor position and visibility.
+     * Check if a specific row is dirty
      */
-    getCursor(): Cursor;
+    isRowDirty(y: number): boolean;
     /**
-     * Get scrollback length (number of lines in history).
+     * Mark render state as clean (call after rendering)
      */
-    getScrollbackLength(): number;
+    markClean(): void;
     /**
-     * Check if terminal is in alternate screen buffer mode.
-     *
-     * The alternate screen is used by vim, less, htop, etc.
-     * When active, normal buffer is preserved and restored when the app exits.
-     *
-     * @returns true if in alternate screen, false if in normal screen
-     *
-     * @example
-     * ```typescript
-     * // Detect if vim is running
-     * if (term.isAlternateScreen()) {
-     *   console.log('Full-screen app is active');
-     * }
-     * ```
+     * Get ALL viewport cells in ONE WASM call - the key performance optimization!
+     * Returns a reusable cell array (zero allocation after warmup).
      */
-    isAlternateScreen(): boolean;
+    getViewport(): GhosttyCell[];
     /**
-     * Check if a row is wrapped from the previous row.
-     *
-     * Wrapped rows are continuations of long lines that exceeded terminal width.
-     * Used for text selection to treat wrapped lines as single logical lines.
-     *
-     * @param row Row index (0 = top visible line)
-     * @returns true if row continues from previous line, false otherwise
-     *
-     * @example
-     * ```typescript
-     * // Get full logical line including wraps
-     * let text = '';
-     * for (let row = 0; row < term.rows; row++) {
-     *   const line = term.getLine(row);
-     *   text += lineToString(line);
-     *
-     *   // Only add newline if NOT wrapped
-     *   if (!term.isRowWrapped(row + 1)) {
-     *     text += '\n';
-     *   }
-     * }
-     * ```
-     */
-    isRowWrapped(row: number): boolean;
-    /**
-     * Get a line of cells from the visible screen.
-     *
-     * @param y Line number (0 = top visible line)
-     * @returns Array of cells, or null if y is out of bounds
-     *
-     * @example
-     * ```typescript
-     * const cells = term.getLine(0);
-     * if (cells) {
-     *   for (const cell of cells) {
-     *     const char = String.fromCodePoint(cell.codepoint);
-     *     const isBold = (cell.flags & CellFlags.BOLD) !== 0;
-     *     console.log(`"${char}" ${isBold ? 'bold' : 'normal'}`);
-     *   }
-     * }
-     * ```
+     * Get line - for compatibility, extracts from viewport.
+     * Ensures render state is fresh by calling update().
+     * Returns a COPY of the cells to avoid pool reference issues.
      */
     getLine(y: number): GhosttyCell[] | null;
-    /**
-     * Get a line from scrollback history.
-     *
-     * @param offset Line offset from top of scrollback (0 = oldest line)
-     * @returns Array of cells, or null if not available
-     */
-    getScrollbackLine(offset: number): GhosttyCell[] | null;
-    /**
-     * Check if any part of the screen is dirty.
-     */
+    /** For compatibility with old API */
     isDirty(): boolean;
     /**
-     * Check if a specific row is dirty.
-     */
-    isRowDirty(y: number): boolean;
-    /**
-     * Clear all dirty flags (call after rendering).
+     * Check if a full redraw is needed (screen change, resize, etc.)
+     * Note: This calls update() to ensure fresh state. Safe to call multiple times.
      */
+    needsFullRedraw(): boolean;
+    /** Mark render state as clean after rendering */
     clearDirty(): void;
+    isAlternateScreen(): boolean;
+    hasBracketedPaste(): boolean;
+    hasFocusEvents(): boolean;
+    hasMouseTracking(): boolean;
+    /** Get dimensions - for compatibility */
+    getDimensions(): {
+        cols: number;
+        rows: number;
+    };
+    /** Get number of scrollback lines (history, not including active screen) */
+    getScrollbackLength(): number;
     /**
-     * Get all visible lines at once (convenience method).
-     *
-     * @returns Array of line arrays, or empty array on error
+     * Get a line from the scrollback buffer.
+     * Ensures render state is fresh by calling update().
+     * @param offset 0 = oldest line, (length-1) = most recent scrollback line
      */
-    getAllLines(): GhosttyCell[][];
+    getScrollbackLine(offset: number): GhosttyCell[] | null;
+    /** Check if a row in the active screen is wrapped (soft-wrapped to next line) */
+    isRowWrapped(row: number): boolean;
+    /** Hyperlink URI not yet exposed in simplified API */
+    getHyperlinkUri(_id: number): string | null;
     /**
-     * Get only the dirty lines (for optimized rendering).
-     *
-     * @returns Map of row number to cell array
+     * Check if there are pending responses from the terminal.
+     * Responses are generated by escape sequences like DSR (Device Status Report).
      */
-    getDirtyLines(): Map<number, GhosttyCell[]>;
+    hasResponse(): boolean;
     /**
-     * Get hyperlink URI by ID
+     * Read pending responses from the terminal.
+     * Returns the response string, or null if no responses pending.
      *
-     * @param hyperlinkId Hyperlink ID from a GhosttyCell (0 = no link)
-     * @returns URI string or null if ID is invalid/not found
+     * Responses are generated by escape sequences that require replies:
+     * - DSR 6 (cursor position): Returns \x1b[row;colR
+     * - DSR 5 (operating status): Returns \x1b[0n
      */
-    getHyperlinkUri(hyperlinkId: number): string | null;
+    readResponse(): string | null;
     /**
-     * Query terminal mode state
+     * Query arbitrary terminal mode by number
+     * @param mode Mode number (e.g., 25 for cursor visibility, 2004 for bracketed paste)
+     * @param isAnsi True for ANSI modes, false for DEC modes (default: false)
      */
     getMode(mode: number, isAnsi?: boolean): boolean;
+    private initCellPool;
+    private parseCellsIntoPool;
+    /** Small buffer for grapheme lookups (reused to avoid allocation) */
+    private graphemeBuffer;
+    private graphemeBufferPtr;
     /**
-     * Check if bracketed paste mode is enabled
+     * Get all codepoints for a grapheme cluster at the given position.
+     * For most cells this returns a single codepoint, but for complex scripts
+     * (Hindi, emoji with ZWJ, etc.) it returns multiple codepoints.
+     * @returns Array of codepoints, or null on error
      */
-    hasBracketedPaste(): boolean;
+    getGrapheme(row: number, col: number): number[] | null;
     /**
-     * Check if focus event reporting is enabled
+     * Get a string representation of the grapheme at the given position.
+     * This properly handles complex scripts like Hindi, emoji with ZWJ, etc.
      */
-    hasFocusEvents(): boolean;
+    getGraphemeString(row: number, col: number): string;
     /**
-     * Check if mouse tracking is enabled
+     * Get all codepoints for a grapheme cluster in the scrollback buffer.
+     * @param offset Scrollback line offset (0 = oldest)
+     * @param col Column index
+     * @returns Array of codepoints, or null on error
      */
-    hasMouseTracking(): boolean;
+    getScrollbackGrapheme(offset: number, col: number): number[] | null;
+    /**
+     * Get a string representation of a grapheme in the scrollback buffer.
+     */
+    getScrollbackGraphemeString(offset: number, col: number): string;
+    private invalidateBuffers;
 }
 
 /**
- * Terminal configuration for WASM.
- * All colors use 0xRRGGBB format. A value of 0 means "use default".
+ * Terminal configuration (passed to ghostty_terminal_new_with_config)
+ * All color values use 0xRRGGBB format. A value of 0 means "use default".
  */
 declare interface GhosttyTerminalConfig {
     scrollbackLimit?: number;
@@ -497,26 +461,29 @@ declare interface GhosttyWasmExports extends WebAssembly.Exports {
     ghostty_terminal_new(cols: number, rows: number): TerminalHandle;
     ghostty_terminal_new_with_config(cols: number, rows: number, configPtr: number): TerminalHandle;
     ghostty_terminal_free(terminal: TerminalHandle): void;
-    ghostty_terminal_write(terminal: TerminalHandle, dataPtr: number, dataLen: number): void;
     ghostty_terminal_resize(terminal: TerminalHandle, cols: number, rows: number): void;
-    ghostty_terminal_get_cols(terminal: TerminalHandle): number;
-    ghostty_terminal_get_rows(terminal: TerminalHandle): number;
-    ghostty_terminal_get_cursor_x(terminal: TerminalHandle): number;
-    ghostty_terminal_get_cursor_y(terminal: TerminalHandle): number;
-    ghostty_terminal_get_cursor_visible(terminal: TerminalHandle): boolean;
+    ghostty_terminal_write(terminal: TerminalHandle, dataPtr: number, dataLen: number): void;
+    ghostty_render_state_update(terminal: TerminalHandle): number;
+    ghostty_render_state_get_cols(terminal: TerminalHandle): number;
+    ghostty_render_state_get_rows(terminal: TerminalHandle): number;
+    ghostty_render_state_get_cursor_x(terminal: TerminalHandle): number;
+    ghostty_render_state_get_cursor_y(terminal: TerminalHandle): number;
+    ghostty_render_state_get_cursor_visible(terminal: TerminalHandle): boolean;
+    ghostty_render_state_get_bg_color(terminal: TerminalHandle): number;
+    ghostty_render_state_get_fg_color(terminal: TerminalHandle): number;
+    ghostty_render_state_is_row_dirty(terminal: TerminalHandle, row: number): boolean;
+    ghostty_render_state_mark_clean(terminal: TerminalHandle): void;
+    ghostty_render_state_get_viewport(terminal: TerminalHandle, bufPtr: number, bufLen: number): number;
+    ghostty_render_state_get_grapheme(terminal: TerminalHandle, row: number, col: number, bufPtr: number, bufLen: number): number;
     ghostty_terminal_is_alternate_screen(terminal: TerminalHandle): boolean;
-    ghostty_terminal_is_row_wrapped(terminal: TerminalHandle, row: number): boolean;
-    ghostty_terminal_is_dirty(terminal: TerminalHandle): boolean;
-    ghostty_terminal_is_row_dirty(terminal: TerminalHandle, row: number): boolean;
-    ghostty_terminal_clear_dirty(terminal: TerminalHandle): void;
-    ghostty_terminal_get_hyperlink_uri(terminal: TerminalHandle, hyperlinkId: number, bufPtr: number, bufLen: number): number;
-    ghostty_terminal_get_line(terminal: TerminalHandle, row: number, bufPtr: number, bufLen: number): number;
-    ghostty_terminal_get_scrollback_line(terminal: TerminalHandle, offset: number, bufPtr: number, bufLen: number): number;
-    ghostty_terminal_get_scrollback_length(terminal: TerminalHandle): number;
-    ghostty_terminal_get_mode(terminal: TerminalHandle, mode: number, isAnsi: number): number;
-    ghostty_terminal_has_bracketed_paste(terminal: TerminalHandle): number;
-    ghostty_terminal_has_focus_events(terminal: TerminalHandle): number;
     ghostty_terminal_has_mouse_tracking(terminal: TerminalHandle): number;
+    ghostty_terminal_get_mode(terminal: TerminalHandle, mode: number, isAnsi: boolean): number;
+    ghostty_terminal_get_scrollback_length(terminal: TerminalHandle): number;
+    ghostty_terminal_get_scrollback_line(terminal: TerminalHandle, offset: number, bufPtr: number, bufLen: number): number;
+    ghostty_terminal_get_scrollback_grapheme(terminal: TerminalHandle, offset: number, col: number, bufPtr: number, bufLen: number): number;
+    ghostty_terminal_is_row_wrapped(terminal: TerminalHandle, row: number): number;
+    ghostty_terminal_has_response(terminal: TerminalHandle): boolean;
+    ghostty_terminal_read_response(terminal: TerminalHandle, bufPtr: number, bufLen: number): number;
 }
 
 /**
@@ -744,9 +711,14 @@ export declare class InputHandler {
     private onBellCallback;
     private onKeyCallback?;
     private customKeyEventHandler?;
+    private getModeCallback?;
     private keydownListener;
     private keypressListener;
     private pasteListener;
+    private compositionStartListener;
+    private compositionUpdateListener;
+    private compositionEndListener;
+    private isComposing;
     private isDisposed;
     /**
      * Create a new InputHandler
@@ -756,8 +728,9 @@ export declare class InputHandler {
      * @param onBell - Callback for bell/beep event
      * @param onKey - Optional callback for raw key events
      * @param customKeyEventHandler - Optional custom key event handler
+     * @param getMode - Optional callback to query terminal mode state (for application cursor mode)
      */
-    constructor(ghostty: Ghostty, container: HTMLElement, onData: (data: string) => void, onBell: () => void, onKey?: (keyEvent: IKeyEvent) => void, customKeyEventHandler?: (event: KeyboardEvent) => boolean);
+    constructor(ghostty: Ghostty, container: HTMLElement, onData: (data: string) => void, onBell: () => void, onKey?: (keyEvent: IKeyEvent) => void, customKeyEventHandler?: (event: KeyboardEvent) => boolean, getMode?: (mode: number) => boolean);
     /**
      * Set custom key event handler (for runtime updates)
      */
@@ -794,6 +767,18 @@ export declare class InputHandler {
      * @param event - ClipboardEvent
      */
     private handlePaste;
+    /**
+     * Handle compositionstart event
+     */
+    private handleCompositionStart;
+    /**
+     * Handle compositionupdate event
+     */
+    private handleCompositionUpdate;
+    /**
+     * Handle compositionend event
+     */
+    private handleCompositionEnd;
     /**
      * Dispose the InputHandler and remove event listeners
      */
@@ -816,7 +801,15 @@ export declare interface IRenderable {
         rows: number;
     };
     isRowDirty(y: number): boolean;
+    /** Returns true if a full redraw is needed (e.g., screen change) */
+    needsFullRedraw?(): boolean;
     clearDirty(): void;
+    /**
+     * Get the full grapheme string for a cell at (row, col).
+     * For cells with grapheme_len > 0, this returns all codepoints combined.
+     * For simple cells, returns the single character.
+     */
+    getGraphemeString?(row: number, col: number): string;
 }
 
 declare interface IScrollbackProvider {
@@ -938,119 +931,186 @@ export declare interface IUnicodeVersionProvider {
 }
 
 /**
- * Physical key codes (based on USB HID Usage Tables - Keyboard/Keypad Page 0x07)
- * Reference: https://www.usb.org/sites/default/files/hut1_21.pdf
+ * Physical key codes matching Ghostty's internal Key enum.
+ * These values are used by Ghostty's key encoder to produce correct escape sequences.
+ * Reference: ghostty/src/input/key.zig
  */
 export declare enum Key {
-    A = 4,
-    B = 5,
-    C = 6,
-    D = 7,
-    E = 8,
-    F = 9,
-    G = 10,
-    H = 11,
-    I = 12,
-    J = 13,
-    K = 14,
-    L = 15,
-    M = 16,
-    N = 17,
-    O = 18,
-    P = 19,
-    Q = 20,
-    R = 21,
-    S = 22,
-    T = 23,
-    U = 24,
-    V = 25,
-    W = 26,
-    X = 27,
-    Y = 28,
-    Z = 29,
-    ONE = 30,
-    TWO = 31,
-    THREE = 32,
-    FOUR = 33,
-    FIVE = 34,
-    SIX = 35,
-    SEVEN = 36,
-    EIGHT = 37,
-    NINE = 38,
-    ZERO = 39,
-    ENTER = 40,
-    ESCAPE = 41,
-    BACKSPACE = 42,
-    TAB = 43,
-    SPACE = 44,
-    MINUS = 45,// - and _
-    EQUAL = 46,// = and +
-    BRACKET_LEFT = 47,// [ and {
-    BRACKET_RIGHT = 48,// ] and }
-    BACKSLASH = 49,// \ and |
-    SEMICOLON = 51,// ; and :
-    QUOTE = 52,// ' and "
-    GRAVE = 53,// ` and ~
-    COMMA = 54,// , and <
-    PERIOD = 55,// . and >
-    SLASH = 56,// / and ?
-    CAPS_LOCK = 57,
-    F1 = 58,
-    F2 = 59,
-    F3 = 60,
-    F4 = 61,
-    F5 = 62,
-    F6 = 63,
-    F7 = 64,
-    F8 = 65,
-    F9 = 66,
-    F10 = 67,
-    F11 = 68,
-    F12 = 69,
-    PRINT_SCREEN = 70,
-    SCROLL_LOCK = 71,
-    PAUSE = 72,
-    INSERT = 73,
-    HOME = 74,
-    PAGE_UP = 75,
-    DELETE = 76,
-    END = 77,
-    PAGE_DOWN = 78,
-    RIGHT = 79,
-    LEFT = 80,
-    DOWN = 81,
-    UP = 82,
-    NUM_LOCK = 83,
-    KP_DIVIDE = 84,// Keypad /
-    KP_MULTIPLY = 85,// Keypad *
-    KP_MINUS = 86,// Keypad -
-    KP_PLUS = 87,// Keypad +
-    KP_ENTER = 88,// Keypad Enter
-    KP_1 = 89,
-    KP_2 = 90,
-    KP_3 = 91,
-    KP_4 = 92,
-    KP_5 = 93,
-    KP_6 = 94,
-    KP_7 = 95,
-    KP_8 = 96,
-    KP_9 = 97,
-    KP_0 = 98,
-    KP_PERIOD = 99,// Keypad .
-    NON_US_BACKSLASH = 100,// \ and | on non-US keyboards
-    APPLICATION = 101,// Context menu key
-    F13 = 104,
-    F14 = 105,
-    F15 = 106,
-    F16 = 107,
-    F17 = 108,
-    F18 = 109,
-    F19 = 110,
-    F20 = 111,
-    F21 = 112,
-    F22 = 113,
-    F23 = 114,
-    F24 = 115
+    UNIDENTIFIED = 0,
+    GRAVE = 1,// ` and ~
+    BACKSLASH = 2,// \ and |
+    BRACKET_LEFT = 3,// [ and {
+    BRACKET_RIGHT = 4,// ] and }
+    COMMA = 5,// , and <
+    ZERO = 6,
+    ONE = 7,
+    TWO = 8,
+    THREE = 9,
+    FOUR = 10,
+    FIVE = 11,
+    SIX = 12,
+    SEVEN = 13,
+    EIGHT = 14,
+    NINE = 15,
+    EQUAL = 16,// = and +
+    INTL_BACKSLASH = 17,
+    INTL_RO = 18,
+    INTL_YEN = 19,
+    A = 20,
+    B = 21,
+    C = 22,
+    D = 23,
+    E = 24,
+    F = 25,
+    G = 26,
+    H = 27,
+    I = 28,
+    J = 29,
+    K = 30,
+    L = 31,
+    M = 32,
+    N = 33,
+    O = 34,
+    P = 35,
+    Q = 36,
+    R = 37,
+    S = 38,
+    T = 39,
+    U = 40,
+    V = 41,
+    W = 42,
+    X = 43,
+    Y = 44,
+    Z = 45,
+    MINUS = 46,// - and _
+    PERIOD = 47,// . and >
+    QUOTE = 48,// ' and "
+    SEMICOLON = 49,// ; and :
+    SLASH = 50,// / and ?
+    ALT_LEFT = 51,
+    ALT_RIGHT = 52,
+    BACKSPACE = 53,
+    CAPS_LOCK = 54,
+    CONTEXT_MENU = 55,
+    CONTROL_LEFT = 56,
+    CONTROL_RIGHT = 57,
+    ENTER = 58,
+    META_LEFT = 59,
+    META_RIGHT = 60,
+    SHIFT_LEFT = 61,
+    SHIFT_RIGHT = 62,
+    SPACE = 63,
+    TAB = 64,
+    CONVERT = 65,
+    KANA_MODE = 66,
+    NON_CONVERT = 67,
+    DELETE = 68,
+    END = 69,
+    HELP = 70,
+    HOME = 71,
+    INSERT = 72,
+    PAGE_DOWN = 73,
+    PAGE_UP = 74,
+    DOWN = 75,
+    LEFT = 76,
+    RIGHT = 77,
+    UP = 78,
+    NUM_LOCK = 79,
+    KP_0 = 80,
+    KP_1 = 81,
+    KP_2 = 82,
+    KP_3 = 83,
+    KP_4 = 84,
+    KP_5 = 85,
+    KP_6 = 86,
+    KP_7 = 87,
+    KP_8 = 88,
+    KP_9 = 89,
+    KP_PLUS = 90,// Keypad +
+    KP_BACKSPACE = 91,
+    KP_CLEAR = 92,
+    KP_CLEAR_ENTRY = 93,
+    KP_COMMA = 94,
+    KP_PERIOD = 95,// Keypad .
+    KP_DIVIDE = 96,// Keypad /
+    KP_ENTER = 97,// Keypad Enter
+    KP_EQUAL = 98,
+    KP_MEMORY_ADD = 99,
+    KP_MEMORY_CLEAR = 100,
+    KP_MEMORY_RECALL = 101,
+    KP_MEMORY_STORE = 102,
+    KP_MEMORY_SUBTRACT = 103,
+    KP_MULTIPLY = 104,// Keypad *
+    KP_PAREN_LEFT = 105,
+    KP_PAREN_RIGHT = 106,
+    KP_MINUS = 107,// Keypad -
+    KP_SEPARATOR = 108,
+    NUMPAD_UP = 109,
+    NUMPAD_DOWN = 110,
+    NUMPAD_RIGHT = 111,
+    NUMPAD_LEFT = 112,
+    NUMPAD_BEGIN = 113,
+    NUMPAD_HOME = 114,
+    NUMPAD_END = 115,
+    NUMPAD_INSERT = 116,
+    NUMPAD_DELETE = 117,
+    NUMPAD_PAGE_UP = 118,
+    NUMPAD_PAGE_DOWN = 119,
+    ESCAPE = 120,
+    F1 = 121,
+    F2 = 122,
+    F3 = 123,
+    F4 = 124,
+    F5 = 125,
+    F6 = 126,
+    F7 = 127,
+    F8 = 128,
+    F9 = 129,
+    F10 = 130,
+    F11 = 131,
+    F12 = 132,
+    F13 = 133,
+    F14 = 134,
+    F15 = 135,
+    F16 = 136,
+    F17 = 137,
+    F18 = 138,
+    F19 = 139,
+    F20 = 140,
+    F21 = 141,
+    F22 = 142,
+    F23 = 143,
+    F24 = 144,
+    F25 = 145,
+    FN_LOCK = 146,
+    PRINT_SCREEN = 147,
+    SCROLL_LOCK = 148,
+    PAUSE = 149,
+    BROWSER_BACK = 150,
+    BROWSER_FAVORITES = 151,
+    BROWSER_FORWARD = 152,
+    BROWSER_HOME = 153,
+    BROWSER_REFRESH = 154,
+    BROWSER_SEARCH = 155,
+    BROWSER_STOP = 156,
+    EJECT = 157,
+    LAUNCH_APP_1 = 158,
+    LAUNCH_APP_2 = 159,
+    LAUNCH_MAIL = 160,
+    MEDIA_PLAY_PAUSE = 161,
+    MEDIA_SELECT = 162,
+    MEDIA_STOP = 163,
+    MEDIA_TRACK_NEXT = 164,
+    MEDIA_TRACK_PREVIOUS = 165,
+    POWER = 166,
+    SLEEP = 167,
+    AUDIO_VOLUME_DOWN = 168,
+    AUDIO_VOLUME_MUTE = 169,
+    AUDIO_VOLUME_UP = 170,
+    WAKE_UP = 171,
+    COPY = 172,
+    CUT = 173,
+    PASTE = 174
 }
 
 /**
@@ -1063,28 +1123,15 @@ export declare enum KeyAction {
 }
 
 /**
- * Key Encoder
- * Converts keyboard events into terminal escape sequences
+ * Key Encoder - converts keyboard events into terminal escape sequences
  */
 export declare class KeyEncoder {
     private exports;
     private encoder;
     constructor(exports: GhosttyWasmExports);
-    /**
-     * Set an encoder option
-     */
     setOption(option: KeyEncoderOption, value: boolean | number): void;
-    /**
-     * Enable Kitty keyboard protocol with specified flags
-     */
     setKittyFlags(flags: KittyKeyFlags): void;
-    /**
-     * Encode a key event to escape sequence
-     */
     encode(event: KeyEvent): Uint8Array;
-    /**
-     * Free encoder resources
-     */
     dispose(): void;
 }
 
@@ -1220,6 +1267,29 @@ export declare interface RendererOptions {
     devicePixelRatio?: number;
 }
 
+/**
+ * Colors from RenderState (12 bytes packed)
+ */
+declare interface RenderStateColors {
+    background: RGB;
+    foreground: RGB;
+    cursor: RGB | null;
+}
+
+/**
+ * Cursor state from RenderState (8 bytes packed)
+ * Layout: x(u16) + y(u16) + viewport_x(i16) + viewport_y(i16) + visible(bool) + blinking(bool) + style(u8) + _pad(u8)
+ */
+declare interface RenderStateCursor {
+    x: number;
+    y: number;
+    viewportX: number;
+    viewportY: number;
+    visible: boolean;
+    blinking: boolean;
+    style: 'block' | 'underline' | 'bar';
+}
+
 /**
  * RGB color
  */
@@ -1430,7 +1500,7 @@ export declare class Terminal implements ITerminalCore {
     private addons;
     private customKeyEventHandler?;
     private currentTitle;
-    private viewportY;
+    viewportY: number;
     private targetViewportY;
     private scrollAnimationStartTime?;
     private scrollAnimationStartY?;
@@ -1446,6 +1516,16 @@ export declare class Terminal implements ITerminalCore {
     private readonly SCROLLBAR_HIDE_DELAY_MS;
     private readonly SCROLLBAR_FADE_DURATION_MS;
     constructor(options?: ITerminalOptions);
+    /**
+     * Handle runtime option changes (called when options are modified after terminal is open)
+     * This enables xterm.js compatibility where options can be changed at runtime
+     */
+    private handleOptionChange;
+    /**
+     * Handle font changes (fontSize or fontFamily)
+     * Updates canvas size to match new font metrics and forces a full re-render
+     */
+    private handleFontChange;
     /**
      * Parse a CSS color string to 0xRRGGBB format.
      * Returns 0 if the color is undefined or invalid.
@@ -1455,11 +1535,6 @@ export declare class Terminal implements ITerminalCore {
      * Convert terminal options to WASM terminal config.
      */
     private buildWasmConfig;
-    /**
-     * Handle runtime option changes (called when options are modified after terminal is open)
-     * This enables xterm.js compatibility where options can be changed at runtime
-     */
-    private handleOptionChange;
     /**
      * Open terminal in a parent element
      *
@@ -1682,6 +1757,18 @@ export declare class Terminal implements ITerminalCore {
      * Fade out scrollbar
      */
     private fadeOutScrollbar;
+    /**
+     * Process any pending terminal responses and emit them via onData.
+     *
+     * This handles escape sequences that require the terminal to send a response
+     * back to the PTY, such as:
+     * - DSR 6 (cursor position): Shell sends \x1b[6n, terminal responds with \x1b[row;colR
+     * - DSR 5 (operating status): Shell sends \x1b[5n, terminal responds with \x1b[0n
+     *
+     * Without this, shells like nushell that rely on cursor position queries
+     * will hang waiting for a response that never comes.
+     */
+    private processTerminalResponses;
     /**
      * Check for title changes in written data (OSC sequences)
      * Simplified implementation - looks for OSC 0, 1, 2