[perf] accelerate Kitty and ANSI rendering

apps/cli/docs/bridge-protocol.md

@@ -20,6 +20,8 @@
 
 凭据不能放在 connect JSON 中。专用描述符可以由 Node `spawn` 的第四条 pipe 提供。成功读取后会话不会保留用户密码供上层访问；MiniRTC 内部为现有 Join/重连流程持有必要凭据直到销毁 Peer。下一次 connect 必须有可读的凭据来源；Pi 关闭视图后直接结束进程。
 
+`viewport.fps` 是本地输出目标。对端支持预览订阅时，超过 15 的目标使用已有交互模式（协议 `fps=60`、编码 `frame_rate=30`），不再折算成 15 FPS；低目标仍按能力选择 1/8/15。bridge 始终输出字符行并要求宿主 ACK，不使用交互 Kitty 的共享内存传图。
+
 帧事件：
 
 ```json

apps/cli/docs/terminal-client.md

@@ -45,13 +45,17 @@ crossdesk-cli 123456789 --server your-server.example --port 9099
 
 ANSI 默认使用四象限字符：每个字符从 2×2 样本选择误差最小的两个颜色和象限形状，比原先上下半方块多一倍水平采样点；每个字符仍只有前景/背景两色。使用 `--ansi-detail half` 可回到上下半方块以兼容字体。缩小时采用面积加权滤波，避免最近邻采样漏掉细线。支持 TrueColor、256 色和基础 8 色，256 色选择实际颜色立方体或灰阶条中更接近的颜色。环境的 COLORTERM/TERM 决定颜色模式；非 UTF-8 locale 使用背景色空格。TERM=dumb、非 TTY 输出明确拒绝交互连接，不输出全屏转义序列。
 
+四象限模式将每个 RGB 通道变化均不超过 6/255 的低对比单元合并为纯背景色，减少平坦区域的字形接缝。其余单元在独立拟合后参考上下左右邻格的量化误差调整选色，保留源图的真实渐变，并在高对比边缘减弱约束；调整设有失真上限，超过低对比阈值且能精确表示的文字细线和双色边缘保持原样。这些处理自动应用于独立 CLI 和 Pi／bridge 的四象限画面，实际效果仍受终端字体和行距影响。
+
 画面按字符单元比例等比缩放，留黑边及状态栏。交互连接通过终端字节流查询字符尺寸，支持通过 SSH 返回的回复：优先使用 `CSI 16 t` 的字符像素尺寸，否则组合 `CSI 14 t` 的完整文本区像素尺寸和 `CSI 18 t` 的完整行列数计算，兼容 GNOME/VTE 的文本区报告。计算后再扣除状态栏及画面行列上限，不把预留行当作图像高度。窗口改变时重新查询，每两秒刷新一次以覆盖字体／行距变化；回复到达后会重绘静止画面和更新鼠标映射。查询不阻塞连接；没有有效回复时使用系统提供的像素尺寸，再缺失时回退为宽高比 0.5。曾收到有效回复时保留最近有效尺寸，直到下一次有效回复。字符栅格的整数舍入仍可能产生小幅比例误差。格式依据 [XTerm 窗口尺寸报告](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html) 和 [GNOME VTE 实现](https://github.com/GNOME/vte/blob/master/src/vteseq.cc)。
 
 Windows 的可见传统控制台优先读取当前字体尺寸；Windows Terminal／ConPTY 使用显示终端的尺寸回复，不采用隐藏控制台宿主的字体值。不同终端版本可能不支持查询，或返回虚拟图形尺寸而非实际字体尺寸，此时需要手动校准。
 
 默认 `--cell-aspect auto` 自动确定比例。如果终端屏蔽查询或需要手动校准，可设置 `--cell-aspect 0.45`，数值表示单个字符的**宽／高**，允许 0.2～2；例如字符为 9×20 像素时使用 0.45。画面被压窄时调小此值，被拉宽时调大。此参数优先于自动检测，同时用于全景、细节和鼠标坐标映射。
 
-每次只输出变化行，合并连续颜色设置；缩放在完整输出边界清理旧画面。上限 240 列、100 画面行；默认顶部预留一行状态栏、底部预留两行快捷键，另预留一列避免自动换行。顶部状态栏用反色区分，左侧为控制模式和连接进度，右侧为画面参数及网络信息；底部两行分别为会话和视图快捷键。视频和等待提示从顶部状态栏下方开始，鼠标坐标按视频区域映射，点击状态栏不会传给远端。按键分组使用统一列宽和左右留白，窄窗口自动减少列数、合并按键组并省略次要参数，累计帧数和输出字节数保留在日志中。控制模式下仅提示本地命令入口及后续操作，进入本地命令模式后才显示平移和缩放按键；终端高度不足时优先收起底部提示行。
+独立 CLI 每次只输出变化行中首尾变化单元之间的区间，光标或局部视频更新不再重写整行；一帧内复用颜色状态、按实际色板索引合并颜色设置，并省略纯背景空格的前景色指令。Pi／bridge 仍发送可独立绘制的完整字符行，同时使用上述颜色编码优化。四象限初始拟合使用整数子集求和计算同等精度的颜色和误差，边界连续性拟合复用加权样本，减少重复运算。
+
+缩放在完整输出边界清理旧画面。上限 240 列、100 画面行；默认顶部预留一行状态栏、底部预留两行快捷键，另预留一列避免自动换行。顶部状态栏用反色区分，左侧为控制模式和连接进度，右侧为画面参数及网络信息；底部两行分别为会话和视图快捷键。视频和等待提示从顶部状态栏下方开始，鼠标坐标按视频区域映射，点击状态栏不会传给远端。按键分组使用统一列宽和左右留白，窄窗口自动减少列数、合并按键组并省略次要参数，累计帧数和输出字节数保留在日志中。控制模式下仅提示本地命令入口及后续操作，进入本地命令模式后才显示平移和缩放按键；终端高度不足时优先收起底部提示行。
 
 快捷键行使用 `KEYS |`、`VIEW |` 等固定宽度标题，标题和按键组之间用竖线分隔；键名用 `<c>`、`<+/->` 等标签标识。宽窗口中的分组分隔线按列对齐，窄窗口保留标题和完整按键标签，按可用宽度合并或减少分组。
 
@@ -59,7 +63,11 @@ ANSI 在完整桌面缩略图中仍无法保留普通字号的文字。先增加
 
 auto 模式发送 Kitty 查询与设备属性查询，等待最多 250ms；没有有效 Kitty 回应就用 ANSI。显式 kitty 模式探测失败时报错。tmux/screen 中 auto 使用 ANSI，显式 kitty 报不支持；不修改用户终端配置。
 
-Kitty 通过终端字节流发送 zlib 压缩的内联 RGB/Base64（每块至多 4096 字符），不使用远端临时图片文件。图像固定 ID=31、placement=1，更新同一图像，退出删除。依据终端报告的像素尺寸生成画面（未知时按 10×20 像素字符估算），上限 1920×1080。保留黑边和宽高比；原始细节模式按像素视口裁取源区域，避免整桌面缩小。没有可靠终端像素尺寸时使用估算值，因此不承诺显示设备的物理像素一一对应。压缩后超出单次输出预算时逐级降低尺寸。高熵视频压缩率较低，同一输出预算下实际帧率可能低于目标。RGB 压缩无损，不代表上游视频编码无损。
+本地 macOS/Linux 的 Kitty 模式会另用一个 1×1 像素的共享内存对象探测 `t=s`，最多等待 250ms；探测成功后，将未压缩 RGB 写入权限为 0600 的 POSIX 共享内存，仅通过终端字节流发送名字和显示命令。每次使用唯一名字，最多保留一个待确认的共享缓冲区（1920×1080×3 字节）。收到上传成功确认后才显示新图并释放缓冲区；上传报错、确认超过 500ms 或本地分配失败时，本次会话退回内联传输，继续保留旧画面。终端和 CLI 都会清理共享对象，退出时也会释放未确认的对象。SSH 中不尝试共享内存；Windows 暂用内联传输。
+
+内联 Kitty 通过终端字节流发送 zlib 压缩的 RGB/Base64（每块至多 4096 字符），不使用远端临时图片文件。两条路径都交替使用图像 ID=31/32：以 `a=t` 上传到未显示的 ID，传完后以 `a=p` 创建 placement=1，再删除旧图。仅在整帧显示命令输出完成后交替 ID，上传和短写期间保留旧画面，退出时清理两个 ID。这样避免重传同一 ID 时终端先移除旧图造成的帧间黑屏。
+
+依据终端报告的像素尺寸生成画面（未知时按 10×20 像素字符估算），上限 1920×1080。保留面积滤波、黑边、宽高比和裁剪坐标；原始细节模式按像素视口裁取源区域。共享内存路径使用可复用水平行计算的整数面积权重，避免逐像素重复浮点运算，也不再因 Base64 字节预算额外降采样。没有可靠终端像素尺寸时使用估算值，因此不承诺显示设备的物理像素一一对应。内联压缩结果超出单次输出预算时仍逐级降低尺寸；高熵视频的实际帧率可能低于目标。RGB 传输和压缩不丢失像素，不代表面积采样或上游视频编码无损。
 
 ```sh
 ssh -t your-server
