@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tui/keys.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 键解析（设计 §12.3）。[B4]
+ *
+ * 支持：C0 控制字符（Ctrl 组合）、CSI / SS3 光标与功能键、xterm 修饰键参数（`ESC[1;5A`）、
+ * `CSI u`（`ESC[13;2u`）与 modifyOtherKeys（`ESC[27;2;13~`）两种扩展形式、Alt 前缀（`ESC x`）。
+ * **不查询 Kitty 键盘协议**（tmux 下回包会污染输入）；只被动解析终端自发的扩展序列。
+ *
+ * KeyId 形如 `ctrl+shift+up`：修饰键按 ctrl → alt → shift 排序，键名小写；
+ * 可打印字符的键名就是字符本身（`a`、`/`、`中`），空格为 `space`。
+ */
+export interface KeyEvent {
+    /** 键名：`enter`、`up`、`f5`、`a`、`中` …… */
+    readonly name: string;
+    readonly ctrl: boolean;
+    readonly alt: boolean;
+    readonly shift: boolean;
+    /** 规范化 KeyId：修饰键 + 键名。 */
+    readonly id: string;
+    /** 产生可打印文本时为该文本（不含修饰键组合）。 */
+    readonly text?: string;
+}
+export declare const PASTE_START = "\u001B[200~";
+export declare const PASTE_END = "\u001B[201~";
+/**
+ * 解析一个完整的键序列（StdinBuffer 已按序列切分）。无法识别返回 undefined。
+ * 多个字符的纯文本（例如非括号粘贴）不算单个键，同样返回 undefined。
+ */
+export declare function parseKey(data: string): KeyEvent | undefined;
+/** 规范化 KeyId 字符串：修饰键重排、别名（return→enter、esc→escape、del→delete）。 */
+export declare function normalizeKeyId(id: string): string;
+/** 数据是否匹配给定 KeyId（`shift+a` 与大写 `A` 视为同一键）。 */
+export declare function matchesKey(data: string, keyId: string): boolean;
+/** 是否为括号粘贴包裹的数据（StdinBuffer 产出的一次 paste 事件）。 */
+export declare function isPasteData(data: string): boolean;
+/** 取出括号粘贴的正文。 */
+export declare function unwrapPaste(data: string): string;
+/** 数据是否为可直接插入的文本（不含控制字符与转义序列）。 */
+export declare function isPrintableText(data: string): boolean;

package/dist/tui/keys.js

