berry-agent-sdk 0.1.0-alpha.2

package/dist/src/channels/engine/memory-io.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MemoryTerminalIO——TerminalIO 的内存实现（07 引擎节件 1：引擎公开测试面，
+ * 结构性义务非可选件）。
+ *
+ * 一切引擎行为可在注入替身下测试：写出收帧（bytes 累积 + 每次 write 一帧）、
+ * 输入 / resize 经测试侧 emit 注入、几何可设。真终端适配（ProcessTerminalIO）
+ * 归批 10c，本件长驻公开面供各层测试复用。
+ */
+import type { TerminalIO } from './types.js';
+export declare class MemoryTerminalIO implements TerminalIO {
+    /** 累积写出全文（多帧拼接——帧序分析用 frames） */
+    bytes: string;
+    /** 逐帧记录（每次 write 一项——收帧语义断言用） */
+    readonly frames: string[];
+    /** 几何（测试可设——resize 场景直接改字段后 emitResize） */
+    columns: number;
+    rows: number;
+    /** setRawMode 调用史（true = 开 / false = 关，序即调用序） */
+    readonly rawModeHistory: boolean[];
+    /** 当前 raw 真值（isRaw 查询面——末次 setRawMode 结果） */
+    raw: boolean;
+    /** pause / resume 调用计数（挂起交出面断言用） */
+    pauseCount: number;
+    resumeCount: number;
+    private readonly inputListeners;
+    private readonly resizeListeners;
+    constructor(columns?: number, rows?: number);
+    /** 写出收帧（帧记录 + 全文累积） */
+    write(data: string): void;
+    size(): {
+        columns: number;
+        rows: number;
+    };
+    setRawMode(enable: boolean): void;
+    isRaw(): boolean;
+    pause(): void;
+    resume(): void;
+    onInput(listener: (data: string) => void): () => void;
+    onResize(listener: () => void): () => void;
+    /** 测试注入：驱动全部输入监听器（模拟终端字节流到达——同步派发） */
+    emitInput(data: string): void;
+    /** 测试注入：驱动全部 resize 监听器（几何已由测试侧先行改定） */
+    emitResize(): void;
+    /** 清输出账（长测试分段断言用——监听器几何保留） */
+    reset(): void;
+}

package/dist/src/channels/engine/memory-io.js

@@ -0,0 +1,72 @@
+export class MemoryTerminalIO {
+    /** 累积写出全文（多帧拼接——帧序分析用 frames） */
+    bytes = '';
+    /** 逐帧记录（每次 write 一项——收帧语义断言用） */
+    frames = [];
+    /** 几何（测试可设——resize 场景直接改字段后 emitResize） */
+    columns;
+    rows;
+    /** setRawMode 调用史（true = 开 / false = 关，序即调用序） */
+    rawModeHistory = [];
+    /** 当前 raw 真值（isRaw 查询面——末次 setRawMode 结果） */
+    raw = false;
+    /** pause / resume 调用计数（挂起交出面断言用） */
+    pauseCount = 0;
+    resumeCount = 0;
+    inputListeners = new Set();
+    resizeListeners = new Set();
+    constructor(columns = 80, rows = 24) {
+        this.columns = columns;
+        this.rows = rows;
+    }
+    /** 写出收帧（帧记录 + 全文累积） */
+    write(data) {
+        this.frames.push(data);
+        this.bytes += data;
+    }
+    size() {
+        return { columns: this.columns, rows: this.rows };
+    }
+    setRawMode(enable) {
+        this.rawModeHistory.push(enable);
+        this.raw = enable;
+    }
+    isRaw() {
+        return this.raw;
+    }
+    pause() {
+        this.pauseCount++;
+    }
+    resume() {
+        this.resumeCount++;
+    }
+    onInput(listener) {
+        this.inputListeners.add(listener);
+        return () => this.inputListeners.delete(listener);
+    }
+    onResize(listener) {
+        this.resizeListeners.add(listener);
+        return () => this.resizeListeners.delete(listener);
+    }
+    /** 测试注入：驱动全部输入监听器（模拟终端字节流到达——同步派发） */
+    emitInput(data) {
+        // 快照后派发：派发中增删监听器不外溢到本批（同步退出/复起场景——副屏
+        // Engine 在派发中退订并复起主屏监听，新订阅者不吃同批字节；与真终端流
+        // 「已派发块不重投」语义一致——批 10f-4 回看器 q 退出路回归锁在
+        // tui-backend.test.ts /history 副屏装配组）
+        for (const listener of [...this.inputListeners])
+            listener(data);
+    }
+    /** 测试注入：驱动全部 resize 监听器（几何已由测试侧先行改定） */
+    emitResize() {
+        // 快照后派发（与 emitInput 同律——派发中增删不外溢）
+        for (const listener of [...this.resizeListeners])
+            listener();
+    }
+    /** 清输出账（长测试分段断言用——监听器几何保留） */
+    reset() {
+        this.bytes = '';
+        this.frames.length = 0;
+    }
+}
+//# sourceMappingURL=memory-io.js.map