@@ -70,7 +78,7 @@ crossdesk-cli 123456789 --renderer ansi --fps 8
 
 ## 预览与背压
 
-`--fps 1..30` 是本地输出目标。对端声明 PreviewSubscription 时，映射到合法 1/8/15 FPS（15 需要对应能力）；普通编码设置仍使用合法 30 FPS。分辨率上限使用协商到的 v2，视频预算只在 bandwidth 能力存在时发送。`--quality low|balanced|high|ultra` 对应如下请求：
+`--fps 1..30` 是本地输出目标。未显式指定时，共享内存探测成功默认使用 30 FPS；ANSI、内联 Kitty 和 bridge 默认仍为 8 FPS。自动选择的共享内存路径运行中退回内联时，目标也恢复为 8；显式设置的 `--fps` 始终保留。对端声明 PreviewSubscription 时，目标不超过 15 映射到合法 1/8/15 FPS（15 需要对应能力）；超过 15 则请求项目已有的交互模式：协议 `fps=60` 是模式标记，编码设置 `frame_rate=30` 才是帧率，不再把 `--fps 30` 限制为 15 FPS。分辨率上限使用协商到的 v2，视频预算只在 bandwidth 能力存在时发送。`--quality low|balanced|high|ultra` 对应如下请求：
 
 | 档位 | 分辨率上限 | 质量枚举 | 视频预算 |
 |---|---|---|---|
