UI 重构 P3：Toolbar 迁移到控件树（新增 UiButtonWidget，逐像素 0 差异 + 功能断言）

新增 Components/Shared/{Inc,Src}/UiButtonWidget.*：通用「文字按钮」控件，视觉规则与旧 Toolbar
按钮逐像素一致（主按钮强调色实底 / 普通按钮 1px 描边 / 可切换选中态 / 禁用态配色）；
交互由控件自己处理：按下即 CaptureMouse 进入按下态，在自身范围内松开才触发 onClick，
指针离开（不会再收到抬起）时 CancelPress。

Toolbar 内部重写，公开 API 一字未改：
- Button 只保留静态配置 + 控件指针；矩形与外观状态归控件。
- 删除 m_hoverIndex / m_pressedIndex 与死字段 Button::hover，改由 UiWidget 的悬停链与 capture 维护。
- Paint 改为「根控件（底色 + 底部分隔线）+ 按钮子节点」，一次 root->Paint(ctx)。
- OnMouseMove/Down/Up/Leave 统一翻译成 UiEvent 后 root->Dispatch；动作经 onClick 回调登记、抬起后执行。

框架约定调整：UiWidget::Paint 的裁剪从「严格等于自身矩形」改为「自身矩形外扩 1px（kUiClipBleed）」。
边框/描边以矩形边界为中心绘制，严格裁剪会切掉外半侧使控件变细、与旧绘制不再像素一致。
uicheck 对应断言改为「裁剪 ⊇ 自身矩形且不超出外扩范围」。

验证：
- make release / make debug 零警告；Target.exe 881,664 B（< 900KB）。
- 逐像素 A/B（8 场景：全览 / 深放大+自由标记+滤波+弱峰+光标 / 平移 / 悬停按钮 / 按下 / 松开 /
  悬停主按钮 / 移出工具栏）：迁移前后哈希逐一相同
  A 2166933039626F66 B C444ECFEB18FD73D C 7984446D8E7A4418 D BF855879CA12F289
  E 1C663E4118616016 F 0535292D8E07AE18 G 7A58172C46577729 H 23F390DD76141113。
- 功能断言：locate-cursor-button PASS (1291,73)；click-cursor-changes-mode PASS (1 -> 2)；
  release-outside-does-not-fire PASS (2 -> 2)。
- Tools/uicheck 62 passed / 0 failed。

Components/Shared/Inc/UiButtonWidget.hpp

@@ -0,0 +1,84 @@
+#ifndef __UI_BUTTON_WIDGET_HPP__
+#define __UI_BUTTON_WIDGET_HPP__
+
+#include <functional>
+#include <string>
+
+#include "UiWidget.hpp"
+
+namespace jdi
+{
+
+	/**
+	 * @brief 一个"文字按钮"控件（工具栏按钮的原语）。
+	 *
+	 * 视觉规则与旧 `Toolbar` 的按钮**逐像素一致**：
+	 * * 主按钮（`primary`）= 强调色实底 + `textOnAccent` 文字，按下 / 悬停时整体提亮或压暗；
+	 * * 普通按钮 = 透明底 + 1px 描边，可切换按钮选中时用 `accentSoft` 底 + `accent` 描边；
+	 * * 禁用时底色回退为工具栏底色、文字用 `textMuted`、描边与底色混 50%。
+	 *
+	 * 交互：按下即 `CaptureMouse()` 并进入按下态；**在自身范围内**松开才触发 `onClick`
+	 *（与"按住移开再松开 = 放弃"的既有语义一致）。
+	 */
+	class UiButtonWidget : public UiWidget
+	{
+	public:
+		UiButtonWidget() = default;
+
+		/** @brief 一次性注入绘制资源与外观参数（尺寸由 `OnMeasure` 按文本实测得出）。 */
+		void Configure(const UiFonts* fonts, const Theme* theme, float scale, std::wstring label,
+		               bool primary, bool toggle, float textPadding, float height);
+
+		/** @brief 修改文本（宽度会在下一次 `InvalidateMeasure` 后重新实测）。 */
+		void SetLabel(std::wstring label);
+		/** @brief 文本（只读）。 */
+		const std::wstring& Label() const { return m_label; }
+
+		/** @brief 设置可切换按钮的选中态。 */
+		void SetChecked(bool checked);
+		/** @brief 选中态。 */
+		bool Checked() const { return m_checked; }
+		/** @brief 是否可切换按钮。 */
+		bool IsToggle() const { return m_toggle; }
+
+		/** @brief 设置可用性（禁用时不可点、不可命中）。 */
+		void SetEnabled(bool enabled);
+		/** @brief 是否可用。 */
+		bool Enabled() const { return m_enabled; }
+		/** @brief 是否处于按下态（按下未松开）。 */
+		bool Pressed() const { return m_pressed; }
+
+		/** @brief 放弃当前按下（指针离开窗口等不会再收到抬起的情形）。 */
+		void CancelPress();
+
+		/** @brief 点击回调（在自身范围内松开时触发）。 */
+		std::function<void()> onClick;
+
+		/** @brief 工具栏底色（普通按钮的底色与禁用配色都以它为基准）。 */
+		void SetCanvasColor(std::uint32_t color) { m_canvasColor = color; }
+
+	protected:
+		gd::SizeF OnMeasure(const UiMeasureContext& ctx) override;
+		void OnPaint(UiPaintContext& ctx) override;
+		UiEventResult OnEvent(UiEvent& event) override;
+		HCURSOR OnQueryCursor(int x, int y) override;
+		std::uint64_t ContentKey() const override;
+
+	private:
+		const UiFonts* m_fonts = nullptr;		/**< 字体。 */
+		const Theme* m_theme = nullptr;			/**< 主题。 */
+		float m_scale = 1.0f;					/**< 缩放系数。 */
+		std::wstring m_label;					/**< 按钮文本。 */
+		bool m_primary = false;					/**< 主按钮（强调色实底）。 */
+		bool m_toggle = false;					/**< 是否可切换。 */
+		bool m_checked = false;					/**< 可切换按钮的选中态。 */
+		bool m_enabled = true;					/**< 是否可用。 */
+		bool m_pressed = false;					/**< 按下态。 */
+		float m_textPadding = 14.0f;			/**< 左右内边距（逻辑像素）。 */
+		float m_height = 30.0f;					/**< 按钮高度（逻辑像素）。 */
+		std::uint32_t m_canvasColor = 0;		/**< 工具栏底色（配色基准）。 */
+	};
+
+} // namespace jdi
+
+#endif // __UI_BUTTON_WIDGET_HPP__