package/dist/src/channels/engine/memory-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-io.js","sourceRoot":"","sources":["../../../../../../src/channels/engine/memory-io.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,gBAAgB;IAC3B,iCAAiC;IAC1B,KAAK,GAAG,EAAE,CAAC;IAClB,iCAAiC;IACjB,MAAM,GAAa,EAAE,CAAC;IACtC,2CAA2C;IACpC,OAAO,CAAS;IAChB,IAAI,CAAS;IACpB,iDAAiD;IACjC,cAAc,GAAc,EAAE,CAAC;IAC/C,6CAA6C;IACtC,GAAG,GAAG,KAAK,CAAC;IACnB,oCAAoC;IAC7B,UAAU,GAAG,CAAC,CAAC;IACf,WAAW,GAAG,CAAC,CAAC;IAEN,cAAc,GAAG,IAAI,GAAG,EAA0B,CAAC;IACnD,eAAe,GAAG,IAAI,GAAG,EAAc,CAAC;IAEzD,YAAY,OAAO,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,uBAAuB;IACvB,KAAK,CAAC,IAAY;QAChB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;IACrB,CAAC;IAED,IAAI;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACpD,CAAC;IAED,UAAU,CAAC,MAAe;QACxB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC;IACpB,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,WAAW,EAAE,CAAC;IACrB,CAAC;IAED,OAAO,CAAC,QAAgC;QACtC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED,QAAQ,CAAC,QAAoB;QAC3B,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,sCAAsC;IACtC,SAAS,CAAC,IAAY;QACpB,qCAAqC;QACrC,wCAAwC;QACxC,uCAAuC;QACvC,sCAAsC;QACtC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,wCAAwC;IACxC,UAAU;QACR,kCAAkC;QAClC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;YAAE,QAAQ,EAAE,CAAC;IAC/D,CAAC;IAED,8BAA8B;IAC9B,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;CACF"}

package/dist/src/channels/engine/process-io.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 真终端适配器（07 篇引擎节件 5 的真 TTY 位——TerminalIO 的 process 直连实现）。
+ *
+ * 引擎六件只认 TerminalIO 注入面、永不直触 process.stdin/stdout——本件是
+ * 唯一的进程接缝。非 TTY fail-loud（管道下运行 berry 需明确报错）归
+ * host 装配批（批 12）在装配层执法——本件 setRawMode 对非 TTY 静默跳过
+ * （`process.stdin.setRawMode` 在非 TTY 上会抛——先查 isTTY 再设）。
+ */
+import type { TerminalIO } from './types.js';
+/** process stdin/stdout 直连适配器（组合根缺省注入位） */
+export declare class ProcessTerminalIO implements TerminalIO {
+    write(data: string): void;
+    size(): {
+        columns: number;
+        rows: number;
+    };
+    setRawMode(enable: boolean): void;
+    isRaw(): boolean;
+    pause(): void;
+    resume(): void;
+    onInput(listener: (data: string) => void): () => void;
+    onResize(listener: () => void): () => void;
+}

package/dist/src/channels/engine/process-io.js

@@ -0,0 +1,39 @@
+/** process stdin/stdout 直连适配器（组合根缺省注入位） */
+export class ProcessTerminalIO {
+    write(data) {
+        process.stdout.write(data);
+    }
+    size() {
+        // 兜底用 || 而非 ??：pty 未设 winsize 时（expect/CI 伪终端）node 返回
+        // rows/columns = 0 而非 undefined——`??` 只兜 null/undefined 兜不住 0；
+        // 0 行 0 列的终端物理不存在，零值与缺席同属「无有效几何」，一律回落
+        // 80×24（2026-09-13 真模型五轮实测定罪：0 值直透曾致 CellGrid 零宽
+        // 只擦不写 + 负行号 CUP——固定区渲染全空）。
+        return { columns: process.stdout.columns || 80, rows: process.stdout.rows || 24 };
+    }
+    setRawMode(enable) {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(enable);
+    }
+    isRaw() {
+        return process.stdin.isRaw ?? false;
+    }
+    pause() {
+        process.stdin.pause();
+    }
+    resume() {
+        process.stdin.resume();
+    }
+    onInput(listener) {
+        const stdin = process.stdin;
+        stdin.setEncoding('utf8');
+        stdin.on('data', listener);
+        return () => stdin.removeListener('data', listener);
+    }
+    onResize(listener) {
+        const stdout = process.stdout;
+        stdout.on('resize', listener);
+        return () => stdout.removeListener('resize', listener);
+    }
+}
+//# sourceMappingURL=process-io.js.map

