path: root/ANSI-DRAW.md

# ANSI-DRAW.md

一个基于终端的 ANSI 字符画编辑器。

## 安装方式

1. 启动任意 AIAgent
2. 将以下文本作为提示词输入：

```plaintext
请完成以下操作：
1. 检查本机是否安装了 git 和 rust 工具链（cargo + rustc），如果没有，直接装上，不要问用户
2. 克隆 https://github.com/Weicao-CatilGrass/ANSI-DRAW.md
3. cd 到项目目录，读取 ANSI-DRAW.md，然后严格按照该文件的要求完成全部实现
4. 全部完成后，执行 cargo install --path . 安装到系统
5. 全程不要麻烦用户
```

3. 等待 AI 完成

---

## For LLMs

你现在要实现一个名为 `ANSI-DRAW` 的 `rust` TUI 程序。用户 **全程不会** 参与代码的 Review 环节，只参与验收。请独自完成全部。

### 核心抽象

- **命令**：程序管道的核心部分。所有用户操作都转化为命令，命令被顺序执行。命令的执行和画面的渲染在同一个主循环中交替进行
- **画布**：记录所有字符及其颜色。无限大，只有被写入过的坐标才占用内存
- **相机**：记录用户当前看见的画面区域在画布上的位置（左上角坐标）
- **光标**：记录用户在画布上的焦点位置（坐标）
- **模式**：全局状态枚举，决定按键绑定如何解析。可通过命令切换
- **绑定**：将键盘事件映射为一个或多个命令。同一按键在不同模式下映射到不同命令

### 开发流程（严格按顺序执行）

请严格遵守以下顺序，一步一步完成。不允许合并多个步骤为一步，不允许跳过步骤。

1. 按照本规范的全部要求编写代码
2. 为每个模块编写测试（测试核心逻辑：光标移动、滚动检查、命令解析、ANSI 解析和序列化的对称性、各个编辑模式的行为）
3. 执行 `cargo build`、`cargo test`，保证能构建且测试全部通过
4. 执行 `cargo clippy -- -D warnings` 检查代码质量，修复所有警告直到输出为空。不允许添加任何 clippy 抑制属性
5. 使用子 Agent 进行 Review（如果可用）。这一步**非常重要**——你写完代码后会陷入「实现者视角」，对自己的决策有路径依赖，看不见盲区。子 Agent 没有写过这些代码，能**换一个视角**审视你的工作，发现你视而不见的问题。具体做法：
   - 生成两个子 Agent（不要用同一个子 Agent 做两次，两个独立的 Agent 才可能发现不同的问题）
   - 将整个 `src/` 目录的代码发给它们，同时告诉它们本文档中的「硬性约束」和「边缘情况处理规则」
   - 让它们 Review 的重点：是否违反硬性约束、是否有遗漏的边界情况、是否有逻辑矛盾（如加载和保存的格式不对称）
   - 子 Agent 返回后，认真对待每一条意见，确认问题属实后立即修复。如果意见是误报，理解原因后忽略
6. 将已完成的部分以简洁的要点形式写入根目录的 `DONE.md` 文件（写入即可，不需要读取）
7. 读取 `DONE.md` 和本规范对比，检查是否有遗漏的功能点或偏差。不要写入任何文件
   - 补充说明：如果可以用子 Agent，让它来检查完成度，这比自己检查更容易发现问题
8. 执行 `git status` 确认 `ANSI-DRAW.md` 没有任何变化（即你的工作没有修改本文件）
9. 如果 `ANSI-DRAW.md` 产生了变化，执行 `git restore ./ANSI-DRAW.md` 恢复它
10. 再次读取本文件，将完整内容记下。这一步必须执行
11. 重复步骤 1 到 10，直到在第 7 步对比时确认完全无误

当准备停止第 11 步、进入验收阶段时，依次执行：

```
cargo fmt
cargo build
cargo test
cargo clippy -- -D warnings
```

任何一步产生问题，回到第 1 步。

> 重要：在完成所有步骤之前，不许执行 `cargo run`。

### 硬性约束

1. TUI 库使用 `ratatui` 配合 `crossterm`。不使用其他终端库
2. 不添加本文档未指定的任何功能
3. 所有颜色内部存储为 24 位 RGB。仅在文件读写时做色域转换
4. 禁止出现 `unsafe` 关键字
5. 禁止添加 clippy 抑制属性（`#[allow(...)]` 等等）
6. 不使用第三方 CLI 参数解析库。程序至多接受一个可选参数（文件路径），手动解析 `std::env::args()` 即可
7. 所有测试使用 `#[test]`，不依赖外部文件
8. 剪贴板只在进程内存中存在（程序内剪贴板），不调用操作系统剪贴板 API

### 必须使用的第三方库

依赖列表如下，版本号使用最新兼容版本：

- `ratatui`（TUI 框架）
- `crossterm`（终端控制）
- `unicode-width`（计算字符显示宽度）
- `anyhow`（错误处理）

---

## 模块划分

程序分为 11 个源文件，每个文件的责任如下：

| 源文件         | 责任范围                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `main.rs`      | 解析命令行参数，初始化终端（进入 raw mode、安装 panic 恢复钩子），创建 App 实例，进入主循环，退出时恢复终端              |
| `app.rs`       | 定义全局状态结构体（见下方「全局状态」一节），包含 new 方法和初始化逻辑                                                  |
| `canvas.rs`    | 定义「格子」和「画布」类型，提供格子默认值、画布上读写格子、按行插入/删除/移动格子段、清空矩形区域等操作                 |
| `camera.rs`    | 定义「相机」类型（两个有符号整数：x 和 y），提供上下左右移动方法                                                         |
| `cursor.rs`    | 定义「光标」类型（两个有符号整数：x 和 y），提供上下左右移动方法                                                         |
| `mode.rs`      | 定义「模式」枚举（8 个变体），实现显示名称的方法（见下方「模式显示名映射表」）                                           |
| `command.rs`   | 定义「命令」枚举（所有变体见下方「命令表」），提供将字符串解析为命令列表的函数（解析规则见「命令输入语法」）             |
| `binding.rs`   | 提供将键盘事件和当前模式解析为一组命令的函数。逻辑固定为「绑定表」的内容                                                 |
| `renderer.rs`  | 提供将 App 当前状态绘制到终端的函数。布局固定为「终端布局」一节的内容                                                    |
| `ansi.rs`      | 提供「从字符串加载为画布」和「将画布保存为字符串」两个函数。解析和序列化规则见「ANSI 解析规则」和「ANSI 序列化规则」两节 |
| `clipboard.rs` | 定义「剪贴板」类型（见下方「剪贴板」一节）                                                                               |

