@teammates/consolonia 0.7.0 → 0.7.2

package/dist/ansi/esc.js

@@ -74,12 +74,94 @@ export const eraseLine = `${ESC}2K`;
 export const bracketedPasteOn = `${ESC}?2004h`;
 /** Disable bracketed paste mode. */
 export const bracketedPasteOff = `${ESC}?2004l`;
-/** Enable SGR mouse tracking (any-event tracking + SGR extended coordinates). */
-export const mouseTrackingOn = `${ESC}?1003h${ESC}?1006h`;
-/** Disable SGR mouse tracking. */
-export const mouseTrackingOff = `${ESC}?1006l${ESC}?1003l`;
+/**
+ * Enable mouse tracking with all supported reporting modes.
+ *
+ * Modes enabled (in order):
+ *   ?1000h — Normal/VT200 click tracking (press + release)
+ *   ?1003h — Any-event tracking (all mouse movement)
+ *   ?1005h — UTF-8 coordinate encoding (extends X10 beyond col/row 223)
+ *   ?1006h — SGR extended coordinates (";"-delimited decimals, M/m terminator)
+ *   ?1015h — URXVT extended coordinates (decimal params, no "<" prefix)
+ *   ?1016h — SGR-Pixels (same wire format as SGR, pixel coordinates)
+ *
+ * Terminals pick the highest mode they support. SGR is preferred by most
+ * modern terminals; URXVT and UTF-8 provide fallback for older ones.
+ */
+export const mouseTrackingOn = `${ESC}?1000h${ESC}?1003h${ESC}?1005h${ESC}?1006h${ESC}?1015h${ESC}?1016h`;
+/**
+ * Disable all mouse tracking modes (reverse order of enable).
+ */
+export const mouseTrackingOff = `${ESC}?1016l${ESC}?1015l${ESC}?1006l${ESC}?1005l${ESC}?1003l${ESC}?1000l`;
 // ── Window ──────────────────────────────────────────────────────────
 /** Set the terminal window title. */
 export function setTitle(title) {
     return `${OSC}0;${title}\x07`;
 }
+// ── Environment-aware init/restore ─────────────────────────────────
+/**
+ * Mouse tracking sequence tailored to detected capabilities.
+ *
+ * When the terminal supports SGR, request all six modes so the terminal
+ * picks the highest one it handles. When SGR is not available (e.g. GNU
+ * screen), fall back to normal + any-event tracking only — UTF-8 and
+ * URXVT modes could confuse terminals that don't understand them.
+ */
+export function mouseOn(caps) {
+    if (!caps.mouse)
+        return "";
+    if (caps.sgrMouse)
+        return mouseTrackingOn;
+    // Minimal: normal click + any-event only
+    return `${ESC}?1000h${ESC}?1003h`;
+}
+/** Matching disable sequence for mouseOn(). */
+export function mouseOff(caps) {
+    if (!caps.mouse)
+        return "";
+    if (caps.sgrMouse)
+        return mouseTrackingOff;
+    return `${ESC}?1003l${ESC}?1000l`;
+}
+/**
+ * Build the full terminal preparation sequence for the given environment.
+ *
+ * @param caps  - Detected terminal capabilities
+ * @param opts  - Which optional features the app requested
+ */
+export function initSequence(caps, opts) {
+    if (!caps.isTTY)
+        return "";
+    let seq = "";
+    if (opts.alternateScreen && caps.alternateScreen) {
+        seq += alternateScreenOn;
+    }
+    seq += hideCursor;
+    if (caps.bracketedPaste) {
+        seq += bracketedPasteOn;
+    }
+    if (opts.mouse) {
+        seq += mouseOn(caps);
+    }
+    seq += clearScreen;
+    return seq;
+}
+/**
+ * Build the full terminal restore sequence (mirror of initSequence).
+ */
+export function restoreSequence(caps, opts) {
+    if (!caps.isTTY)
+        return "";
+    let seq = reset;
+    if (opts.mouse) {
+        seq += mouseOff(caps);
+    }
+    if (caps.bracketedPaste) {
+        seq += bracketedPasteOff;
+    }
+    seq += showCursor;
+    if (opts.alternateScreen && caps.alternateScreen) {
+        seq += alternateScreenOff;
+    }
+    return seq;
+}