package/dist/src/channels/engine/process-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-io.js","sourceRoot":"","sources":["../../../../../../src/channels/engine/process-io.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,IAAY;QAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI;QACF,sDAAsD;QACtD,+DAA+D;QAC/D,sCAAsC;QACtC,iDAAiD;QACjD,4BAA4B;QAC5B,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IACpF,CAAC;IAED,UAAU,CAAC,MAAe;QACxB,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK;QACH,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC;IACtC,CAAC;IAED,KAAK;QACH,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC;IAED,OAAO,CAAC,QAAgC;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC3B,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED,QAAQ,CAAC,QAAoB;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/src/channels/engine/types.d.ts

@@ -0,0 +1,202 @@
+/**
+ * 自研 TUI 引擎契约件（07 篇 §4.1 自研引擎节件 1——批 10b 引擎核心）。
+ *
+ * 引擎与真 TTY 全解耦的接缝根基：TerminalIO 是注入面（按引擎生命周期需要
+ * 设计接口面，非照抄进程 API）、MemoryTerminalIO 内存实现是引擎公开测试面
+ * （结构性义务非可选件——「mock 只停在模型层」纪律的接缝根基）。
+ *
+ * 本文件只立契约（类型 + 协议），零实现、零外部依赖；实现可替换性由接口
+ * 面承载（CellBuffer 协议下实装在 cell 件、TerminalIO 下真终端适配在批 10c）。
+ */
+/** 16 色 ANSI 色号（0-15；色域 = 16 色 + 属性位，真彩 / 256 色挂账不预造） */
+export type AnsiColor = number & {
+    readonly __brand: 'ansi-16-color';
+};
+/** 16 色色号构造（brand 收口：色号只能经此进入引擎面） */
+export declare function ansiColor(n: number): AnsiColor;
+/** 单格样式（属性位族——缺省位一律 false / undefined） */
+export interface CellStyle {
+    /** 前景 16 色索引（undefined = 终端缺省前景） */
+    readonly fg?: AnsiColor;
+    /** 背景 16 色索引（undefined = 终端缺省背景） */
+    readonly bg?: AnsiColor;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly dim?: boolean;
+    readonly inverse?: boolean;
+}
+/**
+ * 网格单格三元：码点面 + 样式 + 列宽（07 引擎节件 3 cell 网格模型）。
+ *
+ * - grapheme 存**完整字素串**（单码点字素即该码点）——多码点字素（ZWJ 家族 /
+ *   旗帜 / 变体选择子）整串入格，同首码点不同字素因串不同在差分按格直比中
+ *   自然判不等（字素面参与差分自证——结构自证、无旁路账本）。
+ * - width 三值：2 = 宽字素首格、0 = 宽字素续格（grapheme 为空串占位——与主流
+ *   终端续格形同构，差分按格直比无需行结构感知）、1 = 常规字素。
+ */
+export interface Cell {
+    readonly grapheme: string;
+    readonly style: CellStyle;
+    readonly width: 0 | 1 | 2;
+}
+/** 本帧光标声明（帧尾统一落位——显隐态跨帧去重归 diff 件） */
+export interface CursorState {
+    readonly row: number;
+    readonly col: number;
+    readonly visible: boolean;
+}
+/**
+ * 终端 IO 注入面（七动词：写出 / 几何 / raw 模式 / 流暂停复起 / 输入订阅 /
+ * resize 订阅 / raw 真值查询）。
+ *
+ * 真终端适配（ProcessTerminalIO）与内存实现（MemoryTerminalIO）同面
+ * 接入；引擎六件只认本接口、永不直触 process.stdout / stdin。isRaw 供
+ * 挂起交出面复原先验态（start 前记录、suspend/dispose 还原）。
+ */
+export interface TerminalIO {
+    /** 写出 ANSI 字节（同步写出——帧缓冲的最终出口） */
+    write(data: string): void;
+    /** 当前几何（列 / 行——resize 后以真值为准，不缓存） */
+    size(): {
+        columns: number;
+        rows: number;
+    };
+    /** raw 模式开关（真终端适配负责复原先验态；内存实现纯记账） */
+    setRawMode(enable: boolean): void;
+    /** 当前 raw 真值（挂起交出面复原先验态的记录依据） */
+    isRaw(): boolean;
+    /** 流暂停 / 复起（挂起交出面用——为 $EDITOR 类子交互进程预留） */
+    pause(): void;
+    resume(): void;
+    /** 订阅输入字节流（解码件消费——回调返回退订函数） */
+    onInput(listener: (data: string) => void): () => void;
+    /** 订阅几何变更（引擎侧弃旧换新重绘） */
+    onResize(listener: () => void): () => void;
+}
+/** 键盘协议轨（DA1 哨兵探测落定：kitty 应答先到 = kitty 轨 / 否则 legacy） */
+export type KeyboardProtocol = 'kitty' | 'legacy';
+/** 组件落位区域（行 / 列 / 宽 / 高——屏幕坐标系） */
+export interface Region {
+    readonly row: number;
+    readonly col: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * 组件两段协商协议（07 引擎节件 1）：
+ * 量高（给定宽度报期望行数）与落位（只写自己区域内）走同一分配单源、
+ * 两段永不漂移（无约束求解器——量高即分配的承诺，落位不得超卖）。
+ * 越界写由缓冲吸收（CellBuffer 静默丢弃界外格——组件可信任缓冲兜底）。
+ */
+export interface Renderable {
+    /** 量高：给定可用宽度，报本组件期望行数 */
+    measure(width: number): number;
+    /** 落位：只写自己区域内（region 由装配层依量高结果划定） */
+    render(buffer: CellBuffer, region: Region): void;
+}
+/**
+ * cell 网格写入契约（实现可替换；含本帧光标声明写入面）。
+ *
+ * 光标三问（07 引擎节件 1 审读补条款）：由谁声明 = 交互件 render 内声明本帧
+ * 可见光标位置；竞声明裁决 = setCursor / clearCursor 同帧多组件竞声明以
+ * **末次为准**；显隐去重 = 帧尾统一落位（定位 + 显 / 隐），同态跨帧零冗余
+ * 序列（去重执法在 diff 件，buffer 只存本帧声明终值）。
+ *
+ * 帧路径零分配：缓冲跨帧复用、clear 只摘格不重分配，resize 是唯一重分配点。
+ */
+export interface CellBuffer {
+    readonly columns: number;
+    readonly rows: number;
+    /** 摘格清屏（网格结构复用——帧间清屏用，零分配） */
+    clear(): void;
+    /** 读单格（界外 / 未写格返回 null = 缺省空格） */
+    getCell(row: number, col: number): Cell | null;
+    /**
+     * 写单字素格（宽字素自动铺续格；覆写区既有宽字素整字摘痕防新旧混叠；
+     * 越界写静默吸收——渲染契约「越界写由缓冲吸收」的执法位）。
+     */
+    setCell(row: number, col: number, grapheme: string, style?: CellStyle): void;
+    /**
+     * 写文本（字素级写入 + 列位推进；返回推进后列位——宽字素占双列）。
+     * 空串 / 零宽情形下返回原列位（推进为零）。
+     */
+    writeText(row: number, col: number, text: string, style?: CellStyle): number;
+    /** 本帧光标声明（显式落位） */
+    setCursor(row: number, col: number): void;
+    /** 本帧光标清除声明（本帧无可见光标） */
+    clearCursor(): void;
+    /** 本帧光标声明终值（无声明 = null） */
+    readonly cursor: CursorState | null;
+    /** 几何变更（唯一重分配点；内容弃置——resize 弃旧换新，编排侧重绘兜底） */
+    resize(columns: number, rows: number): void;
+}
+/**
+ * 输入事件模型五分（07 引擎节件 1——2026-09-11 鼠标解码批四分扩五分）：
+ * key / text / ime / paste / mouse。
+ *
+ * 事件由输入解码件（批 10c；mouse 增补随鼠标解码批 mu-2）产出——本件只立
+ * 模型面。key 事件带 press / repeat / release 三型（kitty 轨可达；legacy 轨
+ * 无事件型区分、恒 press）；text 事件粒度 = 同 chunk 内连续可打印游程合并
+ * 单事件（打字 / 中文提交不撕裂——逐字符派发会每事件触发渲染请求）。
+ * mouse 事件带 press/motion/release 三型 + 按钮语义位 + 修饰键还原 +
+ * 0 基屏幕坐标（SGR 报文 1 基的换算归解码件，模型面单源 0 基）。
+ */
+/** 键相（press 首按 / repeat 连按 / release 释放——kitty 轨专属区分） */
+export type KeyPhase = 'press' | 'repeat' | 'release';
+/** key 事件：逻辑键名（'enter' / 'escape' / 'up' … 词汇表由解码件定）+ 修饰键还原 */
+export interface KeyEvent {
+    readonly kind: 'key';
+    readonly key: string;
+    readonly ctrl: boolean;
+    readonly alt: boolean;
+    readonly shift: boolean;
+    readonly meta: boolean;
+    readonly phase: KeyPhase;
+}
+/** text 事件：可打印文本游程（同 chunk 连续合并；跨 chunk 不滞留） */
+export interface TextInputEvent {
+    readonly kind: 'text';
+    readonly text: string;
+}
+/**
+ * ime 事件：组字一等公民模型面。committed = false 预编辑增量（不落正文）、
+ * committed = true 提交（才落正文）；识别判据（前缀增长检测）与首达零延迟
+ * 是解码件行为条款，模型面不涉。
+ */
+export interface ImeEvent {
+    readonly kind: 'ime';
+    readonly text: string;
+    readonly committed: boolean;
+}
+/** paste 事件：bracketed paste 整段交付（终界跨 chunk 悬置等待在解码件） */
+export interface PasteEvent {
+    readonly kind: 'paste';
+    readonly text: string;
+}
+/** mouse 事件相（press 按下 / motion 按住拖动 / release 释放——SGR 报文 M/m 终点区分） */
+export type MousePhase = 'press' | 'motion' | 'release';
+/** mouse 按钮语义位（07 引擎节件 4 v1 收窄五钮——其余按钮线值整序吞不产事件） */
+export type MouseButton = 'left' | 'middle' | 'right' | 'wheel-up' | 'wheel-down';
+/**
+ * mouse 事件：SGR 1006 解码产物（07 引擎节件 4 鼠标解码批条款）。
+ *
+ * - 坐标 0 基（col 列 / row 行——SGR 报文 1 基的换算归解码件）；
+ * - 修饰键还原（SGR 位域 4=shift / 8=alt / 16=ctrl——线值 8-11 的 alt 系
+ *   组合在此拆解、绝不入吞清单；SGR 无 meta 位，meta 恒 false）；
+ * - motion = 按住拖动（DECSET 1002 button-event tracking——无键 motion 不
+ *   报）；wheel 无 release（终端不报，滚轮以 press 一相到达）。
+ */
+export interface MouseEvent {
+    readonly kind: 'mouse';
+    readonly phase: MousePhase;
+    readonly button: MouseButton;
+    readonly col: number;
+    readonly row: number;
+    readonly ctrl: boolean;
+    readonly alt: boolean;
+    readonly shift: boolean;
+    readonly meta: boolean;
+}
+/** 输入事件五分判别联合（mouse 系 2026-09-11 鼠标解码批增补） */
+export type InputEvent = KeyEvent | TextInputEvent | ImeEvent | PasteEvent | MouseEvent;

package/dist/src/channels/engine/types.js

@@ -0,0 +1,18 @@
+/**
+ * 自研 TUI 引擎契约件（07 篇 §4.1 自研引擎节件 1——批 10b 引擎核心）。
+ *
+ * 引擎与真 TTY 全解耦的接缝根基：TerminalIO 是注入面（按引擎生命周期需要
+ * 设计接口面，非照抄进程 API）、MemoryTerminalIO 内存实现是引擎公开测试面
+ * （结构性义务非可选件——「mock 只停在模型层」纪律的接缝根基）。
+ *
+ * 本文件只立契约（类型 + 协议），零实现、零外部依赖；实现可替换性由接口
+ * 面承载（CellBuffer 协议下实装在 cell 件、TerminalIO 下真终端适配在批 10c）。
+ */
+/** 16 色色号构造（brand 收口：色号只能经此进入引擎面） */
+export function ansiColor(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 15) {
+        throw new Error(`ansiColor: 色号须为 0-15 整数，收到 ${n}`);
+    }
+    return n;
+}
+//# sourceMappingURL=types.js.map