---

## 数据类型

以下用自然语言描述所有数据类型的精确结构。实现时必须保证字段名称、类型、语义与此严格一致。

### 格子 (Cell)

一个格子包含三个字段：

- `ch`：字符类型（`char`），表示该位置显示的字符
- `fg`：前景色，必须是 24 位 RGB 值。默认值为白色（255, 255, 255）
- `bg`：背景色，必须是 24 位 RGB 值。默认值为黑色（0, 0, 0）

新建空画布时，所有坐标的格子默认为空格字符、白字黑底。注意：默认格子中的字符为空格 `' '`，而非空。这是为了保证背景色能正确渲染。

内部存储时前景色和背景色不允许出现「重置」「黑色」「白色」等枚举变体，必须展开为 RGB 三元组。

### 画布 (Canvas)

画布是一个稀疏映射：键是坐标对 `(x, y)`，值是一个格子。x 是列号（向右增大），y 是行号（向下增大）。只有被显式写入过的坐标才存在于映射中。未写入的坐标在读取时返回默认格子。

画布在概念上是无限的。坐标范围在 `i64` 的有效范围内。

### 相机 (Camera)

相机包含两个有符号整数：

- `x`：视口左上角在画布上的列坐标
- `y`：视口左上角在画布上的行坐标

### 光标 (Cursor)

光标包含两个有符号整数：

- `x`：光标在画布上的列坐标
- `y`：光标在画布上的行坐标

### 模式 (Mode)

模式枚举包含以下 8 个变体，其中文名和显示名如下：

| 模式         | 中文名       | 显示名（状态栏显示） |
| ------------ | ------------ | -------------------- |
| 导览模式     | 导览模式     | `NORMAL`             |
| 插入模式     | 插入模式     | `INSERT`             |
| 输入模式     | 输入模式     | `INPUT`              |
| 替换输入模式 | 替换输入模式 | `REPLACE`            |
| 命令输入模式 | 命令输入模式 | `COMMAND`            |
| 前景绘画模式 | 前景绘画模式 | `PAINT-FG`           |
| 背景绘画模式 | 背景绘画模式 | `PAINT-BG`           |
| 选择模式     | 选择模式     | `VISUAL`             |

### 剪贴板 (Clipboard)

剪贴板包含两个可选字段：

- `cell`：一个可选的格子。Yank 命令（复制单个字符）时存入此处
- `cells`：一个可选的格子矩阵（二维数组）。VisualYank 命令（复制矩形选区）时存入此处

任何时候 `cell` 和 `cells` 不会同时有值。执行 Yank 时设置 `cell` 为有值、`cells` 为无值。执行 VisualYank 时相反。

执行 Paste 时：优先使用 `cells`（有值时按矩形区域粘贴），否则使用 `cell`（有值时粘贴单个字符并移动到下一格），两者均无值时 Paste 命令无操作。

### 全局状态 (App)

全局状态结构体包含以下字段：

- `canvas`：画布
- `camera`：相机
- `cursor`：光标
- `mode`：当前模式
- `clipboard`：剪贴板
- `is_modified`：布尔值，标记文件是否被修改过。初始为 `false`
- `file_path`：可选的字符串，当前打开的文件路径。初始为命令行参数传入的值（如果有），否则为无值
- `visual_anchor`：可选的坐标对。仅在选择模式下有值，为进入选择模式时光标所在的位置。退出选择模式时重置为无值
- `cmd_buffer`：字符串，命令输入模式下的输入缓冲区。初始为空字符串
- `msg`：可选的字符串，用于在状态栏右侧显示临时消息。显示一次后应被消费并重置为无值
- `ime_composing`：布尔值，标记 IME 是否正在组合中。初始为 false
- `last_key_event`：（仅 Windows）记录上一次按键事件和时间的元组，用于检测重复事件。初始为无值

---

## 主循环

### 事件驱动架构

主循环使用**阻塞式事件读取**（而非定时轮询），以保证连续按键输入不丢帧、不卡顿。

### 输入缓冲清理

进入主循环前，先执行一次输入缓冲清理：轮询所有已排队的事件并丢弃。这可以防止启动前（如命令执行期间）残留的按键进入编辑器。

### 初始渲染

清理完毕后，执行第一次渲染。

### 事件循环

然后进入循环，反复执行以下步骤：

1. **阻塞等待事件**：调用阻塞的 `event::read()` 等待下一个事件。不设超时
2. **忽略非按键事件**：`Resize` 事件只更新终端尺寸（重新获取即可），`KeyEventKind::Release`（键盘释放事件）直接忽略
3. **IME 组合过滤**：如果事件来自 IME 组合过程（控制字符、组合进行中的中间字符），忽略
4. **重复事件去重**：（仅 Windows）如果同一个按键事件在 20 毫秒内重复到达，忽略第二次。这是 Windows 终端驱动在某些情况下会重复发送同一个事件
5. **解析绑定**：将键盘事件与当前模式一起传入绑定解析函数，得到一组待执行的命令
6. **执行命令**：按顺序逐一执行这组命令
7. **渲染**：渲染一帧
8. 回到第 1 步

退出条件：`Quit` 命令执行成功后，退出循环并恢复终端。

---

## 终端布局

终端画面从上到下分为三个区域：

