chuan/ttui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e78ce2badf3cd23008c1b0f3e7e8a7e0975740e8
ttui/TODO.md
T
chuan e78ce2badf feat: expand terminal key protocol parsing 
- add key event phase metadata for parsed input events

- parse Kitty CSI-u and modifyOtherKeys style key sequences

- filter release events from keybinding dispatch by default

- cover Shift+Tab and Kitty key parsing with xUnit regressions
2026-06-04 03:05:38 +08:00

46 KiB
Raw Blame History

TODO

当前定位

TinyTUI 现在已经具备最小可运行的 C# TUI 框架骨架：终端输入输出、输入缓冲、按键解析、运行时、组件树、差分渲染、overlay、基础组件和示例都已经成型

后续 TODO 不再按单个控件的小功能罗列，而是对齐 tmp/tui 的完整框架能力，优先补齐会影响整个 TUI 可用性、稳定性、可扩展性和可验证性的部分

框架级缺口

1. 终端会话能力

目标：把当前 console 封装升级成完整的终端会话抽象，负责启动、停止、协议协商和状态恢复

  • 管理 bracketed paste、光标显示隐藏、清屏、窗口标题、进度指示等终端模式
  • 启动时保存原始终端状态，停止时稳定恢复，避免 raw mode、paste mode、键盘协议泄漏到父 shell
  • 支持 Kitty keyboard protocol 探测和启用，失败时 fallback 到 modifyOtherKeys
  • Windows 下处理 Virtual Terminal Input，保证 Shift+Tab、组合方向键等输入不会丢失修饰键
  • 停止前 drain stdin，避免慢 SSH 或终端延迟导致的按键释放事件泄漏
  • 提供可替换的 Terminal 接口，为真实终端和测试终端使用同一套运行时

参考：tmp/tui/src/terminal.ts

本次推进：

  • 新增 ITerminalSession，把输入、输出、尺寸、启动停止和终端控制序列收敛为一个可替换的会话抽象
  • 新增 ConsoleTerminalSession，统一管理 bracketed paste、光标显示隐藏、窗口标题恢复、OSC 9;4 进度指示、Windows Virtual Terminal Input、退出前输入 drain 和停止时模式恢复
  • TuiRuntime 改为依赖终端会话，保留旧 ITerminalInput 构造函数用于兼容现有调用方
  • Example 改为用同一个 terminal session 同时提供 renderer 输出和 runtime 生命周期

为什么先做：

  • tmp/tui/src/terminal.ts 的能力不是单个输出方法，而是完整生命周期对象；先把 C# 侧入口统一起来，后续 Kitty protocol、modifyOtherKeys、虚拟终端测试和渲染管线才能接在同一个抽象上
  • 当前实现把 Runtime 从“直接控制 input 生命周期”推进到“只协调组件和会话”，终端状态恢复责任更清晰

当前更好的点：

  • C# 侧接口直接继承 ITerminalOutput，Renderer 和 Runtime 可以共享同一个 terminal session，避免真实终端和测试终端各自维护两套输出入口
  • 保留旧构造函数降低迁移成本，现有使用 ITerminalInput 的代码不会立刻断裂

后续仍需补齐：

  • Kitty keyboard protocol 目前只预留 KittyProtocolActive 和停止恢复序列，还没有实现查询、响应解析、启用和 fallback 到 modifyOtherKeys
  • Windows VT input 已用 P/Invoke 处理 console mode，但还需要结合真实终端验证 Shift+Tab、Ctrl+方向键、Alt 组合键在不同宿主中的表现
  • DrainInput 目前是基于 Console.KeyAvailable 的同步排空，后续要和 stdin buffer / keyboard protocol release 事件联动，避免吞掉应由应用处理的 late input
  • 标题恢复当前只在 Windows 通过 Console.Title 尝试保存；Unix 终端通常无法可靠读取原始标题，后续可以增加可选 title stack 或由调用方提供恢复标题
  • ITerminalSession 还缺键盘协议协商事件和测试 fake terminal，实现虚拟终端回归测试前需要继续抽象可观测输出和模拟输入

2. 输入协议和 Keybinding 系统

目标：把按键解析从“组件里判断具体 key name”升级为“协议解析 + 动作映射”的框架能力

  • 完整处理 Kitty keyboard protocol 的 press、repeat、release 和 alternate key 信息
  • 支持 key release 过滤，并允许组件声明是否接收 release 事件
  • 建立统一 KeyId 表达和 MatchesKey 能力，避免组件分散处理 escape sequence
  • 建立全局 keybinding registry，按动作名绑定默认快捷键，并允许外部覆盖
  • 提供 keybinding 冲突检测，避免多个动作抢同一个快捷键
  • 输入 listener 支持全局拦截和 consume，用于 debug、退出、快捷命令等框架级输入

参考：tmp/tui/src/keys.ts、tmp/tui/src/keybindings.ts

本次推进：

  • 新增 KeyId，把组件使用的按键名称收敛为可比较、可匹配的标准按键标识，并兼容 pageUp/pageDown 与当前 page-up/page-down 命名差异
  • 新增 KeybindingDefinition、KeybindingConflict、KeybindingRegistry 和 TuiKeybindings，建立动作名到默认快捷键的注册表、用户覆盖入口和冲突检测
  • Input、SelectList、Editor 改为通过 keybinding 动作处理快捷键，不再在组件内直接散落判断具体 key name
  • 组件构造函数支持注入 KeybindingRegistry，外部可以先在组件级覆盖默认快捷键，后续再接到运行时级全局配置

为什么先做：

  • tmp/tui/src/keybindings.ts 的关键价值是把“按键是什么”和“动作是什么”拆开；先补 registry 后，自动补全、选择列表、编辑器和全局快捷命令可以复用同一个动作系统
  • C# 侧目前解析器已经能产出标准 key name，本次先不扩大到 Kitty 完整协议，避免同时重写输入解析和组件行为造成不可控回归
  • 保持 IInputComponent.HandleInput(TuiInputEvent) 不变，只在组件内部使用 action matching，兼容现有 Runtime 和 Example