package/dist/src/channels/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/channels/engine/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,qCAAqC;AACrC,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,CAAc,CAAC;AACxB,CAAC"}

package/dist/src/channels/engine/width.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 字素级宽度四规则（07 引擎节件 2）：
+ * ① 字素内任一码点 EAW wide/fullwidth → 2；
+ * ② 含 VS16 → 2（emoji 呈现形——窄基字符 + VS16 也占双列）；
+ * ③ 恰一对 Regional Indicator → 2（旗帜——单码点 EAW 覆盖不到，孤立 RI 按 1）；
+ * ④ 其余 → 1。
+ */
+export declare function graphemeWidth(grapheme: string): 0 | 1 | 2;
+/** 切分字素序列（Intl.Segmenter——ZWJ 家族 / 旗帜 / 变体选择子整素不撕裂） */
+export declare function splitGraphemes(text: string): string[];
+/** 整字三原语之一·测宽：全串字素宽度和 */
+export declare function stringWidth(text: string): number;
+/**
+ * 整字三原语之二·按宽截断：截到不超过 cols 的最长字素前缀——
+ * 宽字素跨界整字丢弃**不产半字**（末位恰剩一列放不下双宽字素时整字放弃）。
+ */
+export declare function truncateToWidth(text: string, cols: number): string;
+/**
+ * 整字三原语之三·整字换行：按 cols 折行——
+ * 行末剩一列遇双宽字素整字下移**第二列不悬挂**；ZWJ 家族**跨行不撕裂**
+ * （字素切分在前、折行只动字素边界）；显式 \n 强制换行（段语义保留）。
+ */
+export declare function wrapText(text: string, cols: number): string[];