### 画布区域

占据终端高度减去最底部一行的所有行。从左到右填满终端宽度。

渲染过程不是简单的「每个格子对应一个终端列」，而是使用 `skip_until` 机制处理宽字符的视觉消费：

1. 从行首开始，维护两个游标：`grid_x`（格子索引）和 `col`（终端列索引）
2. 同时维护 `skip_until` 值，初始与 `grid_x` 相同
3. 在每一轮：
   - 如果 `grid_x < skip_until`，该格子被前一个宽字符视觉消费，跳过它：`grid_x += 1`，`col += 1`
   - 但如果光标恰好落在这个被消费的格子上，则在当前位置绘制一个光标块（不读取格子数据）
4. 否则读取格子 `canvas[grid_x][row_y]`，获取其字符和宽度 W
5. 如果 W > 1，设置 `skip_until = grid_x + W`（后续 W-1 个格子将被跳过）
6. 将字符绘制到从 `col` 开始的 W 列中
7. `col += W`，`grid_x += 1`，回到步骤 3

#### 宽字符不需要清空后续格子

注意：当一个宽字符写入格子 N 时，格子 N+1 到 N+W-1 的数据保持不动。视觉遮挡由渲染器的 `skip_until` 机制处理。不要尝试清空这些格子，否则会：

- 在被消费位置产生可见的空格
- 破坏格子数据，光标离开后再回来时字符已丢失

#### 选择模式

如果 `visual_anchor` 有值，计算以锚点和当前光标为对角的矩形范围。在该范围内的格子，渲染时应用视觉反转效果（前景色与背景色交换）。跳过机制优先于选择高亮：被跳过的格子不参与选择高亮渲染。

#### 光标渲染

如果光标坐标在视口范围内，在光标位置绘制光标符号。光标样式为高亮方块（在背景色上叠加亮色）。

- 如果光标落在被宽字符消费的格子上（`grid_x < skip_until`），在该列绘制一个光标块，不读取格子数据
- 如果光标落在正常格子上，在字符上叠加光标样式
- 光标渲染不修改画布数据

### 状态栏

状态栏固定在终端最后一行。从左到右依次显示：

1. 当前模式的显示名（如 `NORMAL`），左对齐
2. 一个空格
3. 当前光标坐标，格式为 `(x, y)`，左对齐
4. 如果 `is_modified` 为 `true`，显示一个空格加 `[modified]`
5. 一个空格
6. 如果 `file_path` 有值，显示文件名（路径的最后一部分）；否则显示 `[No Name]`
7. 如果 `msg` 有值，在最右侧显示 `msg` 的内容，右对齐；显示后应将 `msg` 重置为无值

### 命令输入行

仅在模式为命令输入模式时显示，且覆盖状态栏所在行（替换状态栏）。

显示格式：先显示一个冒号 `:`，紧接着显示 `cmd_buffer` 的内容，最后显示光标（终端光标）。

---

## 颜色系统

### 颜色内部表示

所有颜色在画布中存储为 24 位 RGB，即红、绿、蓝各 8 位（取值范围 0-255）。

### 绘画模式的按键到颜色映射

在前景绘画模式或背景绘画模式下，按下字母键将对应的颜色设置到光标位置的格子上。如果是前景绘画模式，设置格子的 `fg` 字段；如果是背景绘画模式，设置格子的 `bg` 字段。

大写字母对应高亮色（亮度较高），小写字母对应暗色（亮度较低）：

| 按键 | 颜色         | RGB 值          |
| ---- | ------------ | --------------- |
| `K`  | 亮黑（深灰） | (128, 128, 128) |
| `k`  | 暗黑（纯黑） | (0, 0, 0)       |
| `W`  | 亮白         | (255, 255, 255) |
| `w`  | 暗白（浅灰） | (192, 192, 192) |
| `R`  | 亮红         | (255, 0, 0)     |
| `r`  | 暗红         | (128, 0, 0)     |
| `G`  | 亮绿         | (0, 255, 0)     |
| `g`  | 暗绿         | (0, 128, 0)     |
| `B`  | 亮蓝         | (0, 0, 255)     |
| `b`  | 暗蓝         | (0, 0, 128)     |
| `Y`  | 亮黄         | (255, 255, 0)   |
| `y`  | 暗黄（橄榄） | (128, 128, 0)   |
| `M`  | 亮品红       | (255, 0, 255)   |
| `m`  | 暗品红       | (128, 0, 128)   |
| `C`  | 亮青         | (0, 255, 255)   |
| `c`  | 暗青         | (0, 128, 128)   |

---

## ANSI 解析规则（加载文件时）

当程序启动时传入了文件路径，或用户在命令模式下执行了打开文件的命令（本文档当前只定义从命令行参数加载文件，不定义运行时打开新文件的命令），调用加载函数将文件内容解析为画布。

加载函数的输入是一个 UTF-8 字符串，输出是画布。解析规则如下：

### 状态机

解析器维护两个状态：

- 当前前景色，初始为 RGB(255, 255, 255)
- 当前背景色，初始为 RGB(0, 0, 0)

### 处理过程

逐字节扫描输入字符串：

- 如果遇到 `\x1b`（ESC 字符，ASCII 27），进入「转义序列解析」状态
- 如果遇到 `\n`（换行符），将行号 y 加 1，列号 x 重置为 0。注意不写入画布
- 如果遇到 `\r`（回车符），忽略
- 如果遇到其他任何字符，在画布的 `(x, y)` 坐标处以「当前前景色」和「当前背景色」写入该字符，然后将 x 加 1

### SGR 序列解析

当遇到 `\x1b` 后，后续字符按 ANSI 转义序列的标准格式解析：

