@armadra/agent 0.0.0-stage → 0.3.0

package/dist/tui/terminal.js

@@ -0,0 +1,153 @@
+/**
+ * 终端抽象（设计 §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 { PASTE_END, PASTE_START } from "./keys.js";
+import { StdinBuffer } from "./stdin-buffer.js";
+import { VirtualScreen } from "./vt-screen.js";
+export const BRACKETED_PASTE_ON = "\x1b[?2004h";
+export const BRACKETED_PASTE_OFF = "\x1b[?2004l";
+export const SHOW_CURSOR = "\x1b[?25h";
+export const HIDE_CURSOR = "\x1b[?25l";
+export class ProcessTerminal {
+    stdin;
+    stdout;
+    escTimeoutMs;
+    buffer = null;
+    wasRaw = false;
+    dataListener = null;
+    resizeListener = null;
+    constructor(options = {}) {
+        this.stdin = options.stdin ?? process.stdin;
+        this.stdout = options.stdout ?? process.stdout;
+        this.escTimeoutMs = options.escTimeoutMs;
+    }
+    get columns() {
+        return this.stdout.columns || 80;
+    }
+    get rows() {
+        return this.stdout.rows || 24;
+    }
+    start(onInput, onResize) {
+        const bufferOptions = {
+            onData: onInput,
+            onPaste: (text) => onInput(PASTE_START + text + PASTE_END),
+        };
+        this.buffer = new StdinBuffer(this.escTimeoutMs === undefined
+            ? bufferOptions
+            : { ...bufferOptions, escTimeoutMs: this.escTimeoutMs });
+        if (this.stdin.isTTY) {
+            this.wasRaw = this.stdin.isRaw;
+            this.stdin.setRawMode(true);
+        }
+        this.stdin.setEncoding("utf8");
+        const buffer = this.buffer;
+        this.dataListener = (chunk) => buffer.process(chunk);
+        this.stdin.on("data", this.dataListener);
+        this.stdin.resume();
+        this.resizeListener = onResize;
+        this.stdout.on("resize", this.resizeListener);
+        this.write(BRACKETED_PASTE_ON);
+    }
+    stop() {
+        if (this.buffer === null)
+            return;
+        this.buffer.flush();
+        this.buffer.destroy();
+        this.buffer = null;
+        this.write(BRACKETED_PASTE_OFF + SHOW_CURSOR);
+        if (this.dataListener)
+            this.stdin.off("data", this.dataListener);
+        if (this.resizeListener)
+            this.stdout.off("resize", this.resizeListener);
+        this.dataListener = null;
+        this.resizeListener = null;
+        if (this.stdin.isTTY)
+            this.stdin.setRawMode(this.wasRaw);
+        this.stdin.pause();
+    }
+    write(data) {
+        this.stdout.write(data);
+    }
+}
+export class MemoryTerminal {
+    screen;
+    /** 每次 write 的原始数据（按顺序）。 */
+    writes = [];
+    started = false;
+    rawMode = false;
+    onInput = null;
+    onResize = null;
+    buffer;
+    constructor(options = {}) {
+        this.screen = new VirtualScreen(options.columns ?? 80, options.rows ?? 24);
+        this.buffer = new StdinBuffer({
+            onData: (data) => this.onInput?.(data),
+            onPaste: (text) => this.onInput?.(PASTE_START + text + PASTE_END),
+            escTimeoutMs: options.escTimeoutMs ?? 10,
+        });
+    }
+    get columns() {
+        return this.screen.columns;
+    }
+    get rows() {
+        return this.screen.height;
+    }
+    start(onInput, onResize) {
+        this.onInput = onInput;
+        this.onResize = onResize;
+        this.started = true;
+        this.rawMode = true;
+        this.write(BRACKETED_PASTE_ON);
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.buffer.flush();
+        this.write(BRACKETED_PASTE_OFF + SHOW_CURSOR);
+        this.started = false;
+        this.rawMode = false;
+        this.onInput = null;
+        this.onResize = null;
+    }
+    write(data) {
+        this.writes.push(data);
+        this.screen.write(data);
+    }
+    /** 模拟一个 stdin data 块（经 StdinBuffer 切分，与真实终端同路径）。 */
+    sendInput(chunk) {
+        this.buffer.process(chunk);
+    }
+    /** 立即发出挂起的不完整序列（替代等待 ESC 超时）。 */
+    flushInput() {
+        this.buffer.flush();
+    }
+    /** 改尺寸并触发 resize 回调（模拟 SIGWINCH）。 */
+    resize(columns, rows) {
+        this.screen.resize(columns, rows);
+        this.onResize?.();
+    }
+    /** 全部写入拼成一个字符串。 */
+    get output() {
+        return this.writes.join("");
+    }
+    /** 取走并清空写入记录（便于断言「这一帧写了什么」）。 */
+    takeWrites() {
+        const out = this.writes.join("");
+        this.writes.length = 0;
+        return out;
+    }
+    /** 可见屏幕各行（去掉右侧空白）。 */
+    viewport() {
+        return this.screen.viewport();
+    }
+    /** 回滚 + 屏幕（去掉底部空行）。 */
+    transcript() {
+        return this.screen.transcript();
+    }
+}

