mocode-ai 1.3.9 → 1.4.0

package/dist/ui/layout-internal/input-paint.js

@@ -0,0 +1,365 @@
+// L2 输入框绘制:开窗 / 折行 / 反白 / dim 占位,以及 repaint 总刷新。
+// 从 layout-internal/core.ts 按依赖分层拆出;可变运行态集中在 ./state.ts。
+import { stdout } from 'node:process';
+import { charWidth, displayWidth, truncateDisplay, truncateDisplayHead, wrapByDisplayWidth } from '../render.js';
+import { ui } from '../theme.js';
+import * as content from '../content.js';
+import { state } from './state.js';
+import { esc, cup, getGeo, setRegion, runningCaretPos } from './screen.js';
+import { SEL_OPEN, SEL_OFF, normalizeInputSelection, inputViewSig } from './selection.js';
+import { composeSpinnerLine, composeModelLine, composePlanLines, drawStatusBar } from './statusbar.js';
+// ── 输入区(底栏输入框 + 向上菜单)──
+/**
+ * 把逻辑行软折成可视行并开窗(超 maxInputRows 时滑窗保光标可见)。返回可见可视行文本(已折行)+
+ * 光标在窗口内行号 + 光标在该可视行的显示列 + 所需输入行数 + 窗口起始全局可视行号。
+ *
+ * 光标可视位置按各行**实际**显示宽度逐行累加(不按 width×行号 除法):宽字符(CJK=2)在行尾放不下时
+ * 整字折到下行、本行留尾空格,简单除法会把光标算偏;逐行累加 displayWidth 才与终端实际光标一致。
+ */
+function windowInputVis(lines, cursorLine, cursorCol, cols, promptW, rows) {
+    const W = Math.max(1, cols - promptW);
+    const lineVis = lines.map((l) => wrapByDisplayWidth(l, W));
+    const flat = [];
+    for (const lv of lineVis)
+        for (const r of lv)
+            flat.push(r);
+    const totalVis = flat.length;
+    // 光标在其逻辑行内的可视行 / 可视列
+    const clRows = lineVis[cursorLine] ?? [''];
+    let curVisRow = 0;
+    let curVisCol = cursorCol;
+    {
+        let acc = 0;
+        for (let i = 0; i < clRows.length; i++) {
+            const rw = displayWidth(clRows[i]);
+            if (cursorCol <= acc + rw) {
+                curVisRow = i;
+                curVisCol = cursorCol - acc;
+                break;
+            }
+            acc += rw;
+            curVisRow = i;
+            curVisCol = cursorCol - acc;
+        }
+    }
+    // 光标绝对可视行
+    let curAbs = 0;
+    for (let i = 0; i < cursorLine; i++)
+        curAbs += lineVis[i].length;
+    curAbs += curVisRow;
+    const maxInputRows = Math.max(1, Math.floor(rows * 0.4));
+    let startVis = 0;
+    if (totalVis > maxInputRows) {
+        startVis = Math.max(0, Math.min(curAbs - maxInputRows + 1, totalVis - maxInputRows));
+    }
+    const showCount = Math.min(maxInputRows, totalVis);
+    return {
+        visRows: flat.slice(startVis, startVis + showCount),
+        visLine: curAbs - startVis,
+        cursorVisCol: curVisCol,
+        inputRows: showCount,
+        startVis,
+    };
+}
+/** 把 lines 按 W 做软折,返回 lineVis;供 paintInput 高亮预算用。与 windowInputVis 复用 wrap 算法。 */
+function visInputLines(lines, W) {
+    return lines.map((l) => wrapByDisplayWidth(l, W));
+}
+/**
+ * 给纯文本(无 ANSI,来自 wrap 后的可视段)做"显示列区间"高亮,返回插入 SEL_OPEN/SEL_OFF 后的字符串。
+ * 输入字段 vis 段宽 = displayWidth(seg),clipStart/clipEnd 单位 = display_col。
+ * 与 highlightRange 等价语义但省去 ANSI split(纯文本无 SGR),更省。
+ */
+function highlightWithinRow(seg, clipStart, clipEnd) {
+    if (clipEnd <= clipStart)
+        return seg;
+    let out = '';
+    let w = 0;
+    let opened = false;
+    for (const ch of seg) {
+        const cw = charWidth(ch.codePointAt(0) ?? 0);
+        if (!opened && w >= clipStart && w < clipEnd) {
+            out += SEL_OPEN;
+            opened = true;
+        }
+        if (opened && w >= clipEnd) {
+            out += SEL_OFF;
+            opened = false;
+        }
+        out += ch;
+        w += cw;
+    }
+    if (opened)
+        out += SEL_OFF;
+    return out;
+}
+/**
+ * 画输入区:擦旧菜单 → (必要时)setRegion → 画状态行 + 输入行 + 向上菜单,光标留输入框(dim 时回续写位)。
+ * prompt.ts 每次按键调;enterInputMode / enterRunningMode 也调(空 / dim)。
+ */
+export function paintInput(view) {
+    if (!state.active || !state.base)
+        return;
+    state.lastView = view;
+    // 失效检测:lastView 文本若有变化(键输入/AI 续写)→ 选区锚点不再有效,清掉避免「错位反白」。
+    // 内容区选区用 content 自己的锚,与 lastView 无关,不动。
+    if (state.inputSelection) {
+        const sig = inputViewSig(view);
+        if (sig !== state.lastInputSig) {
+            state.inputSelection = null;
+        }
+        state.lastInputSig = sig;
+    }
+    else {
+        state.lastInputSig = inputViewSig(view);
+    }
+    const preGeo = getGeo();
+    // 累积本帧所有 cup/clearLine/文本,末尾一次写出——避免「擦旧菜单」与「重画」分多次 write 时,
+    // 终端把中间空白渲染出来 → 菜单/面板切换时闪烁(↑↓ 导航每次 redraw 都全帧擦后重画)。
+    let buf = '';
+    // 1. 擦旧菜单(用上次记录的起始行 + 行数,与本次几何无关——setRegion 不动屏幕内容)
+    if (state.lastMenuRows > 0) {
+        for (let i = 0; i < state.lastMenuRows; i++) {
+            buf += cup(state.lastMenuStartRow + i, 1) + esc.clearLine;
+        }
+        state.lastMenuRows = 0;
+    }
+    // 2. 算输入可视行(软折行)+ 必要时 setRegion。dim=运行态占位:单行不折行。
+    const promptW = displayWidth(view.prompt);
+    const vis = view.dim
+        ? {
+            visRows: [view.lines[0] ?? ''],
+            visLine: 0,
+            cursorVisCol: 0,
+            inputRows: 1,
+            startVis: 0,
+        }
+        : windowInputVis(view.lines, view.cursorLine, view.cursorCol, preGeo.cols, promptW, preGeo.rows);
+    const needFooterH = 5 + vis.inputRows + (state.planRows - 1); // 1 虚拟空 + 1 spinner 行 + 1 上线 + 输入行 + 1 下线 + 1 model 行 + plan 多出的行数
+    let g = preGeo;
+    if (needFooterH !== state.footerH) {
+        // setRegion 自己 write(DECSTBM + 清行 + 归位):先把已累积的擦除 flush 出去保序(擦除用的是旧几何的
+        // lastMenuStartRow,须在 setRegion 改区域前落地),再 setRegion,之后 2b..6 重新累积。
+        // footerH 不变时(常见:单行输入 / 菜单切换 / ↑↓ 导航)整帧一次 write,终端原子应用,无中间空白→不闪烁。
+        if (buf) {
+            stdout.write(buf);
+            buf = '';
+        }
+        g = setRegion(needFooterH);
+    }
+    // 2b. 重画内容末行(底栏上一行)从缓冲:防 WT 边距漏影(状态行重复到该行),并保证该行显正确内容
+    {
+        const slice = content.sliceFromEnd(state.scrollOffset, g.contentBottom);
+        const line = slice[g.contentBottom - 1] ?? '';
+        buf += cup(g.contentBottom, 1) + esc.clearLine + line;
+    }
+    // 2c. 虚拟空行(内容区与状态栏之间的视觉间隔,属底栏非内容):
+    //     - 无活跃 plan:清空保留作分隔(原设计)
+    //     - 有活跃 plan:渲染 plan chip(整帧重画时也要更新,避免 listener 漏触发后残留)
+    //     - plan 过长:占 2 行(planRows=2),spinner/上线/输入行随之整体下移 1 行
+    //     paintInput 与 drawStatusBar 共享同一 planRows 模块态,setRegion 已据此把脚栏撑高。
+    {
+        const planBuf = composePlanLines(state.base, preGeo.cols);
+        for (let i = 0; i < planBuf.length; i++) {
+            buf += cup(g.contentBottom + 1 + i, 1) + esc.clearLine + planBuf[i];
+        }
+        // 计划行从 2 行降到 1 行(plan 当前很短):清掉残留的第 2 行,不留尾巴。
+        if (planBuf.length < state.planRows && state.planRows === 2) {
+            buf += cup(g.contentBottom + 2, 1) + esc.clearLine;
+            state.planRows = 1;
+        }
+        // plan 从非空变成空(已结算/无活跃段)时,清掉残留的 plan 行 1。
+        // 上面 for 循环在 planBuf.length===0 时不写任何 cup,需要显式清一行回到「虚拟空行」。
+        if (planBuf.length === 0) {
+            buf += cup(g.contentBottom + 1, 1) + esc.clearLine;
+        }
+    }
+    // 3. 状态行:spinner 行 + model 行(两行式底栏)
+    const spinnerRow = g.contentBottom + 1 + state.planRows; // plan 占 planRows 行(1 或 2),spinner 紧跟其后
+    const modelRow = g.rows; // 屏底:model 行
+    const status = { ...state.base, status: state.statusText, spinnerFrame: state.spinnerFrame };
+    buf += cup(spinnerRow, 1) + esc.clearLine + composeSpinnerLine(status, g.cols);
+    buf += cup(modelRow, 1) + esc.clearLine + composeModelLine(status, g.cols);
+    // 3b. 上线(输入框顶):满屏宽细线 ─(cyan),框住输入区上边界
+    buf += cup(g.contentBottom + 2 + state.planRows, 1) + esc.clearLine + ui.accent + '─'.repeat(g.cols) + ui.reset;
+    // 4. 输入行(g.contentBottom+3+planRows .. rows-1)——按可视行画,首行带 prompt、其余缩进 promptW
+    const firstInputRow = g.contentBottom + 3 + state.planRows;
+    const inputRowsAvail = vis.inputRows; // 脚栏总高 - 1(spinner) - 1(上 sep) - 1(下 sep) - 1(model) - planRows
+    const indent = ' '.repeat(promptW);
+    // 光标:不画反白块/假光标——输入框走终端真光标(WT / VSCode 终端默认竖线/闪烁块,
+    // 各终端表现略不同但都贴合 IME 候选气泡且不再"挡住字符")。真光标位置由下方第 6 步 cup 写。
+    // 保留 view.caret=false 路径给 picker 等非文本输入:把真光标定位到 hint 末尾。
+    const inpSel = normalizeInputSelection(); // 已签名检测失效,这里看到的要么有效要么 null
+    // 预算 (visRow -> line) 用于高亮:与 inputScreenToInputPos 的反推同源(flat → line + segInLine)
+    const colW = Math.max(1, preGeo.cols - promptW);
+    const lineVisArr = visInputLines(view.lines, colW);
+    const flatInput = [];
+    for (const lv of lineVisArr)
+        for (const r of lv)
+            flatInput.push(r);
+    const flatToLine = [];
+    for (let li = 0; li < lineVisArr.length; li++) {
+        const segs = lineVisArr[li];
+        let acc = 0;
+        for (let s = 0; s < segs.length; s++) {
+            flatToLine.push({ line: li, segInLine: s, inLineDisplayCol: acc });
+            acc += displayWidth(segs[s]);
+        }
+        if (segs.length === 0)
+            flatToLine.push({ line: li, segInLine: 0, inLineDisplayCol: 0 });
+    }
+    for (let i = 0; i < inputRowsAvail; i++) {
+        const line = vis.visRows[i] ?? '';
+        const r = firstInputRow + i;
+        const prefix = vis.startVis === 0 && i === 0 ? view.prompt : indent;
+        let text;
+        if (view.dim) {
+            text = renderDimInputRow(view.prompt, line, view.placeholder ?? '', g.cols);
+        }
+        else {
+            text = `${prefix}${line}`;
+            // 空输入引导:INPUT 态缓冲为空时,在首行画 dim ghost 占位(「输入 / 查看命令…」);
+            // 任何按键都会改变缓冲 → 下一帧 isEmpty=false → 占位自然消失,无需额外擦除逻辑。
+            if (!line && view.placeholder && vis.startVis === 0 && i === 0) {
+                const avail = Math.max(0, preGeo.cols - promptW);
+                text = `${prefix}${ui.dim}${truncateDisplay(view.placeholder, avail)}${ui.reset}`;
+            }
+            // 输入框反白叠层:仅当 paintInput 不是 dim(运行态 typeahead 不参与选区,避免干扰 IME 气泡),
+            // 且该可视段所属的逻辑行落在 inpSel 区间内 → 高亮行内 [colStart,colEnd) 段。
+            if (inpSel) {
+                const flatIdx = vis.startVis + i;
+                const m = flatIdx < flatToLine.length ? flatToLine[flatIdx] : flatToLine[flatToLine.length - 1];
+                if (m.line >= inpSel.startLine && m.line <= inpSel.endLine) {
+                    const seg = flatInput[flatIdx] ?? '';
+                    const segW = displayWidth(seg);
+                    const colStart = m.line === inpSel.startLine ? inpSel.startCol - m.inLineDisplayCol : 0;
+                    const colEnd = m.line === inpSel.endLine ? inpSel.endCol - m.inLineDisplayCol : segW;
+                    if (colStart < segW && colEnd > colStart) {
+                        // 对 seg(纯文本无 ANSI)做行内高亮:在 [clipStart, clipEnd) 之间插 SEL_OPEN/SEL_OFF。
+                        text = `${prefix}${highlightWithinRow(seg, Math.max(0, colStart), Math.min(segW, colEnd))}`;
+                    }
+                }
+            }
+        }
+        buf += cup(r, 1) + esc.clearLine + text;
+    }
+    // 4b. 下线(输入框底):满屏宽细线 ─(cyan),在 model 行上一行(model 行占屏底 rows)
+    buf += cup(g.rows - 1, 1) + esc.clearLine + ui.accent + '─'.repeat(g.cols) + ui.reset;
+    // 5. 向上菜单(画在内容区底,底栏正上方)
+    if (view.menu && view.menu.lines.length > 0) {
+        const menuRows = Math.min(view.menu.lines.length, g.contentBottom);
+        const menuStart = g.contentBottom - menuRows + 1;
+        for (let i = 0; i < menuRows; i++) {
+            buf += cup(menuStart + i, 1) + esc.clearLine + view.menu.lines[i];
+        }
+        state.lastMenuStartRow = menuStart;
+        state.lastMenuRows = menuRows;
+    }
+    // 6. 光标
+    if (view.dim) {
+        // 运行态(回尾 / 滚动回看均):真光标归输入框光标位(供 IME 锚定,气泡在输入框而非内容区)。
+        // 滚动态也归输入框——上滑看历史时打字,IME 候选气泡须锚到输入框(conhost IME 不跟随 cup 后续移动,
+        // 须让打字前光标已在输入框);viewport 锁历史靠 scrollOffset,不靠光标位置。
+        const p = runningCaretPos();
+        buf += cup(p.row, p.col);
+    }
+    else {
+        const r = firstInputRow + vis.visLine;
+        const col = promptW + vis.cursorVisCol + 1;
+        buf += cup(r, col);
+    }
+    if (buf)
+        stdout.write(buf); // 整帧一次写出(footerH 不变时):终端原子应用,无中间空白→不闪烁
+}
+/**
+ * 渲染运行态输入行(dim):❯ + (有打字:dim 文本 + 末尾反白块状光标;无打字:反白光标在起点 + dim 占位 ghost)。
+ * 光标是「画出来」的反白块(非真终端光标)——真光标仍归续写位,避开与 contentWrite/drawStatusBar 争用;
+ * 输入行在 RUNNING 期间只被按键回显重画(流式/spinner 不碰这行),故画上去的光标能稳住。
+ * 内容截断到 cols-promptW-1(留 ❯ 与光标各 1 cell),防超长软折行写穿下线。
+ */
+function renderDimInputRow(prompt, text, placeholder, cols) {
+    const promptW = displayWidth(prompt);
+    // dim 态(运行中打字):不画反白块——反白块视觉占位是 INPUT 态真光标的旧版,这里真光标本
+    // 就被隐起来(IME 锚定需要,见 contentMode),在 dim 文本后硬塞个反白空格会"白块闪烁"。
+    // 用户读 dim 文本本身就能定位打字边界;真光标在 INPUT 态显形(竖线/闪烁块,跟终端默认一致)。
+    const contentW = Math.max(0, cols - promptW);
+    if (text.length > 0) {
+        // 有打字:❯ dim + 文本(dim,超长从头部截断保留尾部——光标恒在末尾,须始终看到刚打的字)
+        return `${ui.dim}${prompt}${truncateDisplayHead(text, contentW)}${ui.reset}`;
+    }
+    // 空:❯ dim + dim 占位 ghost(taking the full row)
+    const p = placeholder ? truncateDisplay(placeholder, contentW) : '';
+    return `${ui.dim}${prompt}${p}${ui.reset}`;
+}
+/**
+ * 单行运行态滑窗:以光标为中心,向左右扩展填满 contentW-1(留 1 cell 给光标),
+ * 返回可见子串与光标在子串内的显示列。保证光标恒可见,且不软折行(运行态输入框恒单行,
+ * 不触发 setRegion/ED,避免流式期间底栏抖动)。
+ */
+function windowSingleLine(text, cursor, contentW) {
+    const n = text.length;
+    if (n === 0)
+        return { shown: '', curDisp: 0 };
+    const totalDisp = displayWidth(text);
+    if (totalDisp <= contentW)
+        return { shown: text, curDisp: displayWidth(text.slice(0, cursor)) };
+    let i = cursor;
+    let j = cursor;
+    let w = 0;
+    const cw = (idx) => charWidth(text.codePointAt(idx) ?? 0);
+    while (i > 0 && w + cw(i - 1) <= contentW - 1) {
+        w += cw(i - 1);
+        i--;
+    }
+    while (j < n && w + cw(j) <= contentW - 1) {
+        w += cw(j);
+        j++;
+    }
+    return { shown: text.slice(i, j), curDisp: displayWidth(text.slice(i, cursor)) };
+}
+/**
+ * 运行态 typeahead 回显:定向写输入行(底栏输入框),非 dim(与空闲态同色)、光标可任意位置、单行。
+ * 只 cup 输入行 + clearLine + 文本 + cup 真光标到编辑位——不调 setRegion(运行中禁多行,避免 DECSTBM 抖动)、
+ * 不重画状态行/contentBottom、不用 ED。同步 lastView 为运行视图(非 dim),使 scrollBy/resize 的 repaint
+ * 仍显当前回显 + 光标。空且带 placeholder 时显 dim ghost(提示 agent 状态;非用户输入,不违反"打字不变灰")。
+ * 选区高亮由 paintInput 路径(paint 时鼠标拖选)承担,此处轻量不重复实现。
+ */
+export function paintRunningInput(text, cursor, placeholder) {
+    if (!state.active || !state.base)
+        return;
+    const g = getGeo();
+    const inputRow = g.contentBottom + 3 + state.planRows; // 运行态 footerH 随 plan 行数动态(6 或 7)
+    const promptW = displayWidth('❯ ');
+    const contentW = Math.max(1, g.cols - promptW);
+    let outLine;
+    let curCol; // 输入框内的显示列(不含 prompt)
+    if (text.length === 0 && placeholder) {
+        outLine = `${ui.dim}❯ ${truncateDisplay(placeholder, contentW)}${ui.reset}`;
+        curCol = 0;
+    }
+    else {
+        const { shown, curDisp } = windowSingleLine(text, cursor, contentW);
+        outLine = `❯ ${shown}`; // 正常色 —— 运行态打字与空闲态一致
+        curCol = curDisp;
+    }
+    state.lastView = {
+        prompt: '❯ ',
+        lines: [text],
+        placeholder,
+        cursorLine: 0,
+        cursorCol: cursor,
+        menu: null,
+        // 不置 dim:运行态输入框与空闲态同色、可任意位置编辑
+    };
+    const cursorCol = Math.min(g.cols, promptW + curCol + 1);
+    stdout.write(cup(inputRow, 1) + esc.clearLine + outLine + cup(inputRow, cursorCol));
+}
+/** 重画当前视图(resize / 内部用)。 */
+export function repaint() {
+    if (!state.active || !state.base)
+        return;
+    if (state.lastView)
+        paintInput(state.lastView);
+    else
+        drawStatusBar();
+}