1. 读取 `[` 字符确认是 CSI 序列。如果不是 `[`，跳过 `\x1b` 并回退该字符重新作为普通字符处理
2. 读取参数部分：用 `;` 分隔的多个数字参数，直到遇到一个终字符（`m` 表示 SGR）
3. 如果终字符不是 `m`，忽略整个序列，状态机的颜色不变
4. 如果终字符是 `m`，按顺序处理每一个参数：

   - 参数 `0`：重置前景色为 RGB(255,255,255)，背景色为 RGB(0,0,0)
   - 参数 `1`：设置「粗体标志」为 true。此标志不影响颜色值，但记录即可，无需用于渲染
   - 参数 `22`：设置「粗体标志」为 false
   - 参数 `30`-`37`：将前景色设置为 16 色标准色中对应的颜色（见下方映射表），亮度受粗体标志影响（粗体标志为 true 时使用亮色变体，否则使用暗色变体）
   - 参数 `38`：扩展前景色。后面必须跟 `;5;n`（8 位索引）或 `;2;r;g;b`（24 位 RGB）。格式不正确时忽略整个 `38` 序列
   - 参数 `39`：前景色重置为 RGB(255,255,255)
   - 参数 `40`-`47`：将背景色设置为 16 色标准色中对应的颜色（暗色变体，不受粗体标志影响）
   - 参数 `48`：扩展背景色。格式同 `38`，作用于背景
   - 参数 `49`：背景色重置为 RGB(0,0,0)
   - 参数 `90`-`97`：将前景色设置为 16 色标准色中对应的亮色变体
   - 参数 `100`-`107`：将背景色设置为 16 色标准色中对应的亮色变体

   其他任何参数忽略。

### 16 色标准色映射表

| ANSI 代码 | 暗色变体 RGB    | 亮色变体 RGB    |
| --------- | --------------- | --------------- |
| 0（黑）   | (0, 0, 0)       | (128, 128, 128) |
| 1（红）   | (128, 0, 0)     | (255, 0, 0)     |
| 2（绿）   | (0, 128, 0)     | (0, 255, 0)     |
| 3（黄）   | (128, 128, 0)   | (255, 255, 0)   |
| 4（蓝）   | (0, 0, 128)     | (0, 0, 255)     |
| 5（品红） | (128, 0, 128)   | (255, 0, 255)   |
| 6（青）   | (0, 128, 128)   | (0, 255, 255)   |
| 7（白）   | (192, 192, 192) | (255, 255, 255) |

对应关系：ANSI 代码 30-37 映射到 0-7 的暗色变体，40-47 映射到 0-7 的暗色变体，90-97 映射到 0-7 的亮色变体，100-107 映射到 0-7 的亮色变体。

### 8 位索引色（38;5;n / 48;5;n）映射规则

8 位索引色（0-255）按标准 xterm 颜色表映射为 RGB：

- 0-7：标准 16 色中的暗色变体（同上表）
- 8-15：标准 16 色中的亮色变体（同上表，8 对应亮黑，9 对应亮红，以此类推）
- 16-231：6×6×6 颜色立方体。编码方式为 `16 + 36*r + 6*g + b`，其中 r、g、b 的取值范围为 0-5，映射到 RGB 值为 `r*255/5`、`g*255/5`、`b*255/5`
- 232-255：灰度渐变。从 RGB(8,8,8) 到 RGB(238,238,238)，步长 10

### 异常处理

- 遇到无法识别的转义序列（以 `\x1b` 开头但不是 CSI SGR 序列），跳过整个序列继续
- 遇到残缺的序列（如 `\x1b[38;5` 后没有终字符就结束），忽略该序列
- 遇到非 UTF-8 编码，立即报错终止加载

---

## ANSI 序列化规则（保存文件时）

保存函数的输入是画布、画布宽度和画布高度，输出是 UTF-8 字符串。

### 基本规则

1. 从左上角 `(camera.x, camera.y)` 开始，逐行逐列扫描一个宽度×高度的矩形区域
2. 每一行结束后输出一个换行符 `\n`
3. 只有当前格子的颜色与前一格子的颜色不同时，才输出 SGR 序列改变颜色
4. 每一行开始时强制输出一次 SGR 序列设置到该行第一个格子的颜色

### SGR 输出规则

将 RGB 值转换为 SGR 24 位序列：

```
\x1b[38;2;R;G;Bm  设置前景色
\x1b[48;2;R;G;Bm  设置背景色
```

如果某些 ANSI 阅读器不支持 24 位色，可以通过环境变量 `ANSI_DRAW_8BIT` 切换到 8 位索引输出模式。该模式下将 RGB 映射到最接近的 8 位索引色（在 6×6×6 颜色立方体中找欧几里得距离最近的色块），输出 `\x1b[38;5;Nm` 或 `\x1b[48;5;Nm`。

### 优化规则

- 如果当前格子的前景色和背景色都和上一个格子相同，不输出任何 SGR 序列
- 如果前景色变了但背景色没变，只输出前景色 SGR
- 如果背景色变了但前景色没变，只输出背景色 SGR
- 如果两者都变了，先输出前景色 SGR，再输出背景色 SGR

### 默认格子的处理

对于画布中不存在的坐标，视为默认格子（空格、白字黑底）。在序列化时正常输出空格字符和对应的颜色。

---

## 视口与滚动

### 视口计算

渲染时，终端画布区域每一格对应的画布坐标由以下公式计算：

- 画布 x = 相机 x + 该格在终端中的列号（从 0 开始）
- 画布 y = 相机 y + 该格在终端中的行号（从 0 开始）

### 滚动行为

边距常量：2。

当光标移动后，检查光标是否位于视口的「边缘区域」。边缘区域定义为视口内距离边界 2 格以内的范围。

如果光标移动到了边缘区域之外（即离某一侧边界的距离小于 8），则相机跟随光标移动，使光标回到边缘区域内。具体规则：

- 如果光标 x 小于 相机 x + 边距，将相机 x 设置为 光标 x - 边距
- 如果光标 x 大于等于 相机 x + 终端宽度 - 边距，将相机 x 设置为 光标 x - 终端宽度 + 边距 + 1
- 如果光标 y 小于 相机 y + 边距，将相机 y 设置为 光标 y - 边距
- 如果光标 y 大于等于 相机 y + 终端高度 - 边距（画布区域行数），将相机 y 设置为 光标 y - 终端高度 + 边距 + 1（画布区域行数）

