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 已有启动侧查询、响应解析和 fallback，但还需要结合真实 Kitty、WezTerm、iTerm2、Windows Terminal、tmux 和 SSH 延迟场景验证协商时序
- 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，实现虚拟终端回归测试前需要继续抽象可观测输出和模拟输入

本次 Kitty keyboard protocol 协商推进：

- `ConsoleTerminalSession.Start()` 现在会在 bracketed paste 和隐藏光标后写出 `ESC[>7u ESC[?u ESC[c`，优先请求 Kitty keyboard protocol 的 disambiguate、event type 和 alternate key flags
- 会话输入事件会在启动协商窗口内先拦截 `ESC[?Nu` Kitty flags 响应和 `ESC[?...c` DA 响应；非零 Kitty flags 会设置 `KittyProtocolActive`，DA 响应或 `ESC[?0u` 会 fallback 到 xterm `modifyOtherKeys`
- 未收到确认时会在短超时后写出 `ESC[>4;2m` 启用 `modifyOtherKeys`，并用内部 `ModifyOtherKeysActive` 状态避免重复启用
- `Stop()` 会先取消协商 timer 并按实际状态恢复 Kitty / modifyOtherKeys，再排空输入、关闭进度、关闭 bracketed paste、恢复 Windows VT input、标题和光标
- 新增 `ConsoleTerminalSessionTests`，用 fake input 和 fake output 覆盖启动写序列、Kitty flags 成功、DA fallback、超时 fallback、停止恢复和分片响应缓存

为什么这样做：

- 对齐 `tmp/tui/src/terminal.ts` 的渐进增强策略：先 push 所需 Kitty flags，再查询 flags，同时用 DA 和短 timeout 兜底不支持 Kitty 的终端
- 协商逻辑放在 `ConsoleTerminalSession` 而不是 input parser，是为了让协议响应不会被应用组件当作普通输入，同时保持 `DefaultInputParser` 只负责真实按键序列解析
- Stop 先恢复键盘协议再 drain，是为了减少 Kitty key release 事件在慢 SSH 或终端延迟下继续生成新协议序列并泄漏到父 shell 的风险

当前更好的点：

- C# 侧通过构造函数注入 fallback timeout，测试可以稳定覆盖超时路径，不需要真实等待默认 150ms
- `ModifyOtherKeysActive` 仅 internal 暴露给测试，公开 `ITerminalSession` API 没有因为实现状态膨胀而增加额外属性
- 分片 Kitty flags 响应会被短暂缓存，非协商输入会恢复成原始合并序列继续转发，降低协商窗口误吞输入的概率

本次后续仍需补齐：

- C# 侧还没有像参考实现那样对 late response buffer 单独设置 fragment flush timer；当前只在协商窗口内缓存完整前缀，真实终端若在 fallback 后慢速拆分 DA 响应仍需要继续验证
- `DrainInput` 仍基于 `Console.KeyAvailable`，没有暂时替换 input handler 统计 late data，因此对异步 `ConsoleTerminalInput` 缓冲里的 release 事件处理还不如参考实现精细
- 还没有把 Kitty protocol active 状态同步给 parser 或 key 模块的全局状态；当前 parser 已能解析协议序列，但没有会话级开关参与解析策略
- 测试目前断言写出的 ANSI 序列和状态，没有完整虚拟终端 emulator 断言父 shell 恢复后的最终屏幕和键盘模式

### 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 冲突检测仍主要针对用户覆盖集合，后续需要补作用域或上下文策略，避免全局配置复杂后误报或漏报

本次动态 Container 注入推进：

- `Container` 新增 `ChildAdded` 和 `ChildRemoved` 事件，让 Runtime 可以感知已挂载容器后续动态增删的子组件
- `TuiRuntime` 新增 Runtime 组件挂载上下文，组件进入根树或 overlay 时会递归挂载并注入共享 `KeybindingRegistry`
- 已挂载 `Container.Add(input)` 会立即为新输入组件注入 Runtime 级快捷键，并触发子组件失效和重渲染请求
- 已挂载 `Container.Add(new Box(input))` 会递归穿透内置 `Box.Child`，避免动态加入内置复合组件子树时漏掉输入组件
- 动态 `Remove` 和 `Clear` 会递归卸载子树并解除容器事件订阅，避免已移除容器继续响应 Runtime 注入
- overlay 中已经挂载的 `Container` 也复用同一套挂载上下文，动态加入子组件后可以使用 Runtime 共享快捷键
- 新增 xUnit 回归测试，覆盖动态根容器输入、动态 Box 子树和动态 overlay 容器子树的 keybinding 注入行为

为什么这样做：

- 对比 `tmp/tui/src/tui.ts`，参考实现的 `TUI` 自身继承 `Container`，动态添加后的渲染天然由根容器覆盖；C# 侧 Runtime 是组合式根树，因此需要显式挂载上下文把 Runtime 级能力传播到后续动态子树
- hook 放在 `Container` 层而不是每个输入组件层，是因为问题发生在复合组件子树边界；Runtime 只要监听容器增删，就能复用现有 `IKeybindingComponent` 注入契约
- 挂载计数用于处理同一组件子树同时出现在根树和 overlay 的情况，避免一次移除就提前解除仍然挂载路径上的动态监听

