berry-agent 0.1.0-alpha.1

package/dist/channels/tui/overlay/overlay.js

@@ -0,0 +1,57 @@
+/**
+ * 浮层栈：主屏帧的「后画段」与输入路由的「先吃段」。
+ *
+ * 装配序（每帧）：主树 render → renderAll（浮层覆盖其上）；
+ * 路由序（每键）：routeEvent（栈非空短路三序）→ UiBackend 命令 / 队列 / 输入框。
+ */
+export class OverlayStack {
+    entries = [];
+    /** 栈变更通知（开 / 关——装配层接重绘请求） */
+    onChange;
+    /** 在场浮层数 */
+    get size() {
+        return this.entries.length;
+    }
+    /** 在场浮层只读快照（栈底→栈顶——装配层量高遍历/测试观测面） */
+    get contents() {
+        return this.entries.map((entry) => entry.content);
+    }
+    /** 开层：压栈 + 返回句柄（幂等关闭归句柄） */
+    open(content, anchor) {
+        const entry = { content, anchor, closed: false };
+        this.entries.push(entry);
+        this.onChange?.();
+        return {
+            close: () => {
+                if (entry.closed)
+                    return;
+                entry.closed = true;
+                const idx = this.entries.indexOf(entry);
+                if (idx >= 0)
+                    this.entries.splice(idx, 1);
+                this.onChange?.();
+            },
+            get closed() {
+                return entry.closed;
+            },
+        };
+    }
+    /** 浮层渲染（主树渲染后调用——栈底先画、栈顶覆盖） */
+    renderAll(buffer) {
+        for (const entry of this.entries) {
+            const region = entry.anchor({ width: buffer.columns, height: buffer.rows });
+            entry.content.render(buffer, region);
+        }
+    }
+    /**
+     * 事件路由（模态独占）：栈顶先吃；**栈非空恒返 true**——未消费键不穿透
+     * 至三序（07 §4.3 overlay 占焦条款）。栈空返 false（无浮层归常态路由）。
+     */
+    routeEvent(event) {
+        const top = this.entries[this.entries.length - 1];
+        if (top === undefined)
+            return false;
+        top.content.handleEvent(event); // 消费与否都在层内终局（不穿透）
+        return true;
+    }
+}

package/dist/channels/tui/overlay/select-confirm.js