Components/Shared/Inc/UiLayout.hpp

@@ -75,6 +75,9 @@ namespace jdi
 	/** @brief 内缩（结果可能为空矩形）。 */
 	gd::RectF UiRectDeflate(const gd::RectF& rect, const UiInsets& insets);
 
+	/** @brief 四边外扩（用于“描边允许超出自身矩形”的裁剪补偿）。 */
+	gd::RectF UiRectInflate(const gd::RectF& rect, float amount);
+
 	/**
 	 * @brief 把矩形对齐到**设备像素整数边界**（上界 `floor`、下界 `ceil`）。
 	 *

Components/Shared/Inc/UiWidget.hpp

@@ -18,6 +18,15 @@ namespace jdi
 	struct Theme;
 	struct UiFonts;
 
+	/**
+	 * @brief 裁剪时允许超出控件矩形的像素数（逻辑像素 × scale）。
+	 *
+	 * 边框/描边以矩形边界为中心绘制（1px 笔宽有一半在矩形外），若严格按矩形裁剪
+	 * 会把外半侧切掉（控件看起来变细）。因此裁剪区固定外扩这么多。
+	 * ⚠️ 它只用于**限制控件画到哪**，不参与脏区判定（脏区始终是精确矩形）。
+	 */
+	constexpr float kUiClipBleed = 1.0f;
+
 	/**
 	 * @brief 布局测量上下文（由根节点统一下发，子节点只读）。
 	 */
@@ -233,6 +242,8 @@ namespace jdi
 
 		/** @brief 当前悬停的控件（根节点维护）。 */
 		UiWidget* HoverWidget() const;
+		/** @brief 本控件当前是否被悬停（由根节点的悬停链维护）。 */
+		bool Hovered() const { return m_hovered; }
 
 		/** @brief 请求键盘焦点（根节点记录；键盘/字符事件沿焦点链派发）。 */
 		void RequestFocus();
@@ -314,6 +325,7 @@ namespace jdi
 		bool m_visible = true;								/**< 是否可见。 */
 		bool m_hitTransparent = false;						/**< 是否命中透明。 */
 		bool m_measureValid = false;						/**< 期望尺寸是否有效。 */
+		bool m_hovered = false;								/**< 是否被悬停（悬停链写入）。 */
 
 		// 根节点专用状态。
 		UiWidget* m_capture = nullptr;						/**< 鼠标捕获者。 */

Components/Shared/Src/UiButtonWidget.cpp

@@ -0,0 +1,231 @@
+#include "UiButtonWidget.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+#include "PaintUtil.hpp"
+#include "Theme.hpp"
+
+namespace jdi
+{
+
+	namespace
+	{
+		const float kButtonRadius = 5.0f;		/**< 按钮圆角半径（逻辑像素）。 */
+
+		/** @brief 按比例把一个颜色向目标色混合（与旧 Toolbar 的写法保持一致）。 */
+		std::uint32_t BlendToward(std::uint32_t base, std::uint32_t target, double ratio)
+		{
+			return MixColor(base, target, ratio);
+		}
+	}
+
+	void UiButtonWidget::Configure(const UiFonts* fonts, const Theme* theme, float scale,
+	                              std::wstring label, bool primary, bool toggle, float textPadding,
+	                              float height)
+	{
+		m_fonts = fonts;
+		m_theme = theme;
+		m_scale = (scale > 0.1f) ? scale : 1.0f;
+		m_label = std::move(label);
+		m_primary = primary;
+		m_toggle = toggle;
+		m_textPadding = textPadding;
+		m_height = height;
+		InvalidateMeasure();
+		Invalidate(Bounds());
+	}
+
+	void UiButtonWidget::SetLabel(std::wstring label)
+	{
+		if (m_label == label)
+		{
+			return;
+		}
+		m_label = std::move(label);
+		InvalidateMeasure();
+		Invalidate(Bounds());
+	}
+
+	void UiButtonWidget::SetChecked(bool checked)
+	{
+		if (m_checked == checked)
+		{
+			return;
+		}
+		m_checked = checked;
+		Invalidate(Bounds());
+	}
+
+	void UiButtonWidget::SetEnabled(bool enabled)
+	{
+		if (m_enabled == enabled)
+		{
+			return;
+		}
+		m_enabled = enabled;
+		Invalidate(Bounds());
+	}
+
+	void UiButtonWidget::CancelPress()
+	{
+		if (!m_pressed)
+		{
+			return;
+		}
+		m_pressed = false;
+		ReleaseMouse();
+		Invalidate(Bounds());
+	}
+
+	gd::SizeF UiButtonWidget::OnMeasure(const UiMeasureContext& ctx)
+	{
+		const float scale = (ctx.scale > 0.1f) ? ctx.scale : m_scale;
+		const float width = (m_fonts != nullptr && m_fonts->ui != nullptr)
+		                        ? (m_textPadding * 2.0f * scale + UiMeasureTextWidth(m_fonts->ui, m_label))
+		                        : 0.0f;
+		return gd::SizeF(width, m_height * scale);
+	}
+
+	void UiButtonWidget::OnPaint(UiPaintContext& ctx)
+	{
+		if (m_theme == nullptr || m_fonts == nullptr || ctx.g == nullptr)
+		{
+			return;
+		}
+		const gd::RectF& rect = Bounds();
+		const bool hovered = Hovered();
+		const bool enabled = m_enabled;
+		std::uint32_t background = 0;
+		std::uint32_t border = 0;
+		std::uint32_t textColor = 0;
+
+		if (m_primary)
+		{
+			background = enabled ? m_theme->accent
+			                     : BlendToward(m_theme->accent, m_canvasColor, 0.6);
+			if (m_pressed)
+			{
+				background = BlendToward(m_theme->accent, 0xFF000000u, 0.12);
+			}
+			else if (enabled && hovered)
+			{
+				background = BlendToward(m_theme->accent, 0xFFFFFFFFu, 0.12);
+			}
+			border = background;
+			textColor = m_theme->textOnAccent;
+		}
+		else
+		{
+			background = (m_toggle && m_checked) ? m_theme->accentSoft : m_canvasColor;
+			if (m_pressed)
+			{
+				background = m_theme->pressed;
+			}
+			else if (enabled && hovered)
+			{
+				background = (m_toggle && m_checked)
+				                 ? BlendToward(m_theme->accentSoft, m_theme->accent, 0.16)
+				                 : m_theme->hover;
+			}
+			if (!enabled)
+			{
+				background = m_canvasColor;
+			}
+
+			if (m_toggle && m_checked && enabled)
+			{
+				border = m_theme->accent;
+			}
+			else
+			{
+				border = BlendToward(m_theme->border, m_canvasColor, enabled ? 0.0 : 0.5);
+			}
+			textColor = enabled ? ((m_toggle && m_checked) ? m_theme->textStrong : m_theme->text)
+			                    : m_theme->textMuted;
+		}
+
+		if (background != m_canvasColor)
+		{
+			UiFillRoundRect(*ctx.g, rect, kButtonRadius * m_scale, background);
+		}
+		if (!m_primary)
+		{
+			UiDrawRoundRect(*ctx.g, rect, kButtonRadius * m_scale, border, 1.0f);
+		}
+
+		// ⚠️ 与旧实现一致：文字走 `UiText`（GDI，不受 GDI+ 裁剪约束）。
+		// 按钮矩形本身就在裁剪区内（外扩 1px 只影响描边），因此不需要 `UiTextClipped`。
+		UiText(*ctx.g, m_label, m_fonts->ui, rect, textColor, TextAlign::CENTER);
+	}
+
+	UiEventResult UiButtonWidget::OnEvent(UiEvent& event)
+	{
+		switch (event.kind)
+		{
+		case UiEventKind::MOUSE_DOWN:
+			if (event.button != UiMouseButton::LEFT || !m_enabled)
+			{
+				return UiEventResult();
+			}
+			m_pressed = true;
+			CaptureMouse();
+			{
+				UiEventResult result = UiEventResult::Handled();
+				result.dirty = Bounds();
+				return result;
+			}
+		case UiEventKind::MOUSE_UP:
+			if (event.button != UiMouseButton::LEFT || !m_pressed)
+			{
+				return UiEventResult();
+			}
+			// 只有"在自身范围内松开"才算点击（按住移开再松开 = 放弃）。
+			m_pressed = false;
+			ReleaseMouse();
+			{
+				UiEventResult result = UiEventResult::Handled();
+				result.dirty = Bounds();
+				if (Contains(event.x, event.y) && m_enabled && onClick)
+				{
+					onClick();
+				}
+				return result;
+			}
+		case UiEventKind::MOUSE_LEAVE:
+			if (m_pressed)
+			{
+				m_pressed = false;
+				ReleaseMouse();
+				UiEventResult result = UiEventResult::Handled();
+				result.dirty = Bounds();
+				return result;
+			}
+			return UiEventResult();
+		default:
+			return UiEventResult();
+		}
+	}
+
+	HCURSOR UiButtonWidget::OnQueryCursor(int x, int y)
+	{
+		(void)x;
+		(void)y;
+		// 与旧实现一致：工具栏按钮不改变光标形态（箭头）。
+		return nullptr;
+	}
+
+	std::uint64_t UiButtonWidget::ContentKey() const
+	{
+		std::uint64_t key = BaseContentKey();
+		key = UiMixKey(key, static_cast<std::uint64_t>(m_label.size()));
+		key = UiMixKey(key, m_primary ? 1u : 0u);
+		key = UiMixKey(key, m_toggle ? 1u : 0u);
+		key = UiMixKey(key, m_checked ? 1u : 0u);
+		key = UiMixKey(key, m_enabled ? 1u : 0u);
+		key = UiMixKey(key, m_pressed ? 1u : 0u);
+		key = UiMixKey(key, Hovered() ? 1u : 0u);
+		return key;
+	}
+
+} // namespace jdi

