@teammates/consolonia 0.2.0

package/dist/drawing/context.js

@@ -0,0 +1,275 @@
+/**
+ * DrawingContext: the main drawing API for rendering to a PixelBuffer.
+ *
+ * Port of Consolonia's DrawingContextImpl.cs + DrawingContextImpl.Boxes.cs,
+ * simplified for the Node.js/TypeScript environment.
+ */
+import { background } from "../pixel/background.js";
+import { boxChar, DOWN, LEFT, mergeBoxPatterns, RIGHT, UP, } from "../pixel/box-pattern.js";
+import { foreground } from "../pixel/foreground.js";
+import { blendPixel } from "../pixel/pixel.js";
+import { charWidth, isZeroWidth, sym } from "../pixel/symbol.js";
+import { ClipStack } from "./clip.js";
+// ── Defaults ──────────────────────────────────────────────────────
+const DEFAULT_FG = { r: 255, g: 255, b: 255, a: 255 };
+const TRANSPARENT = { r: 0, g: 0, b: 0, a: 0 };
+const TAB_WIDTH = 4;
+// ── DrawingContext ────────────────────────────────────────────────
+export class DrawingContext {
+    buffer;
+    clipStack;
+    translateStack = [];
+    offsetX = 0;
+    offsetY = 0;
+    constructor(buffer) {
+        this.buffer = buffer;
+        this.clipStack = new ClipStack();
+    }
+    // ── Clip management ──────────────────────────────────────────
+    /** Push a clip rectangle. All drawing is clipped to this region. */
+    pushClip(rect) {
+        this.clipStack.push(rect);
+    }
+    /** Pop the last clip rectangle. */
+    popClip() {
+        this.clipStack.pop();
+    }
+    // ── Translate management ───────────────────────────────────
+    /** Push a coordinate translation. All drawing coordinates are offset. */
+    pushTranslate(dx, dy) {
+        this.translateStack.push({ dx: this.offsetX, dy: this.offsetY });
+        this.offsetX += dx;
+        this.offsetY += dy;
+    }
+    /** Pop the last coordinate translation. */
+    popTranslate() {
+        const prev = this.translateStack.pop();
+        if (prev) {
+            this.offsetX = prev.dx;
+            this.offsetY = prev.dy;
+        }
+        else {
+            this.offsetX = 0;
+            this.offsetY = 0;
+        }
+    }
+    // ── Visibility check ────────────────────────────────────────
+    /** Translate a point by the current offset. */
+    tx(x) {
+        return x + this.offsetX;
+    }
+    ty(y) {
+        return y + this.offsetY;
+    }
+    /** Check if a local-coord point is visible after translate. */
+    isVisible(x, y) {
+        const wx = this.tx(x);
+        const wy = this.ty(y);
+        if (wx < 0 ||
+            wx >= this.buffer.width ||
+            wy < 0 ||
+            wy >= this.buffer.height) {
+            return false;
+        }
+        return this.clipStack.contains(wx, wy);
+    }
+    /** Get a pixel at local coordinates (translated to buffer coords). */
+    bufGet(x, y) {
+        return this.buffer.get(this.tx(x), this.ty(y));
+    }
+    /** Set a pixel at local coordinates (translated to buffer coords). */
+    bufSet(x, y, px) {
+        this.buffer.set(this.tx(x), this.ty(y), px);
+    }
+    // ── Fill ─────────────────────────────────────────────────────
+    /** Fill a rectangle with a solid color. */
+    fillRect(rect, color) {
+        const bg = background(color);
+        const fg = foreground(sym(" "), TRANSPARENT);
+        const px = { foreground: fg, background: bg };
+        for (let y = rect.y; y < rect.y + rect.height; y++) {
+            for (let x = rect.x; x < rect.x + rect.width; x++) {
+                if (this.isVisible(x, y)) {
+                    this.bufSet(x, y, blendPixel(px, this.bufGet(x, y)));
+                }
+            }
+        }
+    }
+    // ── Single character ─────────────────────────────────────────
+    /** Draw a single character at (x, y) with styling. */
+    drawChar(x, y, char, style) {
+        if (!this.isVisible(x, y))
+            return;
+        const fgColor = style?.fg ?? DEFAULT_FG;
+        const bgColor = style?.bg ?? TRANSPARENT;
+        const s = sym(char);
+        const fg = foreground(s, fgColor, {
+            bold: style?.bold ?? false,
+            italic: style?.italic ?? false,
+            underline: style?.underline ?? false,
+            strikethrough: style?.strikethrough ?? false,
+        });
+        const bg = background(bgColor);
+        const px = { foreground: fg, background: bg };
+        this.bufSet(x, y, blendPixel(px, this.bufGet(x, y)));
+        // Wide characters need a continuation marker in the next cell
+        if (s.width === 2 && this.isVisible(x + 1, y)) {
+            const contFg = foreground(sym(""), TRANSPARENT);
+            const contPx = { foreground: contFg, background: bg };
+            this.bufSet(x + 1, y, blendPixel(contPx, this.bufGet(x + 1, y)));
+        }
+    }
+    // ── Text string ──────────────────────────────────────────────
+    /** Draw a text string at (x, y). Handles wide characters and tabs. */
+    drawText(x, y, text, style) {
+        let cx = x;
+        for (const char of text) {
+            // Handle tab characters as spaces
+            if (char === "\t") {
+                for (let i = 0; i < TAB_WIDTH; i++) {
+                    this.drawChar(cx, y, " ", style);
+                    cx++;
+                }
+                continue;
+            }
+            // Skip control characters and zero-width characters (variation
+            // selectors, ZWJ, combining marks, etc.) — they have no visual
+            // representation and would render as "missing glyph" boxes.
+            const cp = char.codePointAt(0);
+            if (cp < 0x20 && cp !== 0x09)
+                continue;
+            if (isZeroWidth(cp))
+                continue;
+            const w = charWidth(cp);
+            this.drawChar(cx, y, char, style);
+            cx += w;
+        }
+    }
+    // ── Styled text (segment arrays) ────────────────────────────
+    /**
+     * Draw an array of styled segments at (x, y).
+     * Each segment carries its own TextStyle; segments are drawn sequentially.
+     */
+    drawStyledText(x, y, segments) {
+        let cx = x;
+        for (const seg of segments) {
+            for (const char of seg.text) {
+                if (char === "\t") {
+                    for (let i = 0; i < TAB_WIDTH; i++) {
+                        this.drawChar(cx, y, " ", seg.style);
+                        cx++;
+                    }
+                    continue;
+                }
+                const cp = char.codePointAt(0);
+                if (cp < 0x20 && cp !== 0x09)
+                    continue;
+                if (isZeroWidth(cp))
+                    continue;
+                const w = charWidth(cp);
+                this.drawChar(cx, y, char, seg.style);
+                cx += w;
+            }
+        }
+    }
+    // ── Box drawing ──────────────────────────────────────────────
+    /** Draw a box-drawing rectangle (border) with smart corner merging. */
+    drawBox(rect, style) {
+        const { x, y, width, height } = rect;
+        if (width < 1 || height < 1)
+            return;
+        const fgColor = style?.fg ?? DEFAULT_FG;
+        const bgColor = style?.bg ?? TRANSPARENT;
+        const bold = style?.bold ?? false;
+        // Single cell box — draw a cross
+        if (width === 1 && height === 1) {
+            this.drawBoxChar(x, y, UP | RIGHT | DOWN | LEFT, fgColor, bgColor, bold);
+            return;
+        }
+        // Single column box
+        if (width === 1) {
+            this.drawBoxChar(x, y, DOWN, fgColor, bgColor, bold); // top
+            for (let dy = 1; dy < height - 1; dy++) {
+                this.drawBoxChar(x, y + dy, UP | DOWN, fgColor, bgColor, bold);
+            }
+            this.drawBoxChar(x, y + height - 1, UP, fgColor, bgColor, bold); // bottom
+            return;
+        }
+        // Single row box
+        if (height === 1) {
+            this.drawBoxChar(x, y, RIGHT, fgColor, bgColor, bold); // left
+            for (let dx = 1; dx < width - 1; dx++) {
+                this.drawBoxChar(x + dx, y, LEFT | RIGHT, fgColor, bgColor, bold);
+            }
+            this.drawBoxChar(x + width - 1, y, LEFT, fgColor, bgColor, bold); // right
+            return;
+        }
+        // Corners
+        this.drawBoxChar(x, y, DOWN | RIGHT, fgColor, bgColor, bold); // top-left
+        this.drawBoxChar(x + width - 1, y, DOWN | LEFT, fgColor, bgColor, bold); // top-right
+        this.drawBoxChar(x, y + height - 1, UP | RIGHT, fgColor, bgColor, bold); // bottom-left
+        this.drawBoxChar(x + width - 1, y + height - 1, UP | LEFT, fgColor, bgColor, bold); // bottom-right
+        // Top and bottom edges
+        for (let dx = 1; dx < width - 1; dx++) {
+            this.drawBoxChar(x + dx, y, LEFT | RIGHT, fgColor, bgColor, bold); // top
+            this.drawBoxChar(x + dx, y + height - 1, LEFT | RIGHT, fgColor, bgColor, bold); // bottom
+        }
+        // Left and right edges
+        for (let dy = 1; dy < height - 1; dy++) {
+            this.drawBoxChar(x, y + dy, UP | DOWN, fgColor, bgColor, bold); // left
+            this.drawBoxChar(x + width - 1, y + dy, UP | DOWN, fgColor, bgColor, bold); // right
+        }
+    }
+    /**
+     * Draw a single box-drawing character at (x, y), merging with any existing
+     * box pattern at that position.
+     */
+    drawBoxChar(x, y, pattern, fgColor, bgColor, bold) {
+        if (!this.isVisible(x, y))
+            return;
+        // Check if there's already a box pattern at this position
+        const existing = this.bufGet(x, y);
+        const existingPattern = existing.foreground.symbol.pattern;
+        const mergedPattern = existingPattern !== 0
+            ? mergeBoxPatterns(existingPattern, pattern)
+            : pattern;
+        const char = boxChar(mergedPattern);
+        const s = sym(char, mergedPattern);
+        const fg = foreground(s, fgColor, { bold });
+        const bg = background(bgColor);
+        const px = { foreground: fg, background: bg };
+        this.bufSet(x, y, blendPixel(px, this.bufGet(x, y)));
+    }
+    // ── Lines ────────────────────────────────────────────────────
+    /** Draw a horizontal line using box-drawing characters. */
+    drawHLine(x, y, width, style) {
+        const fgColor = style?.fg ?? DEFAULT_FG;
+        const bgColor = style?.bg ?? TRANSPARENT;
+        const bold = style?.bold ?? false;
+        for (let dx = 0; dx < width; dx++) {
+            this.drawBoxChar(x + dx, y, LEFT | RIGHT, fgColor, bgColor, bold);
+        }
+    }
+    /** Draw a vertical line using box-drawing characters. */
+    drawVLine(x, y, height, style) {
+        const fgColor = style?.fg ?? DEFAULT_FG;
+        const bgColor = style?.bg ?? TRANSPARENT;
+        const bold = style?.bold ?? false;
+        for (let dy = 0; dy < height; dy++) {
+            this.drawBoxChar(x, y + dy, UP | DOWN, fgColor, bgColor, bold);
+        }
+    }
+    // ── Raw pixel operations ─────────────────────────────────────
+    /** Set a pixel directly. Respects clip. */
+    setPixel(x, y, pixel) {
+        if (!this.isVisible(x, y))
+            return;
+        this.bufSet(x, y, pixel);
+    }
+    /** Blend a pixel at (x, y) with what's already there. Respects clip. */
+    blendPixel(x, y, pixel) {
+        if (!this.isVisible(x, y))
+            return;
+        this.bufSet(x, y, blendPixel(pixel, this.bufGet(x, y)));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @teammates/consolonia — Terminal UI rendering engine for Node.js.
+ *
+ * A TypeScript port of Consolonia (.NET console UI framework).
+ * Provides pixel-buffer rendering, raw input handling, layout engine,
+ * and widgets for building interactive terminal applications.
+ */
+export { background, blendBackground, EMPTY_BACKGROUND, type PixelBackground, } from "./pixel/background.js";
+export { BOX_CHARS, BOX_NONE, type BoxPattern, boxChar, DOWN, LEFT, mergeBoxPatterns, RIGHT, UP, } from "./pixel/box-pattern.js";
+export { PixelBuffer } from "./pixel/buffer.js";
+export { BLACK, BLACK_BRIGHT, BLUE, BLUE_BRIGHT, type Color, CYAN, CYAN_BRIGHT, color, colorBlend, colorBrighten, colorShade, DARK_GRAY, GRAY, GREEN, GREEN_BRIGHT, GREY, LIGHT_GRAY, MAGENTA, MAGENTA_BRIGHT, RED, RED_BRIGHT, TRANSPARENT, WHITE, WHITE_BRIGHT, YELLOW, YELLOW_BRIGHT, } from "./pixel/color.js";
+export { blendForeground, EMPTY_FOREGROUND, foreground, type PixelForeground, } from "./pixel/foreground.js";
+export { blendPixel, PIXEL_EMPTY, PIXEL_SPACE, type Pixel, pixel, } from "./pixel/pixel.js";
+export { charWidth, EMPTY_SYMBOL, isZeroWidth, type Symbol, stringDisplayWidth, sym, } from "./pixel/symbol.js";
+export type { Constraint, Point, Rect, Size, } from "./layout/types.js";
+export * as esc from "./ansi/esc.js";
+export { AnsiOutput } from "./ansi/output.js";
+export { stripAnsi, truncateAnsi, visibleLength, } from "./ansi/strip.js";
+export { DirtyRegions, DirtySnapshot } from "./render/regions.js";
+export { RenderTarget } from "./render/render-target.js";
+export { EscapeMatcher } from "./input/escape-matcher.js";
+export type { InputEvent, KeyEvent, MouseEvent, PasteEvent, } from "./input/events.js";
+export { keyEvent, mouseEvent, pasteEvent, resizeEvent, } from "./input/events.js";
+export { type IMatcher, MatchResult } from "./input/matcher.js";
+export { MouseMatcher } from "./input/mouse-matcher.js";
+export { PasteMatcher } from "./input/paste-matcher.js";
+export { createInputProcessor, InputProcessor } from "./input/processor.js";
+export { disableRawMode, enableRawMode } from "./input/raw-mode.js";
+export { TextMatcher } from "./input/text-matcher.js";
+export { ClipStack } from "./drawing/clip.js";
+export { type BoxStyle, DrawingContext, type TextStyle, } from "./drawing/context.js";
+export { Box, type BoxOptions } from "./layout/box.js";
+export { Column, type ColumnOptions } from "./layout/column.js";
+export { Control } from "./layout/control.js";
+export { Row, type RowOptions } from "./layout/row.js";
+export { Stack, type StackOptions } from "./layout/stack.js";
+export { Border, type BorderOptions } from "./widgets/border.js";
+export { ChatView, type ChatViewOptions, type DropdownItem, type FeedActionItem, } from "./widgets/chat-view.js";
+export { Interview, type InterviewOptions, type InterviewQuestion, } from "./widgets/interview.js";
+export { Panel, type PanelOptions } from "./widgets/panel.js";
+export { ScrollView, type ScrollViewOptions } from "./widgets/scroll-view.js";
+export { type StyledLine, StyledText, type StyledTextOptions, } from "./widgets/styled-text.js";
+export { Text, type TextOptions } from "./widgets/text.js";
+export { type DeleteSizer, type InputColorizer, TextInput, type TextInputOptions, } from "./widgets/text-input.js";
+export { type MarkdownOptions, type MarkdownTheme, renderMarkdown, } from "./widgets/markdown.js";
+export { DEFAULT_SYNTAX_THEME, getHighlighter, highlightLine, registerHighlighter, type SyntaxHighlighter, type SyntaxTheme, type SyntaxToken, type SyntaxTokenType, } from "./widgets/syntax.js";
+export { concat, isStyledSpan, pen, type StyledSegment, type StyledSpan, spanLength, spanText, } from "./styled.js";
+export { App, type AppOptions } from "./app.js";

package/dist/index.js

@@ -0,0 +1,63 @@
+/**
+ * @teammates/consolonia — Terminal UI rendering engine for Node.js.
+ *
+ * A TypeScript port of Consolonia (.NET console UI framework).
+ * Provides pixel-buffer rendering, raw input handling, layout engine,
+ * and widgets for building interactive terminal applications.
+ */
+// ── Pixel types ─────────────────────────────────────────────────────
+export { background, blendBackground, EMPTY_BACKGROUND, } from "./pixel/background.js";
+export { BOX_CHARS, BOX_NONE, boxChar, DOWN, LEFT, mergeBoxPatterns, RIGHT, UP, } from "./pixel/box-pattern.js";
+export { PixelBuffer } from "./pixel/buffer.js";
+export { 
+// Standard ANSI colors
+BLACK, 
+// Bright ANSI colors
+BLACK_BRIGHT, BLUE, BLUE_BRIGHT, CYAN, CYAN_BRIGHT, color, colorBlend, colorBrighten, colorShade, DARK_GRAY, 
+// Aliases
+GRAY, GREEN, GREEN_BRIGHT, GREY, LIGHT_GRAY, MAGENTA, MAGENTA_BRIGHT, RED, RED_BRIGHT, TRANSPARENT, WHITE, WHITE_BRIGHT, YELLOW, YELLOW_BRIGHT, } from "./pixel/color.js";
+export { blendForeground, EMPTY_FOREGROUND, foreground, } from "./pixel/foreground.js";
+export { blendPixel, PIXEL_EMPTY, PIXEL_SPACE, pixel, } from "./pixel/pixel.js";
+export { charWidth, EMPTY_SYMBOL, isZeroWidth, stringDisplayWidth, sym, } from "./pixel/symbol.js";
+// ── ANSI output ─────────────────────────────────────────────────────
+export * as esc from "./ansi/esc.js";
+export { AnsiOutput } from "./ansi/output.js";
+export { stripAnsi, truncateAnsi, visibleLength, } from "./ansi/strip.js";
+// ── Render pipeline ─────────────────────────────────────────────────
+export { DirtyRegions, DirtySnapshot } from "./render/regions.js";
+export { RenderTarget } from "./render/render-target.js";
+// ── Input system ────────────────────────────────────────────────────
+export { EscapeMatcher } from "./input/escape-matcher.js";
+export { keyEvent, mouseEvent, pasteEvent, resizeEvent, } from "./input/events.js";
+export { MatchResult } from "./input/matcher.js";
+export { MouseMatcher } from "./input/mouse-matcher.js";
+export { PasteMatcher } from "./input/paste-matcher.js";
+export { createInputProcessor, InputProcessor } from "./input/processor.js";
+export { disableRawMode, enableRawMode } from "./input/raw-mode.js";
+export { TextMatcher } from "./input/text-matcher.js";
+// ── Drawing context ─────────────────────────────────────────────────
+export { ClipStack } from "./drawing/clip.js";
+export { DrawingContext, } from "./drawing/context.js";
+// ── Layout engine ───────────────────────────────────────────────────
+export { Box } from "./layout/box.js";
+export { Column } from "./layout/column.js";
+export { Control } from "./layout/control.js";
+export { Row } from "./layout/row.js";
+export { Stack } from "./layout/stack.js";
+// ── Widgets ─────────────────────────────────────────────────────────
+export { Border } from "./widgets/border.js";
+export { ChatView, } from "./widgets/chat-view.js";
+export { Interview, } from "./widgets/interview.js";
+export { Panel } from "./widgets/panel.js";
+export { ScrollView } from "./widgets/scroll-view.js";
+export { StyledText, } from "./widgets/styled-text.js";
+export { Text } from "./widgets/text.js";
+export { TextInput, } from "./widgets/text-input.js";
+// ── Markdown ─────────────────────────────────────────────────────────
+export { renderMarkdown, } from "./widgets/markdown.js";
+// ── Syntax highlighting ──────────────────────────────────────────────
+export { DEFAULT_SYNTAX_THEME, getHighlighter, highlightLine, registerHighlighter, } from "./widgets/syntax.js";
+// ── Styled text (chalk-like API) ─────────────────────────────────────
+export { concat, isStyledSpan, pen, spanLength, spanText, } from "./styled.js";
+// ── App shell ────────────────────────────────────────────────────────
+export { App } from "./app.js";

package/dist/input/escape-matcher.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parses ANSI escape sequences into KeyEvents.
+ * Handles CSI sequences, SS3 sequences, and alt+char combinations.
+ */
+import { type InputEvent } from "./events.js";
+import { type IMatcher, MatchResult } from "./matcher.js";
+export declare class EscapeMatcher implements IMatcher {
+    private state;
+    /** Accumulated parameter bytes for CSI sequences (digits and semicolons). */
+    private params;
+    /** The completed event ready for flushing. */
+    private result;
+    append(char: string): MatchResult;
+    flush(): InputEvent | null;
+    reset(): void;
+    /**
+     * Called externally when an ESC timeout fires — emit the standalone
+     * escape key event if we are still in the GotEsc state.
+     */
+    flushEscapeTimeout(): InputEvent | null;
+    private handleControlChar;
+    private handleAfterEsc;
+    private handleCsi;
+    private handleTildeSequence;
+    private handleSs3;
+    private parseModifier;
+}

package/dist/input/escape-matcher.js

@@ -0,0 +1,253 @@
+/**
+ * Parses ANSI escape sequences into KeyEvents.
+ * Handles CSI sequences, SS3 sequences, and alt+char combinations.
+ */
+import { keyEvent } from "./events.js";
+import { MatchResult } from "./matcher.js";
+const ESC = "\x1b";
+/** Internal state of the escape sequence parser. */
+var State;
+(function (State) {
+    /** Waiting for ESC to start a sequence. */
+    State[State["Idle"] = 0] = "Idle";
+    /** Received ESC, waiting to see what follows. */
+    State[State["GotEsc"] = 1] = "GotEsc";
+    /** Inside a CSI sequence (\x1b[). */
+    State[State["Csi"] = 2] = "Csi";
+    /** Inside an SS3 sequence (\x1bO). */
+    State[State["Ss3"] = 3] = "Ss3";
+})(State || (State = {}));
+/** Decode the xterm modifier parameter (1-based) into shift/alt/ctrl flags. */
+function decodeModifier(mod) {
+    // modifier = 1 + (shift ? 1 : 0) + (alt ? 2 : 0) + (ctrl ? 4 : 0)
+    const m = mod - 1;
+    return {
+        shift: (m & 1) !== 0,
+        alt: (m & 2) !== 0,
+        ctrl: (m & 4) !== 0,
+    };
+}
+/**
+ * Map CSI final byte to key name for cursor/editing keys.
+ * Final byte is the letter that terminates the sequence.
+ */
+const CSI_FINAL_KEYS = {
+    A: "up",
+    B: "down",
+    C: "right",
+    D: "left",
+    H: "home",
+    F: "end",
+    Z: "tab", // shift+tab (backtab) produces CSI Z
+};
+/**
+ * Map CSI numeric code (before ~) to key name.
+ * These are the "tilde" sequences like \x1b[3~.
+ */
+const CSI_TILDE_KEYS = {
+    1: "home",
+    2: "insert",
+    3: "delete",
+    4: "end",
+    5: "pageup",
+    6: "pagedown",
+    // Function keys (F5-F12)
+    15: "f5",
+    17: "f6",
+    18: "f7",
+    19: "f8",
+    20: "f9",
+    21: "f10",
+    23: "f11",
+    24: "f12",
+};
+/** SS3 final bytes map to F1-F4. */
+const SS3_KEYS = {
+    P: "f1",
+    Q: "f2",
+    R: "f3",
+    S: "f4",
+};
+/** Control character code points mapped to key names. */
+const CTRL_KEYS = {
+    0: { key: "space", char: "", ctrl: true }, // Ctrl+Space / Ctrl+@
+    8: { key: "backspace", char: "", ctrl: false }, // Ctrl+H (some terminals)
+    9: { key: "tab", char: "\t", ctrl: false },
+    10: { key: "enter", char: "\n", ctrl: false }, // Ctrl+J
+    13: { key: "enter", char: "\r", ctrl: false },
+    127: { key: "backspace", char: "", ctrl: false },
+};
+export class EscapeMatcher {
+    state = State.Idle;
+    /** Accumulated parameter bytes for CSI sequences (digits and semicolons). */
+    params = "";
+    /** The completed event ready for flushing. */
+    result = null;
+    append(char) {
+        const code = char.charCodeAt(0);
+        switch (this.state) {
+            case State.Idle:
+                if (char === ESC) {
+                    this.state = State.GotEsc;
+                    return MatchResult.Partial;
+                }
+                // Handle control characters (Ctrl+A through Ctrl+Z, etc.)
+                if (code < 32 || code === 127) {
+                    return this.handleControlChar(code);
+                }
+                return MatchResult.NoMatch;
+            case State.GotEsc:
+                return this.handleAfterEsc(char, code);
+            case State.Csi:
+                return this.handleCsi(char, code);
+            case State.Ss3:
+                return this.handleSs3(char);
+            default:
+                return MatchResult.NoMatch;
+        }
+    }
+    flush() {
+        const ev = this.result;
+        this.result = null;
+        return ev;
+    }
+    reset() {
+        this.state = State.Idle;
+        this.params = "";
+        this.result = null;
+    }
+    /**
+     * Called externally when an ESC timeout fires — emit the standalone
+     * escape key event if we are still in the GotEsc state.
+     */
+    flushEscapeTimeout() {
+        if (this.state === State.GotEsc) {
+            this.state = State.Idle;
+            this.params = "";
+            return keyEvent("escape", "", false, false, false);
+        }
+        return null;
+    }
+    handleControlChar(code) {
+        const mapped = CTRL_KEYS[code];
+        if (mapped) {
+            this.result = keyEvent(mapped.key, mapped.char, false, mapped.ctrl, false);
+            return MatchResult.Complete;
+        }
+        // Ctrl+A (1) through Ctrl+Z (26)
+        if (code >= 1 && code <= 26) {
+            const letter = String.fromCharCode(code + 96); // 1 -> 'a', 2 -> 'b', etc.
+            this.result = keyEvent(letter, "", false, true, false);
+            return MatchResult.Complete;
+        }
+        // Other control chars (28-31)
+        this.result = keyEvent(`ctrl-${code}`, "", false, true, false);
+        return MatchResult.Complete;
+    }
+    handleAfterEsc(char, code) {
+        if (char === "[") {
+            this.state = State.Csi;
+            this.params = "";
+            return MatchResult.Partial;
+        }
+        if (char === "O") {
+            this.state = State.Ss3;
+            return MatchResult.Partial;
+        }
+        if (char === ESC) {
+            // Double ESC — emit first escape and stay in GotEsc for the second
+            this.result = keyEvent("escape", "", false, false, false);
+            this.state = State.GotEsc;
+            return MatchResult.Complete;
+        }
+        // Alt+char
+        this.state = State.Idle;
+        if (code < 32 || code === 127) {
+            // Alt+control char, e.g. Alt+Enter = \x1b\r
+            const mapped = CTRL_KEYS[code];
+            if (mapped) {
+                this.result = keyEvent(mapped.key, mapped.char, false, mapped.ctrl, true);
+                return MatchResult.Complete;
+            }
+        }
+        // Alt + printable character
+        const isUpper = code >= 65 && code <= 90;
+        const key = char.toLowerCase() || char;
+        this.result = keyEvent(key, char, isUpper, false, true);
+        return MatchResult.Complete;
+    }
+    handleCsi(char, code) {
+        // Parameter bytes: digits, semicolons, and '<' (for SGR mouse, but
+        // mouse-matcher handles that — if we see '<' at start, bail out so
+        // mouse-matcher can handle it)
+        if (this.params.length === 0 && char === "<") {
+            // This is the start of an SGR mouse sequence; we should not match it.
+            this.state = State.Idle;
+            this.params = "";
+            return MatchResult.NoMatch;
+        }
+        if (code >= 0x30 && code <= 0x3b /* 0-9, :, ; */) {
+            this.params += char;
+            return MatchResult.Partial;
+        }
+        // Final byte — the actual command character
+        this.state = State.Idle;
+        if (char === "~") {
+            return this.handleTildeSequence();
+        }
+        const keyName = CSI_FINAL_KEYS[char];
+        if (keyName) {
+            const mods = this.parseModifier();
+            // CSI Z (shift+tab/backtab) always implies shift
+            const shift = char === "Z" ? true : mods.shift;
+            this.params = "";
+            this.result = keyEvent(keyName, "", shift, mods.ctrl, mods.alt);
+            return MatchResult.Complete;
+        }
+        // Unrecognized CSI sequence — discard
+        this.params = "";
+        return MatchResult.NoMatch;
+    }
+    handleTildeSequence() {
+        const parts = this.params.split(";");
+        const num = parseInt(parts[0], 10);
+        this.params = "";
+        const keyName = CSI_TILDE_KEYS[num];
+        if (!keyName) {
+            return MatchResult.NoMatch;
+        }
+        const mods = parts.length >= 2
+            ? decodeModifier(parseInt(parts[1], 10))
+            : { shift: false, ctrl: false, alt: false };
+        this.result = keyEvent(keyName, "", mods.shift, mods.ctrl, mods.alt);
+        return MatchResult.Complete;
+    }
+    handleSs3(char) {
+        this.state = State.Idle;
+        const keyName = SS3_KEYS[char];
+        if (keyName) {
+            this.result = keyEvent(keyName, "", false, false, false);
+            return MatchResult.Complete;
+        }
+        // Some terminals send SS3 A/B/C/D for arrow keys
+        const arrowKey = CSI_FINAL_KEYS[char];
+        if (arrowKey) {
+            this.result = keyEvent(arrowKey, "", false, false, false);
+            return MatchResult.Complete;
+        }
+        return MatchResult.NoMatch;
+    }
+    parseModifier() {
+        if (!this.params) {
+            return { shift: false, ctrl: false, alt: false };
+        }
+        const parts = this.params.split(";");
+        if (parts.length >= 2) {
+            const mod = parseInt(parts[1], 10);
+            if (!Number.isNaN(mod)) {
+                return decodeModifier(mod);
+            }
+        }
+        return { shift: false, ctrl: false, alt: false };
+    }
+}