@@ -0,0 +1,275 @@
+/**
+ * 键解析（设计 §12.3）。[B4]
+ *
+ * 支持：C0 控制字符（Ctrl 组合）、CSI / SS3 光标与功能键、xterm 修饰键参数（`ESC[1;5A`）、
+ * `CSI u`（`ESC[13;2u`）与 modifyOtherKeys（`ESC[27;2;13~`）两种扩展形式、Alt 前缀（`ESC x`）。
+ * **不查询 Kitty 键盘协议**（tmux 下回包会污染输入）；只被动解析终端自发的扩展序列。
+ *
+ * KeyId 形如 `ctrl+shift+up`：修饰键按 ctrl → alt → shift 排序，键名小写；
+ * 可打印字符的键名就是字符本身（`a`、`/`、`中`），空格为 `space`。
+ */
+export const PASTE_START = "\x1b[200~";
+export const PASTE_END = "\x1b[201~";
+const NO_MODS = { ctrl: false, alt: false, shift: false };
+function makeKey(name, mods, text) {
+    const parts = [];
+    if (mods.ctrl)
+        parts.push("ctrl");
+    if (mods.alt)
+        parts.push("alt");
+    if (mods.shift)
+        parts.push("shift");
+    parts.push(name);
+    const base = { name, ctrl: mods.ctrl, alt: mods.alt, shift: mods.shift, id: parts.join("+") };
+    return text === undefined ? base : { ...base, text };
+}
+/** xterm 修饰参数：值 = 1 + 位掩码（1 shift，2 alt，4 ctrl，8 meta→按 alt 处理）。 */
+function modsFromParam(param) {
+    if (param === undefined || !Number.isFinite(param) || param < 1)
+        return NO_MODS;
+    const bits = param - 1;
+    return {
+        shift: (bits & 1) !== 0,
+        alt: (bits & 2) !== 0 || (bits & 8) !== 0,
+        ctrl: (bits & 4) !== 0,
+    };
+}
+const CSI_LETTER = {
+    A: "up",
+    B: "down",
+    C: "right",
+    D: "left",
+    H: "home",
+    F: "end",
+    E: "clear",
+    P: "f1",
+    Q: "f2",
+    R: "f3",
+    S: "f4",
+};
+const CSI_TILDE = {
+    1: "home",
+    2: "insert",
+    3: "delete",
+    4: "end",
+    5: "pageup",
+    6: "pagedown",
+    7: "home",
+    8: "end",
+    11: "f1",
+    12: "f2",
+    13: "f3",
+    14: "f4",
+    15: "f5",
+    17: "f6",
+    18: "f7",
+    19: "f8",
+    20: "f9",
+    21: "f10",
+    23: "f11",
+    24: "f12",
+};
+/** 码点（CSI u / modifyOtherKeys）→ 键名。 */
+function nameFromCodePoint(cp) {
+    switch (cp) {
+        case 13:
+            return "enter";
+        case 9:
+            return "tab";
+        case 27:
+            return "escape";
+        case 127:
+        case 8:
+            return "backspace";
+        case 32:
+            return "space";
+        default:
+            if (cp < 32)
+                return undefined;
+            return String.fromCodePoint(cp).toLowerCase();
+    }
+}
+function parseCsi(body, final) {
+    // body：ESC[ 与终止字节之间的参数部分
+    if (body.startsWith("<") || body.startsWith("?") || body.startsWith(">"))
+        return undefined;
+    const params = body.split(";").map((p) => (p === "" ? undefined : Number(p.split(":")[0])));
+    if (final === "u") {
+        const cp = params[0];
+        if (cp === undefined)
+            return undefined;
+        const name = nameFromCodePoint(cp);
+        return name === undefined ? undefined : makeKey(name, modsFromParam(params[1]));
+    }
+    if (final === "~") {
+        const first = params[0];
+        if (first === 27 && params.length >= 3) {
+            // modifyOtherKeys：ESC[27;<mod>;<code>~
+            const name = nameFromCodePoint(params[2] ?? -1);
+            return name === undefined ? undefined : makeKey(name, modsFromParam(params[1]));
+        }
+        if (first === 200 || first === 201)
+            return undefined;
+        const name = first === undefined ? undefined : CSI_TILDE[first];
+        return name === undefined ? undefined : makeKey(name, modsFromParam(params[1]));
+    }
+    if (final === "Z")
+        return makeKey("tab", { ...modsFromParam(params[1]), shift: true });
+    const name = CSI_LETTER[final];
+    if (name === undefined)
+        return undefined;
+    return makeKey(name, modsFromParam(params.length > 1 ? params[1] : undefined));
+}
+const SS3 = {
+    A: "up",
+    B: "down",
+    C: "right",
+    D: "left",
+    H: "home",
+    F: "end",
+    P: "f1",
+    Q: "f2",
+    R: "f3",
+    S: "f4",
+    M: "enter",
+};
+function parseControl(code) {
+    switch (code) {
+        case 0x0d:
+            return makeKey("enter", NO_MODS);
+        case 0x0a:
+            return makeKey("j", { ...NO_MODS, ctrl: true });
+        case 0x09:
+            return makeKey("tab", NO_MODS);
+        case 0x7f:
+        case 0x08:
+            return makeKey("backspace", NO_MODS);
+        case 0x1b:
+            return makeKey("escape", NO_MODS);
+        case 0x00:
+            return makeKey("space", { ...NO_MODS, ctrl: true });
+        case 0x1c:
+            return makeKey("\\", { ...NO_MODS, ctrl: true });
+        case 0x1d:
+            return makeKey("]", { ...NO_MODS, ctrl: true });
+        case 0x1e:
+            return makeKey("^", { ...NO_MODS, ctrl: true });
+        case 0x1f:
+            return makeKey("-", { ...NO_MODS, ctrl: true });
+        default:
+            if (code >= 0x01 && code <= 0x1a) {
+                return makeKey(String.fromCharCode(code + 0x60), { ...NO_MODS, ctrl: true });
+            }
+            return undefined;
+    }
+}
+function withAlt(key) {
+    return makeKey(key.name, { ctrl: key.ctrl, alt: true, shift: key.shift });
+}
+function parsePrintable(data) {
+    const cp = data.codePointAt(0);
+    if (cp === undefined || cp < 0x20 || cp === 0x7f)
+        return undefined;
+    if (data === " ")
+        return makeKey("space", NO_MODS, " ");
+    const lower = data.toLowerCase();
+    const shift = lower !== data && data.length === 1;
+    return makeKey(lower, { ...NO_MODS, shift }, data);
+}
+/**
+ * 解析一个完整的键序列（StdinBuffer 已按序列切分）。无法识别返回 undefined。
+ * 多个字符的纯文本（例如非括号粘贴）不算单个键，同样返回 undefined。
+ */
+export function parseKey(data) {
+    if (data.length === 0)
+        return undefined;
+    const first = data.charCodeAt(0);
+    if (first !== 0x1b) {
+        if (data.length === 1)
+            return parseControl(first) ?? parsePrintable(data);
+        // 单个非 BMP 字符或组合字素
+        if ([...data].length === 1 || isSingleGrapheme(data))
+            return parsePrintable(data);
+        return undefined;
+    }
+    if (data.length === 1)
+        return makeKey("escape", NO_MODS);
+    const second = data[1];
+    if (second === "[") {
+        const final = data[data.length - 1];
+        if (data.length >= 3)
+            return parseCsi(data.slice(2, -1), final);
+        return makeKey("[", { ...NO_MODS, alt: true }, undefined);
+    }
+    if (second === "O" && data.length === 3) {
+        const name = SS3[data[2]];
+        return name === undefined ? undefined : makeKey(name, NO_MODS);
+    }
+    // Alt 前缀：ESC + 另一序列
+    const rest = data.slice(1);
+    const inner = parseKey(rest);
+    if (inner === undefined)
+        return undefined;
+    return withAlt(inner);
+}
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+function isSingleGrapheme(data) {
+    let count = 0;
+    for (const _ of graphemeSegmenter.segment(data)) {
+        count++;
+        if (count > 1)
+            return false;
+    }
+    return count === 1;
+}
+/** 规范化 KeyId 字符串：修饰键重排、别名（return→enter、esc→escape、del→delete）。 */
+export function normalizeKeyId(id) {
+    const parts = id.toLowerCase().split("+");
+    // "ctrl++" 这类以 + 为键名的写法
+    if (id.endsWith("++")) {
+        parts.splice(parts.length - 2, 2, "+");
+    }
+    const name = parts.pop() ?? "";
+    const mods = new Set(parts.map((p) => (p === "option" || p === "meta" ? "alt" : p)));
+    const alias = {
+        return: "enter",
+        esc: "escape",
+        del: "delete",
+        bs: "backspace",
+        pgup: "pageup",
+        pgdn: "pagedown",
+        " ": "space",
+    };
+    const finalName = alias[name] ?? name;
+    return makeKey(finalName, {
+        ctrl: mods.has("ctrl"),
+        alt: mods.has("alt"),
+        shift: mods.has("shift"),
+    }).id;
+}
+/** 数据是否匹配给定 KeyId（`shift+a` 与大写 `A` 视为同一键）。 */
+export function matchesKey(data, keyId) {
+    const key = parseKey(data);
+    if (key === undefined)
+        return false;
+    return key.id === normalizeKeyId(keyId);
+}
+/** 是否为括号粘贴包裹的数据（StdinBuffer 产出的一次 paste 事件）。 */
+export function isPasteData(data) {
+    return data.startsWith(PASTE_START) && data.endsWith(PASTE_END);
+}
+/** 取出括号粘贴的正文。 */
+export function unwrapPaste(data) {
+    return data.slice(PASTE_START.length, data.length - PASTE_END.length);
+}
+/** 数据是否为可直接插入的文本（不含控制字符与转义序列）。 */
+export function isPrintableText(data) {
+    if (data.length === 0)
+        return false;
+    for (let i = 0; i < data.length; i++) {
+        const c = data.charCodeAt(i);
+        if (c < 0x20 || c === 0x7f)
+            return false;
+    }
+    return true;
+}