Components/Shared/Src/UiLayout.cpp

@@ -89,6 +89,16 @@ namespace jdi
 		return gd::RectF(rect.X + insets.left, rect.Y + insets.top, width, height);
 	}
 
+	gd::RectF UiRectInflate(const gd::RectF& rect, float amount)
+	{
+		if (!UiRectHasArea(rect) || amount <= 0.0f)
+		{
+			return rect;
+		}
+		return gd::RectF(rect.X - amount, rect.Y - amount, rect.Width + amount * 2.0f,
+		                 rect.Height + amount * 2.0f);
+	}
+
 	gd::RectF UiRectSnapInward(const gd::RectF& rect, float scale)
 	{
 		const float safeScale = (scale > 0.0f) ? scale : 1.0f;

Components/Shared/Src/UiWidget.cpp

@@ -195,10 +195,13 @@ namespace jdi
 			return;
 		}
 
-		// (2) 裁剪 = 祖先裁剪切 ∩ 自身矩形；脏区非空时再与脏区求交（只更新需要更新的部分）。
+		// (2) 裁剪 = 祖先裁剪切 ∩ （自身矩形外扩 1px）；脏区非空时再与脏区求交。
+		//     ⚠️ 外扩 1px 是刻意设计的：边框/描边是**以矩形边界为中心**画的（`UiDrawRoundRect`
+		//     的 1px 笔宽有一半在矩形外），严格按矩形裁剪会把外半侧切掉 ⇒ 控件看起来变细。
+		//     这是与旧绘制代码保持“逐像素一致”的必要保证。
 		UiPaintContext local = ctx;
 		gd::RectF clip;
-		if (!UiRectIntersect(ctx.clip, m_bounds, clip))
+		if (!UiRectIntersect(ctx.clip, UiRectInflate(m_bounds, kUiClipBleed), clip))
 		{
 			return;		// 完全被祖先裁掉
 		}
@@ -230,7 +233,13 @@ namespace jdi
 			{
 				continue;
 			}
-			UiPaintContext childContext = local.WithClip(child->m_bounds);
+			UiPaintContext childContext = local;
+			gd::RectF childClip;
+			if (!UiRectIntersect(local.clip, UiRectInflate(child->m_bounds, kUiClipBleed), childClip))
+			{
+				continue;
+			}
+			childContext.clip = childClip;
 			childContext.dirty = local.dirty;
 			child->Paint(childContext);
 		}
@@ -465,11 +474,13 @@ namespace jdi
 		m_hover = target;
 		if (previous != nullptr)
 		{
+			previous->m_hovered = false;
 			previous->OnHoverChanged(false);
 			previous->Invalidate(previous->m_bounds);
 		}
 		if (target != nullptr)
 		{
+			target->m_hovered = true;
 			target->OnHoverChanged(true);
 			target->Invalidate(target->m_bounds);
 		}

Components/Toolbar/Inc/Toolbar.hpp

@@ -5,11 +5,15 @@
 #include <objidl.h>
 #include <gdiplus.h>
 
+#include <memory>
 #include <string>