当前更好的点：

  • C# 侧 KeybindingRegistry.SetUserBinding 会校验动作名，调用方写错动作会立即抛错，而不是静默忽略
  • 默认动作常量集中在 TuiKeybindings，组件调用处能直接看出“行为意图”，比继续比较 ctrl+... 字符串更容易维护
  • 单行输入、选择列表和多行编辑器已经区分 tui.input.*、tui.select.*、tui.editor.*，后续做用户配置时不会因为复用 Enter 语义互相污染

后续仍需补齐：

  • KeyId 目前仍基于已解析的 key name 匹配，还没有像 tmp/tui/src/keys.ts 那样直接识别 raw escape sequence 或完整协议元数据
  • Kitty keyboard protocol 已有基础 press、repeat、release 和 alternate key 解析，但还没有为组件提供是否接收 release 事件的声明能力
  • KeybindingRegistry 目前只支持组件级注入，尚未接入 Runtime 统一持有，也没有全局 input listener、拦截、consume 和 debug 快捷键入口
  • 冲突检测当前对用户覆盖生效，后续可以增加“默认绑定冲突是否允许按上下文共存”的策略，比如 editor/select 都使用 Enter 但不会同时处理
  • DefaultInputParser 还需要继续补 parseKey 级能力：空格、Ctrl+符号、Alt+方向键、Windows Ctrl+Backspace 等特殊兼容路径

本次 Runtime 级推进：

  • TuiRuntime 改为统一持有 KeybindingRegistry，构造函数支持传入外部 registry，并通过 ITuiRuntime.Keybindings 暴露给运行时级输入监听器
  • 新增 TuiInputListener 和 TuiInputListenerContext，全局 listener 可以读取当前输入、Runtime 和共享 keybinding registry
  • ITuiRuntime.AddInputListener 支持按注册顺序添加全局输入监听器，返回 IDisposable 句柄用于注销
  • TuiRuntime.Dispatch 改为先执行全局 listener，任一 listener 返回 consumed 后立即停止后续 listener，并阻止输入继续派发到焦点组件
  • consumed 和未 consumed 的输入都会在 Dispatch 末尾走统一 RequestRender，保证全局快捷键修改状态后可以触发刷新
  • 新增 xUnit 回归测试，覆盖 listener 顺序、consume 阻止焦点组件收到输入、不 consume 继续派发、注销句柄、listener 使用 Runtime registry 匹配动作

为什么这样做：

  • 对齐 tmp/tui/src/tui.ts 的 addInputListener 思路，把 debug、退出、快捷命令等框架级输入入口放在 Runtime，而不是继续分散到组件
  • C# 侧保留 IInputComponent.HandleInput(TuiInputEvent) 不变，只在 Runtime 派发前增加拦截层，避免组件体系和已有 Example 大面积重构
  • listener 派发前复制快照，允许监听器在回调中注册或注销其他监听器，本轮输入顺序仍保持稳定

当前更好的点：

  • Runtime 级 registry 是构造注入的实例属性，测试和应用可以显式传入自定义快捷键配置，不依赖全局静态状态
  • 注册 API 返回 IDisposable，适合 C# 的 using 生命周期，也比单独暴露 remove 方法更不容易忘记注销
  • TuiInputListenerContext.Keybindings 是便捷属性，listener 写全局快捷键时不需要知道 Runtime 内部字段

后续仍需补齐：

  • 还没有补 removeInputListener(listener) 形式的 API；当前以 IDisposable 句柄为主，若需要和参考实现更一致可再增加等价注销方法
  • listener 当前是同步 bool 契约，尚未支持异步命令、取消令牌、异常隔离和按优先级/作用域管理监听器
  • 输入协议已有 Kitty keyboard protocol 的基础 press、repeat、release、alternate key 和 release 过滤，还没有组件声明能力或完整 raw matching
  • 仍缺 Runtime + virtual terminal 的端到端屏幕断言，本次只覆盖输入派发路径和渲染请求计数

本次 Runtime 共享注入推进：

  • 新增 IKeybindingComponent，让内置输入组件可以在进入 Runtime 后接收共享 KeybindingRegistry
  • Input、SelectList、Editor、CancellableLoader 改为实现该接口，保留构造函数显式传入 registry 的兼容性
  • TuiRuntime.Add 和 ShowOverlay 会在组件进入根树或 overlay 栈前注入 Runtime.Keybindings
  • Runtime 注入会递归处理内置 Container.Children 和 Box.Child，避免容器里的输入组件继续使用各自默认 registry
  • Editor.SetKeybindings 会同步更新内部 AutocompleteList，确保补全候选列表导航也走 Runtime 共享配置
  • 新增 xUnit 回归测试，覆盖根输入组件、overlay 列表、容器子组件和 Editor 内部补全列表使用 Runtime 自定义快捷键

为什么这样做：

  • 对比 tmp/tui/src/keybindings.ts 的 getKeybindings() 全局 manager，C# 侧已有 Runtime 实例级 Keybindings，显式注入更适合测试隔离和多 Runtime 场景
  • 注入点放在 Add 和 ShowOverlay，是因为这是组件真正进入运行时输入派发范围的边界，能让组件离线构造时仍保持原有默认行为
  • 递归只覆盖当前内置容器类型，不引入反射扫描，减少第三方组件属性命名或生命周期被 Runtime 误触碰的风险

当前更好的点：

  • 自定义 keybinding 现在能真实影响焦点组件行为，而不只是 Runtime listener 可见
  • C# 侧可以给每个 Runtime 持有独立 registry，比参考实现的模块级全局 keybindings 更容易做并发测试和多终端实例
  • Editor 内部补全列表与编辑器共享同一 registry，避免外层动作覆盖生效但内层选择列表仍用默认键的割裂行为

后续仍需补齐：

  • Runtime 只知道内置 Container 和 Box 的子组件结构，第三方复合组件若要递归注入仍需要自己实现 IKeybindingComponent 并转发给子组件
  • Container.Add 在容器已经挂到 Runtime 之后再动态添加子组件时，目前不会自动触发 Runtime 注入；后续可以引入组件挂载上下文或 Runtime-aware container
  • 已补 tmp/tui/src/keys.ts 里的 Kitty press、repeat、release、alternate key 基础解析，仍缺组件声明是否接收 release 事件和完整 raw matching
  • keybinding 冲突检测仍主要针对用户覆盖集合，后续需要补作用域或上下文策略，避免全局配置复杂后误报或漏报

