berry-agent 0.1.0-alpha.1

package/dist/channels/tui/editor/editor-model.js

@@ -0,0 +1,543 @@
+/**
+ * 多行输入编辑模型（Editor 件族核心——纯状态机，零渲染依赖）。
+ *
+ * 07 §4.1 引擎节件 6（组件与呈现装配件） 多行输入件条款的语义载体：字素光标算术（永不落半字）、
+ * 词级删除、undo（上限 100）、输入历史（100 帽 + draft 保底）、IME 预编辑
+ * 挂起态、垂直移动 sticky 列（显示列制——CJK 双宽对齐）。机制语义承 pi
+ * Editor（裁 ⓪ 从零重写：粘贴标记机制不采纳——本仓规范「多行粘贴整段入框
+ * 呈现」；视觉列按显示宽非码元差）。
+ *
+ * 坐标系：cursorCol 为 UTF-16 下标（字符串切片高效），但一切移动 / 删除
+ * 原语经 visual-lines 件的字素边界函数——结构上保证光标恒在字素边界。
+ */
+import { buildVisualLineMap, colAtDisplayColumn, findVisualLineAt, nextGraphemeBoundary, prefixDisplayWidth, prevGraphemeBoundary, } from './visual-lines.js';
+import { findWordBackward, findWordForward } from './word-nav.js';
+import { UndoStack } from './undo-stack.js';
+/** 输入历史帽（07 呈现面件 2 语义：输入历史 100 条） */
+export const HISTORY_LIMIT = 100;
+/** undo 上限（码面定值——与历史帽同值，规范只钉「有上限」） */
+export const UNDO_LIMIT = 100;
+/** 文本规范化：CRLF / CR → LF（粘贴与程序设值共用路） */
+function normalizeText(text) {
+    return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+/**
+ * 编辑模型：状态自持、变更方法驱动；onChange 通知（渲染侧组装请求重绘）。
+ */
+export class EditorModel {
+    state = { lines: [''], cursorLine: 0, cursorCol: 0 };
+    undoStack = new UndoStack(UNDO_LIMIT);
+    /** undo 合并判据（fish 式）：连续词字符插入合并一单元；空白段、词接空白后各独立成步 */
+    lastAction = null;
+    history = [];
+    historyIndex = -1; // -1 = 不在浏览态
+    historyDraft = null;
+    /** 垂直移动 sticky 列（显示列——非垂直移动清空） */
+    preferredVisualCol = null;
+    /** IME 预编辑挂起段（null = 无组字；渲染呈现、不并入正文） */
+    preedit = null;
+    /** 布局宽（视图渲染时回写——垂直导航的折行依据，与渲染同宽） */
+    layoutWidth = 80;
+    /** 变更通知（订阅面——由持有方装配） */
+    onChange = null;
+    /* ---------------- 查询面 ---------------- */
+    getText() {
+        return this.state.lines.join('\n');
+    }
+    getLines() {
+        return [...this.state.lines];
+    }
+    getCursor() {
+        return { line: this.state.cursorLine, col: this.state.cursorCol };
+    }
+    /** IME 预编辑挂起段（渲染面消费） */
+    get pendingPreedit() {
+        return this.preedit;
+    }
+    /** 视觉行映射（视图渲染与视口滚动共用——与模型内部导航同宽同源） */
+    visualLines() {
+        return buildVisualLineMap(this.state.lines, this.layoutWidth);
+    }
+    /** 光标所在视觉行下标 */
+    currentVisualLine(map) {
+        return findVisualLineAt(map, this.state.cursorLine, this.state.cursorCol);
+    }
+    /** 光标的视觉列（显示列——含预编辑宽：组字期光标在预编辑段尾） */
+    cursorDisplayColumn() {
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        let cols = prefixDisplayWidth(line, this.state.cursorCol);
+        if (this.preedit !== null)
+            cols += prefixDisplayWidth(this.preedit, this.preedit.length);
+        return cols;
+    }
+    /** 布局宽回写（视图渲染时——垂直导航用，须与渲染宽一致） */
+    setLayoutWidth(width) {
+        this.layoutWidth = Math.max(1, width);
+    }
+    /* ---------------- 设值与提交 ---------------- */
+    /** 整体设值（程序面：清历史浏览 + undo 快照 + 光标归尾） */
+    setText(text) {
+        this.exitHistoryBrowsing();
+        const normalized = normalizeText(text);
+        if (this.getText() !== normalized)
+            this.pushUndo();
+        this.state = { lines: normalized.split('\n'), cursorLine: 0, cursorCol: 0 };
+        const last = this.state.lines[this.state.lines.length - 1] ?? '';
+        this.state.cursorLine = this.state.lines.length - 1;
+        this.state.cursorCol = last.length;
+        this.lastAction = null;
+        this.notify();
+    }
+    /**
+     * 提交：取 trim 后全文、全清（状态 / undo / 历史浏览 / 预编辑）返回。
+     * 历史入册归调用方（组件层 onSubmit 消费方决定）。
+     */
+    submit() {
+        const result = this.getText().trim();
+        this.state = { lines: [''], cursorLine: 0, cursorCol: 0 };
+        this.undoStack.clear();
+        this.lastAction = null;
+        this.preedit = null;
+        this.preferredVisualCol = null;
+        this.exitHistoryBrowsing();
+        this.notify();
+        return result;
+    }
+    /* ---------------- 插入路（text 游程 / IME 提交 / 粘贴共用） ---------------- */
+    /**
+     * 光标处插入文本（可多行——拆行落位、光标落插入段尾）。
+     * undo 合并：连续非空白段合并一单元（打字游程）、空白段独立成步。
+     */
+    insertText(text) {
+        if (text === '')
+            return;
+        this.exitHistoryBrowsing();
+        const isWhitespace = text.trim().length === 0;
+        if (isWhitespace || this.lastAction !== 'type-word')
+            this.pushUndo();
+        this.lastAction = isWhitespace ? 'type-whitespace' : 'type-word';
+        this.insertTextRaw(normalizeText(text));
+        this.notify();
+    }
+    /** 原子插入（无 undo 编排——内部路） */
+    insertTextRaw(text) {
+        const inserted = text.split('\n');
+        const current = this.state.lines[this.state.cursorLine] ?? '';
+        const before = current.slice(0, this.state.cursorCol);
+        const after = current.slice(this.state.cursorCol);
+        if (inserted.length === 1) {
+            this.state.lines[this.state.cursorLine] = before + inserted[0] + after;
+            this.setCursorCol(this.state.cursorCol + inserted[0].length);
+        }
+        else {
+            this.state.lines = [
+                ...this.state.lines.slice(0, this.state.cursorLine),
+                before + inserted[0],
+                ...inserted.slice(1, -1),
+                inserted[inserted.length - 1] + after,
+                ...this.state.lines.slice(this.state.cursorLine + 1),
+            ];
+            this.state.cursorLine += inserted.length - 1;
+            this.setCursorCol(inserted[inserted.length - 1].length);
+        }
+    }
+    /**
+     * 整 token 代换（补全弹层唯一写路径）：指定行 [start,end) 段整段替换、
+     * 光标落代换尾。独立 undo 步（不与前后输入合并）、退出历史浏览、清预编辑
+     * 与水平粘滞链。
+     */
+    replaceToken(line, start, end, replacement) {
+        this.exitHistoryBrowsing();
+        this.pushUndo();
+        this.preedit = null;
+        this.preferredVisualCol = null;
+        this.lastAction = null;
+        const text = this.state.lines[line] ?? '';
+        this.state.lines[line] = text.slice(0, start) + replacement + text.slice(end);
+        this.state.cursorLine = line;
+        this.state.cursorCol = start + replacement.length;
+        this.notify();
+    }
+    /* ---------------- 删除族（字素算术 + 行合并） ---------------- */
+    /** 退格：删光标前一字素；行首与前行合并（换行删除语义） */
+    backspace() {
+        this.lastAction = null;
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol > 0) {
+            this.pushUndo();
+            const boundary = prevGraphemeBoundary(line, this.state.cursorCol);
+            this.state.lines[this.state.cursorLine] = line.slice(0, boundary) + line.slice(this.state.cursorCol);
+            this.setCursorCol(boundary);
+        }
+        else if (this.state.cursorLine > 0) {
+            this.pushUndo();
+            const prev = this.state.lines[this.state.cursorLine - 1] ?? '';
+            this.state.lines[this.state.cursorLine - 1] = prev + line;
+            this.state.lines.splice(this.state.cursorLine, 1);
+            this.state.cursorLine--;
+            this.setCursorCol(prev.length);
+        }
+        else {
+            return; // 空框行首——无操作（不空通知）
+        }
+        this.exitHistoryBrowsing();
+        this.notify();
+    }
+    /** 前删：删光标处一字素；行尾与下一行合并 */
+    deleteForward() {
+        this.lastAction = null;
+        this.exitHistoryBrowsing();
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol < line.length) {
+            this.pushUndo();
+            const boundary = nextGraphemeBoundary(line, this.state.cursorCol);
+            this.state.lines[this.state.cursorLine] = line.slice(0, this.state.cursorCol) + line.slice(boundary);
+        }
+        else if (this.state.cursorLine < this.state.lines.length - 1) {
+            this.pushUndo();
+            const next = this.state.lines[this.state.cursorLine + 1] ?? '';
+            this.state.lines[this.state.cursorLine] = line + next;
+            this.state.lines.splice(this.state.cursorLine + 1, 1);
+        }
+        else {
+            return; // 末行行尾——无操作
+        }
+        this.notify();
+    }
+    /** 删至行首：光标前段整删；行首与前行合并 */
+    deleteToLineStart() {
+        this.lastAction = null;
+        this.exitHistoryBrowsing();
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol > 0) {
+            this.pushUndo();
+            this.state.lines[this.state.cursorLine] = line.slice(this.state.cursorCol);
+            this.setCursorCol(0);
+        }
+        else if (this.state.cursorLine > 0) {
+            this.pushUndo();
+            const prev = this.state.lines[this.state.cursorLine - 1] ?? '';
+            this.state.lines[this.state.cursorLine - 1] = prev + line;
+            this.state.lines.splice(this.state.cursorLine, 1);
+            this.state.cursorLine--;
+            this.setCursorCol(prev.length);
+        }
+        else {
+            return;
+        }
+        this.notify();
+    }
+    /** 删至行尾：光标后段整删；行尾与下一行合并 */
+    deleteToLineEnd() {
+        this.lastAction = null;
+        this.exitHistoryBrowsing();
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol < line.length) {
+            this.pushUndo();
+            this.state.lines[this.state.cursorLine] = line.slice(0, this.state.cursorCol);
+        }
+        else if (this.state.cursorLine < this.state.lines.length - 1) {
+            this.pushUndo();
+            const next = this.state.lines[this.state.cursorLine + 1] ?? '';
+            this.state.lines[this.state.cursorLine] = line + next;
+            this.state.lines.splice(this.state.cursorLine + 1, 1);
+        }
+        else {
+            return;
+        }
+        this.notify();
+    }
+    /** 词级退删：删光标前一词（词边界 = word-nav 单源）；行首与前行合并 */
+    deleteWordBackward() {
+        this.lastAction = null;
+        this.exitHistoryBrowsing();
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol === 0) {
+            if (this.state.cursorLine > 0) {
+                this.pushUndo();
+                const prev = this.state.lines[this.state.cursorLine - 1] ?? '';
+                this.state.lines[this.state.cursorLine - 1] = prev + line;
+                this.state.lines.splice(this.state.cursorLine, 1);
+                this.state.cursorLine--;
+                this.setCursorCol(prev.length);
+                this.notify();
+            }
+            return;
+        }
+        this.pushUndo();
+        const boundary = findWordBackward(line, this.state.cursorCol);
+        this.state.lines[this.state.cursorLine] = line.slice(0, boundary) + line.slice(this.state.cursorCol);
+        this.setCursorCol(boundary);
+        this.notify();
+    }
+    /** 词级前删：删光标后一词；行尾与下一行合并 */
+    deleteWordForward() {
+        this.lastAction = null;
+        this.exitHistoryBrowsing();
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol >= line.length) {
+            if (this.state.cursorLine < this.state.lines.length - 1) {
+                this.pushUndo();
+                const next = this.state.lines[this.state.cursorLine + 1] ?? '';
+                this.state.lines[this.state.cursorLine] = line + next;
+                this.state.lines.splice(this.state.cursorLine + 1, 1);
+                this.notify();
+            }
+            return;
+        }
+        this.pushUndo();
+        const boundary = findWordForward(line, this.state.cursorCol);
+        this.state.lines[this.state.cursorLine] = line.slice(0, this.state.cursorCol) + line.slice(boundary);
+        this.notify();
+    }
+    /* ---------------- 换行 ---------------- */
+    /** 插入换行：当前行光标处劈开、光标落新行首 */
+    addNewLine() {
+        this.lastAction = null;
+        this.exitHistoryBrowsing();
+        this.pushUndo();
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        this.state.lines[this.state.cursorLine] = line.slice(0, this.state.cursorCol);
+        this.state.lines.splice(this.state.cursorLine + 1, 0, line.slice(this.state.cursorCol));
+        this.state.cursorLine++;
+        this.setCursorCol(0);
+        this.notify();
+    }
+    /* ---------------- 移动族（字素边界 + 视觉行 sticky 列） ---------------- */
+    /** 左移一字素（行首 wrap 到前行行尾） */
+    moveLeft() {
+        this.lastAction = null;
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol > 0) {
+            this.setCursorCol(prevGraphemeBoundary(line, this.state.cursorCol));
+        }
+        else if (this.state.cursorLine > 0) {
+            this.state.cursorLine--;
+            this.setCursorCol((this.state.lines[this.state.cursorLine] ?? '').length);
+        }
+    }
+    /** 右移一字素（行尾 wrap 到下一行行首） */
+    moveRight() {
+        this.lastAction = null;
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol < line.length) {
+            this.setCursorCol(nextGraphemeBoundary(line, this.state.cursorCol));
+        }
+        else if (this.state.cursorLine < this.state.lines.length - 1) {
+            this.state.cursorLine++;
+            this.setCursorCol(0);
+        }
+    }
+    /** 上移一视觉行（sticky 列——显示列制双宽对齐） */
+    moveUp() {
+        this.lastAction = null;
+        const map = this.visualLines();
+        this.moveToVisualLine(map, this.currentVisualLine(map) - 1);
+    }
+    /** 下移一视觉行 */
+    moveDown() {
+        this.lastAction = null;
+        const map = this.visualLines();
+        this.moveToVisualLine(map, this.currentVisualLine(map) + 1);
+    }
+    /** 上 / 下翻页（页大小 = 视觉行数；光标随页夹取） */
+    pageUp(pageSize) {
+        this.lastAction = null;
+        const map = this.visualLines();
+        this.moveToVisualLine(map, this.currentVisualLine(map) - Math.max(1, pageSize));
+    }
+    pageDown(pageSize) {
+        this.lastAction = null;
+        const map = this.visualLines();
+        this.moveToVisualLine(map, this.currentVisualLine(map) + Math.max(1, pageSize));
+    }
+    /** 词向后移（行首 wrap 到前行行尾） */
+    moveWordBackward() {
+        this.lastAction = null;
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol === 0) {
+            if (this.state.cursorLine > 0) {
+                this.state.cursorLine--;
+                this.setCursorCol((this.state.lines[this.state.cursorLine] ?? '').length);
+            }
+            return;
+        }
+        this.setCursorCol(findWordBackward(line, this.state.cursorCol));
+    }
+    /** 词向前移（行尾 wrap 到下一行行首） */
+    moveWordForward() {
+        this.lastAction = null;
+        const line = this.state.lines[this.state.cursorLine] ?? '';
+        if (this.state.cursorCol >= line.length) {
+            if (this.state.cursorLine < this.state.lines.length - 1) {
+                this.state.cursorLine++;
+                this.setCursorCol(0);
+            }
+            return;
+        }
+        this.setCursorCol(findWordForward(line, this.state.cursorCol));
+    }
+    /** 行首 */
+    moveHome() {
+        this.lastAction = null;
+        this.setCursorCol(0);
+    }
+    /** 行尾 */
+    moveEnd() {
+        this.lastAction = null;
+        this.setCursorCol((this.state.lines[this.state.cursorLine] ?? '').length);
+    }
+    /**
+     * jump 词向：跳到指定字符的下 / 上一处出现（多行搜索、跳过光标当前位）。
+     * 无匹配光标不动。
+     */
+    jumpToChar(ch, direction) {
+        this.lastAction = null;
+        const isForward = direction === 'forward';
+        const step = isForward ? 1 : -1;
+        const end = isForward ? this.state.lines.length : -1;
+        for (let li = this.state.cursorLine; li !== end; li += step) {
+            const line = this.state.lines[li] ?? '';
+            const isCurrent = li === this.state.cursorLine;
+            const from = isCurrent ? (isForward ? this.state.cursorCol + 1 : this.state.cursorCol - 1) : undefined;
+            const idx = isForward ? line.indexOf(ch, from) : line.lastIndexOf(ch, from);
+            if (idx !== -1) {
+                this.state.cursorLine = li;
+                this.setCursorCol(idx);
+                return;
+            }
+        }
+    }
+    /* ---------------- undo ---------------- */
+    undo() {
+        this.exitHistoryBrowsing();
+        const snapshot = this.undoStack.pop();
+        if (!snapshot)
+            return;
+        this.state = snapshot;
+        this.lastAction = null;
+        this.preedit = null;
+        this.preferredVisualCol = null;
+        this.notify();
+    }
+    canUndo() {
+        return this.undoStack.length > 0;
+    }
+    /* ---------------- IME 预编辑 ---------------- */
+    /** 挂起 / 清除预编辑段（committed = false 增量路——渲染呈现不并入正文） */
+    setPreedit(text) {
+        this.preedit = text !== null && text.length > 0 ? text : null;
+    }
+    /* ---------------- 输入历史 ---------------- */
+    /** 入册（提交后调用）：trim 空不加、连续重复不加、100 帽 */
+    addToHistory(text) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        if (this.history[0] === trimmed)
+            return;
+        this.history.unshift(trimmed);
+        if (this.history.length > HISTORY_LIMIT)
+            this.history.pop();
+    }
+    /** 翻阅（-1 向旧 / +1 向新）：draft 保底、尽头 no-op */
+    navigateHistory(direction) {
+        this.lastAction = null;
+        if (this.history.length === 0)
+            return;
+        const newIndex = this.historyIndex - direction;
+        if (newIndex < -1 || newIndex >= this.history.length)
+            return;
+        // 首入浏览态：快照草稿（回新态时恢复未提交编辑）
+        if (this.historyIndex === -1 && newIndex >= 0) {
+            this.pushUndo();
+            this.historyDraft = structuredClone(this.state);
+        }
+        this.historyIndex = newIndex;
+        if (this.historyIndex === -1) {
+            const draft = this.historyDraft;
+            this.historyDraft = null;
+            if (draft) {
+                this.state = draft;
+                this.preferredVisualCol = null;
+                this.notify();
+            }
+        }
+        else {
+            // 向旧翻光标归首、向新翻归尾（浏览方向语义）
+            const text = this.history[this.historyIndex] ?? '';
+            const lines = text.split('\n');
+            this.state.lines = lines.length === 0 ? [''] : lines;
+            const goingOld = direction === -1;
+            this.state.cursorLine = goingOld ? 0 : this.state.lines.length - 1;
+            const target = this.state.lines[this.state.cursorLine] ?? '';
+            this.setCursorCol(goingOld ? 0 : target.length);
+            this.notify();
+        }
+    }
+    /** 退出浏览态（任何编辑动作先行——draft 弃） */
+    exitHistoryBrowsing() {
+        this.historyIndex = -1;
+        this.historyDraft = null;
+    }
+    /** 是否在历史浏览态（↑ 触发判据之一） */
+    isBrowsingHistory() {
+        return this.historyIndex > -1;
+    }
+    /** 空框判（↑ 触发判据之一） */
+    isEmpty() {
+        return this.state.lines.length === 1 && this.state.lines[0] === '';
+    }
+    /** 光标在首视觉行判（↑ 于首行顶端才触发历史——呈现面件 2 语义） */
+    isOnFirstVisualLine() {
+        return this.currentVisualLine(this.visualLines()) === 0;
+    }
+    /** 光标在末视觉行判（↓ 触发历史回新的判据） */
+    isOnLastVisualLine() {
+        const map = this.visualLines();
+        return this.currentVisualLine(map) === map.length - 1;
+    }
+    /* ---------------- 内部 ---------------- */
+    /** 非垂直移动统一清 sticky 列（所有光标落位走此路） */
+    setCursorCol(col) {
+        this.state.cursorCol = col;
+        this.preferredVisualCol = null;
+    }
+    /** 落位目标视觉行（sticky 列决策——显示列制；越界 no-op） */
+    moveToVisualLine(map, target) {
+        if (target < 0 || target >= map.length)
+            return;
+        const curIdx = this.currentVisualLine(map);
+        const curVL = map[curIdx];
+        const tgtVL = map[target];
+        const curLine = this.state.lines[curVL.line] ?? '';
+        // 源显示列（光标在本段内的显示列）
+        const curCols = prefixDisplayWidth(curLine, this.state.cursorCol) - prefixDisplayWidth(curLine, curVL.startCol);
+        // sticky 决策（pi 表简化形）：
+        // - 链中（源行已夹到尾）：目标放得下回 sticky 位（清链）、放不下保持夹尾（留链）；
+        // - 无链或编辑中途起链：源显示列放得下平移（不启链）、放不下落目标尾并起链
+        const preferred = this.preferredVisualCol;
+        let wantCols;
+        if (preferred !== null && curCols >= curVL.width) {
+            wantCols = Math.min(preferred, tgtVL.width);
+            this.preferredVisualCol = preferred > tgtVL.width ? preferred : null;
+        }
+        else {
+            wantCols = Math.min(curCols, tgtVL.width);
+            this.preferredVisualCol = curCols > tgtVL.width ? curCols : null;
+        }
+        const tgtLine = this.state.lines[tgtVL.line] ?? '';
+        // 显示列反查（相对段起点计——与 curCols 同坐标系；夹段宽，半字防线由反查内建）
+        const col = colAtDisplayColumn(tgtLine, tgtVL.startCol, wantCols);
+        this.state.cursorLine = tgtVL.line;
+        // 垂直落位直写（不经 setCursorCol——sticky 生命周期归本路，落位不得自清）
+        this.state.cursorCol = col;
+    }
+    pushUndo() {
+        this.undoStack.push(this.state);
+    }
+    notify() {
+        if (this.onChange !== null)
+            this.onChange(this.getText());
+    }
+}