@@ -0,0 +1,156 @@
+import { ACCENT_INDEX } from '../theme.js';
+import { ansiColor } from '../../engine/index.js';
+import { prefixDisplayWidth } from '../editor/visual-lines.js';
+/** 保守取消值（select——空串与撤销面同语义） */
+export const SELECT_CANCELLED = '';
+/** 高亮行样式（整行反色——面板内最强存在感） */
+const ACTIVE_STYLE = Object.freeze({ inverse: true });
+/** 标题样式（accent 定值——theme 单源） */
+const TITLE_STYLE = Object.freeze({ fg: ansiColor(ACCENT_INDEX) });
+/** 说明段样式（dim） */
+const HINT_STYLE = Object.freeze({ dim: true });
+/** 无修饰单字符 / 命名键匹配 */
+function isPlainKey(e, key) {
+    return !e.ctrl && !e.alt && !e.shift && !e.meta && e.key === key;
+}
+/** 键事件窄化（其他事件形面板不消费） */
+function asKey(event) {
+    return event.kind === 'key' ? event : null;
+}
+/**
+ * 选择面板：单选浮层。onFinish 后赋（装配在 open 句柄后接线——闭包里关层）。
+ */
+export class SelectPanel {
+    /** 完成回调（Enter 选定 value / Esc 取消收 ''）——装配接线 */
+    onFinish;
+    activeIndex = 0;
+    done = false;
+    title;
+    options;
+    constructor(options) {
+        this.title = options.title;
+        this.options = options.options;
+    }
+    /** 量高：标题（有则 1）+ 选项行数（单行制——不折行，超宽截断归渲染） */
+    measure(width) {
+        void width; // 高与宽无关（截断不折行）
+        return (this.title !== undefined ? 1 : 0) + this.options.length;
+    }
+    /** 落位：铺底空格 → 标题 → 选项行（高亮反色 + 说明右对齐） */
+    render(buffer, region) {
+        // 铺底空格（写格覆盖——未写格会透出主树文字）
+        for (let r = 0; r < region.height; r++) {
+            for (let c = 0; c < region.width; c++) {
+                buffer.setCell(region.row + r, region.col + c, ' ');
+            }
+        }
+        let row = region.row;
+        if (this.title !== undefined) {
+            buffer.writeText(row, region.col, this.title, TITLE_STYLE);
+            row += 1;
+        }
+        for (let i = 0; i < this.options.length; i++, row++) {
+            const active = i === this.activeIndex;
+            const option = this.options[i];
+            // 前缀 + label 段（高亮行整段反色）
+            const prefix = active ? '❯ ' : '  ';
+            buffer.writeText(row, region.col, `${prefix}${option.label}`, active ? ACTIVE_STYLE : undefined);
+            // 说明段右对齐（dim 恒态——不随高亮变脸；按显示宽——CJK 段宽 ≠ 码位数）
+            if (option.hint !== undefined && option.hint.length > 0) {
+                const hintCols = prefixDisplayWidth(option.hint, option.hint.length);
+                buffer.writeText(row, region.col + region.width - hintCols, option.hint, HINT_STYLE);
+            }
+        }
+    }
+    /** 事件分发：完成态静默；↑/↓ 循环移动、Enter 选定、Esc 取消 */
+    handleEvent(event) {
+        const e = asKey(event);
+        if (e === null)
+            return true; // 面板占焦——非键事件（文本 / IME / 粘贴）层内终局
+        if (e.phase === 'release' || this.done)
+            return true;
+        if (e.ctrl || e.alt || e.shift || e.meta)
+            return true;
+        if (e.key === 'up') {
+            this.activeIndex = this.activeIndex === 0 ? this.options.length - 1 : this.activeIndex - 1;
+            return true;
+        }
+        if (e.key === 'down') {
+            this.activeIndex = this.activeIndex === this.options.length - 1 ? 0 : this.activeIndex + 1;
+            return true;
+        }
+        if (e.key === 'enter') {
+            this.finish(this.options[this.activeIndex]?.value ?? SELECT_CANCELLED);
+            return true;
+        }
+        if (e.key === 'escape') {
+            this.finish(SELECT_CANCELLED);
+            return true;
+        }
+        return true; // 其余键层内终局（模态独占——不穿透）
+    }
+    /** 单次完成路（触发后锁完成态） */
+    finish(value) {
+        if (this.done)
+            return;
+        this.done = true;
+        this.onFinish?.(value);
+    }
+}
+/**
+ * 确认面板：两键问答浮层（Enter/y → true、Esc/n → false——保守值 = 不动原状态）。
+ */
+export class ConfirmPanel {
+    /** 完成回调——装配接线（同 SelectPanel 形） */
+    onFinish;
+    done = false;
+    message;
+    confirmHint;
+    cancelHint;
+    constructor(options) {
+        this.message = options.message;
+        this.confirmHint = options.confirmHint ?? 'enter 确认';
+        this.cancelHint = options.cancelHint ?? 'esc 取消';
+    }
+    /** 量高：消息 1 + 键提示 1 */
+    measure(width) {
+        void width;
+        return 2;
+    }
+    /** 落位：铺底空格 → 消息 → 键提示（dim） */
+    render(buffer, region) {
+        for (let r = 0; r < region.height; r++) {
+            for (let c = 0; c < region.width; c++) {
+                buffer.setCell(region.row + r, region.col + c, ' ');
+            }
+        }
+        buffer.writeText(region.row, region.col, this.message);
+        buffer.writeText(region.row + 1, region.col, `${this.confirmHint} · ${this.cancelHint}`, HINT_STYLE);
+    }
+    /** 事件分发：Enter/y 确认、Esc/n 取消（保守值） */
+    handleEvent(event) {
+        const e = asKey(event);
+        if (e === null)
+            return true;
+        if (e.phase === 'release' || this.done)
+            return true;
+        if (e.ctrl || e.alt || e.shift || e.meta)
+            return true;
+        if (isPlainKey(e, 'enter') || isPlainKey(e, 'y')) {
+            this.finish(true);
+            return true;
+        }
+        if (isPlainKey(e, 'escape') || isPlainKey(e, 'n')) {
+            this.finish(false);
+            return true;
+        }
+        return true; // 其余键层内终局
+    }
+    /** 单次完成路 */
+    finish(confirmed) {
+        if (this.done)
+            return;
+        this.done = true;
+        this.onFinish?.(confirmed);
+    }
+}

