Expose layout API and refresh regression docs

开发记录/BUG/BUG-20260415-0005-局部重绘未补画上层兄弟导致遮挡错误.md

@@ -0,0 +1,73 @@
+# BUG-20260415-0005
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260415-0005
+- 标题: 局部重绘未补画上层兄弟导致遮挡错误
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: Window / Canvas / TabControl 局部重绘与合成
+- 版本 / 分支: 当前工作区
+- 环境: Windows + EasyX
+- 发现人: 用户回归测试
+- 关联 Fix ID：[可选]
+  - `Fix-BUG-20260415-0005`
+
+## 问题描述
+
+- 现象:
+  - 下层控件发生局部重绘后，位于其上方且与 coverage 相交的兄弟控件没有被补画回来。
+  - 表现为上层 `Canvas / Dialog / 页 / 页签按钮` 被“切掉”或被下层重新盖住。
+- 影响范围:
+  - 顶层普通控件之间
+  - `Canvas` 直接子控件之间
+  - `TabControl` 页签按钮与页面之间
+- 期望结果:
+  - 任意局部重绘提交后，父容器应按实际绘制顺序把 coverage 上方相交的兄弟重新合成回来。
+- 实际结果:
+  - 仅 dirty root 或 dirty child 被重画，上层兄弟未恢复。
+
+## 复现信息
+
+- 前置条件：[可选]
+  - 使用 `KEY5` 测试场景
+- 复现步骤:
+
+1. 进入 `KEY5`
+2. 触发下层控件局部重绘，例如 `Table` 翻页或相交子控件 hover / click
+3. 观察上层相交兄弟区域
+
+- 复现概率：高概率
+- 最小复现 Demo：[可选]
+  - `KEY5` 中 `Table` 与顶层粉色浮层重叠场景
+  - 同父 `Canvas` 兄弟相交场景
+- 证据：截图 / 日志 / 调用栈 / 录屏 / 断点观察
+  - 断点观察显示 dirty root 已提交，但上层 sibling 未重新执行 draw
+
+## 初步分析
+
+- 疑似位置:
+  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Window.cpp)
+  - [`Canvas.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Canvas.cpp)
+  - [`TabControl.cpp`](D:/programming/imGUI-easyX/imGui-easyX/TabControl.cpp)
+- 触发条件:
+  - 局部重绘提交写入了下层像素，但没有做 overlay 兄弟补画
+- 相关线索:
+  - 该问题不依赖“是否回贴背景快照”，直接重绘同样会破坏上层合成结果
+  - `Dialog` 之前之所以需要补画，本质上是同一类问题
+- 最近相关改动：[可选]
+  - 第二阶段开始引入更严格的局部重绘与 overlay 收口后，问题被系统性暴露
+
+## 跟踪信息
+
+- 首次发现时间: 2026-04-15
+- 最后更新时间: 2026-04-15
+- 修复版本：[可选]
+  - 当前工作区
+- 验证版本：[可选]
+  - 当前工作区
+- 备注：[可选]
+  - 后续仍需继续关注 `Dialog` 旧 synthetic move 机制与新模型的统一。