package/dist/tui/stdin-buffer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 标准输入缓冲（设计 §12.3）。[B4]
+ *
+ * - 把分片到达的原始输入切成「一个键一个序列」：完整的 CSI / SS3 / OSC / APC / DCS、
+ *   Alt 前缀（`ESC x`、`ESC ESC [ A`）、单个字素簇。
+ * - 括号粘贴 `ESC[200~ … ESC[201~` 跨任意多个 data 块累积，结束时作为**一次** paste 事件发出；
+ *   粘贴内部的 `\r` / `\n` / ESC 都是数据，不解析为键。
+ * - 块末尾的不完整转义序列先挂起；在 `AMA_TUI_ESC_TIMEOUT` 毫秒内没有后续数据就原样发出
+ *   （孤立 ESC 即 Escape 键）。缺省：SSH / tmux 下 100 ms，本地 10 ms。
+ */
+export interface StdinBufferOptions {
+    /** 每个完整键序列。 */
+    onData(sequence: string): void;
+    /** 括号粘贴正文（不含 200~/201~ 包裹）。 */
+    onPaste(text: string): void;
+    /** 孤立 ESC 判定超时（ms）；缺省见 `defaultEscTimeout()`。 */
+    escTimeoutMs?: number;
+}
+/** 读环境：`AMA_TUI_ESC_TIMEOUT` 优先；否则 SSH / tmux 100 ms，本地 10 ms。 */
+export declare function defaultEscTimeout(env?: NodeJS.ProcessEnv): number;
+export declare class StdinBuffer {
+    private readonly options;
+    private buffer;
+    private pasteBuffer;
+    private timer;
+    private readonly escTimeoutMs;
+    private destroyed;
+    constructor(options: StdinBufferOptions);
+    /** 是否处于括号粘贴中（等待 ESC[201~）。 */
+    get inPaste(): boolean;
+    process(chunk: string | Buffer): void;
+    /** 立即发出所有挂起数据（超时或停止时调用）。 */
+    flush(): void;
+    destroy(): void;
+    private clearTimer;
+    private drain;
+    /** 粘贴模式：找结束标记；标记可能被切在块边界上，保留可能的前缀等下一块。 */
+    private drainPaste;
+    /** 非转义数据：一个字素簇为一个序列（控制字符单独成序列）。 */
+    private nextTextLength;
+}

