berry-agent 0.1.0-alpha.1

package/dist/channels/tui/memory/memory-viewer.js

@@ -0,0 +1,540 @@
+import { ScrollView } from '../scroll/scroll-view.js';
+import { Editor } from '../editor/editor.js';
+import { prefixDisplayWidth } from '../editor/visual-lines.js';
+import { shortIdOf } from '../backend/transcript.js';
+import { tokenize } from '../../commands.js';
+/** 筛选四态循环序（全部→活体→冻结→终态→全部——Tab 单步右移） */
+const FILTER_CYCLE = ['all', 'active', 'frozen', 'terminal'];
+/** 分区呈现名（分区头 + 筛选注记共用单源） */
+const SECTION_LABEL = Object.freeze({
+    active: '活体',
+    frozen: '冻结',
+    terminal: '终态',
+});
+/** 提示行样式（dim——存在感弱于正文；分区头/投影行同载体） */
+const DIM_STYLE = Object.freeze({ dim: true });
+/** 光标行反色样式（整行最强存在感——SelectPanel 高亮行同载体） */
+const CURSOR_STYLE = Object.freeze({ inverse: true });
+/** 常态底行键面提示（按光标行分区动态铸造——零条目可见时行动词消隐） */
+function hintText(section) {
+    const verbs = section === null
+        ? ''
+        : section === 'active'
+            ? 'f 冻结 · d 忘掉 · '
+            : section === 'frozen'
+                ? 'f 解冻 · '
+                : 'r 恢复 · ';
+    return `${verbs}e 导出 · tab 筛选 · q/esc 返回`;
+}
+/** owner 键短显（头行——project 键 16 hex 截前 8 位，引用短 id 同款 8 位惯例） */
+function ownerLabel(key) {
+    if (key.startsWith('project:'))
+        return `project:${key.slice('project:'.length, 'project:'.length + 8)}`;
+    return key; // global（及未来他形）原样——project 之外的键无哈希面
+}
+/** epoch 毫秒 → ISO UTC（tools.ts fmt 同式——呈现换算面同源注记） */
+function fmtTs(ts) {
+    return new Date(ts).toISOString().replace('.000Z', 'Z');
+}
+/** key 事件窄化（text/ime/paste 归各分路） */
+function asKey(event) {
+    return event.kind === 'key' ? event : null;
+}
+/** 无修饰命名键判 */
+function isPlainKey(e, key) {
+    return !e.ctrl && !e.alt && !e.shift && !e.meta && e.key === key;
+}
+/** 错误折底行文案（守卫错人读面——码与人读原因直呈，同命令面 idiom） */
+function errorText(err) {
+    if (err instanceof Error && 'code' in err && typeof err.code === 'string') {
+        return `${err.code}：${err.message}`;
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 管理面内容件：ScrollView 子类（滚动/折叠/偏移算术继承）+ OverlayContent
+ * （副屏 root——render 直收全屏 region）。
+ */
+export class MemoryViewer extends ScrollView {
+    ownerKeys;
+    dao;
+    sanitize;
+    exportCommand;
+    onExit;
+    onInterrupt;
+    onQuit;
+    /* ---- 视图态（rebuild 全量重建——动词后整表重取） ---- */
+    styledLines = [];
+    entries = [];
+    /** 光标（entries 下标；-1 = 零条目可见无处可指） */
+    cursor = -1;
+    /** 健康五计数（投影两行数据源） */
+    health = { active: 0, dismissed: 0, expired: 0, frozen: 0, total: 0 };
+    /** 筛选态（Tab 循环） */
+    filter = 'all';
+    /* ---- 模态两态（互斥：确认态与输入态不并在场——开其一先收另一） ---- */
+    /** 确认态（d 两段式——目标条目非空即在态） */
+    confirmTarget = null;
+    /** 输入态（e 导出参数行在场位） */
+    exportOpen = false;
+    exportEditor;
+    /** 底行一次性提示（守卫错/导出回执/解冻指引——常态下次按键即清） */
+    notice = null;
+    /** 退出闭锁（同批多事件只退一次——q 与 Esc 竞发的防御位） */
+    exited = false;
+    constructor(options) {
+        super(); // 无 maxHeight——副屏 root 直收 region 全高
+        this.ownerKeys = options.ownerKeys;
+        this.dao = options.dao;
+        this.sanitize = options.sanitize;
+        this.exportCommand = options.exportCommand;
+        this.onExit = options.onExit;
+        this.onInterrupt = options.onInterrupt;
+        this.onQuit = options.onQuit;
+        this.exportEditor = new Editor({ maxVisibleLines: 1 }); // 单行档——导出参数行
+        this.exportEditor.setFocused(false);
+        this.rebuild(); // 开屏快照（光标落首条——顶部对齐）
+    }
+    /** 量高：头行 + 视口全量 + 底铬（输入态 = Editor；其余恒 1 行） */
+    measure(width) {
+        return 1 + super.measure(width) + (this.exportOpen ? this.exportEditor.measure(width) : 1);
+    }
+    /**
+     * 落位（副屏全屏 region 三段）：头行（档名 + owner 短显 + 筛选注记）→
+     * 滚动视口（super.render——投影两行/分区头/条目行全在内，折叠与偏移恒归
+     * ScrollView）→ 底铬（输入态 = 单行 Editor；确认态 = 确认文案；否则
+     * 一次性提示 ?? 动态键面提示）。
+     */
+    render(buffer, region) {
+        if (region.height < 2)
+            return; // 防御位（极小终端——头行 + 视口都不够）
+        // 头行（筛选态在场时附注记——Tab 动作的可视反馈位）
+        const filterTag = this.filter === 'all' ? '' : ` ·〔筛选：${SECTION_LABEL[this.filter]}〕`;
+        buffer.writeText(region.row, region.col, `❄ 记忆管理 · ${this.ownerKeys.map(ownerLabel).join(' · ')}${filterTag}`);
+        // 滚动视口
+        const chromeBottom = this.exportOpen ? this.exportEditor.measure(region.width) : 1;
+        const viewHeight = region.height - 1 - chromeBottom;
+        if (viewHeight > 0) {
+            super.render(buffer, { row: region.row + 1, col: region.col, width: region.width, height: viewHeight });
+        }
+        // 底铬
+        if (this.exportOpen) {
+            this.exportEditor.setFocused(true);
+            this.exportEditor.render(buffer, {
+                row: region.row + region.height - chromeBottom,
+                col: region.col,
+                width: region.width,
+                height: chromeBottom,
+            });
+            return;
+        }
+        const bottom = this.confirmTarget !== null
+            ? `忘掉 [m:${shortIdOf(this.confirmTarget.id)}]？enter/y 确认 · esc/n 取消`
+            : (this.notice ?? hintText(this.cursorEntry()?.section ?? null));
+        buffer.writeText(region.row + region.height - 1, region.col, bottom, DIM_STYLE);
+    }
+    /**
+     * 事件分发（副屏内容终局消费——未消费键不穿透，模态独占）。
+     * 序：Ctrl+C/Ctrl+D 副屏键面补丁 → Tab 全局动词（输入态仍可达——Editor
+     * 不消费 Tab）→ 输入态模态 → 确认态模态 → 常态（退出键/行动词/光标键
+     * → ScrollView 滚动路）。
+     */
+    handleEvent(event) {
+        if (event.kind === 'mouse')
+            return this.handleMouse(event); // mouse 路（终局消费）
+        const k = asKey(event);
+        if (k !== null && k.phase !== 'release') {
+            // Ctrl+C = 打断在飞 run（press/repeat 相动作滤 kitty release——主屏同键面）
+            if (k.ctrl && !k.alt && !k.shift && !k.meta && k.key === 'c') {
+                this.onInterrupt?.();
+                return true;
+            }
+            // Ctrl+D = 退出进程（先收副屏再转退出柄；输入行有文不退——主屏空框闸同律）
+            if (k.ctrl && !k.alt && !k.shift && !k.meta && k.key === 'd' && this.exportEditor.model.isEmpty()) {
+                this.exit();
+                this.onQuit?.();
+                return true;
+            }
+            // Tab 全局动词：筛选循环单步（输入态在场仍可达——Editor 不消费 Tab，
+            // 与 /history 搜索框键面无冲突的判据面）
+            if (isPlainKey(k, 'tab')) {
+                this.closeModals();
+                this.cycleFilter();
+                return true;
+            }
+        }
+        // 输入态（e 导出参数行）——模态：Esc 关 / Enter 执行 / 其余入 Editor
+        if (this.exportOpen) {
+            if (k !== null && k.phase !== 'release' && !k.ctrl && !k.alt && !k.meta) {
+                if (isPlainKey(k, 'escape')) {
+                    this.closeExport();
+                    return true;
+                }
+                if (isPlainKey(k, 'enter')) {
+                    void this.runExport();
+                    return true;
+                }
+            }
+            this.exportEditor.handleEvent(event);
+            return true;
+        }
+        // 确认态（d 两段式）——模态：Enter/y 确认 / Esc/n 取消（保守值）/ 其余吞
+        //（y/n 双轨同判——kitty 轨纯键打字走 text 事件，与常态行动词同律）
+        if (this.confirmTarget !== null) {
+            const typed = event.kind === 'text' ? event.text : null;
+            if (k !== null && k.phase !== 'release') {
+                if (isPlainKey(k, 'enter') || isPlainKey(k, 'y')) {
+                    this.commitForget();
+                    return true;
+                }
+                if (isPlainKey(k, 'escape') || isPlainKey(k, 'n')) {
+                    this.confirmTarget = null; // 取消——保守值收场
+                    return true;
+                }
+            }
+            if (typed === 'y') {
+                this.commitForget();
+                return true;
+            }
+            if (typed === 'n') {
+                this.confirmTarget = null; // 取消——保守值收场
+                return true;
+            }
+            return true; // 未消费键层内终局（模态）
+        }
+        // 常态：退出键与行动词双轨（kitty disambiguate 轨纯键打字走 text 事件、
+        // legacy 轨走 key 事件——同一动作两轨同判，HistoryViewer q 键同律）
+        this.notice = null; // 一次性提示读毕即清（动词自身的新提示随后覆写）
+        if (k !== null && k.phase !== 'release') {
+            if (isPlainKey(k, 'escape')) {
+                this.exit();
+                return true;
+            }
+            if (isPlainKey(k, 'up')) {
+                this.moveCursor(-1);
+                return true;
+            }
+            if (isPlainKey(k, 'down')) {
+                this.moveCursor(1);
+                return true;
+            }
+            if (isPlainKey(k, 'f')) {
+                this.applyFreezeToggle();
+                return true;
+            }
+            if (isPlainKey(k, 'd')) {
+                this.beginForget();
+                return true;
+            }
+            if (isPlainKey(k, 'r')) {
+                this.applyRestore();
+                return true;
+            }
+            if (isPlainKey(k, 'e')) {
+                this.openExport();
+                return true;
+            }
+        }
+        if (event.kind === 'text') {
+            const ch = event.text;
+            if (ch === 'q') {
+                this.exit();
+                return true;
+            }
+            if (ch === 'f') {
+                this.applyFreezeToggle();
+                return true;
+            }
+            if (ch === 'd') {
+                this.beginForget();
+                return true;
+            }
+            if (ch === 'r') {
+                this.applyRestore();
+                return true;
+            }
+            if (ch === 'e') {
+                this.openExport();
+                return true;
+            }
+        }
+        // 滚动键（PgUp/PgDn/Home/End——↑/↓ 已被光标消费；未消费键终局吞）
+        super.handleEvent(event);
+        return true;
+    }
+    /* ---------------- 鼠标消费面（07 屏模型双形态节同批回写） ---------------- */
+    /**
+     * mouse 事件路（终局消费——模态独占）：滚轮归 ScrollView（统一滚动路）；
+     * 左键点条目行 = 光标移至该行（点击反查经视口段映射到逻辑行，再对
+     * entries 锚比对——非条目行零动作）；头行/底铬/滚动条列/非左键零动作吞。
+     */
+    handleMouse(event) {
+        if (event.button === 'wheel-up' || event.button === 'wheel-down') {
+            super.handleEvent(event); // 滚轮消费路（±3 视觉行——显式滚动路）
+            return true;
+        }
+        if (event.phase !== 'press')
+            return true; // motion/release 零动作（无拖选面 v1）
+        if (this.exportOpen || this.confirmTarget !== null)
+            return true; // 模态在场零动作吞
+        if (event.button !== 'left')
+            return true; // v1 只有左键消费——中/右零动作
+        const geo = this.viewportGeometry;
+        if (event.row < 1 || event.row >= 1 + geo.height)
+            return true; // 头行/底铬命中零动作
+        if (this.hitScrollbar(event.col))
+            return true; // 滚动条列零动作
+        const seg = this.segmentAt(event.row - 1); // 视口首行 = region.row + 1
+        if (seg === null)
+            return true;
+        const idx = this.entries.findIndex((e) => e.lineIndex === seg.line);
+        if (idx >= 0)
+            this.cursor = idx; // 条目行命中——光标移至该行；分区头/投影行不指
+        return true;
+    }
+    /* ---------------- 行动词（f/d/r——单源走 DAO 既有族） ---------------- */
+    /** f：冻结切换（呈现层判向——frozen 行 unfreeze、active 行 freeze；终态行零义吞） */
+    applyFreezeToggle() {
+        const entry = this.cursorEntry();
+        if (entry === undefined || entry.section === 'terminal')
+            return; // 终态行 f 零义吞
+        try {
+            if (entry.section === 'frozen')
+                this.dao.unfreeze(entry.row.id);
+            else
+                this.dao.freeze(entry.row.id);
+            this.rebuild(entry.row.id); // 同 id 锚定（frozen 位变即换分区呈现）
+        }
+        catch (err) {
+            this.notice = errorText(err); // 守卫错折底行
+        }
+    }
+    /** d：忘掉起手（active 行入确认态；终态行零义吞；冻结行零义吞 + 底行指引） */
+    beginForget() {
+        const entry = this.cursorEntry();
+        if (entry === undefined || entry.section === 'terminal')
+            return; // 终态行 d 零义吞
+        if (entry.section === 'frozen') {
+            this.notice = '已冻结——先 f 解冻再忘掉';
+            return;
+        }
+        this.confirmTarget = entry.row; // 确认态（两段式第二段）
+    }
+    /** 确认态落子：forget(id) 缺省 supersededBy='user'（撤回后条目呈终态区——r 可复） */
+    commitForget() {
+        const target = this.confirmTarget;
+        this.confirmTarget = null; // 单次语义（先出态——守卫错也不再回确认态）
+        if (target === null)
+            return;
+        try {
+            this.dao.forget(target.id, { supersededBy: 'user' });
+            this.rebuild(target.id); // 同 id 锚定（filter=all 时条目现于终态区）
+        }
+        catch (err) {
+            this.notice = errorText(err); // 守卫错折底行（MEMORY_FROZEN 等）
+        }
+    }
+    /** r：恢复（终态行免 confirm 直接 restore；active 行零义吞） */
+    applyRestore() {
+        const entry = this.cursorEntry();
+        if (entry === undefined || entry.section !== 'terminal')
+            return; // active 行 r 零义吞
+        try {
+            this.dao.restore(entry.row.id);
+            this.rebuild(entry.row.id); // 同 id 锚定（复活后现于活体区）
+        }
+        catch (err) {
+            this.notice = errorText(err);
+        }
+    }
+    /* ---------------- 全局动词（e/Tab） ---------------- */
+    /** e：开导出参数输入行（/memory-export 真身同一函数——参数面与命令面同形） */
+    openExport() {
+        this.confirmTarget = null; // 模态互斥（先收另一态）
+        this.exportOpen = true;
+        this.exportEditor.setFocused(true);
+    }
+    /** 关输入行（查询文本保留——重开续打的增量延续，/history 搜索框同律） */
+    closeExport() {
+        this.exportOpen = false;
+        this.exportEditor.setFocused(false);
+    }
+    /**
+     * 执行导出：输入行文本 → 引号感知切分（命令分发同源 tokenize）→ 注入的
+     * 处理器闭包；回执折底行（多行以 · 连呈——底行单行面）。fire-and-forget：
+     * 命令体同步落盘（writeFileSync），promise 首微task即resolve——引擎帧
+     * 合并的 setTimeout 渲染在其后，回执同帧可见。
+     */
+    async runExport() {
+        const raw = this.exportEditor.getText();
+        this.closeExport();
+        try {
+            const text = await this.exportCommand(tokenize(raw));
+            this.notice = text.replace(/\n+/g, ' · ');
+        }
+        catch (err) {
+            this.notice = errorText(err); // 非 BaseError 异常面（BaseError 命令内已折文本）
+        }
+    }
+    /** Tab：筛选循环单步（全部→活体→冻结→终态→全部）+ 整表按新筛选重建 */
+    cycleFilter() {
+        const idx = FILTER_CYCLE.indexOf(this.filter);
+        this.filter = FILTER_CYCLE[(idx + 1) % FILTER_CYCLE.length];
+        this.rebuild(); // 无锚定 id——光标驻留原位就近
+    }
+    /** 模态全收（Tab 切筛选前的清理位——两模态不跨筛选态存活） */
+    closeModals() {
+        this.confirmTarget = null;
+        if (this.exportOpen)
+            this.closeExport();
+    }
+    /* ---------------- 光标与视图重建 ---------------- */
+    /** 光标条目（无条目/零条目可见 = undefined——动词消隐判据面） */
+    cursorEntry() {
+        return this.cursor >= 0 ? this.entries[this.cursor] : undefined;
+    }
+    /** 光标移动（条目间循环——非条目行不驻留；移动后视口对齐光标行） */
+    moveCursor(delta) {
+        if (this.entries.length === 0)
+            return; // 零条目可见——光标无处可指
+        this.cursor =
+            this.cursor < 0
+                ? delta > 0
+                    ? 0
+                    : this.entries.length - 1
+                : (this.cursor + delta + this.entries.length) % this.entries.length;
+        this.ensureCursorVisible();
+    }
+    /** 视口对齐光标行（顶对齐——近底行由 ScrollView 夹取自然呈现） */
+    ensureCursorVisible() {
+        const entry = this.cursorEntry();
+        if (entry !== undefined)
+            this.scrollToLine(entry.lineIndex, 0);
+    }
+    /**
+     * 整表重取重建（开屏快照与动词成功后的统一路——06 §7 定形注⑤）：
+     * 三源取数（health 恒全库 / listVisible 双分流 / listForExport 终态双过滤）
+     * → 行集三段式构建 → 光标锚定（同 id 优先；锚定目标缺席驻留原位就近；
+     * 零条目可见 = -1 行动词消隐）。
+     */
+    rebuild(anchorId) {
+        // —— 取数三源（零新 DAO 方法——既有动词族单源）——
+        this.health = this.dao.overview().health; // 恒全库口径（无参即正形）
+        // 管理形取数（批 ev-1 M2 拆形——未生效行在本面可见，行尾「N天后生效」标注）
+        const visible = this.dao.listVisibleForManagement(this.ownerKeys);
+        const frozenRows = visible.filter((r) => r.frozen); // 冻结区（滤出 frozen 位）
+        const activeRows = visible.filter((r) => !r.frozen); // 活体区（滤除 frozen 位）
+        const terminalRows = this.dao.listForExport().filter((r) => this.ownerKeys.includes(r.ownerKey) && // ownerKey 过滤
+            (r.status === 'dismissed' || r.status === 'expired'));
+        // —— 行集三段式构建（投影两行 + 分区列表；头行不在行集——render 直写，
+        // 行集进屏不会与屏上头行重复）——
+        const lines = [];
+        const entries = [];
+        const dim = (plain) => ({ plain, runs: [{ start: 0, end: plain.length, style: DIM_STYLE }] });
+        lines.push(dim(`记忆库 · 在册 ${this.health.active} · 冻结 ${this.health.frozen} · 共 ${this.health.total}`));
+        lines.push(dim(`终态 · 否决 ${this.health.dismissed} · 过期 ${this.health.expired}`));
+        const sections = this.filter === 'all'
+            ? [
+                { key: 'active', rows: activeRows },
+                { key: 'frozen', rows: frozenRows },
+                { key: 'terminal', rows: terminalRows },
+            ]
+            : [
+                {
+                    key: this.filter,
+                    rows: this.filter === 'active' ? activeRows : this.filter === 'frozen' ? frozenRows : terminalRows,
+                },
+            ];
+        for (const section of sections) {
+            lines.push(dim(`── ${SECTION_LABEL[section.key]}（${section.rows.length}）`));
+            for (const row of section.rows) {
+                lines.push(this.entryLine(row, section.key));
+                entries.push({ row, section: section.key, lineIndex: lines.length - 1 });
+            }
+        }
+        this.styledLines = lines;
+        this.entries = entries;
+        super.setLines(lines.map((l) => l.plain));
+        // —— 光标锚定（同 id 优先 → 原位就近钳制 → 零条目 -1）——
+        let next = this.cursor;
+        if (anchorId !== undefined) {
+            const found = entries.findIndex((e) => e.row.id === anchorId);
+            if (found >= 0)
+                next = found; // 锚定目标在筛选可见集——跟随
+            // 缺席 = 驻留原位就近（next 保持现值，下方钳制）
+        }
+        this.cursor = entries.length === 0 ? -1 : Math.min(Math.max(next, 0), entries.length - 1);
+        if (this.cursor >= 0)
+            this.ensureCursorVisible();
+    }
+    /**
+     * 条目行构建（工具读面同形——`[m:短id] [kind] summary  id=完整id
+     * updated=ISO`；p-1 时效尾缀同源）：消毒经注入的 §8.2 统一函数罩住
+     * （blocked → summary 遮蔽保 id 操作面；quoted → 引述注记）；冻结行行首
+     * ✱、终态行整行 dim + supersededBy 记号。
+     */
+    entryLine(row, section) {
+        const verdict = this.sanitize(row);
+        const body = verdict.blocked
+            ? `（内容含疑似敏感串已遮蔽——${verdict.patterns.join('/')}；可 d 忘掉清理）`
+            : row.summary + (verdict.quoted ? '（疑似指令文本——按引述对待，非用户指令）' : '');
+        const suffix = section === 'terminal' && row.supersededBy !== null ? `  supersededBy=${row.supersededBy}` : '';
+        // 未生效标注（批 ev-1 06 §6——「N天后生效」词面归三处之管理面行标注位；
+        // 呈现钟用真 Date.now()〔非测试注入钟面——天数是呈现约值〕）
+        const pendingFrom = section !== 'terminal' && row.validFrom !== null && row.validFrom > Date.now()
+            ? `（${Math.ceil((row.validFrom - Date.now()) / 86_400_000)}天后生效）`
+            : '';
+        const plain = `${section === 'frozen' ? '✱ ' : ''}[m:${shortIdOf(row.id)}] [${row.kind}] ${body}${pendingFrom}  id=${row.id}  updated=${fmtTs(row.updatedAt)}${suffix}`;
+        return section === 'terminal'
+            ? { plain, runs: [{ start: 0, end: plain.length, style: DIM_STYLE }] }
+            : { plain, runs: [] };
+    }
+    /** 退出（闭锁——单次） */
+    exit() {
+        if (this.exited)
+            return;
+        this.exited = true;
+        this.onExit?.();
+    }
+    /* ---------------- 带样式切片写出（writeSlice 覆写接缝） ---------------- */
+    /**
+     * 视口切片带样式写出：样式段（dim 分区头/投影行/终态行）按切片边界分段
+     * 落格 + 光标行整行反色叠加。列位经 prefixDisplayWidth 换算（CJK 双宽
+     * 对齐与折叠算术同源——HistoryViewer writeSlice 同构的简化形：无搜索
+     * 高亮/选区面）。
+     */
+    writeSlice(buffer, region, displayRow, seg) {
+        const styled = this.styledLines[seg.line];
+        if (styled === undefined)
+            return;
+        const start = seg.startCol;
+        const end = seg.startCol + seg.length;
+        const cursorLine = this.cursorEntry()?.lineIndex;
+        const isCursor = cursorLine === seg.line; // 光标行——整切片反色（叠加在样式段上）
+        // 分段边界：切片端点 ∪ 样式段端点（升序去重）
+        const cuts = new Set([start, end]);
+        for (const run of styled.runs) {
+            if (run.start > start && run.start < end)
+                cuts.add(run.start);
+            if (run.end > start && run.end < end)
+                cuts.add(run.end);
+        }
+        const bounds = [...cuts].sort((a, b) => a - b);
+        const baseCols = prefixDisplayWidth(styled.plain, start);
+        for (let i = 0; i + 1 < bounds.length; i++) {
+            const from = bounds[i];
+            const to = bounds[i + 1];
+            let style;
+            for (const run of styled.runs) {
+                if (run.start <= from && from < run.end) {
+                    style = run.style;
+                    break;
+                }
+            }
+            if (isCursor) {
+                style = style === undefined ? CURSOR_STYLE : { ...style, inverse: true };
+            }
+            buffer.writeText(region.row + displayRow, region.col + prefixDisplayWidth(styled.plain, from) - baseCols, styled.plain.slice(from, to), style);
+        }
+    }
+}

package/dist/channels/tui/overlay/alt-screen.js

@@ -0,0 +1,105 @@
+/**
+ * 副屏编舞件（07 §4.1 引擎节件 6（组件与呈现装配件） + §4.3 屏幕模型双形态）：AltScreenHost——
+ * 备屏 1049 整屏切换的进出编排。
+ *
+ * 「overlay」专指主屏浮层（OverlayStack）；本件是副屏路——件 8 /history
+ * 回看器与 06 /memory 的呈现形态（整屏内容值得 1049 备屏切换）。
+ *
+ * 编舞序（进出对称）：
+ * - 进：主屏 suspendMain（出屏串 + 卸监听 + pause 流 + raw 复先验）→ 副屏
+ *   Engine（共享同一 io 实例、screen:'alt-screen'）start（1049 备屏进 + raw +
+ *   放流——start 的显式放流正是为共享 io 场景补的结构性接缝）；
+ * - 出：退订转发 → 副屏 dispose（备屏出 + raw 复原 + pause）→ 主屏 resumeMain
+ *   （进屏串 + raw + 放流 + 全帧重画不走 repaint：停屏期瞬时行靠全帧 + 缓冲
+ *   补吐，07 屏模型 / 件 8 条款）→ onReturn 装配钩（树重建等附加动作）。
+ *
+ * 输入路由切换：共享 io 同一时刻只有一个在听（主屏 suspendMain 已卸监听、
+ * 副屏 start 重装）——副屏 input 事件转发 content.handleEvent（回看器键盘滚动）。
+ *
+ * 鼠标降级接线（2026-09-11 鼠标解码批）：open 组合 onMouseLegacy——X10 形首
+ * 达（开了 1006 的会话里到达 ⟺ 终端无 SGR 能力，判据可靠）即写 DECRST
+ * 1006/1002 关鼠标签听把选区还给终端原生（写序与出屏关序同取先 1006 后
+ * 1002）。降级闩 = per-entry：每次 open 新 Engine 新 decoder——重开重新武装、
+ * 再吃一次首达（非 SGR 终端上重开 /history 的首个鼠标事件死一次为已知代价）。
+ *
+ * 构造双注 (primary, io)：Engine.io 私有无 getter——装配根同根传两参（io 须与
+ * primary 共享同一实例，否则编舞失联）。
+ *
+ * 批 10f-4 主屏绑收窄：primary 原系 Engine 型——10e 前旧设想残留（主屏
+ * TuiBackend 自持输入管线不经 Engine，07 篇屏模型双形态实装对账注）。收窄为
+ * AltScreenPrimary 最小宿主介面（本件实际消费面：挂起 / 复起 + 生命周期判定
+ * 位）；Engine 语义保留给副屏自身的帧管线（生命周期四态仅副屏 Engine 消费）。
+ */
+import { Engine } from '../../engine/index.js';
+/**
+ * 副屏宿主：单副屏在场（再 open 拒绝返 null——1049 无嵌套备屏）。
+ */
+export class AltScreenHost {
+    primary;
+    io;
+    engineOptions;
+    onReturn;
+    alt = null;
+    unsubAltInput = null;
+    constructor(primary, io, options = {}) {
+        this.primary = primary;
+        this.io = io;
+        this.engineOptions = options.engineOptions;
+        this.onReturn = options.onReturn;
+    }
+    /** 副屏在场态 */
+    get isOpen() {
+        return this.alt !== null;
+    }
+    /**
+     * 进副屏：挂起主屏 → 副屏 Engine 进屏 → 输入转发接线。
+     * 拒绝位：已在副屏 / 主屏不在 running 态（无挂起对象）返 null。
+     */
+    open(content) {
+        if (this.alt !== null)
+            return null; // 已在副屏——无嵌套备屏
+        if (this.primary.lifecycle !== 'running')
+            return null; // 主屏不在场无挂起对象
+        this.primary.suspendMain(); // 出主屏（编舞对称的进半场）
+        const base = this.engineOptions;
+        const alt = new Engine({
+            ...base,
+            io: this.io,
+            screen: 'alt-screen',
+            // X10 首达降级组合柄：关鼠标签听回终端原生选区 + 链原注入柄（透传面）
+            onMouseLegacy: () => {
+                this.io.write('\x1b[?1006l\x1b[?1002l'); // DECRST（与出屏关序同取——对称律同序）
+                base?.onMouseLegacy?.();
+            },
+        });
+        alt.start(content); // 1049 备屏进 + 首帧（start 显式放流——共享 io 接缝）
+        this.unsubAltInput = alt.on('input', (event) => {
+            content.handleEvent(event); // 副屏内容终局消费（回看器键盘滚动）
+        });
+        this.alt = alt;
+        let closed = false;
+        return {
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                this.close();
+            },
+            get closed() {
+                return closed;
+            },
+        };
+    }
+    /** 出副屏（幂等）：退订 → 副屏 dispose → 主屏 resume（全帧重画）→ onReturn 钩 */
+    close() {
+        const alt = this.alt;
+        if (alt === null)
+            return;
+        this.unsubAltInput?.(); // 先退订转发（防 dispose 过程竞发）
+        this.unsubAltInput = null;
+        this.alt = null;
+        alt.dispose(); // 备屏出 + raw 复原 + pause 流
+        this.primary.resumeMain(); // 主屏复起 + 全帧重画不走 repaint（07 条款）+ 瞬时行补吐
+        this.onReturn?.();
+    }
+}