[perf] optimize CLI ANSI output and refresh previews

apps/cli/docs/terminal-client.md

@@ -99,7 +99,7 @@ crossdesk-cli 123456789 --renderer ansi --fps 8
 
 媒体回调仅同步复制借用的 NV12 数据，校验尺寸、容量、native 描述符与 stride；不保留借用指针。上限单帧 16,777,216 像素、每边 8192、偶数尺寸。最多一个待转换帧，替换前先完成校验与复制，无效帧不会挤掉已有画面；播放器另保留最近转换的一帧用于静止桌面的本地放大/重绘，并在接收新帧时回收上一帧缓冲区供后续复制使用。只丢弃解码后图像。显示器切换/关闭提升 generation，旧帧失效。
 
-转换与输出在拥有会话的事件循环，媒体回调独立。输出至多一个完整消息（2MiB），按令牌预算分块非阻塞写入，突发额度上限仍为 1MiB。本地 Kitty 使用 8MiB/s；存在 `SSH_CONNECTION`、`SSH_CLIENT` 或 `SSH_TTY` 时，Kitty 保持 1MiB/s，ANSI 和 Pi 桥接也保持 1MiB/s。不能开始新画面时保留最新解码帧。ANSI 差分基准只在整帧输出完成后提交。Pi 桥接另要求消费帧 ACK，最多一帧等待 ACK，输入映射只在对应 ACK 后切换到新网格。状态栏优先在完整画面输出之间更新，避免大图持续刷新时状态饥饿；可写事件唤醒短写重试，仍遵守字节预算。控制事件至多 64 条，协议输入 64KiB/嵌套 32 层，输入粘贴缓冲 32KiB，文本单次最多 16KiB。
+转换与输出在拥有会话的事件循环，媒体回调独立。输出至多一个完整消息（2MiB），按令牌预算分块非阻塞写入，突发额度上限仍为 1MiB。本地交互 ANSI 和 Kitty 使用 8MiB/s；存在 `SSH_CONNECTION`、`SSH_CLIENT` 或 `SSH_TTY` 时，两者保持 1MiB/s，Pi 桥接始终保持 1MiB/s。不能开始新画面时保留最新解码帧。ANSI 差分按终端实际使用的颜色与字形比较，忽略量化后相同的颜色和空格不可见的前景色；同一行可输出多个变化片段，并按光标定位、颜色切换和字符的实际字节成本合并短间隔。差分基准只在整帧输出完成后提交。Pi 桥接另要求消费帧 ACK，最多一帧等待 ACK，输入映射只在对应 ACK 后切换到新网格。状态栏优先在完整画面输出之间更新，避免大图持续刷新时状态饥饿；可写事件唤醒短写重试，仍遵守字节预算。控制事件至多 64 条，协议输入 64KiB/嵌套 32 层，输入粘贴缓冲 32KiB，文本单次最多 16KiB。
 
 测量像素渲染帧率时使用 release 构建；debug 的 `-O0` 面积采样开销明显更高。共享内存中的像素不经过终端字节预算，但仍受转换和终端消费速度限制；8MiB/s 是内联路径的输出上限，不是帧率保证。解码、像素转换、压缩、终端消费速度和帧大小都会影响结果。退出时，未完成画面最多继续写入 2s；取消图像传输及恢复屏幕的短写最多另重试 500ms。POSIX 立即恢复 termios 并清理输入，不等待输出排空；如果终端始终不消费输出，屏幕清理只能尽力发送。
 

apps/cli/docs/validation.md

@@ -122,6 +122,16 @@
 - SSH 环境保持原有 1MiB/s 字节预算且不探测共享内存；慢速输出降远端请求但保留本地目标。ANSI 默认 30／显式 15 和 bridge 默认 8／帧 ACK 通过。所有 Kitty 场景继续验证不显示未确认帧、最多两个终端图像、共享对象释放及退出后终端模式恢复。
 - 以上数字是合成源和伪终端的完整输出接收率，不包含真实视频解码、网络或 Ghostty GPU 呈现。全部额外测试代码、数据、构建脚本和产物位于工程外系统临时目录；本次未新增工程内测试，尚未对新版进行 Ghostty 实窗验收。
 
+## ANSI 多片段差分与本地吞吐（2026-10-31）
+
+- 本地交互 ANSI 的持续输出预算由 1MiB/s 提高到 8MiB/s；SSH 与 bridge 仍为 1MiB/s。保留 2MiB 单消息、1MiB 突发、非阻塞短写、最新帧替换和完整输出后提交差分基准的约束。
+- 同一行的分散修改按多个片段输出，短间隔按实际编码字节成本合并，比较包含下一单元的颜色设置。差分忽略色板量化后相同的颜色、空格前景色以及 ASCII 模式不显示的字形／背景字段；未修改采样、象限拟合及 Kitty 传输。
+- macOS arm64 CLI debug／release 构建及两种产物的 `doctor --json` 通过，完成后工程配置恢复为桌面与 CLI 同时启用的 debug。工程外 ASan/UBSan 检查通过：全部四象限字形、8／24／256 色、ASCII、首尾单元、长短间隔、色板等价、多种尺寸及偏移变化、600 帧连续随机更新与整帧重绘的屏幕一致性；140 组转换逐格一致，bridge 行输出及 Kitty 数据保持一致。
+- `-O2`、240×100 合成网格：10 行各两处分散修改由 90,058 降到 931 字节；隔列修改由 919,260 降到 562,601 字节；量化后颜色相同的整屏变化由 72,716 降到 0 字节。高色彩变化整帧仍为 922,929 字节，2×3 光标修改仍为 262 字节。多片段选择会增加部分交错修改场景的编码计算，以减少终端输出量。
+- 使用生产 CLI／渲染器的 `-O3` 构建、1920×1080 连续变化合成 NV12、240×100 字符视口、固定目标 30 FPS 的本地 PTY 对比：跳过启动阶段后的完整帧接收速率约 1.64 → 6.42 FPS，约 3.9 倍；平均每帧约 640 KB。分别设置 `SSH_TTY`、`SSH_CONNECTION`、`SSH_CLIENT` 时预算均保持 1MiB/s；设置 `TMUX` 的本地 ANSI 路径使用 8MiB/s。
+- 暂停 PTY 读取 1.3s，并在暂停期间发送退出命令，恢复读取后完整帧计数与提交计数一致，约 1.17s 内退出，备用屏幕、termios 和非阻塞标志恢复。没有连接真实远端，也未验证真实终端的 GPU 绘制、SSH 或 tmux 实际显示；上述帧率为合成源的完整输出接收率。
+- 额外检查源码、脚本、数据和产物均位于工程外系统临时目录，未新增或修改工程内测试文件／用例。
+
 ## 实测边界
 
 本地检查不涵盖 Linux / Windows 完整构建、跨平台远程控制、Kitty/SSH 实际终端显示、真实 Pi TUI 或长时间资源占用。五个平台 CI 配置与 npm 包名均不代表已发布或已验收。