8a8e862098
Split the verified renderer, layout engine, Grid support, native boundary, tests, examples, and paired documentation into the independent Ebox repository. Keep ETAF and application concerns outside this package.
49 lines
2.0 KiB
Markdown
49 lines
2.0 KiB
Markdown
# Ebox 增量更新合同
|
||
|
||
本文定义底层发布合同。它独立于 ETAF 应用状态，直接使用 Ebox 的调用者和上层包都必须遵守。
|
||
|
||
## 所有权
|
||
|
||
1. 调用者拥有新的 source tree。
|
||
2. `ebox-tree.el` 拥有 identity、key、遍历和 snapshot。
|
||
3. `ebox-style.el`、`ebox-measure.el` 与布局模块拥有归一化、测量和几何。
|
||
4. `ebox-incremental.el` 拥有 dirty 分类、patch 规划、候选发布和更新报告。
|
||
5. `ebox-buffer-backend.el` 是 text property 与 buffer 变更的唯一 owner。
|
||
|
||
任何层都不能从可见 buffer 文本推断应用状态；公共调用者不能原地修改已经发布的树。
|
||
|
||
## Commit 生命周期
|
||
|
||
```text
|
||
新的根树
|
||
-> 校验与归一化
|
||
-> reconciliation key 与 identity
|
||
-> 测量/布局候选
|
||
-> 分类 dirty owner
|
||
-> 渲染候选 span
|
||
-> 原子发布
|
||
-> 刷新 snapshot 与报告
|
||
```
|
||
|
||
候选要么完整发布，要么丢弃。候选失败时必须保留之前的 buffer 文本、属性、runtime identity、滚动状态和最近一次成功报告。
|
||
|
||
## Patch 顺序
|
||
|
||
规划器优先使用 `paint-patch`，再使用 `span-patch`、`owner-rerender`，最后在几何或 identity 使小操作不安全时使用 `root-rerender`。Patch 不得静默扩大范围；报告要记录策略、dirty key、owner 和 patch 操作。
|
||
|
||
## Identity 与坐标
|
||
|
||
Key 只在同级兄弟集合内有效。Region 与 host-ref 位置绑定于 generation；buffer 变更后调用者必须通过公共 accessor 重新获得位置。Buffer marker、display span 和 text property 是 backend 事实，不是 source tree identity。
|
||
|
||
## 验证
|
||
|
||
每条更新路径都要验证：
|
||
|
||
- 发布后的可见文本和属性完全正确；
|
||
- 兄弟节点重排时 keyed identity 稳定；
|
||
- rollback 后没有候选数据残留；
|
||
- 可以局部更新时 patch 范围受控；
|
||
- native reflow 不可用时 fallback 正确。
|
||
|
||
聚焦测试使用 `tests/ebox-commit-tests.el`、`tests/ebox-core-render-tests.el` 和 `tests/ebox-grid-tests.el`，然后运行 `make check`。
|