8863977c0d
Drag to select terminal text and copy it with Ctrl-Shift-C. Built as a
custom selection model (xterm.js-style) rather than native selection,
because the virtual scroll only keeps ~60 rows in the DOM and rebuilds
them every frame — native selection would be destroyed and couldn't span
scrolled-out rows.
core.rs:
- selection_text(start, end) extracts a (row,col)→(row,col) range straight
from history_rows + screen_cache, so copy is correct across the whole
buffer regardless of what is currently rendered
- TerminalRow::text_in_cols slices a row by grid columns (using the
segment `cols` widths), trimming trailing whitespace
component.rs:
- Selection { anchor, head } in logical buffer coords; mousedown/move/up
drag updates it; point_to_cell maps pixels→cell (padding + scrollTop)
- selection_rects computes per-row highlight rects clipped to the rendered
window; rendered as an overlay inside the translated rows layer so the
highlight follows scrolling without splitting text segments
- cell_size signal kept in sync with viewport measurement
- Ctrl-Shift-C copies via navigator.clipboard.write_text; Ctrl-C is left
untouched (still SIGINT); typing clears the selection
style: .terminal-selection overlay, user-select:none on the grid, rows
above the highlight via z-index.
web-sys: add DomRect, MouseEvent, Navigator, Clipboard.
Adds point_to_cell / selection_rects / selection_text unit tests (16
terminal tests total). Marks P0 done in TERMINAL_ROADMAP.md.
Known follow-up: no auto-scroll when dragging past the viewport edge
(scroll first, then select); wide+combining column slicing is approximate.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
8.0 KiB
8.0 KiB
Terminal Roadmap — 对照 xterm.js 的追平计划
本文档记录 base-path-demo 浏览器终端当前已实现的能力、相比 xterm.js 仍缺失的功能，以及每一项计划的实现方式与优先级，供后续开发接手。
定位提醒：本项目目标不是复刻 xterm.js 这个通用 JS 终端库，而是按 TERMINAL_HANDOFF.md 的方向，用
Axum + portable-pty（后端）+Leptos + Rust/WASM（前端）沉淀一套可复用的 Rust 终端组件。因此追平的重点是「让真实终端会话好用」，而非铺平 xterm.js 的全部 API 面。
1. 覆盖度自评（截至本文档）
按用途粗估：
- 「跑通真实终端会话」核心用途：约 50–60%
- xterm.js 完整 API / 特性面：约 15–20%
差距集中在输入完整性、API/生态、可配置性，而非「能不能用」。
已实现（有代码 + 单元测试）
| 能力 | 位置 |
|---|---|
| PTY 会话 + WebSocket 双向流 | server/src/terminal/{pty_session,ws}.rs |
| ANSI 解析（vt100 crate）：颜色 / 粗体 / 斜体 / 下划线 / 反色、CSI 光标控制、擦除、滚动区 | app/src/terminal/core.rs |
| 256 色 + RGB 真彩 | core.rs::indexed_color / resolve_* |
| alt-screen（vim / btm / htop），含历史隔离 | core.rs::process |
| scrollback + 虚拟滚动（万行不卡，绝对定位） | core.rs::collect_window / component.rs::virtual_window |
| 宽字符 / 组合字符网格对齐 | core.rs TerminalSegment.cols |
| resize / reflow | core.rs::resize |
clear（含 ESC[3J 清 scrollback） |
core.rs::contains_erase_scrollback |
| alt-screen 滚轮 → 方向键翻页 | component.rs::handle_wheel |
| 基础按键：Ctrl-C/D/L、方向键、Enter/Tab/Esc/Backspace | component.rs::map_key_to_terminal_input |
| 粘贴（Ctrl-V / 浏览器菜单，含 bracketed paste） | component.rs::handle_paste / prepare_paste |
| 文本选区 + 复制（自建模型，Ctrl-Shift-C，跨滚动） | component.rs 鼠标处理 / core.rs::selection_text |
2. 追平项（按优先级）
P0 — 复制 / 粘贴 + 文本选区 ⭐ ✅ 已完成
现状：粘贴、选区、复制全部完成并验证通过。
已实现：
- 粘贴 ✅
on:paste（ClipboardEvent）读clipboard_data().get_data("text")，归一换行为\r后作为Input发送。- bracketed paste：应用开启时（
core.bracketed_paste()）包进ESC[200~ … ESC[201~。 - 实现于
component.rs::handle_paste+ 纯函数prepare_paste。 - 右键走浏览器默认菜单（避免依赖剪贴板读权限）；Ctrl-V 为主路径。
- 选区 + 复制 ✅（自建选区模型，xterm.js 风格）
- 选区按逻辑行列坐标跟踪（
Selection { anchor, head }），鼠标mousedown/move/up拖拽更新；point_to_cell做像素→单元格换算（含 padding/scroll）。 - 高亮 overlay：
selection_rects算每行矩形，渲染在虚拟滚动层内（共享 translateY，跟随滚动），不拆分文本段。 - 复制取
TerminalCore::selection_text(start, end)—— 直接从history_rows + screen_cache数据模型按行列取文本，跨滚动、输出流动时都正确（不依赖 DOM）。 - Ctrl-Shift-C 复制（Ctrl-C 保持 SIGINT）；打字清除选区。
- 实现于
component.rs（Selection/selection_rects/point_to_cell/鼠标处理）+core.rs::selection_text+core.rs::TerminalRow::text_in_cols，均有单元测试。
- 选区按逻辑行列坐标跟踪（
- 快捷键：Ctrl-Shift-C 复制 / Ctrl-V 粘贴。
已知后续项（非阻塞）：拖拽到视窗边缘时没有自动滚动延伸选区（需先滚到位再选）；行内 wide+组合字符混排的列切片为近似。
P1 — 完整功能键 + application-cursor 模式
现状：只映射了方向键、Ctrl-C/D/L、Enter/Tab/Esc/Backspace。缺 F1–F12、Home/End/Insert/Delete、PageUp/PageDown、大量 Ctrl/Alt 组合。
计划实现：
- 扩展
map_key_to_terminal_input，补齐：F1–F12→ESC O P/Q/R/S（F1–4）、ESC[15~…（F5–12）Home/End→ESC[H/ESC[F（或ESC[1~/ESC[4~）Insert/Delete→ESC[2~/ESC[3~PageUp/PageDown→ESC[5~/ESC[6~Ctrl+A..Z→ 控制字符0x01..0x1A（通用化，不再只 C/D/L）Alt+<key>→ 前缀ESC+ 字符
- application-cursor 模式：vt100 暴露
screen().application_cursor()。为真时，方向键要发 SS3 形式ESC O A/B/C/D而非ESC [ A/B/C/D。handle_keydown和handle_wheel（alt-screen 滚轮翻页）都要据此切换序列。- 这能修掉「某些 vim 配置 / 全屏程序里方向键行为怪异」的潜在问题。
风险：低。纯查表扩展 + 一个模式判断。建议把按键表抽成数据驱动并加单元测试覆盖。
P2 — 鼠标上报（mouse reporting）
现状：没有。点击 / 拖拽位置不会发给应用，vim 鼠标、tmux 选区、btm 点击都用不了。
计划实现：
- vt100 已解析鼠标模式：
screen().mouse_protocol_mode()（None/Press/PressRelease/ButtonMotion/AnyMotion）和mouse_protocol_encoding()（Default/Utf8/Sgr）。 - 在
terminal-screen上监听on:mousedown/on:mouseup/on:mousemove：- 把像素坐标换算成终端 行列（用已测量的 cell 宽高 + 容器 rect）。
- 按当前 encoding 编码：
- SGR（最常用）：
ESC[<b;col;row;M（按下）/m（释放）。 - Default：
ESC[M+ 三字节。
- SGR（最常用）：
- 只在
mouse_protocol_mode != None时拦截，否则放行（不破坏选区/原生行为）。
- 与 P0 选区冲突处理：应用开启鼠标上报时，鼠标事件优先发给应用；否则用于本地选区。
风险：中。坐标换算边界 + 与选区的优先级仲裁需要仔细测。
P3 — 中文 / IME 输入
现状：map_key_to_terminal_input 只处理 key.chars().count() == 1 的单字符，IME 组合输入（拼音候选）完全没接。
计划实现：
- 改用
composition事件 + 隐藏<textarea>的标准方案（xterm.js 也是这套）：- 一个 1×1 透明、跟随光标的
textarea承接 IME。 - 监听
compositionstart/compositionupdate/compositionend。 - 组合进行中不发字节；
compositionend时把最终文本一次性作为 Input 发送。 - 普通
input事件（非组合）也走这个 textarea，替代部分keydown逐字符逻辑。
- 一个 1×1 透明、跟随光标的
- 光标定位：把隐藏 textarea 定位到终端光标处，让候选框出现在正确位置。
风险：中高。事件模型要从「keydown 逐键」迁一部分到「textarea + composition」，需保证不回归现有按键。建议先把 P1 功能键做完再动这块，避免两套输入逻辑互相打架。
3. 其余缺口（暂不排期，记录备查）
xterm.js 还有这些，本项目暂列「按需再做」：
- 链接检测（点 URL 打开）、搜索 / 查找（Ctrl-F 高亮）
- 光标样式：块 / 竖线 / 下划线 + 闪烁（目前固定块状反色）
- Canvas / WebGL 渲染器：当前是 DOM 渲染，够用但不如 Canvas 快；超大终端 + 高刷新率场景才需要
- sixel / 图片协议、字形连字控制
- Unicode 11/15 宽度表：目前依赖 vt100 的宽度判断，极端 emoji / 新字符可能不准
- 无障碍（屏幕阅读器 live region）
- 公开 API / 插件系统 / 配置项：当前是项目内定制组件，无对外 API
4. 建议推进顺序
P0 复制粘贴(先粘贴→可见区复制) ← 最先，体验提升最大
↓
P1 完整功能键 + application-cursor
↓
P2 鼠标上报
↓
P3 中文 IME(放在功能键之后，避免输入逻辑冲突)
每一项都应延续现有做法：纯逻辑抽成可单测的函数（如 map_key_to_terminal_input、wheel_delta_to_rows、virtual_window），用 cargo test -p app --lib terminal:: 锁定，浏览器只做交互验证。