fix(UI): 布局边界按尺寸自适应 + 修复拖滚动条的绘制残留与浮层层级

## 1. 边界描边按元素尺寸自适应（修复"小元素变成粗描边"）旧规则四角固定 3-4px：对 15px 的复选框来说包角占短边 20%，看起来就是一整圈粗边框。新规则全部以**短边**为基准： - 四边固定 1 设备像素； - 包角粗细 = min(基础 4/3, 短边/10)，再夹到 [1, 短边/4]； - 包角长度 = min(14, 短边/3)，且不小于包角粗细； - 短边 <= 12 只画四个 L 形角标记、**不画边**（一圈连续描边会让小方框显得"被框住"）； - 短边 <= 5 完全不画（再画就盖住元素本身）； - 内缩只用于「层级 > 0 且短边 >= 10」，否则小元素会被缩没。同时**删除文字标签**（含 UiDebugPaintStyle）：黑底白字在小元素上必糊成一片，体积也省约 1.5KB。 ## 2. 拖网格滚动条时的"大量绘制残留"：三个独立成因 R1. PlotView::CollectDebugBoxes 读了 m_decorRects —— 那是**装饰层位图缓存**的登记矩形，坐标处在位图/图层坐标系（带负 Y、超出绘图区），于是出现 (472,-27 1213x101) 这类 **横跨工具栏的幽灵巨框**。改为只用 LaneBadgeRect 与 m_legendHits（屏幕坐标）。 R2. Paint 的三条快路径（静态场景贴图 / 宽基底贴图 / 样式补丁）只重画**变化的部分**，而调试边框是画在整个窗口上的叠加内容 ⇒ 上一帧的边框残留在未被重画的像素上，直到松开鼠标走整幅重绘才消失。新增 PlotView::SetForceFullRepaint(bool)：开启调试叠加层时禁用全部快路径。 R3. 组件内元素可能落在自己地盘之外（滚出可视区的 lane.rect 的 Y 为负），不裁剪就画到工具栏/标签栏上。box 增加 clip：宿主按组件 Area() 设置，Add() 跳过无交集、绘制时与 clip 求交。另外把 Render 的 fullChrome 并入 m_showLayoutBounds，装饰区也保证完整一帧。 ## 3. 层级：排序 + 挖洞（修复二级菜单被下层边界覆盖） - UiDebugBoxList::PushLayer() + 按 (layer, depth) 稳定排序：后收集的内容压住先收集的。 - 但仅靠排序不够：调试线画在所有内容之后，下层组件的线仍会显示在不透明菜单上面。新增 AddOccluder()：菜单/拾色器把本体登记为遮挡矩形，绘制**更低层**的 box 时用 Region::Exclude 挖洞。实测菜单区与子菜单区的琥珀/绿色像素均为 0。 - 浮层**不设** clip = 本体矩形：二级子菜单会展开到本体之外，设裁剪会把它整个裁掉。 ## 4. 验证 - make release / make debug 零 error 零 warning；TargetCheck.exe 906,752 B（885.5 KiB < 900 KiB）。 - 新增 .preflight/lbresid（MF4-Record.MF4 / 283 网格 / 拖滚动条）**5/5**： toolbar-unchanged-while-scrolling、repaint-same-state-is-identical、 toolbar-restored-by-full-repaint、residual-never-above-plot-area、later-layer-wins-over-earlier。 - 新增 .preflight/lbzorder **4/4**：菜单与二级子菜单区内下层颜色像素 = 0。 - 回归：.preflight/lbcheck 21/21、Tools/uicheck 69/69、 Tools/rendercheck「工具栏带以下」区域哈希 8/8 与上一轮逐一相同 + FUNC 7/7。注：判断"是否有绘制残留"不能用"拖拽帧 vs 松开后一帧"——两者图层预热进度不同会产生几十万像素的**合法**差异；正确判据是**同一状态连续两帧必须逐像素相同**。 ## 5. 文档 Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第八阶段； Documents/agent_mem.md 同步变更日志与「2026-10-28 第十轮」硬约束与踩坑。
2026-10-28 17:01:26 +08:00
1 parent 24706c906a
commit 57e12cfb27
@@ -482,3 +482,41 @@ protected:
 * 「工具栏带以下」区域哈希与上一轮**逐一相同**（证明改动只落在工具栏带内）；
 * `lbcheck` 21/21、`rendercheck` FUNC 7/7、`uicheck` 69/69；
 * 打开开关后：每行的复选框/色块/名称/GX 徽标/✕、每个网格的 GX 徽标与图例、每个浮层控件都有独立包角框。