package/dist/channels/tui/panels/todo-panel.js

@@ -0,0 +1,54 @@
+/**
+ * todo 面板（07 §4.1 呈现面件 4）——输入框上方紧凑面板。
+ *
+ * - 数据面纯呈现投影：items 全量快照经 `update()` 整体替换（真源 = 装配
+ *   注入的 todoFor——05 §1.1 todo/write 事件载荷的会话侧映射，webui SPA
+ *   同源折叠产物）；空表与 null/undefined 同为清板；
+ * - 条目四态记号：☐ 待办 / ◐ 进行中（activeForm 优先于 content——CC 式
+ *   文案）/ ☑ 已完成·暗淡 / ⊙ 缓办·暗淡；
+ * - 帽 6 条 + 溢出行「+ N 更多」（暗淡）；
+ * - 刷新时机归装配（TuiBackend 三时点 repaint / tool_execution_end /
+ *   agent_end——批 10e-2 已接线），件内零时钟零事件面。
+ */
+import { truncateToWidth } from '../../engine/index.js';
+/** 帽内条数（溢出行另计——spec 定形不预收数字者已实测定形 6） */
+const MAX_ITEMS = 6;
+/** 四态记号（呈现投影——07 §4.1 件 4 定形） */
+const STATUS_MARKS = Object.freeze({
+    pending: '☐',
+    'in-progress': '◐',
+    completed: '☑',
+    deferred: '⊙',
+});
+/** 暗淡两态（已完成 / 缓办——退场视觉语义） */
+const DIM_STATUSES = new Set(['completed', 'deferred']);
+/** todo 面板：条目快照 → 固定区行段（清板即零行——布局自洽） */
+export class TodoPanel {
+    items = [];
+    /** 快照整体替换（null / undefined / 空表同义——清板） */
+    update(items) {
+        this.items = items ?? [];
+    }
+    /** 量高：清板 0；帽内条数 + 溢出行 */
+    measure(width) {
+        void width; // 条目单行制——宽度不敏感（内容截断吸收）
+        if (this.items.length === 0)
+            return 0;
+        return Math.min(this.items.length, MAX_ITEMS) + (this.items.length > MAX_ITEMS ? 1 : 0);
+    }
+    /** 落位：每条一行（记号 + 空格 + 内容截断）；溢出行收尾 */
+    render(buffer, region) {
+        const visible = this.items.slice(0, MAX_ITEMS);
+        visible.forEach((item, i) => {
+            const dimmed = DIM_STATUSES.has(item.status);
+            // 进行中 activeForm 优先（缺席回落 content）
+            const content = item.status === 'in-progress' && item.activeForm !== undefined ? item.activeForm : item.content;
+            const row = `${STATUS_MARKS[item.status]} ${truncateToWidth(content, region.width - 2)}`;
+            buffer.writeText(region.row + i, region.col, row, dimmed ? { dim: true } : undefined);
+        });
+        const overflow = this.items.length - MAX_ITEMS;
+        if (overflow > 0) {
+            buffer.writeText(region.row + MAX_ITEMS, region.col, `+ ${overflow} 更多`, { dim: true });
+        }
+    }
+}

package/dist/channels/tui/panels/tool-progress-panel.js

