发布前托管重绘与布局封版收口

收口 Dialog/overlay 后鼠标状态同步、Tooltip 临时 coverage 与持久 coverage 拆分、跨 root 脏区补提交、TextBox/Button 绘制副作用修复，并补充 KEY6 回归用例和 BUG/Fix/Feature 开发记录。
2026-05-17 00:26:08 +08:00
parent 2388f22c99
commit 9155a86a8a
26 changed files with 1355 additions and 175 deletions
@@ -0,0 +1,51 @@
+# BUG-20260511-0009
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260511-0009
+- 标题: TabControl::indexOf 未命中时返回最后索引
+- 状态：已修复
+- 严重性：S3
+- 优先级：P2
+- 模块: TabControl
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX / z-testDome 回归场景
+- 发现人: Codex 巡检
+- 关联 Fix ID: Fix-BUG-20260511-0009
+
+## 问题描述
+
+- 现象: `TabControl::indexOf(const std::string& tabText) const` 在未找到目标页签时返回循环后的最后索引。
+- 影响范围: 依赖 `indexOf()` 判断页签是否存在的调用方可能把“不存在”误判为最后一个页签。
+- 期望结果: 找到匹配页签时返回对应索引；未找到时返回 `-1`。
+- 实际结果: 未找到时返回最后一个页签的索引。
+
+## 复现信息
+
+- 前置条件：[可选]
+- 复现步骤:
+
+1. 构造包含至少一个页签的 `TabControl`。
+2. 调用 `indexOf()` 查询不存在的页签文本。
+3. 观察返回值。
+
+- 复现概率：必现
+- 最小复现 Demo：[可选]
+- 证据：源码巡检可证
+
+## 初步分析
+
+- 疑似位置: `TabControl.cpp::indexOf`
+- 触发条件: 查询文本不存在。
+- 相关线索: 函数名和预期语义要求“不存在返回 -1”，但旧实现返回 `idx`。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2026-05-11
+- 最后更新时间: 2026-05-11
+- 修复版本: 当前工作区
+- 验证版本: KEY1 ~ KEY6 编译验证通过
+- 备注：[可选]
@@ -0,0 +1,52 @@
+# BUG-20260511-0010
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260511-0010
+- 标题: 局部提交内部 coverage 扩张未反馈导致 Dialog 漏补
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: Window / Canvas / Dialog / 托管重绘
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX / KEY6
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260511-0010
+
+## 问题描述
+
+- 现象: KEY6 中非模态 Dialog 打开后，触发旁边按钮 Tooltip，某些位置会导致下层按钮重绘覆盖 Dialog。
+- 影响范围: 可局部提交的 root 在内部补画兄弟控件后，如果实际写屏范围扩大，Window 可能仍按初始 coverage 判断上层 overlay。
+- 期望结果: 下层 root 内部扩张后的实际写屏区域能触发上层 Dialog 补画。
+- 实际结果: Window 使用初始 coverage，导致 Dialog overlay 补画漏判。
+
+## 复现信息
+
+- 前置条件：[可选] 打开 KEY6，触发非模态 `AbortRetryIgnore` 对话框。
+- 复现步骤:
+
+1. 最大化窗口。
+2. 打开 KEY6 非模态 `AbortRetryIgnore` 对话框。
+3. 在 `RetryCancel` 按钮特定区域触发 Tooltip。
+4. 观察非模态 Dialog 是否被下层按钮局部重绘覆盖。
+
+- 复现概率：高概率
+- 最小复现 Demo：KEY6
+- 证据：临时 `OverlayTemp` 日志显示 Canvas 内部 coverage 从 `(250,512,490,583)` 扩张到 `(250,512,700,583)`，但 Window 仍用旧 working coverage 判断 Dialog，相交结果为 `hit=0`。
+
+## 初步分析
+
+- 疑似位置: `Window::flushManagedRepaint()` 与 `Canvas::requestRepaint(this)` 的 coverage 交接。
+- 触发条件: root 支持局部提交，内部补画后序兄弟导致实际 coverage 扩张。
+- 相关线索: Dialog 区域与内部最终 coverage 相交，但与 Window 初始 working coverage 不相交。
+- 最近相关改动：[可选] 托管局部重绘与 overlay 补画收口。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-05-11
+- 最后更新时间: 2026-05-11
+- 修复版本: 当前工作区
+- 验证版本: KEY6 编译通过，待用户手测
+- 备注：[可选] 精确 actual coverage 回传作为下版本优化项。
@@ -0,0 +1,51 @@
+# BUG-20260511-0011
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260511-0011
+- 标题: 跨 root 回调改脏未同轮提交导致 Label 延迟刷新
+- 状态：已修复
+- 严重性：S3
+- 优先级：P1
+- 模块: Window / 托管重绘 / Label / TabControl
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX / KEY6
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260511-0011
+
+## 问题描述
+
+- 现象: KEY6 中点击 Right 页签内按钮后，A 区状态 Label 不立即刷新，需要下一次左键消息才显示。
+- 影响范围: 事件回调修改了另一个顶层 root 下的控件状态时，目标 root 可能不会进入本轮托管重绘队列。
+- 期望结果: 回调中改脏的跨 root 控件能在同一轮事件尾刷新。
+- 实际结果: 只有当前事件分发链所在 root 被提交，其他 root 的 dirty 子树滞留到下一次事件。
+
+## 复现信息
+
+- 前置条件：[可选] 打开 KEY6，激活右侧页签第一页。
+- 复现步骤:
+
+1. 点击 Right 页签中的“页内按钮”。
+2. 观察 A 区状态 Label。
+3. 再点击空白处或其他控件。
+
+- 复现概率：必现
+- 最小复现 Demo：KEY6
+- 证据：`Label::setText()` 只标脏目标 Label，不主动把其所属 `shapePanel` root 登记到 Window。
+
+## 初步分析
+
+- 疑似位置: `Window` 事件尾托管重绘收口。
+- 触发条件: 当前事件 root 与被回调修改的目标 root 不同。
+- 相关线索: A 区 Label 在下一次左键消息后才刷新，说明 dirty 状态存在但未同轮提交。
+- 最近相关改动：[可选] 托管重绘统一收口。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-05-11
+- 最后更新时间: 2026-05-11
+- 修复版本: 当前工作区
+- 验证版本: KEY6 编译通过，待用户手测
+- 备注：[可选]
@@ -0,0 +1,54 @@
+# BUG-20260511-0012
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260511-0012
+- 标题: Tooltip 临时浮层污染或擦除兄弟控件快照
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: Tooltip / Canvas / TabControl / 托管重绘 / 背景快照
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX / KEY6
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260511-0012
+
+## 问题描述
+
+- 现象: KEY6 A 区禁用按钮触发 Tooltip 后，如果 Tooltip 位于状态 Label 下方，状态 Label 可能捕获 Tooltip 到背景快照，或用透明 Label 的旧快照擦掉 Tooltip 一部分。
+- 影响范围: 同一容器内，绘制顺序在 Tooltip 触发控件之后、且与 Tooltip coverage 相交的兄弟控件。
+- 期望结果: Tooltip 作为临时浮层显示，不应污染兄弟控件背景快照，也不应被透明 Label 的旧快照擦除。
+- 实际结果: 旧逻辑把 Tooltip coverage 与持久绘制 coverage 混用，导致兄弟控件作废快照并重抓，或保留快照重画时擦掉 Tooltip。
+
+## 复现信息
+
+- 前置条件：[可选] 打开 KEY6。
+- 复现步骤:
+
+1. 将鼠标移到 A 区禁用按钮上触发 Tooltip。
+2. 让 Tooltip 显示区域位于状态 Label 下方。
+3. 观察状态 Label 区域是否覆盖 / 擦除 Tooltip。
+4. 触发下一次重绘后观察是否有 Tooltip 残留。
+
+- 复现概率：高概率
+- 最小复现 Demo：KEY6 A 区
+- 证据：`Label::draw()` 即使透明也会先 `restBackground()`；如果被临时浮层触发补画，会回贴旧快照。
+
+## 初步分析
+
+- 疑似位置: `Canvas::requestRepaint(this)` / `TabControl::requestRepaint(this)` 的局部 overlay 补画策略。
+- 触发条件: 下层 Button Tooltip 的完整 coverage 与后序兄弟控件相交。
+- 相关线索:
+  - `Button::getManagedRepaintCoverageRect()` 包含 Tooltip。
+  - Canvas 旧逻辑用同一 coverage 同时决定“是否补画兄弟”和“是否刷新兄弟背景快照”。
+- 最近相关改动：[可选] Tooltip coverage 纳入托管重绘链。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-05-11
+- 最后更新时间: 2026-05-11
+- 修复版本: 当前工作区
+- 验证版本: KEY1 ~ KEY6 编译通过，待用户手测
+- 备注：[可选]
@@ -0,0 +1,55 @@
+# Fix-BUG-20260511-0009
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260511-0009
+- 关联 BUG ID: BUG-20260511-0009
+- 修复目标: 保证 `TabControl::indexOf()` 未命中时返回 `-1`
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: `indexOf()` 循环结束后直接返回 `idx`，没有显式处理未命中分支。
+- 触发条件: 查询不存在的页签文本。
+- 为什么之前没发现：[可选] 当前测试更多关注页签切换行为，未覆盖未命中返回值。
+- 关键证据：[可选] `TabControl.cpp` 旧实现未命中路径返回最后索引。
+
+## 修复方案
+
+- 修复思路: 未找到匹配项时显式返回 `-1`。
+- 关键改动: 将 `TabControl::indexOf()` 末尾返回值从 `idx` 改为 `-1`。
+- 涉及文件 / 类 / 函数: `TabControl.cpp::TabControl::indexOf`
+- 影响的 API / 行为：[可选] 行为修正；符合函数语义。
+- 关键约束 / 不变量：[可选] 找到时仍返回真实索引。
+- 回滚点 / 开关：[可选] 无
+
+## 影响评估
+
+- 影响范围: 仅影响 `indexOf()` 未命中返回值。
+- 兼容性影响：无
+- 行为变化：有（未命中从最后索引修正为 `-1`）
+- 性能影响：无
+- 回归风险: 低
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `TabControl.cpp`。
+2. 编译 `z-testDome.cpp` 的 `KEY1 ~ KEY6`。
+3. 静态确认未命中路径返回 `-1`。
+
+- 验证结果: 编译通过
+- 回归检查：[可选] KEY1 ~ KEY6 编译级回归通过
+- 验证证据：[可选]
+
+## 落地信息
+
+- Commit: 未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
@@ -0,0 +1,57 @@
+# Fix-BUG-20260511-0010
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260511-0010
+- 关联 BUG ID: BUG-20260511-0010
+- 修复目标: 避免局部 root 内部 coverage 扩张后漏补 Dialog / 上层 overlay
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: `commitManagedRepaint()` 只执行绘制，不返回本轮实际写屏 coverage；Window 仍按登记时的初始 coverage 进行上层补画判断。
+- 触发条件: Canvas / TabControl 内部局部提交中补画了后序兄弟控件，实际写屏范围大于初始 source coverage。
+- 为什么之前没发现：[可选] 需要 Dialog、Tooltip、后序兄弟补画三者同时满足。
+- 关键证据：[可选] 临时日志中 `Canvas partial end coverage` 已与 Dialog 相交，但 `dialog overlay check` 使用旧 working coverage 结果为不相交。
+
+## 修复方案
+
+- 修复思路: 在 Window 层进行保守兜底。root 局部提交完成后，如果 root 仍支持局部提交，则将 root 当前 managed coverage 并入上层补画判断 coverage。
+- 关键改动:
+  - `Window::flushManagedRepaint()` 在 `root->commitManagedRepaint()` 后合并 `root->getManagedRepaintCoverageRect()`。
+  - 只扩大上层补画判断，不改变 root 自身局部提交策略。
+- 涉及文件 / 类 / 函数: `Window.cpp::flushManagedRepaint`
+- 影响的 API / 行为：[可选] 无公开 API 变化。
+- 关键约束 / 不变量：[可选] Dialog 仍保持顶层 overlay 语义。
+- 回滚点 / 开关：[可选] 回退该 coverage 合并逻辑。
+
+## 影响评估
+
+- 影响范围: 托管重绘后的上层普通控件 / Dialog 补画判断。
+- 兼容性影响：无
+- 行为变化：有（Dialog / 上层控件补画更保守）
+- 性能影响：有（可能多补画少量 overlay）
+- 回归风险: 中低；主要风险是局部 root 大范围覆盖时上层补画次数增加。
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Window.cpp / Canvas.cpp`。
+2. 编译 `z-testDome.cpp /DKEY=6`。
+3. 编译 `z-testDome.cpp` 的 `KEY1 ~ KEY6`。
+
+- 验证结果: 编译通过；临时日志已删除
+- 回归检查：[可选] KEY6 非模态 Dialog + Tooltip 覆盖链待用户手测
+- 验证证据：[可选]
+
+## 落地信息
+
+- Commit: 未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注: 下版本建议让 `commitManagedRepaint()` 返回 actual coverage，替代 root 全覆盖兜底。
@@ -0,0 +1,60 @@
+# Fix-BUG-20260511-0011
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260511-0011
+- 关联 BUG ID: BUG-20260511-0011
+- 修复目标: 事件尾补收集跨 root dirty 子树，保证同轮托管提交
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: `Window::requestManagedRepaint()` 只登记当前事件链触发的 source/root；回调里直接修改其他 root 的控件时，该 root 只变 dirty，没有进入 `managedRepaintItems`。
+- 触发条件: 点击一个 root 中的控件，回调修改另一个 root 下的 Label / 控件状态。
+- 为什么之前没发现：[可选] 需要跨 root 回调才能稳定暴露。
+- 关键证据：[可选] 下一次鼠标消息后 Label 才刷新，说明目标 root dirty 状态滞留。
+
+## 修复方案
+
+- 修复思路: 在普通输入事件收口阶段、`flushManagedRepaint()` 前扫描所有顶层普通控件和可见 Dialog，发现未登记但存在 dirty 子树的 root，则补登记为托管重绘项。
+- 关键改动:
+  - 新增 `Window::collectDirtyRootsForManagedRepaint()`。
+  - `runEventLoop()` 在 `flushManagedRepaint()` 前调用该函数。
+- 涉及文件 / 类 / 函数:
+  - `Window.h`
+  - `Window.cpp::collectDirtyRootsForManagedRepaint`
+  - `Window.cpp::runEventLoop`
+- 影响的 API / 行为：[可选] 无公开 API 变化。
+- 关键约束 / 不变量：[可选] 只处理可见 root；已登记 root 不重复登记。
+- 回滚点 / 开关：[可选] 移除事件尾补收集调用。
+
+## 影响评估
+
+- 影响范围: 普通输入事件尾的托管重绘收口。
+- 兼容性影响：无
+- 行为变化：有（跨 root dirty 会更及时刷新）
+- 性能影响：有（事件尾多一次顶层 dirty 子树扫描）
+- 回归风险: 中；如果存在历史残留 dirty，可能更早暴露重绘问题。
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Window.cpp`。
+2. 编译 `z-testDome.cpp /DKEY=6`。
+3. 编译 `z-testDome.cpp` 的 `KEY1 ~ KEY6`。
+
+- 验证结果: 编译通过
+- 回归检查：[可选] KEY6 Right 页内按钮更新 A 区状态 Label 待用户手测
+- 验证证据：[可选]
+
+## 落地信息
+
+- Commit: 未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
@@ -0,0 +1,68 @@
+# Fix-BUG-20260511-0012
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260511-0012
+- 关联 BUG ID: BUG-20260511-0012
+- 修复目标: 区分 Tooltip 临时浮层 coverage 与会污染背景快照的持久 coverage
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: 托管重绘只有一类 coverage，既用于完整绘制范围判断，也用于兄弟控件背景快照刷新判断。Tooltip 属于临时浮层，不应进入后者。
+- 触发条件: Tooltip coverage 覆盖到后序兄弟控件，兄弟控件被局部 overlay 补画。
+- 为什么之前没发现：[可选] 需要 Tooltip 与透明 Label 或带快照兄弟控件重叠。
+- 关键证据：[可选] 透明 Label 已设置 `setTextdisap(true)`，但 `draw()` 仍会先回贴背景快照。
+
+## 修复方案
+
+- 修复思路: 拆分完整 coverage 与持久 coverage。Tooltip 进入完整 coverage，用于 Window/Dialog overlay 判断；但不进入持久 coverage，避免兄弟控件刷新快照时捕获 Tooltip。
+- 关键改动:
+  - `Control` 新增内部虚函数 `getManagedRepaintPersistentCoverageRect()`。
+  - `Button` 的完整 coverage 包含 Tooltip，持久 coverage 仅包含按钮本体。
+  - `Canvas / TabControl / Table` 递归合并子控件持久 coverage。
+  - `Canvas / TabControl` 局部提交中，只有命中持久 coverage 的兄弟控件才作废快照并补画。
+  - 只命中 Tooltip 等临时 coverage 的兄弟控件不再补画，避免透明控件回贴旧快照擦掉 Tooltip。
+- 涉及文件 / 类 / 函数:
+  - `Control.h / Control.cpp`
+  - `Button.h / Button.cpp`
+  - `Canvas.h / Canvas.cpp`
+  - `TabControl.h / TabControl.cpp`
+  - `Table.h / Table.cpp`
+- 影响的 API / 行为：[可选] 新增内部 virtual 接口，无公开用户 API 变化。
+- 关键约束 / 不变量：[可选] Tooltip 智能选位仍不在本轮范围内。
+- 回滚点 / 开关：[可选] 回退持久 coverage 拆分逻辑。
+
+## 影响评估
+
+- 影响范围: Tooltip、Canvas / TabControl 局部 overlay 补画、背景快照捕获。
+- 兼容性影响：无
+- 行为变化：有（Tooltip 作为临时浮层时，不再触发普通兄弟控件补画）
+- 性能影响：轻微（多维护一组矩形并集和相交判断）
+- 回归风险:
+  - 如果某控件持久 coverage 定义过小，可能漏补兄弟快照。
+  - Tooltip 会短暂显示在同容器后序普通控件上方，这是本轮有意选择。
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Control.cpp / Button.cpp / Canvas.cpp / TabControl.cpp / Table.cpp / Window.cpp`。
+2. 编译 `z-testDome.cpp` 的 `KEY1 ~ KEY6`。
+3. 手测 KEY6 A 区禁用按钮 Tooltip 与状态 Label 交叠。
+4. 手测 TabControl 页签 / 页面内 Tooltip。
+
+- 验证结果: 编译通过；GUI 行为待用户手测
+- 回归检查：[可选] KEY6 A 区、KEY5 Tooltip/overlay、KEY4 Dialog overlay
+- 验证证据：[可选]
+
+## 落地信息
+
+- Commit: 未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注: 下版本可进一步引入 actual coverage 返回值和正式 coverage 诊断日志。
@@ -0,0 +1,105 @@
+# 功能变更 ID: Feature-20260511-0012
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260511-0012
+- 标题: 发布前托管重绘与 KEY6 封版收口
+- 状态：已完成
+- 类型：修改
+- 级别：L3 重大
+- 模块: Window / Canvas / TabControl / Tooltip / Dialog / 测试用例
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX
+- 负责人: Codex
+
+## 变更背景
+
+- 背景:
+  - 发布前封版阶段需要稳定现有布局、托管重绘、Dialog / overlay / hover 状态同步链路。
+  - KEY6 补充覆盖后暴露了非模态 Dialog、Tooltip、跨 root dirty、透明 Label 快照等组合问题。
+- 目标:
+  - 修复确定性小问题。
+  - 收口 Dialog / overlay 后鼠标状态同步语义。
+  - 让 KEY6 覆盖已实现但原主回归未覆盖的分支。
+  - 修复托管局部重绘中 coverage 和背景快照语义混用导致的问题。
+- 不做什么：[可选]
+  - 不实现焦点系统。
+  - 不实现键盘事件系统。
+  - 不做 Tooltip 智能选位。
+  - 不做 Table 纵向 Stretch。
+  - 不实现 Table 内部局部重绘体系。
+
+## 变更内容
+
+- 变更摘要:
+  - 修复 `TabControl::indexOf()` 未命中返回值。
+  - 抽取 Dialog / overlay 后鼠标状态同步辅助函数。
+  - 新增 KEY6 分支覆盖用例。
+  - `Window` 增加局部 root 提交后 overlay coverage 保守兜底。
+  - `Window` 事件尾补收集跨 root dirty 子树。
+  - 托管重绘拆分完整 coverage 与持久 coverage，避免 Tooltip 污染背景快照。
+- 新增项：[可选]
+  - `Window::syncMouseStateAfterOverlayChanged(...)`
+  - `Window::collectDirtyRootsForManagedRepaint()`
+  - `Control::getManagedRepaintPersistentCoverageRect()`
+  - KEY6 测试入口
+- 修改项：[可选]
+  - `Canvas / TabControl` 局部 overlay 补画策略。
+  - `Button` Tooltip coverage 语义。
+  - `Table` 托管 coverage 语义补充。
+- 删除 / 废弃项：[可选]
+  - 无
+- 受影响的文件 / 类 / 函数:
+  - `Window.h / Window.cpp`
+  - `Control.h / Control.cpp`
+  - `Button.h / Button.cpp`
+  - `Canvas.h / Canvas.cpp`
+  - `TabControl.h / TabControl.cpp`
+  - `Table.h / Table.cpp`
+  - `z-testDome.cpp`
+- 对外 API / 属性变化：[可选]
+  - 无公开用户 API 变化。
+  - 新增接口均为内部托管重绘语义。
+
+## 行为对照
+
+- 变更前:
+  - `indexOf()` 未命中返回最后索引。
+  - Dialog 关闭 / 非模态 Dialog 吞鼠标移动后的 synthetic move 逻辑散落在 `runEventLoop()`。
+  - 局部 root 内部 coverage 扩张后，Window 可能漏补 Dialog。
+  - 跨 root 回调改脏后，目标 root 可能等下一次事件才刷新。
+  - Tooltip 临时浮层与持久 coverage 混用，可能污染或擦除兄弟控件快照。
+- 变更后:
+  - `indexOf()` 未命中返回 `-1`。
+  - overlay 后鼠标状态同步由语义函数集中处理。
+  - Window 对可局部提交 root 的上层补画判断更保守。
+  - 事件尾会补收集未登记但已 dirty 的 root。
+  - Tooltip 进入完整 coverage，但不进入持久 coverage；只命中临时浮层的兄弟控件不再补画。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 用户代码无需迁移。
+
+## 验证与落地
+
+- 验证方式:
+  - 编译核心变更文件。
+  - 编译 `z-testDome.cpp` 的 `KEY1 ~ KEY6`。
+  - 根据用户手测反馈修正 KEY6 Tooltip / Dialog / Label 组合问题。
+- 验证结果:
+  - `Control.cpp / Button.cpp / Canvas.cpp / TabControl.cpp / Table.cpp / Window.cpp` 编译通过。
+  - `KEY1 ~ KEY6` 编译通过。
+  - GUI 行为需继续由用户在本机手测确认。
+- 关联 BUG / Fix：[可选]
+  - BUG-20260511-0009 / Fix-BUG-20260511-0009
+  - BUG-20260511-0010 / Fix-BUG-20260511-0010
+  - BUG-20260511-0011 / Fix-BUG-20260511-0011
+  - BUG-20260511-0012 / Fix-BUG-20260511-0012
+- Commit: 未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - 下版本建议引入 `commitManagedRepaint()` actual coverage 返回值，替代当前 root coverage 保守兜底。
+  - 下版本建议建立正式 coverage 诊断日志开关，避免再临时散加日志。