fix(UI): 浮层不再被下层边界穿透 + 菜单条目裁剪 + 修正性能误判

## 0. 仓库同步

远端 gitea 已把 UI_Refactor 合入 main（PR #1，合并提交 322b658，分支保留）。
main 与 UI_Refactor 均同步到该提交；dev 分支远端从未存在（意外产物），本地已删除。

## 1. 修正上一轮的性能误判（重要）

上一轮报告称「PlotView 基线每帧在 WarmLaneLayersStep 上多花约 2.4ms」。本轮用两级计时查证，
该结论是错的：

  排空前 idle      2.60 ms   ← 含"图层预热队列排空"的瞬时成本
  排空后 idle      0.53 ms   ← 真正的稳态
  强制整帧 idle    0.46 ms

那 2.4ms 是载入 283 个网格后给 16 个网格补建宽基底图层的**瞬时**开销（每帧补 1 个，约 16 帧结束），
属于设计内的预热，不存在每帧白烧的固定成本。

仍修掉顺带发现的一处顺序问题：RollWideBuffer 原来对全部 283 个网格先算 LaneLayerKey()
（逐网格内容哈希 ≈0.7ms/帧）再判断可视性，且离屏网格的"结构不可用"分支会逐帧把它们塞进
待重画队列再被清掉。现在把 LaneVisuallyRelevant 判断提到循环最前面（见函数内注释）。

## 2. 浮动面板被网格边界穿透（层级 + 挖洞 + 裁剪）

根因：PlotView::CollectDebugBoxes 把网格盒子与面板盒子放在同一绘制层，只靠 depth 排序；
而调试线画在所有内容之后，"后画"只决定谁压谁，不能阻止下层组件的线仍然可见。

修复三步：
- 收集面板前 boxes.PushLayer() ⇒ 面板层高于网格层；
- 每个面板 boxes.AddOccluder(layout.panel) ⇒ 绘制更低层盒子时用 Region::Exclude 挖洞；
- boxes.SetClip(layout.panel) ⇒ 面板内部元素（如滚出内容区的行）不再登记到面板外。

## 3. 滚动时面板/菜单边界闪烁或溢出

滚动容器里的条目矩形始终存在，只是绘制时被裁剪掉；调试层读到这些矩形就会给"看不见的内容"画框，
滚动时条目不断进出可视区，框也就不断出现/消失 ⇒ 闪烁 / "边界超出菜单"。

- 面板内容裁到 layout.panel；
- 菜单条目裁到 m_scrollEnabled ? m_scrollViewport : m_rect；二级子菜单条目裁到 m_subRect。

## 4. 顺带小优化

EdgePanelLayoutFor 单次约 2~3µs，283 网格 × 5 类 = 1415 次/帧。现在先看该网格的 5 个面板
open 标志，全关就跳过内层循环。

## 5. 验证

- make release / make debug 零 error 零 warning；TargetCheck.exe 909,824 B（888.5 KiB < 900 KiB）。
- 新增探针 .preflight/lbpanel 10/10：
  panel-open / panel-contents-clipped-to-panel / panel-registered-as-occluder /
  no-lane-bounds-inside-panel（面板内网格层颜色像素=0）/ scrolling-actually-happened
  （真滚动 0.0→1295.1）/ panel-boxes-stable-while-scrolling（11/11 帧签名一致）/
  menu-open-scrollable / no-box-escapes-menu / scrolled-out-items-not-collected。
- 回归：lbcovr 7/7、lbzorder 4/4、lbresid 5/5、lbcheck 21/21、uicheck 69/69。
- rendercheck：8 个场景哈希与上一轮**逐一相同** + FUNC 7/7（本轮不应改变任何正常绘制像素）。

## 6. 文档

Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第十阶段；
Documents/agent_mem.md 同步变更日志与「2026-10-29 第十二轮」的结论修正、浮层三件事、踩坑。

Documents/UI_Refactor_Report.md

@@ -595,3 +595,70 @@ TargetCheck.exe：909,824 B（888.5 KiB）
 2. 文本墨迹矩形是"字符单元"高度，不含下伸部（descender）的差异；对除 `g/y/p` 多的文本
    会略微偏扁，属可接受近似。
 3. `PlotView` 的坐标轴刻度带仍未单独上报（只上报整条 `m_timeAxisRect`）。