+#include <utility>
 #include <vector>
 
 #include "PaintUtil.hpp"
 #include "Theme.hpp"
+#include "UiButtonWidget.hpp"
+#include "UiWidget.hpp"
 
 namespace jdi
 {
@@ -37,6 +41,7 @@ namespace jdi
 	{
 	public:
 		Toolbar();
+		~Toolbar();
 
 		/**
 		 * @brief 绑定字体与主题资源。
@@ -135,19 +140,17 @@ namespace jdi
 
 	private:
 		/**
-		 * @brief 单个工具栏按钮的运行时状态。
+		 * @brief 单个工具栏按钮的**静态配置**（矩形与外观状态由控件自己维护）。
 		 */
 		struct Button
 		{
 			ToolbarAction action = ToolbarAction::NONE;	/**< 按钮动作。 */
-			std::wstring label;							/**< 按钮文本。 */
+			UiButtonWidget* widget = nullptr;			/**< 对应控件（由 `m_root` 拥有）。 */
-			gd::RectF rect;								/**< 按钮矩形。 */
-			float width = 0.0f;							/**< 按钮宽度。 */
 			bool primary = false;						/**< 是否为主按钮（强调色填充）。 */
-			bool needsDocument = true;					/**< 是否依赖已加载数据。 */			bool toggle = false;						/**< 是否为可切换按钮。 */
+			bool needsDocument = true;					/**< 是否依赖已加载数据。 */
+			bool toggle = false;						/**< 是否为可切换按钮。 */
 			bool checked = false;						/**< 可切换按钮的选中状态。 */
-			bool hover = false;							/**< 悬停状态（当前由 `Toolbar::m_hoverIndex` 派生，字段保留供未来使用）。 */
+			float width = 0.0f;						/**< 按钮宽度（由控件实测得出）。 */
-			bool pressed = false;						/**< 按下状态。 */
 		};
 
 		/**
@@ -157,15 +160,20 @@ namespace jdi
 		 */
 		bool IsEnabled(const Button& button) const;
 
+		/** @brief 按固定规格表重建控件树（文本变化/首次布局时调用）。 */
+		void RebuildWidgets();
+		/** @brief 把可用性同步到控件（未加载数据时禁用依赖数据的按钮）。 */
+		void SyncEnabledState();
+
 		const UiFonts* m_fonts = nullptr;	/**< 字体资源。 */
 		const Theme* m_theme = nullptr;		/**< 主题资源。 */
 		float m_scale = 1.0f;				/**< DPI 缩放比例。 */
 		bool m_documentLoaded = false;		/**< 是否已加载数据。 */
-		std::vector<Button> m_buttons;		/**< 按钮集合。 */
+		std::vector<Button> m_buttons;		/**< 按钮配置集合。 */
 		std::vector<std::pair<ToolbarAction, std::wstring>> m_labelOverrides;	/**< 动态文本覆盖表。 */
 		gd::RectF m_area;					/**< 工具栏整体区域。 */
-		int m_hoverIndex = -1;				/**< 当前悬停按钮下标。 */
+		std::unique_ptr<UiWidget> m_root;	/**< 控件树根（负责底色与底部分隔线）。 */
-		int m_pressedIndex = -1;			/**< 当前按下按钮下标。 */
+		ToolbarAction m_pendingAction = ToolbarAction::NONE;	/**< 最近一次成功点击的动作。 */
 	};
 
 } // namespace jdi

Components/Toolbar/Src/Toolbar.cpp

@@ -1,8 +1,8 @@
 #include "Toolbar.hpp"
 
+#include <algorithm>
 #include <cmath>
-
+#include <utility>
-#include "Utf8Util.hpp"
 
 namespace jdi
 {
@@ -13,13 +13,78 @@ namespace jdi
 		const float kButtonGap = 6.0f;			/**< 按钮间距。 */
 		const float kButtonPadding = 14.0f;		/**< 按钮左右内边距。 */
 		const float kGroupGap = 18.0f;			/**< 分组间距。 */
-		const float kButtonRadius = 5.0f;		/**< 按钮圆角半径。 */
 		const float kSidePadding = 12.0f;		/**< 工具栏左右留白。 */
 		const float kTopPadding = 8.0f;			/**< 工具栏上下留白。 */
-	}
+
+		/**
+		 * @brief 工具栏的根控件：只负责"整条底色 + 底部分隔线"。
+		 *
+		 * 按钮是它的子节点（`UiButtonWidget`），由 `Toolbar::Layout` 逐个 `Arrange`。
+		 * 之所以把根做成控件而不是让 `Toolbar` 自己遍历按钮绘制：命中 / 悬停 / 按下的仲裁
+		 * 全部交给 `UiWidget` 的派发链与悬停链，`Toolbar` 只做"规格表 → 控件"的翻译。
+		 */
+		class ToolbarRootWidget : public UiWidget
+		{
+		public:
+			void Configure(const Theme* theme, float scale)
+			{
+				m_theme = theme;
+				m_scale = scale;
+			}
+
+			/** @brief 根尺寸由宿主（`Toolbar::Layout`）给定，不参与父级测量。 */
+			gd::SizeF OnMeasure(const UiMeasureContext& ctx) override
+			{
+				(void)ctx;
+				return gd::SizeF(Bounds().Width, Bounds().Height);
+			}
+
+			void OnPaint(UiPaintContext& ctx) override
+			{
+				if (m_theme == nullptr || ctx.g == nullptr || !UiRectHasArea(Bounds()))
+				{
+					return;
+				}
+				const gd::RectF& area = Bounds();
+				UiFillRect(*ctx.g, area, m_theme->toolbarBg);
+				// 底部分隔线：按钮不会覆盖到这一行，因此"底色 + 分隔线先画"与旧实现像素一致。
+				UiDrawLine(*ctx.g, area.X, area.Y + area.Height - 1.0f, area.X + area.Width,
+				           area.Y + area.Height - 1.0f, m_theme->border, 1.0f);
+			}
+
+		private:
+			const Theme* m_theme = nullptr;		/**< 主题。 */
+			float m_scale = 1.0f;				/**< 缩放系数。 */
+		};
+
+		/** @brief 按钮规格（顺序即绘制顺序）。 */
+		struct ButtonSpec
+		{
+			ToolbarAction action;		/**< 动作。 */
+			const wchar_t* label;		/**< 默认文本。 */
+			bool primary;				/**< 是否主按钮。 */
+			bool needsDocument;			/**< 是否依赖已加载数据。 */
+			bool toggle;				/**< 是否可切换。 */
+		};
+
+		const ButtonSpec kButtonSpecs[] = {
+		    {ToolbarAction::OPEN_FILE, L"导入文件", true, false, false},
+		    {ToolbarAction::FIT_ALL, L"适应视图", false, true, false},
+		    {ToolbarAction::AUTO_FIT_Y, L"Y 轴自适应", false, true, true},
+		    {ToolbarAction::ZOOM_SELECT, L"选区放大", false, true, true},
+		    {ToolbarAction::CURSOR, L"光标", false, true, true},
+		    {ToolbarAction::MERGE_LANES, L"合并网格", false, true, false},
+		    {ToolbarAction::SPLIT_LANES, L"拆分网格", false, true, false},
+		    {ToolbarAction::CLEAR_ALL, L"清空网格", false, true, false},
+		};
+	} // namespace
 
 	Toolbar::Toolbar() = default;
 
