@teammates/consolonia 0.2.0

package/dist/input/events.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Input event type definitions for the raw terminal input system.
+ * Mirrors Consolonia's RawConsoleInputEventArgs and related types.
+ */
+/** Keyboard event produced by key presses and escape sequences. */
+export interface KeyEvent {
+    /** Logical key name: 'a', 'A', 'enter', 'backspace', 'up', 'f1', etc. */
+    key: string;
+    /** The actual character produced, empty string for non-printable keys. */
+    char: string;
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+}
+/** Mouse event produced by SGR extended mouse tracking. */
+export interface MouseEvent {
+    /** 0-based column. */
+    x: number;
+    /** 0-based row. */
+    y: number;
+    button: "left" | "middle" | "right" | "none";
+    type: "press" | "release" | "move" | "wheelup" | "wheeldown";
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+}
+/** Bracketed paste event containing the pasted text. */
+export interface PasteEvent {
+    text: string;
+}
+/** Discriminated union of all input events. */
+export type InputEvent = {
+    type: "key";
+    event: KeyEvent;
+} | {
+    type: "mouse";
+    event: MouseEvent;
+} | {
+    type: "paste";
+    event: PasteEvent;
+} | {
+    type: "resize";
+    width: number;
+    height: number;
+};
+export declare function keyEvent(key: string, char?: string, shift?: boolean, ctrl?: boolean, alt?: boolean): InputEvent;
+export declare function mouseEvent(x: number, y: number, button: MouseEvent["button"], type: MouseEvent["type"], shift?: boolean, ctrl?: boolean, alt?: boolean): InputEvent;
+export declare function pasteEvent(text: string): InputEvent;
+export declare function resizeEvent(width: number, height: number): InputEvent;

package/dist/input/events.js

@@ -0,0 +1,17 @@
+/**
+ * Input event type definitions for the raw terminal input system.
+ * Mirrors Consolonia's RawConsoleInputEventArgs and related types.
+ */
+// ── Factory helpers ─────────────────────────────────────────────────
+export function keyEvent(key, char = "", shift = false, ctrl = false, alt = false) {
+    return { type: "key", event: { key, char, shift, ctrl, alt } };
+}
+export function mouseEvent(x, y, button, type, shift = false, ctrl = false, alt = false) {
+    return { type: "mouse", event: { x, y, button, type, shift, ctrl, alt } };
+}
+export function pasteEvent(text) {
+    return { type: "paste", event: { text } };
+}
+export function resizeEvent(width, height) {
+    return { type: "resize", width, height };
+}

package/dist/input/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Raw terminal input system.
+ *
+ * Provides escape sequence parsing, mouse tracking, bracketed paste
+ * detection, and a unified InputProcessor pipeline.
+ */
+export { EscapeMatcher } from "./escape-matcher.js";
+export type { InputEvent, KeyEvent, MouseEvent, PasteEvent, } from "./events.js";
+export { keyEvent, mouseEvent, pasteEvent, resizeEvent, } from "./events.js";
+export { type IMatcher, MatchResult } from "./matcher.js";
+export { MouseMatcher } from "./mouse-matcher.js";
+export { PasteMatcher } from "./paste-matcher.js";
+export { createInputProcessor, InputProcessor } from "./processor.js";
+export { disableRawMode, enableRawMode } from "./raw-mode.js";
+export { TextMatcher } from "./text-matcher.js";

package/dist/input/index.js

@@ -0,0 +1,14 @@
+/**
+ * Raw terminal input system.
+ *
+ * Provides escape sequence parsing, mouse tracking, bracketed paste
+ * detection, and a unified InputProcessor pipeline.
+ */
+export { EscapeMatcher } from "./escape-matcher.js";
+export { keyEvent, mouseEvent, pasteEvent, resizeEvent, } from "./events.js";
+export { MatchResult } from "./matcher.js";
+export { MouseMatcher } from "./mouse-matcher.js";
+export { PasteMatcher } from "./paste-matcher.js";
+export { createInputProcessor, InputProcessor } from "./processor.js";
+export { disableRawMode, enableRawMode } from "./raw-mode.js";
+export { TextMatcher } from "./text-matcher.js";