package/dist/tui/theme.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 主题与颜色能力（设计 §12.7）。[B4]
+ *
+ * - `dark` / `light` 两套语义色（§12.7 的 11 个名字），以 24 位 RGB 定义。
+ * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（xterm 缺省调色板取近）→ 无色。
+ * - `NO_COLOR`（非空）或 `TERM=dumb` → 无色；不探测终端背景（不发查询序列）。
+ * - 样式用各自的关闭码（39 / 49 / 22 / 23 / 24）而不是全重置，可以嵌套。
+ */
+import type { ColorDepth, SemanticColor, Theme, ThemeCapabilities } from "./component.js";
+export type ThemeName = "dark" | "light";
+type Rgb = readonly [number, number, number];
+export declare const THEME_PALETTES: Record<ThemeName, Record<SemanticColor, string>>;
+/** 由环境推断颜色深度。 */
+export declare function detectColorDepth(env?: NodeJS.ProcessEnv, isTTY?: boolean): ColorDepth;
+export declare function detectCapabilities(env?: NodeJS.ProcessEnv, isTTY?: boolean): ThemeCapabilities;
+export declare function parseHex(hex: string): Rgb;
+/** RGB → xterm 256 色索引（立方与灰阶取较近者）。 */
+export declare function rgbTo256(rgb: Rgb): number;
+/** RGB → 16 色索引（0–15）。 */
+export declare function rgbTo16(rgb: Rgb): number;
+/** 生成前景 / 背景开启序列；depth 0 返回空串。 */
+export declare function colorCode(hex: string, depth: ColorDepth, background: boolean): string;
+export interface CreateThemeOptions {
+    caps?: ThemeCapabilities;
+    /** 覆盖部分语义色（`#rrggbb`）。 */
+    overrides?: Partial<Record<SemanticColor, string>>;
+}
+export declare function createTheme(name?: ThemeName, options?: CreateThemeOptions): Theme;
+/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本。 */
+export declare function plainTheme(): Theme;
+export {};

package/dist/tui/theme.js