+	// 控件树用 `std::unique_ptr<UiWidget>` 持有，而具体根类型只在本 TU 可见
+	// ⇒ 析构函数必须在这里显式定义（否则其它 TU 里实例化会因类型不完整而编译失败）。
+	Toolbar::~Toolbar() = default;
+
 	void Toolbar::Setup(const UiFonts* fonts, const Theme* theme)
 	{
 		m_fonts = fonts;
@@ -33,7 +98,12 @@ namespace jdi
 
 	void Toolbar::SetDocumentLoaded(bool hasDocument)
 	{
+		if (m_documentLoaded == hasDocument)
+		{
+			return;
+		}
 		m_documentLoaded = hasDocument;
+		SyncEnabledState();
 	}
 
 	float Toolbar::DesiredHeight() const
@@ -46,92 +116,111 @@ namespace jdi
 		return button.needsDocument ? m_documentLoaded : true;
 	}
 
-	void Toolbar::Layout(const gd::RectF& area)
+	void Toolbar::SyncEnabledState()
 	{
-		m_area = area;
+		for (Button& button : m_buttons)
-
-		// 重新排布会重建全部按钮：先记下当前各 toggle 的勾选状态，
-		// 否则每次因文本变化（如「光标x2」）触发的 Layout 会把按钮选中态全部清掉。
-		std::vector<std::pair<ToolbarAction, bool>> previousChecked;
-		for (const Button& button : m_buttons)
 		{
-			previousChecked.emplace_back(button.action, button.checked);
+			if (button.widget != nullptr)
-		}
-		const auto inheritedChecked = [&previousChecked](ToolbarAction action)
-		{
-			for (const std::pair<ToolbarAction, bool>& entry : previousChecked)
 			{
-				if (entry.first == action)
+				button.widget->SetEnabled(IsEnabled(button));
-				{
-					return entry.second;
-				}
 			}
-			return false;
+		}
-		};
+	}
+
+	void Toolbar::RebuildWidgets()
+	{
+		m_root = std::make_unique<ToolbarRootWidget>();
+		static_cast<ToolbarRootWidget*>(m_root.get())->Configure(m_theme, m_scale);
 
 		m_buttons.clear();
-
+		const std::size_t specCount = sizeof(kButtonSpecs) / sizeof(kButtonSpecs[0]);
-		if (m_fonts == nullptr || m_fonts->ui == nullptr)
-		{
-			return;
-		}
-
-		struct Spec
-		{
-			ToolbarAction action;
-			const wchar_t* label;
-			bool primary;
-			bool needsDocument;
-			bool toggle;
-		};
-
-		const Spec specs[] = {
-		    {ToolbarAction::OPEN_FILE, L"导入文件", true, false, false},
-		    {ToolbarAction::FIT_ALL, L"适应视图", false, true, false},
-		    {ToolbarAction::AUTO_FIT_Y, L"Y 轴自适应", false, true, true},
-		    {ToolbarAction::ZOOM_SELECT, L"选区放大", false, true, true},
-		    {ToolbarAction::CURSOR, L"光标", false, true, true},
-		    {ToolbarAction::MERGE_LANES, L"合并网格", false, true, false},
-		    {ToolbarAction::SPLIT_LANES, L"拆分网格", false, true, false},
-		    {ToolbarAction::CLEAR_ALL, L"清空网格", false, true, false},
-		};
-		const std::size_t specCount = sizeof(specs) / sizeof(specs[0]);
-
-		// 按钮宽度按实际文本像素宽 + 固定内边距计算，避免中文标签被裁切。
-		const float top = area.Y + kTopPadding * m_scale;
-		const float height = kButtonHeight * m_scale;
-		const float horizontalPadding = kButtonPadding * 2.0f * m_scale;
-
-		// 先建立全部按钮并测量宽度，再决定“导入文件”固定在左、其余按钮整体靠右。
-		// （函数开头已经 `m_buttons.clear()` 并做过 `previousChecked` 快照，这里只需预留容量。）
 		m_buttons.reserve(specCount);
 
-		for (const Spec& spec : specs)
+		for (std::size_t index = 0; index < specCount; ++index)
 		{
-			Button button;
+			const ButtonSpec& spec = kButtonSpecs[index];
-			button.action = spec.action;
-			button.label = spec.label;
-			button.primary = spec.primary;
-			button.needsDocument = spec.needsDocument;
-			button.toggle = spec.toggle;
-			button.checked = inheritedChecked(spec.action);
-
 			// 动态文本覆盖（例如「光标」按当前模式显示 光标 / 光标x1 / 光标x2）。
+			std::wstring label = spec.label;
 			for (const std::pair<ToolbarAction, std::wstring>& entry : m_labelOverrides)
 			{
 				if (entry.first == spec.action)
 				{
-					button.label = entry.second;
+					label = entry.second;
 					break;
 				}
 			}
 
-			button.width = horizontalPadding + UiMeasureTextWidth(m_fonts->ui, button.label);
+			Button button;
-			m_buttons.push_back(std::move(button));
+			button.action = spec.action;
+			button.primary = spec.primary;
+			button.needsDocument = spec.needsDocument;
+			button.toggle = spec.toggle;
+			button.checked = false;
+
+			auto widget = std::make_unique<UiButtonWidget>();
+			UiButtonWidget* raw = widget.get();
+			raw->Configure(m_fonts, m_theme, m_scale, label, spec.primary, spec.toggle, kButtonPadding,
+			               kButtonHeight);
+			if (m_theme != nullptr)
+			{
+				raw->SetCanvasColor(m_theme->toolbarBg);
+			}
+			raw->SetEnabled(IsEnabled(button));
+			// 点击回调只登记动作，由宿主在鼠标抬起后统一执行（与旧语义一致）。
+			raw->onClick = [this, action = spec.action]() { m_pendingAction = action; };
+
+			button.widget = raw;
+			m_root->AddChild(std::move(widget));
+			m_buttons.push_back(button);
+		}
+	}
+
+	void Toolbar::Layout(const gd::RectF& area)
+	{
+		m_area = area;
+
+		if (m_fonts == nullptr || m_fonts->ui == nullptr || m_theme == nullptr)
+		{
+			return;
+		}
+
+		// 重建控件树：先记下各 toggle 的勾选状态，否则每次因文本变化（如「光标x2」）
+		// 触发的 Layout 会把按钮选中态全部清掉。
+		std::vector<std::pair<ToolbarAction, bool>> previousChecked;
+		previousChecked.reserve(m_buttons.size());
+		for (const Button& button : m_buttons)
+		{
+			previousChecked.emplace_back(button.action, button.checked);
+		}
+
+		RebuildWidgets();
+		m_root->Arrange(area);
+
+		UiMeasureContext measure;
+		measure.theme = m_theme;
+		measure.fonts = m_fonts;
+		measure.scale = m_scale;
+
+		// 宽度由控件实测（`内边距 × 2 + 文本宽`），与旧公式完全一致；中文标签因此不会被裁切。
+		for (Button& button : m_buttons)
+		{
+			button.width = button.widget->Measure(measure).Width;
+			for (const std::pair<ToolbarAction, bool>& entry : previousChecked)
+			{
+				if (entry.first == button.action)
+				{
+					button.checked = entry.second;
+					button.widget->SetChecked(entry.second);
+					break;
+				}
+			}
 		}
 
 		// 首按钮（导入文件）靠左；其余按钮作为整体靠右，并留出一组额外间距。
+		const float top = area.Y + kTopPadding * m_scale;
+		const float height = kButtonHeight * m_scale;
 		const float leftX = area.X + kSidePadding * m_scale;
+
 		float groupWidth = 0.0f;
 		for (std::size_t index = 1; index < m_buttons.size(); ++index)
 		{
@@ -143,13 +232,13 @@ namespace jdi
 		}
 
 		float cursorX = leftX;
-		m_buttons[0].rect = gd::RectF(cursorX, top, m_buttons[0].width, height);
+		m_buttons[0].widget->Arrange(gd::RectF(cursorX, top, m_buttons[0].width, height));
 
 		const float rightEdge = area.X + area.Width - kSidePadding * m_scale;
 		cursorX = std::max(leftX + m_buttons[0].width + kGroupGap * m_scale, rightEdge - groupWidth);
 		for (std::size_t index = 1; index < m_buttons.size(); ++index)
 		{
-			m_buttons[index].rect = gd::RectF(cursorX, top, m_buttons[index].width, height);
+			m_buttons[index].widget->Arrange(gd::RectF(cursorX, top, m_buttons[index].width, height));
 			cursorX += m_buttons[index].width + kButtonGap * m_scale;
 		}
 	}