@@ -0,0 +1,93 @@
+/**
+ * 工具实时进度面板（07 §4.1 呈现面件 5）——状态行上方的瞬时活动面板。
+ *
+ * - 行生命周期：`tool_execution_start` 建档（toolCallId→名——**不建行**，
+ *   首个 `tool_execution_update` 才建行）/ 后续 update 原位换行 /
+ *   `tool_execution_end` 即摘行 / `clear()` 清板（agent_start·end·repaint
+ *   三时点——瞬时面律：不入正文、不跨 repaint 保存）；
+ * - 宽容解码（update 载荷契约面 `unknown`——03 §2.3 自由载荷，呈现侧零
+ *   契约收紧）：string 直显 / AgentToolResult 形〔content 块数组〕取文本块
+ *   倒扫末条非空行 / 其余视为文本缺席退化为 ` ▸ 名 …`；
+ * - 帽 4 行 + 溢出行「+ N 更多」；
+ * - 与件 3 分职互补：状态行示「执行哪个工具」、本件行示「输出到哪了」。
+ */
+import { truncateToWidth } from '../../engine/index.js';
+/** 帽内行数（溢出行另计——spec 定形） */
+const MAX_ROWS = 4;
+/**
+ * update 载荷宽容解码 → 末行输出文本（null = 文本缺席）。
+ * 网格行是单行物理面——string 形内部换行折叠空格（直显语义的物理收口）。
+ */
+export function decodeUpdateText(update) {
+    if (typeof update === 'string') {
+        const collapsed = update.replaceAll('\n', ' ');
+        return collapsed.trim() === '' ? null : collapsed;
+    }
+    // AgentToolResult 形：content 块数组——取文本块的行序列倒扫末条非空行
+    if (typeof update === 'object' && update !== null && Array.isArray(update.content)) {
+        const lines = [];
+        for (const block of update.content) {
+            if (typeof block === 'object' &&
+                block !== null &&
+                block.type === 'text' &&
+                typeof block.text === 'string') {
+                lines.push(...block.text.split('\n'));
+            }
+        }
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (line !== '')
+                return line;
+        }
+    }
+    return null; // 数字/布尔/无文本块对象——文本缺席
+}
+/** 工具进度面板：正在流 partial 的工具各占一行（清板即零行） */
+export class ToolProgressPanel {
+    /** 建档表（toolCallId→名——start 建档反查；end/clear 同摘） */
+    names = new Map();
+    rows = [];
+    /** 建档不建行（工具名供 update 反查——无档退 toolCallId 防御路径） */
+    begin(toolCallId, name) {
+        this.names.set(toolCallId, name);
+    }
+    /** update 消费：已有行原位换文本；无行建行（首 update 建行条款） */
+    applyUpdate(toolCallId, update) {
+        const text = decodeUpdateText(update);
+        const existing = this.rows.find((row) => row.toolCallId === toolCallId);
+        if (existing !== undefined) {
+            existing.text = text;
+            return;
+        }
+        this.rows.push({ toolCallId, name: this.names.get(toolCallId) ?? toolCallId, text });
+    }
+    /** end 即摘行（建档同摘——迟到 update 无档退 id 名） */
+    end(toolCallId) {
+        this.rows = this.rows.filter((row) => row.toolCallId !== toolCallId);
+        this.names.delete(toolCallId);
+    }
+    /** 清板（行与建档同清——agent_start·end·repaint 瞬时面律） */
+    clear() {
+        this.rows = [];
+        this.names.clear();
+    }
+    /** 量高：清板 0；帽内行数 + 溢出行 */
+    measure(width) {
+        void width; // 行单行制——宽度不敏感（截断吸收）
+        if (this.rows.length === 0)
+            return 0;
+        return Math.min(this.rows.length, MAX_ROWS) + (this.rows.length > MAX_ROWS ? 1 : 0);
+    }
+    /** 落位：每工具一行 ` ▸ 名 · 末行`（缺席 ` ▸ 名 …`）；溢出行收尾 */
+    render(buffer, region) {
+        const visible = this.rows.slice(0, MAX_ROWS);
+        visible.forEach((row, i) => {
+            const tail = row.text !== null ? ` · ${row.text}` : ' …';
+            buffer.writeText(region.row + i, region.col, truncateToWidth(` ▸ ${row.name}${tail}`, region.width));
+        });
+        const overflow = this.rows.length - MAX_ROWS;
+        if (overflow > 0) {
+            buffer.writeText(region.row + MAX_ROWS, region.col, `+ ${overflow} 更多`, { dim: true });
+        }
+    }
+}

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