当前更好的点：

- C# 侧 Runtime keybinding 是实例级注入，多 Runtime 或测试场景可以各自持有独立 registry，不依赖参考实现那类模块级全局状态
- 动态子树注入同时支持根树和 overlay 栈，普通应用组件和浮层容器不需要走两套生命周期逻辑
- `ChildRemoved` 路径会解除订阅并失效子树，比只做 `ChildAdded` 注入更不容易在长生命周期应用里留下过期 Runtime 回调

本次后续仍需补齐：

- Runtime 递归仍只理解内置 `Container` 和 `Box`，第三方复合组件的内部子树还需要实现自己的 `IKeybindingComponent` 转发或后续新增通用子组件枚举接口
- `Box` 当前是固定单子组件结构，没有动态更换 `Child` 的 API；如果后续增加可变 Child，需要同样触发 Runtime 挂载上下文更新
- 动态加入新输入组件后 Runtime 不会自动切焦点，本次保持现有显式 `SetFocus` 语义，后续可以按组件声明或 overlay 策略决定是否自动聚焦
- 组件生命周期目前只覆盖 keybinding 注入和 invalidate，还没有像完整框架那样统一管理主题、终端能力、异步任务取消和组件 dispose

本次协议解析推进：

- 新增 `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，也没有处理退出时恢复协议状态

本次 release opt-in 推进：

- `DefaultInputParser` 不再在解析层丢弃 Kitty release 事件，`TuiInputEvent.EventType` 会保留 `Release` 让 Runtime 和全局 listener 有机会观察
- 新增 `IKeyReleaseComponent`，聚焦输入组件只有显式实现该接口时才接收 key release，普通 `IInputComponent` 默认继续过滤 release
- `TuiRuntime.Dispatch` 保持先派发全局 input listener，再判断是否进入焦点组件；因此 listener 可以记录或消费 release，组件侧不会默认触发 key-up 行为
- `KeybindingRegistry.Matches` 继续拒绝 `TuiKeyEventType.Release`，避免 release 触发快捷键动作
- 新增 xUnit 回归测试，覆盖 parser 保留 release、listener 可见 release、普通组件默认过滤、opt-in 组件接收和 keybinding 不匹配 release

为什么这样做：

- 对齐 `tmp/tui/src/tui.ts` 的边界：input listener 先看到输入，焦点组件派发前再按 `wantsKeyRelease` 决定是否过滤 release
- C# 侧用 marker interface 表达 opt-in，比参考实现的可选布尔属性更类型安全，组件是否接收 release 能从类型声明直接看出
- 过滤放在 Runtime 而不是 parser，可以让 debug listener、全局快捷层或测试基础设施看到完整协议事件，同时不改变普通组件的默认行为

当前 C# 版本更好的点：

- `TuiInputEvent.EventType` 是强类型字段，Runtime 不需要像 `tmp/tui/src/keys.ts` 一样重新解析原始字符串或依赖最近一次解析状态判断 release
- `IKeyReleaseComponent` 复用现有 `IInputComponent.HandleInput(TuiInputEvent)`，不需要引入新的回调形状，也不会影响已有组件构造和 keybinding 注入
- release 过滤和 keybinding 过滤是两层防线：组件默认不收到 release，手工构造的 release 事件也不会匹配动作

仍存在的问题和后续建议：

- `IKeyReleaseComponent` 目前是 marker interface，没有提供更细粒度的按键级 release opt-in；如果后续有拖拽、长按或组合键释放逻辑，可以扩展为属性或策略接口
- Runtime 仍是同步 listener 和同步组件派发，若 release 事件用于异步状态机，后续需要补异常隔离、取消令牌和 listener 作用域
- raw matching 仍未实现，`KeyId` 还不能直接匹配 Kitty 原始序列；本轮只保证 release 事件不被过早丢弃并按 opt-in 分发

### 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 宽度处理

本次 Runtime 级主题上下文推进：

- 新增 `IThemeComponent`，让组件可以显式接收 Runtime 级共享 `ITuiTheme`
- `TuiRuntime` 现在持有 `Theme`，构造函数支持传入初始主题，默认仍使用 `TuiTheme.Default`
- `ITuiRuntime` 增加 `ThemeChanged` 和 `SetTheme(ITuiTheme theme)`，主题切换时会更新已挂载根组件和 overlay 组件并请求重渲染
- `MountRuntimeComponentTree` 复用现有 Runtime 挂载上下文，在根组件、overlay、动态 `Container.Add` 和内置 `Box.Child` 路径同时注入共享主题和共享 keybinding
- `Input`、`SelectList`、`Image`、`CancellableLoader`、`Editor` 接入主题注入，其中 `Editor` 会把主题转发给内部 `AutocompleteList`
- 新增 xUnit 回归测试，覆盖根组件主题注入、overlay 主题注入、动态容器子组件主题注入、`SetTheme` 刷新已挂载组件且不破坏 keybinding 注入

本次为什么这样做：

- 对比 `tmp/tui/src/tui.ts`，参考实现的关键生命周期是 `TUI.invalidate()` 会递归根组件和 overlay；C# 侧已有 Runtime 挂载计数，因此把主题注入接到同一条生命周期能避免维护两套递归逻辑
- 主题切换只负责更新共享主题、触发组件失效和重渲染，不扩展控件样式细节，避免把本轮任务扩大成完整主题系统
- `IThemeComponent` 与 `IKeybindingComponent` 对称，第三方组件可以选择接入并自行向内部子组件转发，Runtime 不需要用反射猜测组件结构

本次当前更好的点：

- C# 侧主题是 Runtime 实例级状态，不是模块级全局对象，多 Runtime 和测试场景可以隔离不同主题
- 已挂载 overlay 和动态添加的容器子树会收到同一个主题对象，避免浮层和后续加入组件继续使用默认主题
- 主题切换路径不会重建 keybinding registry，测试覆盖了切换主题后共享快捷键仍然生效

本次通用复合组件子树枚举推进：

- 新增 `ICompositeComponent`，让复合组件可以通过 `GetChildren()` 暴露直接子组件，Runtime 不再需要硬编码认识每一种内置复合组件
- `Container` 和 `Box` 实现统一子组件枚举契约，保留现有 `Container.ChildAdded` / `ChildRemoved` 动态事件作为可变容器专属能力
- `TuiRuntime.MountRuntimeComponentTree` 和 `UnmountRuntimeComponentTree` 改为通过 `ICompositeComponent` 递归，keybinding、theme、invalidate 和动态挂载上下文共用同一条子树遍历路径
- 新增第三方复合组件回归测试，覆盖 Runtime 根组件添加、overlay 添加、已挂载 `Container` 动态添加后，内部 `Input` 和主题组件都能收到 Runtime 共享上下文

本次为什么这样做：

- 对比 `tmp/tui/src/tui.ts` 和 `tmp/tui/src/components/box.ts`，参考实现的 `Container` / `Box` 都以 `children` 作为复合组件结构来源；C# 侧无法依赖 TS 的公开字段约定，因此用显式接口把这个能力稳定成组件契约
- 动态增删事件仍只保留在 `Container`，是因为本轮目标是统一“如何枚举子树”，不是扩展所有复合组件的可变生命周期协议，避免把 `Box` 或第三方组件强行要求成可变容器
- Runtime 挂载上下文本来已经负责 keybinding 和 theme 注入，本轮只替换递归来源，保持现有根树、overlay 和动态容器行为不退化

本次当前更好的点：

- 第三方复合组件只要实现 `ICompositeComponent`，内部子树就能自动拿到 Runtime 级 keybinding 和 theme，不再需要自己实现 `IKeybindingComponent` 或 `IThemeComponent` 转发
- Runtime 的子树遍历入口收敛为一个 helper，后续 invalidate、生命周期、dispose 或更多上下文注入可以复用同一个契约，减少继续追加 `Container` / `Box` 分支的风险
- C# 侧把“可枚举子树”和“动态子组件事件”拆开，静态复合组件可以轻量接入，动态容器仍能保留已有挂载计数和事件订阅语义

本次 Runtime 组件生命周期上下文推进：

- 新增 `TuiRuntimeContext`，把 Runtime、共享 `KeybindingRegistry`、共享 `ITuiTheme`、当前 `ITerminalSession`、`TerminalSize`、Kitty 协议状态和 Runtime 退出 `CancellationToken` 收敛成组件可接收的上下文快照
- 新增 `IRuntimeContextComponent`，组件可以通过 `OnMounted`、`OnUnmounted` 和 `OnRuntimeContextChanged` 感知首次挂载、最后卸载和 Runtime 上下文变化
- `TuiRuntime.MountRuntimeComponentTree` 和 `UnmountRuntimeComponentTree` 继续沿用挂载计数，同一组件经根树和 overlay 多路径挂载时只在首次挂载触发 `OnMounted`，最后一次卸载触发 `OnUnmounted`
- keybinding 和 theme 的旧接口注入改为由统一 Runtime 上下文路径驱动，`IKeybindingComponent` 和 `IThemeComponent` 仍保持兼容，不要求现有组件立即迁移到新生命周期接口
- `SetTheme`、终端 resize、`Stop` 和 `Dispose` 会通知仍挂载组件 Runtime 上下文变化，Runtime 停止时取消上下文令牌但不自动卸载组件
- `CancellableLoader` 接入 Runtime 上下文取消令牌，Runtime 停止时会复用现有 `Cancel()` 路径让等待中的异步工作退出，组件卸载时解除令牌注册
- 新增 xUnit 回归测试，覆盖根组件添加移除、overlay show/remove、动态 `Container` 子组件、同一组件多路径挂载计数、`SetTheme` 上下文变化、Runtime `Stop` / `Dispose` 不重复卸载仍挂载组件

本次为什么这样做：

- 对比 `tmp/tui/src/tui.ts`，参考实现没有显式 mount/unmount 接口，主要依赖 `TUI extends Container`、递归 `invalidate()` 和组件构造注入 theme；C# 侧 Runtime 是组合式根树并已有多 Runtime 实例状态，因此用显式上下文契约更适合 keybinding、theme、终端能力和取消信号统一传播
- 生命周期通知放在 Runtime 的组件树挂载边界，而不是单个控件内部，是为了覆盖根树、overlay 和动态容器三条路径，避免各组件自行猜测是否已经进入运行时
- Stop/Dispose 只取消 Runtime 上下文，不自动 `Dispose` 用户组件，是为了避免 Runtime 移除 overlay 或根组件时释放调用方仍持有、可能复用的组件对象

本次当前更好的点：

- C# 侧把终端会话和能力状态放进上下文，组件不需要通过全局变量读取当前终端尺寸或 Kitty 协议状态
- 上下文是 Runtime 实例级快照，多 Runtime 测试和多终端实例可以各自隔离 keybinding、theme、终端会话和取消令牌
- 重复挂载计数让同一组件可以同时出现在根树和 overlay，避免一次隐藏 overlay 就提前触发卸载或取消仍在根树中的组件

本次可变复合组件动态契约推进：

- 新增 `IMutableCompositeComponent` 和 `CompositeComponentChildChangedEventArgs`，把动态子组件 `ChildAdded` / `ChildRemoved` 从 `Container` 专属能力抽成通用复合组件契约
- `Container` 实现通用可变复合组件契约，同时保留原有 `ContainerChildChangedEventArgs` 和公开事件类型，避免旧调用方因为事件参数类型变化断裂
- `TuiRuntime` 的挂载上下文不再特判 `Container`，改为订阅所有 `IMutableCompositeComponent`，动态添加的第三方子树会自动获得 keybinding、theme 和 runtime context 注入
- 动态移除第三方可变复合组件子树时会复用同一条 `UnmountRuntimeComponentTree` 路径，触发 `IRuntimeContextComponent.OnUnmounted` 并解除子树内动态事件订阅
- 新增 xUnit 回归测试，用自定义第三方可变复合组件覆盖动态添加后快捷键提交、主题注入、Runtime 上下文挂载，以及动态移除后的 unmount 通知

本次为什么这样做：

- 对比 `tmp/tui/src/tui.ts`，参考实现的 `TUI extends Container` 让根容器动态增删天然影响渲染，但它没有给第三方可变复合组件提供独立生命周期事件；C# 侧 Runtime 是组合式根树，需要显式事件契约才能把 Runtime 级上下文传播到任意动态子树
- `ICompositeComponent` 继续只负责静态子树枚举，`IMutableCompositeComponent` 只给会动态增删子组件的类型实现，避免让固定结构组件如 `Box` 承担不需要的事件协议
- `Container` 使用显式接口事件接入通用契约，是为了让 Runtime 看到统一事件类型，同时保留原公开 API 的兼容性

本次当前更好的点：

- 第三方可变复合组件只要实现 `IMutableCompositeComponent`，无需继承 `Container` 或让 Runtime 认识具体类型，也能获得完整挂载上下文
- 动态添加和动态移除都走同一套 Runtime 挂载计数，根树和 overlay 多路径挂载时仍能避免重复 mount 或提前 unmount
- C# 侧把“可枚举子树”和“可变子树事件”拆成两个接口，比参考实现依赖 `instanceof Container` 的递归判断更适合第三方组件扩展

本次焦点生命周期修复推进：

- `TuiRuntime.Remove` 和动态 `IMutableCompositeComponent.ChildRemoved` 路径会在卸载子树前递归检查当前焦点是否位于被移除子树内
- 如果焦点命中被移除子树，Runtime 会优先切到当前最上层可聚焦 overlay；普通根树或动态容器移除则保守清空焦点
- 子树检测复用 `ICompositeComponent.GetChildren()`，因此 `Container`、`Box` 和第三方复合组件都走同一套焦点清理逻辑
- 新增 xUnit 回归测试，覆盖动态 `Container.Remove(focusedInput)`、`Container.Remove(boxContainingFocusedInput)` 和第三方 `IMutableCompositeComponent.Remove(subtree)` 后旧输入组件不再收到后续输入

本次为什么这样做：

- 对比 `tmp/tui/src/tui.ts`，参考实现通过 `containsComponent` / `isComponentMounted` 辅助判断焦点目标是否仍处于组件树内；C# 侧已有通用复合组件枚举契约，因此把判断落在 Runtime 子树移除边界即可避免 stale focus
- 清理发生在 `UnmountRuntimeComponentTree` 前，是因为此时被移除子树仍可通过 `GetChildren()` 完整遍历，能可靠判断深层已聚焦子组件
- 本轮不扩展完整 overlay blocked restore 机制，只在 overlay 场景使用现有 `_overlayManager.TopFocusableComponent` 作为安全 fallback，避免把焦点生命周期修复扩大成多层 overlay 重构

本次当前更好的点：

- C# 侧焦点清理支持第三方 `ICompositeComponent` / `IMutableCompositeComponent`，不依赖参考实现中的 `instanceof Container`
- Runtime 统一在根移除和动态复合移除两条路径处理焦点，后续输入派发入口不需要每次再判断焦点组件是否仍挂载
- 保守清空焦点能确保已卸载组件不会再接收输入，比继续保留显式 `SetFocus` 语义更安全

本次 owned 组件释放生命周期推进：

- `ITuiRuntime` 新增 `AddOwned(IComponent component)` 和 `ShowOwnedOverlay(IComponent component, OverlayOptions? options = null)`，显式表达 Runtime 接管组件释放责任
- `Add` 和 `ShowOverlay` 保持不释放用户组件的默认语义，避免调用方仍持有或准备复用的组件在移除后被 Runtime 意外释放
- `TuiRuntime` 新增 owned 组件集合和已释放集合，owned 子树通过 `ICompositeComponent.GetChildren()` 递归标记，动态 `IMutableCompositeComponent.ChildAdded` 会继承父组件所有权
- root `Remove`、overlay handle `Hide`、动态子组件移除和 Runtime `Dispose` 都会尝试释放 owned disposable，但只有在组件挂载计数归零或 Runtime 自身释放时才真正释放
- 同一 owned 组件通过根树和 overlay 多路径挂载时，关闭 overlay 不会提前释放，最后一个挂载路径移除后才释放一次
- 新增 xUnit 回归测试，覆盖 owned root、owned overlay、owned composite children、owned dynamic children、多路径挂载、非 owned 不释放、重复 remove/hide/dispose 不二次释放

本次为什么这样做：

- 对比 `tmp/tui/src/tui.ts`，参考实现的 remove/hide 只管理组件树和焦点恢复，并没有自动 dispose 用户组件；C# 侧补 owned API 而不是改变默认 `Add` / `ShowOverlay`，可以保留同样保守的用户组件语义
- owned 状态接到 Runtime 现有挂载计数，是为了和 `OnMounted` / `OnUnmounted` 的最后卸载语义一致，避免多路径挂载时某一路移除导致资源提前释放
- 释放递归复用 `ICompositeComponent` 和 `IMutableCompositeComponent`，让第三方复合组件只要实现现有契约就能被 owned 生命周期覆盖，不需要 Runtime 继续硬编码具体组件类型

本次当前更好的点：

- C# 侧显式区分“进入 Runtime 生命周期”和“Runtime 拥有释放责任”，比隐式 dispose 所有 `IDisposable` 用户组件更安全
- owned 释放覆盖动态子组件和第三方复合组件子树，能力范围比参考实现只递归 `Container` 的 `containsComponent` 判断更通用
- Runtime Dispose 会释放仍挂载的 owned 组件，同时用已释放集合保证 root remove、overlay hide 和 Runtime dispose 任意顺序下同一实例只释放一次

后续仍需补齐：

- owned 释放目前只覆盖同步 `IDisposable`，如果后续组件持有异步资源，需要评估是否引入 `IAsyncDisposable` 和异步 Runtime dispose 流程
- `IMutableCompositeComponent` 目前只表达直接子组件增删，没有批量变更、移动、替换或变更事务；如果后续出现高频动态列表，需要补批量事件或挂载 diff 策略减少重复注入
- owned 动态子组件继承父组件所有权，但还没有单独的“释放子树但保留父组件”策略；如果后续需要组件池或临时 detach/reuse，需要增加更细粒度的所有权转移 API
- `SettingsList` 已完成基础移植，覆盖标签和值渲染、搜索 fuzzy 过滤、上下移动、Enter/Space 值循环、Escape 取消、选中项描述换行和 submenu 输入委托
- `ITuiTheme` 当前仍是轻量样式接口，还没有 theme version、分区主题、Markdown 完整主题或控件级样式覆盖策略
- `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 场景仍需要真实终端验证

