berry-agent-sdk 0.1.0-alpha.2

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

@@ -0,0 +1,174 @@
+/**
+ * 输入解码器（07 篇引擎节件 2——kitty/legacy 双轨七态机）。
+ *
+ * 把终端 stdin 字节流解析成结构化输入事件（key/text/ime/paste/mouse 五分——
+ * 事件模型在 types 件），一台状态机两种轨制同吃：
+ * - **legacy 轨**：C0 控制码（Ctrl+字母 = 0x01-0x1a）、CSI/SS3 功能键
+ *   （`\x1b[A` 箭头、`\x1b[1;5C` Ctrl+Right、`\x1b[3~` Delete、`\x1b[15~` F5…）、
+ *   `ESC` 前缀 = alt（`\x1bx`）、`CSI Z` = shift+tab。legacy 轨无事件型区分、
+ *   键相恒 press（types 契约条款）。
+ * - **kitty 轨**：`CSI unicode-key-code[:交替键] ; 修饰[:事件型] ; 文本码点 u`
+ *   全形解析（kitty 键盘协议规范）；探测应答（`CSI ? flags u`）与 DA1
+ *   （`CSI ? …c`）拦截上抛协议落定，绝不误当按键。
+ * - **IME 组字态**（CSI u 形态）：key 0 纯文本事件 = OS/IME 组装文本（kitty
+ *   规范原文「终端拿不到键信息时键号必须用 0」）。增量流识别 = 前缀增长检测：
+ *   新文本严格扩展挂起预编辑 → 组字中事件（不落正文）；否则 → 提交事件（主流
+ *   终端只送提交：首达即立即交付，零延迟）。任意按键到达时若预编辑仍挂起 →
+ *   先冲刷为提交（流式预编辑终端的安全网，不双发）。
+ * - **legacy 形态 IME**：主流终端组字期间不送任何字节（终端自绘预编辑），提交
+ *   以纯 UTF-8 到达——整段作为 text 事件交付（不撕裂、不误判为按键序列）。
+ *   带内无标记，诚实不发明启发式。
+ * - **bracketed paste**：`\x1b[200~ … \x1b[201~` 整段识别整段交付（内容不逐键
+ *   解析——「严格处理」）。
+ * - **SGR 1006 鼠标**（2026-09-11 鼠标解码批）：`CSI < Cb;Cx;Cy M/m` 全形解析
+ *   （M = 按压/按住拖动、m = 释放）；v1 语义面收窄五钮 left/middle/right/
+ *   wheel-up/wheel-down——66/67（水平滚轮）与 128-131（扩展键）线值整序吞；
+ *   线值 8-11 是 alt 系修饰组合（位域 8=alt 叠加），照常拆解还原绝不入吞
+ *   清单；坐标 1 基 → 0 基（模型面单源 0 基）。
+ * - **X10 防御吞 + 运行时降级**：bare `CSI M` 后三字节（X10 形）整吞不产事件
+ *   （坐标字节 0x20+ 落可打印区间——地面态重解会伪造 text/按键）；开了 1006
+ *   的会话里 X10 形到达 ⟺ 终端无 SGR 能力（判据可靠），首达触发
+ *   onMouseLegacy 一次性回调（per-entry 闩），装配层据此 DECRST 关鼠标回
+ *   原生选区。
+ * - **lone-ESC 判定窗**：ESC 为 chunk 末字节时挂起等续；窗内
+ *   （escapeWindowMs，缺省 30ms）无续字节（settle）→ 判 Esc 键。kitty
+ *   disambiguate 轨下 Esc 键以 `CSI 27u` 到达，此窗只剩 legacy 轨兜底职责。
+ * - **换防吞在途**：discardPending() 丢弃解析中途的一切在途转义/粘贴/预编辑
+ *   状态——换防瞬间 stdin 在途序列不漏进新栈。
+ *
+ * 事件产出形与本仓契约对齐：KeyEvent.phase 必填三值（legacy 恒 press）；
+ * ImeEvent.committed（true 提交 / false 预编辑增量——与 berry composing 互反）。
+ */
+import type { InputEvent, KeyboardProtocol } from './types.js';
+/** 解码器构造选项 */
+export interface InputDecoderOptions {
+    /** 时钟注入（缺省 Date.now——lone-ESC 判定窗 / IME 跟随窗计时） */
+    now?: () => number;
+    /** lone-ESC 判定窗（ms；缺省 30） */
+    escapeWindowMs?: number;
+    /** 协议探测落定回调（kitty 应答先到 / DA1 到达时裁 kitty 或 legacy） */
+    onProtocol?: (protocol: KeyboardProtocol) => void;
+    /**
+     * X10 形首达回调（一次性——per-entry 闩；onProtocol 同形先例）：开了
+     * 1006 的会话里 X10 形到达 ⟺ 终端无 SGR 能力（判据可靠），装配层据此
+     * DECRST 关鼠标回原生选区（运行时降级）。
+     */
+    onMouseLegacy?: () => void;
+}
+/**
+ * 状态机输入解码器。feed 进 chunk、take 排空事件；settle 在判定窗到点时由
+ * 引擎调用（lone-ESC 裁决）；discardPending 换防吞在途。
+ */
+export declare class InputDecoder {
+    /** 事件积压队列（take 排空后换新数组——feed 不回调，避免重入） */
+    private queue;
+    /**
+     * 解析态七分：ground 地面 / esc 转义挂起 / csi 参数积攒 / ss3 / paste
+     * 粘贴体 / paste-drain 粘贴吸收态（粘贴态被换防丢弃或超帽冲刷后残余粘贴体
+     * 不得按地面态解码成伪造命令行事件——空框 enter 开应用、`/exit`+CRLF 触
+     * 退出，吞到真终界 PASTE_END 再回地面）/ mouse-x10 X10 吞态（bare CSI M
+     * 后三字节整吞——坐标字节落可打印区间，地面态重解会伪造 text 事件）。
+     */
+    private mode;
+    /** CSI 参数积攒缓冲（含私用标记 ?/> 与参数字节） */
+    private csiBuf;
+    /** CSI 超帽毒化旗标：序列已判畸形——吞到终点字节整序丢弃（残段不漏成文本） */
+    private csiPoisoned;
+    /** 粘贴体积攒缓冲 */
+    private pasteBuf;
+    /**
+     * 跨 chunk 终界悬置尾（≤5 字节）：上 chunk 末尾可能是终界 \x1b[201~ 的真
+     * 前缀——悬置于此，下 chunk 先拼回再搜。生命周期：paste 态未命中路径置位；
+     * 终界命中 / 防护帽冲刷 / discardPending 清。
+     */
+    private pendingPasteTail;
+    /** 地面态可打印文本游程积攒（连续可打印合并单事件——打字/提交不撕裂） */
+    private textRun;
+    /** lone-ESC 挂起时刻（null = 无挂起） */
+    private escPendingAt;
+    /** IME 挂起预编辑（组字中间态；null = 无组字） */
+    private preedit;
+    /** 上一发 CSI 0 文本事件（跟随窗回溯判据——流式预编辑终端的组字态开session锚） */
+    private lastCsi0;
+    /** kitty 协议已应答旗标（DA1 到达时裁 legacy/kitty） */
+    private kittyAnswered;
+    /** 协议落定已上报旗标（事件只发一次） */
+    private protocolReported;
+    /** X10 吞态剩余字节数（bare CSI M 后整吞 3 字节；0 = 不在吞态） */
+    private mouseX10Remain;
+    /** X10 首达已上报旗标（onMouseLegacy 只发一次——per-entry 闩） */
+    private mouseLegacyReported;
+    private readonly now;
+    private readonly escapeWindowMs;
+    private readonly onProtocol?;
+    private readonly onMouseLegacy?;
+    constructor(opts?: InputDecoderOptions);
+    /** 组字中旗标（焦面查询面——true 时预编辑在途） */
+    get composing(): boolean;
+    /** 挂起预编辑全文（无则 null——预编辑渲染面取用） */
+    get pendingPreedit(): string | null;
+    /** lone-ESC 挂起中（引擎据此装判定窗定时器） */
+    get hasPendingEscape(): boolean;
+    /** 喂入一个 stdin chunk（字符串已按 UTF-8 解码完成） */
+    feed(chunk: string): void;
+    /** 判定窗裁决（引擎在窗到点调用）：仍挂起 → 判 Esc 键 */
+    settle(): void;
+    /**
+     * 换防吞在途：丢弃解析中途的转义/粘贴/预编辑/文本游程——换防瞬间 stdin
+     * 在途序列一窗全丢，不漏进新栈。
+     *
+     * 粘贴态例外：粘贴体半截被弃后残余字节若按地面态重解会伪造命令行事件——
+     * 粘贴态/吸收态换防改入吸收态（paste-drain），吞残余到真终界 PASTE_END 再
+     * 回地面；CSI/ESC/X10 半序列无续作义务，仍回地面。
+     */
+    discardPending(): void;
+    /** 排空事件队列（引擎 emit 的取货口） */
+    take(): InputEvent[];
+    /** 游程冲刷：地面态连续可打印合并成一个 text 事件（提交/打字不撕裂） */
+    private flushTextRun;
+    /** 按键派发（预编辑挂起时先冲刷为提交——流式组字安全网；phase 必填） */
+    private emitKey;
+    /** 预编辑被非组字事件打断 → 冲刷为提交（终端漏发显式提交时的兜底） */
+    private flushImeOnInterrupt;
+    /** C0 控制码 → 键事件（legacy ctrl 映射表：a-z=0x01-0x1a 等） */
+    private dispatchControl;
+    /** CSI 整序派发（params 含私用标记；final 为终点字节） */
+    private dispatchCsi;
+    /** CSI number[;mods] ~ 功能键派发（200/201 粘贴包裹由 paste 态接管） */
+    private dispatchTilde;
+    /**
+     * SGR 1006 鼠标报文派发：`CSI < Cb;Cx;Cy M/m`（M = 按压/按住拖动、m = 释放）。
+     *
+     * - Cb 位域：低两位 = 按钮号（0 左/1 中/2 右；3 无按钮）；4=shift / 8=alt /
+     *   16=ctrl；32=按住 motion；64 帽位 = 轮系（+0 上/+1 下；+2/+3 = 66/67
+     *   水平滚轮左右）；128 位 = 扩展按钮 8-11（线值 128-131）。
+     * - v1 语义面收窄五钮（left/middle/right/wheel-up/wheel-down）：66/67 与
+     *   128-131 线值整序吞不产事件；线值 8-11 是 alt 系修饰组合（8=alt+左键
+     *   等），位域拆解后照常还原，绝不入吞清单。
+     * - 坐标 1 基 → 0 基（types 契约单源 0 基）；wheel 无 release（终端不报，
+     *   滚轮以 press 一相到达）；SGR 位域无 meta 位，meta 恒 false。
+     * - 非法参数（NaN/坐标越 0 基界）fail-closed 整序吞。
+     */
+    private decodeSgrMouse;
+    /**
+     * kitty CSI u 全形派发：
+     * `CSI key[:交替键] ; 修饰[:事件型] ; 文本码点 u`
+     */
+    private dispatchKittyKey;
+    /** kitty 键号 → 规范键名（功能键表 + 可打印码点直映） */
+    private kittyKeyName;
+    /**
+     * IME 文本事件裁决（组字态机）：
+     * - 组字 session 在途：新文本严格扩展挂起预编辑 → 组字中（不落正文，仅供
+     *   预编辑渲染）；不扩展 → 冲刷为提交。
+     * - 无 session：主流终端 CSI 0 只送单发提交 → **立即交付零延迟**。跟随窗内
+     *   再来一发且与前发构成前缀链 → 判流式预编辑终端：回溯开 session（前发已
+     *   交付不可撤——流式首块漏判是本设计的已知边界，注释在案），本发转组字中。
+     */
+    private dispatchImeText;
+    /**
+     * 粘贴体防护帽：超帽强制冲刷并转吸收态（畸形流不锁死键盘）。冲刷后入吸收
+     * 态吞残余到真终界 PASTE_END——残余粘贴体按地面态重解会伪造命令行事件。
+     */
+    private enforcePasteCap;
+}