@@ -0,0 +1,254 @@
+import { buildVisualLineMap, findVisualLineAt } from '../editor/visual-lines.js';
+/** 滚动条 thumb 样式（dim——存在感弱于正文） */
+const SCROLLBAR_STYLE = Object.freeze({ dim: true });
+/** 滚动条 thumb 字符 */
+const THUMB = '┃';
+/** 未渲染过时的防御缺省（render 后由实测回写） */
+const DEFAULT_WIDTH = 80;
+const DEFAULT_PAGE_SIZE = 10;
+/** 单步滚动键位表（无修饰——ctrl/meta/shift 组合归上层） */
+const SCROLL_ACTIONS = Object.freeze({
+    up: 'line-up',
+    down: 'line-down',
+    pageup: 'page-up',
+    pagedown: 'page-down',
+    home: 'to-top',
+    end: 'to-bottom',
+});
+/** 滚轮单步视觉行数（vim mousescroll ver 缺省档三行——tmux copy-mode 五行不取；07 引擎节件 6 条款码面缺省参数） */
+const WHEEL_LINES = 3;
+/**
+ * 滚动视口：逻辑行集为数据源，字素硬折视觉行（复用 editor 基件折行算术），
+ * 自持视口偏移与尾随态。
+ */
+export class ScrollView {
+    lines = [];
+    /** 折叠缓存（行集引用失效 + 折宽分槽——同一行集多折宽并存零抖动） */
+    cacheLines = null;
+    cacheMaps = new Map();
+    /** 视口首行（视觉行下标） */
+    offset = 0;
+    /** 尾随模式（true = 内容更替贴尾） */
+    follow = true;
+    /** 折宽与视口高实测（render / measure 回写——显式滚动的即时夹取依据） */
+    lastWidth = DEFAULT_WIDTH;
+    viewportHeight = DEFAULT_PAGE_SIZE;
+    /** 量高帽（嵌入 Flex 布局时限制分配；缺省全量——副屏 root 直收全屏 region） */
+    maxHeight;
+    /** 滚动通知（装配层接重绘请求） */
+    onScroll;
+    constructor(options = {}) {
+        this.maxHeight = options.maxHeight;
+    }
+    /* ---------------- 数据面 ---------------- */
+    /** 行集整体替换（回看器快照档——新事件不追加、整档重设） */
+    setLines(lines) {
+        this.lines = lines;
+        this.cacheLines = null; // 缓存失效（引用比对落空即整缓存弃）
+        if (this.follow) {
+            this.offset = Number.MAX_SAFE_INTEGER; // 尾随贴尾
+            this.clampNow(); // 即时夹到视觉底
+        }
+    }
+    /* ---------------- 滚动控制面 ---------------- */
+    /** 绝对滚动（视觉行下标——越界即时夹取） */
+    scrollTo(viewportRow) {
+        this.applyOffset(viewportRow);
+    }
+    /** 相对滚动（负向上 / 正向下；0 无动作） */
+    scrollBy(delta) {
+        if (delta !== 0)
+            this.applyOffset(this.offset + delta);
+    }
+    /** 滚到顶部（破随） */
+    scrollToTop() {
+        this.applyOffset(0);
+    }
+    /** 滚到底部（复随） */
+    scrollToEnd() {
+        this.applyOffset(Number.MAX_SAFE_INTEGER);
+    }
+    /**
+     * 滚到逻辑行定位处（件 8 回看器搜索跳转消费）：定位处所在视觉行对齐视口顶
+     * （col 缺省 = 行首）；两遍折叠同 render 判溢出（溢出档折宽与呈现一致——
+     * 跳转落点不因滚动条让列错行）。显式滚动路——破随（applyOffset 同律）。
+     */
+    scrollToLine(line, col = 0) {
+        let map = this.visualMap(this.lastWidth, false);
+        if (map.length > this.viewportHeight)
+            map = this.visualMap(this.lastWidth, true);
+        // 定位处所在视觉行（col 落段判定——与 findVisualLineAt 同规则的本体内联）
+        const vi = findVisualLineAt(map, line, col);
+        this.applyOffset(vi);
+    }
+    /** 视口首行（夹取后的观测值） */
+    get scrollOffset() {
+        return this.offset;
+    }
+    /** 尾随态（回看器判断是否在追新） */
+    get isFollowing() {
+        return this.follow;
+    }
+    /* ---------------- 渲染协商 ---------------- */
+    /** 量高：视觉行数夹 maxHeight（缺省全量——副屏 root 场景不经本路） */
+    measure(width) {
+        this.lastWidth = width;
+        const map = this.visualMap(width, false);
+        const cap = this.maxHeight ?? map.length;
+        if (map.length <= cap)
+            return map.length;
+        // 溢出预判：滚动条让列重折后行数只多不少——以折后行数夹帽（量高即承诺，不超卖）
+        return Math.min(this.visualMap(width, true).length, cap);
+    }
+    /** 落位渲染：折行判溢出 → 夹取自愈 → 正文 → 滚动条（溢出才显） */
+    render(buffer, region) {
+        if (region.width <= 1 || region.height <= 0)
+            return; // 一列给内容都不够——防御位
+        this.lastWidth = region.width;
+        this.viewportHeight = region.height;
+        // 两遍折叠：全宽判溢出 → 溢出让一列重折（分槽缓存免抖动）
+        let map = this.visualMap(region.width, false);
+        const reservesBar = map.length > region.height;
+        if (reservesBar)
+            map = this.visualMap(region.width, true);
+        // follow 物化：尾随态贴真尾后再夹取（防御 setLines 时几何缺省值的贴尾失真
+        // ——批 10f-4 回看器开屏场景：构造期 clampNow 用缺省页高，首帧真几何才对齐）
+        if (this.follow)
+            this.offset = Number.MAX_SAFE_INTEGER;
+        this.clampOffset(map, region.height);
+        // 正文（视口内视觉行——切片写出经 writeSlice 单点，子类覆写带样式）
+        const end = Math.min(map.length, this.offset + region.height);
+        for (let vi = this.offset; vi < end; vi++) {
+            const seg = map[vi];
+            this.writeSlice(buffer, region, vi - this.offset, seg);
+        }
+        // 滚动条（溢出才显——右列 thumb 段按比例）
+        if (reservesBar)
+            this.drawScrollbar(buffer, region, map.length);
+    }
+    /**
+     * 视口切片写出（批 10f-4 件 8 回看器接缝）：基类裸文本直写；子类覆写按
+     * 带样式行渲染（样式段 + 匹配高亮）——折叠与偏移算术恒归本件，样式呈现
+     * 归子类（零第二滚动引擎）。
+     */
+    writeSlice(buffer, region, displayRow, seg) {
+        const line = this.lines[seg.line] ?? '';
+        buffer.writeText(region.row + displayRow, region.col, line.slice(seg.startCol, seg.startCol + seg.length));
+    }
+    /* ---------------- 输入事件 ---------------- */
+    /** 输入消费：key = 无修饰滚动键位（press/repeat 相）；mouse = 滚轮（其余归上层） */
+    handleEvent(event) {
+        if (event.kind === 'mouse') {
+            // 滚轮消费路（mu-2）：wheel 无 release 相（终端不报——press 一相到达）；
+            // 修饰位照常滚动——shift/ctrl+轮在终端侧多已截留改道（水平滚/缩放），
+            // SGR 报文到达即按垂直滚消费。走 scrollBy 显式滚动路（复随判据同键盘）
+            if (event.phase !== 'press')
+                return false;
+            if (event.button === 'wheel-up') {
+                this.scrollBy(-WHEEL_LINES);
+                return true;
+            }
+            if (event.button === 'wheel-down') {
+                this.scrollBy(WHEEL_LINES);
+                return true;
+            }
+            return false; // 非滚轮鼠标相归上层（子类选区路）
+        }
+        if (event.kind !== 'key')
+            return false;
+        if (event.phase === 'release')
+            return false;
+        if (event.ctrl || event.alt || event.shift || event.meta)
+            return false;
+        const action = SCROLL_ACTIONS[event.key];
+        if (action === undefined)
+            return false;
+        switch (action) {
+            case 'line-up':
+                this.scrollBy(-1);
+                break;
+            case 'line-down':
+                this.scrollBy(1);
+                break;
+            case 'page-up':
+                this.scrollBy(-this.viewportHeight);
+                break;
+            case 'page-down':
+                this.scrollBy(this.viewportHeight);
+                break;
+            case 'to-top':
+                this.scrollToTop();
+                break;
+            case 'to-bottom':
+                this.scrollToEnd();
+                break;
+        }
+        return true;
+    }
+    /* ---------------- 内部算术 ---------------- */
+    /** 视口几何观测（子类屏幕坐标反查用——render/measure 实测回写值） */
+    get viewportGeometry() {
+        return { width: this.lastWidth, height: this.viewportHeight };
+    }
+    /**
+     * 视口内显示行 → 视觉段反查（mu-2 子类接缝：屏幕坐标 → 逻辑位的折叠映射
+     * 半场——与 render 两遍折叠同判溢出同分槽缓存，零第二映射；界外返 null）。
+     */
+    segmentAt(displayRow) {
+        let map = this.visualMap(this.lastWidth, false);
+        if (map.length > this.viewportHeight)
+            map = this.visualMap(this.lastWidth, true);
+        return map[this.offset + displayRow] ?? null;
+    }
+    /** 滚动条列命中判（溢出让列时末列——07 件 8「视口外命中零动作」的判据位） */
+    hitScrollbar(col) {
+        const map = this.visualMap(this.lastWidth, false);
+        return map.length > this.viewportHeight && col === this.lastWidth - 1;
+    }
+    /** 折叠缓存取（行集引用 + 折宽双键——分槽并存） */
+    visualMap(width, reserveBar) {
+        const foldWidth = Math.max(1, width - (reserveBar ? 1 : 0));
+        if (this.cacheLines !== this.lines) {
+            this.cacheLines = this.lines;
+            this.cacheMaps.clear();
+        }
+        let map = this.cacheMaps.get(foldWidth);
+        if (map === undefined) {
+            map = buildVisualLineMap(this.lines, foldWidth);
+            this.cacheMaps.set(foldWidth, map);
+        }
+        return map;
+    }
+    /** 以已知折宽即时夹取（显式滚动 / 尾随贴尾的收口路——渲染后缓存命中零成本） */
+    clampNow() {
+        const map = this.visualMap(this.lastWidth, false);
+        this.clampOffset(map, this.viewportHeight);
+    }
+    /** 偏移夹取（内容短于视口归零）+ 复随判据（到底即复随；破随只在显式滚动） */
+    clampOffset(map, viewportHeight) {
+        const maxOffset = Math.max(0, map.length - viewportHeight);
+        this.offset = Math.min(Math.max(0, this.offset), maxOffset);
+        if (this.offset >= maxOffset)
+            this.follow = true;
+    }
+    /** 显式滚动统一路（先破随后即时夹取——夹到底自然复随） */
+    applyOffset(next) {
+        this.follow = false;
+        this.offset = Math.max(0, next);
+        this.clampNow();
+        this.onScroll?.();
+    }
+    /** 滚动条：右列 thumb 段（size 按比例、start 按偏移比例） */
+    drawScrollbar(buffer, region, totalLines) {
+        const h = region.height;
+        const maxOffset = Math.max(0, totalLines - h);
+        if (maxOffset === 0)
+            return; // 防御位（溢出判据已排除——双保险）
+        const thumbSize = Math.max(1, Math.floor((h * h) / totalLines));
+        const thumbStart = Math.round((this.offset / maxOffset) * (h - thumbSize));
+        const col = region.col + region.width - 1;
+        for (let r = 0; r < thumbSize; r++) {
+            buffer.setCell(region.row + thumbStart + r, col, THUMB, SCROLLBAR_STYLE);
+        }
+    }
+}