本次 SettingsList 移植总结：

- 新增 `SettingItem` 和 `SettingsList`，设置项保留 `Id`、`Label`、`Description`、`CurrentValue`、可循环 `Values` 和同步 submenu 工厂
- `SettingsList` 接入 `IInputComponent`、`IFocusableComponent`、`IKeybindingComponent`、`IThemeComponent` 和 `IMutableCompositeComponent`，主列表处理标准化输入，激活 submenu 后把输入完全委托给子组件
- 新增 `FuzzyMatcher` / `FuzzyMatch`，按 `tmp/tui/src/fuzzy.ts` 的顺序匹配、连续奖励、边界奖励、间隔惩罚和字母数字换序兼容实现搜索过滤
- `ITuiTheme` 补充 `SettingDescription`，描述行使用现有 ANSI 感知 `TerminalTextMeasurer.Wrap` 换行，不额外引入完整主题分区系统
- 新增 `SettingsListTests` 覆盖渲染与描述、搜索过滤、值循环、取消、submenu 输入转发和 done 后恢复选择

本次为什么这样做：

- 对比 `tmp/tui/src/components/settings-list.ts`，C# 侧没有把搜索实现为嵌套 `Input`，而是直接消费 `TuiInputEvent` 并维护 `SearchQuery`，这样可以避免为单行过滤框额外引入焦点切换和光标模型
- submenu 使用 `IMutableCompositeComponent.ChildAdded` / `ChildRemoved` 事件暴露动态子组件，让已挂载 Runtime 复用现有主题、快捷键和生命周期注入路径，不需要扩展 overlay 或焦点策略
- `SettingItem.CurrentValue` 设计为可变属性，是为了和参考实现一致，让组件内部值循环、外部 `UpdateValue` 和 submenu done 回调都能更新同一设置项模型