package/dist/ui/layout-internal/screen.js

@@ -0,0 +1,128 @@
+// L0 屏幕原语:ANSI 序列表 / CUP / 几何 / 滚动区域 / 续写位归位。
+// 从 layout-internal/core.ts 按依赖分层拆出;可变运行态集中在 ./state.ts。
+import { stdout } from 'node:process';
+import { displayWidth, truncateDisplayHead } from '../render.js';
+import { state } from './state.js';
+/**
+ * 全屏 TUI 布局:alt screen + 单滚动区域(内容区)+ 区域外固定底栏(状态行 + 输入框)。
+ *
+ * 只依赖最成熟、Windows(WT / conhost)最稳的 ANSI 子集:
+ *  - alt screen        \x1B[?1049h / \x1B[?1049l
+ *  - DECSTBM 滚动区域  \x1B[<top>;<bottom>r   (区域内写满自动在区域内滚动,区域外底栏不被顶)
+ *  - 逐行擦除          \x1B[2K / \x1B[K        (菜单 / 清屏,绝不用 ED \x1B[J 做边界擦除)
+ *  - CUP 绝对定位      \x1B[<row>;<col>H
+ * 不用原点模式(\x1B[?6h)、不依赖 ED 边界、不用 DECSC/DECRC、不用 IL/DL/SU/SD——这些在 conhost 上不可靠。
+ *
+ * 续写位(contentRow / contentCol)由 contentWrite 按字符宽度 + 折行模拟跟踪;CUP 到它即可随时回到内容续写位,
+ * 故底栏刷新(状态行 / spinner)无需保存/恢复光标——CUP 回续写位即可。
+ *
+ * 关键洞察:RUNNING 态也支持 typeahead 输入与滚动回看。INPUT 态光标常驻输入框;RUNNING 态光标在续写位,
+ * 运行中打的字经 paintRunningInput(非 dim)回显(占位行换成已打文本,光标停在编辑位,不与流式争用);
+ * 运行中可滚动回看——contentWrite 在 scrollOffset>0 时只喂缓冲不物理写(否则新流式覆盖 viewport 历史行),
+ * 回尾(scrollOffset===0)才 cup 续写位写出。两态切换不重设区域(底栏高度恒 = 2),仅多行输入换行撑高时才 setRegion。
+ *
+ * 非 TTY:全部空操作,contentWrite 退化为 stdout.write,与改造前内联行为一致。
+ */
+// 可变运行态全部集中在 ./state.ts 的共享单例;本文件只留纯常量与函数。
+/** 是否处于全屏 TUI(alt screen)激活态。非 TTY / 嵌入宿主(host)下为 false。
+ *  子 agent 等异步路径据此判断能否把中间过程实时写入主内容区。 */
+export function isTuiActive() {
+    return state.active;
+}
+export const esc = {
+    altOn: '\x1B[?1049h',
+    altOff: '\x1B[?1049l',
+    // 完整鼠标追踪:1000=按键(按下/释放)+ 1002=拖动 motion + 1006=SGR 编码。
+    // 拿到按下/拖动/释放的坐标后,由 layout 在应用层维护选区(mouse.ts 重组报表 → handleMouseEvent):
+    //  - 左键:内容区按下开选区、拖动扩展(触边自动翻页跨屏)、释放只留高亮,不自动复制;输入框不响应
+    //    (不干扰正常打字/焦点)。
+    //  - 右键(单击,press→release 未拖动):落在输入框 → 读剪贴板贴入(setPasteHandler 回调);
+    //    落在内容区 → 复制当前选区(若有)到剪贴板(clipboard.ts),静默不弹提示。
+    //  - 滚轮报表(button&64)转 scrollBy。
+    // 代价:终端原生框选被鼠标捕获接管——想用终端原生选区可按住 Shift(多数终端放行)。
+    // 1007l=关闭 Alternate Scroll Mode:VSCode xterm.js 进 alt screen(?1049)后默认开 1007,
+    // 滚轮发 Up/Down 方向键而非 SGR 鼠标报表;不关的话滚轮会绕过 mouse.swallow 直接触发
+    // prompt 的历史导航(recallPrevious/recallNext)→ "输入框打字时滚轮跳到上一条历史消息"。
+    mouseOn: '\x1B[?1007l\x1B[?1000h\x1B[?1002h\x1B[?1006h',
+    mouseOff: '\x1B[?1006l\x1B[?1002l\x1B[?1000l\x1B[?1007h', // 关:反序;末尾恢复 1007(交还终端默认)
+    cursorShow: '\x1B[?25h',
+    cursorHide: '\x1B[?25l',
+    clearLine: '\x1B[2K',
+    home: '\x1B[H',
+};
+/** CUP(光标绝对定位),钳到 >=1。 */
+export function cup(row, col) {
+    return `\x1B[${Math.max(1, Math.round(row))};${Math.max(1, Math.round(col))}H`;
+}
+export function getGeo(fh = state.footerH) {
+    const rows = stdout.rows || 24;
+    const cols = stdout.columns || 80;
+    const f = Math.max(1, Math.min(fh, rows - 1));
+    return {
+        rows,
+        cols,
+        footerH: f,
+        contentTop: 1,
+        contentBottom: Math.max(1, rows - f),
+    };
+}
+/** (重)设滚动区域 [1, rows-footerH];设完 \x1B[H 归位(conhost 设 DECSTBM 时光标留旧位置行为未定义)。 */
+export function setRegion(fh) {
+    const rows = stdout.rows || 24;
+    const oldBottom = Math.max(1, rows - state.footerH);
+    const g = getGeo(fh);
+    state.footerH = g.footerH;
+    if (state.active) {
+        stdout.write(`\x1B[1;${g.contentBottom}r`); // DECSTBM: top=1, bottom=contentBottom
+        // 底栏缩小:原底栏行变回内容区,清掉残留底栏文本(否则提交多行后旧输入残留在底部)
+        if (g.contentBottom > oldBottom) {
+            let p = '';
+            for (let r = oldBottom + 1; r <= g.contentBottom; r++) {
+                p += cup(r, 1) + esc.clearLine;
+            }
+            stdout.write(p);
+        }
+        stdout.write(esc.home);
+    }
+    if (state.contentRow > g.contentBottom)
+        state.contentRow = g.contentBottom; // 底栏撑高挤掉内容:钳到新区底
+    return g;
+}
+/** 运行态真光标(隐藏)的归位点 = 输入框光标位:行 = 动态 contentBottom+3+planRows(resize 安全)。
+ *  非 dim 运行态(与空闲态同色、可任意位置编辑)→ 归当前编辑位,供 IME 锚定气泡到光标处;
+ *  dim 占位(空 + placeholder)兼容态→ 归输入框起点。供 IME 锚定。 */
+export function runningCaretPos() {
+    const g = getGeo();
+    const row = g.contentBottom + 3 + state.planRows;
+    if (state.lastView && !state.lastView.dim) {
+        const promptW = displayWidth(state.lastView.prompt);
+        const line = state.lastView.lines[state.lastView.cursorLine] ?? '';
+        const before = line.slice(0, state.lastView.cursorCol);
+        const col = Math.min(g.cols, promptW + displayWidth(before) + 1);
+        return { row, col };
+    }
+    const text = state.lastView?.dim ? (state.lastView.lines[0] ?? '') : '';
+    const contentW = Math.max(0, g.cols - 3); // ❯ =2 + 光标=1
+    const w = displayWidth(truncateDisplayHead(text, contentW));
+    return { row, col: Math.min(g.cols, 2 + w + 1) };
+}
+export function contentMode() {
+    if (!state.active)
+        return;
+    const g = getGeo();
+    if (state.mode === 'running') {
+        // 运行态(回尾 / 滚动回看均):真光标归输入框光标位(供 IME 锚定,气泡不跟流式跑)。
+        // 滚动态也归输入框——否则上滑看历史时打字,IME 候选气泡会锚到内容区底而非输入框
+        // (conhost IME 不跟随 cup 后续移动,须让打字前光标已在输入框)。
+        const p = runningCaretPos();
+        stdout.write(cup(p.row, p.col));
+    }
+    else {
+        // INPUT 态:回尾归续写位,滚动回看归内容区底(viewport 锁历史;INPUT 态无 IME 锚定需求)
+        stdout.write(cup(state.scrollOffset === 0 ? state.contentRow : g.contentBottom, state.scrollOffset === 0 ? state.contentCol : 1));
+    }
+}
+/** 运行态用户是否在打字(近期有按键)——是则暂停流式物理写(contentWrite/drawStatusBar/paintLiveAtCursor 跳过物理写),光标留输入框,IME 候选窗稳定不跟流式跑。 */
+export function isStreamingPaused() {
+    return state.mode === 'running' && Date.now() < state.userActiveUntil;
+}