+
+---
+
+# 第八阶段计划（2026-10-28 第十轮）：边界观感自适应 + 残留与层级缺陷修复
+
+> 用户反馈：① 包角对小元素来说太粗（小方框直接变成粗描边）；② 不需要黑色底衬的文字标签；
+> ③ 加载 MF4-Record.MF4 全部信号独立网格后，按住左键拖动网格滚动条快速滚动会出现大量
+> 绘制残留（工具栏与网格区域都有），松开并移动鼠标才消失；④ 右键二级菜单上被下层元素的
+> 边界线覆盖，干扰观察菜单布局。
+
+## 任务清单
+
+| # | 任务 | 验证手段 |
+| --- | --- | --- |
+| P8-1 | 包角粗细／长度按矩形短边自适应；小方框只画角不画边；过小则不画 | 截图放大 3 倍核对 |
+| P8-2 | 删除文字标签（连同 `UiDebugPaintStyle`），降低体积与视觉噪声 | 编译 + 体积 |
+| P8-3 | 定位并修复「拖网格滚动条时的绘制残留」 | 新增离屏探针 `.preflight/lbresid` |
+| P8-4 | 修复 `PlotView` 误用 `m_decorRects`（位图坐标系）产生的跨工具栏幽灵框 | 同上（box 清单打印） |
+| P8-5 | 调试叠加层开启时强制绘图区整幅重绘（禁用三条快路径） | 同上（同状态两帧必须逐像素相同） |
+| P8-6 | box 增加 `clip`（组件地盘），组件内越界元素不再画到邻居上 | 同上（差异 bbox 不得越过绘图区上沿） |
+| P8-7 | 层级：`(layer, depth)` 双排序键 + 浮层 `occluder` 挖洞 | 新增探针 `.preflight/lbzorder`（4 条断言） |
+| P8-8 | 文档与共享记忆同步；`TargetCheck.exe` < 900 KiB | 构建 |
+
+## 风险与对策
+
+| 风险 | 对策 |
+| --- | --- |
+| 强制整幅重绘让调试模式变慢 | 只在开关打开时生效；关闭立即恢复快路径 |
+| `Region::Exclude` 影响其他绘制 | 只在 `Save/Restore` 内临时 `SetClip`，且仅在存在遮挡时才走该分支 |
+| 裁剪把紧贴边界的包角裁掉 | 裁剪用 `floor/ceil` 向外取整（宁可多一像素） |
+| 移除标签后难以辨认 box 归属 | 层级配色（青蓝/品红/琥珀/绿）+ 包角形状 |
+
+## 完成判据
+
+* 零 warning；`lbresid` 5/5、`lbzorder` 4/4、`lbcheck` 21/21、`uicheck` 69/69；
+* `rendercheck` 的「工具栏带以下」区域哈希与上一轮**逐一相同**、FUNC 7/7；
+* 拖动滚动条期间工具栏区域像素**完全不变**，且同状态两帧**逐像素相同**；
+* 菜单/二级子菜单区域内不出现下层组件的边界色。
@@ -499,3 +499,83 @@ rendercheck FUNC               7/7 PASS
 * 齿轮图标在 22px 时，"齿从环中心线伸出"会让齿被环的描边吃掉，看起来只剩一个甜甜圈。
  必须让**齿占最外一圈、外环缩到 0.54R**，齿才会明显。
 * 中文不能写进 `.ps1`（PS 5.1 按 GBK 读），文本块要落到 UTF-8 数据文件再由 ASCII 脚本拼接。