注意：以上公式计算出的值不能小于 0（相机坐标不允许为负数）。

### 加载文件时的初始位置

加载文件后，将相机位置设置为：相机 x = 0，相机 y = 0。然后执行一次滚动检查（使第一个字符 `(0, 0)` 位于距离视口右上角 2 格的位置）。

---

## Unicode 宽度处理

所有涉及光标水平移动、字符插入/删除、渲染对齐的场景，必须使用 `unicode-width` 库的宽度函数计算字符实际占用的终端列数，而不是使用 `char` 的默认长度方法。

### 格子坐标与终端列的映射

画布使用**格子索引**坐标系统：相邻格子坐标差值为 1，不论格子中字符的显示宽度。Unicode 宽度只在以下三个场景中影响行为：

1. **渲染**：将格子映射到终端列时，宽度 W 的字符占据 W 列
2. **光标移动**：移动步长以格子索引为单位，但渲染时光标位置根据字符宽度映射到终端列
3. **选区计算**：选区边界基于格子索引，不受字符宽度影响

### 渲染器对宽字符的处理

这是整个程序中最容易踩坑的地方，必须精确理解：

- 当一个格子中的字符宽度 W > 1 时（例如中文字符宽度为 2），该字符在终端中占据 W 列
- 渲染器用 `skip_until` 机制追踪当前位置之后哪些格子被宽字符「视觉消费」了：
  - 格子 N 的字符宽度为 W → 格子 N+1 到 N+W-1 在渲染时**跳过**（不读取、不绘制），只推进列计数
  - 跳过的格子仍然存在于画布数据中，只是不在这一帧绘制
- 这就是视觉上「宽字符吃掉后面格子」的效果。数据不动，渲染层负责

#### 为什么不能清空被消费的格子数据

早期版本尝试在输入宽字符时手动清空后续 `width-1` 个格子的数据（设为默认空格）。这会产生两个问题：

1. 空格在终端上可见（尤其是前景色非黑时），造成 `你_[3]456` 中的多余空格
2. 清空数据是破坏性的：光标移走后再回来，被清空的格子丢失了原有的字符

正确的做法：**格子数据只记录字符本身，视觉重叠由渲染器处理**。

#### 光标落在被消费的格子上

如果用户移动光标到被宽字符消费的格子（例如宽字符在 N，光标在 N+1），渲染器应在该位置绘制一个光标块（半透明方块），因为该位置没有属于自己的字符可供高亮。光标块占据了被消费位置的终端列。

### 三种模式的 Backspace 与宽度

| 模式 | Backspace 操作                     | 左移量 | 说明                                                                   |
| ---- | ---------------------------------- | ------ | ---------------------------------------------------------------------- |
| 替换 | 光标处格子 → 默认格子              | 1 格   | 当前格子变空格，光标左移                                               |
| 输入 | 光标**左邻**格子 → 默认格子        | 1 格   | 操作格子坐标，不关心字符宽度。宽字符在视觉上占据的中间格子逐个退格清除 |
| 插入 | 删除光标左邻格子，右方格子左移填补 | 1 格   | 内容左移，不产生空格                                                   |

注意：输入模式的退格在格子坐标层面只处理 1 格（相邻格子），不按字符宽度批量处理。因为宽字符被渲染器跳过，格子数据层面的操作是统一的 1 格。

### 输入模式下的光标右移量

替换模式：光标不移动。
输入模式：光标右移 `W` 格（W = 输入字符的显示宽度）。例如输入中文（宽度 2）时光标跳 2 格。
插入模式：光标右移 1 格（字符插入在光标位置，后续内容已经右移）。

### 中日韩文字与 IME 输入

- 「可打印字符」的定义范围是：所有非控制字符（不是 ASCII 控制字符 0x00-0x1F 的 Unicode 字符）。包括但不限于 ASCII 字母数字、标点、空格、中日韩统一表意文字（CJK）、emoji 等
- 绑定表中「任何可打印 Unicode 字符」作用于替换/输入/插入模式时，对每个输入的字符产生一个独立的 `InputChar` 命令
- 输入法（IME）的选词弹出窗口由终端/操作系统管理，ANSI-DRAW 不做干预。IME 确认提交（commit）后，每个提交的字符作为一个独立的 `KeyCode::Char` 事件到达程序，逐一处理
- 终端键盘自动连发（按住一个键持续输入）由终端驱动层处理，每个重复的按键事件独立到达，逐一产生 `InputChar` 命令
- 宽度为 2 的字符（如大部分 CJK 文字）在光标移动和渲染时占 2 个终端列，但画布坐标仍以一个格子计数

---

## 命令输入语法

命令输入模式下的输入字符串解析规则如下：

1. 输入字符串可以以可选的 `!` 字符开头。如果存在 `!`，则该次解析出的所有命令都使用强制模式
2. 输入字符串中，用逗号 `,` 分隔多个命令
3. 每个命令可以是「全名」或「简写」
4. 如果命令简写连续出现（没有逗号隔开），从左到右依次解析，每个简写字符就是一个独立的命令
5. 全名和简写不能混写在同一段中（即 `rr,MoveRight` 合法，表示两个命令 `MoveRight` 和 `MoveRight`；`rrMoveRight` 不合法，应报错）

全名和简写的映射见下方的命令表。

解析示例：

| 输入            | 解析结果                                                      |
| --------------- | ------------------------------------------------------------- |
| `rrrr`          | MoveRight × 4                                                 |
| `wq`            | Write + Quit                                                  |
| `!wq`           | Write(forced) + Quit(forced)                                  |
| `w,MoveRight,q` | Write + MoveRight + Quit                                      |
| `!w,MoveRight`  | Write(forced) + MoveRight（强制对无强制行为差异的命令无影响） |