package/dist/ansi/terminal-env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Terminal environment detection.
+ *
+ * Probes environment variables and process state to determine which
+ * terminal capabilities are available. Used by App to send only the
+ * escape sequences the host terminal actually supports.
+ */
+export interface TerminalCaps {
+    /** Terminal is a TTY (not piped). */
+    isTTY: boolean;
+    /** Supports alternate screen buffer (?1049h). */
+    alternateScreen: boolean;
+    /** Supports bracketed paste mode (?2004h). */
+    bracketedPaste: boolean;
+    /** Supports escape-based mouse tracking (?1000h and above). */
+    mouse: boolean;
+    /** Supports SGR extended mouse encoding (?1006h). */
+    sgrMouse: boolean;
+    /** Supports truecolor (24-bit) SGR sequences. */
+    truecolor: boolean;
+    /** Supports 256-color SGR sequences. */
+    color256: boolean;
+    /** Detected terminal name (for diagnostics). */
+    name: string;
+}
+/**
+ * Detect terminal capabilities from the current environment.
+ *
+ * On Windows the main differentiator is whether we're running under
+ * Windows Terminal / ConPTY (full VT support) or legacy conhost
+ * (very limited escape handling). On Unix the TERM variable and
+ * TERM_PROGRAM give us enough signal.
+ */
+export declare function detectTerminal(): TerminalCaps;

package/dist/ansi/terminal-env.js