+
+---
+
+## 第十轮（2026-10-28）：包角自适应 + 文字标签移除 + 绘制残留与层级缺陷修复
+
+### 进度总览
+
+| # | 任务 | 状态 | 验证 |
+| --- | --- | --- | --- |
+| 1 | 包角粗细/长度按短边自适应 | ✅ | 3 倍放大截图 |
+| 2 | 小方框只画角、不画边 | ✅ | 同上 |
+| 3 | 删除文字标签与 `UiDebugPaintStyle` | ✅ | 体积 −1.5 KB |
+| 4 | 修复拖滚动条时的绘制残留（三条快路径） | ✅ | `.preflight/lbresid` |
+| 5 | 修复 `m_decorRects` 幽灵框 | ✅ | box 清单打印 |
+| 6 | box `clip`（组件地盘） | ✅ | 差异 bbox 不再越过绘图区上沿 |
+| 7 | `(layer, depth)` 双排序键 | ✅ | `.preflight/lbzorder` |
+| 8 | 浮层 `occluder` 挖洞 | ✅ | 菜单区 `amber=0 green=0` |
+| 9 | 文档 + 共享记忆 | ✅ | — |
+
+### 1. 描边按尺寸自适应（修复"小元素变成粗描边"）
+
+旧规则：四角固定 3–4px、四边 1px。对 15px 的复选框来说，3px 包角占短边 20%，看起来就是粗边框。
+
+新规则（全部以**短边**为基准）：
+
+| 量 | 规则 |
+| --- | --- |
+| 四边 | 固定 1 设备像素 |
+| 包角粗细 | `min(基础值 4/3, 短边/10)`，再夹到 `[1, 短边/4]` |
+| 包角长度 | `min(14, 短边/3)`，且不小于包角粗细 |
+| 短边 ≤ 12 | **只画四个 L 形角标记、不画边**（一圈连续描边会让小方框显得"被框住"） |
+| 短边 ≤ 5 | 完全不画（再画就盖住元素本身） |
+| 内缩 | 仅层级 > 0 **且短边 ≥ 10** 时内缩 1px |
+
+同时**删除了文字标签**（含 `UiDebugPaintStyle`）：黑底白字在小元素上必然连成一片，
+且体积上省掉约 1.5 KB。
+
+### 2. 绘制残留：三个独立成因，逐个修复
+
+| # | 成因 | 修复 |
+| --- | --- | --- |
+| R1 | `PlotView::CollectDebugBoxes` 读了 `m_decorRects` —— 那是**装饰层位图缓存**的登记矩形，坐标处在**位图/图层坐标系**（带负 Y、超出绘图区）。于是出现 `(472,-27 1213x101)` 这类**横跨工具栏的幽灵巨框** | 不再读 `m_decorRects`；只保留 `LaneBadgeRect` 与 `m_legendHits`（屏幕坐标） |
+| R2 | `Paint` 的三条快路径（静态场景贴图 / 宽基底贴图 / 样式补丁）只重画**变化的部分**，而调试边框是画在整个窗口上的叠加内容 ⇒ 上一帧的边框残留在未被重画的像素上 | 新增 `PlotView::SetForceFullRepaint(bool)`：开启调试叠加层时禁用全部快路径 |
+| R3 | 组件内元素可能落在自己地盘之外（滚出可视区的 `lane.rect` Y 为负），不裁剪就画到工具栏/标签栏上 | box 增加 `clip`：宿主按组件 `Area()` 设置，`Add()` 跳过无交集、绘制时求交 |
+
+另外把 `Render` 的 `fullChrome` 也并入 `m_showLayoutBounds`，保证装饰区每帧都是完整一帧。
+
+### 3. 层级：`(layer, depth)` 双排序键 + 浮层挖洞
+
+* `layer` 由 `UiDebugBoxList::PushLayer()` 分配，宿主每收集完一个组件就 +1 ⇒ **后收集的压住先收集的**
+  （右键二级菜单是最后收集的浮层）。
+* `depth` 在同一层内先画父再画子，子元素的彩色包角不被父的边压住。
+* ⚠️ 仅靠排序**不够**：调试线画在所有内容之后，下层组件的线仍会显示在不透明菜单上面。
+  因此新增 `AddOccluder()`：菜单/拾色器把本体登记为遮挡矩形，绘制时对**更低层**的 box
+  用 `Region::Exclude` 挖洞。实测菜单区与子菜单区的琥珀/绿像素均为 **0**。
+
+### 4. 验证数据
+
+```
+make release / make debug      零 error 零 warning
+TargetCheck.exe                906,752 B（885.5 KiB，< 900 KiB）
+.preflight/lbresid  5/5        toolbar-unchanged-while-scrolling / repaint-same-state-is-identical
+                              / toolbar-restored-by-full-repaint / residual-never-above-plot-area
+                              / later-layer-wins-over-earlier
+   INFO toolbar diff pixels=0；same-state 两帧 settled after 1 extra frame 后逐像素相同
+.preflight/lbzorder 4/4        menu 区 amber=0 green=0；submenu 区 amber=0 green=0
+.preflight/lbcheck  21/21
+uicheck             69/69
+rendercheck 「工具栏带以下」区域哈希 8/8 与上一轮逐一相同 + FUNC 7/7
+```
+
+### 5. 本轮踩到的坑
+
+* `Region::MakeInfinite()` 之后必须 `Intersect` 一个足够大的有限矩形，否则 `Exclude` 的行为
+  在部分 GDI+ 版本上不可预期；这里用 `(-1e5,-1e5) + 2e5 见方`。
+* 给浮层设 `clip = 菜单本体` 会把**展开到本体之外**的二级子菜单整个裁掉
+  （首版就是这样，子菜单一个框都没有）。正确做法是浮层不设 clip，改用它自己登记的 occluder。
+* 探针判定"是否有残留"不能拿"拖拽帧 vs 松开后一帧"直接比：两者渲染路径不同
+  （图层预热进度不同）会得到几十万像素的**合法**差异。正确判据是
+  **同一状态连续两帧必须逐像素相同**。
@@ -439,3 +439,73 @@ uicheck                    69/69
 3. 开关状态仍未持久化。
 4. `TargetCheck.exe` 已接近 900 KiB（889 KiB），`CollectDebugBoxes` 的文字常量与
   `std::to_wstring` 是主要增量；若继续增长需要把标签文本改回静态字面量并去掉动态编号。
