ttui/TODO.md

TODO

Success Criteria

最终成功应该具备这些能力：

• 能作为一个 C# TUI 类库被其他控制台程序引用。
• 能启动和停止终端运行时，并在退出时恢复终端状态。
• 能读取键盘输入，并把普通字符、方向键、组合键、回车、退格、Esc 等转换成统一事件。
• 能处理粘贴输入，避免大段粘贴被拆成混乱的按键事件。
• 能监听终端窗口尺寸变化，并触发重新布局和重新渲染。
• 能用组件树描述界面，而不是让组件直接写控制台。
• 能支持焦点管理，让当前焦点组件接收输入。
• 能渲染基础组件，包括文本、容器、单行输入框、多行编辑器、选择列表和加载状态。
• 能支持 overlay 弹层，用于菜单、弹窗、提示框和临时输入。
• 能正确显示中文、emoji、ANSI 样式文本，并避免宽度计算错位。
• 能进行全量渲染，保证最小版本可以稳定显示。
• 能进行差分渲染，只刷新变化的行，减少闪烁。
• 能提供一组示例程序，展示输入、编辑、列表选择、overlay 和动态刷新。
• 能提供测试覆盖核心模块，包括输入解析、宽度计算、渲染输出和组件行为。
• 能在 Windows Terminal / PowerShell 环境下稳定运行。

Architecture

整体分成几个大模块：

• STDIO 模块：负责读取键盘输入、监听窗口尺寸变化、管理 raw mode 和生命周期。
• STDOUT 模块：负责向终端输出文本和 ANSI 控制序列。
• Input 模块：负责把原始输入转换成统一的按键、粘贴、控制事件。
• Runtime 模块：负责管理组件树、焦点、事件分发和渲染调度。
• Renderer 模块：负责把组件输出同步到终端，先全量渲染，后续升级成差分渲染。
• Text Width 模块：负责计算终端显示宽度，处理 ANSI、中文、emoji、截断和换行。
• Component 模块：负责提供 Text、Input、Container、Box 等基础 UI 组件。
• Overlay 模块：负责弹层显示、遮盖合成、焦点切换和恢复。
• Example 模块：负责验证框架 API 和真实交互流程。
• Test 模块：负责覆盖输入解析、渲染输出、宽度计算和组件行为。

大致依赖方向：

Example
  -> Runtime
      -> Component
      -> Overlay
      -> Renderer
          -> STDOUT
          -> Text Width
      -> Input
          -> STDIO

Steps

1. 定义核心模块边界：STDIO/STDOUT、输入解析、运行时、渲染器、组件、示例。
2. 实现终端 IO 模块，统一封装控制台输入、输出、尺寸和生命周期。
3. 实现输入解析模块，把原始按键和控制序列转换成框架事件。
4. 实现组件运行时，管理组件树、焦点、事件分发和渲染请求。
5. 实现基础渲染器，先完成全量渲染和清屏重画。
6. 实现文本宽度模块，统一处理 ANSI、中文、emoji 和截断。
7. 实现差分渲染器，只更新变化的终端行。
8. 实现基础组件集，包括 Text、Input、Container 和 Box。
9. 实现 Overlay 模块，支持弹层显示、遮盖合成和焦点切换。
10. 实现高级组件集，包括 Editor、SelectList、Markdown 和 Loader。
11. 完善示例程序，用真实场景验证输入、渲染、焦点和 overlay。
12. 补齐测试和基准，覆盖输入解析、宽度计算、渲染输出和组件行为。