内部原理总览

Guide 负责教你“怎么使用 Ansiq”，但它不会细讲一个更根本的问题：

为什么 Ansiq 的边界要这样切。

“内部原理”这一部分，就是专门用来回答这个问题的。

这一部分适合谁看

如果你属于下面几类读者，这一部分很值得认真读：

• 你已经写过一个 Ansiq app，想理解底层为什么这样工作
• 你准备贡献 runtime、layout、surface 或 widgets
• 你遇到了一个不是 API 文档能直接解释的 bug
• 你想评估 Ansiq 适不适合承载一个长期运行的终端应用

如果你还没有写过任何 Ansiq 代码，建议先回到 Guide。

这一部分不是什么

它不是：

• API 手册
• rustdoc 替代品
• “源码逐行导读”

它更像是 Ansiq 的系统设计说明。

也就是说，这里讨论的核心问题通常是：

• 这个边界为什么属于 runtime，而不属于 widgets
• reactive graph 和 UI tree 为什么要分开
• 为什么 subtree replacement 不等于 virtual DOM diff
• 为什么 viewport / history 是 surface 语义，而不是 app 临时策略

你会在这里看到哪些主题

Runtime Boundary

解释：

• runtime 负责什么
• runtime 不负责什么

这是 Ansiq 整个架构里最重要的一条边界。

如果你现在最想知道的是“一个 app 在 runtime 里到底怎么活起来、怎么循环、怎么退出”，那下一页更适合直接读 Runtime 循环。

Reactive Graph vs UI Tree

解释：

• 响应式系统只负责“谁脏了”
• UI runtime 负责“脏了以后怎么更新屏幕”

如果你想理解 Ansiq 为什么不是“终端版 React”，这一页很重要。

如果你现在最想知道的是“响应式系统本身到底怎么工作、dirty 信息是怎么传给 runtime 的”，那就直接读 响应式图与 UI 树。

Subtree Replacement

解释：

• 为什么 Ansiq 没走完整 virtual DOM reconciliation
• 为什么用 dirty scope + subtree replacement

Continuity Contract

解释：

• subtree replacement 后怎么保住交互态
• continuity key 为什么存在

Partial Relayout and Damage Model

解释：

• 为什么不是每次都整棵树 relayout
• 为什么 invalidated regions 是 runtime 的核心能力之一

Terminal Session, Viewport, History, Scrollback

解释：

• Ansiq 如何在真实终端里管理 live viewport
• history 如何 commit 到 scrollback
• 哪些行为是显式 tradeoff，而不是“实现细节”

推荐阅读顺序

如果你第一次读“内部原理”，我建议按这个顺序：

1. Runtime Boundary
2. Reactive Graph vs UI Tree
3. Subtree Replacement
4. Continuity Contract
5. Partial Relayout and Damage Model
6. Terminal Session and Viewport
7. History and Scrollback

如果你是第一次从 Guide 切到“内部原理”，更推荐先读：

1. 生命周期与 Runtime 循环
2. 响应式系统原理
3. 再回到本区的阅读顺序

这一部分和 Guide 的关系

Guide 会告诉你：

• 用哪个 API
• 从哪个 example 开始
• 组件和 signals 怎么写

“内部原理”会告诉你：

• 这些 API 背后的系统边界是什么
• 为什么某些能力应该在 runtime 做，而不是在 app 做
• 当前实现已经成熟到什么程度，还在哪些点是 tradeoff

这两者不是重复，而是互补。