Files
LN-Code-Editor/packages/xterm/PATCHES.md
T
2026-09-16 11:58:58 +08:00

3.2 KiB
Raw Blame History

本地补丁说明(vendored xterm)

本目录是 xterm 的内置副本(vendored),来源:pub.dev xterm 4.0.0。 引入原因:上游 4.0.0 存在一个会破坏终端框选(选区无法绘制 / 复制为空)的内核缺陷, 而该缺陷位于包内部(无法在应用层通过公开 API 修正),因此内置并打补丁。

上游来源

  • 包名 / 版本:xterm 4.0.0
  • 来源:https://pub.dev/packages/xterm(xterm-4.0.0)
  • SHA256(pub.dev 归档):168dfedca77cba33fdb6f52e2cd001e9fde216e398e89335c19b524bb22da3a2
  • 复制范围:lib/、pubspec.yaml、LICENSE、CHANGELOG.md、README.md、analysis_options.yaml (未复制 test/、example/、bin/、media/、script/)

补丁清单

1. lib/src/utils/circular_buffer.dart → IndexAwareCircularBuffer.trimStart()

上游缺陷:原实现只调整 _startIndex / _length,既不 _detach() 被裁掉的元素, 也不同步 _absoluteStartIndex:

void trimStart(int count) {
  if (count > _length) count = _length;
  _startIndex += count;
  _startIndex %= _array.length;
  _length -= count;
}

后果一:IndexedItem.index(_absoluteIndex - _absoluteStartIndex)不再等于元素在列表中的位置, 而是整体偏移“被裁掉的行数”。BufferLine.index 正是 CellAnchor.y / CellAnchor.offset 的来源, 而同一个 y 在 xterm 内部被当作 lines[y] 下标使用(RenderTerminal._paintSelection、 Buffer.createAnchorFromOffset、Buffer.getText(range)、TerminalController.selection), 于是锚点与行坐标系自相矛盾:选区画不出来、复制得到空串或别的行。

后果二:被裁掉的行从不 _detach(),仍 attached == true 且留在 _array 中, 旧锚点既不失效、又会静默指向其它行(“僵尸锚点”)。

触发链:shell 的 clear / Ctrl+L 发出 ESC[3J(ED3,xterm-256color 带 E3 能力) → Terminal.eraseScrollbackOnly() → Buffer.clearScrollback() → trimStart(scrollBack)。 之后终端“再也无法框选”,且错误一直残留到会话销毁。

修复:委托给上游自身已验证的 remove(0, count) —— 它会 _detach() 被移除的元素, 并用 _move() 重新校准存活元素的绝对索引,两个后果一并消除。代价是“只调窗口”变成 O(存活元素) 的搬移,而调用场景(清空回滚缓冲)是低频操作。

守护测试:test/xterm_trim_start_patch_test.dart

重新 vendor / 升级流程

  1. 删除本目录(packages/xterm)。
  2. 从 pub cache 或 pub.dev 解包目标版本,按上面“复制范围”复制到本目录。
  3. 依据本文件的“补丁清单”重新应用补丁(对照上游最新 trimStart() 实现)。
  4. 更新本文件顶部的版本 / 来源 / SHA256。
  5. 运行守护测试:flutter test test/xterm_trim_start_patch_test.dart。 若上游已自行修复该缺陷,可删除补丁并保留测试(测试断言的是不变式,不是补丁本身)。
  6. flutter pub get 后跑一遍终端相关测试: flutter test test/terminal_selection_and_menu_test.dart test/terminal_test.dart test/toolchain_service_test.dart