@@ -0,0 +1,206 @@
+/**
+ * Terminal environment detection.
+ *
+ * Probes environment variables and process state to determine which
+ * terminal capabilities are available. Used by App to send only the
+ * escape sequences the host terminal actually supports.
+ */
+// ── Detection ───────────────────────────────────────────────────────
+/**
+ * Detect terminal capabilities from the current environment.
+ *
+ * On Windows the main differentiator is whether we're running under
+ * Windows Terminal / ConPTY (full VT support) or legacy conhost
+ * (very limited escape handling). On Unix the TERM variable and
+ * TERM_PROGRAM give us enough signal.
+ */
+export function detectTerminal() {
+    const env = process.env;
+    const isTTY = !!process.stdout.isTTY;
+    if (!isTTY) {
+        return {
+            isTTY: false,
+            alternateScreen: false,
+            bracketedPaste: false,
+            mouse: false,
+            sgrMouse: false,
+            truecolor: false,
+            color256: false,
+            name: "pipe",
+        };
+    }
+    // ── Windows ─────────────────────────────────────────────────────
+    if (process.platform === "win32") {
+        // Windows Terminal sets WT_SESSION
+        if (env.WT_SESSION) {
+            return {
+                isTTY: true,
+                alternateScreen: true,
+                bracketedPaste: true,
+                mouse: true,
+                sgrMouse: true,
+                truecolor: true,
+                color256: true,
+                name: "windows-terminal",
+            };
+        }
+        // VS Code's integrated terminal (xterm.js)
+        if (env.TERM_PROGRAM === "vscode") {
+            return {
+                isTTY: true,
+                alternateScreen: true,
+                bracketedPaste: true,
+                mouse: true,
+                sgrMouse: true,
+                truecolor: true,
+                color256: true,
+                name: "vscode",
+            };
+        }
+        // ConEmu / Cmder
+        if (env.ConEmuPID) {
+            return {
+                isTTY: true,
+                alternateScreen: true,
+                bracketedPaste: true,
+                mouse: true,
+                sgrMouse: true,
+                truecolor: true,
+                color256: true,
+                name: "conemu",
+            };
+        }
+        // Mintty (Git Bash) — sets TERM=xterm*
+        if (env.TERM?.startsWith("xterm") && env.MSYSTEM) {
+            return {
+                isTTY: true,
+                alternateScreen: true,
+                bracketedPaste: true,
+                mouse: true,
+                sgrMouse: true,
+                truecolor: true,
+                color256: true,
+                name: "mintty",
+            };
+        }
+        // Fallback: modern Windows 10+ conhost with ConPTY has decent VT
+        // support, but mouse tracking can be unreliable. Enable everything
+        // and let the terminal silently ignore what it doesn't support.
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: true,
+            color256: true,
+            name: "conhost",
+        };
+    }
+    // ── Unix / macOS ────────────────────────────────────────────────
+    const term = env.TERM ?? "";
+    const termProgram = env.TERM_PROGRAM ?? "";
+    // tmux — full VT support, passes through SGR mouse
+    if (env.TMUX || term.startsWith("tmux") || term === "screen-256color") {
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: !!env.COLORTERM || term.includes("256color"),
+            color256: true,
+            name: "tmux",
+        };
+    }
+    // GNU screen — limited mouse support, no SGR
+    if (term === "screen" && !env.TMUX) {
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: false,
+            mouse: true,
+            sgrMouse: false,
+            truecolor: false,
+            color256: false,
+            name: "screen",
+        };
+    }
+    // iTerm2
+    if (termProgram === "iTerm.app" || env.ITERM_SESSION_ID) {
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: true,
+            color256: true,
+            name: "iterm2",
+        };
+    }
+    // VS Code integrated terminal (macOS/Linux)
+    if (termProgram === "vscode") {
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: true,
+            color256: true,
+            name: "vscode",
+        };
+    }
+    // Alacritty
+    if (termProgram === "Alacritty" || term === "alacritty") {
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: true,
+            color256: true,
+            name: "alacritty",
+        };
+    }
+    // xterm-compatible (most Linux/macOS terminals)
+    if (term.startsWith("xterm") || term.includes("256color")) {
+        const hasTruecolor = env.COLORTERM === "truecolor" || env.COLORTERM === "24bit";
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: hasTruecolor,
+            color256: true,
+            name: term,
+        };
+    }
+    // Dumb terminal — absolute minimum
+    if (term === "dumb" || !term) {
+        return {
+            isTTY: true,
+            alternateScreen: false,
+            bracketedPaste: false,
+            mouse: false,
+            sgrMouse: false,
+            truecolor: false,
+            color256: false,
+            name: term || "unknown",
+        };
+    }
+    // Unknown but it is a TTY — enable common capabilities
+    return {
+        isTTY: true,
+        alternateScreen: true,
+        bracketedPaste: true,
+        mouse: true,
+        sgrMouse: false,
+        truecolor: false,
+        color256: true,
+        name: term,
+    };
+}

package/dist/ansi/win32-console.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Win32 Console Mode — enables mouse input on Windows terminals.
+ *
+ * Node.js `setRawMode(true)` enables ENABLE_VIRTUAL_TERMINAL_INPUT but
+ * does NOT disable ENABLE_QUICK_EDIT_MODE (which intercepts mouse clicks
+ * for text selection) or enable ENABLE_MOUSE_INPUT. This module uses
+ * koffi to call the Win32 API directly and set the correct flags.
+ *
+ * Only loaded on win32 — no-ops on other platforms.
+ */
+/**
+ * Configure the Windows console for mouse input.
+ *
+ * Disables Quick Edit Mode (which swallows mouse clicks) and enables
+ * ENABLE_MOUSE_INPUT + ENABLE_EXTENDED_FLAGS + ENABLE_WINDOW_INPUT.
+ * Saves the original mode so it can be restored later.
+ *
+ * No-op on non-Windows platforms or if koffi is not available.
+ * Returns true if the mode was successfully changed.
+ */
+export declare function enableWin32Mouse(): boolean;
+/**
+ * Restore the original Windows console mode saved by enableWin32Mouse().
+ *
+ * No-op if enableWin32Mouse() was never called or failed.
+ * Returns true if the mode was successfully restored.
+ */
+export declare function restoreWin32Console(): boolean;

