green-screen-proxy 0.3.0

package/dist/vt/encoder.d.ts

@@ -0,0 +1,30 @@
+import { VTScreenBuffer } from './screen.js';
+/**
+ * Encodes client input into VT terminal wire-format data.
+ *
+ * VT terminals are character-at-a-time (stream mode): each keystroke
+ * is sent immediately to the host. No block-mode buffering.
+ */
+export declare class VTEncoder {
+    private screen;
+    /** Whether BACKSPACE sends DEL (0x7F) or BS (0x08). Default: DEL */
+    backspaceIsDel: boolean;
+    /** Whether ENTER sends CR (0x0D) or CRLF. Default: CR only */
+    enterIsCR: boolean;
+    constructor(screen: VTScreenBuffer);
+    /**
+     * Encode a key name into the VT escape sequence to send over the wire.
+     * Returns null if the key is unknown.
+     */
+    encodeKey(keyName: string): Buffer | null;
+    /**
+     * Encode plain text for sending to the host.
+     * Each character is sent as its ASCII byte.
+     */
+    encodeText(text: string): Buffer;
+    /**
+     * Insert text at the current cursor position (local echo + wire output).
+     * Returns true if text was encoded successfully.
+     */
+    insertText(text: string): boolean;
+}

package/dist/vt/encoder.js

@@ -0,0 +1,55 @@
+import { VT_KEYS } from './constants.js';
+/**
+ * Encodes client input into VT terminal wire-format data.
+ *
+ * VT terminals are character-at-a-time (stream mode): each keystroke
+ * is sent immediately to the host. No block-mode buffering.
+ */
+export class VTEncoder {
+    screen;
+    /** Whether BACKSPACE sends DEL (0x7F) or BS (0x08). Default: DEL */
+    backspaceIsDel = true;
+    /** Whether ENTER sends CR (0x0D) or CRLF. Default: CR only */
+    enterIsCR = true;
+    constructor(screen) {
+        this.screen = screen;
+    }
+    /**
+     * Encode a key name into the VT escape sequence to send over the wire.
+     * Returns null if the key is unknown.
+     */
+    encodeKey(keyName) {
+        const upper = keyName.toUpperCase();
+        const seq = VT_KEYS[upper];
+        if (seq) {
+            return Buffer.from(seq, 'binary');
+        }
+        // Ctrl+letter (Ctrl+C = 0x03, Ctrl+A = 0x01, etc.)
+        if (upper.startsWith('CTRL+') && upper.length === 6) {
+            const letter = upper.charAt(5);
+            const code = letter.charCodeAt(0) - 0x40; // A=1, B=2, ...
+            if (code >= 1 && code <= 26) {
+                return Buffer.from([code]);
+            }
+        }
+        return null;
+    }
+    /**
+     * Encode plain text for sending to the host.
+     * Each character is sent as its ASCII byte.
+     */
+    encodeText(text) {
+        return Buffer.from(text, 'utf-8');
+    }
+    /**
+     * Insert text at the current cursor position (local echo + wire output).
+     * Returns true if text was encoded successfully.
+     */
+    insertText(text) {
+        if (!text)
+            return false;
+        // VT is stream mode — no local screen buffering needed.
+        // The host will echo characters back and the parser will render them.
+        return true;
+    }
+}

package/dist/vt/parser.d.ts

@@ -0,0 +1,36 @@
+import { VTScreenBuffer } from './screen.js';
+/**
+ * VT100/VT220/VT320 escape sequence parser.
+ *
+ * Processes a stream of bytes from the host, interpreting control characters
+ * and ANSI/VT escape sequences, and updating the screen buffer accordingly.
+ */
+export declare class VTParser {
+    private screen;
+    private state;
+    /** Accumulated CSI parameter string */
+    private params;
+    /** CSI intermediate bytes */
+    private intermediates;
+    /** Whether the CSI sequence has a '?' prefix (DEC private mode) */
+    private decPrivate;
+    /** OSC accumulator */
+    private oscData;
+    constructor(screen: VTScreenBuffer);
+    /**
+     * Feed a chunk of data from the host into the parser.
+     * Returns true if the screen was modified.
+     */
+    feed(data: Buffer): boolean;
+    private handleNormal;
+    private handleControlChar;
+    private handleEsc;
+    private handleCsi;
+    /** Parse CSI parameters as an array of numbers (default values handled per command) */
+    private parseParams;
+    private executeCsi;
+    /** Handle DEC private mode sequences (CSI ? ... h/l) */
+    private executeDecPrivate;
+    private executeSgr;
+    private handleOsc;
+}

