# 移动端终端交互顶级约束 (Mobile Terminal Top-Level Constraints)

本文档定义了 PxTerm 移动端终端界面的**“四大不可回归”顶级约束**。在未来任何针对 CSS、JS 逻辑、甚至 Xterm.js 版本升级的修改中，都必须且优先满足以下条件。

任何破坏以下任一体验的代码修改，都视为 **核心体验回归 (Critical Regression)**，禁止合入。

---

## 🛑 约束 1：正常的软键盘弹出与收回 (Keyboard Lifecycle)
用户的输入意图必须被绝对尊重，不能因为防阻断逻辑导致系统键盘失灵或无法正常收起。

- **约束标准**：
  - 点击终端内最后一行空白处或已有文本，必须能够迅速唤起原生软键盘。
  - 在唤起状态下，可以通过 UI 按钮或符合常理的操作顺畅收起键盘，而不引起全屏闪烁或虚假重绘。
- **QA 测试用例 (Test Case 1)**：
  1. 在手机浏览器中打开终端。
  2. 短按屏幕输入区，**验证**：系统软键盘立刻出现。
  3. 点击顶部工具栏的隐藏键盘按钮/或进行收起手势，**验证**：软键盘顺利降下，终端不触发无关的字符输入或选中。

## 🛑 约束 2：原生且丝滑的滚动 (Native-like Smooth Scroll)
无论渲染层多么复杂（海量 `span`/`div` 标签），滑动都必须 1:1 跟手，并保留操作系统级的惯性阻尼。

- **约束标准**：
  - `touchmove` 事件绝不能由于 OS 原生手势侦测而在中途被无故截断（Frozen Screen）。
  - 松开手指后必须有自然的衰减惯性滚动。
- **QA 测试用例 (Test Case 2)**：
  1. 打印一长串历史构建输出（如 `ls -la /` 或 `dmesg`）。
  2. 手指在屏幕上连续、快速且不离开屏幕地上下来回拖拽。**验证**：无论速度多快，列表紧跟指尖，没有丝毫卡顿或断流。
  3. 快速向上一划并立刻松手。**验证**：列表如原生 App 一样继续依靠惯性顺滑滚动，直至自然停止。

## 🛑 约束 3：完整的长按选中功能 (Long-Press Text Selection)
滚动优化和事件劫持不能杀灭系统底层的文本选取工作流。

- **约束标准**：
  - 在触摸初始阶段 (`touchstart` / `pointerdown`) 绝对不滥用 `preventDefault` 导致 OS 选区定时器失效。
  - 一旦触发选区，一切系统原生拖拽行为享有最高优先级，防劫持和自定义滚动必须全面让路。
- **QA 测试用例 (Test Case 3)**：
  1. 在终端中找到一段带颜色的日志文本。
  2. 手指长按某个单词，**验证**：出现 iOS/Android 原生放大镜，并且选中该词（高亮或系统菜单出现）。
  3. 拖拽选区两端的“小拉手”扩大选中范围，**验证**：选区顺利扩大，且此时不应该误触发页面的大幅度重新滚动。

## 🛑 约束 4：键盘唤起/收回期间光标与命令行的正确位置 (Viewport Pinning during Transitions)
当可视区域 (`Visual Viewport`) 受到物理屏幕与虚拟键盘挤压变化时，我们必须保证用户正在操作的焦点不丢失。

- **约束标准**：
  - 软键盘弹出的瞬间，终端内部高度与排版自动重调，强制将**当前活动命令行 (光标所在行)** 顶出至可视范围内（浮于键盘正上方）。
  - 软键盘收回时，恢复之前的满铺视图高度，且当前输入行依然停留在舒适可见范围内，不会沉入看不见的“黑洞（屏幕下方）”。
- **QA 测试用例 (Test Case 4)**：
  1. 屏幕充满日志内容后，最下面的一行是当前的 Shell 提示符 `$ `。
  2. 短按唤起键盘，此时屏幕下半部分被键盘遮挡。
  3. **验证**：整个终端内容自动缩紧或向上推移，最后那行 `$ ` 以及光标刚好贴在这个物理键盘的顶部，能清晰看见输入的内容。
  4. 顺势收回键盘，**验证**：屏幕重新展平，最后一行依然保留在屏幕最下方，并未丢失位置。