@@ -0,0 +1,199 @@
+/**
+ * 主题与颜色能力（设计 §12.7）。[B4]
+ *
+ * - `dark` / `light` 两套语义色（§12.7 的 11 个名字），以 24 位 RGB 定义。
+ * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（xterm 缺省调色板取近）→ 无色。
+ * - `NO_COLOR`（非空）或 `TERM=dumb` → 无色；不探测终端背景（不发查询序列）。
+ * - 样式用各自的关闭码（39 / 49 / 22 / 23 / 24）而不是全重置，可以嵌套。
+ */
+export const THEME_PALETTES = {
+    dark: {
+        text: "#e4e4e4",
+        dim: "#808080",
+        accent: "#5fafff",
+        success: "#5fd787",
+        warning: "#ffd75f",
+        error: "#ff5f5f",
+        user: "#87afff",
+        assistant: "#e4e4e4",
+        tool: "#af87ff",
+        border: "#5f5f5f",
+        code: "#ffaf5f",
+    },
+    light: {
+        text: "#1c1c1c",
+        dim: "#6c6c6c",
+        accent: "#005fd7",
+        success: "#008700",
+        warning: "#af5f00",
+        error: "#d70000",
+        user: "#005faf",
+        assistant: "#1c1c1c",
+        tool: "#8700af",
+        border: "#a8a8a8",
+        code: "#875f00",
+    },
+};
+/** 由环境推断颜色深度。 */
+export function detectColorDepth(env = process.env, isTTY = process.stdout.isTTY === true) {
+    if (env["NO_COLOR"] !== undefined && env["NO_COLOR"] !== "")
+        return 0;
+    const force = env["FORCE_COLOR"];
+    if (force === "0")
+        return 0;
+    const term = (env["TERM"] ?? "").toLowerCase();
+    if (term === "dumb")
+        return 0;
+    if (!isTTY && (force === undefined || force === ""))
+        return 0;
+    const colorterm = (env["COLORTERM"] ?? "").toLowerCase();
+    if (colorterm === "truecolor" || colorterm === "24bit" || force === "3")
+        return 16_777_216;
+    if (term.includes("256color") || force === "2")
+        return 256;
+    return 16;
+}
+export function detectCapabilities(env = process.env, isTTY = process.stdout.isTTY === true) {
+    return { colors: detectColorDepth(env, isTTY) };
+}
+export function parseHex(hex) {
+    const h = hex.replace(/^#/, "");
+    const n = Number.parseInt(h.length === 3 ? [...h].map((c) => c + c).join("") : h, 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+function nearestIndex(levels, v) {
+    let best = 0;
+    for (let i = 1; i < levels.length; i++) {
+        if (Math.abs(levels[i] - v) < Math.abs(levels[best] - v))
+            best = i;
+    }
+    return best;
+}
+function distance(a, b) {
+    const dr = a[0] - b[0];
+    const dg = a[1] - b[1];
+    const db = a[2] - b[2];
+    return dr * dr * 0.3 + dg * dg * 0.59 + db * db * 0.11;
+}
+/** RGB → xterm 256 色索引（立方与灰阶取较近者）。 */
+export function rgbTo256(rgb) {
+    const ri = nearestIndex(CUBE_LEVELS, rgb[0]);
+    const gi = nearestIndex(CUBE_LEVELS, rgb[1]);
+    const bi = nearestIndex(CUBE_LEVELS, rgb[2]);
+    const cube = [CUBE_LEVELS[ri], CUBE_LEVELS[gi], CUBE_LEVELS[bi]];
+    const avg = Math.round((rgb[0] + rgb[1] + rgb[2]) / 3);
+    const grayIndex = Math.max(0, Math.min(23, Math.round((avg - 8) / 10)));
+    const grayLevel = 8 + grayIndex * 10;
+    const gray = [grayLevel, grayLevel, grayLevel];
+    return distance(rgb, gray) < distance(rgb, cube) ? 232 + grayIndex : 16 + 36 * ri + 6 * gi + bi;
+}
+/** xterm 缺省 16 色调色板。 */
+const ANSI16 = [
+    [0, 0, 0],
+    [205, 0, 0],
+    [0, 205, 0],
+    [205, 205, 0],
+    [0, 0, 238],
+    [205, 0, 205],
+    [0, 205, 205],
+    [229, 229, 229],
+    [127, 127, 127],
+    [255, 0, 0],
+    [0, 255, 0],
+    [255, 255, 0],
+    [92, 92, 255],
+    [255, 0, 255],
+    [0, 255, 255],
+    [255, 255, 255],
+];
+/** RGB → 16 色索引（0–15）。 */
+export function rgbTo16(rgb) {
+    let best = 0;
+    for (let i = 1; i < ANSI16.length; i++) {
+        if (distance(rgb, ANSI16[i]) < distance(rgb, ANSI16[best]))
+            best = i;
+    }
+    return best;
+}
+/** 生成前景 / 背景开启序列；depth 0 返回空串。 */
+export function colorCode(hex, depth, background) {
+    if (depth === 0)
+        return "";
+    const rgb = parseHex(hex);
+    if (depth === 16_777_216)
+        return `\x1b[${background ? 48 : 38};2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+    if (depth === 256)
+        return `\x1b[${background ? 48 : 38};5;${rgbTo256(rgb)}m`;
+    const idx = rgbTo16(rgb);
+    const base = idx < 8 ? (background ? 40 : 30) + idx : (background ? 100 : 90) + idx - 8;
+    return `\x1b[${base}m`;
+}
+class PaletteTheme {
+    name;
+    caps;
+    fgCodes;
+    bgCodes;
+    constructor(name, palette, caps) {
+        this.name = name;
+        this.caps = caps;
+        const fg = {};
+        const bg = {};
+        for (const key of Object.keys(palette)) {
+            fg[key] = colorCode(palette[key], caps.colors, false);
+            bg[key] = colorCode(palette[key], caps.colors, true);
+        }
+        this.fgCodes = fg;
+        this.bgCodes = bg;
+    }
+    fg(color, text) {
+        const code = this.fgCodes[color];
+        return code === "" ? text : `${code}${text}\x1b[39m`;
+    }
+    bg(color, text) {
+        const code = this.bgCodes[color];
+        return code === "" ? text : `${code}${text}\x1b[49m`;
+    }
+    bold(text) {
+        return `\x1b[1m${text}\x1b[22m`;
+    }
+    dim(text) {
+        return this.caps.colors === 0 ? text : `\x1b[2m${text}\x1b[22m`;
+    }
+    italic(text) {
+        return `\x1b[3m${text}\x1b[23m`;
+    }
+    underline(text) {
+        return `\x1b[4m${text}\x1b[24m`;
+    }
+}
+export function createTheme(name = "dark", options = {}) {
+    const palette = { ...THEME_PALETTES[name], ...options.overrides };
+    return new PaletteTheme(name, palette, options.caps ?? detectCapabilities());
+}
+/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本。 */
+export function plainTheme() {
+    return new PlainTheme();
+}
+class PlainTheme {
+    name = "plain";
+    caps = { colors: 0 };
+    fg(_color, text) {
+        return text;
+    }
+    bg(_color, text) {
+        return text;
+    }
+    bold(text) {
+        return text;
+    }
+    dim(text) {
+        return text;
+    }
+    italic(text) {
+        return text;
+    }
+    underline(text) {
+        return text;
+    }
+}

package/dist/tui/tui.d.ts

@@ -0,0 +1,103 @@
+/**
+ * TUI 主类（设计 §12.1、§12.2，主屏 regular 模式）。[B4]
+ *
+ * 组件树（自身是纵向 Container）+ 焦点 + 覆盖层 + 差分渲染：
+ * 1. `requestRender()` 合并到 `process.nextTick`，两帧最小间隔 16 ms；键盘输入触发的渲染绕过节流。
+ * 2. 渲染组件树 → 合成覆盖层 → 提取并剔除 CURSOR_MARKER → 每行截断到宽度、含样式的行尾补重置。
+ * 3. 首帧全量；宽度 / 高度变化全量（回到屏幕左上清屏，只画最后一屏）。
+ * 4. 否则找首末变化行只重写该区间；首变化行已滚出视口 → 从视口顶清到屏底重画视口。
+ *    已滚出终端顶部的历史行不再重绘（它们在终端回滚里）。
+ * 5. 每帧写入包在同步输出 `?2026h … ?2026l` 内，按 64 KiB 分块写。
+ * 6. 记录硬件光标所在内容行；最后把硬件光标移到获焦组件的光标处（便于输入法候选窗）。
+ * 7. `stop()`：光标移到内容末尾下一行、显示光标、交还终端（关括号粘贴、cooked 模式）；不清屏。
+ *
+ * 首帧前把当前行滚到屏幕顶（输出 height-1 个换行再上移），原屏内容进入回滚而不是被清掉；
+ * 这样内容起点与屏幕顶对齐，相对光标移动不会越过屏幕顶部。
+ */
+import { type Component } from "./component.js";
+import { Container } from "./components/container.js";
+import { type OverlayOptions } from "./components/overlay.js";
+import { type Terminal } from "./terminal.js";
+export declare const SYNC_BEGIN = "\u001B[?2026h";
+export declare const SYNC_END = "\u001B[?2026l";
+export declare const WRITE_CHUNK_SIZE: number;
+export declare const MIN_RENDER_INTERVAL_MS = 16;
+export interface TuiOptions {
+    /** 两帧最小间隔（ms），缺省 16。 */
+    minRenderIntervalMs?: number;
+    /** 获焦组件有光标时是否显示硬件光标（缺省 false：只摆位置给输入法，组件自画光标）。 */
+    showHardwareCursor?: boolean;
+    /** 首帧前把当前行滚到屏幕顶（缺省 true）。 */
+    anchorToTop?: boolean;
+    now?: () => number;
+}
+export interface OverlayHandle {
+    hide(): void;
+    /** 重新把焦点交给覆盖层组件。 */
+    focus(): void;
+    readonly visible: boolean;
+}
+/** 返回 true 表示已消费，不再交给获焦组件。 */
+export type InputListener = (data: string) => boolean | void;
+export interface RenderStats {
+    renders: number;
+    fullRedraws: number;
+}
+export declare class TUI extends Container {
+    readonly terminal: Terminal;
+    private readonly options;
+    readonly stats: RenderStats;
+    private started;
+    private focused;
+    private readonly overlays;
+    private readonly listeners;
+    private readonly minInterval;
+    private readonly now;
+    private tickScheduled;
+    private renderGeneration;
+    private timer;
+    private lastRenderAt;
+    private prevLines;
+    private prevWidth;
+    private prevHeight;
+    /** 硬件光标所在内容行。 */
+    private hwRow;
+    /** 终端上已存在的内容行数（自上次全量起写到过的最大行 + 1）。 */
+    private bufferRows;
+    /** 可达的最小内容行（更早的行在回滚里或从未画过）。 */
+    private topLimit;
+    private cursorShown;
+    constructor(terminal: Terminal, options?: TuiOptions);
+    get isStarted(): boolean;
+    start(): void;
+    /** 画完最后一帧，光标移到内容末尾下一行，交还终端；不清屏。 */
+    stop(): void;
+    getFocus(): Component | null;
+    setFocus(component: Component | null): void;
+    /** 全局输入监听（先于获焦组件）；返回取消函数。 */
+    addInputListener(listener: InputListener): () => void;
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    get hasOverlay(): boolean;
+    /** 原始输入：监听器 → 获焦组件 → 立即渲染（绕过节流）。 */
+    handleInput(data: string): void;
+    /** 请求渲染；同一 tick 内合并。immediate 用于键盘输入与 resize，不受 16 ms 节流。 */
+    requestRender(immediate?: boolean): void;
+    /** 同步渲染一帧（测试与需要立刻落屏的场合）。 */
+    renderNow(): void;
+    /** 丢弃差分状态，下一帧按 resize 方式全量重画（例如外部程序写乱了屏幕）。 */
+    forceFullRedraw(): void;
+    private cancelScheduled;
+    /** 组件树 + 覆盖层 → 规范化行与光标位置。 */
+    private compose;
+    private viewportTop;
+    /** 从 hwRow 移到内容行 row 的行首；越过已有行时用换行（会滚屏）。 */
+    private moveTo;
+    private doRender;
+    private writeRows;
+    private fullFirst;
+    private fullResize;
+    /** 首变化行在视口之上：从视口顶清到屏底，重画视口（更早的行留在回滚里）。 */
+    private fullViewport;
+    private diff;
+    private placeCursor;
+}