+
+---
+
+# 第十阶段报告：把"层级"变成一条可验证的规则
+
+## 1. 先说清楚"既有性能问题"到底是什么
+
+上一轮报告里我写了"`PlotView` 基线每帧在 `WarmLaneLayersStep()` 上花约 2.4ms"。
+本轮用更细的探针查证，**这个结论是错的**：
+
+```
+排空前 idle      2.60 ms   ← 这里包含"图层预热队列排空"的瞬时成本
+排空后 idle      0.53 ms   ← 真正的稳态
+强制整帧 idle    0.46 ms
+```
+
+也就是说**没有**每帧白烧 2.4ms；那 2.4ms 是"载入 283 个网格后，需要给 16 个网格补建宽基底图层"
+的瞬时开销（每帧补 1 个，1~3ms/帧，约 16 帧结束）。这属于设计内的预热。
+
+不过顺着这条线**确实**找到一处顺序问题：`RollWideBuffer` 先给**所有**网格算内容指纹
+（`LaneLayerKey()`，283 次 ≈ 0.7ms/帧），然后才判断"这个网格是否可视、不视则跳过"；
+而且离屏网格的"结构不可用"分支会**逐帧**把它们塞进待重画队列，再在同一帧被 `remove_if` 清掉。
+把可视性判断提到循环最前之后，离屏网格既不哈希也不入队。
+
+**教训**：性能结论必须先区分"稳态"与"瞬时"，否则会把预热成本误判成常态浪费。
+
+## 2. "浮层不能被下层覆盖"需要两件事，不是一件
+
+用户先后两次报告同一类现象（面板被网格边界穿透、菜单边界溢出），根源都在**分层只有一半**：
+
+| 机制 | 作用 | 只有它够吗 |
+| --- | --- | --- |
+| `layer`（`PushLayer`）+ 按 `(layer, depth)` 排序 | 决定**两个盒子重叠时谁压谁** | ❌ 不够 |
+| `AddOccluder` + `Region::Exclude` | 让**更低层的盒子整体不进入浮层区域** | ❌ 单独也不够（还需要层号） |
+| `SetClip` | 让**滚动容器里滚出的条目不再登记/绘制** | 解决"溢出/闪烁" |
+
+本轮把这三件事在浮动面板上补齐（菜单在上一轮已有 occluder，本轮补 clip）。
+
+## 3. 为什么"滚动时闪烁"
+
+滚动容器（面板内容区 / 菜单条目区）的条目矩形**始终存在**，只是绘制时被裁剪掉。
+调试层读到这些矩形就会给"看不见的内容"画框 —— 而滚动时条目不断进出可视区，
+框也就不断出现/消失，看上去就是闪烁。修法与菜单一致：登记盒子时把裁剪矩形设为可视区。
+
+实测：面板层 escaped=0、菜单层 belowViewport=0、面板内网格层颜色像素=0，
+且真滚动 1295px 的过程中"面板盒子签名"11/11 帧完全一致。
+
+## 4. 顺带的一处小优化
+
+`EdgePanelLayoutFor` 单次约 2~3µs，283 网格 × 5 类 = 1415 次/帧。现在先看该网格的
+5 个面板 `open` 标志，全关就跳过整个内层循环。
+
+## 5. 数据
+
+```
+零 warning；TargetCheck.exe 909,824 B（888.5 KiB）
+lbpanel 10/10（新增）· lbcovr 7/7 · lbzorder 4/4 · lbresid 5/5 · lbcheck 21/21 · uicheck 69/69
+rendercheck 8 场景哈希与上一轮逐一相同 + FUNC 7/7
+```
+
+## 6. 仍然存在的近似
+
+* 面板层的层号只比网格高 1，而**文本盒子**固定在 layer 2 收集。因此面板**自己的**文字框
+  能正常显示，但理论上"图例文字"若与面板重叠仍会画在面板上。实际布局下两者不重叠。
+  若要彻底消除，需要让文本收集器在"面板绘制期间"使用面板层的层号。
+* 菜单/面板的条目裁剪用的是"可视区矩形"，因此**与边界部分相交的那一条**仍会被登记并裁剪绘制
+  （这是期望行为：它确实可见）。