@@ -161,6 +250,10 @@ namespace jdi
 			if (button.action == action && button.toggle)
 			{
 				button.checked = checked;
+				if (button.widget != nullptr)
+				{
+					button.widget->SetChecked(checked);
+				}
 				return;
 			}
 		}
@@ -177,12 +270,11 @@ namespace jdi
 					return false;
 				}
 				entry.second = label;
-				// 已排布过时同步更新按钮文本，宿主随后会调用 Layout() 重新计算宽度。
 				for (Button& button : m_buttons)
 				{
-					if (button.action == action)
+					if (button.action == action && button.widget != nullptr)
 					{
-						button.label = label;
+						button.widget->SetLabel(label);
 					}
 				}
 				return true;
@@ -191,9 +283,9 @@ namespace jdi
 		m_labelOverrides.emplace_back(action, label);
 		for (Button& button : m_buttons)
 		{
-			if (button.action == action)
+			if (button.action == action && button.widget != nullptr)
 			{
-				button.label = label;
+				button.widget->SetLabel(label);
 			}
 		}
 		return true;
@@ -201,84 +293,16 @@ namespace jdi
 
 	void Toolbar::Paint(gd::Graphics& g)
 	{
-		if (m_theme == nullptr || m_fonts == nullptr)
+		if (m_theme == nullptr || m_fonts == nullptr || m_root == nullptr)
 		{
 			return;
 		}
 
-		UiFillRect(g, m_area, m_theme->toolbarBg);
+		UiPaintContext ctx;
-
+		ctx.g = &g;
-		for (std::size_t buttonIndex = 0; buttonIndex < m_buttons.size(); ++buttonIndex)
+		ctx.clip = m_area;
-		{
+		ctx.scale = m_scale;
-			const Button& button = m_buttons[buttonIndex];
+		m_root->Paint(ctx);
-			const bool enabled = IsEnabled(button);
-			// ⚠️ 悬停态的唯一来源是 `m_hoverIndex`（`Button::hover` 字段从未被赋值，
-			// 旧实现读它 ⇒ 鼠标移到按钮上永远不高亮）。
-			const bool hovered = (static_cast<int>(buttonIndex) == m_hoverIndex);
-			std::uint32_t background = 0;
-			std::uint32_t border = 0;
-			std::uint32_t textColor = 0;
-
-			if (button.primary)
-			{
-				background = enabled ? m_theme->accent : MixColor(m_theme->accent, m_theme->toolbarBg, 0.6);
-				if (button.pressed)
-				{
-					background = MixColor(m_theme->accent, 0xFF000000u, 0.12);
-				}
-				else if (enabled && hovered)
-				{
-					background = MixColor(m_theme->accent, 0xFFFFFFFFu, 0.12);
-				}
-				border = background;
-				textColor = m_theme->textOnAccent;
-			}
-			else
-			{
-				// 可切换按钮在选中时用强调色浅底 + 强调描边，与普通按钮区分。
-				background = (button.toggle && button.checked) ? m_theme->accentSoft : m_theme->toolbarBg;
-				if (button.pressed)
-				{
-					background = m_theme->pressed;
-				}
-				else if (enabled && hovered)
-				{
-					background = (button.toggle && button.checked) ? MixColor(m_theme->accentSoft, m_theme->accent,
-					                                                        0.16)
-					                                              : m_theme->hover;
-				}
-				if (!enabled)
-				{
-					background = m_theme->toolbarBg;
-				}
-
-				if (button.toggle && button.checked && enabled)
-				{
-					border = m_theme->accent;
-				}
-				else
-				{
-					border = MixColor(m_theme->border, m_theme->toolbarBg, enabled ? 0.0 : 0.5);
-				}
-				textColor = enabled ? ((button.toggle && button.checked) ? m_theme->textStrong : m_theme->text)
-				                    : m_theme->textMuted;
-			}
-
-			if (background != m_theme->toolbarBg)
-			{
-				UiFillRoundRect(g, button.rect, kButtonRadius * m_scale, background);
-			}
-			if (!button.primary)
-			{
-				UiDrawRoundRect(g, button.rect, kButtonRadius * m_scale, border, 1.0f);
-			}
-
-			UiText(g, button.label, m_fonts->ui, button.rect, textColor, TextAlign::CENTER);
-		}
-
-		// 底部分隔线。
-		UiDrawLine(g, m_area.X, m_area.Y + m_area.Height - 1.0f, m_area.X + m_area.Width,
-		           m_area.Y + m_area.Height - 1.0f, m_theme->border, 1.0f);
 	}
 
 	bool Toolbar::HitTest(int x, int y) const