+
+---
+
+# 第八阶段报告：调试叠加层的三个真实缺陷（尺寸、残留、层级）
+
+## 1. 症状与真实成因
+
+用户报的三个问题看起来都像"边界画得不好"，实际是**三个互不相干**的缺陷：
+
+| 症状 | 真实成因 |
+| --- | --- |
+| 小元素变成粗描边 | 包角粗细是**固定值**（3–4px），没考虑元素尺寸 |
+| 拖滚动条时"大量绘制残留"，松开并移动鼠标才消失 | ① 我的收集代码读了**位图坐标系**的 `m_decorRects`，生成横跨工具栏的幽灵框；② 绘图区的三条快路径只重画变化区域，而调试线画在最后 ⇒ 旧线残留；③ 组件内越界元素没裁剪 |
+| 右键二级菜单被下层边界线覆盖 | 只有按 `depth` 排序，没有"收集顺序/浮层"概念；且调试线画在内容之后，光是排序并不能阻止露线 |
+
+## 2. 尺寸自适应
+
+以短边为基准推导包角：粗细 `min(4/3, 短边/10)`（再夹到 `[1, 短边/4]`），长度 `min(14, 短边/3)`。
+短边 ≤ 12 只画四个 L 形角标记（不画边），≤ 5 完全不画。于是：
+
+* 15px 复选框 → 1px 角标记，不再"被框住"；
+* 40px 按钮 → 3px 包角 + 1px 边；
+* 200px 区域 → 4px 包角，形状仍是 `⌜ ⌝ ⌞ ⌟`。
+
+文字标签整块删除（含 `UiDebugPaintStyle`）：黑底白字在小元素上必然糊成一片，体积也省 1.5 KB。
+
+## 3. 残留：为什么"松开并移动鼠标"就消失
+
+因为松开鼠标后 `m_dragMode` 回到 `NONE` 且 `m_chromeDirty` 被置位 ⇒ 走**整幅重绘**，
+把上一帧残留的边框像素全部盖掉。这反过来证明残留来自"部分重画 + 叠加层"。
+
+修法分三层：
+1. **不再读位图坐标系的缓存**（`m_decorRects`），消灭幽灵框；
+2. **调试模式强制整幅重绘**（`SetForceFullRepaint`），让每一帧都是完整一帧；
+3. **box 带 `clip`**（组件地盘），组件内越界元素（`lane.rect` 的 Y 可以是负数）
+   不会画到工具栏上。
+
+探针的判据也值得记一笔：不能拿"拖拽帧 vs 松开后一帧"比 —— 两者图层预热进度不同，
+会有几十万像素的**合法**差异。正确判据是**同一状态连续两帧必须逐像素相同**。
+
+## 4. 层级：排序不够，还要挖洞
+
+`layer`（收集顺序）+ `depth`（父子）双排序键解决"两个 box 重叠时谁压谁"。
+但调试线是画在**所有内容之后**的，下层组件的线仍然会显示在不透明菜单上 ——
+于是补上 `AddOccluder()`：菜单/拾色器把本体登记为遮挡矩形，绘制更低层的 box 时
+用 `Region::Exclude` 挖洞。
+
+实测：菜单区与二级子菜单区的琥珀/绿色像素均为 **0**（既没有下层行边框，也没有被裁破的包角）。
+
+## 5. 顺带修掉的东西
+
+* 浮层**不能**用"本体矩形"当 clip：二级子菜单会展开到本体之外，会被整个裁掉
+  （首版就踩了这个坑，子菜单一个框都没有）。
+* `Render` 的 `fullChrome` 并入 `m_showLayoutBounds`，装饰区也保证完整一帧。
+
+## 6. 验证
+
+```
+lbresid  5/5   （工具栏恒等、同状态两帧恒等、差异不越过绘图区上沿、层序正确）
+lbzorder 4/4   （菜单与子菜单区内 0 个下层颜色）
+lbcheck  21/21 ；uicheck 69/69 ；rendercheck 区域哈希 8/8 不变 + FUNC 7/7
+零 warning；TargetCheck.exe 906,752 B（885.5 KiB）
+```
+
+## 7. 遗留
+
+1. 调试模式下强制整幅重绘：283 个网格时帧率明显下降 —— 这是**有意的取舍**
+   （调试而非日常使用），但若将来要让边界常驻，需要改为"只把叠加层位图化再贴回"。
+2. 菜单项逐个画框略显拥挤，可选做"只画外框 + 悬停项高亮框"。
+3. 开关状态仍未持久化。
@@ -3031,6 +3031,8 @@ else if (panelOnly) { /* 只回送“本帧重绘过的区域并集” */ }

 | 2026-10-28 | DeepSeek-V4.1-Flash（**UI_Refactor 分支**） | **布局边界观感重做（四角粗/四边细）+ 全覆盖 + 几何同源（详见 §12 末尾「2026-10-28 第九轮」）**。① **描边规则改了**：四条边固定 **1 设备像素**，四个角加粗（层级 0 = 4px、其余 3px，沿边延伸 ≤14px 且 ≤ 短边一半），层级 > 0 整体**内缩 1px**（父子共边不再叠粗），**绝不填充**；整像素对齐 + `PixelOffsetModeNone` + 关抗锯齿。② **协议改为「收集 → 统一绘制」**：`UiComponent::CollectDebugBoxes(UiDebugBoxList&)`（默认只登记 `Area()`）+ `UiWidget::CollectDebugBoxes(boxes, depth)` 递归控件树；**不要**改成"所有元素继承同一基类"（会与 `PlotView` 4 层缓存 / `SignalPanel` 行位图缓存的失效体系打架）。③ **覆盖补齐**：`Toolbar` 按钮内容（新增 `UiButtonWidget::ContentRect()`）、`TabBar` ✕、`SignalPanel` 每个可见行的折起三角/复选框/色块/名称/GX 徽标/✕（组行另有组名/计数）+ 筛选框/清空✕/滚动轨道与滑块/样式 5 行与 12 色块/3 模式/3 调整/线宽与透明度轨道和数值/目标行/编辑框、`PlotView` GX 徽标/装饰层矩形/图例托底+色块+文本/**5 类浮动面板全部 20+ 字段**、`PopupMenu` 条目/可视区/轨道/滑块/二级子菜单、`ColorPickerPopup` 各控件。标签设**尺寸门槛**（< 56×16 逻辑像素不画）避免糊字。④ **性能**：`RowRect` 曾是 O(row) 逐行累加且画一行调 5 次 ⇒ 改用 `m_rowTop` 前缀和（`UpdateAnimGeometry()` 重建，长度不一致时退回累加）⇒ O(1)；`ContentOffsetBeforeRow` 同步；`PanelBounds()` 收敛 6 处重复三元式。⑤ **齿轮按钮改主按钮配色**（与「导入文件」一致），图标重画（齿占最外一圈 0.66R→1.0R、外环 0.54R，否则齿被环描边吃掉只剩甜甜圈）。验证：`lbcheck` 21/21（含关闭后逐像素还原）、`rendercheck` 「工具栏带以下」区域哈希 **8/8 与上一轮逐一相同** + FUNC 7/7、`uicheck` 69/69、零警告、`TargetCheck.exe` **910,336 字节（889 KiB）**。 |

+| 2026-10-28 | DeepSeek-V4.1-Flash（**UI_Refactor 分支**） | **布局边界自适应 + 绘制残留与层级缺陷修复（详见 §12 末尾「2026-10-28 第十轮」）**。① **描边按短边自适应**（取代第九轮固定包角）：四边固定 1px；包角粗细 `min(4/3, 短边/10)` 夹到 `[1, 短边/4]`；包角长度 `min(14, 短边/3)`；**短边 ≤ 12 只画 L 形角标记不画边、≤ 5 完全不画**；内缩仅层级 > 0 且短边 ≥ 10。文字标签**整体删除**（含 `UiDebugPaintStyle`，省 ~1.5KB）。② **绘制残留三个成因**：(a) `PlotView::CollectDebugBoxes` 误读 `m_decorRects`（位图坐标系，负 Y）⇒ 横跨工具栏的幽灵巨框，改为只用 `LaneBadgeRect`/`m_legendHits`；(b) `Paint` 三条快路径只重画变化区域而调试线画在最后 ⇒ 新增 `PlotView::SetForceFullRepaint(bool)`，开启边界时禁用全部快路径；(c) 组件内元素越界（`lane.rect` Y 为负）⇒ box 增加 `clip`（宿主按 `Area()` 设置，`Add()` 跳过无交集、绘制时求交）。`Render` 的 `fullChrome` 并入 `m_showLayoutBounds`。③ **层级**：`UiDebugBoxList::PushLayer()` + 按 `(layer, depth)` 稳定排序；⚠️ 仅排序不够（调试线在所有内容之后），新增 `AddOccluder()` 让菜单/拾色器把本体登记为遮挡矩形，绘制更低层 box 时用 `Region::Exclude` 挖洞；⚠️ 浮层不要设 `clip=本体`（会把展开到本体外的二级子菜单整个裁掉）。④ **验证方法论**：判断残留不能用"拖拽帧 vs 松开后一帧"（图层预热进度不同会产生几十万像素合法差异），正确判据是**同一状态连续两帧逐像素相同**。新增探针 `.preflight/lbresid`（5/5）与 `.preflight/lbzorder`（4/4）；`lbcheck` 21/21、`uicheck` 69/69、`rendercheck` 区域哈希 8/8 不变 + FUNC 7/7；零 warning；`TargetCheck.exe` **906,752 字节（885.5 KiB）**。 |
+
 ## 11. 跨设备协作须知（起源设备视角）

 > **本文件是唯一权威记忆**。所有设备 / Agent 共用它，**不要再新建 `agent_mem_origin.md` 等旁支记忆文件**。
@@ -8129,3 +8131,67 @@ rendercheck 「工具栏带以下」区域哈希 8/8 与上一轮逐一相同 +
  文件里的闭括号带前导缩进，用 `TrimEnd()` 会越界（`InvokeMethodOnNull`）且**开头已被删掉**，
  要在替换后逐个核对括号配对。
 * 中文不能写进 `.ps1`（PS 5.1 按 GBK 读）⇒ 文本块落 UTF-8 数据文件、脚本保持纯 ASCII。
+
+---
+
+## 本轮（2026-10-28 第十轮，本机）：布局边界自适应 + 绘制残留与层级缺陷修复
+
+### 1. 描边规则（**现行，取代第九轮的固定包角**）
+
+以**短边**为基准，不再用固定 3–4px 包角：
+
+| 量 | 规则 |
+| --- | --- |
+| 四边 | 固定 1 设备像素 |
+| 包角粗细 | `min(4(层级0)/3(其余), 短边/10)`，夹到 `[1, 短边/4]` |
+| 包角长度 | `min(14, 短边/3)`，且 ≥ 包角粗细 |
+| 短边 ≤ 12 | **只画四个 L 形角标记、不画边** |
+| 短边 ≤ 5 | 完全不画 |
+| 内缩 | 仅层级 > 0 **且短边 ≥ 10** |
+
+文字标签已**整体删除**（含 `UiDebugPaintStyle`）：黑底白字在小元素上必糊，且省 ~1.5 KB。
+
+### 2. 调试叠加层的三条硬约束（血泪）
+
+1. **绝不读位图坐标系的缓存**：`m_decorRects` 是装饰层位图缓存的登记矩形（负 Y / 超出绘图区），
+   拿它当屏幕矩形会出现横跨工具栏的幽灵巨框。屏幕几何请用 `LaneBadgeRect` / `m_legendHits`。
+2. **调试开启时必须强制整幅重绘**：`PlotView::SetForceFullRepaint(true)` 关掉三条快路径
+   （静态场景贴图 / 宽基底贴图 / 样式补丁），否则局部重画会让上一帧的边框残留
+   （症状：拖网格滚动条时工具栏与网格区域出现大量残留，松开并移动鼠标才消失）。
+3. **box 必须带 `clip`（组件地盘）**：组件内元素可能越界（滚出可视区的 `lane.rect` Y 为负），
+   宿主按 `Area()` 设置裁剪，`Add()` 跳过无交集、绘制时求交。
+
+### 3. 层级：排序 + 挖洞
+
+* `UiDebugBoxList::PushLayer()`：宿主每收集完一个组件 +1（菜单/拾色器最后）。
+  绘制按 `(layer, depth)` 稳定排序 ⇒ 后收集的压住先收集的。
+* ⚠️ 仅排序**不够**：调试线画在所有内容之后，下层组件的线仍会显示在不透明菜单上。
+  因此 `AddOccluder()`：菜单/拾色器登记本体为遮挡矩形，绘制**更低层** box 时用
+  `Region::Exclude` 挖洞。实测菜单区 / 子菜单区下层颜色像素 = **0**。
+* ⚠️ 浮层**不要**设 `clip = 本体矩形`：二级子菜单会展开到本体之外，会被整个裁掉
+  （改用它自己登记的 occluder）。
+
+### 4. 验证
+
+```
+lbresid  5/5  toolbar-unchanged-while-scrolling / repaint-same-state-is-identical
+              / toolbar-restored-by-full-repaint / residual-never-above-plot-area
+              / later-layer-wins-over-earlier
+lbzorder 4/4  menu & submenu：amber=0 green=0
+lbcheck  21/21 ；uicheck 69/69；rendercheck 区域哈希 8/8 不变 + FUNC 7/7
+零 warning；TargetCheck.exe 906,752 B（885.5 KiB）
+```
+
+### 5. 验证方法论（重要）
+
+判断"是否有绘制残留"**不能**用"拖拽帧 vs 松开后一帧"：两者图层预热进度不同，
+会产生几十万像素的**合法**差异。正确判据是 **同一状态连续两帧必须逐像素相同**
+（探针里先跑若干帧直到收敛，再比较相邻两帧）。
+
+### 6. 新增探针
+
+* `.preflight/lbresid`：MF4-Record.MF4 / 283 网格 / 拖滚动条，5 条断言 + BMP 落盘。
+* `.preflight/lbzorder`：打开网格右键菜单与「实验性功能」子菜单，检查浮层区内无下层颜色。
+
+两个探针都在 `.preflight/`（已被 gitignore），需在 `make release TARGET_FILE_NAME=TargetCheck`
+之后用各自的 `build.ps1` 构建。