package/dist/input/matcher.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Base matcher interface for the input processing pipeline.
+ * Inspired by Consolonia's InputProcessor matcher chain.
+ */
+import type { InputEvent } from "./events.js";
+/** Result of feeding a character to a matcher. */
+export declare enum MatchResult {
+    /** This character is not part of a sequence this matcher handles. */
+    NoMatch = 0,
+    /** This character continues a partial sequence; more input needed. */
+    Partial = 1,
+    /** This character completes a recognized sequence; call flush(). */
+    Complete = 2
+}
+/** A matcher consumes characters and produces InputEvents. */
+export interface IMatcher {
+    /** Feed a character to the matcher. Returns the match state. */
+    append(char: string): MatchResult;
+    /** Get the matched event and reset. Only valid after Complete. */
+    flush(): InputEvent | null;
+    /** Reset matcher state, discarding any partial sequence. */
+    reset(): void;
+}

package/dist/input/matcher.js

@@ -0,0 +1,14 @@
+/**
+ * Base matcher interface for the input processing pipeline.
+ * Inspired by Consolonia's InputProcessor matcher chain.
+ */
+/** Result of feeding a character to a matcher. */
+export var MatchResult;
+(function (MatchResult) {
+    /** This character is not part of a sequence this matcher handles. */
+    MatchResult[MatchResult["NoMatch"] = 0] = "NoMatch";
+    /** This character continues a partial sequence; more input needed. */
+    MatchResult[MatchResult["Partial"] = 1] = "Partial";
+    /** This character completes a recognized sequence; call flush(). */
+    MatchResult[MatchResult["Complete"] = 2] = "Complete";
+})(MatchResult || (MatchResult = {}));

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

@@ -0,0 +1,27 @@
+/**
+ * Parses SGR extended mouse tracking sequences.
+ *
+ * Format: \x1b[<Cb;Cx;CyM  (press/motion)
+ *         \x1b[<Cb;Cx;Cym  (release)
+ *
+ * Cb encodes button and modifiers:
+ *   bits 0-1: 0=left, 1=middle, 2=right
+ *   bit 5 (+32): motion event
+ *   bits 6-7: 64=wheel up, 65=wheel down
+ *   bit 2 (+4): shift
+ *   bit 3 (+8): alt/meta
+ *   bit 4 (+16): ctrl
+ *
+ * Cx, Cy are 1-based coordinates.
+ */
+import { type InputEvent } from "./events.js";
+import { type IMatcher, MatchResult } from "./matcher.js";
+export declare class MouseMatcher implements IMatcher {
+    private state;
+    private params;
+    private result;
+    append(char: string): MatchResult;
+    flush(): InputEvent | null;
+    reset(): void;
+    private finalize;
+}

package/dist/input/mouse-matcher.js

