@teammates/consolonia 0.6.3 → 0.7.1

package/dist/__tests__/ansi.test.js

@@ -1,8 +1,9 @@
 import { Writable } from "node:stream";
-import { beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import * as esc from "../ansi/esc.js";
 import { AnsiOutput } from "../ansi/output.js";
 import { stripAnsi, truncateAnsi, visibleLength } from "../ansi/strip.js";
+import { detectTerminal } from "../ansi/terminal-env.js";
 // ── Helpers ────────────────────────────────────────────────────────
 const ESC = "\x1b[";
 /** Build a mock writable stream that accumulates output to a string. */
@@ -123,11 +124,11 @@ describe("esc", () => {
             expect(esc.bracketedPasteOn).toBe(`${ESC}?2004h`);
             expect(esc.bracketedPasteOff).toBe(`${ESC}?2004l`);
         });
-        it("mouseTrackingOn enables button-event tracking and SGR mode", () => {
-            expect(esc.mouseTrackingOn).toBe(`${ESC}?1003h${ESC}?1006h`);
+        it("mouseTrackingOn enables all mouse tracking modes", () => {
+            expect(esc.mouseTrackingOn).toBe(`${ESC}?1000h${ESC}?1003h${ESC}?1005h${ESC}?1006h${ESC}?1015h${ESC}?1016h`);
         });
-        it("mouseTrackingOff disables SGR mode and button-event tracking", () => {
-            expect(esc.mouseTrackingOff).toBe(`${ESC}?1006l${ESC}?1003l`);
+        it("mouseTrackingOff disables all mouse tracking modes", () => {
+            expect(esc.mouseTrackingOff).toBe(`${ESC}?1016l${ESC}?1015l${ESC}?1006l${ESC}?1005l${ESC}?1003l${ESC}?1000l`);
         });
     });
     describe("setTitle", () => {
@@ -518,3 +519,208 @@ describe("AnsiOutput", () => {
         });
     });
 });
+// ═══════════════════════════════════════════════════════════════════
+// terminal-env.ts
+// ═══════════════════════════════════════════════════════════════════
+describe("detectTerminal", () => {
+    const origEnv = { ...process.env };
+    const origPlatform = process.platform;
+    const origIsTTY = process.stdout.isTTY;
+    afterEach(() => {
+        // Restore environment
+        for (const key of Object.keys(process.env)) {
+            if (!(key in origEnv))
+                delete process.env[key];
+        }
+        Object.assign(process.env, origEnv);
+        Object.defineProperty(process, "platform", { value: origPlatform });
+        Object.defineProperty(process.stdout, "isTTY", { value: origIsTTY, writable: true });
+    });
+    function setEnv(overrides) {
+        for (const [k, v] of Object.entries(overrides)) {
+            if (v === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = v;
+        }
+    }
+    it("returns pipe caps when stdout is not a TTY", () => {
+        Object.defineProperty(process.stdout, "isTTY", { value: false, writable: true });
+        const caps = detectTerminal();
+        expect(caps.isTTY).toBe(false);
+        expect(caps.mouse).toBe(false);
+        expect(caps.alternateScreen).toBe(false);
+        expect(caps.name).toBe("pipe");
+    });
+    it("detects Windows Terminal via WT_SESSION", () => {
+        Object.defineProperty(process, "platform", { value: "win32" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ WT_SESSION: "some-guid" });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("windows-terminal");
+        expect(caps.sgrMouse).toBe(true);
+        expect(caps.truecolor).toBe(true);
+    });
+    it("detects VS Code terminal on Windows", () => {
+        Object.defineProperty(process, "platform", { value: "win32" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ WT_SESSION: undefined, TERM_PROGRAM: "vscode" });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("vscode");
+        expect(caps.sgrMouse).toBe(true);
+    });
+    it("detects ConEmu on Windows", () => {
+        Object.defineProperty(process, "platform", { value: "win32" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ WT_SESSION: undefined, TERM_PROGRAM: undefined, ConEmuPID: "1234" });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("conemu");
+    });
+    it("detects mintty via TERM + MSYSTEM", () => {
+        Object.defineProperty(process, "platform", { value: "win32" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ WT_SESSION: undefined, TERM_PROGRAM: undefined, ConEmuPID: undefined, TERM: "xterm-256color", MSYSTEM: "MINGW64" });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("mintty");
+    });
+    it("detects tmux on Unix", () => {
+        Object.defineProperty(process, "platform", { value: "linux" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ TMUX: "/tmp/tmux-1000/default,1234,0", TERM: "screen-256color" });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("tmux");
+        expect(caps.sgrMouse).toBe(true);
+    });
+    it("detects GNU screen with limited caps", () => {
+        Object.defineProperty(process, "platform", { value: "linux" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ TMUX: undefined, TERM: "screen", TERM_PROGRAM: undefined, ITERM_SESSION_ID: undefined });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("screen");
+        expect(caps.sgrMouse).toBe(false);
+        expect(caps.bracketedPaste).toBe(false);
+    });
+    it("detects iTerm2", () => {
+        Object.defineProperty(process, "platform", { value: "darwin" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ TMUX: undefined, TERM: "xterm-256color", TERM_PROGRAM: "iTerm.app" });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("iterm2");
+        expect(caps.truecolor).toBe(true);
+    });
+    it("detects xterm-compatible with COLORTERM truecolor", () => {
+        Object.defineProperty(process, "platform", { value: "linux" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ TMUX: undefined, TERM: "xterm-256color", TERM_PROGRAM: undefined, ITERM_SESSION_ID: undefined, COLORTERM: "truecolor" });
+        const caps = detectTerminal();
+        expect(caps.truecolor).toBe(true);
+        expect(caps.color256).toBe(true);
+    });
+    it("detects dumb terminal with minimal caps", () => {
+        Object.defineProperty(process, "platform", { value: "linux" });
+        Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+        setEnv({ TMUX: undefined, TERM: "dumb", TERM_PROGRAM: undefined, ITERM_SESSION_ID: undefined });
+        const caps = detectTerminal();
+        expect(caps.name).toBe("dumb");
+        expect(caps.mouse).toBe(false);
+        expect(caps.alternateScreen).toBe(false);
+    });
+});
+// ═══════════════════════════════════════════════════════════════════
+// esc.ts — environment-aware init/restore sequences
+// ═══════════════════════════════════════════════════════════════════
+describe("esc environment-aware sequences", () => {
+    /** Helper to build a TerminalCaps with overrides. */
+    function makeCaps(overrides = {}) {
+        return {
+            isTTY: true,
+            alternateScreen: true,
+            bracketedPaste: true,
+            mouse: true,
+            sgrMouse: true,
+            truecolor: true,
+            color256: true,
+            name: "test",
+            ...overrides,
+        };
+    }
+    describe("mouseOn / mouseOff", () => {
+        it("returns full mouse sequence when SGR is supported", () => {
+            const caps = makeCaps({ sgrMouse: true });
+            expect(esc.mouseOn(caps)).toBe(esc.mouseTrackingOn);
+            expect(esc.mouseOff(caps)).toBe(esc.mouseTrackingOff);
+        });
+        it("returns minimal mouse sequence when SGR is not supported", () => {
+            const caps = makeCaps({ sgrMouse: false });
+            const on = esc.mouseOn(caps);
+            expect(on).toContain("?1000h");
+            expect(on).toContain("?1003h");
+            expect(on).not.toContain("?1006h");
+            expect(on).not.toContain("?1015h");
+        });
+        it("returns empty string when mouse is not supported", () => {
+            const caps = makeCaps({ mouse: false });
+            expect(esc.mouseOn(caps)).toBe("");
+            expect(esc.mouseOff(caps)).toBe("");
+        });
+    });
+    describe("initSequence", () => {
+        it("includes all features for a full-caps terminal", () => {
+            const caps = makeCaps();
+            const seq = esc.initSequence(caps, { alternateScreen: true, mouse: true });
+            expect(seq).toContain(esc.alternateScreenOn);
+            expect(seq).toContain(esc.hideCursor);
+            expect(seq).toContain(esc.bracketedPasteOn);
+            expect(seq).toContain(esc.mouseTrackingOn);
+            expect(seq).toContain(esc.clearScreen);
+        });
+        it("skips alternate screen when not supported", () => {
+            const caps = makeCaps({ alternateScreen: false });
+            const seq = esc.initSequence(caps, { alternateScreen: true, mouse: false });
+            expect(seq).not.toContain(esc.alternateScreenOn);
+        });
+        it("skips alternate screen when app opts out", () => {
+            const caps = makeCaps();
+            const seq = esc.initSequence(caps, { alternateScreen: false, mouse: false });
+            expect(seq).not.toContain(esc.alternateScreenOn);
+        });
+        it("skips bracketed paste when not supported", () => {
+            const caps = makeCaps({ bracketedPaste: false });
+            const seq = esc.initSequence(caps, { alternateScreen: false, mouse: false });
+            expect(seq).not.toContain(esc.bracketedPasteOn);
+        });
+        it("skips mouse when app opts out even if caps support it", () => {
+            const caps = makeCaps();
+            const seq = esc.initSequence(caps, { alternateScreen: false, mouse: false });
+            expect(seq).not.toContain("?1000h");
+        });
+        it("returns empty string for non-TTY", () => {
+            const caps = makeCaps({ isTTY: false });
+            const seq = esc.initSequence(caps, { alternateScreen: true, mouse: true });
+            expect(seq).toBe("");
+        });
+    });
+    describe("restoreSequence", () => {
+        it("includes all restore features for a full-caps terminal", () => {
+            const caps = makeCaps();
+            const seq = esc.restoreSequence(caps, { alternateScreen: true, mouse: true });
+            expect(seq).toContain(esc.reset);
+            expect(seq).toContain(esc.mouseTrackingOff);
+            expect(seq).toContain(esc.bracketedPasteOff);
+            expect(seq).toContain(esc.showCursor);
+            expect(seq).toContain(esc.alternateScreenOff);
+        });
+        it("mirrors initSequence — skips what init skipped", () => {
+            const caps = makeCaps({ bracketedPaste: false, alternateScreen: false });
+            const seq = esc.restoreSequence(caps, { alternateScreen: true, mouse: false });
+            expect(seq).not.toContain(esc.bracketedPasteOff);
+            expect(seq).not.toContain(esc.alternateScreenOff);
+            expect(seq).not.toContain(esc.mouseTrackingOff);
+        });
+        it("returns empty string for non-TTY", () => {
+            const caps = makeCaps({ isTTY: false });
+            const seq = esc.restoreSequence(caps, { alternateScreen: true, mouse: true });
+            expect(seq).toBe("");
+        });
+    });
+});

package/dist/__tests__/input.test.js

@@ -28,6 +28,9 @@ function collectEvents(data) {
     processor.destroy();
     return collected;
 }
+function x10Seq(cb, x, y) {
+    return `\x1b[M${String.fromCharCode(cb + 32)}${String.fromCharCode(x + 32)}${String.fromCharCode(y + 32)}`;
+}
 // =====================================================================
 // EscapeMatcher
 // =====================================================================
@@ -675,6 +678,137 @@ describe("MouseMatcher", () => {
             expect(results[results.length - 1]).toBe(MatchResult.Complete);
         });
     });