本次当前更好的点：

- C# 版本复用标准化输入事件和 `KeybindingRegistry`，不会像参考实现一样依赖原始字符串按键分支
- 描述换行复用 ANSI 感知测量器，后续如果描述文本带样式或超链接，换行边界比参考实现里的普通工具函数更贴合现有渲染管线
- 动态 submenu 通过通用可变复合组件契约进入 Runtime，上下文注入能力覆盖第三方子菜单组件，不需要 Runtime 识别 `SettingsList` 具体类型
- `FuzzyMatcher` 做成通用文本工具，后续 Autocomplete、文件搜索或命令面板可以复用同一套排序规则

SettingsList 后续仍需补齐：

- submenu 仍是同步工厂和 done 回调，未实现异步加载、取消中的状态恢复或 overlay 自动挂载
- 搜索框目前是轻量尾部输入，只支持追加和 Backspace，不支持光标移动、水平滚动、组合文本编辑或输入法边界验证
- 主题只补了 settings 描述样式，还没有控件级主题对象、主题版本或完整 settings 分区
- fuzzy 搜索当前只按 `Label` 过滤，后续如果要匹配 `Id`、`CurrentValue` 或 `Description`，需要明确排序权重
- `SettingsList` 自身没有引入布局缓存，复杂列表大量刷新时仍依赖后续统一 cache key 设计