@@ -0,0 +1,142 @@
+/**
+ * Parses SGR extended mouse tracking sequences.
+ *
+ * Format: \x1b[<Cb;Cx;CyM  (press/motion)
+ *         \x1b[<Cb;Cx;Cym  (release)
+ *
+ * Cb encodes button and modifiers:
+ *   bits 0-1: 0=left, 1=middle, 2=right
+ *   bit 5 (+32): motion event
+ *   bits 6-7: 64=wheel up, 65=wheel down
+ *   bit 2 (+4): shift
+ *   bit 3 (+8): alt/meta
+ *   bit 4 (+16): ctrl
+ *
+ * Cx, Cy are 1-based coordinates.
+ */
+import { mouseEvent } from "./events.js";
+import { MatchResult } from "./matcher.js";
+const ESC = "\x1b";
+var State;
+(function (State) {
+    State[State["Idle"] = 0] = "Idle";
+    /** Got \x1b */
+    State[State["GotEsc"] = 1] = "GotEsc";
+    /** Got \x1b[ */
+    State[State["GotBracket"] = 2] = "GotBracket";
+    /** Got \x1b[< — now reading params until M or m */
+    State[State["Reading"] = 3] = "Reading";
+})(State || (State = {}));
+export class MouseMatcher {
+    state = State.Idle;
+    params = "";
+    result = null;
+    append(char) {
+        switch (this.state) {
+            case State.Idle:
+                if (char === ESC) {
+                    this.state = State.GotEsc;
+                    return MatchResult.Partial;
+                }
+                return MatchResult.NoMatch;
+            case State.GotEsc:
+                if (char === "[") {
+                    this.state = State.GotBracket;
+                    return MatchResult.Partial;
+                }
+                this.state = State.Idle;
+                return MatchResult.NoMatch;
+            case State.GotBracket:
+                if (char === "<") {
+                    this.state = State.Reading;
+                    this.params = "";
+                    return MatchResult.Partial;
+                }
+                this.state = State.Idle;
+                return MatchResult.NoMatch;
+            case State.Reading: {
+                if (char === "M" || char === "m") {
+                    return this.finalize(char === "m");
+                }
+                // Valid param chars: digits and semicolons
+                const code = char.charCodeAt(0);
+                if ((code >= 0x30 && code <= 0x39) || char === ";") {
+                    this.params += char;
+                    return MatchResult.Partial;
+                }
+                // Unexpected character — abort
+                this.state = State.Idle;
+                this.params = "";
+                return MatchResult.NoMatch;
+            }
+            default:
+                return MatchResult.NoMatch;
+        }
+    }
+    flush() {
+        const ev = this.result;
+        this.result = null;
+        return ev;
+    }
+    reset() {
+        this.state = State.Idle;
+        this.params = "";
+        this.result = null;
+    }
+    finalize(isRelease) {
+        this.state = State.Idle;
+        const parts = this.params.split(";");
+        this.params = "";
+        if (parts.length !== 3) {
+            return MatchResult.NoMatch;
+        }
+        const cb = parseInt(parts[0], 10);
+        const cx = parseInt(parts[1], 10);
+        const cy = parseInt(parts[2], 10);
+        if (Number.isNaN(cb) || Number.isNaN(cx) || Number.isNaN(cy)) {
+            return MatchResult.NoMatch;
+        }
+        // Decode modifiers from cb
+        const shift = (cb & 4) !== 0;
+        const alt = (cb & 8) !== 0;
+        const ctrl = (cb & 16) !== 0;
+        const isMotion = (cb & 32) !== 0;
+        // Decode button from low bits (masking out modifier/motion bits)
+        const buttonBits = cb & 3;
+        const highBits = cb & (64 | 128);
+        let button;
+        let type;
+        if (highBits === 64) {
+            // Wheel events
+            button = "none";
+            type = buttonBits === 0 ? "wheelup" : "wheeldown";
+        }
+        else if (isRelease) {
+            button = decodeButton(buttonBits);
+            type = "release";
+        }
+        else if (isMotion) {
+            button = buttonBits === 3 ? "none" : decodeButton(buttonBits);
+            type = "move";
+        }
+        else {
+            button = decodeButton(buttonBits);
+            type = "press";
+        }
+        // Convert from 1-based to 0-based coordinates
+        this.result = mouseEvent(cx - 1, cy - 1, button, type, shift, ctrl, alt);
+        return MatchResult.Complete;
+    }
+}
+function decodeButton(bits) {
+    switch (bits) {
+        case 0:
+            return "left";
+        case 1:
+            return "middle";
+        case 2:
+            return "right";
+        default:
+            return "none";
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Detects bracketed paste mode sequences and collects pasted text.
+ *
+ * Start marker: \x1b[200~
+ * End marker:   \x1b[201~
+ * Everything between the markers is emitted as a single PasteEvent.
+ */
+import { type InputEvent } from "./events.js";
+import { type IMatcher, MatchResult } from "./matcher.js";
+export declare class PasteMatcher implements IMatcher {
+    private state;
+    /** How many characters of the start marker have been matched. */
+    private startPos;
+    /** How many characters of the end marker have been matched. */
+    private endPos;
+    /** Accumulated paste text. */
+    private buffer;
+    /** Completed event ready for flushing. */
+    private result;
+    append(char: string): MatchResult;
+    flush(): InputEvent | null;
+    reset(): void;
+}

package/dist/input/paste-matcher.js

@@ -0,0 +1,104 @@
+/**
+ * Detects bracketed paste mode sequences and collects pasted text.
+ *
+ * Start marker: \x1b[200~
+ * End marker:   \x1b[201~
+ * Everything between the markers is emitted as a single PasteEvent.
+ */
+import { pasteEvent } from "./events.js";
+import { MatchResult } from "./matcher.js";
+/** The start marker as an array of characters. */
+const PASTE_START = "\x1b[200~".split("");
+/** The end marker as an array of characters. */
+const PASTE_END = "\x1b[201~".split("");
+var State;
+(function (State) {
+    /** Waiting for the first character of the start marker. */
+    State[State["Idle"] = 0] = "Idle";
+    /** Matching characters of the start marker. */
+    State[State["MatchingStart"] = 1] = "MatchingStart";
+    /** Inside the paste — collecting text. */
+    State[State["Collecting"] = 2] = "Collecting";
+    /** Matching characters of the end marker. */
+    State[State["MatchingEnd"] = 3] = "MatchingEnd";
+})(State || (State = {}));
+export class PasteMatcher {
+    state = State.Idle;
+    /** How many characters of the start marker have been matched. */
+    startPos = 0;
+    /** How many characters of the end marker have been matched. */
+    endPos = 0;
+    /** Accumulated paste text. */
+    buffer = "";
+    /** Completed event ready for flushing. */
+    result = null;
+    append(char) {
+        switch (this.state) {
+            case State.Idle:
+                if (char === PASTE_START[0]) {
+                    this.state = State.MatchingStart;
+                    this.startPos = 1;
+                    return MatchResult.Partial;
+                }
+                return MatchResult.NoMatch;
+            case State.MatchingStart:
+                if (char === PASTE_START[this.startPos]) {
+                    this.startPos++;
+                    if (this.startPos === PASTE_START.length) {
+                        // Full start marker matched — begin collecting.
+                        this.state = State.Collecting;
+                        this.buffer = "";
+                        this.endPos = 0;
+                    }
+                    return MatchResult.Partial;
+                }
+                // Mismatch — not a paste start sequence.
+                this.state = State.Idle;
+                this.startPos = 0;
+                return MatchResult.NoMatch;
+            case State.Collecting:
+                if (char === PASTE_END[0]) {
+                    this.state = State.MatchingEnd;
+                    this.endPos = 1;
+                    return MatchResult.Partial;
+                }
+                this.buffer += char;
+                return MatchResult.Partial;
+            case State.MatchingEnd: {
+                if (char === PASTE_END[this.endPos]) {
+                    this.endPos++;
+                    if (this.endPos === PASTE_END.length) {
+                        // Full end marker matched — paste is complete.
+                        this.state = State.Idle;
+                        this.result = pasteEvent(this.buffer);
+                        this.buffer = "";
+                        this.endPos = 0;
+                        return MatchResult.Complete;
+                    }
+                    return MatchResult.Partial;
+                }
+                // End marker mismatch — the partially-matched end marker chars
+                // are actually part of the paste text.
+                const partial = PASTE_END.slice(0, this.endPos).join("");
+                this.buffer += partial + char;
+                this.state = State.Collecting;
+                this.endPos = 0;
+                return MatchResult.Partial;
+            }
+            default:
+                return MatchResult.NoMatch;
+        }
+    }
+    flush() {
+        const ev = this.result;
+        this.result = null;
+        return ev;
+    }
+    reset() {
+        this.state = State.Idle;
+        this.startPos = 0;
+        this.endPos = 0;
+        this.buffer = "";
+        this.result = null;
+    }
+}

package/dist/input/processor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * InputProcessor — the central input pipeline.
+ * Port of Consolonia's InputProcessor.cs.
+ *
+ * All matchers run in parallel on each character. When multiple matchers
+ * return Partial, all of them continue receiving input. The first matcher
+ * (by priority order) to return Complete wins, and the others are reset.
+ *
+ * Matcher priority order: PasteMatcher > MouseMatcher > EscapeMatcher > TextMatcher
+ *
+ * The escape key requires special handling: a lone ESC (\x1b) could be
+ * the start of an escape sequence or the escape key itself. We use a
+ * short timeout (50ms) to distinguish — if no follow-up character
+ * arrives within the timeout, we emit an escape key event.
+ */
+import { EventEmitter } from "node:events";
+export declare class InputProcessor {
+    private readonly matchers;
+    private readonly escapeMatcher;
+    private readonly emitter;
+    /** Which matchers are still active (Partial or not yet tried) for the current sequence. */
+    private active;
+    /** Timer for the escape key timeout. */
+    private escTimer;
+    constructor(emitter: EventEmitter);
+    /**
+     * Feed a chunk of raw stdin data into the processor.
+     * Characters are dispatched one at a time through the matcher chain.
+     */
+    feed(data: string): void;
+    /** Destroy timers and clean up. */
+    destroy(): void;
+    private feedChar;
+    /** Reset all matchers and re-activate them. */
+    private resetAll;
+    /**
+     * If the escape matcher is active and holding a partial \x1b,
+     * schedule a timeout to emit the escape key event.
+     */
+    private scheduleEscTimeoutIfNeeded;
+    private clearEscTimer;
+    private emit;
+}
+/**
+ * Create an InputProcessor wired to a fresh EventEmitter.
+ * Listen on the returned emitter's 'input' event to receive InputEvents.
+ */
+export declare function createInputProcessor(): {
+    processor: InputProcessor;
+    events: EventEmitter;
+};

package/dist/input/processor.js

@@ -0,0 +1,145 @@
+/**
+ * InputProcessor — the central input pipeline.
+ * Port of Consolonia's InputProcessor.cs.
+ *
+ * All matchers run in parallel on each character. When multiple matchers
+ * return Partial, all of them continue receiving input. The first matcher
+ * (by priority order) to return Complete wins, and the others are reset.
+ *
+ * Matcher priority order: PasteMatcher > MouseMatcher > EscapeMatcher > TextMatcher
+ *
+ * The escape key requires special handling: a lone ESC (\x1b) could be
+ * the start of an escape sequence or the escape key itself. We use a
+ * short timeout (50ms) to distinguish — if no follow-up character
+ * arrives within the timeout, we emit an escape key event.
+ */
+import { EventEmitter } from "node:events";
+import { EscapeMatcher } from "./escape-matcher.js";
+import { MatchResult } from "./matcher.js";
+import { MouseMatcher } from "./mouse-matcher.js";
+import { PasteMatcher } from "./paste-matcher.js";
+import { TextMatcher } from "./text-matcher.js";
+/** Duration in ms to wait for a follow-up character after a lone ESC. */
+const ESC_TIMEOUT_MS = 50;
+export class InputProcessor {
+    matchers;
+    escapeMatcher;
+    emitter;
+    /** Which matchers are still active (Partial or not yet tried) for the current sequence. */
+    active;
+    /** Timer for the escape key timeout. */
+    escTimer = null;
+    constructor(emitter) {
+        this.emitter = emitter;
+        this.escapeMatcher = new EscapeMatcher();
+        // Priority order — first matcher to complete wins.
+        this.matchers = [
+            new PasteMatcher(),
+            new MouseMatcher(),
+            this.escapeMatcher,
+            new TextMatcher(),
+        ];
+        this.active = this.matchers.map(() => true);
+    }
+    /**
+     * Feed a chunk of raw stdin data into the processor.
+     * Characters are dispatched one at a time through the matcher chain.
+     */
+    feed(data) {
+        for (let i = 0; i < data.length; i++) {
+            this.feedChar(data[i]);
+        }
+    }
+    /** Destroy timers and clean up. */
+    destroy() {
+        this.clearEscTimer();
+    }
+    feedChar(char) {
+        // Cancel any pending ESC timeout — we got more input.
+        this.clearEscTimer();
+        let completed = -1;
+        // Feed the character to ALL active matchers in priority order.
+        for (let i = 0; i < this.matchers.length; i++) {
+            if (!this.active[i])
+                continue;
+            const result = this.matchers[i].append(char);
+            if (result === MatchResult.Complete) {
+                completed = i;
+                break; // Highest-priority complete wins
+            }
+            if (result === MatchResult.NoMatch) {
+                this.matchers[i].reset();
+                this.active[i] = false;
+            }
+            // Partial: matcher stays active
+        }
+        if (completed >= 0) {
+            const ev = this.matchers[completed].flush();
+            // Reset all matchers EXCEPT the completed one (it manages its own state,
+            // e.g. EscapeMatcher stays in GotEsc after double-ESC).
+            for (let i = 0; i < this.matchers.length; i++) {
+                if (i !== completed) {
+                    this.matchers[i].reset();
+                }
+                this.active[i] = true;
+            }
+            if (ev) {
+                this.emit(ev);
+            }
+            this.scheduleEscTimeoutIfNeeded();
+            return;
+        }
+        // Check if any matcher is still active (in Partial state).
+        const anyActive = this.active.some((a) => a);
+        if (!anyActive) {
+            // No matcher claimed this sequence. Reset all for next input.
+            this.resetAll();
+            return;
+        }
+        // Some matchers still in Partial state — check for ESC timeout.
+        this.scheduleEscTimeoutIfNeeded();
+    }
+    /** Reset all matchers and re-activate them. */
+    resetAll() {
+        for (let i = 0; i < this.matchers.length; i++) {
+            this.matchers[i].reset();
+            this.active[i] = true;
+        }
+    }
+    /**
+     * If the escape matcher is active and holding a partial \x1b,
+     * schedule a timeout to emit the escape key event.
+     */
+    scheduleEscTimeoutIfNeeded() {
+        const escIdx = this.matchers.indexOf(this.escapeMatcher);
+        if (escIdx < 0 || !this.active[escIdx])
+            return;
+        this.escTimer = setTimeout(() => {
+            this.escTimer = null;
+            const ev = this.escapeMatcher.flushEscapeTimeout();
+            if (ev) {
+                this.resetAll();
+                this.emit(ev);
+            }
+        }, ESC_TIMEOUT_MS);
+    }
+    clearEscTimer() {
+        if (this.escTimer !== null) {
+            clearTimeout(this.escTimer);
+            this.escTimer = null;
+        }
+    }
+    emit(event) {
+        this.emitter.emit("input", event);
+    }
+}
+// ── Convenience factory ───────────────────────────────────────────────
+/**
+ * Create an InputProcessor wired to a fresh EventEmitter.
+ * Listen on the returned emitter's 'input' event to receive InputEvents.
+ */
+export function createInputProcessor() {
+    const events = new EventEmitter();
+    const processor = new InputProcessor(events);
+    return { processor, events };
+}

package/dist/input/raw-mode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Functions to enable and disable raw terminal mode on stdin.
+ */
+/**
+ * Enable raw mode: disables line buffering and echo so we receive
+ * every keystroke as it arrives.
+ */
+export declare function enableRawMode(): void;
+/**
+ * Disable raw mode: restores normal line-buffered terminal input
+ * and pauses stdin so the process can exit cleanly.
+ */
+export declare function disableRawMode(): void;

package/dist/input/raw-mode.js

@@ -0,0 +1,24 @@
+/**
+ * Functions to enable and disable raw terminal mode on stdin.
+ */
+/**
+ * Enable raw mode: disables line buffering and echo so we receive
+ * every keystroke as it arrives.
+ */
+export function enableRawMode() {
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+}
+/**
+ * Disable raw mode: restores normal line-buffered terminal input
+ * and pauses stdin so the process can exit cleanly.
+ */
+export function disableRawMode() {
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+    }
+    process.stdin.pause();
+}