package/dist/tui/stdin-buffer.js

@@ -0,0 +1,206 @@
+/**
+ * 标准输入缓冲（设计 §12.3）。[B4]
+ *
+ * - 把分片到达的原始输入切成「一个键一个序列」：完整的 CSI / SS3 / OSC / APC / DCS、
+ *   Alt 前缀（`ESC x`、`ESC ESC [ A`）、单个字素簇。
+ * - 括号粘贴 `ESC[200~ … ESC[201~` 跨任意多个 data 块累积，结束时作为**一次** paste 事件发出；
+ *   粘贴内部的 `\r` / `\n` / ESC 都是数据，不解析为键。
+ * - 块末尾的不完整转义序列先挂起；在 `AMA_TUI_ESC_TIMEOUT` 毫秒内没有后续数据就原样发出
+ *   （孤立 ESC 即 Escape 键）。缺省：SSH / tmux 下 100 ms，本地 10 ms。
+ */
+import { PASTE_END, PASTE_START } from "./keys.js";
+/** 读环境：`AMA_TUI_ESC_TIMEOUT` 优先；否则 SSH / tmux 100 ms，本地 10 ms。 */
+export function defaultEscTimeout(env = process.env) {
+    const raw = env["AMA_TUI_ESC_TIMEOUT"];
+    if (raw !== undefined && raw.trim() !== "") {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    if (env["SSH_CONNECTION"] || env["SSH_TTY"] || env["SSH_CLIENT"] || env["TMUX"])
+        return 100;
+    return 10;
+}
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** 从 0 开始扫描一个转义序列（buf[0] === ESC）。 */
+function scanEscape(buf) {
+    if (buf.length === 1)
+        return { kind: "incomplete" };
+    const second = buf[1];
+    if (second === "[") {
+        for (let j = 2; j < buf.length; j++) {
+            const c = buf.charCodeAt(j);
+            if (c >= 0x40 && c <= 0x7e) {
+                const seq = buf.slice(0, j + 1);
+                if (seq === PASTE_START)
+                    return { kind: "paste-start", length: j + 1 };
+                return { kind: "complete", length: j + 1 };
+            }
+            // CSI 参数 / 中间字节之外的字符：序列被打断，只取 ESC[
+            if (c < 0x20 || c > 0x7e)
+                return { kind: "complete", length: 2 };
+        }
+        return { kind: "incomplete" };
+    }
+    if (second === "O") {
+        if (buf.length < 3)
+            return { kind: "incomplete" };
+        return { kind: "complete", length: 3 };
+    }
+    if (second === "]" || second === "_" || second === "P" || second === "^" || second === "X") {
+        for (let j = 2; j < buf.length; j++) {
+            const c = buf.charCodeAt(j);
+            if (c === 0x07)
+                return { kind: "complete", length: j + 1 };
+            if (c === 0x1b) {
+                if (j + 1 >= buf.length)
+                    return { kind: "incomplete" };
+                if (buf[j + 1] === "\\")
+                    return { kind: "complete", length: j + 2 };
+            }
+        }
+        return { kind: "incomplete" };
+    }
+    if (second === "\x1b") {
+        // ESC ESC [ A：Alt + 转义序列；ESC ESC 单独出现为 Alt+Escape
+        if (buf.length === 2)
+            return { kind: "incomplete" };
+        const inner = scanEscape(buf.slice(1));
+        if (inner.kind === "complete")
+            return { kind: "complete", length: inner.length + 1 };
+        if (inner.kind === "paste-start")
+            return { kind: "complete", length: 2 };
+        return inner;
+    }
+    // Alt 前缀 + 单个字素
+    const rest = buf.slice(1);
+    const first = segmenter.segment(rest.slice(0, 64))[Symbol.iterator]().next();
+    const segment = first.done ? rest[0] : first.value.segment;
+    return { kind: "complete", length: 1 + segment.length };
+}
+export class StdinBuffer {
+    options;
+    buffer = "";
+    pasteBuffer = null;
+    timer = null;
+    escTimeoutMs;
+    destroyed = false;
+    constructor(options) {
+        this.options = options;
+        this.escTimeoutMs = options.escTimeoutMs ?? defaultEscTimeout();
+    }
+    /** 是否处于括号粘贴中（等待 ESC[201~）。 */
+    get inPaste() {
+        return this.pasteBuffer !== null;
+    }
+    process(chunk) {
+        if (this.destroyed)
+            return;
+        this.clearTimer();
+        this.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        this.drain();
+    }
+    /** 立即发出所有挂起数据（超时或停止时调用）。 */
+    flush() {
+        this.clearTimer();
+        if (this.pasteBuffer !== null) {
+            // 粘贴结束标记一直没到：按已收到的正文发出，不丢数据
+            const text = this.pasteBuffer + this.buffer;
+            this.pasteBuffer = null;
+            this.buffer = "";
+            this.options.onPaste(text);
+            return;
+        }
+        if (this.buffer.length > 0) {
+            const pending = this.buffer;
+            this.buffer = "";
+            this.options.onData(pending);
+        }
+    }
+    destroy() {
+        this.clearTimer();
+        this.destroyed = true;
+        this.buffer = "";
+        this.pasteBuffer = null;
+    }
+    clearTimer() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    drain() {
+        while (this.buffer.length > 0) {
+            if (this.pasteBuffer !== null) {
+                if (!this.drainPaste())
+                    return;
+                continue;
+            }
+            const buf = this.buffer;
+            if (buf.charCodeAt(0) === 0x1b) {
+                const scan = scanEscape(buf);
+                if (scan.kind === "incomplete") {
+                    this.timer = setTimeout(() => {
+                        this.timer = null;
+                        this.flush();
+                    }, this.escTimeoutMs);
+                    return;
+                }
+                this.buffer = buf.slice(scan.length);
+                if (scan.kind === "paste-start")
+                    this.pasteBuffer = "";
+                else
+                    this.options.onData(buf.slice(0, scan.length));
+                continue;
+            }
+            const length = this.nextTextLength(buf);
+            this.buffer = buf.slice(length);
+            this.options.onData(buf.slice(0, length));
+        }
+    }
+    /** 粘贴模式：找结束标记；标记可能被切在块边界上，保留可能的前缀等下一块。 */
+    drainPaste() {
+        const combined = this.pasteBuffer + this.buffer;
+        const end = combined.indexOf(PASTE_END);
+        if (end === -1) {
+            const keep = partialSuffixLength(combined, PASTE_END);
+            this.pasteBuffer = combined.slice(0, combined.length - keep);
+            this.buffer = combined.slice(combined.length - keep);
+            // buffer 里只剩可能的结束标记前缀：等下一块
+            return false;
+        }
+        const text = combined.slice(0, end);
+        this.pasteBuffer = null;
+        this.buffer = combined.slice(end + PASTE_END.length);
+        this.options.onPaste(text);
+        return true;
+    }
+    /** 非转义数据：一个字素簇为一个序列（控制字符单独成序列）。 */
+    nextTextLength(buf) {
+        const c = buf.charCodeAt(0);
+        if (c < 0x20 || c === 0x7f)
+            return 1;
+        const first = segmenter.segment(buf.slice(0, 64))[Symbol.iterator]().next();
+        if (first.done)
+            return 1;
+        // 字素簇不能吞掉后面的 ESC 或控制字符
+        let len = first.value.segment.length;
+        for (let i = 1; i < len; i++) {
+            const cc = buf.charCodeAt(i);
+            if (cc < 0x20 || cc === 0x7f) {
+                len = i;
+                break;
+            }
+        }
+        return len;
+    }
+}
+/** s 的后缀与 marker 的前缀最长重合长度（< marker.length）。 */
+function partialSuffixLength(s, marker) {
+    const max = Math.min(s.length, marker.length - 1);
+    for (let len = max; len > 0; len--) {
+        if (marker.startsWith(s.slice(s.length - len)))
+            return len;
+    }
+    return 0;
+}

package/dist/tui/terminal.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 终端抽象（设计 §12.2、§12.3、§12.8）。[B4]
+ *
+ * - `Terminal`：TUI 只依赖这个接口——尺寸、写入、输入回调、尺寸变化回调。
+ * - `ProcessTerminal`：真实 TTY。raw 模式、括号粘贴 `?2004`、stdout `resize`（SIGWINCH）；
+ *   输入经 `StdinBuffer` 切分，括号粘贴以 `ESC[200~正文ESC[201~` 一次交给 onInput。
+ *   停止时关括号粘贴、显示光标、恢复 cooked 模式；**不清屏**（回滚保留对话）。
+ * - `MemoryTerminal`：测试用。记录每次写入，并用 `VirtualScreen` 还原屏幕与回滚。
+ */
+import { VirtualScreen } from "./vt-screen.js";
+export interface Terminal {
+    readonly columns: number;
+    readonly rows: number;
+    /** 进入 raw 模式、开括号粘贴、开始投递输入与尺寸变化。 */
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    /** 关括号粘贴、恢复 cooked 模式、停止投递；不清屏。 */
+    stop(): void;
+    write(data: string): void;
+}
+export declare const BRACKETED_PASTE_ON = "\u001B[?2004h";
+export declare const BRACKETED_PASTE_OFF = "\u001B[?2004l";
+export declare const SHOW_CURSOR = "\u001B[?25h";
+export declare const HIDE_CURSOR = "\u001B[?25l";
+export interface ProcessTerminalOptions {
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+    escTimeoutMs?: number;
+}
+export declare class ProcessTerminal implements Terminal {
+    private readonly stdin;
+    private readonly stdout;
+    private readonly escTimeoutMs;
+    private buffer;
+    private wasRaw;
+    private dataListener;
+    private resizeListener;
+    constructor(options?: ProcessTerminalOptions);
+    get columns(): number;
+    get rows(): number;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    write(data: string): void;
+}
+export interface MemoryTerminalOptions {
+    columns?: number;
+    rows?: number;
+    /** 测试里孤立 ESC 的超时；缺省 10 ms。 */
+    escTimeoutMs?: number;
+}
+export declare class MemoryTerminal implements Terminal {
+    readonly screen: VirtualScreen;
+    /** 每次 write 的原始数据（按顺序）。 */
+    readonly writes: string[];
+    started: boolean;
+    rawMode: boolean;
+    private onInput;
+    private onResize;
+    private buffer;
+    constructor(options?: MemoryTerminalOptions);
+    get columns(): number;
+    get rows(): number;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    write(data: string): void;
+    /** 模拟一个 stdin data 块（经 StdinBuffer 切分，与真实终端同路径）。 */
+    sendInput(chunk: string): void;
+    /** 立即发出挂起的不完整序列（替代等待 ESC 超时）。 */
+    flushInput(): void;
+    /** 改尺寸并触发 resize 回调（模拟 SIGWINCH）。 */
+    resize(columns: number, rows: number): void;
+    /** 全部写入拼成一个字符串。 */
+    get output(): string;
+    /** 取走并清空写入记录（便于断言「这一帧写了什么」）。 */
+    takeWrites(): string;
+    /** 可见屏幕各行（去掉右侧空白）。 */
+    viewport(): string[];
+    /** 回滚 + 屏幕（去掉底部空行）。 */
+    transcript(): string[];
+}