package/dist/src/channels/engine/width.js

@@ -0,0 +1,123 @@
+/**
+ * 文本度量件（07 篇 §4.1 自研引擎节件 2——批 10b 引擎核心）。
+ *
+ * 字素边界与列宽两件必须同时在场（立法缘由：berry 注释点名 OpenCode 反课
+ * 「只用字素切分不管列宽 → CJK 断行错位至今未修」）——
+ * - 字素边界：运行时内建 Intl.Segmenter（零新依赖，模块级单例）；
+ * - 列宽：EAW 分类**数据面**外包 get-east-asian-width（§2.1 精确锁 1.6.0），
+ *   `ambiguous = 1` 的中西混排语境取舍**决策面自持**在本件（见 eawWidth 注释）。
+ */
+import { eastAsianWidthType } from 'get-east-asian-width';
+/** 字素切分器（模块级单例——Segmenter 构造贵、无状态可复用） */
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** 变体选择子 16（emoji 呈现形——字素含之即宽 2） */
+const VS16 = 0xfe0f;
+/** Regional Indicator 起止（旗帜 = 恰一对 RI 合成一字素） */
+const RI_FIRST = 0x1f1e6;
+const RI_LAST = 0x1f1ff;
+/**
+ * EAW 单码点分类宽（决策面自持位）。
+ *
+ * ambiguous（A 类：〇 ⊡ ⛭ …）在 CJK 语境常按 2 列渲染、西文语境按 1 列——
+ * 本仓取舍 **= 1**（中西混排对话正文按窄计），依据 = berry 实证同款取舍；
+ * 部分按 2 渲染的 CJK 终端上对齐误差可容忍，可配置性挂真实需求再裁
+ * （07 §4.1 终端支持矩阵降级三款注记在案）。
+ * 注：外包库的 eastAsianWidth() 缺省 ambiguousAsWide = true——与本取舍相反，
+ * 故只取其分类函数、宽度判定自持，不走其合成宽函数。
+ */
+function eawWidth(codePoint) {
+    const type = eastAsianWidthType(codePoint);
+    return type === 'wide' || type === 'fullwidth' ? 2 : 1;
+}
+/**
+ * 字素级宽度四规则（07 引擎节件 2）：
+ * ① 字素内任一码点 EAW wide/fullwidth → 2；
+ * ② 含 VS16 → 2（emoji 呈现形——窄基字符 + VS16 也占双列）；
+ * ③ 恰一对 Regional Indicator → 2（旗帜——单码点 EAW 覆盖不到，孤立 RI 按 1）；
+ * ④ 其余 → 1。
+ */
+export function graphemeWidth(grapheme) {
+    const codePoints = [...grapheme].map((ch) => ch.codePointAt(0));
+    // 规则③：恰一对 RI（两面旗恰好两个 RI 码点合成）判 2；单 RI / 三连 RI 落规则④
+    const riCount = codePoints.filter((cp) => cp >= RI_FIRST && cp <= RI_LAST).length;
+    if (codePoints.length === 2 && riCount === 2)
+        return 2;
+    // 规则②：VS16 在场即宽（emoji 呈现形语义优先于基字符分类）
+    if (codePoints.includes(VS16))
+        return 2;
+    // 规则①：任一码点 wide/fullwidth → 2
+    for (const cp of codePoints) {
+        if (eawWidth(cp) === 2)
+            return 2;
+    }
+    // 规则④：其余 → 1（含控制字符的占位语义不在此件发明——网格写入层拒收）
+    return 1;
+}
+/** 切分字素序列（Intl.Segmenter——ZWJ 家族 / 旗帜 / 变体选择子整素不撕裂） */
+export function splitGraphemes(text) {
+    if (text === '')
+        return [];
+    const out = [];
+    for (const seg of segmenter.segment(text))
+        out.push(seg.segment);
+    return out;
+}
+/** 整字三原语之一·测宽：全串字素宽度和 */
+export function stringWidth(text) {
+    let width = 0;
+    for (const g of splitGraphemes(text))
+        width += graphemeWidth(g);
+    return width;
+}
+/**
+ * 整字三原语之二·按宽截断：截到不超过 cols 的最长字素前缀——
+ * 宽字素跨界整字丢弃**不产半字**（末位恰剩一列放不下双宽字素时整字放弃）。
+ */
+export function truncateToWidth(text, cols) {
+    if (cols <= 0)
+        return '';
+    let used = 0;
+    let out = '';
+    for (const g of splitGraphemes(text)) {
+        const w = graphemeWidth(g);
+        if (used + w > cols)
+            break; // 剩余列宽不足整字——整字丢弃（不产半字）
+        used += w;
+        out += g;
+    }
+    return out;
+}
+/**
+ * 整字三原语之三·整字换行：按 cols 折行——
+ * 行末剩一列遇双宽字素整字下移**第二列不悬挂**；ZWJ 家族**跨行不撕裂**
+ * （字素切分在前、折行只动字素边界）；显式 \n 强制换行（段语义保留）。
+ */
+export function wrapText(text, cols) {
+    if (cols <= 0)
+        return [text]; // 非法宽防御：不折行整段返回（坏参不丢字）
+    const lines = [];
+    // 先按显式换行分段（空段保留——空行语义），段内再按宽折行
+    for (const paragraph of text.split('\n')) {
+        if (paragraph === '') {
+            lines.push('');
+            continue;
+        }
+        let current = '';
+        let used = 0;
+        for (const g of splitGraphemes(paragraph)) {
+            const w = graphemeWidth(g);
+            if (used + w > cols) {
+                lines.push(current); // 当前行满——整字下移开新行（双宽字不悬挂第二列）
+                current = g;
+                used = w;
+            }
+            else {
+                current += g;
+                used += w;
+            }
+        }
+        lines.push(current); // 段尾行（含整段未折情形）
+    }
+    return lines;
+}
+//# sourceMappingURL=width.js.map