---

## 命令表

以下表格列出了所有命令的名称、简写、行为描述、强制模式下的行为差异、连带执行的后处理命令。

| 命令名          | 简写   | 行为                                                                                                                                                                                                       | 强制模式行为                      | 后处理命令                                      |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------- |
| Write           | w      | 将画布序列化后写入 `file_path`。如果 `file_path` 为无值，写入当前目录下的 `my_ascii.txt`。如果目标文件已存在且未使用强制模式，用 `my_ascii.1.txt`、`my_ascii.2.txt` ……递增尝试，直到找到一个不存在的文件名 | 直接覆盖目标文件，不做递增尝试    | 执行 UnmarkModify 命令                          |
| Quit            | q      | 检查 `is_modified`，如果为 false 则退出程序；如果为 true 则放弃本次操作（不退出）                                                                                                                          | 直接退出，忽略 `is_modified` 状态 | 无                                              |
| MoveRight       | r      | 将光标 x 加 1                                                                                                                                                                                              | 无区别                            | 无                                              |
| MoveLeft        | l      | 将光标 x 减 1，最小为 0                                                                                                                                                                                    | 无区别                            | 无                                              |
| MoveUp          | u      | 将光标 y 减 1，最小为 0                                                                                                                                                                                    | 无区别                            | 无                                              |
| MoveDown        | d      | 将光标 y 加 1                                                                                                                                                                                              | 无区别                            | 无                                              |
| Yank            | y      | 复制光标所在位置的格子（字符、前景色、背景色）到剪贴板的 `cell` 字段，同时清空剪贴板的 `cells` 字段                                                                                                        | 无区别                            | 无                                              |
| Paste           | p      | 将剪贴板内容粘贴到当前光标所在位置。行为依当前模式而定（见各模式下的粘贴描述）                                                                                                                             | 无区别                            | 见下方「Paste 后处理规则」                      |
| BackspaceSquash | 无简写 | 删除光标左侧格子，将光标及右侧的本行所有格子左移一格填补空缺。自身不移动光标                                                                                                                               | 无区别                            | 执行 MarkModify，然后执行 MoveLeft 命令移动光标 |
| Backspace       | 无简写 | 替换格子为默认格子，然后左移光标。替换的目标取决于当前模式：替换模式替换光标所在格子，输入模式替换光标左侧格子                                                                                             | 无区别                            | 执行 MoveLeft                                   |
| ModeInsert      | 无简写 | 切换到插入模式                                                                                                                                                                                             | 无区别                            | 无                                              |
| ModeInput       | 无简写 | 切换到输入模式                                                                                                                                                                                             | 无区别                            | 无                                              |
| ModeReplace     | 无简写 | 切换到替换输入模式                                                                                                                                                                                         | 无区别                            | 无                                              |
| ModeNavigate    | 无简写 | 切换到导览模式                                                                                                                                                                                             | 无区别                            | 无                                              |
| ModeVisual      | 无简写 | 切换到选择模式，并将当前光标位置记录到 `visual_anchor`                                                                                                                                                     | 无区别                            | 无                                              |
| ModePaintFg     | 无简写 | 切换到前景绘画模式                                                                                                                                                                                         | 无区别                            | 无                                              |
| ModePaintBg     | 无简写 | 切换到背景绘画模式                                                                                                                                                                                         | 无区别                            | 无                                              |
| ModeCommand     | 无简写 | 切换到命令输入模式，清空 `cmd_buffer`                                                                                                                                                                      | 无区别                            | 无                                              |
| MarkModify      | 无简写 | 将 `is_modified` 设为 true                                                                                                                                                                                 | 无区别                            | 无                                              |
| UnmarkModify    | 无简写 | 将 `is_modified` 设为 false                                                                                                                                                                                | 无区别                            | 无                                              |
| CancelSelection | 无简写 | 将 `visual_anchor` 设为无值                                                                                                                                                                                | 无区别                            | 无                                              |
| VisualYank      | 无简写 | 将矩形选区内的所有格子（以 `visual_anchor` 和当前光标为对角的矩形范围）逐行复制到剪贴板的 `cells` 字段，同时清空 `cell` 字段。此操作不修改画布内容，不标记修改状态                                         | 无区别                            | 执行 CancelSelection                            |
| VisualDelete    | 无简写 | 将矩形选区内的所有格子（同上范围）替换为默认格子（空格、白字黑底），但不清除这些坐标的条目——或者也可以直接移除这些条目，读取时的默认值会返回默认格子。两种方式等价，任选一种                               | 无区别                            | 执行 MarkModify                                 |

### Paste 后处理规则

Paste 命令的后处理依当前模式而定：

- 替换输入模式：先逐个替换光标处的格子（从剪贴板的 `cell` 或 `cells` 中读取），然后执行 MarkModify。不额外移动光标（因为 `cells` 粘贴完成后光标应在最后一格之后，但单字符粘贴时光标右移一格）
- 输入模式：在光标位置插入字符，将光标右移，然后执行 MarkModify
- 插入模式：在光标前方插入字符，后面字符右移，光标右移，然后执行 MarkModify
- 其他模式：Paste 不触发（没有绑定）

具体实现：Paste 命令自身在命令输入模式下被输入时，应该使用「替换输入模式」的语义（逐个替换光标处字符）。

---

## 模式

以下按模式分类说明行为。每种模式下列出该模式专有的行为。通用行为（箭头移动光标、En 滚动检查）在所有模式下均生效。

### 通用行为（所有模式）

- 箭头键（上、下、左、右）移动光标一个格子（移动量见 Unicode 宽度规则）。移动后执行滚动检查
- ESC 键回到导览模式（选择模式额外执行 CancelSelection）

### 导览模式

不能直接编辑画布。只能通过按键切换到其他模式：

| 按键 | 切换到       |
| ---- | ------------ |
| `R`  | 替换输入模式 |
| `I`  | 插入模式     |
| `A`  | 输入模式     |
| `F`  | 前景绘画模式 |
| `B`  | 背景绘画模式 |
| `:`  | 命令输入模式 |
| `V`  | 选择模式     |