@@ -288,44 +312,42 @@ namespace jdi
 
 	bool Toolbar::OnMouseMove(int x, int y)
 	{
-		int hoverIndex = -1;
+		if (m_root == nullptr)
-		for (std::size_t index = 0; index < m_buttons.size(); ++index)
-		{
-			if (UiPointInRect(m_buttons[index].rect, static_cast<float>(x), static_cast<float>(y)))
-			{
-				hoverIndex = static_cast<int>(index);
-				break;
-			}
-		}
-
-		if (hoverIndex == m_hoverIndex)
 		{
 			return false;
 		}
-		m_hoverIndex = hoverIndex;
+		UiEvent event;
-		return true;
+		event.kind = UiEventKind::MOUSE_MOVE;
+		event.x = x;
+		event.y = y;
+		m_root->Dispatch(event);
+		// 悬停链切换会通过 `Invalidate` 把矩形冒泡到根 ⇒ 用它判断"是否需要重绘"
+		//（与旧实现"悬停下标变化才重绘"等价，但不再手工维护下标）。
+		return UiRectHasArea(m_root->TakeDirty());
 	}
 
 	bool Toolbar::OnLButtonDown(int x, int y, ToolbarAction& action)
 	{
 		action = ToolbarAction::NONE;
-
+		if (m_root == nullptr)
-		for (std::size_t index = 0; index < m_buttons.size(); ++index)
 		{
-			Button& button = m_buttons[index];
+			return false;
-			if (!UiPointInRect(button.rect, static_cast<float>(x), static_cast<float>(y)))
+		}
-			{
+		UiEvent event;
-				continue;
+		event.kind = UiEventKind::MOUSE_DOWN;
-			}
+		event.x = x;
-			if (!IsEnabled(button))
+		event.y = y;
-			{
+		event.button = UiMouseButton::LEFT;
-				return false;
+		m_root->Dispatch(event);
-			}
+		(void)m_root->TakeDirty();
 
-			m_pressedIndex = static_cast<int>(index);
+		for (const Button& button : m_buttons)
-			button.pressed = true;
+		{
-			action = button.action;
+			if (button.widget != nullptr && button.widget->Pressed())
-			return true;
+			{
+				action = button.action;
+				return true;
+			}
 		}
 		return false;
 	}
@@ -333,47 +355,70 @@ namespace jdi
 	bool Toolbar::OnLButtonUp(int x, int y, ToolbarAction& action)
 	{
 		action = ToolbarAction::NONE;
-		if (m_pressedIndex < 0)
+		if (m_root == nullptr)
 		{
 			return false;
 		}
 
-		const int index = m_pressedIndex;
+		// 旧语义：没有按下过就不进入抬起处理。
-		m_pressedIndex = -1;
+		bool hadPressed = false;
-		if (index >= static_cast<int>(m_buttons.size()))
+		for (const Button& button : m_buttons)
+		{
+			if (button.widget != nullptr && button.widget->Pressed())
+			{
+				hadPressed = true;
+				break;
+			}
+		}
+		if (!hadPressed)
 		{
 			return false;
 		}
 
-		Button& button = m_buttons[static_cast<std::size_t>(index)];
+		m_pendingAction = ToolbarAction::NONE;
-		button.pressed = false;
+		UiEvent event;
+		event.kind = UiEventKind::MOUSE_UP;
+		event.x = x;
+		event.y = y;
+		event.button = UiMouseButton::LEFT;
+		m_root->Dispatch(event);
 
-		const bool inside = UiPointInRect(button.rect, static_cast<float>(x), static_cast<float>(y));
+		// 旧实现会在抬起时按落点重算悬停态；派发一条 MOUSE_MOVE 让悬停链同步。
-		m_hoverIndex = inside ? index : -1;
+		UiEvent sync;
-		if (inside && IsEnabled(button))
+		sync.kind = UiEventKind::MOUSE_MOVE;
-		{
+		sync.x = x;
-			action = button.action;
+		sync.y = y;
-		}
+		m_root->Dispatch(sync);
+		(void)m_root->TakeDirty();
+
+		action = m_pendingAction;
+		m_pendingAction = ToolbarAction::NONE;
 		return true;
 	}
 
 	bool Toolbar::OnMouseLeave()
 	{
+		if (m_root == nullptr)
+		{
+			return false;
+		}
+		UiEvent event;
+		event.kind = UiEventKind::MOUSE_LEAVE;
+		event.x = 0;
+		event.y = 0;
+		m_root->Dispatch(event);
+
+		// 指针离开窗口后不会再收到 MOUSE_UP ⇒ 在这里放弃"按下"（与旧实现一致）。
 		bool changed = false;
-		if (m_hoverIndex >= 0)
+		for (Button& button : m_buttons)
 		{
-			m_hoverIndex = -1;
+			if (button.widget != nullptr && button.widget->Pressed())
-			changed = true;
-		}
-		if (m_pressedIndex >= 0)
-		{
-			if (m_pressedIndex < static_cast<int>(m_buttons.size()))
 			{
-				m_buttons[static_cast<std::size_t>(m_pressedIndex)].pressed = false;
+				button.widget->CancelPress();
+				changed = true;
 			}
-			m_pressedIndex = -1;
-			changed = true;
 		}
+		changed = UiRectHasArea(m_root->TakeDirty()) || changed;
 		return changed;
 	}
 

Documents/UI_Refactor_Progress.md