+    // ── URXVT sequences ────────────────────────────────────────────────
+    describe("URXVT sequences", () => {
+        it("parses URXVT left press at (9,19) from \\x1b[0;10;20M", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[0;10;20M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            expect(ev).not.toBeNull();
+            expect(ev.type).toBe("mouse");
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("left");
+                expect(ev.event.type).toBe("press");
+                expect(ev.event.x).toBe(9);
+                expect(ev.event.y).toBe(19);
+            }
+        });
+        it("parses URXVT right press", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[2;5;5M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("right");
+                expect(ev.event.type).toBe("press");
+                expect(ev.event.x).toBe(4);
+                expect(ev.event.y).toBe(4);
+            }
+        });
+        it("parses URXVT release (button bits = 3)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[3;10;20M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("none");
+                expect(ev.event.type).toBe("release");
+            }
+        });
+        it("parses URXVT wheel up (cb=64)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[64;5;5M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("none");
+                expect(ev.event.type).toBe("wheelup");
+            }
+        });
+        it("parses URXVT wheel down (cb=65)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[65;5;5M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("none");
+                expect(ev.event.type).toBe("wheeldown");
+            }
+        });
+        it("parses URXVT motion with left button (cb=32)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[32;10;10M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.type).toBe("move");
+                expect(ev.event.button).toBe("left");
+            }
+        });
+        it("parses URXVT shift+left press (cb=4)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[4;1;1M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("left");
+                expect(ev.event.type).toBe("press");
+                expect(ev.event.shift).toBe(true);
+                expect(ev.event.ctrl).toBe(false);
+                expect(ev.event.alt).toBe(false);
+            }
+        });
+        it("parses URXVT with large coordinates (beyond X10 range)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[0;300;200M")).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("left");
+                expect(ev.event.type).toBe("press");
+                expect(ev.event.x).toBe(299);
+                expect(ev.event.y).toBe(199);
+            }
+        });
+        it("rejects URXVT with wrong param count (2 params)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[0;10M")).toBe(MatchResult.NoMatch);
+        });
+        it("rejects URXVT with wrong param count (4 params)", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, "\x1b[0;10;20;30M")).toBe(MatchResult.NoMatch);
+        });
+    });
+    describe("classic X10 sequences", () => {
+        it("parses left press from classic CSI M encoding", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, x10Seq(0, 10, 20))).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            expect(ev).not.toBeNull();
+            expect(ev.type).toBe("mouse");
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("left");
+                expect(ev.event.type).toBe("press");
+                expect(ev.event.x).toBe(9);
+                expect(ev.event.y).toBe(19);
+            }
+        });
+        it("parses release from classic CSI M encoding", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, x10Seq(3, 10, 20))).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            expect(ev).not.toBeNull();
+            expect(ev.type).toBe("mouse");
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("none");
+                expect(ev.event.type).toBe("release");
+            }
+        });
+        it("parses wheel down from classic CSI M encoding", () => {
+            matcher = new MouseMatcher();
+            expect(feedString(matcher, x10Seq(65, 5, 5))).toBe(MatchResult.Complete);
+            const ev = matcher.flush();
+            expect(ev).not.toBeNull();
+            expect(ev.type).toBe("mouse");
+            if (ev.type === "mouse") {
+                expect(ev.event.button).toBe("none");
+                expect(ev.event.type).toBe("wheeldown");
+            }
+        });
+    });
 });
 // =====================================================================
 // TextMatcher