package/dist/ui/layout-internal/scroll.js

@@ -0,0 +1,152 @@
+// L2 滚动与 viewport:回看偏移 / 重画可视区 / 滚轮 / 轮首滚动锁。
+// 从 layout-internal/core.ts 按依赖分层拆出;可变运行态集中在 ./state.ts。
+import { stdout } from 'node:process';
+import { displayWidth, truncateDisplayHead, truncateAnsi, ansiDisplayWidth, padEndAnsiBackground } from '../render.js';
+import { ui } from '../theme.js';
+import * as content from '../content.js';
+import { state } from './state.js';
+import { esc, cup, getGeo, runningCaretPos } from './screen.js';
+import { normalizeSelection, highlightRange } from './selection.js';
+import { repaint } from './input-paint.js';
+// ── 纯常量(可变运行态在 state.ts)──
+const SCROLL_LOCK_MS = 400; // 锁时长:覆盖 OS 缓冲残留 + 常规滚轮惯性;LLM TTFB 多 >200ms,不影响轮中后段滚动
+/** Sticky banner 的 ❯ 前缀(同 repl 的 PROMPT;常量统一视觉)。 */
+const BANNER_PROMPT = '❯ ';
+export const WHEEL_LINES = 3; // 滚轮每格滚动行数
+// ── viewport 滚动回看(Phase 2)──
+/** 是否处于滚动回看态(offset>0,内容区显历史)。prompt 据此在非滚动键时回尾。 */
+export function isScrolled() {
+    return state.scrollOffset > 0;
+}
+/** viewport 窗口起点绝对行索引(0-based,对齐 content.sliceFromEnd 的 start)。 */
+export function viewportAbsStart() {
+    const g = getGeo();
+    const total = content.totalRows();
+    const end = Math.max(0, total - state.scrollOffset);
+    return Math.max(0, end - g.contentBottom);
+}
+/** 屏行(1-based,内容区内)→ 绝对缓冲行索引(0-based)。 */
+export function screenRowToAbsLine(row) {
+    return viewportAbsStart() + (row - 1);
+}
+/**
+ * 重画内容区 viewport:按 scrollOffset 取缓冲尾窗,逐行 cup+clearline+rowtext 映射到屏 1..contentBottom。
+ * offset=0 即尾窗(== 实时屏,resize / 回尾时用)。清行含 contentBottom——顺带擦 WT 边距漏影(状态行重复)。
+ * 有活跃选区(鼠标拖拽中)时,对选中范围套反白——纯视觉,不影响缓冲内容。
+ *
+ * **滚动回看 sticky banner(输入框上方固定标题的姊妹需求)**:
+ * 仅在 scrollOffset > 0 时,在 viewport 第 1 行顶部叠一行横幅,显示「当前 viewport 顶上
+ * 那条用户消息」的预览。用户上滑翻历史时,横幅内容随滚动到的 user→agent 对应关系变化;
+ * 滑到底(offset===0)自动消失(实时屏可见,无需 banner)。满宽 padding + 底色对比反色
+ * 提示「↑ 这是上方滚走的内容」,不与内容区行内 SGR 冲突。
+ */
+export function repaintViewport() {
+    if (!state.active)
+        return;
+    const g = getGeo();
+    const h = g.contentBottom;
+    const slice = content.sliceFromEnd(state.scrollOffset, h);
+    const sel = normalizeSelection();
+    // viewportAbsStart() 无选区时也用:sticky banner 必须按真实窗口头算,不能降级 0(否则 banner 永不出现)。
+    const absStart = viewportAbsStart();
+    // sticky banner:仅 scrollOffset>0 时显示;offset=0 即实时屏,user 气泡本来就在视口内,无需 banner。
+    const bannerText = state.scrollOffset > 0 ? content.lastUserMessageBefore(absStart) : null;
+    const BANNER_ROW = 1; // 横幅占 viewport 第 1 行(会把原第 1 行内容遮住 —— 1 行换"我在看啥"的可读性,可接受)
+    let p = '';
+    for (let r = 1; r <= h; r++) {
+        // 缓冲中的普通行（用户气泡、工具摘要等）仍按写入时宽度保存。窗口缩窄后若原样
+        // 输出会触发终端 auto-wrap，打破“一条 buffer 行 = 一条屏幕物理行”。重画时统一
+        // 钳到当前列宽：宽度恢复后原内容仍在 buffer 中，可重新完整显示。
+        const rawLine = slice[r - 1] ?? '';
+        let line = truncateAnsi(rawLine, g.cols);
+        // 用户消息是在提交时按当时 cols 填满背景的普通物理行。放宽终端后，buffer 里的
+        // 尾部 reset 仍停在旧列宽，若只重画就会留下截图中的灰条短一截。识别 userBg 行并
+        // 在 reset 后重新开启同一背景补齐新宽度；不改 buffer，后续缩放仍可从原文重算。
+        if (rawLine.includes(ui.userBg)) {
+            line = padEndAnsiBackground(line, g.cols, ui.userBg, ui.reset);
+        }
+        if (bannerText && r === BANNER_ROW) {
+            // banner 行:满宽 userBg + ❯ + 单行截断(多行 ⏎ 折叠)+ userBg 补到底 + 底线分隔短横
+            const cols = g.cols;
+            const oneLine = bannerText.replace(/\s*\n\s*/g, ' ⏎ ');
+            const promptW = displayWidth(BANNER_PROMPT);
+            const avail = Math.max(1, cols - promptW);
+            const truncated = truncateDisplayHead(oneLine, avail);
+            const padCount = Math.max(0, cols - promptW - displayWidth(truncated));
+            line = `${ui.userBg}${BANNER_PROMPT}${truncated}${' '.repeat(padCount)}${ui.reset}`;
+        }
+        else if (sel) {
+            const absLine = absStart + r - 1;
+            if (absLine >= sel.startLine && absLine <= sel.endLine) {
+                const lineW = ansiDisplayWidth(line);
+                const colStart = absLine === sel.startLine ? sel.startCol : 0;
+                const colEnd = absLine === sel.endLine ? sel.endCol : lineW;
+                line = highlightRange(line, colStart, colEnd);
+            }
+        }
+        p += cup(r, 1) + esc.clearLine + line;
+    }
+    // 光标:合并进同一 write(若拆成两次 stdout.write,行写完光标会暂留 contentRow/contentBottom,
+    // 流式每 chunk 调一次 → contentBottom 频繁现块状光标白块;打字第一键赶上这瞬 IME 候选气泡锚到 contentBottom)。
+    // 运行态(回尾 / 滚动均)归输入框 runningCaretPos(供 IME 锚定);INPUT 态回尾归续写位 / 滚动归内容区底。
+    if (state.mode === 'running') {
+        const c = runningCaretPos();
+        p += cup(c.row, c.col);
+    }
+    else {
+        p += cup(state.scrollOffset === 0 ? state.contentRow : g.contentBottom, state.scrollOffset === 0 ? state.contentCol : 1);
+    }
+    stdout.write(p);
+}
+/** 滚动 delta 行(正=往新、负=往旧);钳 [0, max(0, total-contentBottom)];变则重画 + 刷底栏(显指示、光标回输入框)。 */
+export function scrollBy(delta) {
+    if (!state.active)
+        return;
+    if (Date.now() < state.scrollLockUntil)
+        return; // 轮首滚动锁:吸收发消息前后 stdin 残留滚轮事件,保 agent 输出从底部开始
+    const g = getGeo();
+    const total = content.totalRows();
+    const maxOff = Math.max(0, total - g.contentBottom);
+    const off = Math.max(0, Math.min(state.scrollOffset + delta, maxOff));
+    if (off === state.scrollOffset)
+        return;
+    // 进入滚动态前清掉 spinner 内联帧:滚动态由状态行心跳兜底,内联帧若残留会卡在历史视图某行。
+    if (state.scrollOffset === 0 && off > 0 && state.frameRow) {
+        stdout.write(cup(Math.min(state.frameRow, g.contentBottom), state.frameCol) + esc.clearLine);
+        state.frameRow = 0;
+        state.frameCol = 0;
+    }
+    state.scrollOffset = off;
+    repaintViewport();
+    repaint();
+}
+/**
+ * 滚动一格「滚轮量」(WHEEL_LINES 行):dir=+1 看更旧(等同 ↑ / PgUp),dir=-1 看更新(等同 ↓ / PgDn)。
+ * 鼠标滚轮与键盘裸 ↑/↓ 共用同一入口,保证两者行为与步长恒一致。
+ */
+export function scrollWheel(dir) {
+    scrollBy(dir > 0 ? WHEEL_LINES : -WHEEL_LINES);
+}
+/** 回尾(offset=0);仅当原本滚动过才重画(避免每轮 enterRunningMode 闪烁)。 */
+export function resetScroll() {
+    if (state.scrollOffset === 0)
+        return;
+    state.scrollOffset = 0;
+    repaintViewport();
+    repaint();
+}
+/** 发消息轮首短时锁住滚动:吸收 stdin 残留滚轮事件(发消息前后的滚轮惯性 / OS 缓冲延迟到达),
+ *  防 resetScroll 回尾后被 onRunningKey 接到的残留事件重新滚上去——致 agent 输出进缓冲、显示在历史区。
+ *  锁只挡 scrollBy(滚轮 / PgUp-PgDn);不影响 contentWrite 写屏(offset=0 时照常物理写,agent 输出从底部开始)。
+ *  默认 SCROLL_LOCK_MS 后自动解锁;enterInputMode(轮末)也清锁。用户轮中后段仍可上滑(满足"输出时能看历史")。 */
+export function lockScrollToBottom(ms = SCROLL_LOCK_MS) {
+    state.scrollLockUntil = Date.now() + ms;
+}
+/** 解锁(轮末 enterInputMode / 测试用)。 */
+export function unlockScroll() {
+    state.scrollLockUntil = 0;
+}
+/** 轮首滚动锁是否生效(测试用)。 */
+export function isScrollLocked() {
+    return Date.now() < state.scrollLockUntil;
+}