@@ -83,9 +91,11 @@ crossdesk-cli 123456789 --renderer ansi --fps 8
 
 媒体回调仅同步复制借用的 NV12 数据，校验尺寸、容量、native 描述符与 stride；不保留借用指针。上限单帧 16,777,216 像素、每边 8192、偶数尺寸。最多一个待转换帧，替换前先完成校验与复制，无效帧不会挤掉已有画面；播放器另保留最近转换的一帧用于静止桌面的本地放大/重绘，并在接收新帧时回收上一帧缓冲区供后续复制使用。只丢弃解码后图像。显示器切换/关闭提升 generation，旧帧失效。
 
-转换与输出在拥有会话的事件循环，媒体回调独立。输出至多一个完整消息（2MiB），以 1MiB/s 令牌预算分块非阻塞写入；不能开始新画面时保留最新解码帧。ANSI 差分基准只在整帧输出完成后提交。Pi 桥接另要求消费帧 ACK，最多一帧等待 ACK，输入映射只在对应 ACK 后切换到新网格。状态栏优先在完整画面输出之间更新，避免大图持续刷新时状态饥饿；可写事件唤醒短写重试，仍遵守字节预算。控制事件至多 64 条，协议输入 64KiB/嵌套 32 层，输入粘贴缓冲 32KiB，文本单次最多 16KiB。
+转换与输出在拥有会话的事件循环，媒体回调独立。输出至多一个完整消息（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。
 