package/dist/channels/tui/editor/editor-view.js

@@ -0,0 +1,140 @@
+import { prefixDisplayWidth } from './visual-lines.js';
+import { ACCENT_INDEX } from '../theme.js';
+import { ansiColor } from '../../engine/index.js';
+/** 边框字符（制表符单宽——写格按字素推进） */
+const BORDER_TOP_LEFT = '┌';
+const BORDER_TOP_RIGHT = '┐';
+const BORDER_BOTTOM_LEFT = '└';
+const BORDER_BOTTOM_RIGHT = '┘';
+const BORDER_H = '─';
+const BORDER_V = '│';
+/** 聚焦态边框样式（accent 定值——theme 单源） */
+const FOCUSED_BORDER = Object.freeze({ fg: ansiColor(ACCENT_INDEX) });
+/** 最大可视行数缺省（装配层按终端高 30% 注入覆盖——pi 同形 max(5, rows*0.3)） */
+const DEFAULT_MAX_VISIBLE_LINES = 8;
+/**
+ * 编辑器视图：模型只读消费 + 自持视口偏移；measure / render 双段协商。
+ */
+export class EditorView {
+    model;
+    focused = false;
+    /** 视口首行（视觉行下标——render 时对光标夹取自愈） */
+    scrollOffset = 0;
+    maxVisibleLines;
+    constructor(model, options = {}) {
+        this.model = model;
+        this.maxVisibleLines = Math.max(1, options.maxVisibleLines ?? DEFAULT_MAX_VISIBLE_LINES);
+    }
+    /** 聚焦态切换（事件路由裁决后由组件调用） */
+    setFocused(focused) {
+        this.focused = focused;
+    }
+    /** 量高：边框 2 + 视觉行数夹 maxVisibleLines（量高即分配承诺——不超卖） */
+    measure(width) {
+        this.model.setLayoutWidth(innerWidth(width));
+        const count = this.model.visualLines().length;
+        return 2 + Math.min(count, this.maxVisibleLines);
+    }
+    /** 落位渲染：边框 → 视口行 → 预编辑段 → 光标声明 */
+    render(buffer, region) {
+        const innerW = innerWidth(region.width);
+        const innerH = region.height - 2;
+        this.model.setLayoutWidth(innerW);
+        if (innerH <= 0 || innerW <= 0)
+            return; // 边框都容不下——防御位
+        const map = this.model.visualLines();
+        const cursorVL = this.model.currentVisualLine(map);
+        // 视口夹取自愈：光标恒可视（滚出上方提顶 / 滚出下方沉底）
+        this.scrollOffset = clampScroll(this.scrollOffset, cursorVL, innerH, map.length);
+        this.drawBorder(buffer, region, map.length);
+        this.drawContent(buffer, region, map, innerH);
+        this.drawCursor(buffer, region, map, cursorVL);
+    }
+    /* ---------------- 边框（含滚动指示） ---------------- */
+    drawBorder(buffer, region, totalLines) {
+        const style = this.focused ? FOCUSED_BORDER : undefined;
+        const lastRow = region.row + region.height - 1;
+        const lastCol = region.col + region.width - 1;
+        // 四角
+        buffer.setCell(region.row, region.col, BORDER_TOP_LEFT, style);
+        buffer.setCell(region.row, lastCol, BORDER_TOP_RIGHT, style);
+        buffer.setCell(lastRow, region.col, BORDER_BOTTOM_LEFT, style);
+        buffer.setCell(lastRow, lastCol, BORDER_BOTTOM_RIGHT, style);
+        // 横边（顶 / 底）
+        for (let c = region.col + 1; c < lastCol; c++) {
+            buffer.setCell(region.row, c, BORDER_H, style);
+            buffer.setCell(lastRow, c, BORDER_H, style);
+        }
+        // 竖边（左 / 右）
+        for (let r = region.row + 1; r < lastRow; r++) {
+            buffer.setCell(r, region.col, BORDER_V, style);
+            buffer.setCell(r, lastCol, BORDER_V, style);
+        }
+        // 滚动指示（有溢出才显——写入边框行右端、覆盖既有横边格）
+        const above = this.scrollOffset;
+        const below = totalLines - this.scrollOffset - (region.height - 2);
+        if (above > 0)
+            this.writeIndicator(buffer, region.row, lastCol, ` ↑${above}`, style);
+        if (below > 0)
+            this.writeIndicator(buffer, lastRow, lastCol, ` ↓${below}`, style);
+    }
+    /** 右端对齐写入指示文本（覆盖边框横格；越界由缓冲吸收） */
+    writeIndicator(buffer, row, lastCol, text, style) {
+        buffer.writeText(row, lastCol - text.length, text, style);
+    }
+    /* ---------------- 正文（视口内视觉行） ---------------- */
+    drawContent(buffer, region, map, innerH) {
+        const lines = this.model.getLines();
+        const preedit = this.model.pendingPreedit;
+        const cursor = this.model.getCursor();
+        const end = Math.min(map.length, this.scrollOffset + innerH);
+        for (let vi = this.scrollOffset; vi < end; vi++) {
+            const seg = map[vi];
+            const row = region.row + 1 + (vi - this.scrollOffset);
+            const line = lines[seg.line] ?? '';
+            const plain = line.slice(seg.startCol, seg.startCol + seg.length);
+            // 光标在本段且组字中：前缀 + 预编辑（下划线）+ 后缀三段呈现
+            if (preedit !== null &&
+                seg.line === cursor.line &&
+                cursor.col >= seg.startCol &&
+                cursor.col <= seg.startCol + seg.length) {
+                const prefix = line.slice(seg.startCol, cursor.col);
+                const suffix = line.slice(cursor.col, seg.startCol + seg.length);
+                const next = buffer.writeText(row, region.col + 1, prefix);
+                const afterPreedit = buffer.writeText(row, next, preedit, PREEDIT_STYLE);
+                buffer.writeText(row, afterPreedit, suffix);
+                continue;
+            }
+            buffer.writeText(row, region.col + 1, plain);
+        }
+    }
+    /* ---------------- 光标声明（聚焦态独占） ---------------- */
+    drawCursor(buffer, region, map, cursorVL) {
+        if (!this.focused)
+            return; // 非聚焦不声明——不抢其他交互件的本帧声明
+        const seg = map[cursorVL];
+        const cursor = this.model.getCursor();
+        const line = this.model.getLines()[seg.line] ?? '';
+        // 光标段内显示列（前缀宽差——宽字素边界由模型算术保证，落在首列）
+        const displayCol = prefixDisplayWidth(line, cursor.col) - prefixDisplayWidth(line, seg.startCol);
+        const preedit = this.model.pendingPreedit;
+        const preeditCols = preedit !== null ? prefixDisplayWidth(preedit, preedit.length) : 0;
+        buffer.setCursor(region.row + 1 + (cursorVL - this.scrollOffset), region.col + 1 + displayCol + preeditCols);
+    }
+}
+/** 预编辑段样式（下划线——组字中的挂起提示） */
+const PREEDIT_STYLE = Object.freeze({ underline: true });
+/** 内容区宽（左右边框各 1） */
+function innerWidth(width) {
+    return Math.max(0, width - 2);
+}
+/** 视口夹取：光标滚出上方提顶、滚出下方沉底；内容短于视口归零 */
+function clampScroll(offset, cursorVL, innerH, total) {
+    let next = offset;
+    if (cursorVL < next)
+        next = cursorVL;
+    if (cursorVL >= next + innerH)
+        next = cursorVL - innerH + 1;
+    const maxOffset = Math.max(0, total - innerH);
+    return Math.min(Math.max(0, next), maxOffset);
+}