package/dist/ansi/win32-console.js

@@ -0,0 +1,122 @@
+/**
+ * Win32 Console Mode — enables mouse input on Windows terminals.
+ *
+ * Node.js `setRawMode(true)` enables ENABLE_VIRTUAL_TERMINAL_INPUT but
+ * does NOT disable ENABLE_QUICK_EDIT_MODE (which intercepts mouse clicks
+ * for text selection) or enable ENABLE_MOUSE_INPUT. This module uses
+ * koffi to call the Win32 API directly and set the correct flags.
+ *
+ * Only loaded on win32 — no-ops on other platforms.
+ */
+import { createRequire } from "node:module";
+// ── Console mode flag constants ─────────────────────────────────────
+const ENABLE_PROCESSED_INPUT = 0x0001;
+const ENABLE_LINE_INPUT = 0x0002;
+const ENABLE_ECHO_INPUT = 0x0004;
+const ENABLE_WINDOW_INPUT = 0x0008;
+const ENABLE_MOUSE_INPUT = 0x0010;
+const ENABLE_QUICK_EDIT_MODE = 0x0040;
+const ENABLE_EXTENDED_FLAGS = 0x0080;
+const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
+const STD_INPUT_HANDLE = -10;
+// ── State ───────────────────────────────────────────────────────────
+let originalMode = null;
+let _kernel32;
+function getKernel32() {
+    if (_kernel32 !== undefined)
+        return _kernel32;
+    try {
+        // koffi is an optional native dependency — dynamic require so the
+        // module loads cleanly even when koffi is absent.
+        const require = createRequire(import.meta.url);
+        const koffi = require("koffi");
+        const lib = koffi.load("kernel32.dll");
+        _kernel32 = {
+            GetStdHandle: lib.func("void* __stdcall GetStdHandle(int nStdHandle)"),
+            GetConsoleMode: lib.func("bool __stdcall GetConsoleMode(void* hConsoleHandle, _Out_ uint32_t* lpMode)"),
+            SetConsoleMode: lib.func("bool __stdcall SetConsoleMode(void* hConsoleHandle, uint32_t dwMode)"),
+        };
+    }
+    catch {
+        _kernel32 = null;
+    }
+    return _kernel32;
+}
+// ── Public API ──────────────────────────────────────────────────────
+/**
+ * Configure the Windows console for mouse input.
+ *
+ * Disables Quick Edit Mode (which swallows mouse clicks) and enables
+ * ENABLE_MOUSE_INPUT + ENABLE_EXTENDED_FLAGS + ENABLE_WINDOW_INPUT.
+ * Saves the original mode so it can be restored later.
+ *
+ * No-op on non-Windows platforms or if koffi is not available.
+ * Returns true if the mode was successfully changed.
+ */
+export function enableWin32Mouse() {
+    if (process.platform !== "win32")
+        return false;
+    const k32 = getKernel32();
+    if (!k32)
+        return false;
+    try {
+        const handle = k32.GetStdHandle(STD_INPUT_HANDLE);
+        if (!handle)
+            return false;
+        // Read current mode
+        const modeBuffer = Buffer.alloc(4);
+        if (!k32.GetConsoleMode(handle, modeBuffer))
+            return false;
+        originalMode = modeBuffer.readUInt32LE(0);
+        // Build new mode:
+        // - Keep ENABLE_VIRTUAL_TERMINAL_INPUT (set by Node raw mode)
+        // - Add ENABLE_MOUSE_INPUT + ENABLE_WINDOW_INPUT + ENABLE_EXTENDED_FLAGS
+        // - Remove ENABLE_QUICK_EDIT_MODE
+        // - Remove line/echo/processed (already cleared by raw mode)
+        let newMode = originalMode;
+        newMode |= ENABLE_MOUSE_INPUT;
+        newMode |= ENABLE_WINDOW_INPUT;
+        newMode |= ENABLE_EXTENDED_FLAGS;
+        newMode &= ~ENABLE_QUICK_EDIT_MODE;
+        newMode &= ~ENABLE_LINE_INPUT;
+        newMode &= ~ENABLE_ECHO_INPUT;
+        newMode &= ~ENABLE_PROCESSED_INPUT;
+        // Preserve VT input if it was set
+        if (originalMode & ENABLE_VIRTUAL_TERMINAL_INPUT) {
+            newMode |= ENABLE_VIRTUAL_TERMINAL_INPUT;
+        }
+        return k32.SetConsoleMode(handle, newMode);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Restore the original Windows console mode saved by enableWin32Mouse().
+ *
+ * No-op if enableWin32Mouse() was never called or failed.
+ * Returns true if the mode was successfully restored.
+ */
+export function restoreWin32Console() {
+    if (process.platform !== "win32" || originalMode === null)
+        return false;
+    const k32 = getKernel32();
+    if (!k32) {
+        originalMode = null;
+        return false;
+    }
+    try {
+        const handle = k32.GetStdHandle(STD_INPUT_HANDLE);
+        if (!handle) {
+            originalMode = null;
+            return false;
+        }
+        const result = k32.SetConsoleMode(handle, originalMode);
+        originalMode = null;
+        return result;
+    }
+    catch {
+        originalMode = null;
+        return false;
+    }
+}

package/dist/app.d.ts

@@ -5,6 +5,7 @@
  * RenderTarget, DrawingContext, InputProcessor) and drives the
  * measure → arrange → render loop in response to input and resize events.
  */
+import { type TerminalCaps } from "./ansi/terminal-env.js";
 import type { Control } from "./layout/control.js";
 export interface AppOptions {
     /** Root control to render. */
@@ -21,6 +22,7 @@ export declare class App {
     private readonly _alternateScreen;
     private readonly _mouse;
     private readonly _title;
+    private readonly _caps;
     private _output;
     private _buffer;
     private _dirtyRegions;
@@ -34,6 +36,8 @@ export declare class App {
     private _resizeListener;
     private _sigintListener;
     private _renderScheduled;
+    /** Detected terminal capabilities (read-only, for diagnostics). */
+    get caps(): Readonly<TerminalCaps>;
     constructor(options: AppOptions);
     /**
      * Start the app — enters raw mode, sets up terminal, runs the event

package/dist/app.js

@@ -7,6 +7,8 @@
  */
 import * as esc from "./ansi/esc.js";
 import { AnsiOutput } from "./ansi/output.js";
+import { detectTerminal } from "./ansi/terminal-env.js";
+import { enableWin32Mouse, restoreWin32Console } from "./ansi/win32-console.js";
 import { DrawingContext } from "./drawing/context.js";
 import { createInputProcessor } from "./input/processor.js";
 import { disableRawMode, enableRawMode } from "./input/raw-mode.js";
@@ -19,6 +21,7 @@ export class App {
     _alternateScreen;
     _mouse;
     _title;
+    _caps;
     // Subsystems — created during run()
     _output;
     _buffer;
@@ -34,11 +37,16 @@ export class App {
     _resizeListener = null;
     _sigintListener = null;
     _renderScheduled = false;
+    /** Detected terminal capabilities (read-only, for diagnostics). */
+    get caps() {
+        return this._caps;
+    }
     constructor(options) {
         this.root = options.root;
         this._alternateScreen = options.alternateScreen ?? true;
         this._mouse = options.mouse ?? false;
         this._title = options.title;
+        this._caps = detectTerminal();
     }
     // ── Public API ───────────────────────────────────────────────────
     /**
@@ -90,54 +98,50 @@ export class App {
         const stdout = process.stdout;
         // 1. Enable raw mode
         enableRawMode();
-        // 2. Create ANSI output
+        // 2. On Windows, configure console mode for mouse input
+        //    (must happen after raw mode so we modify the right base flags)
+        if (this._mouse) {
+            enableWin32Mouse();
+        }
+        // 3. Create ANSI output
         this._output = new AnsiOutput(stdout);
-        // 3. Prepare terminal (custom sequence instead of prepareTerminal()
+        // 4. Prepare terminal (custom sequence instead of prepareTerminal()
         //    so we can conditionally enable mouse tracking)
         this._prepareTerminal();
-        // 4. Set terminal title
+        // 5. Set terminal title
         if (this._title) {
             stdout.write(esc.setTitle(this._title));
         }
-        // 5. Create pixel buffer at terminal dimensions
+        // 6. Create pixel buffer at terminal dimensions
         const cols = stdout.columns || 80;
         const rows = stdout.rows || 24;
         this._createRenderPipeline(cols, rows);
-        // 6. Wire up input
+        // 7. Wire up input
         this._setupInput();
-        // 7. Wire up resize
+        // 8. Wire up resize
         this._resizeListener = () => this._handleResize();
         stdout.on("resize", this._resizeListener);
-        // 8. SIGINT fallback
+        // 9. SIGINT fallback
         this._sigintListener = () => this.stop();
         process.on("SIGINT", this._sigintListener);
     }
     _prepareTerminal() {
         const stream = process.stdout;
-        let seq = "";
-        if (this._alternateScreen) {
-            seq += esc.alternateScreenOn;
-        }
-        seq += esc.hideCursor;
-        seq += esc.bracketedPasteOn;
-        if (this._mouse) {
-            seq += esc.mouseTrackingOn;
-        }
-        seq += esc.clearScreen;
-        stream.write(seq);
+        const seq = esc.initSequence(this._caps, {
+            alternateScreen: this._alternateScreen,
+            mouse: this._mouse,
+        });
+        if (seq)
+            stream.write(seq);
     }
     _restoreTerminal() {
         const stream = process.stdout;
-        let seq = esc.reset;
-        if (this._mouse) {
-            seq += esc.mouseTrackingOff;
-        }
-        seq += esc.bracketedPasteOff;
-        seq += esc.showCursor;
-        if (this._alternateScreen) {
-            seq += esc.alternateScreenOff;
-        }
-        stream.write(seq);
+        const seq = esc.restoreSequence(this._caps, {
+            alternateScreen: this._alternateScreen,
+            mouse: this._mouse,
+        });
+        if (seq)
+            stream.write(seq);
     }
     _createRenderPipeline(cols, rows) {
         this._buffer = new PixelBuffer(cols, rows);
@@ -296,6 +300,8 @@ export class App {
         }
         // Restore terminal
         this._restoreTerminal();
+        // Restore Win32 console mode (before disabling raw mode)
+        restoreWin32Console();
         // Disable raw mode
         disableRawMode();
         // Resolve the run() promise

package/dist/index.d.ts

@@ -16,6 +16,8 @@ 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 { detectTerminal, type TerminalCaps, } from "./ansi/terminal-env.js";
+export { enableWin32Mouse, restoreWin32Console, } from "./ansi/win32-console.js";
 export { DirtyRegions, DirtySnapshot } from "./render/regions.js";
 export { RenderTarget } from "./render/render-target.js";
 export { EscapeMatcher } from "./input/escape-matcher.js";

package/dist/index.js

@@ -23,6 +23,8 @@ export { charWidth, EMPTY_SYMBOL, isZeroWidth, stringDisplayWidth, sym, } from "
 export * as esc from "./ansi/esc.js";
 export { AnsiOutput } from "./ansi/output.js";
 export { stripAnsi, truncateAnsi, visibleLength, } from "./ansi/strip.js";
+export { detectTerminal, } from "./ansi/terminal-env.js";
+export { enableWin32Mouse, restoreWin32Console, } from "./ansi/win32-console.js";
 // ── Render pipeline ─────────────────────────────────────────────────
 export { DirtyRegions, DirtySnapshot } from "./render/regions.js";
 export { RenderTarget } from "./render/render-target.js";