学习 ratatui-kit

Ratatui Kit 的文档按渐进式学习组织：先写出一个能运行的终端界面，再把交互、状态、路由和组件组合逐层接上，最后进入完整 API、内置组件和高级逃生口。

这个节奏参考 React 的 Learn / Reference，也参考 Vue 的 Guide / API：教程只讲当下需要的 80% 日常概念；参考手册完整展开边界、参数和内部机制。文档里的教程都对应仓库中的真实 example；需要展示运行效果时，只使用 VHS 录制出来的终端素材。

跟着教程

从安装依赖、hello_world 和 counter 开始，边运行边理解 element!、#[component]、hooks、输入互斥和路由。

按需查参考

当你开始写真实应用，再进入组件模型、hooks、输入层、状态、路由和内置组件的参考页。

最后用逃生口

内置抽象不够时，再看自定义 Hook、Provider、手写 Component 和原生 ratatui widget 桥接。

推荐路径

1. 安装与功能门控：把 crate 接进 Cargo 项目，并选择 feature set。
2. 快速开始：运行第一个应用。
3. 心智模型：理解声明式 UI 如何变成持久组件树。
4. 计数器教程：用一个每秒自增的数字串起组件和异步唤醒。
5. 异步数据三态：把本地状态推进到请求、loading、error 和旧数据保留。
6. Atom 全局状态：区分局部草稿、跨页面共享状态和 Router 自身状态。
7. 输入互斥：让编辑层和弹窗层独占键盘事件，背景组件不再抢输入。
8. 路由工作台：进入多页面应用结构、动态参数和 history。
9. Todo App：把状态、输入互斥和内置组件组合成完整工作流。
10. 核心模型：进入参考区，查组件模型、hooks、输入层、状态和路由细节。
11. 内置组件：按场景选择输入、弹窗、列表、树形选择和长文本组件。
12. 高级自定义：学习自定义 Hook、Provider、手写 Component 和原生 widget 桥接。
13. 示例路线图：查看 examples、文档页和 VHS 录制之间的对应关系。

像 React / Vue 一样读

你现在想做什么	对应文档	什么时候读
建立手感	start/*	第一次打开文档
做一个功能	tutorials/*、apps/todo-app	需要跟着例子写代码
查清 API 边界	core/*、components/*	已经知道自己要用什么
定制框架能力	advanced/*	内置组件或 hook 不够用
理解为什么这样设计	internals/*	需要调试运行时或贡献框架

文档原则

• 每个教程先出现可运行结果，再解释概念。
• 每个核心概念都有一个继续深入的参考页。
• 每个 example 都保持真实可运行，命令不随目录迁移变化。
• 每个运行截图都来自 VHS，不用手写终端效果图。
• 流程图优先使用 Mermaid；概念配图可以用 imagegen，但不能替代真实运行素材。