-统计包括收到帧数、被替换帧数、非法帧、等待帧数、实际完整提交次数、输出字节数、运行秒数、最近本地排队时间、网络码率/RTT/SRTP。通过计数差/时间差可得到区间 FPS；交互连接结束日志另给平均提交 FPS。`client.log` 摘要的 `startup_ms` 记录从发起连接到连接成功（`connected`）、首个取出用于显示的视频帧入队（`first_frame`）、首帧完整写入终端（`first_output`）的毫秒数；未到达的阶段为 `null`。写入 TTY 完成不等于屏幕显示完成，本地排队时间不是端到端延迟。
+测量像素渲染帧率时使用 release 构建；debug 的 `-O0` 面积采样开销明显更高。共享内存中的像素不经过终端字节预算，但仍受转换和终端消费速度限制；8MiB/s 是内联路径的输出上限，不是帧率保证。解码、像素转换、压缩、终端消费速度和帧大小都会影响结果。退出时，未完成画面最多继续写入 2s；取消图像传输及恢复屏幕的短写最多另重试 500ms。POSIX 立即恢复 termios 并清理输入，不等待输出排空；如果终端始终不消费输出，屏幕清理只能尽力发送。
+
+统计包括收到帧数、被替换帧数、非法帧、等待帧数、实际完整提交次数、输出字节数、运行秒数、最近本地排队时间、网络码率/RTT/SRTP。通过计数差/时间差可得到区间 FPS；交互连接结束日志另给平均提交 FPS，以及实际 `renderer` 和 `output_bytes_per_second` 预算。`kitty_transport=shared_memory/inline/none` 标明生效路径，`target_fps` 是当前目标，`frame_processing_ms` 是平均本地布局／转换／传输准备耗时，`shared_ack_ms` 是平均上传命令写完到解析成功确认的耗时，`shared_fallbacks` 记录运行时回退次数。`client.log` 摘要的 `startup_ms` 记录从发起连接到连接成功（`connected`）、首个取出用于显示的视频帧入队（`first_frame`）、首帧显示命令完整写入终端（`first_output`）的毫秒数；未到达的阶段为 `null`。写入 TTY 完成不等于屏幕显示完成，本地排队时间不是端到端延迟。
 
 ## 输入与退出
 

apps/cli/docs/validation.md

@@ -73,6 +73,45 @@
 - Pi 1.4.0 SDK 严格类型检查及模拟宿主运行通过：使用真实 SDK 分片组包，覆盖文本区成对回复、字符尺寸优先级、宿主缓存、字体／窗口变化、手动覆盖、旧比例帧丢弃及 ACK、控制键回归、启动失败／异常退出后的监听与定时器清理。
 - 新增验证代码和产物全部位于工程外系统临时目录；尚未在真实 Windows、GNOME／SSH 或 Pi TUI 进行视觉验收。
 