### 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} ` 并把光标放到参数位置
- 新增 `FilePathAutocompleteProvider`，支持普通路径和 `@` 附件路径补全，覆盖 `./`、`../`、`/`、`~/`、含路径分隔符的 token、quoted path 和路径含空格自动加引号
- 新增 `CompositeAutocompleteProvider`，按顺序组合 slash command、文件路径或后续自定义 provider，让 Editor 仍只依赖一个 `IAutocompleteProvider`
- `SlashCommand` 新增参数补全入口，支持 `/command argPrefix` 场景调用命令自己的补全回调，返回候选时只把 `argPrefix` 作为待替换前缀
- `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 取消
- 新增 `TinyTUI.Tests.Autocomplete` 回归测试，覆盖路径前缀提取、目录优先排序、嵌套路径、`@` 附件前缀、quoted path、路径含空格加引号、确认应用和组合 provider 分派

这样设计的原因：

- provider 契约返回 `items + prefix`，与 `tmp/tui/src/autocomplete.ts` 的核心模型一致，Editor 不需要知道候选来自命令、路径还是特殊前缀
- 应用候选独立成 `ApplyCompletion`，是为了保留 slash command 自动补空格、路径目录不补空格、引号去重等后续差异，不把这些规则硬塞进 Editor
- slash command 参数补全复用默认 prefix 替换，而命令名补全仍由专门分支自动补 `/{command} `，这样参数候选确认时不会重写命令名，也不会把参数误当成新的 slash command
- 路径 provider 只做当前目录同步枚举和稳定排序，不引入 fd/fuzzy 搜索，是为了先把可预测的补全协议、引用规则和确认行为稳定下来，避免把异步搜索和请求取消提前塞进 Editor
- 组合 provider 记录最近一次返回候选的 provider，确认时把 `ApplyCompletion` 分派回原 provider，这样 slash command 和路径补全可以共用一个 Editor 入口
- Editor 内部持有 `SelectList`，先把补全选择和确认流程跑通，后续 overlay 只需要挂载 `RenderAutocomplete` 或直接挂载同一个列表组件
- 补全确认通过现有 `Edit` 包装写回文本，所以撤销栈、redo 清理和 `OnChanged` 行为与普通编辑保持一致

怎么看懂当前代码：

- 先看 `Autocomplete/IAutocompleteProvider.cs`，它定义自动补全框架的两个关键动作：查询候选和应用候选
- 再看 `Autocomplete/SlashCommandAutocompleteProvider.cs`，它展示了一个最小 provider 如何根据当前行和光标返回命令名或参数候选，以及如何把候选写回文本
- 然后看 `Autocomplete/FilePathAutocompleteProvider.cs`，重点是 `ExtractAtPrefix` / `ExtractPathPrefix` 负责判断当前 token，`ResolveSearchScope` 负责把显示路径映射到真实目录，`ApplyCompletion` 负责目录不补空格、文件补空格和 closing quote 去重
- 如果要同时启用命令和路径补全，看 `Autocomplete/CompositeAutocompleteProvider.cs`，provider 顺序就是优先级，先返回候选的 provider 会负责后续确认应用
- 最后看 `Components/Editor/Editor.Autocomplete.cs`，这里是 Editor 的补全状态机：启动查询、用 `SelectList` 展示候选、确认应用、取消清理
- `Components/Editor/Editor.cs` 的 `HandleInput` 入口可以看到补全输入优先级：活动补全先消费导航和确认，普通 Tab 强制触发补全，普通文本输入后尝试自然补全

对比 `tmp/tui/src/autocomplete.ts` 和 `tmp/tui/test/autocomplete.test.ts` 的结论：

- 已对齐的核心行为：prefix 提取仍以“光标前 token”为边界，支持 `@`、`@"..."`、普通 `"..."`、路径分隔符和强制 Tab 补全；候选值保留用户输入的显示前缀，目录追加 `/`，文件确认后追加空格
- 已对齐的 slash command 参数行为：`/command argPrefix` 会先定位命令名，再调用该命令的参数补全回调；回调无结果或不存在时返回 null；确认参数候选时只替换 `argPrefix`，不会重写 `/command `
- 已对齐的引用行为：路径含空格或原输入已经处于 quoted path 时自动生成 quoted value；确认 quoted completion 时如果光标后已有 closing quote，会移除旧 quote，避免出现重复 closing quote
- 已对齐的排序行为：目录优先，再按名称进行大小写不敏感排序，并增加原始名称排序作为稳定兜底
- 当前 C# 版本更好的点：路径 provider 被拆成独立类型，不和 slash command 逻辑混在一个 `CombinedAutocompleteProvider` 里；组合能力由 `CompositeAutocompleteProvider` 提供，后续变量、命令参数或远程资源补全可以按优先级插入
- 当前 C# 版本更好的点：测试不依赖外部 `fd` 是否安装，普通路径和 `@` 附件路径都用临时目录同步验证，结果更稳定
- 当前 C# 版本更好的点：`AutocompleteRequest` 使用 `CancellationToken` 和 `ValueTask` 预留异步 provider 形态，后续迁移 fd/fuzzy 时不需要改 provider 主接口
- 当前 C# 版本更好的点：命令名应用和参数应用分成两个清晰路径，参数补全直接复用 `AutocompleteProviderBase` 的前缀替换逻辑，比参考实现里在一个 `applyCompletion` 中靠字符串上下文猜测更容易测试和维护

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

- C# 侧 provider 契约已用 `ValueTask` 支持异步形态，但 Editor 当前 `HandleInput` 仍是同步接口，会阻塞等待 provider；后续需要 Runtime 级 invalidate 和取消令牌来实现真正非阻塞异步补全
- 文件路径 provider 已支持本地同步目录枚举、`@` 附件前缀、引号路径、`~/` 展开和目录优先排序，但还没有移植 fd fuzzy 搜索、递归匹配、`.git` 排除、隐藏文件策略配置或 symlink 递归跟随
- slash command 参数补全当前只把第一个空格后的完整文本作为 `argumentPrefix` 传给命令回调，与参考实现一致；后续如果要支持多参数、引号内参数或 option/value 级别补全，需要为参数范围引入更明确的解析协议
- 还没有把补全列表通过 `OverlayManager` 自动挂到光标附近，目前只提供 `RenderAutocomplete` 和内部 `SelectList` 供后续 overlay 接线
- 还没有做补全预览文本、候选变化 debounce、过期请求丢弃和 AbortController 等请求竞争处理
- `CompositeAutocompleteProvider` 当前用最近一次查询记录确认 provider，适合现有同步 Editor 流程；如果后续多个 Editor 共享同一个组合 provider 或实现并发异步查询，应把 provider 归属放进 suggestions 上下文或引入补全 session
- 当前默认前缀替换基类按字符串长度处理 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 任意位置识别
- 将 `TextChecks` 残余断言完全迁移到 `TerminalTextMeasurerTests`，补齐 plain wrap、underline URL wrap、ANSI continuation 和 OSC 8 BEL hyperlink wrap 覆盖
- 将 `ComponentChecks` 残余断言完全迁移到 `ComponentRegressionTests` 和 `DifferentialRendererTests`，补齐 SelectList focused marker、Spacer 负数 clamp、TruncatedText padding/首行截断、CancellableLoader 取消、PNG dimensions、长 iTerm2 image line overflow bypass
- 从 `ttui.slnx` 移除 `test/TinyTUI.TextChecks` 和 `test/TinyTUI.ComponentChecks`，删除两个早期 console smoke check 项目，README 测试说明改为统一 xUnit 入口

为什么先做：

- `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，降低测试基础设施增量的风险
- 旧 smoke check 已经和 xUnit 用例重叠，继续保留会导致同一行为维护两套入口；本次先按旧 `Program.cs` 的有效断言逐项对齐，再删除旧项目，保证边界清晰

