# 公开 API 和内部边界

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

## 应用侧稳定入口

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

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

## 推荐组合

真实终端应用建议使用：

```csharp
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 拆分

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