+## ANSI 四象限接缝优化（2026-10-30）
+
+- macOS arm64 的 CLI debug 构建和 `doctor --json` 通过。工程外 ASan/UBSan 检查覆盖低对比合并、横纵细线／斜线／双色图案、等亮度彩色边缘、随机 NV12 输入的失真上限、局部更新范围和重复转换确定性。
+- 合成低对比图案中，3,072 个非空白字形全部合并为纯背景。合成渐变纹理的加权接缝误差由约 207,373 降至 180,187（13.1%）；仅统计两端均未合并为纯色的边界时，由约 198,007 降至 169,621。指标衡量相邻样本的重建色差相对源图色差的偏离，并降低真实高对比边缘的权重；不代表实机条纹减少的百分比。
+- 8／24／256 色输出、half／ASCII 与原实现一致性、不同视口／比例／缩放的布局和鼠标映射、静止网格差分及 Kitty 输出检查通过。
+- 本机 `-O2`、1920×1080 输入、240×100 字符视口、每项 12 次转换的合成基准：平滑画面约 7.14 → 6.03 ms/帧，随机亮度噪声约 5.44 → 7.73 ms/帧。仅衡量转换，不包含视频解码、ANSI 输出和终端绘制。
+- 额外检查代码、基准和数据均位于工程外系统临时目录；未新增工程内测试，未连接真实远端或进行终端字形／行距的视觉验收。
+
+## ANSI 转换与输出加速（2026-10-30）
+
+- macOS arm64 CLI debug 构建和 `doctor --json` 通过。工程外 ASan/UBSan 与 `-O2` 检查均通过：加速后的转换与此前接缝优化版本逐格颜色／字形一致，覆盖随机 NV12、低对比及平滑纹理、half／quadrant／ASCII、缩放和细节模式；Kitty 数据保持一致。
+- ANSI 转义序列模拟器验证最终屏幕一致，覆盖全部四象限字形、8／24／256 色、纯背景及色板复用、首尾单元、局部修改、视口／偏移变化和可独立绘制的 bridge 字符行。未向工程新增测试文件或用例。
+- 本机 `-O2`、1920×1080 输入、240×100 字符视口、每项 24 次转换：平滑画面约 6.26 → 4.83 ms/帧，随机亮度噪声约 7.75 → 5.72 ms/帧。保留面积滤波、低对比合并及边界连续性约束。
+- 240×100 真彩色合成网格、每项 100 次输出生成：整帧约 2.03 → 1.43 ms；120×50 单元的局部修改约 1.02 → 0.36 ms，输出 461,743 → 231,026 字节；2×3 单元的光标修改约 0.072 → 0.013 ms，输出 27,763 → 262 字节。纯背景色块整帧输出 875,352 → 449,826 字节。
+- 这些结果衡量转换、编码及输出量，不包含实际终端绘制或网络传输。整帧高色彩变化图案仍需约 923 KB，仍受 1 MiB/s 输出预算限制；不能将转换耗时的倒数作为远程显示帧率。默认本地目标为 8 FPS，`--fps 15` 可请求更高目标，预览订阅还需要对端支持 15 FPS。
+- 额外检查代码、模拟器、基准和产物均位于工程外临时目录；未进行跨平台终端或真实远端帧率验收。
+
+## Kitty 帧间黑屏与本地吞吐修复（2026-10-30）
+
+- macOS arm64 debug、release 构建通过，release `doctor --json` 通过。release 使用工程外独立配置构建，保留工程原有 debug 配置；额外检查脚本、伪终端夹具和数据均位于系统临时目录。
+- ASan/UBSan 检查及 Kitty 协议模拟验证：ID 31/32 交替上传，所有上传分块完成前旧图保持显示；先创建新图 placement，再释放旧图；最多两个完整图像驻留，切换后只保留一个。新旧输出的解压 RGB 和尺寸逐字节一致，覆盖尺寸、偏移和缩放变化；单帧小于 2MiB，全部分块边界的中断清理通过。
+- ANSI 的 half／quadrant／ASCII 和 8／24／256 色共 12 种组合，转换单元及输出字节与此次修改前一致。
+- 使用生产 `View`、`Output` 和 Kitty 编码代码、`-O2`、合成 NV12 持续回调的本地 PTY 对比：目标 8 FPS，单帧约 1.25 MB，稳定完整接收速率约 0.84 → 6.71 FPS，帧间隔中位数约 1,192 → 148 ms。只衡量完整输出接收，不包含真实网络、视频解码和 Ghostty GPU 显示，不能作为实机帧率承诺。
+- 本地 Kitty 的日志预算为 8MiB/s；分别仅设置 `SSH_TTY`、`SSH_CONNECTION`、`SSH_CLIENT` 时均保持 1MiB/s，ANSI 也保持 1MiB/s。连续帧 ID 仅在完整写入后交替，退出清理两个 ID。
+- 慢速 PTY 在第二帧上传中退出：首帧保留、第二帧未提交，约 2.06s 后退出；两个 ID 清理、备用屏幕／光标控制序列和原 termios 均恢复。测试发现原单次清理写入会在满缓冲区时丢失，现增加至多 500ms 的非阻塞短写重试。
+- 模拟父 shell 保持会话、终端完全停止读取的 PTY：CLI 约 2.53s 后返回，termios 和非阻塞标志恢复。POSIX 恢复改为 `TCSANOW` 加输入清理，避免 `TCSAFLUSH` 等待输出排空。完全不读取时，屏幕清理字节不保证送达。
+- 本机安装 Ghostty 1.4.0，但自动化工具拒绝访问其窗口，未完成 Ghostty 实窗视觉验收。npm 安装的 CLI 不会随本地构建自动更新，复测需要直接运行本次 release 产物。
+
+## 本地 Kitty 共享内存与 30 FPS 目标（2026-10-30）
+
+- 本地 POSIX Kitty 增加共享内存能力探测、唯一名称、0600 权限、上传确认和 500ms 超时回退。单个待确认共享缓冲区不超过 1920×1080×3 字节；确认前保留旧画面，退出释放未确认对象。Windows 暂保留内联路径，SSH 不发共享内存探测。
+- 共享内存可用且未显式指定 `--fps` 时默认目标 30；自动回退内联恢复 8，显式帧率保持不变。目标大于 15 使用现有预览协议的交互模式 `fps=60, frame_rate=30`；没有新增协议取值或修改被控端。
+- 工程外 ASan/UBSan 检查通过：110 组随机帧／视口／宽高比／缩放／细节模式，整数面积滤波相对原浮点参考的每通道最大误差为 1/255；内联 Kitty 和 ANSI 保持原输出。覆盖共享内存权限、读取内容、命名、容量限制、双方 unlink、分片确认及非法／溢出／重复 ID 回应。
+- 使用实际 release CLI 对象代码、1920×1080 合成噪声 NV12 连续回调、1568×1088 报告视口的 PTY 测试：内联完整接收约 4.06 FPS，共享内存约 29.04 FPS；平均本地处理约 166.6 → 12.3 ms，终端字节流约 1,703,174 → 188 字节/帧。共享内存仍传输完整 RGB，并非总数据量只有 188 字节；数据复制、终端绘制和实际网络另有成本。
+- 显式 8 FPS、探测不支持／静默、第三帧上传报错／丢失确认、80ms 延迟确认、SSH 禁用探测均通过。回退前不显示未确认帧，运行时回退仅触发一次，并正确恢复自动目标和协议请求；所有共享对象均清理。第二帧上传后立即退出时，首帧仍是已提交画面，未确认对象及两个图像 ID 均清理。
+- 相同合成输入的 debug 构建约 5.91 FPS，本地处理约 163 ms，说明 `-O0` 仍明显影响像素转换；性能验收使用 release。上述精确数字是本地测试接收速率，不是 Ghostty GPU 显示帧率。
+- 用户在本机 Ghostty 运行新版 release 后反馈“明显流畅了”。额外测试源码、数据、构建夹具和产物均位于系统临时目录，未在工程或子模块新增测试。
+- 该次实机日志确认 `kitty_transport=shared_memory`、目标 30、预览请求已接受、运行时回退 0 次。会话约 13.61s 完整提交 273 帧，平均提交约 20.06 FPS（包含约 1.49s 首帧启动等待）；平均本地处理约 10.87ms、共享内存确认约 0.42ms。该日志记录提交速率，不测量终端 GPU 呈现频率。
+
 ## 实测边界
 
 本地检查不涵盖 Linux / Windows 完整构建、跨平台远程控制、Kitty/SSH 实际终端显示、真实 Pi TUI 或长时间资源占用。五个平台 CI 配置与 npm 包名均不代表已发布或已验收。