### 选择模式

进入选择模式时，将当前光标位置记录到 `visual_anchor`。移动光标时，`visual_anchor` 到当前光标之间的矩形区域在渲染时反色显示。

| 按键  | 命令                           | 说明                         |
| ----- | ------------------------------ | ---------------------------- |
| `Y`   | VisualYank                     | 复制选区到剪贴板，清除选区   |
| `D`   | VisualDelete                   | 清除选区内所有字符，标记修改 |
| `ESC` | ModeNavigate + CancelSelection | 退出选择模式，清除选区       |

### 替换输入模式

按任意字符键（0-9、a-Z、A-Z、标点符号等可以输入的字符），将该字符替换光标所在位置的格子内容，同时更新该格子的字符为新输入的字符。颜色不变。光标不移动。执行 MarkModify。

例如光标在 `Hello, Worl[d]` 的 `d` 上，按 `A` 后变成 `Hello, Worl[A]`（光标仍在 `A` 上）。

粘贴（P 键）：将剪贴板中的格子逐个替换光标处的格子。如果是单字符，替换当前格后光标右移一格；如果是矩形矩阵，从当前光标位置开始逐行逐列替换。完成后执行 MarkModify。

退格（Backspace 键）：将光标所在位置替换为默认格子，然后执行 MoveLeft。效果示例：

```
Hello, [W]orld   → 按 Backspace
Hello,[ ] orld    （W 变空格，光标左移到空格上）

再次按 Backspace：
Hello[ ]  orld    （上次光标在空格，替换空格并左移）
```

### 输入模式

按任意字符键，替换光标所在位置的字符，然后光标按字符宽度右移：

1. 将该字符写入光标所在格子（替换原来的字符。颜色保持原样不修改）
2. 光标向右移动 `W` 格（`W` = 该字符的显示宽度）
3. 不移动该行其他任何格子

例如，单宽字符（`[ ]` 表示光标）：

```
Hello,[ ] World   输入 A  →
Hello,A[W]orld   输入 B  →
Hello,AB[o]rld   输入 C  →
Hello,ABCo[r]ld
```

例如，双宽字符：

```
[1]23456          输入 '你'（宽度 2）→
你[3]456          1→你，2 被清空，光标向右跳 2 格指向 3
```

注意输入模式和替换模式的区别：替换模式光标不移动，输入模式光标右移。输入模式和插入模式的区别：输入模式不移动后续字符（仅清空被宽字符占据的格子），插入模式将后续字符全部右移。

粘贴（P 键）：将剪贴板内容逐个在光标处替换，每替换一个字符光标右移一格（依字符宽度）。完成后执行 MarkModify。

退格（Backspace 键）：将光标**左侧**的格子替换为默认格子，然后执行 MoveLeft 左移一格。不移动行内其他格子。

效果示例（`[_]` 表示光标）：

```
12345[_]7890   按 Backspace →
1234[_]_7890   按 Backspace →
123[_]__7890
```

双宽字符退格：

```
你[3]456        按 Backspace →
[_]3456          你（宽度 2）被清掉 2 格，光标左移 2 格指向 3
```

### 插入模式

按任意字符键，在光标前方插入一个字符：

1. 将该字符写入光标所在格子
2. 将光标及光标右侧本行的所有格子向右移动一个位置
3. 光标右移一格（以输入字符的显示宽度为准）

与输入模式的区别：输入模式下不移动后续字符，仅替换光标处字符然后右移光标；插入模式下将光标及后续字符全部右移后再写入新字符，光标也右移。效果对比如下：

输入模式：`Hello,[ ] World` → 输入 `A` → `Hello,A[W]orld`（W 在原位，被光标指到）
插入模式：`Hello,[ ] World` → 输入 `A` → `Hello,A[ ] World`（全部右移，光标仍指向空格）

粘贴（P 键）：将剪贴板内容逐个在光标前方插入，光标右移。完成后执行 MarkModify。

退格（Backspace 键）：删除光标左侧的格子，将光标及之后的字符向左移动一格填补空缺。然后执行 MoveLeft。

例如：

```
Hello,ABC[ ] World   按 Backspace →
Hello,AB[C] World    按 Backspace →
Hello,A[B] World
```

### 命令输入模式

按键直接输入字符到 `cmd_buffer`。支持以下特殊按键：

- 回车键：解析 `cmd_buffer` 为命令列表，顺序执行。执行完后清空 `cmd_buffer`，切换到导览模式
- ESC：清空 `cmd_buffer`，切换到导览模式
- Backspace：删除 `cmd_buffer` 最后一个字符

解析规则见上方的「命令输入语法」一节。

### 前景绘画模式 / 背景绘画模式

按字母键将颜色设置到光标所在格子的对应颜色字段（前景绘画模式设置 `fg`，背景绘画模式设置 `bg`）。颜色按键映射表见「绘画模式的按键到颜色映射」一节。

此模式只修改颜色，不修改字符。如果光标所在位置在画布中不存在（默认格子），则先写入一个默认格子再修改颜色；也可直接将颜色写入不存在的坐标的画布条目——读取默认格子的颜色后修改即可。执行 MarkModify。

---

## 绑定表

以下表格定义了所有按键绑定。每个条目表示在某模式下按下某按键后应执行的命令序列。