当前更好的点：

- C# 侧测试辅助直接实现 `ITerminalOutput`，不需要绕过 renderer 或 runtime 私有状态，能观察 `ClearScreen`、`MoveCursorTo`、`HideCursor`、Kitty cleanup 等真实输出
- `VirtualTerminalOutput` 同时保留完整 buffer 和 write 片段，既能断言最终序列，也能检查删除图像必须早于新内容写入这类顺序问题
- 正式测试项目已覆盖 text/input/overlay/rendering/components 五个基础面，后续新增回归时有明确目录，不需要继续把所有断言塞进单个 `Program.cs`
- 相比 console check 手写 `AssertTrue`，xUnit 测试按模块命名，失败时能直接定位到文本、组件或 renderer 的具体行为
- 现有 C# 写法用 collection expression、target-typed `new` 和 `using var` 保持测试输入短小，断言结构更接近被测行为本身

后续仍需补齐：

- 还没有像 `tmp/tui/test/virtual-terminal.ts` 那样基于真实终端 emulator 解析 ANSI 后得到 viewport、scrollback、cell style 和 cursor position；当前只能断言写出的序列，不能验证终端最终屏幕状态
- `TextChecks` 和 `ComponentChecks` 已删除，后续新增回归应直接进入 `test/TinyTUI.Tests`，不要再恢复独立 console 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 行为
- 图像尺寸目前只把旧 smoke check 的 PNG 样本迁入正式测试；参考 `tmp/tui/test/terminal-image.test.ts` 的大量协议负例、环境能力检测和 WebP/JPEG/GIF 样本仍建议后续拆成专门测试类