package/dist/vt/parser.js

@@ -0,0 +1,534 @@
+import { defaultAttrs } from './screen.js';
+import { ESC, CSI_CHAR, BS, HT, LF, VT, FF, CR, SO, SI, BEL, SGR } from './constants.js';
+/**
+ * VT100/VT220/VT320 escape sequence parser.
+ *
+ * Processes a stream of bytes from the host, interpreting control characters
+ * and ANSI/VT escape sequences, and updating the screen buffer accordingly.
+ */
+export class VTParser {
+    screen;
+    state = 0 /* State.NORMAL */;
+    /** Accumulated CSI parameter string */
+    params = '';
+    /** CSI intermediate bytes */
+    intermediates = '';
+    /** Whether the CSI sequence has a '?' prefix (DEC private mode) */
+    decPrivate = false;
+    /** OSC accumulator */
+    oscData = '';
+    constructor(screen) {
+        this.screen = screen;
+    }
+    /**
+     * Feed a chunk of data from the host into the parser.
+     * Returns true if the screen was modified.
+     */
+    feed(data) {
+        let modified = false;
+        for (let i = 0; i < data.length; i++) {
+            const byte = data[i];
+            switch (this.state) {
+                case 0 /* State.NORMAL */:
+                    modified = this.handleNormal(byte) || modified;
+                    break;
+                case 1 /* State.ESC */:
+                    modified = this.handleEsc(byte) || modified;
+                    break;
+                case 2 /* State.CSI_PARAM */:
+                case 3 /* State.CSI_INTER */:
+                    modified = this.handleCsi(byte) || modified;
+                    break;
+                case 4 /* State.OSC */:
+                    this.handleOsc(byte);
+                    break;
+                case 5 /* State.DCS */:
+                    // Consume until ST (ESC \) — simplified: just wait for ESC or BEL
+                    if (byte === ESC || byte === BEL) {
+                        this.state = 0 /* State.NORMAL */;
+                    }
+                    break;
+                case 7 /* State.SS3 */:
+                    // SS3 sequences: ESC O <final> — used for F1-F4, keypad
+                    // From the host side these are rare; just consume and ignore
+                    this.state = 0 /* State.NORMAL */;
+                    break;
+                case 6 /* State.SS2 */:
+                    this.state = 0 /* State.NORMAL */;
+                    break;
+            }
+        }
+        return modified;
+    }
+    // ---------------------------------------------------------------------------
+    // State: NORMAL
+    // ---------------------------------------------------------------------------
+    handleNormal(byte) {
+        // Control characters
+        if (byte === ESC) {
+            this.state = 1 /* State.ESC */;
+            return false;
+        }
+        if (byte < 0x20 || byte === 0x7f) {
+            return this.handleControlChar(byte);
+        }
+        // Printable character — write to screen
+        this.screen.writeChar(String.fromCharCode(byte));
+        return true;
+    }
+    handleControlChar(byte) {
+        switch (byte) {
+            case BS: // Backspace
+                if (this.screen.cursorCol > 0) {
+                    this.screen.cursorCol--;
+                    this.screen.pendingWrap = false;
+                }
+                return false;
+            case HT: // Horizontal tab
+                this.screen.tabForward();
+                return false;
+            case LF: // Line feed
+            case VT: // Vertical tab (treated as LF)
+            case FF: // Form feed (treated as LF)
+                this.screen.lineFeed();
+                return true;
+            case CR: // Carriage return
+                this.screen.cursorCol = 0;
+                this.screen.pendingWrap = false;
+                return false;
+            case SO: // Shift Out — select G1 charset (simplified: ignore)
+                return false;
+            case SI: // Shift In — select G0 charset (simplified: ignore)
+                return false;
+            case BEL: // Bell
+                return false;
+            default:
+                return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // State: ESC (received ESC byte)
+    // ---------------------------------------------------------------------------
+    handleEsc(byte) {
+        switch (byte) {
+            case CSI_CHAR: // '[' — Control Sequence Introducer
+                this.state = 2 /* State.CSI_PARAM */;
+                this.params = '';
+                this.intermediates = '';
+                this.decPrivate = false;
+                return false;
+            case 0x5d: // ']' — OSC (Operating System Command)
+                this.state = 4 /* State.OSC */;
+                this.oscData = '';
+                return false;
+            case 0x50: // 'P' — DCS (Device Control String)
+                this.state = 5 /* State.DCS */;
+                return false;
+            case 0x4e: // 'N' — SS2 (Single Shift 2)
+                this.state = 6 /* State.SS2 */;
+                return false;
+            case 0x4f: // 'O' — SS3 (Single Shift 3)
+                this.state = 7 /* State.SS3 */;
+                return false;
+            case 0x37: // '7' — DECSC (Save Cursor)
+                this.screen.saveCursor();
+                this.state = 0 /* State.NORMAL */;
+                return false;
+            case 0x38: // '8' — DECRC (Restore Cursor)
+                this.screen.restoreCursor();
+                this.state = 0 /* State.NORMAL */;
+                return false;
+            case 0x44: // 'D' — IND (Index / line feed)
+                this.screen.lineFeed();
+                this.state = 0 /* State.NORMAL */;
+                return true;
+            case 0x4d: // 'M' — RI (Reverse Index / reverse line feed)
+                this.screen.reverseLineFeed();
+                this.state = 0 /* State.NORMAL */;
+                return true;
+            case 0x45: // 'E' — NEL (Next Line = CR + LF)
+                this.screen.cursorCol = 0;
+                this.screen.lineFeed();
+                this.state = 0 /* State.NORMAL */;
+                return true;
+            case 0x48: // 'H' — HTS (Horizontal Tab Set) — simplified: ignore
+                this.state = 0 /* State.NORMAL */;
+                return false;
+            case 0x63: // 'c' — RIS (Reset to Initial State)
+                this.screen.reset();
+                this.state = 0 /* State.NORMAL */;
+                return true;
+            case 0x5c: // '\' — ST (String Terminator) — end of DCS/OSC
+                this.state = 0 /* State.NORMAL */;
+                return false;
+            case 0x28: // '(' — Designate G0 character set — consume next byte
+            case 0x29: // ')' — Designate G1 character set — consume next byte
+            case 0x2a: // '*' — Designate G2 character set
+            case 0x2b: // '+' — Designate G3 character set
+                // Next byte is the charset designator (B, 0, etc.) — ignore it
+                // We stay in a pseudo-state; simplification: just consume one more byte
+                // by not changing state. Actually we need to consume the next byte.
+                // Use a trick: stay in ESC state for one more byte? No — just go NORMAL
+                // and accept that we may misinterpret one character. For correctness,
+                // we handle it by noting this is a 3-byte sequence.
+                this.state = 0 /* State.NORMAL */; // next byte will be consumed as normal char
+                // This is a slight inaccuracy but charset switching is rarely
+                // semantically important for screen scraping.
+                return false;
+            default:
+                // Unknown ESC sequence — return to NORMAL
+                this.state = 0 /* State.NORMAL */;
+                return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // State: CSI (parsing CSI parameters and executing)
+    // ---------------------------------------------------------------------------
+    handleCsi(byte) {
+        // Check for '?' prefix (DEC private mode)
+        if (byte === 0x3f && this.params === '' && !this.decPrivate) { // '?'
+            this.decPrivate = true;
+            return false;
+        }
+        // Parameter bytes: 0x30-0x3F (digits, semicolons, etc.)
+        if (byte >= 0x30 && byte <= 0x3f) {
+            this.params += String.fromCharCode(byte);
+            return false;
+        }
+        // Intermediate bytes: 0x20-0x2F
+        if (byte >= 0x20 && byte <= 0x2f) {
+            this.intermediates += String.fromCharCode(byte);
+            this.state = 3 /* State.CSI_INTER */;
+            return false;
+        }
+        // Final byte: 0x40-0x7E — execute the sequence
+        if (byte >= 0x40 && byte <= 0x7e) {
+            const result = this.executeCsi(byte);
+            this.state = 0 /* State.NORMAL */;
+            return result;
+        }
+        // Invalid byte — abort
+        this.state = 0 /* State.NORMAL */;
+        return false;
+    }
+    /** Parse CSI parameters as an array of numbers (default values handled per command) */
+    parseParams() {
+        if (this.params === '')
+            return [];
+        return this.params.split(';').map((s) => {
+            const n = parseInt(s, 10);
+            return isNaN(n) ? 0 : n;
+        });
+    }
+    executeCsi(finalByte) {
+        const params = this.parseParams();
+        const p1 = params[0] || 0;
+        const finalChar = String.fromCharCode(finalByte);
+        // Handle intermediate bytes (e.g., space for some sequences)
+        if (this.intermediates.length > 0) {
+            // CSI ? ... h/l with intermediates, or CSI ... SP q (cursor style), etc.
+            // Mostly safe to ignore for screen-scraping purposes.
+            return false;
+        }
+        if (this.decPrivate) {
+            return this.executeDecPrivate(finalChar, params);
+        }
+        switch (finalChar) {
+            // ------- Cursor movement -------
+            case 'A': // CUU — Cursor Up
+                this.screen.setCursor(this.screen.cursorRow - Math.max(p1, 1), this.screen.cursorCol);
+                return false;
+            case 'B': // CUD — Cursor Down
+                this.screen.setCursor(this.screen.cursorRow + Math.max(p1, 1), this.screen.cursorCol);
+                return false;
+            case 'C': // CUF — Cursor Forward
+                this.screen.setCursor(this.screen.cursorRow, this.screen.cursorCol + Math.max(p1, 1));
+                return false;
+            case 'D': // CUB — Cursor Backward
+                this.screen.setCursor(this.screen.cursorRow, this.screen.cursorCol - Math.max(p1, 1));
+                return false;
+            case 'E': // CNL — Cursor Next Line
+                this.screen.setCursor(this.screen.cursorRow + Math.max(p1, 1), 0);
+                return false;
+            case 'F': // CPL — Cursor Previous Line
+                this.screen.setCursor(this.screen.cursorRow - Math.max(p1, 1), 0);
+                return false;
+            case 'G': // CHA — Cursor Horizontal Absolute
+                this.screen.setCursor(this.screen.cursorRow, Math.max(p1, 1) - 1);
+                return false;
+            case 'H': // CUP — Cursor Position
+            case 'f': // HVP — Horizontal and Vertical Position (same as CUP)
+                {
+                    const row = (params[0] || 1) - 1;
+                    const col = (params[1] || 1) - 1;
+                    this.screen.setCursor(row, col);
+                    return false;
+                }
+            case 'd': // VPA — Vertical Position Absolute
+                this.screen.setCursor(Math.max(p1, 1) - 1, this.screen.cursorCol);
+                return false;
+            // ------- Erase -------
+            case 'J': // ED — Erase in Display
+                this.screen.eraseInDisplay(p1);
+                return true;
+            case 'K': // EL — Erase in Line
+                this.screen.eraseInLine(p1);
+                return true;
+            case 'X': // ECH — Erase Characters
+                this.screen.eraseCharacters(Math.max(p1, 1));
+                return true;
+            // ------- Insert / Delete -------
+            case 'L': // IL — Insert Lines
+                this.screen.insertLines(Math.max(p1, 1));
+                return true;
+            case 'M': // DL — Delete Lines
+                this.screen.deleteLines(Math.max(p1, 1));
+                return true;
+            case '@': // ICH — Insert Characters
+                this.screen.insertCharacters(Math.max(p1, 1));
+                return true;
+            case 'P': // DCH — Delete Characters
+                this.screen.deleteCharacters(Math.max(p1, 1));
+                return true;
+            // ------- Scrolling -------
+            case 'S': // SU — Scroll Up
+                this.screen.scrollUp(Math.max(p1, 1));
+                return true;
+            case 'T': // SD — Scroll Down
+                this.screen.scrollDown(Math.max(p1, 1));
+                return true;
+            // ------- Attributes -------
+            case 'm': // SGR — Select Graphic Rendition
+                this.executeSgr(params);
+                return false;
+            // ------- Scroll region -------
+            case 'r': // DECSTBM — Set Top and Bottom Margins
+                {
+                    const top = (params[0] || 1) - 1;
+                    const bottom = (params[1] || this.screen.rows) - 1;
+                    this.screen.scrollTop = Math.max(0, Math.min(top, this.screen.rows - 1));
+                    this.screen.scrollBottom = Math.max(0, Math.min(bottom, this.screen.rows - 1));
+                    // CUP to home after DECSTBM
+                    this.screen.setCursor(0, 0);
+                    return false;
+                }
+            // ------- Mode set/reset -------
+            case 'h': // SM — Set Mode
+                // Standard modes (non-DEC private) — most are irrelevant for screen scraping
+                return false;
+            case 'l': // RM — Reset Mode
+                return false;
+            // ------- Device status -------
+            case 'n': // DSR — Device Status Report
+                // 6 = CPR (Cursor Position Report) — we'd need to send response
+                // For now, ignore
+                return false;
+            case 'c': // DA — Device Attributes
+                // Ignore — we'd need to send a response
+                return false;
+            // ------- Tab -------
+            case 'I': // CHT — Cursor Horizontal Tab (forward n tabs)
+                {
+                    const count = Math.max(p1, 1);
+                    for (let t = 0; t < count; t++)
+                        this.screen.tabForward();
+                    return false;
+                }
+            case 'g': // TBC — Tab Clear — ignore
+                return false;
+            default:
+                // Unknown CSI sequence — ignore
+                return false;
+        }
+    }
+    /** Handle DEC private mode sequences (CSI ? ... h/l) */
+    executeDecPrivate(finalChar, params) {
+        const mode = params[0] || 0;
+        switch (finalChar) {
+            case 'h': // DECSET — Set DEC private mode
+                switch (mode) {
+                    case 1: // DECCKM — Application cursor keys (affects what arrow keys send)
+                        // Tracked but no screen effect
+                        return false;
+                    case 6: // DECOM — Origin mode
+                        this.screen.originMode = true;
+                        this.screen.setCursor(0, 0);
+                        return false;
+                    case 7: // DECAWM — Auto wrap mode
+                        this.screen.autoWrap = true;
+                        return false;
+                    case 25: // DECTCEM — Show cursor (no visual effect in our buffer)
+                        return false;
+                    case 1049: // Save cursor + switch to alternate screen buffer
+                        this.screen.saveCursor();
+                        this.screen.eraseInDisplay(2);
+                        return true;
+                    case 47:
+                    case 1047: // Alternate screen buffer
+                        this.screen.eraseInDisplay(2);
+                        return true;
+                }
+                return false;
+            case 'l': // DECRST — Reset DEC private mode
+                switch (mode) {
+                    case 1: // DECCKM — Normal cursor keys
+                        return false;
+                    case 6: // DECOM — Origin mode off
+                        this.screen.originMode = false;
+                        this.screen.setCursor(0, 0);
+                        return false;
+                    case 7: // DECAWM — Auto wrap off
+                        this.screen.autoWrap = false;
+                        return false;
+                    case 25: // DECTCEM — Hide cursor
+                        return false;
+                    case 1049: // Restore cursor + switch from alternate screen
+                        this.screen.restoreCursor();
+                        return true;
+                    case 47:
+                    case 1047:
+                        return true;
+                }
+                return false;
+            default:
+                return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // SGR — Select Graphic Rendition
+    // ---------------------------------------------------------------------------
+    executeSgr(params) {
+        // If no params, treat as reset
+        if (params.length === 0)
+            params = [0];
+        const attrs = this.screen.currentAttrs;
+        for (let i = 0; i < params.length; i++) {
+            const p = params[i];
+            switch (p) {
+                case SGR.RESET:
+                    Object.assign(attrs, defaultAttrs());
+                    break;
+                case SGR.BOLD:
+                    attrs.bold = true;
+                    break;
+                case SGR.DIM:
+                    attrs.dim = true;
+                    break;
+                case SGR.ITALIC:
+                    attrs.italic = true;
+                    break;
+                case SGR.UNDERLINE:
+                    attrs.underline = true;
+                    break;
+                case SGR.BLINK:
+                case SGR.RAPID_BLINK:
+                    attrs.blink = true;
+                    break;
+                case SGR.REVERSE:
+                    attrs.reverse = true;
+                    break;
+                case SGR.HIDDEN:
+                    attrs.hidden = true;
+                    break;
+                case SGR.STRIKETHROUGH:
+                    attrs.strikethrough = true;
+                    break;
+                case SGR.NORMAL_INTENSITY:
+                    attrs.bold = false;
+                    attrs.dim = false;
+                    break;
+                case SGR.NO_ITALIC:
+                    attrs.italic = false;
+                    break;
+                case SGR.NO_UNDERLINE:
+                    attrs.underline = false;
+                    break;
+                case SGR.NO_BLINK:
+                    attrs.blink = false;
+                    break;
+                case SGR.NO_REVERSE:
+                    attrs.reverse = false;
+                    break;
+                case SGR.NO_HIDDEN:
+                    attrs.hidden = false;
+                    break;
+                case SGR.NO_STRIKETHROUGH:
+                    attrs.strikethrough = false;
+                    break;
+                default:
+                    // Foreground colors
+                    if (p >= 30 && p <= 37) {
+                        attrs.fg = p - 30;
+                    }
+                    else if (p === 39) {
+                        attrs.fg = 8; // default
+                    }
+                    // Background colors
+                    else if (p >= 40 && p <= 47) {
+                        attrs.bg = p - 40;
+                    }
+                    else if (p === 49) {
+                        attrs.bg = 8; // default
+                    }
+                    // Bright foreground
+                    else if (p >= 90 && p <= 97) {
+                        attrs.fg = p - 90; // Map to 0-7 (bright handled by bold in classic VT)
+                        attrs.bold = true;
+                    }
+                    // Bright background
+                    else if (p >= 100 && p <= 107) {
+                        attrs.bg = p - 100;
+                    }
+                    // 256-color / truecolor: CSI 38;5;n m or CSI 38;2;r;g;b m
+                    else if (p === 38) {
+                        if (i + 1 < params.length && params[i + 1] === 5) {
+                            // 256-color foreground — map to basic 8 if possible
+                            if (i + 2 < params.length) {
+                                const color = params[i + 2];
+                                attrs.fg = color < 8 ? color : 8;
+                                i += 2;
+                            }
+                        }
+                        else if (i + 1 < params.length && params[i + 1] === 2) {
+                            // Truecolor — skip r,g,b
+                            i += 4;
+                            attrs.fg = 8;
+                        }
+                    }
+                    else if (p === 48) {
+                        if (i + 1 < params.length && params[i + 1] === 5) {
+                            if (i + 2 < params.length) {
+                                const color = params[i + 2];
+                                attrs.bg = color < 8 ? color : 8;
+                                i += 2;
+                            }
+                        }
+                        else if (i + 1 < params.length && params[i + 1] === 2) {
+                            i += 4;
+                            attrs.bg = 8;
+                        }
+                    }
+                    break;
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // State: OSC
+    // ---------------------------------------------------------------------------
+    handleOsc(byte) {
+        // OSC terminated by BEL (0x07) or ST (ESC \)
+        if (byte === BEL) {
+            // OSC complete — we ignore OSC data (window titles, etc.)
+            this.state = 0 /* State.NORMAL */;
+            return;
+        }
+        if (byte === ESC) {
+            // Could be start of ST (ESC \) — next byte should be '\'
+            // Simplified: just go to NORMAL; the '\' will be consumed harmlessly
+            this.state = 0 /* State.NORMAL */;
+            return;
+        }
+        // Accumulate (ignored but consumed)
+        this.oscData += String.fromCharCode(byte);
+    }
+}