ttui/docs/public-api.md

公开 API 和内部边界

本文档用于说明 TinyTUI 当前可被应用代码依赖的公开边界，以及后续重构时应尽量保持稳定的区域。

应用侧稳定入口

应用代码优先依赖以下命名空间：

• TinyTUI.Components：组件接口和内置组件
• TinyTUI.Runtime：运行时入口和 overlay 操作
• TinyTUI.Terminal：真实终端会话
• TinyTUI.Rendering：渲染器和渲染选项
• TinyTUI.Text：ANSI 感知宽度、截断、切片和换行
• TinyTUI.Input：输入事件、按键名称和 keybinding
• TinyTUI.Autocomplete：自动补全 provider 契约
• TinyTUI.Terminal.Images：终端图像服务和能力检测

推荐组合

真实终端应用建议使用：

using var terminal = new ConsoleTerminalSession();
var parser = new DefaultInputParser();
var textMeasurer = new TerminalTextMeasurer();
var renderer = new DifferentialRenderer(terminal, textMeasurer);
using var runtime = new TuiRuntime(terminal, parser, renderer);

测试或嵌入场景可以替换 ITerminalSession、ITerminalOutput、IInputParser、IRenderer 或 ITextMeasurer，但仍保持 runtime 和组件不直接写终端。

组件约束

组件只负责 Render(int width) 返回行数组，输入组件通过 HandleInput(TuiInputEvent input) 接收规范化输入事件。

组件不应该直接调用 Console.Write 或依赖真实终端尺寸。需要终端宽度时使用 render 传入的 width，需要截断或换行时使用 ITextMeasurer。

可缓存组件应该在 Invalidate() 中清理缓存。runtime 会在焦点切换、resize 和显式失效时调用该入口。

仍在演进的区域

以下能力已具备基础形态，但公开契约后续仍可能细化：

• Kitty keyboard protocol 的完整协商和 release 事件
• Runtime 级全局 input listener 和 keybinding 配置
• Overlay 多层焦点恢复和复杂样式 segment 保持
• Unicode RGI emoji 精确宽度和 CJK 标点断行
• 终端图像 cell size 查询、resize 重新布局和 Kitty image 生命周期同步
• 正式 benchmark 和多场景 Example 拆分

如果应用需要提前依赖这些能力，建议通过接口注入或封装适配层隔离变更。