berry-agent 0.1.0-alpha.1

package/dist/channels/engine/input.js

@@ -0,0 +1,596 @@
+import { decodeMods, decodePhase, KITTY_PUA_KEYS, LETTER_KEYS, NO_MODS, TILDE_KEYS } from './input-keys.js';
+/** 粘贴态防护帽：超帽强制冲刷（恶意/畸形流不锁死解码器——4 MiB） */
+const PASTE_CAP = 4 * 1024 * 1024;
+/** bracketed paste 终界（包裹尾——6 字节 \x1b[201~） */
+const PASTE_END = '\x1b[201~';
+/**
+ * rest 尾部可悬置量（0-5）：终界 PASTE_END 的最长真前缀后缀长。pty 写缓冲
+ * 分块（典型 4-16KiB）可能把 6 字节终界劈成两半——上 chunk 尾部恰是终界前缀
+ * 时不能并入粘贴体（并入后下 chunk 永不匹配完整终界 → 解码器滞留 paste 态，
+ * 此后键盘输入全被吞进 pasteBuf 零事件），须悬置到实例字段待下 chunk 拼回再搜。
+ */
+function pasteMarkerPrefixLen(rest) {
+    const max = Math.min(PASTE_END.length - 1, rest.length);
+    for (let k = max; k > 0; k--) {
+        if (rest.endsWith(PASTE_END.slice(0, k)))
+            return k;
+    }
+    return 0;
+}
+/** CSI 参数缓冲防护帽（超帽毒化吞到终点——畸形流防御） */
+const CSI_CAP = 64;
+/** IME 跟随窗（ms）：两发 CSI 0 在窗内构成前缀链 = 流式预编辑（kitty 单发提交不受影响） */
+const IME_FOLLOW_WINDOW_MS = 100;
+/**
+ * 状态机输入解码器。feed 进 chunk、take 排空事件；settle 在判定窗到点时由
+ * 引擎调用（lone-ESC 裁决）；discardPending 换防吞在途。
+ */
+export class InputDecoder {
+    /** 事件积压队列（take 排空后换新数组——feed 不回调，避免重入） */
+    queue = [];
+    /**
+     * 解析态七分：ground 地面 / esc 转义挂起 / csi 参数积攒 / ss3 / paste
+     * 粘贴体 / paste-drain 粘贴吸收态（粘贴态被换防丢弃或超帽冲刷后残余粘贴体
+     * 不得按地面态解码成伪造命令行事件——空框 enter 开应用、`/exit`+CRLF 触
+     * 退出，吞到真终界 PASTE_END 再回地面）/ mouse-x10 X10 吞态（bare CSI M
+     * 后三字节整吞——坐标字节落可打印区间，地面态重解会伪造 text 事件）。
+     */
+    mode = 'ground';
+    /** CSI 参数积攒缓冲（含私用标记 ?/> 与参数字节） */
+    csiBuf = '';
+    /** CSI 超帽毒化旗标：序列已判畸形——吞到终点字节整序丢弃（残段不漏成文本） */
+    csiPoisoned = false;
+    /** 粘贴体积攒缓冲 */
+    pasteBuf = '';
+    /**
+     * 跨 chunk 终界悬置尾（≤5 字节）：上 chunk 末尾可能是终界 \x1b[201~ 的真
+     * 前缀——悬置于此，下 chunk 先拼回再搜。生命周期：paste 态未命中路径置位；
+     * 终界命中 / 防护帽冲刷 / discardPending 清。
+     */
+    pendingPasteTail = '';
+    /** 地面态可打印文本游程积攒（连续可打印合并单事件——打字/提交不撕裂） */
+    textRun = '';
+    /** lone-ESC 挂起时刻（null = 无挂起） */
+    escPendingAt = null;
+    /** IME 挂起预编辑（组字中间态；null = 无组字） */
+    preedit = null;
+    /** 上一发 CSI 0 文本事件（跟随窗回溯判据——流式预编辑终端的组字态开session锚） */
+    lastCsi0 = null;
+    /** kitty 协议已应答旗标（DA1 到达时裁 legacy/kitty） */
+    kittyAnswered = false;
+    /** 协议落定已上报旗标（事件只发一次） */
+    protocolReported = false;
+    /** X10 吞态剩余字节数（bare CSI M 后整吞 3 字节；0 = 不在吞态） */
+    mouseX10Remain = 0;
+    /** X10 首达已上报旗标（onMouseLegacy 只发一次——per-entry 闩） */
+    mouseLegacyReported = false;
+    now;
+    escapeWindowMs;
+    onProtocol;
+    onMouseLegacy;
+    constructor(opts = {}) {
+        this.now = opts.now ?? Date.now;
+        this.escapeWindowMs = opts.escapeWindowMs ?? 30;
+        this.onProtocol = opts.onProtocol;
+        this.onMouseLegacy = opts.onMouseLegacy;
+    }
+    /** 组字中旗标（焦面查询面——true 时预编辑在途） */
+    get composing() {
+        return this.preedit !== null;
+    }
+    /** 挂起预编辑全文（无则 null——预编辑渲染面取用） */
+    get pendingPreedit() {
+        return this.preedit;
+    }
+    /** lone-ESC 挂起中（引擎据此装判定窗定时器） */
+    get hasPendingEscape() {
+        return this.escPendingAt !== null;
+    }
+    /** 喂入一个 stdin chunk（字符串已按 UTF-8 解码完成） */
+    feed(chunk) {
+        let i = 0;
+        while (i < chunk.length) {
+            const cp = chunk.codePointAt(i);
+            switch (this.mode) {
+                case 'ground': {
+                    if (cp === 0x1b) {
+                        this.flushTextRun();
+                        this.mode = 'esc';
+                        i++;
+                        continue;
+                    }
+                    if (cp < 0x20 || cp === 0x7f) {
+                        this.flushTextRun();
+                        this.dispatchControl(cp);
+                        i++;
+                        continue;
+                    }
+                    // 可打印：游程积攒（代理对整对入游程）
+                    this.textRun += String.fromCodePoint(cp);
+                    i += cp > 0xffff ? 2 : 1;
+                    continue;
+                }
+                case 'esc': {
+                    if (cp === 0x5b) {
+                        // '[' —— CSI 序列起
+                        this.mode = 'csi';
+                        this.csiBuf = '';
+                        i++;
+                        continue;
+                    }
+                    if (cp === 0x4f) {
+                        // 'O' —— SS3 序列起
+                        this.mode = 'ss3';
+                        i++;
+                        continue;
+                    }
+                    if (cp === 0x1b) {
+                        // ESC ESC = alt+Escape（legacy alt 编码两字节形）
+                        this.escPendingAt = null;
+                        this.emitKey('escape', { ...NO_MODS, alt: true }, 'press');
+                        this.mode = 'ground';
+                        i++;
+                        continue;
+                    }
+                    // ESC + 可打印 = legacy alt 编码（如 \x1bx → alt+x）；控制码罕见——吞
+                    this.escPendingAt = null;
+                    if (cp >= 0x20 && cp !== 0x7f) {
+                        this.emitKey(String.fromCodePoint(cp), { ...NO_MODS, alt: true }, 'press');
+                        i += cp > 0xffff ? 2 : 1;
+                    }
+                    else {
+                        i++;
+                    }
+                    this.mode = 'ground';
+                    continue;
+                }
+                case 'csi': {
+                    if (cp >= 0x40 && cp <= 0x7e) {
+                        // 终点字节到——整序派发（毒化序列整序丢弃）
+                        if (!this.csiPoisoned)
+                            this.dispatchCsi(this.csiBuf, String.fromCodePoint(cp));
+                        this.csiBuf = '';
+                        this.csiPoisoned = false;
+                        // dispatchTilde 200 可能已转粘贴态——不覆写（粘贴体接管后续字节）
+                        if (this.mode === 'csi')
+                            this.mode = 'ground';
+                        this.escPendingAt = null;
+                        i++;
+                        continue;
+                    }
+                    this.csiBuf += String.fromCodePoint(cp);
+                    i += cp > 0xffff ? 2 : 1;
+                    if (this.csiBuf.length > CSI_CAP) {
+                        // 畸形超帽：毒化标记（继续吞参数到终点字节——不锁死、不误发文本）
+                        this.csiPoisoned = true;
+                        this.csiBuf = '';
+                    }
+                    continue;
+                }
+                case 'ss3': {
+                    // SS3 单字母终点（A/B/C/D/H/F/P/Q/R/S）
+                    const key = LETTER_KEYS[String.fromCodePoint(cp)];
+                    this.escPendingAt = null;
+                    if (key)
+                        this.emitKey(key, { ...NO_MODS }, 'press');
+                    this.mode = 'ground';
+                    i++;
+                    continue;
+                }
+                case 'mouse-x10': {
+                    // X10 形后三字节整吞（防御吞）：坐标字节 0x20+ 落可打印区间——按
+                    // 地面态重解会伪造 text/按键；降级（DECRST）后不再有后续 X10 报文，
+                    // 吞态必终止
+                    i++;
+                    this.mouseX10Remain--;
+                    if (this.mouseX10Remain <= 0)
+                        this.mode = 'ground';
+                    continue;
+                }
+                case 'paste': {
+                    // 粘贴体：找包裹尾 PASTE_END——整段交付，体内容不逐键解析。
+                    // 跨 chunk 终界拼接：上 chunk 尾部的终界真前缀悬置在
+                    // pendingPasteTail——先拼回再搜；命中时推进量须还账悬置字节（那
+                    // tail.length 个字节来自上 chunk，本 chunk 未消费）
+                    const tail = this.pendingPasteTail;
+                    this.pendingPasteTail = '';
+                    const rest = tail + chunk.slice(i);
+                    const end = rest.indexOf(PASTE_END);
+                    if (end < 0) {
+                        // 未命中：头部（确定不可能参与终界）并入体积攒；尾部真前缀悬置
+                        const hold = pasteMarkerPrefixLen(rest);
+                        this.pasteBuf += rest.slice(0, rest.length - hold);
+                        this.pendingPasteTail = rest.slice(rest.length - hold);
+                        i = chunk.length; // 本 chunk 全量消化（并入或悬置——无剩可解）
+                        this.enforcePasteCap();
+                    }
+                    else {
+                        this.pasteBuf += rest.slice(0, end);
+                        const text = this.pasteBuf;
+                        this.pasteBuf = '';
+                        this.mode = 'ground';
+                        this.escPendingAt = null;
+                        // 终界长 6 > 悬置上限 5 ⇒ 推进量恒 ≥1（无死循环）；且 end+6 ≤
+                        // rest.length 保证不越过本 chunk 末尾
+                        i += end + PASTE_END.length - tail.length;
+                        if (text.length > 0)
+                            this.queue.push({ kind: 'paste', text });
+                    }
+                    continue;
+                }
+                case 'paste-drain': {
+                    // 粘贴吸收态：粘贴体已被换防丢弃/超帽冲刷——残余粘贴体字节全吞（含
+                    // CRLF/命令形文本，防伪造命令行事件），直到真终界 PASTE_END 到达回
+                    // 地面。终端协议保证 200~ 后必有 201~——吸收态必终止。跨 chunk 分裂
+                    // 终界复用 paste 态同款悬置尾（真前缀悬置拼回，不吞真终界字节）
+                    const tail = this.pendingPasteTail;
+                    this.pendingPasteTail = '';
+                    const rest = tail + chunk.slice(i);
+                    const end = rest.indexOf(PASTE_END);
+                    if (end < 0) {
+                        // 未命中：全吞；尾部真前缀悬置（下 chunk 拼回再搜）
+                        const hold = pasteMarkerPrefixLen(rest);
+                        this.pendingPasteTail = rest.slice(rest.length - hold);
+                        i = chunk.length;
+                    }
+                    else {
+                        // 真终界命中：回地面，续解其后字节（推进量还账悬置字节——同 paste 态）
+                        this.mode = 'ground';
+                        this.escPendingAt = null;
+                        i += end + PASTE_END.length - tail.length;
+                    }
+                    continue;
+                }
+            }
+        }
+        // chunk 尽：地面态文本游程冲刷（每 chunk 一个 text 事件——跨 chunk 不滞留；
+        // esc/csi/paste 态下 textRun 必为空，冲刷为无操作）
+        this.flushTextRun();
+        // esc 态挂起无续 → 记 lone-ESC 判定窗起点（首帧记时）
+        if (this.mode === 'esc' && this.escPendingAt === null) {
+            this.escPendingAt = this.now();
+        }
+    }
+    /** 判定窗裁决（引擎在窗到点调用）：仍挂起 → 判 Esc 键 */
+    settle() {
+        if (this.mode === 'esc' && this.escPendingAt !== null) {
+            if (this.now() - this.escPendingAt >= this.escapeWindowMs) {
+                this.escPendingAt = null;
+                this.mode = 'ground';
+                this.emitKey('escape', { ...NO_MODS }, 'press');
+            }
+        }
+    }
+    /**
+     * 换防吞在途：丢弃解析中途的转义/粘贴/预编辑/文本游程——换防瞬间 stdin
+     * 在途序列一窗全丢，不漏进新栈。
+     *
+     * 粘贴态例外：粘贴体半截被弃后残余字节若按地面态重解会伪造命令行事件——
+     * 粘贴态/吸收态换防改入吸收态（paste-drain），吞残余到真终界 PASTE_END 再
+     * 回地面；CSI/ESC/X10 半序列无续作义务，仍回地面。
+     */
+    discardPending() {
+        this.mode = this.mode === 'paste' || this.mode === 'paste-drain' ? 'paste-drain' : 'ground';
+        this.csiBuf = '';
+        this.csiPoisoned = false;
+        this.pasteBuf = '';
+        this.pendingPasteTail = '';
+        this.textRun = '';
+        this.escPendingAt = null;
+        this.preedit = null;
+        this.mouseX10Remain = 0;
+    }
+    /** 排空事件队列（引擎 emit 的取货口） */
+    take() {
+        const out = this.queue;
+        this.queue = [];
+        return out;
+    }
+    /** 游程冲刷：地面态连续可打印合并成一个 text 事件（提交/打字不撕裂） */
+    flushTextRun() {
+        if (this.textRun.length > 0) {
+            this.queue.push({ kind: 'text', text: this.textRun });
+            this.textRun = '';
+        }
+    }
+    /** 按键派发（预编辑挂起时先冲刷为提交——流式组字安全网；phase 必填） */
+    emitKey(key, mods, phase) {
+        this.flushImeOnInterrupt();
+        const ev = { kind: 'key', key, ...mods, phase };
+        this.queue.push(ev);
+    }
+    /** 预编辑被非组字事件打断 → 冲刷为提交（终端漏发显式提交时的兜底） */
+    flushImeOnInterrupt() {
+        if (this.preedit !== null) {
+            const text = this.preedit;
+            this.preedit = null;
+            const ev = { kind: 'ime', text, committed: true };
+            this.queue.push(ev);
+        }
+    }
+    /** C0 控制码 → 键事件（legacy ctrl 映射表：a-z=0x01-0x1a 等） */
+    dispatchControl(cp) {
+        if (cp === 0x0d || cp === 0x0a) {
+            this.emitKey('enter', { ...NO_MODS }, 'press');
+            return;
+        }
+        if (cp === 0x09) {
+            this.emitKey('tab', { ...NO_MODS }, 'press');
+            return;
+        }
+        if (cp === 0x7f) {
+            this.emitKey('backspace', { ...NO_MODS }, 'press');
+            return;
+        }
+        if (cp === 0x00) {
+            this.emitKey('space', { ...NO_MODS, ctrl: true }, 'press');
+            return;
+        }
+        if (cp >= 0x01 && cp <= 0x1a) {
+            // ctrl+字母：0x01=a … 0x1a=z（0x08=h/0x09=i/0x0d=m 由上优先拦走）
+            this.emitKey(String.fromCharCode(cp + 96), { ...NO_MODS, ctrl: true }, 'press');
+            return;
+        }
+        if (cp >= 0x1c && cp <= 0x1f) {
+            // ctrl+标点（kitty 表：\ ] ^ _）
+            this.emitKey(String.fromCharCode(cp + 64), { ...NO_MODS, ctrl: true }, 'press');
+            return;
+        }
+        // 其余 C0（0x1b 已在状态机先行）：吞
+    }
+    /** CSI 整序派发（params 含私用标记；final 为终点字节） */
+    dispatchCsi(params, final) {
+        // 私用标记 '?' 开头 = 终端应答（探测/DA1）——协议面处理，绝不误当按键
+        if (params.startsWith('?')) {
+            if (final === 'u') {
+                this.kittyAnswered = true;
+                if (!this.protocolReported) {
+                    this.protocolReported = true;
+                    this.onProtocol?.('kitty');
+                }
+            }
+            else if (final === 'c') {
+                // DA1 应答：kitty 应答从未到 → legacy 落定
+                if (!this.protocolReported) {
+                    this.protocolReported = true;
+                    this.onProtocol?.(this.kittyAnswered ? 'kitty' : 'legacy');
+                }
+            }
+            return; // 其余私用应答（CPR 等）吞
+        }
+        if (params.startsWith('<')) {
+            // SGR 1006 鼠标报文（私用标记 '<' 引导）——协议面处理，绝不误当按键
+            this.decodeSgrMouse(params.slice(1), final);
+            return;
+        }
+        if (params === '' && final === 'M') {
+            // bare CSI M = X10 形起手（LETTER_KEYS 无 M 键——此形不与功能键冲突）：
+            // 开了 1006 的会话里 X10 形到达 ⟺ 终端无 SGR 能力——首达上报降级信号
+            // （一次性），后三字节转吞态整吞
+            if (!this.mouseLegacyReported) {
+                this.mouseLegacyReported = true;
+                this.onMouseLegacy?.();
+            }
+            this.mode = 'mouse-x10';
+            this.mouseX10Remain = 3;
+            return;
+        }
+        if (final === 'u') {
+            this.dispatchKittyKey(params);
+            return;
+        }
+        if (final === '~') {
+            this.dispatchTilde(params);
+            return;
+        }
+        if (final === 'Z') {
+            this.emitKey('tab', { ...NO_MODS, shift: true }, 'press');
+            return;
+        }
+        if (final === 'R') {
+            return; // 光标位置报告应答形状——吞（引擎从不请求，防串扰误键）
+        }
+        if (final === 'I' || final === 'O') {
+            return; // 焦点进出通知——吞（v1 不消费）
+        }
+        const letterKey = LETTER_KEYS[final];
+        if (letterKey) {
+            // CSI A/B/C/D/H/F/P-S（`CSI 1;mods C` 修饰形同表）
+            const parts = params.split(';');
+            this.emitKey(letterKey, decodeMods(parts[1]), 'press');
+            return;
+        }
+        // 未知序列：吞（fail-silent——协议噪音吸收，不出垃圾文本）
+    }
+    /** CSI number[;mods] ~ 功能键派发（200/201 粘贴包裹由 paste 态接管） */
+    dispatchTilde(params) {
+        const parts = params.split(';');
+        if (parts[0] === '200') {
+            // bracketed paste 开始：转粘贴体积攒态
+            this.mode = 'paste';
+            this.pasteBuf = '';
+            return;
+        }
+        if (parts[0] === '201') {
+            return; // 裸包裹尾（无开始）——吞
+        }
+        const key = TILDE_KEYS[Number(parts[0])];
+        if (key)
+            this.emitKey(key, decodeMods(parts[1]), 'press');
+    }
+    /**
+     * 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 整序吞。
+     */
+    decodeSgrMouse(params, final) {
+        if (final !== 'M' && final !== 'm')
+            return; // SGR 鼠标只有 M/m 终点——余吞
+        const fields = params.split(';');
+        const cb = Number(fields[0]);
+        const cx = Number(fields[1]);
+        const cy = Number(fields[2]);
+        if (!Number.isInteger(cb) || !Number.isInteger(cx) || !Number.isInteger(cy))
+            return;
+        const col = cx - 1;
+        const row = cy - 1;
+        if (col < 0 || row < 0)
+            return;
+        const low = cb & 3;
+        let button;
+        if (cb & 64) {
+            if (low === 0)
+                button = 'wheel-up';
+            else if (low === 1)
+                button = 'wheel-down';
+            else
+                return; // 66/67 水平滚轮——v1 收窄面外，整序吞
+        }
+        else if (cb & 128) {
+            return; // 128-131 扩展按钮 8-11——v1 收窄面外，整序吞
+        }
+        else if (low === 0)
+            button = 'left';
+        else if (low === 1)
+            button = 'middle';
+        else if (low === 2)
+            button = 'right';
+        else
+            return; // 低两位 3 = 无按钮（X10 遗迹/1003 any-motion 形）——不可归因，吞
+        const phase = final === 'm' ? 'release' : cb & 32 ? 'motion' : 'press';
+        this.queue.push({
+            kind: 'mouse',
+            phase,
+            button,
+            col,
+            row,
+            ctrl: (cb & 16) !== 0,
+            alt: (cb & 8) !== 0,
+            shift: (cb & 4) !== 0,
+            meta: false, // SGR 位域无 meta 位——模型面恒 false（types 契约注记）
+        });
+    }
+    /**
+     * kitty CSI u 全形派发：
+     * `CSI key[:交替键] ; 修饰[:事件型] ; 文本码点 u`
+     */
+    dispatchKittyKey(params) {
+        const fields = params.split(';');
+        const keyParts = (fields[0] ?? '').split(':');
+        const keyCode = Number(keyParts[0]);
+        if (!Number.isFinite(keyCode))
+            return;
+        // 修饰子域：值 = 1+位域；冒号后缀 = 事件型（1 press 缺省/2 repeat/3 release）
+        const modParts = (fields[1] ?? '').split(':');
+        const mods = decodeMods(modParts[0]);
+        const phase = decodePhase(modParts.length > 1 ? Number(modParts[1]) : 1);
+        // 文本子域：冒号分隔码点列表。码点界检（fail-closed）：String.fromCodePoint
+        // 对越界/负值/NaN 抛 RangeError——未捕获即杀整进程；Number(' ')===0 静默产
+        // NUL。kitty 文本子域结构上只该是 1..0x10FFFF 整数码点，非法子域丢弃
+        // （全弃后 keyCode 0 无文本 → 整事件吞——fail-closed，键名码点界检同尺）
+        const text = (fields[2] ?? '')
+            .split(':')
+            .filter((s) => s.length > 0)
+            .map((s) => Number(s))
+            .filter((n) => Number.isInteger(n) && n >= 1 && n <= 0x10ffff)
+            .map((n) => String.fromCodePoint(n))
+            .join('');
+        // IME/文本优先裁决：key 0 纯文本事件（终端拿不到键信息 = OS/IME 组装）
+        if (keyCode === 0 && text.length > 0) {
+            this.dispatchImeText(text);
+            return;
+        }
+        const keyName = this.kittyKeyName(keyCode);
+        if (keyName === undefined) {
+            // 未知键号：带文本则按提交交付，否则吞
+            if (text.length > 0)
+                this.dispatchImeText(text);
+            return;
+        }
+        if (text.length > 0) {
+            // 文本字段在场：与键符一致（大小写不敏感）= 普通打字 → text 事件；
+            // 不一致 = 死键/组合变换文本 → IME 提交路径
+            const plain = text.length === 1 && text.toLowerCase() === keyName.toLowerCase();
+            if (plain) {
+                this.flushImeOnInterrupt();
+                this.queue.push({ kind: 'text', text });
+                return;
+            }
+            this.dispatchImeText(text);
+            return;
+        }
+        this.emitKey(keyName, mods, phase);
+    }
+    /** kitty 键号 → 规范键名（功能键表 + 可打印码点直映） */
+    kittyKeyName(keyCode) {
+        if (keyCode === 27)
+            return 'escape';
+        if (keyCode === 13)
+            return 'enter';
+        if (keyCode === 9)
+            return 'tab';
+        if (keyCode === 127)
+            return 'backspace';
+        const pua = KITTY_PUA_KEYS[keyCode];
+        if (pua)
+            return pua;
+        if (keyCode >= 0x20 && keyCode <= 0x10ffff) {
+            const ch = String.fromCodePoint(keyCode);
+            if (ch >= ' ')
+                return ch; // 可打印（无 shift 修饰原形——kitty 恒小写规范）
+        }
+        return undefined;
+    }
+    /**
+     * IME 文本事件裁决（组字态机）：
+     * - 组字 session 在途：新文本严格扩展挂起预编辑 → 组字中（不落正文，仅供
+     *   预编辑渲染）；不扩展 → 冲刷为提交。
+     * - 无 session：主流终端 CSI 0 只送单发提交 → **立即交付零延迟**。跟随窗内
+     *   再来一发且与前发构成前缀链 → 判流式预编辑终端：回溯开 session（前发已
+     *   交付不可撤——流式首块漏判是本设计的已知边界，注释在案），本发转组字中。
+     */
+    dispatchImeText(text) {
+        if (this.preedit !== null && text.length > this.preedit.length && text.startsWith(this.preedit)) {
+            this.preedit = text;
+            this.queue.push({ kind: 'ime', text, committed: false });
+            return;
+        }
+        // 无 session：跟随窗内前缀链 → 流式预编辑终端，回溯开 session
+        const last = this.lastCsi0;
+        if (this.preedit === null &&
+            last !== null &&
+            this.now() - last.at <= IME_FOLLOW_WINDOW_MS &&
+            (text.startsWith(last.text) || last.text.startsWith(text)) &&
+            text !== last.text) {
+            this.preedit = text;
+            this.queue.push({ kind: 'ime', text, committed: false });
+            this.lastCsi0 = { text, at: this.now() };
+            return;
+        }
+        this.preedit = null;
+        this.lastCsi0 = { text, at: this.now() };
+        this.queue.push({ kind: 'ime', text, committed: true });
+    }
+    /**
+     * 粘贴体防护帽：超帽强制冲刷并转吸收态（畸形流不锁死键盘）。冲刷后入吸收
+     * 态吞残余到真终界 PASTE_END——残余粘贴体按地面态重解会伪造命令行事件。
+     */
+    enforcePasteCap() {
+        if (this.pasteBuf.length > PASTE_CAP) {
+            const text = this.pasteBuf;
+            this.pasteBuf = '';
+            this.pendingPasteTail = ''; // 悬置尾同弃（已离粘贴态——半截终界无意义）
+            this.mode = 'paste-drain';
+            if (text.length > 0)
+                this.queue.push({ kind: 'paste', text });
+        }
+    }
+}

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

@@ -0,0 +1,71 @@
+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;
+    }
+}