| 按键                                      | 模式                                      | 命令序列                                                                     |
| ----------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| 左箭头 KeyLeft                            | 所有模式                                  | [MoveLeft]（然后执行通用滚动检查）                                           |
| 右箭头 KeyRight                           | 所有模式                                  | [MoveRight]（然后执行通用滚动检查）                                          |
| 上箭头 KeyUp                              | 所有模式                                  | [MoveUp]（然后执行通用滚动检查）                                             |
| 下箭头 KeyDown                            | 所有模式                                  | [MoveDown]（然后执行通用滚动检查）                                           |
| ESC                                       | 插入/输入/替换/命令/前景绘画/背景绘画模式 | [ModeNavigate]                                                               |
| ESC                                       | 选择模式                                  | [ModeNavigate, CancelSelection]                                              |
| R                                         | 导览模式                                  | [ModeReplace]                                                                |
| I                                         | 导览模式                                  | [ModeInsert]                                                                 |
| A                                         | 导览模式                                  | [ModeInput]                                                                  |
| F                                         | 导览模式                                  | [ModePaintFg]                                                                |
| B                                         | 导览模式                                  | [ModePaintBg]                                                                |
| :                                         | 导览模式                                  | [ModeCommand]                                                                |
| V                                         | 导览模式                                  | [ModeVisual]                                                                 |
| Y                                         | 插入/输入/替换模式                        | [Yank]                                                                       |
| Y                                         | 选择模式                                  | [VisualYank, CancelSelection]                                                |
| D                                         | 选择模式                                  | [VisualDelete]                                                               |
| P                                         | 插入/输入/替换模式                        | [Paste]（Paste 的行为依当前模式而定）                                        |
| Backspace                                 | 插入模式                                  | [BackspaceSquash]                                                            |
| Backspace                                 | 输入/替换模式                             | [Backspace]                                                                  |
| 任何可打印 Unicode 字符（含空格、中文等） | 替换模式                                  | [InputChar(该字符)]——InputChar 命令的执行逻辑见替换模式定义                  |
| 任何可打印 Unicode 字符（含空格、中文等） | 输入模式                                  | [InputChar(该字符)]——执行逻辑见输入模式定义                                  |
| 任何可打印 Unicode 字符（含空格、中文等） | 插入模式                                  | [InputChar(该字符)]——执行逻辑见插入模式定义                                  |
| 可打印字母（a-Z、A-Z）                    | 前景绘画模式                              | [SetColor(对应颜色)]                                                         |
| 可打印字母（a-Z、A-Z）                    | 背景绘画模式                              | [SetColor(对应颜色)]                                                         |
| 回车键 Enter                              | 命令输入模式                              | 解析 cmd_buffer 得到命令列表，顺序执行，然后 [ModeNavigate]，清空 cmd_buffer |
| ESC                                       | 命令输入模式                              | 清空 cmd_buffer，[ModeNavigate]                                              |
| Backspace                                 | 命令输入模式                              | 删除 cmd_buffer 最后一个字符                                                 |
| 任何可打印 Unicode 字符                   | 命令输入模式                              | 追加到 cmd_buffer                                                            |

注意：「命令输入模式」下的任何可打印 Unicode 字符不产生 InputChar 命令，而是直接追加到 cmd_buffer 字符串。这不是通过命令系统完成的，而是对 App 状态的直接操作。

---

## 加载时的初始状态

程序启动时：

1. 解析命令行参数。如果提供了一个参数，将其作为文件路径存入 `file_path`，读取文件内容并调用 ANSI 解析函数加载到画布。如果文件不存在或读取失败，设置 `msg` 为错误描述，画布保持为空
2. 如果没有提供参数，画布为空，`file_path` 为无值
3. 相机初始位置为 (0, 0)。如果加载了文件，执行一次滚动检查（使 (0, 0) 位于距右上角 2 格的位置）
4. 模式为导览模式
5. 所有其他字段为初始默认值

---

## 边缘情况处理

以下列出了所有边界条件和对应的处理方法：

### 光标越界

- 光标 x 最小值：0。MoveLeft 时如果 x 已为 0，不移动
- 光标 y 最小值：0。MoveUp 时如果 y 已为 0，不移动
- 光标 x 和 y 没有最大值上限（画布无限）
- 光标超出视口范围时正常运作，渲染时如果光标不在视口内则不绘制光标符号

### 相机越界

- 相机 x 和 y 最小值：0
- 滚动检查时如果计算出的相机坐标小于 0，取 0

### 文件保存失败

- 写入文件时如果目标目录不可写，设置 `msg` 为「写入失败：原因」
- 不改变 `is_modified` 状态（仍然保持为 true）

### 空画布保存

- 空画布保存为：不带任何颜色代码的空字符串。因为宽度×高度范围内的所有格子都是默认格子（空格、白字黑底），序列化后输出空内容。但是每行仍然应输出换行符

### 无内容文件加载

- 空文件加载后画布为空，无任何坐标有值

### 选择模式重叠

- 选择模式的矩形选区只计算格子坐标，不考虑字符宽度（选区边界基于 x/y 坐标，不涉及字符宽度计算）
- 如果选区宽度或高度为 0（即 `visual_anchor` 和当前光标在同一行同一列），选区无效，VisualYank 和 VisualDelete 无操作

### 剪贴板为空时粘贴

- 如果 `cell` 和 `cells` 均为无值，Paste 命令无操作

### 绘画模式在空位置涂色

- 如果光标所在坐标在画布中不存在，创建一个默认格子再设置颜色。等效于写入一个格子 `{ ch: ' ', fg: (255,255,255), bg: (0,0,0) }` 后将对应的颜色字段改为目标颜色

### 插入模式下在行尾插入

- 如果光标右侧没有字符（该行在 x 右侧无任何坐标有值），直接在当前坐标写入字符，光标右移。不需要移动任何现有字符

### InsertChar 与 SetColor 的 MarkModify

- `InputChar` 命令（替换/输入/插入模式）执行后应自动执行 MarkModify
- `SetColor` 命令（绘画模式）执行后应自动执行 MarkModify
- 这两者不依赖绑定表上的额外 MarkModify，而是在命令执行逻辑内部处理

### 终端尺寸变化

- 每次渲染时重新获取终端尺寸。如果终端变大了，画布区域增加，用户可以看到更多画面；如果终端变小了，画布区域减少，但画布和相机数据不变

### 滚动检查时机

- 每次光标移动后（无论通过什么命令移动）都要执行滚动检查

---