@@ -17,8 +17,8 @@
 | --- | --- | --- |
 | **P0** | 离屏回归网 `Tools/uicheck`（入库） | ✅ 完成（62 项断言全绿） |
 | **P1** | `UiLayout` + `UiWidget` 基础层 | ✅ 完成（编译零警告，`uicheck` 覆盖） |
-| **P2** | `PlotViewPaint.cpp` 零行为分片 | ✅ 完成（**逐像素 0 差异**，见 §2） |
+| **P2** | `PlotViewPaint.cpp` 零行为分片 | ✅ 完成（**逐像素 0 差异**，见 §2/§3） |
-| **P3** | 迁移 chrome（Toolbar / TabBar / 菜单 / 拾色器 / 列表行） | ⏳ 待做 |
+| **P3** | 迁移 chrome（Toolbar / TabBar / 菜单 / 拾色器 / 列表行） | 🔄 **Toolbar 已完成**，其余待做 |
 | **P4** | 迁移 5 个浮动面板 | ⏳ 待做 |
 | **P5** | 波形管线包成叶子 surface + 共享 DIB | ⏳ 待做 |
 
@@ -27,7 +27,6 @@
 ## 提交记录
 
 ### 1. `P0 + P1`：UI 基础层与离屏回归网
-
 **新增文件**
 
 | 文件 | 行数 | 职责 |
@@ -139,13 +138,50 @@ Tools/uicheck/uicheck.exe                      # 62 passed, 0 failed
 
 ---
 
+### 4. `P3`：Toolbar 迁移到控件树（**逐像素 0 差异**）
+
+**新增**：`Components/Shared/{Inc,Src}/UiButtonWidget.*` —— 通用"文字按钮"控件，视觉规则与旧 Toolbar
+按钮逐像素一致（主按钮强调色实底 / 普通按钮 1px 描边 / 可切换选中态 / 禁用态配色）；
+交互由自己处理：按下即 `CaptureMouse()` 进入按下态，**在自身范围内**松开才触发 `onClick`，
+指针离开时 `CancelPress()`。
+
+**`Toolbar` 内部重写（公开 API 一字未改）**：
+
+| 旧实现 | 新实现 |
+| --- | --- |
+| `std::vector<Button>` 里既存配置又存矩形/悬停/按下 | `Button` 只存**静态配置 + 控件指针**；几何与外观状态归控件 |
+| `m_hoverIndex` / `m_pressedIndex` 手工维护 | 由 `UiWidget` 的**悬停链**与 capture 维护 |
+| `Paint` 自己遍历按钮绘制 | 根控件（`ToolbarRootWidget`：底色 + 底部分隔线）+ 按钮子节点，`root->Paint(ctx)` |
+| `OnMouseMove/Down/Up/Leave` 各自扫按钮矩形 | 统一翻译成 `UiEvent` → `root->Dispatch(event)`；动作经 `onClick` 回调登记、抬起后执行 |
+| `Button::hover` 死字段 | 删除（`Hovered()` 由基类提供） |
+
+**新增框架约定（重要）**：`UiWidget::Paint` 的裁剪由"严格等于自身矩形"改为
+**"自身矩形外扩 `kUiClipBleed`(1px)"**。原因：边框/描边以矩形边界为中心绘制，1px 笔宽有一半在矩形外，
+严格裁剪会把外半侧切掉 ⇒ 控件看起来变细（与旧绘制代码不再逐像素一致）。
+`uicheck` 对应断言改为"裁剪 ⊇ 自身矩形且不超出外扩范围"。
+
+**验证**
+
+1. `make release` / `make debug` **零警告**；`Target.exe` **881 664 B**（< 900 KB）。
+2. **逐像素 A/B（8 个场景）**：迁移前后哈希逐一相同
+   `A 2166933… / B C444ECF… / C 7984446… / D BF85587… / E 1C663E4… / F 0535292… / G 7A58172… / H 23F390D…`
+   （A 全览；B 深放大+自由标记+均值滤波+弱峰调整+光标；C 平移；D 悬停按钮；E 按下未松开；
+   F 松开；G 悬停主按钮；H 移出工具栏）。
+3. **功能验证**（证明点击真的翻译成动作，而不是"看起来没坏"）：
+   * `FUNC locate-cursor-button PASS (1291,73)` —— 用控件自身矩形定位按钮；
+   * `FUNC click-cursor-changes-mode PASS (1 -> 2)` —— 点击「光标」按钮后光标模式 单→双；
+   * `FUNC release-outside-does-not-fire PASS (2 -> 2)` —— 按下后移出再松开，不触发动作。
+4. `Tools/uicheck` **62/62**。
+
+---
+
 ## 下一步（接手者请从这里开始）
 
-1. **P3：Toolbar 优先**（最小、最容易验证的组件）：
+1. **P3 续**：按同一套路迁移 `TabBar`（标签 + 「+」按钮 + 重命名内联输入框）→ 再迁移
-   继承 `UiWidget` → `OnMeasure` 由按钮文本实测得出 → `OnPaint` 用 `ctx.clip` 画按钮 →
+   `PopupMenu` / `ColorPickerPopup` 的条目行。判据同为"8+ 场景像素哈希一致 + 功能断言"。
-   `OnEvent` 返回 `{consumed, redraw, dirty}`；迁移后用 `uicheck` + 新旧像素对比。
+2. **P4**：5 个浮动面板（`EdgePanelLayoutFor` 651 行 → 真控件；Stack + Abs + Measure-driven），
-2. **P4：浮动面板**：`EdgePanelLayoutFor` 的 651 行 → 真控件（Stack + Abs + Measure-driven），
+   消掉 `rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...` 等平行数组。
-   并消掉面板里 10 多个平行数组（`rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...`）。
+   ⚠️ 每个面板单独一轮；吸顶/滚动/滚动条/滑块复位/行悬停压暗/开关联动是 6 轮补丁叠出的隐式约定。
-3. **P5：共享 DIB + `SurfaceView`**（`CreateCompatibleBitmap` → top-down 32bpp `CreateDIBSection`，
+3. **P5**：共享 top-down 32bpp `CreateDIBSection` + `SurfaceView{dc,rect,stride,bits,version}`，
-   带 `version` 作废机制），随后把 56 处 `InvalidateRect` 收敛成脏区并集。
+   把 56 处 `InvalidateRect` 收敛成脏区并集。
-4. 每个阶段单独提交，提交信息写清"改了什么 / 为什么 / 怎么验证"。
+4. 每阶段单独提交，提交信息写清"改了什么 / 为什么 / 怎么验证"。