Something went wrong. Try again.
Ghostty for the web with xterm.js API compatibility
Something went wrong. Try again.
18 kB · 697 lines
TypeScript
at renderstate
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698/** * TypeScript type definitions for libghostty-vt WASM API * Based on include/ghostty/vt/*.h from Ghostty repository */
// ============================================================================// SGR (Select Graphic Rendition) Types// ============================================================================
/** * SGR attribute tags - identifies the type of attribute * From include/ghostty/vt/sgr.h */export enum SgrAttributeTag { UNSET = 0, UNKNOWN = 1, BOLD = 2, RESET_BOLD = 3, ITALIC = 4, RESET_ITALIC = 5, FAINT = 6, RESET_FAINT = 7, UNDERLINE = 8, RESET_UNDERLINE = 9, BLINK = 10, RESET_BLINK = 11, INVERSE = 12, RESET_INVERSE = 13, INVISIBLE = 14, RESET_INVISIBLE = 15, STRIKETHROUGH = 16, RESET_STRIKETHROUGH = 17, FG_8 = 18, // 8-color (0-7) FG_16 = 19, // 16-color (0-15) FG_256 = 20, // 256-color palette FG_RGB = 21, // RGB color FG_DEFAULT = 22, // Reset to default BG_8 = 23, // Background 8-color BG_16 = 24, // Background 16-color BG_256 = 25, // Background 256-color BG_RGB = 26, // Background RGB BG_DEFAULT = 27, // Reset background UNDERLINE_COLOR_8 = 28, UNDERLINE_COLOR_16 = 29, UNDERLINE_COLOR_256 = 30, UNDERLINE_COLOR_RGB = 31, UNDERLINE_COLOR_DEFAULT = 32,}
export interface RGBColor { r: number; g: number; b: number;}
export type SgrAttribute = | { tag: SgrAttributeTag.BOLD } | { tag: SgrAttributeTag.RESET_BOLD } | { tag: SgrAttributeTag.ITALIC } | { tag: SgrAttributeTag.RESET_ITALIC } | { tag: SgrAttributeTag.FAINT } | { tag: SgrAttributeTag.RESET_FAINT } | { tag: SgrAttributeTag.UNDERLINE } | { tag: SgrAttributeTag.RESET_UNDERLINE } | { tag: SgrAttributeTag.BLINK } | { tag: SgrAttributeTag.RESET_BLINK } | { tag: SgrAttributeTag.INVERSE } | { tag: SgrAttributeTag.RESET_INVERSE } | { tag: SgrAttributeTag.INVISIBLE } | { tag: SgrAttributeTag.RESET_INVISIBLE } | { tag: SgrAttributeTag.STRIKETHROUGH } | { tag: SgrAttributeTag.RESET_STRIKETHROUGH } | { tag: SgrAttributeTag.FG_8; color: number } | { tag: SgrAttributeTag.FG_16; color: number } | { tag: SgrAttributeTag.FG_256; color: number } | { tag: SgrAttributeTag.FG_RGB; color: RGBColor } | { tag: SgrAttributeTag.FG_DEFAULT } | { tag: SgrAttributeTag.BG_8; color: number } | { tag: SgrAttributeTag.BG_16; color: number } | { tag: SgrAttributeTag.BG_256; color: number } | { tag: SgrAttributeTag.BG_RGB; color: RGBColor } | { tag: SgrAttributeTag.BG_DEFAULT } | { tag: SgrAttributeTag.UNDERLINE_COLOR_RGB; color: RGBColor } | { tag: SgrAttributeTag.UNDERLINE_COLOR_DEFAULT } | { tag: SgrAttributeTag.UNKNOWN; params: number[] };
// ============================================================================// Key Encoder Types// ============================================================================
/** * Kitty keyboard protocol flags * From include/ghostty/vt/key/encoder.h */export enum KittyKeyFlags { DISABLED = 0, DISAMBIGUATE = 1 << 0, // Disambiguate escape codes REPORT_EVENTS = 1 << 1, // Report press and release REPORT_ALTERNATES = 1 << 2, // Report alternate key codes REPORT_ALL = 1 << 3, // Report all events REPORT_ASSOCIATED = 1 << 4, // Report associated text ALL = 0x1f, // All flags enabled}
/** * Key encoder options */export enum KeyEncoderOption { CURSOR_KEY_APPLICATION = 0, // DEC mode 1 KEYPAD_KEY_APPLICATION = 1, // DEC mode 66 IGNORE_KEYPAD_WITH_NUMLOCK = 2, // DEC mode 1035 ALT_ESC_PREFIX = 3, // DEC mode 1036 MODIFY_OTHER_KEYS_STATE_2 = 4, // xterm modifyOtherKeys KITTY_KEYBOARD_FLAGS = 5, // Kitty protocol flags}
/** * Key action */export enum KeyAction { RELEASE = 0, PRESS = 1, REPEAT = 2,}
/** * Physical key codes (based on USB HID Usage Tables - Keyboard/Keypad Page 0x07) * Reference: https://www.usb.org/sites/default/files/hut1_21.pdf */export enum Key { // Letters (0x04-0x1D) 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,
// Numbers (0x1E-0x27) ONE = 30, TWO = 31, THREE = 32, FOUR = 33, FIVE = 34, SIX = 35, SEVEN = 36, EIGHT = 37, NINE = 38, ZERO = 39,
// Special keys (0x28-0x2C) ENTER = 40, ESCAPE = 41, BACKSPACE = 42, TAB = 43, SPACE = 44,
// Punctuation (0x2D-0x38) 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 ?
// Function keys (0x3A-0x45) 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,
// Special keys (0x46-0x4E) PRINT_SCREEN = 70, SCROLL_LOCK = 71, PAUSE = 72, INSERT = 73, HOME = 74, PAGE_UP = 75, DELETE = 76, END = 77, PAGE_DOWN = 78,
// Arrow keys (0x4F-0x52) RIGHT = 79, LEFT = 80, DOWN = 81, UP = 82,
// Keypad (0x53-0x63) 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 .
// International keys (0x64-0x65) NON_US_BACKSLASH = 100, // \ and | on non-US keyboards APPLICATION = 101, // Context menu key
// Additional function keys (0x68-0x73) - optional but included for completeness F13 = 104, F14 = 105, F15 = 106, F16 = 107, F17 = 108, F18 = 109, F19 = 110, F20 = 111, F21 = 112, F22 = 113, F23 = 114, F24 = 115,}
/** * Modifier keys */export enum Mods { NONE = 0, SHIFT = 1 << 0, CTRL = 1 << 1, ALT = 1 << 2, SUPER = 1 << 3, // Windows/Command key CAPSLOCK = 1 << 4, NUMLOCK = 1 << 5,}
/** * Key event structure */export interface KeyEvent { action: KeyAction; key: Key; mods: Mods; consumedMods?: Mods; composing?: boolean; utf8?: string; unshiftedCodepoint?: number;}
// ============================================================================// WASM Exports Interface// ============================================================================
/** * Interface for libghostty-vt WASM exports */export interface GhosttyWasmExports extends WebAssembly.Exports { memory: WebAssembly.Memory;
// Memory helpers ghostty_wasm_alloc_opaque(): number; ghostty_wasm_free_opaque(ptr: number): void; ghostty_wasm_alloc_u8_array(len: number): number; ghostty_wasm_free_u8_array(ptr: number, len: number): void; ghostty_wasm_alloc_u16_array(len: number): number; ghostty_wasm_free_u16_array(ptr: number, len: number): void; ghostty_wasm_alloc_u8(): number; ghostty_wasm_free_u8(ptr: number): void; ghostty_wasm_alloc_usize(): number; ghostty_wasm_free_usize(ptr: number): void;
// SGR parser ghostty_sgr_new(allocator: number, parserPtrPtr: number): number; ghostty_sgr_free(parser: number): void; ghostty_sgr_reset(parser: number): void; ghostty_sgr_set_params( parser: number, paramsPtr: number, subsPtr: number, paramsLen: number ): number; ghostty_sgr_next(parser: number, attrPtr: number): boolean; ghostty_sgr_attribute_tag(attrPtr: number): number; ghostty_sgr_attribute_value(attrPtr: number, tagPtr: number): number; ghostty_wasm_alloc_sgr_attribute(): number; ghostty_wasm_free_sgr_attribute(ptr: number): void;
// Key encoder ghostty_key_encoder_new(allocator: number, encoderPtrPtr: number): number; ghostty_key_encoder_free(encoder: number): void; ghostty_key_encoder_setopt(encoder: number, option: number, valuePtr: number): number; ghostty_key_encoder_encode( encoder: number, eventPtr: number, bufPtr: number, bufLen: number, writtenPtr: number ): number;
// Key event ghostty_key_event_new(allocator: number, eventPtrPtr: number): number; ghostty_key_event_free(event: number): void; ghostty_key_event_set_action(event: number, action: number): void; ghostty_key_event_set_key(event: number, key: number): void; ghostty_key_event_set_mods(event: number, mods: number): void; ghostty_key_event_set_utf8(event: number, ptr: number, len: number): void;
// Terminal lifecycle 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_resize(terminal: TerminalHandle, cols: number, rows: number): void; ghostty_terminal_write(terminal: TerminalHandle, dataPtr: number, dataLen: number): void;
// RenderState API - high-performance rendering (ONE call gets ALL data) ghostty_render_state_update(terminal: TerminalHandle): number; // 0=none, 1=partial, 2=full 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; // 0xRRGGBB ghostty_render_state_get_fg_color(terminal: TerminalHandle): number; // 0xRRGGBB 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; // Returns total cells written or -1 on error
// Terminal modes ghostty_terminal_is_alternate_screen(terminal: TerminalHandle): boolean; ghostty_terminal_has_mouse_tracking(terminal: TerminalHandle): number; ghostty_terminal_get_mode(terminal: TerminalHandle, mode: number, isAnsi: boolean): number;
// Scrollback API ghostty_terminal_get_scrollback_length(terminal: TerminalHandle): number; ghostty_terminal_get_scrollback_line( terminal: TerminalHandle, offset: number, bufPtr: number, bufLen: number ): number; // Returns cells written or -1 on error ghostty_terminal_is_row_wrapped(terminal: TerminalHandle, row: number): number;}
// ============================================================================// Terminal Types// ============================================================================
/** * Dirty state from RenderState */export enum DirtyState { NONE = 0, PARTIAL = 1, FULL = 2,}
/** * 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) */export interface RenderStateCursor { x: number; y: number; viewportX: number; // -1 if not in viewport viewportY: number; visible: boolean; blinking: boolean; style: 'block' | 'underline' | 'bar';}
/** * Colors from RenderState (12 bytes packed) */export interface RenderStateColors { background: RGB; foreground: RGB; cursor: RGB | null;}
/** * Size of cursor struct in WASM (8 bytes) */export const CURSOR_STRUCT_SIZE = 8;
/** * Size of colors struct in WASM (12 bytes) */export const COLORS_STRUCT_SIZE = 12;
/** * Terminal configuration (passed to ghostty_terminal_new_with_config) * All color values use 0xRRGGBB format. A value of 0 means "use default". */export interface GhosttyTerminalConfig { scrollbackLimit?: number; fgColor?: number; bgColor?: number; cursorColor?: number; palette?: number[];}
/** * Size of GhosttyTerminalConfig struct in WASM memory (bytes). * Layout: scrollback_limit(u32) + fg_color(u32) + bg_color(u32) + cursor_color(u32) + palette[16](u32*16) * Total: 4 + 4 + 4 + 4 + 64 = 80 bytes */export const GHOSTTY_CONFIG_SIZE = 80;
/** * Opaque terminal pointer (WASM memory address) */export type TerminalHandle = number;
/** * Cell structure matching ghostty_cell_t in C (16 bytes) */export interface GhosttyCell { codepoint: number; // u32 (Unicode codepoint) fg_r: number; // u8 (foreground red) fg_g: number; // u8 (foreground green) fg_b: number; // u8 (foreground blue) bg_r: number; // u8 (background red) bg_g: number; // u8 (background green) bg_b: number; // u8 (background blue) flags: number; // u8 (style flags bitfield) width: number; // u8 (character width: 1=normal, 2=wide, etc.) hyperlink_id: number; // u16 (0 = no link, >0 = hyperlink ID in set)}
/** * RGB color */export interface RGB { r: number; g: number; b: number;}
/** * Cell style flags (bitfield) */export enum CellFlags { BOLD = 1 << 0, ITALIC = 1 << 1, UNDERLINE = 1 << 2, STRIKETHROUGH = 1 << 3, INVERSE = 1 << 4, INVISIBLE = 1 << 5, BLINK = 1 << 6, FAINT = 1 << 7,}
/** * Cursor position and visibility */export interface Cursor { x: number; y: number; visible: boolean;}
/** * Terminal configuration (passed to ghostty_terminal_new_with_config) */export interface TerminalConfig { scrollback_limit: number; // Number of scrollback lines (default: 10,000) fg_color: RGB; // Default foreground color bg_color: RGB; // Default background color}
// ============================================================================// Link Detection System// ============================================================================
/** * Represents a coordinate in the terminal buffer */export interface IBufferCellPosition { x: number; // Column (0-based) y: number; // Row (0-based, absolute buffer position)}
/** * Represents a range in the terminal buffer * Can span multiple lines for wrapped links */export interface IBufferRange { start: IBufferCellPosition; end: IBufferCellPosition; // Inclusive}
/** * Represents a detected link in the terminal */export interface ILink { /** The URL or text of the link */ text: string;
/** The range of the link in the buffer (may span multiple lines) */ range: IBufferRange;
/** Called when the link is activated (clicked with modifier) */ activate(event: MouseEvent): void;
/** Optional: called when mouse enters/leaves the link */ hover?(isHovered: boolean): void;
/** Optional: called to clean up resources */ dispose?(): void;}
/** * Provides link detection for a specific type of link * Examples: OSC 8 hyperlinks, URL regex detection */export interface ILinkProvider { /** * Provide links for a given row * @param y Absolute row in buffer (0-based) * @param callback Called with detected links (or undefined if none) */ provideLinks(y: number, callback: (links: ILink[] | undefined) => void): void;
/** Optional: called when terminal is disposed */ dispose?(): void;}
/** * Simplified buffer line interface for link providers */export interface IBufferLine { /** Number of cells in this line */ length: number;
/** Get cell at position */ getCell(x: number): IBufferCell;
/** Get text content of the line */ translateToString(trimRight?: boolean, startColumn?: number, endColumn?: number): string;}
/** * Simplified buffer cell interface for link providers */export interface IBufferCell { /** Get the character codepoint */ getCodepoint(): number;
/** Get the hyperlink ID (0 = no link) */ getHyperlinkId(): number;
/** Get the width of the character (1 or 2 for wide chars) */ getWidth(): number;
/** Check if cell has specific flags */ isBold(): boolean; isItalic(): boolean; isDim(): boolean;}
/** * Simplified terminal buffer interface for link providers */export interface IBuffer { /** Number of rows in the buffer (viewport + scrollback) */ length: number;
/** Get line at absolute buffer position */ getLine(y: number): IBufferLine;}
/** * Terminal buffer manager (active vs alternate screen) */export interface IBufferManager { /** Currently active buffer */ active: IBuffer;
/** Normal screen buffer */ normal: IBuffer;
/** Alternate screen buffer (for fullscreen apps) */ alternate: IBuffer;}
/** * Event system interface (xterm.js compatible) */export type IEvent<T> = (listener: (data: T) => void) => IDisposable;
export interface IDisposable { dispose(): void;}
/** * Event emitter for custom events */export class EventEmitter<T> { private listeners: Array<(data: T) => void> = [];
/** Subscribe to events */ public readonly event: IEvent<T> = (listener: (data: T) => void): IDisposable => { this.listeners.push(listener); return { dispose: () => { const index = this.listeners.indexOf(listener); if (index !== -1) { this.listeners.splice(index, 1); } }, }; };
/** Emit an event to all listeners */ public fire(data: T): void { for (const listener of this.listeners) { listener(data); } }
/** Remove all listeners */ public dispose(): void { this.listeners = []; }}
/** * Terminal mode identifiers * * ANSI modes (use with is_ansi = true): * - INSERT = 4 * * DEC modes (use with is_ansi = false): * - CURSOR_VISIBLE = 25 * - MOUSE_TRACKING_NORMAL = 1000 * - MOUSE_TRACKING_BUTTON = 1002 * - MOUSE_TRACKING_ANY = 1003 * - FOCUS_EVENTS = 1004 * - ALT_SCREEN = 1047 * - ALT_SCREEN_WITH_CURSOR = 1049 * - BRACKETED_PASTE = 2004 */export enum TerminalMode { // ANSI modes INSERT = 4,
// DEC modes CURSOR_VISIBLE = 25, MOUSE_TRACKING_NORMAL = 1000, MOUSE_TRACKING_BUTTON = 1002, MOUSE_TRACKING_ANY = 1003, FOCUS_EVENTS = 1004, ALT_SCREEN = 1047, ALT_SCREEN_WITH_CURSOR = 1049, BRACKETED_PASTE = 2004,}