package/dist/src/channels/engine/width.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"width.js","sourceRoot":"","sources":["../../../../../../src/channels/engine/width.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * channels 模块公开面（L4 宿主固定件——02 篇席 10；机制真源 07 篇 §4.1/§4.3、
+ * 03 篇 §2.2 命令面、04 篇 §4/§9）。
+ *
+ * 批 10a 落通道核（多会话信封分流 + 投影拉取注入 + 命令面 + ui 原语分发 +
+ * 提问队列——零 pi-tui import）。TUI 实装：呈现面九件（07 §4.1 定稿——件 9
+ * 非聚焦会话摘要行含内）与交互/补全族已落批 10e/10f；件 8 /history 副屏
+ * 回看器归批 10f-4 未落（现状陈述——本面暂无其注册位）；host 装配接线
+ * （bin 入口/启动会话策略）归批 12。
+ */
+export type { SessionEnvelope, UiCapabilities, UiBackend, UiAskOptions, UiSelectChoice, UiInputOptions, NotifyLevel, AskKind, ApprovalAskAnswer, ApprovalAskRequest, TodoItem, CommandArgs, CommandHandler, CommandSpec, ChannelsOptions, } from './types.js';
+export { CommandRegistry, tokenize } from './commands.js';
+export { AskQueue } from './ask-queue.js';
+export type { AskHooks } from './ask-queue.js';
+export { UiCore } from './ui-core.js';
+export { SessionChannels } from './registry.js';
+export { createChannels } from './service.js';
+export type { ChannelsService } from './service.js';
+export type { TuiBackendOptions } from './tui/index.js';
+export { TuiBackend } from './tui/index.js';
+export { ProcessTerminalIO } from './engine/index.js';
+export type { TerminalIO } from './engine/index.js';
+export { FileMentionSource } from './tui/index.js';
+export type { FileMentionSourceOptions, AutocompleteSources, AutocompleteItem } from './tui/index.js';
+export * from './sdk/index.js';

package/dist/src/channels/index.js

@@ -0,0 +1,16 @@
+export { CommandRegistry, tokenize } from './commands.js';
+export { AskQueue } from './ask-queue.js';
+export { UiCore } from './ui-core.js';
+export { SessionChannels } from './registry.js';
+export { createChannels } from './service.js';
+export { TuiBackend } from './tui/index.js';
+// 真终端适配器 + 补全源族（批 12e host 装配消费——engine/·tui/ 组件族非公开
+// 面纪律的件外出口位：「本面随真实件外消费扩」先例；余组件仍件内消费）
+export { ProcessTerminalIO } from './engine/index.js';
+export { FileMentionSource } from './tui/index.js';
+// SDK 线协议（批 13a 契约先行——03 §10.6 件身份条：协议核心代码位与 channels
+// 通道核同体，SDK 通道后端 = UiBackend 第三后端；本面出协议词汇/信封 + NDJSON
+// 编解码 + admit/游标纯逻辑四件。后端实装（事件外推/请求受理/出站队列）随批
+// 13b；stdio 传输归宿主 serve、HTTP+SSE/MCP 归 core:sdk 件〔src/sdk/ 13e〕）
+export * from './sdk/index.js';
+//# sourceMappingURL=index.js.map

package/dist/src/channels/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/channels/index.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,qDAAqD;AACrD,qCAAqC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,sDAAsD;AACtD,sDAAsD;AACtD,6CAA6C;AAC7C,iEAAiE;AACjE,cAAc,gBAAgB,CAAC"}

package/dist/src/channels/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 多会话注册表与焦点编排（07 §4.1 通道契约——2026-09-06 channels 纵切批）。
+ *
+ * 职责：会话在场集合 + 焦点位（聚焦者全渲染/非聚焦摘要行的判定源）+
+ * 焦点切换清屏重画（拉投影 → repaint 回调——投影拉取经装配注入，
+ * channels 不 import session 是 02 §4.1 边表的刻意设计）。
+ *
+ * 焦点切换不自动回退：聚焦会话注销后焦点空悬（focused=null——非聚焦态
+ * 全体），下一焦点由用户动作显式给（切焦编舞归 TUI 呈现批）。
+ */
+export declare class SessionChannels<TProjection> {
+    private readonly fetchProjection;
+    private readonly repaint;
+    private readonly sessions;
+    private currentFocus;
+    constructor(fetchProjection: ((sessionId: string) => Promise<readonly TProjection[]>) | undefined, repaint: (sessionId: string, projection: readonly TProjection[]) => void);
+    /** 会话入场（幂等；焦点不自动变更——显式 focus 才切） */
+    registerSession(sessionId: string): void;
+    /** 会话退场：在场集移除；若正是聚焦者 → 焦点空悬（不自动接续） */
+    unregisterSession(sessionId: string): void;
+    /** 当前聚焦会话（null = 焦点空悬——全体非聚焦态） */
+    get focusedId(): string | null;
+    isFocused(sessionId: string): boolean;
+    /** 在场判定（emit 路由前置——不在场会话的信封仍可分流，呈现裁剪归后端） */
+    has(sessionId: string): boolean;
+    /**
+     * 焦点切换（07 §4.1：清屏重画）：置位 → 拉投影 → repaint。
+     * 投影拉取缺席 → 空投影重画（诚实缺席：装配缺真源是可观察态，不静默假装
+     * 有历史）；拉取异常向上抛（fail-loud——投影真源故障不降级为「无历史」谎言）。
+     * 未注册会话 focus 视同注册（焦点即活跃声明——幂等）。
+     */
+    focus(sessionId: string): Promise<void>;
+}