### 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`，把应用侧稳定入口、推荐组合、组件约束和仍在演进的公开边界写清楚，避免后续重构误伤使用者依赖
- 新增 `benchmark/TinyTUI.Benchmarks` console 压力示例项目，并加入 `ttui.slnx`，覆盖大文本测量/截断、Markdown render、overlay compose、差分渲染频繁刷新和图像行检测保护
- README 增加压力示例运行命令和场景说明，明确它是本地观察入口，不替代 xUnit，也不作为默认 CI test gate

为什么先做：

- 对比 `tmp/tui/README.md` 和 `package.json`，参考实现已经能让使用者快速判断“怎么安装、怎么跑、有哪些 API、怎么测试和发布”；C# 侧 README 和包元数据为空或缺失，会阻塞集成和 NuGet 发布
- 第 9 项已经有正式 xUnit 项目，先接 CI 和 pack 可以把测试基础设施转成持续验证能力，后续每个框架增量都有自动守门
- 公开 API 边界先用文档声明，不急着重命名或收缩源码命名空间，避免在第 10 项里引入运行时行为变更
- benchmark 先选择无真实终端交互的内存输出，可以稳定覆盖参考实现 changelog 和源码里反复出现的性能风险：宽度测量缓存、Markdown 渲染缓存、overlay 按列合成、频繁 diff patch、image line 不进入普通文本测宽