@@ -853,6 +987,29 @@ describe("InputProcessor", () => {
             expect(events[0].event.y).toBe(0);
         }
     });
+    it("URXVT mouse sequences are recognized through parallel matching", () => {
+        // URXVT: \x1b[0;5;10M — left press at (4,9)
+        const events = collectEvents("\x1b[0;5;10M");
+        expect(events).toHaveLength(1);
+        expect(events[0].type).toBe("mouse");
+        if (events[0].type === "mouse") {
+            expect(events[0].event.button).toBe("left");
+            expect(events[0].event.type).toBe("press");
+            expect(events[0].event.x).toBe(4);
+            expect(events[0].event.y).toBe(9);
+        }
+    });
+    it("classic X10 mouse sequences are recognized through parallel matching", () => {
+        const events = collectEvents(x10Seq(0, 1, 1));
+        expect(events).toHaveLength(1);
+        expect(events[0].type).toBe("mouse");
+        if (events[0].type === "mouse") {
+            expect(events[0].event.button).toBe("left");
+            expect(events[0].event.type).toBe("press");
+            expect(events[0].event.x).toBe(0);
+            expect(events[0].event.y).toBe(0);
+        }
+    });
     it("handles text after a paste sequence", () => {
         const events = collectEvents("\x1b[200~pasted\x1b[201~after");
         expect(events).toHaveLength(6); // 1 paste + 5 chars

package/dist/ansi/esc.d.ts

@@ -2,6 +2,7 @@
  * ANSI escape sequence constants and builder functions.
  * All functions return raw escape strings — nothing is written to stdout.
  */
+import type { TerminalCaps } from "./terminal-env.js";
 export declare const reset = "\u001B[0m";
 export declare const bold = "\u001B[1m";
 export declare const dim = "\u001B[2m";
@@ -53,9 +54,52 @@ export declare const eraseLine = "\u001B[2K";
 export declare const bracketedPasteOn = "\u001B[?2004h";
 /** Disable bracketed paste mode. */
 export declare const bracketedPasteOff = "\u001B[?2004l";
-/** Enable SGR mouse tracking (any-event tracking + SGR extended coordinates). */
-export declare const mouseTrackingOn = "\u001B[?1003h\u001B[?1006h";
-/** Disable SGR mouse tracking. */
-export declare const mouseTrackingOff = "\u001B[?1006l\u001B[?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 declare const mouseTrackingOn = "\u001B[?1000h\u001B[?1003h\u001B[?1005h\u001B[?1006h\u001B[?1015h\u001B[?1016h";
+/**
+ * Disable all mouse tracking modes (reverse order of enable).
+ */
+export declare const mouseTrackingOff = "\u001B[?1016l\u001B[?1015l\u001B[?1006l\u001B[?1005l\u001B[?1003l\u001B[?1000l";
 /** Set the terminal window title. */
 export declare function setTitle(title: string): string;
+/**
+ * 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 declare function mouseOn(caps: TerminalCaps): string;
+/** Matching disable sequence for mouseOn(). */
+export declare function mouseOff(caps: TerminalCaps): string;
+/**
+ * Build the full terminal preparation sequence for the given environment.
+ *
+ * @param caps  - Detected terminal capabilities
+ * @param opts  - Which optional features the app requested
+ */
+export declare function initSequence(caps: TerminalCaps, opts: {
+    alternateScreen: boolean;
+    mouse: boolean;
+}): string;
+/**
+ * Build the full terminal restore sequence (mirror of initSequence).
+ */
+export declare function restoreSequence(caps: TerminalCaps, opts: {
+    alternateScreen: boolean;
+    mouse: boolean;
+}): string;

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;