Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# 显示快照的有界解码与宽字符边界

## Status

#235 的候选审计修正,待审核。沿用现有 JSON 字段,不改变后台发布协议。

## Context

编码文件的字节限额不能代替解码对象限额。先反序列化嵌套 Vec 再 validate,
会在拒绝输入前分配大量空行、单元格或组合字符。宽字符占位参与文本提取和
重排;行首孤立占位会使文本提取回退到负列。另一方面,终端删除半个宽字符
后的重排可能留下孤立标志,严格拒绝会让正常编辑后的输出无法恢复。

## Evidence

- [解码器](../../../../pebrel_terminal/src/grid/snapshot/serialization.rs)原先先生成完整 WireSnapshot。
- [快照回归测试](../../../../pebrel_terminal/src/grid/snapshot.rs)用超限有效元素后接畸形尾部,证明解码必须先因预算失败;包括跨单元格累计组合字符。
- 同处真实解析器测试覆盖中文、组合字符以及删除、插入、擦除后三种列宽的重排。

## Decision

通过 serde DeserializeSeed 按行读取,每读入一个单元格即扣减预算。不信任
size_hint,不按输入提示预分配。行、单元格与单格组合字符在读取中计数,累计组合
字符在每个单元格读完后扣减;各项均不超过 262_144。后续 validate 仍检查尺寸和
控制数据。保留 JSON 对象字段顺序无关的合同。

捕获与导入共用同一规范化:清除互斥宽字符标志、未配对的宽字符/占位以及错误位置
的跨行前导占位,保留字符、颜色、组合字符和其他标志;末行跨行占位可以没有下一行。
倒序处理确保前导占位看到已规范化的下一行。行首孤立占位因此不会进入文本提取;
活终端不变。

## Rejected alternatives

- 只在整个 Vec 建成后校验:拒绝太晚,不能限制解码期间分配。
- 每个单元格单独限制组合字符:无法限制所有单元格的累计量。
- 导入严格拒绝畸形宽字符标志:需与捕获分设两套规则,且一个无效标志即丢弃整段输出。
- 依赖 columns 已先读取:会破坏已有 JSON 字段顺序无关的格式。
- 所有跨行占位必须有下一行:误拒绝合法的有界裁剪。
- 直接修活网格:改变正常终端编辑行为。

## Consequences

资源与结构校验属于 terminal 快照边界,不增加应用依赖、数据迁移或新配置。
旧格式的正常快照继续可读;超预算或尺寸/控制数据畸形的快照拒绝,应用降级为无旧
输出。无效宽字符标志仅从快照副本移除,不承诺修复终端核心的编辑行为。

## Validation

`cargo test --offline --locked -p nebula_terminal --features serde` 全套通过。
新测试在原解码器上失败(超限尾部被读取、孤立占位保留),并用真实解析器覆盖中文
半字符删除/插入/擦除后在三种列宽下重排的正常快照不被改动。

## Supersedes

None。

## Revisit when

改变 wire 格式、快照资源上限、宽字符布局或主屏捕获边界时重新核验。
1 change: 1 addition & 0 deletions pebrel_terminal/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
- 不为 UI 需求在终端核心增加产品概念。确需新接口时,公开最小命令/结果并保持状态私有。
- 重大协议、缓冲、线程、所有权或兼容性决策写入 `architecture/notes/pebrel_terminal/<capability>/`;普通回归修复只需测试和变更说明。
- 快照中的 DIM 与反色颜色归属见 [`render`](../architecture/notes/pebrel_terminal/render/);颜色保持未解析,前端统一处理调色板和 OSC 覆盖。
- 滚动历史显示快照的解码预算和宽字符边界见 [静态网格快照](../architecture/notes/pebrel_terminal/grid/2026-09-28-bounded-display-snapshot-decoding.md)。
- ZMODEM(rz/sz)只做识别并自动取消,不实现传输;依据见 [`zmodem`](../architecture/notes/pebrel_terminal/zmodem/2026-11-05-cancel-unsupported-zmodem.md)。
- OSC 7501 记录、PTY 生命周期和 GPUI 投影的边界见 [`program_status`](../architecture/notes/pebrel_terminal/program_status/)。
- 有界输出载荷、命令捕获与网格标记的所有权见 [`inline_content`](../architecture/notes/pebrel_terminal/inline_content/2026-10-21-bounded-output-store.md);前端分类命令,核心不解释 MIME 正文。
1 change: 1 addition & 0 deletions pebrel_terminal/src/grid/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ use crate::vte::ansi::{CharsetIndex, StandardCharset};

pub mod resize;
mod row;
pub mod snapshot;
mod storage;
#[cfg(test)]
mod tests;
Expand Down
Loading
Loading