ttui/TODO.md

# 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 基本稳定后再做