本次协议解析推进：

  • 新增 TuiKeyEventType，让 TuiInputEvent 可以承载 Press、Repeat、Release 三种按键阶段，并保留现有两参数构造默认 Press 的兼容行为
  • TuiInputEvent 增加 AlternateKey 和 RawSequence 元数据，用于承载 Kitty CSI-u alternate key 和原始协议序列，现有组件仍继续读取 Value
  • DefaultInputParser 增加 Kitty CSI-u 基础解析，覆盖普通 codepoint、Ctrl/Alt/Shift/Super modifier、event type、shifted alternate key、base layout key 和 Kitty keypad functional codepoint 归一化
  • DefaultInputParser 增加带 event type 的 Kitty final-byte 功能键解析，并保留无 event type 的 legacy modified CSI 行为，避免 ESC[1;2A 这类旧序列因为新增元数据影响现有相等断言和组件行为
  • DefaultInputParser 增加 xterm modifyOtherKeys CSI 27 ; modifier ; codepoint ~ 解析，覆盖 Ctrl+字母、Shift+Tab、Alt+Enter 等组合键
  • 补齐 ESC[Z Shift+Tab 和 legacy Alt+字母解析，减少组件或测试直接识别 raw escape sequence 的需求
  • release 事件默认在 parser 层不派发，同时 KeybindingRegistry.Matches 对手工构造的 release 事件也默认不匹配，避免释放阶段误触发组件动作
  • 新增 xUnit 回归测试，覆盖 Shift+Tab、Alt+字母、Kitty 普通字符、Ctrl/Shift 组合、repeat 阶段、alternate key 元数据、modifyOtherKeys 组合键和 release 过滤

本次当前更好的点：

  • C# 侧把按键阶段作为 TuiInputEvent 的强类型字段，不依赖类似 isKeyRelease(data) 的全局最近解析状态，Runtime listener 和组件拿到事件后可以直接判断来源阶段
  • release 过滤同时放在 parser 和 keybinding registry 两层，真实终端输入不会派发 release，测试或外部代码手工构造 release 事件时也不会误匹配默认动作
  • 协议解析后仍输出原有 Value key name，组件和 keybinding registry 不需要立刻迁移到 raw sequence 匹配模型
  • Kitty final-byte 解析只接管带 :event 的新协议形态，旧 xterm modified CSI 仍走原逻辑，避免为了新增元数据破坏已有 record 相等和 legacy 行为

本次后续仍需补齐：

  • 还没有实现组件声明是否接收 release 事件的 API；当前策略是框架默认过滤，后续若需要 key-up 交互要给 Runtime listener 或组件增加 opt-in 通道
  • AlternateKey 目前只承载 shifted alternate key，base layout key 用于解析匹配但没有单独暴露字段；后续如果要完整支持非 Latin 布局调试和用户配置，应扩展为结构化元数据
  • modifyOtherKeys 目前覆盖基础 CSI 27 ; modifier ; codepoint ~，还没有处理所有参考实现中的 printable duplicate drop、Windows Ctrl+Backspace heuristic、legacy Ctrl+符号兼容路径
  • parser 仍不是完整 tmp/tui/src/keys.ts 的 matchesKey raw sequence 模型，KeyId 还不能直接匹配 raw Kitty/modifyOtherKeys 序列，只是依赖解析后的 Value
  • 终端协议协商仍属于 TODO 1，没有在本轮启用 Kitty keyboard protocol 或 fallback 到 modifyOtherKeys，也没有处理退出时恢复协议状态

3. 渲染管线和视口模型

目标：把当前按行差分刷新升级成能长期运行、低闪烁、能处理滚动区域和复杂内容的渲染管线

  • 使用 synchronized output 包裹每次渲染，降低闪烁和中间态显示
  • 维护 viewport top、工作区高度、硬件光标位置和上一帧尺寸，避免内容增长或缩短时滚动错位
  • 区分首次渲染、宽度变化、视口外变化、普通差分更新、内容缩短清理等策略
  • 每行输出前统一追加 SGR reset 和 OSC 8 reset，避免 ANSI 样式或超链接泄漏到后续行
  • 在渲染层校验每行可见宽度不超过终端宽度，错误时提供可定位的调试信息
  • 增加可选写出日志和重绘调试日志，方便定位真实终端中的闪烁、残影和错位问题

参考：tmp/tui/src/tui.ts

本次推进：

  • 新增 RenderFrameBuilder、RenderedFrame、RenderViewportState 和 RenderPipelineOptions，把组件输出统一转换成逻辑帧、可见视口帧和可调试的渲染状态
  • DifferentialRenderer 改为维护上一帧尺寸、viewport top、working height 和内容高水位，能区分首次渲染、宽度变化、高度变化、viewport 变化、内容缩短和普通差分更新
  • 每次实际写终端时使用 synchronized output 包裹，并且每行统一追加 SGR reset 和 OSC 8 reset，降低闪烁和样式/超链接泄漏风险
  • 渲染层先校验可见宽度，默认继续按当前文本模型截断作为兼容防线，也支持通过 ThrowOnWidthOverflow 让组件宽度溢出直接暴露
  • 增加 TINYTUI_DEBUG_REDRAW 和 TINYTUI_DEBUG_RENDER 对应的重绘/差分日志，默认写到临时目录下的 tinytui
  • FullScreenRenderer 也复用同一套帧构建逻辑，避免全量渲染和差分渲染在截断、cursor marker、行尾 reset 上行为不一致

为什么先做：

  • tmp/tui/src/tui.ts 的渲染稳定性核心不是单个 escape sequence，而是“渲染前归一化 + viewport 状态 + full redraw 策略 + 差分写入”组合；先把 C# 侧帧模型抽出来，后续 overlay、文本工具和图像能力都能接入同一条管线
  • 当前组件仍可能输出超过终端宽度的内容，本次保留截断兼容，同时提供溢出日志和可选异常，避免一次性把所有组件改成严格模式造成使用方回归
  • 先采用 bottom viewport 模型，只渲染终端可见的最后 Rows 行，能避免内容高度超过终端时继续用绝对行号写到不可见区域

当前更好的点：

  • C# 侧把渲染帧构建抽成内部类型，DifferentialRenderer 和 FullScreenRenderer 共享同一套规则，后续做测试 fake output 时更容易只验证帧输出和状态
  • RenderPipelineOptions 是显式对象，不完全依赖环境变量，测试和调用方可以按实例控制 synchronized output、行 reset、缩短清理和溢出策略
  • ViewportState 暴露最近一次渲染状态，Example 或后续测试可以直接检查 viewport top、working height 和 logical line count

后续仍需补齐：

  • 当前 viewport 变化直接触发全量重绘，还没有像 tmp/tui/src/tui.ts 那样在部分追加行场景里精确滚动并更新 hardware cursor row
  • 宽度校验仍依赖现有 TerminalTextMeasurer，还没有 grapheme cluster、Kitty image line、OSC/APC 完整识别和按列严格切片能力
  • 内容缩短清理现在对所有 shrink 默认 full redraw，后续可以增加 overlay-aware 策略，避免 overlay 需要 padding 时误清理工作区
  • 调试日志目前记录帧和变化行，但还没有写出最终 ANSI buffer，也没有像参考实现那样在崩溃前恢复终端会话状态
  • 硬件光标位置目前仍以绝对 MoveCursorTo 到可见行处理，尚未维护 hardwareCursorRow 与相对移动模型，IME 定位在复杂滚动场景下还需要真实终端验证

4. Overlay 合成正确性

目标：让 overlay 成为菜单、弹窗、自动补全、设置面板等上层交互的稳定基础

  • 合成时保留 overlay 右侧的底层内容，而不是简单截断整行
  • 处理 ANSI、OSC 8 超链接、APC、Kitty image sequence 等不可见序列
  • 使用按列切片和宽字符边界保护，避免中文、emoji、regional indicator 在 overlay 边界被切坏
  • overlay 前后插入样式 reset，避免底层样式污染 overlay 或 overlay 样式污染底层
  • 完善多层 overlay 的焦点恢复策略，处理 overlay 被临时隐藏、释放焦点、被其他组件短暂抢焦点后的恢复
  • 支持 overlay 显示区域与底部视口对齐，避免在内容超过终端高度时覆盖位置偏移

参考：tmp/tui/src/tui.ts、tmp/tui/test/tui-overlay-style-leak.test.ts、tmp/tui/test/overlay-short-content.test.ts

本次推进：

  • 新增 TextSlice 和 ITextMeasurer.Slice，让文本工具可以按终端可见列切出片段并返回实际宽度
  • TerminalTextMeasurer.Slice 使用单次扫描处理 ANSI、OSC、APC、DCS 等不可见序列，并在 strict 模式下跳过压到边界的双宽字符
  • OverlayManager.ComposeLine 改为拼接底层左侧、overlay 区域和底层右侧，不再因为 overlay 覆盖一段内容就丢弃整行右侧内容
  • overlay 段前后插入 SGR reset 和 OSC 8 reset，降低底层样式污染 overlay、overlay 样式污染右侧底层内容的风险
  • overlay 行坐标改为映射到底部 viewport 的逻辑行，内容超过终端高度时 overlay 仍按当前屏幕可见区域定位

为什么先做：

  • tmp/tui/src/tui.ts 的 compositeLineAt 首先解决的是 overlay 短内容覆盖长底层行时的残留和截断问题；C# 侧原实现明确丢弃了右侧底层内容，这是菜单、补全列表和浮层提示最容易出现的视觉回归
  • 按列切片必须下沉到文本工具，否则 overlay、渲染管线和后续组件会继续各自用字符串长度或局部截断逻辑处理 ANSI 内容
  • 本次只引入轻量 TextSlice，不直接引入完整 grapheme / style tracker，避免把 TODO 第 5 项文本模型重构提前扩大

当前更好的点：

  • C# 侧把按列切片挂到 ITextMeasurer，后续组件可以先复用同一入口，不需要等完整文本模型落地
  • overlay 合成现在和第 3 项的 bottom viewport 模型对齐，短内容和超高内容都使用同一套屏幕坐标逻辑
  • reset 隔离在 overlay 合成层执行，即使 overlay 组件输出缺少结尾 reset，也能降低样式泄漏到右侧底层内容和后续行的概率

后续仍需补齐：

  • TerminalTextMeasurer.Slice 仍按 Rune 处理，不是 tmp/tui/src/utils.ts 那样的 grapheme cluster 切片；ZWJ emoji、肤色、regional indicator 等复杂组合还可能被切开
  • overlay 右侧底层内容现在会被 reset 隔离，但还没有像参考实现的 extractSegments 那样追踪并恢复切片前的活动 SGR 样式，因此右侧内容的继承样式可能丢失
  • 当前没有识别 Kitty image line，overlay 合成还不会像参考实现一样跳过图片行或管理已显示图片 id
  • ITextMeasurer 的默认 Slice 是兼容 fallback，遇到带 ANSI 的非 TerminalTextMeasurer 实现时不如专用实现可靠，后续文本模型稳定后应收敛为显式能力
  • 还缺 C# 虚拟终端测试，无法自动覆盖 overlay 短内容保留右侧、样式泄漏、宽字符边界和底部 viewport 对齐这些回归

5. 文本模型和 ANSI 感知工具

目标：把文本宽度、截断、切片、换行作为框架底座，而不是散落在组件里的局部逻辑

  • 用 grapheme cluster 计算宽度，覆盖 ZWJ emoji、肤色、variation selector、regional indicator
  • 提供 ANSI / OSC 感知的 VisibleWidth、TruncateToWidth、SliceByColumn、WrapTextWithAnsi
  • 支持 tab 宽度配置
  • 截断和换行时保持 ANSI 样式闭合，并在换行后恢复必要样式
  • 抽象 terminal output normalization，统一清理和补齐行尾 reset
  • 所有组件渲染统一依赖这套文本工具，减少宽度计算不一致导致的渲染 bug

参考：tmp/tui/src/utils.ts

本次推进：

  • TerminalTextMeasurer 从 Rune 扫描升级为 ANSI / OSC 感知的 grapheme cluster token 扫描，统一用于可见宽度、截断和按列切片
  • 支持可配置 tab 宽度，默认按 tmp/tui 的 3 列处理，避免 tab 在切片、overlay 和渲染宽度中计算不一致
  • 对 ZWJ emoji、variation selector、regional indicator 和常见 emoji 区间按终端双宽处理，降低流式输出中 emoji 中间态导致的差分渲染漂移
  • 新增带 ellipsis 和 pad 参数的 ANSI 感知截断，截断时保留样式前缀，并在省略符前后插入 SGR reset，避免样式污染省略符和后续内容
  • 新增 ITextMeasurer.Wrap 和 TerminalTextMeasurer.Wrap，提供 ANSI / OSC 8 感知换行，支持长词按 grapheme 切分、续行恢复活动 SGR 样式、行末临时关闭 underline 和 OSC 8 超链接
  • 新增 test/TinyTUI.TextChecks 最小文本检查项目，覆盖 tab、regional indicator、ZWJ emoji、variation selector、ANSI 截断、宽省略符、ANSI 换行和 OSC 8 BEL 超链接续行

为什么先做：

  • 第 3 项渲染管线和第 4 项 overlay 合成都已经依赖 ITextMeasurer 的宽度、截断和切片；先把文本底座升级后，可以减少组件、overlay、renderer 各自实现宽度规则导致的错位
  • tmp/tui/src/utils.ts 的核心能力是同一套 grapheme/ANSI 工具支撑 visibleWidth、truncateToWidth、sliceWithWidth 和 wrapTextWithAnsi，本次选择在 C# 侧先收敛到 TerminalTextMeasurer，保持现有公开入口简单
  • 换行先处理 ANSI SGR 与 OSC 8，是因为 Markdown、Editor、SelectList 后续都需要长链接、带颜色文本和 underline 内容稳定换行

当前更好的点：

  • C# 侧把 Wrap 挂到 ITextMeasurer，调用方可以先依赖抽象逐步迁移组件，而不是直接绑定某个静态工具函数
  • TerminalTextMeasurer 的 escape 识别覆盖 CSI、OSC、APC 和 DCS，切片与宽度计算共用同一次 token 化逻辑，比组件内手写字符串长度更稳定
  • 换行时 OSC 8 会保留原始 BEL 或 ST 终止符，避免 OAuth 等 BEL 终止超链接在续行中被改写成另一种终止形式
  • 新增检查项目只验证文本工具，不引入完整虚拟终端测试基础设施，避免提前扩大第 9 项范围

后续仍需补齐：

  • C# 当前使用 StringInfo.GetNextTextElementLength 和 emoji 区间启发式，不等价于 tmp/tui 的 Intl.Segmenter + RGI_Emoji 精确判断，未来可引入更完整的 Unicode/RGI 数据或专门测试集
  • Wrap 目前是 word wrap + 长词切分，还没有实现 tmp/tui 中完整的 punctuation/word segmenter 行为，CJK 断行、标点避头尾和复杂 Markdown token 换行仍需细化
  • SGR tracker 已覆盖常见样式、标准色、256 色和 RGB 色，但还没有处理所有终端私有样式参数和嵌套 hyperlink 的边界测试
  • 按列切片仍没有像 extractSegments 那样恢复切片前的活动样式，overlay 右侧继承样式丢失问题需要在后续文本 segment 模型中解决
  • 还缺正式测试框架和虚拟终端断言；当前 TinyTUI.TextChecks 是最小可执行检查，后续第 9 项应把这些用例迁移到统一测试项目

6. 组件基础设施

目标：补齐组件体系的横向能力，而不是继续只补单个组件的小功能

  • 给组件接口增加 Invalidate 语义，用于主题变化、缓存失效和强制重绘
  • 建立 Focusable 模型，由运行时统一设置焦点状态，组件只负责在渲染中输出 cursor marker
  • 支持硬件光标定位配置，兼容 IME 候选窗定位
  • 引入主题接口和默认主题，让组件样式可配置且跨组件一致
  • 增加通用组件：Spacer、TruncatedText、SettingsList、CancellableLoader
  • 组件渲染缓存统一由宽度、内容和主题状态驱动，避免每帧重复解析 Markdown 或重算复杂布局

参考：tmp/tui/src/components/*

本次推进：

  • 新增 IFocusableComponent，把焦点状态从组件内部自管改成由 TuiRuntime.SetFocus 统一写入
  • Input、SelectList、Editor 改为只在 Focused 为 true 时输出 CursorMarker，避免多个可输入组件同时影响硬件光标定位
  • TuiRuntime 在添加、移除、焦点切换、resize 和显式 Invalidate() 时递归清理组件缓存，为主题变化和复杂组件缓存失效提供框架入口
  • RenderPipelineOptions 新增 ShowHardwareCursor，renderer 始终能把硬件光标定位到 marker，是否显示光标由配置或 TINYTUI_HARDWARE_CURSOR 控制
  • 新增 ITuiTheme 和默认 TuiTheme，先提供 hint、dim、输入光标、设置项标签和值、选择 cursor 等跨组件样式入口
  • 新增通用组件 Spacer、TruncatedText、CancellableLoader，覆盖空行间隔、ANSI 感知单行截断和 Escape 取消加载流程
  • 新增 TinyTUI.ComponentChecks 最小检查项目，验证 focusable marker、通用组件渲染和 cancellable loader 取消行为

为什么先做：

  • tmp/tui/src/tui.ts 的 Focusable.focused 是组件基础设施的关键分界：运行时决定谁有焦点，组件只根据状态决定是否发出硬件光标 marker；先补这一层能减少后续 overlay、autocomplete、settings 子菜单抢焦点时的耦合
  • 主题和通用组件先提供薄接口和默认实现，不直接重写所有现有组件样式，避免一次提交同时改变大量视觉输出
  • Invalidate() 先接入 runtime 生命周期和 resize，不提前实现完整缓存系统，但给 Markdown、SettingsList、Autocomplete 这类后续复杂组件留下统一失效入口

当前更好的点：

  • C# 侧通过 IFocusableComponent 明确焦点状态契约，运行时切换焦点时会同时 invalidate 前后组件，后续带缓存组件不需要自己猜测焦点变化
  • 硬件光标显示配置放在渲染管线选项里，组件只负责 marker，避免组件直接依赖终端输出细节
  • CancellableLoader 暴露标准 CancellationToken，比只暴露回调更容易接入 C# async 工作流
  • TruncatedText 直接复用 ITextMeasurer，能继承第 5 项已经补过的 ANSI、OSC 和 grapheme 宽度处理

后续仍需补齐：

  • SettingsList 还没有移植，参考实现里的搜索、描述换行、值循环、submenu 委托和主题分区仍需单独推进
  • ITuiTheme 当前只是轻量样式接口，还没有 runtime 级主题持有、主题切换事件和组件缓存 theme version
  • Input 目前仍是尾部输入模型，还没有参考实现里的水平滚动、按 grapheme 移动、kill ring 和 undo；这些应在输入/编辑能力后续增量中处理
  • 组件缓存规范还只具备 invalidate 入口，没有统一的 width/content/theme cache key，也没有 Markdown AST 或复杂布局缓存基类
  • 焦点恢复策略仍比 tmp/tui/src/tui.ts 简化，overlay 被临时隐藏、非 overlay 组件短暂抢焦点和多层 submenu 的 blocked restore 还需要继续补强
  • 硬件光标定位已可配置显示隐藏，但还没有维护 renderer 级 hardwareCursorRow 相对移动模型，IME 在滚动和 resize 场景仍需要真实终端验证

7. 自动补全和命令交互基础

目标：把自动补全从 Editor 局部功能升级为可复用的交互能力

  • 定义 autocomplete provider 接口，支持同步和异步候选
  • 支持 slash command 候选、文件路径候选、特殊前缀候选
  • 使用 overlay 呈现补全列表，并复用 SelectList 的选择、过滤和滚动能力
  • 将补全确认、取消、预览、应用文本变更抽象成独立流程
  • 让 keybinding 系统负责 Tab、Enter、Escape 等动作触发，避免补全逻辑和具体按键强绑定

参考：tmp/tui/src/autocomplete.ts、tmp/tui/src/components/editor.ts

本次增量已完成：

  • 新增 TinyTUI.Autocomplete 模块，定义 IAutocompleteProvider、AutocompleteRequest、AutocompleteSuggestions、AutocompleteApplyContext 和 AutocompleteApplyResult，先把“查询候选”和“应用候选”从 Editor 中拆成可复用契约
  • 新增 AutocompleteProviderBase，提供默认的前缀替换实现，后续文件路径、变量、命令参数等 provider 可以只覆盖查询或特殊应用逻辑
  • 新增 SlashCommandAutocompleteProvider 和 SlashCommand，支持行首 / 命令名候选，确认后自动写回 /{command} 并把光标放到参数位置
  • Editor 增加 AutocompleteProvider、AutocompleteList、IsAutocompleteActive、StartAutocomplete、ConfirmAutocomplete、CancelAutocomplete 和 RenderAutocomplete，补全列表复用现有 SelectList 的选择、滚动和渲染能力
  • 新增 tui.autocomplete.trigger、tui.autocomplete.confirm、tui.autocomplete.cancel 默认动作，Tab 触发或确认补全，Enter 在补全激活时确认，Escape 取消补全
  • 扩展 TinyTUI.ComponentChecks 覆盖 slash command 候选渲染、方向键切换候选、Tab 确认应用和 Escape 取消

这样设计的原因：

  • provider 契约返回 items + prefix，与 tmp/tui/src/autocomplete.ts 的核心模型一致，Editor 不需要知道候选来自命令、路径还是特殊前缀
  • 应用候选独立成 ApplyCompletion，是为了保留 slash command 自动补空格、路径目录不补空格、引号去重等后续差异，不把这些规则硬塞进 Editor
  • Editor 内部持有 SelectList，先把补全选择和确认流程跑通，后续 overlay 只需要挂载 RenderAutocomplete 或直接挂载同一个列表组件
  • 补全确认通过现有 Edit 包装写回文本，所以撤销栈、redo 清理和 OnChanged 行为与普通编辑保持一致

怎么看懂当前代码：

  • 先看 Autocomplete/IAutocompleteProvider.cs，它定义自动补全框架的两个关键动作：查询候选和应用候选
  • 再看 Autocomplete/SlashCommandAutocompleteProvider.cs，它展示了一个最小 provider 如何根据当前行和光标返回候选，以及如何把候选写回文本
  • 最后看 Components/Editor/Editor.Autocomplete.cs，这里是 Editor 的补全状态机：启动查询、用 SelectList 展示候选、确认应用、取消清理
  • Components/Editor/Editor.cs 的 HandleInput 入口可以看到补全输入优先级：活动补全先消费导航和确认，普通 Tab 强制触发补全，普通文本输入后尝试自然补全

对比 tmp/tui 后续仍需补齐：

  • C# 侧 provider 契约已用 ValueTask 支持异步形态，但 Editor 当前 HandleInput 仍是同步接口，会阻塞等待 provider；后续需要 Runtime 级 invalidate 和取消令牌来实现真正非阻塞异步补全
  • 还没有移植文件路径 provider、@ 附件前缀、引号路径、~/ 展开、目录优先排序和 fd fuzzy 搜索
  • 还没有实现 slash command 参数补全，参考实现里的 getArgumentCompletions 需要在 C# 侧扩展到 SlashCommand
  • 还没有把补全列表通过 OverlayManager 自动挂到光标附近，目前只提供 RenderAutocomplete 和内部 SelectList 供后续 overlay 接线
  • 还没有做补全预览文本、候选变化 debounce、过期请求丢弃和 AbortController 等请求竞争处理
  • 当前默认前缀替换基类按字符串长度处理 prefix，后续支持宽字符或跨行补全时需要把 provider 光标协议统一成 Rune 列或专门的文本范围类型

8. 图像和特殊终端内容

目标：为 Kitty / iTerm2 图像和特殊终端序列预留完整框架入口

  • 检测终端图像能力，选择 Kitty graphics protocol、iTerm2 inline image 或文本 fallback
  • 解析图片尺寸并按终端 cell 尺寸计算显示区域
  • 渲染差分时追踪已显示的 Kitty image id，在内容变化或清屏时删除旧图像
  • 合成和截断逻辑识别 image line，避免把图像序列当普通文本切坏
  • 在终端 resize 或 cell size 变化后刷新图像布局

参考：tmp/tui/src/terminal-image.ts、tmp/tui/src/components/image.ts

本次推进：

  • 新增 TinyTUI.Terminal.Images 图像基础设施，提供终端能力检测、Kitty/iTerm2 协议选择、cell 像素尺寸、图片尺寸解析、终端 cell 尺寸换算、Kitty/iTerm2 编码和 fallback 所需的数据结构
  • 新增 Image 组件，支持 PNG/JPEG/GIF/WebP 尺寸解析结果或外部尺寸注入，终端支持图像时输出 Kitty/iTerm2 内联图像序列，不支持时输出带文件名、MIME 和尺寸的文本 fallback
  • RenderFrameBuilder 识别 Kitty 和 iTerm2 image line，遇到图像序列时跳过普通宽度测量和截断，避免把大段 base64 当作可见文本导致溢出或切坏协议序列
  • DifferentialRenderer 和 FullScreenRenderer 增加 Kitty image cleanup，清屏、reset 或变化行覆盖旧 Kitty 图像时写出删除序列，降低图像残影
  • 扩展 TinyTUI.ComponentChecks 覆盖 cell 尺寸换算、PNG 尺寸解析、Kitty Image 组件输出、fallback、image line 任意位置识别、长 iTerm2 image line 不触发宽度溢出和差分删除旧 Kitty image id

为什么先做：

  • tmp/tui/src/terminal-image.ts 的图像能力是渲染、组件和终端环境共同依赖的底座；先把 C# 侧服务抽出来，后续真实 cell size 查询、resize 后重新布局和更多组件都能复用同一个入口
  • 参考实现里 isImageLine 的回归说明很明确：图像序列可能出现在行中间，且终端不支持图像时仍需要识别，否则宽度校验会处理几百 KB base64 并崩溃；因此本次优先把 image line 保护接到渲染帧构建
  • Kitty 图像不会只靠清行自动消失，差分渲染覆盖旧内容时必须发删除序列；本次只做可见帧中的 id 追踪和变化行清理，避免一次性引入完整滚动区域和硬件光标模型重构

当前更好的点：

  • C# 侧 ITerminalImageService 是显式可替换服务，组件测试可以直接注入固定能力和 cell 尺寸，不需要改全局环境变量
  • Image 组件构造时直接接受 byte[] 并缓存 base64，尺寸解析和协议渲染分离，调用方可以用真实图片数据，也可以为测试或远端元数据直接注入尺寸
  • renderer 层的 image line 判断不依赖当前终端是否支持图像，能覆盖“fallback 终端仍收到工具输出图像 escape”的崩溃场景

后续仍需补齐：

  • 终端 cell size 目前仍是默认估计或外部手动设置，还没有像 tmp/tui/src/tui.ts 那样查询 CSI 16 t 并在响应后 invalidate 所有图片组件
  • 能力检测对 tmux hyperlink forwarding 仍保守禁用，没有调用 tmux client_termfeatures，也没有区分更多终端的图像代理能力
  • Kitty cleanup 目前只按可见行变化删除旧 id，没有实现参考实现中的 expandLastChangedForKittyImages、滚动区域跨行扩展和 previousKittyImageIds 全量精细同步
  • Image 组件还没有真实示例入口、动画/更新复用 id 的公开构造选项，也没有 iTerm2 name、inline、preserveAspectRatio 等完整参数
  • WebP/JPEG/GIF 尺寸解析已有基础路径，但还缺专门测试样本和异常格式覆盖；后续第 9 项测试基础设施应把这些协议和 renderer cleanup 用例迁移到正式测试项目
  • overlay 合成对 image line 仍只是依赖文本切片层不主动切 escape，后续需要在 overlay manager 中像参考实现一样遇到 image line 直接保留或跳过合成，避免浮层覆盖图片区域时产生未定义行为

9. 测试基础设施

目标：引入可以验证真实终端行为的测试层，而不是只靠 Example 手动看效果

  • 建立虚拟终端或 fake terminal output，捕获 ANSI 输出并模拟窗口尺寸
  • 覆盖输入缓冲、按键协议、keybinding、文本宽度、ANSI 换行和截断
  • 覆盖差分渲染、内容缩短清理、resize full redraw、viewport 覆盖和硬件光标定位
  • 覆盖 overlay 样式泄漏、短内容覆盖长内容、宽字符边界和多层焦点恢复
  • 覆盖 Markdown、SelectList、Editor、Autocomplete 等组件的框架行为
  • 示例仍用于人工验收，但不能替代回归测试

参考：tmp/tui/test/virtual-terminal.ts、tmp/tui/test/*.test.ts

本次推进：

  • 新增 test/TinyTUI.Tests 正式 xUnit 测试项目并加入 ttui.slnx，让后续回归可以通过 dotnet test ttui.slnx 统一执行，不再只依赖手写 console check
  • 新增 VirtualTerminalOutput 测试辅助，捕获渲染器写出的 ANSI 序列、记录每次 write、模拟终端窗口尺寸，并复用 ITerminalOutput 接口验证真实渲染输出路径
  • 新增 AnsiAssert，提供 ANSI 感知的可见文本比较，便于 overlay、renderer 和文本工具测试在保留 escape sequence 的同时断言最终可见内容
  • 迁移并规范化 TextChecks 的关键文本回归，覆盖 ANSI/tab/emoji 宽度、按列切片、ANSI 截断、省略符和 OSC 8 wrap
  • 新增输入基础测试，覆盖 StdinBuffer 分块 escape、批量 Kitty CSI-u 片段、bracketed paste、flush 未完成序列、DefaultInputParser 常见按键和 keybinding 冲突归一化
  • 新增 overlay 回归测试，覆盖短内容时 overlay 仍可见、短 overlay 覆盖长底层行时保留右侧内容、overlay 段 reset 隔离
  • 新增差分渲染测试，覆盖 bottom viewport、行尾 reset、只重绘变化行、resize/shrink full redraw、硬件光标 marker 定位和 Kitty image 删除顺序
  • 新增组件回归测试，覆盖 focusable 光标 marker、slash command autocomplete 确认/取消、Image 组件 Kitty/fallback 和 image line 任意位置识别

为什么先做：

  • tmp/tui/test/virtual-terminal.ts 的核心价值是让终端行为可自动断言；C# 侧当前没有 xterm.js 等完整终端模拟依赖，本次先用 ITerminalOutput 建立轻量 fake output，优先覆盖 renderer 实际写出的 ANSI 序列和尺寸变化
  • 前面 TODO 5/6/7/8 已经产生 TextChecks 和 ComponentChecks，继续追加 console check 会让失败定位和 CI 接入变差；正式测试项目能把这些回归按模块拆分，并为第 10 项 CI 打基础
  • 本次只固化已实现能力和已修过的关键回归，不把 Kitty 完整协议、真实终端屏幕缓冲或更多组件行为混进同一个 commit，降低测试基础设施增量的风险

当前更好的点：

  • C# 侧测试辅助直接实现 ITerminalOutput，不需要绕过 renderer 或 runtime 私有状态，能观察 ClearScreen、MoveCursorTo、HideCursor、Kitty cleanup 等真实输出
  • VirtualTerminalOutput 同时保留完整 buffer 和 write 片段，既能断言最终序列，也能检查删除图像必须早于新内容写入这类顺序问题
  • 正式测试项目已覆盖 text/input/overlay/rendering/components 五个基础面，后续新增回归时有明确目录，不需要继续把所有断言塞进单个 Program.cs

后续仍需补齐：

  • 还没有像 tmp/tui/test/virtual-terminal.ts 那样基于真实终端 emulator 解析 ANSI 后得到 viewport、scrollback、cell style 和 cursor position；当前只能断言写出的序列，不能验证终端最终屏幕状态
  • 现有 TextChecks 和 ComponentChecks 暂时保留，后续可以在所有断言迁移完成后删除或改成示例 smoke check，避免同一回归维护两套入口
  • DefaultInputParser 当前对 ESC[Z Shift+Tab 仍会原样透传，本次测试只覆盖当前支持的修饰 CSI；后续输入协议增量应补正式回归
  • StdinBuffer 还没有参考实现中的超时 flush、ESC+ESC+CSI 分裂、Kitty printable duplicate drop、鼠标协议和旧式 mouse sequence 测试
  • overlay 测试目前通过 OverlayManager.Compose 断言合成结果，还没有跑完整 Runtime + Renderer + virtual terminal 的端到端路径，多层 overlay 焦点恢复和 viewport 对齐仍需继续补
  • 渲染测试尚未覆盖 synchronized output、debug 日志、Termux resize 策略、硬件光标相对移动和完整 Kitty reserved row redraw 行为

10. 工程化和发布完整性

目标：让 TinyTUI 从本地骨架变成可维护、可发布、可集成的类库

  • 完善 README，覆盖快速开始、核心 API、组件接口、overlay、keybinding、文本工具和自定义组件约束
  • 补 XML documentation 和包元数据，为 NuGet 发布做准备
  • 增加 CI：restore、build、format、test、pack
  • 增加 benchmark 或压力示例，用于观察大文本、频繁刷新、overlay 合成和 Markdown 缓存性能
  • 拆分 Example 为多个真实场景：基础输入、overlay 菜单、聊天界面、Markdown 浏览、设置面板、图像 fallback
  • 明确公开 API 和内部实现边界，避免后续重构时破坏使用者代码

本次推进：

  • README 从空文件补成可执行入口文档，覆盖快速开始、最小 C# 示例、核心 API、内置组件、overlay、keybinding、文本工具、自动补全、图像 fallback、自定义组件约束、工程命令和调试日志
  • Directory.Build.props 增加统一工程属性：LangVersion=latest、nullable、implicit usings、确定性构建、CI build 标记和统一 build/artifacts 输出目录
  • TinyTUI.csproj 增加 NuGet 包元数据、tags、README 打包、XML documentation、symbol package 和包输出目录，为 dotnet pack 产出可发布包做准备
  • 新增 GitHub Actions CI，按 restore、Release build、format verify、test、pack 的顺序覆盖工程化闭环
  • 新增 docs/public-api.md，把应用侧稳定入口、推荐组合、组件约束和仍在演进的公开边界写清楚，避免后续重构误伤使用者依赖

为什么先做：

  • 对比 tmp/tui/README.md 和 package.json，参考实现已经能让使用者快速判断“怎么安装、怎么跑、有哪些 API、怎么测试和发布”；C# 侧 README 和包元数据为空或缺失，会阻塞集成和 NuGet 发布
  • 第 9 项已经有正式 xUnit 项目，先接 CI 和 pack 可以把测试基础设施转成持续验证能力，后续每个框架增量都有自动守门
  • 公开 API 边界先用文档声明，不急着重命名或收缩源码命名空间，避免在第 10 项里引入运行时行为变更

当前更好的点：

  • C# 侧把 XML documentation 和 artifacts 输出放在根级 Directory.Build.props，类库、测试和示例的构建产物路径一致，CI 和本地命令更容易对齐
  • NuGet README 直接复用仓库根 README，包页面和源码文档不会维护两套快速开始
  • CI 同时跑 dotnet format --verify-no-changes 和 dotnet pack，比只跑测试更早暴露工程文件、包元数据和格式问题

后续仍需补齐：

  • 当前还没有正式 LICENSE 文件，包使用 PackageLicenseExpression=MIT 只是发布元数据，后续应补仓库级 license 文本
  • PackageProjectUrl 和 RepositoryUrl 先使用占位仓库地址，真实发布前需要替换成实际远端
  • XML documentation 已启用，但大量 public API 还缺中文 summary，后续需要分模块补齐并决定是否把 CS1591 提升为 CI 约束
  • CI 已提供 dotnet format，但当前仓库还没有 .editorconfig，格式规则仍主要依赖 SDK 默认值，后续应补编码、缩进、nullable 和 analyzer 策略
  • benchmark 目录仍未建立，后续需要补大文本、频繁刷新、overlay 合成、Markdown 缓存和图像行保护的压力场景
  • Example 仍是单个综合示例，尚未像参考实现 test/chat-simple.ts 那样拆出聊天、设置、图像 fallback、Markdown 浏览等真实场景

建议执行顺序

  1. 先补终端会话能力、输入协议和 keybinding，因为它们会影响所有交互组件
  2. 再升级文本模型、渲染管线和 overlay 合成正确性，因为它们决定整体显示稳定性
  3. 然后补组件基础设施、自动补全和主题，让上层组件可以复用统一能力
  4. 接着引入虚拟终端测试和关键回归用例，把已修过的问题固化下来
  5. 最后处理图像、benchmark、README、CI、NuGet 等发布和扩展能力

暂缓

  • 不继续列举 Editor、SelectList、Markdown 的零散小功能
  • 不优先追求所有组件与 tmp/tui 逐项一致
  • 图像能力可以等终端、渲染、文本和测试基础稳定后再做
  • NuGet 发布可以等公开 API 基本稳定后再做
Reference in New Issue View Git Blame Copy Permalink