当前更好的点：

- C# 侧把 XML documentation 和 artifacts 输出放在根级 `Directory.Build.props`，类库、测试和示例的构建产物路径一致，CI 和本地命令更容易对齐
- NuGet README 直接复用仓库根 README，包页面和源码文档不会维护两套快速开始
- CI 同时跑 `dotnet format --verify-no-changes` 和 `dotnet pack`，比只跑测试更早暴露工程文件、包元数据和格式问题
- 压力示例直接复用 `ITerminalOutput` 抽象和 `DifferentialRenderer`，不会为了 benchmark 绕过真实渲染路径；C# 的接口边界让同一份场景能在本地稳定统计写入次数、输出字节和 redraw 计数
- 图像行保护场景启用 `ThrowOnWidthOverflow`，能观察大段 Kitty payload 是否被 `RenderFrameBuilder` 按 image line 跳过普通测宽和截断，比只调用 `IsImageLine` 更贴近真实渲染风险
- benchmark 项目加入 solution 参与 restore/build，但 README 明确不作为默认 CI test gate，避免机器性能波动影响回归测试稳定性

后续仍需补齐：

- 当前还没有正式 `LICENSE` 文件，包使用 `PackageLicenseExpression=MIT` 只是发布元数据，后续应补仓库级 license 文本
- `PackageProjectUrl` 和 `RepositoryUrl` 先使用占位仓库地址，真实发布前需要替换成实际远端
- XML documentation 已启用，但大量 public API 还缺中文 summary，后续需要分模块补齐并决定是否把 CS1591 提升为 CI 约束
- CI 已提供 `dotnet format`，但当前仓库还没有 `.editorconfig`，格式规则仍主要依赖 SDK 默认值，后续应补编码、缩进、nullable 和 analyzer 策略
- benchmark 当前是可读压力示例，不是统计严格的微基准；后续如果要比较版本间性能，需要固定 warmup、迭代次数、结果导出格式和基线阈值，或再引入 BenchmarkDotNet
- Markdown 压力场景当前只能观察 C# 轻量逐行 render 成本，尚未具备参考实现 `Markdown` 的 AST 解析和缓存命中对照；后续补 Markdown 缓存时应把命中/失效计数加入输出
- overlay 压力场景覆盖普通文本和 ANSI reset 隔离，但 overlay 遇到 image line 的行为仍是已知后续项，暂不在本轮 benchmark 中模拟真实图片区域覆盖
- 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 基本稳定后再做