UI 重构 P0+P1：新增布局/控件基础层与离屏回归网（对产品像素零影响）

新增 Components/Shared 下的 UI 基础层：
- UiLayout：矩形原语 / 对齐 / 设备像素内侧对齐 / Stack / Flow / 布局缓存（deque 保证引用稳定、
  定向失效、按最久未命中淘汰）。
- UiWidget：控件树基类。两段式布局（Measure 自下而上带缓存、Arrange 自上而下）、
  脏区下探绘制（dirty 为空=全画；与子树矩形无交集=整棵跳过；有效裁剪=祖先裁剪切∩自身∩脏区）、
  只沿命中链派发的冒泡模型（绝不分发给同层兄弟）、capture/modal/hover/focus 仲裁、
  光标认领链、统一动画 tick、内容指纹入口。

新增 Tools/uicheck 离屏回归网（62 项断言，全程不创建窗口、不注入输入）：
- 布局数学：对齐/STRETCH/超尺寸夹取、Stack 固定与自动均分且绝不产生负尺寸、Flow 换行与 overflow。
- 缓存：引用稳定、定向失效、容量淘汰。
- 绘制：全画 / 子树跳过 / 裁剪收窄 / 不可见跳过 / 失效冒泡。
- 派发：重叠子节点只投最上层、hit-transparent 穿透、消费不上抛、capture 越过边界仍投递、
  仅持有者可释放、modal 屏蔽其余子树、祖先兜底、光标由最上层认领、键盘沿焦点链。
- 动画：时间戳统一下发、活跃状态汇总。

过程中修正自身两处缺陷：补齐 AdvanceAnimationSelf/AnimationActiveSelf 声明；
把"遍历同层兄弟"改为"只沿命中链派发 + 祖先兜底"（否则一次点击可能被视觉上位于下方的控件也处理）。

验证：make release TARGET_FILE_NAME=TargetCheck 零警告（873,984 B，低于 900KB 阈值）；
Tools/uicheck 62 passed / 0 failed。

本提交不改动任何现有组件，Toolbar/TabBar/SignalPanel/PlotView 仍走旧路径，产品像素零变化。
文档：Documents/UI_Refactor_Plan.md（蓝图）、Documents/UI_Refactor_Progress.md（台账）。

Components/Shared/Inc/UiLayout.hpp

@@ -0,0 +1,220 @@
+#ifndef __UI_LAYOUT_HPP__
+#define __UI_LAYOUT_HPP__
+
+#include <windows.h>
+#include <objidl.h>
+#include <gdiplus.h>
+
+#include <cstdint>
+#include <cstddef>
+#include <deque>
+#include <vector>
+
+#include "Theme.hpp"
+
+namespace jdi
+{
+
+	/**
+	 * @brief 布局方向。
+	 */
+	enum class UiAxis : int
+	{
+		HORIZONTAL = 0,		/**< 主轴为水平（从左到右排列）。 */
+		VERTICAL = 1		/**< 主轴为垂直（从上到下排列）。 */
+	};
+
+	/**
+	 * @brief 在容器中的对齐方式（单一方向）。
+	 *
+	 * `STRETCH` = 占满该方向可用空间（尺寸由容器决定，忽略自身期望尺寸）。
+	 */
+	enum class UiAlign : int
+	{
+		BEGIN = 0,			/**< 起始边（左 / 上）。 */
+		CENTER = 1,			/**< 居中。 */
+		END = 2,			/**< 结束边（右 / 下）。 */
+		STRETCH = 3			/**< 拉伸占满。 */
+	};
+
+	/**
+	 * @brief 四边内边距（逻辑像素，使用时由调用方乘缩放系数）。
+	 */
+	struct UiInsets
+	{
+		float left = 0.0f;		/**< 左内边距。 */
+		float top = 0.0f;		/**< 上内边距。 */
+		float right = 0.0f;		/**< 右内边距。 */
+		float bottom = 0.0f;	/**< 下内边距。 */
+
+		/** @brief 四边同值。 */
+		static UiInsets All(float value);
+		/** @brief 左右 / 上下分别指定。 */
+		static UiInsets Symmetric(float horizontal, float vertical);
+		/** @brief 按缩放系数放大（DPR 1.25 等）。 */
+		UiInsets Scaled(float scale) const;
+		/** @brief 水平方向占用量。 */
+		float Horizontal() const { return left + right; }
+		/** @brief 垂直方向占用量。 */
+		float Vertical() const { return top + bottom; }
+	};
+
+	// ------------------------------------------------------------------
+	// 矩形原语
+	// ------------------------------------------------------------------
+
+	/** @brief 矩形是否有面积（宽度与高度都 > 0）。 */
+	bool UiRectHasArea(const gd::RectF& rect);
+
+	/** @brief 两个矩形的交集；无交集时输出空矩形并返回 false。 */
+	bool UiRectIntersect(const gd::RectF& a, const gd::RectF& b, gd::RectF& out);
+
+	/** @brief 两个矩形的并集（任一为空时直接返回另一个）。 */
+	gd::RectF UiRectUnion(const gd::RectF& a, const gd::RectF& b);
+
+	/** @brief 内缩（结果可能为空矩形）。 */
+	gd::RectF UiRectDeflate(const gd::RectF& rect, const UiInsets& insets);
+
+	/**
+	 * @brief 把矩形对齐到**设备像素整数边界**（上界 `floor`、下界 `ceil`）。
+	 *
+	 * ⚠️ 离屏位图（图层 / 装饰层 / 面板层）必须用这个结果做贴图源矩形：
+	 * 直接对浮点矩形取整会让补丁多算一行，从而盖到相邻网格的分界线上（历史 1px 接缝 BUG）。
+	 */
+	gd::RectF UiRectSnapInward(const gd::RectF& rect, float scale);
+
+	/** @brief 把一个 `size` 的盒子按对齐方式放进 `outer`（`STRETCH` 时返回 `outer` 本身）。 */
+	gd::RectF UiAlignInRect(const gd::RectF& outer, float width, float height, UiAlign horizontal,
+	                        UiAlign vertical, float offsetX = 0.0f, float offsetY = 0.0f);
+
+	// ------------------------------------------------------------------
+	// 布局：Stack（一维流）/ Flow（换行流）/ Abs（绝对）
+	// ------------------------------------------------------------------
+
+	/** @brief 尺寸未知（由剩余空间均分）。 */
+	constexpr float kUiSizeAuto = -1.0f;
+
+	/**
+	 * @brief 一维栈布局的**期望尺寸**。
+	 * @param [IN] sizes 各项主尺寸（`kUiSizeAuto` 表示由剩余空间均分，不参与求和）。
+	 * @param [IN] gap 项间距。
+	 * @return 主尺寸合计（含间距）。
+	 */
+	float UiStackExtent(const std::vector<float>& sizes, float gap);
+
+	/**
+	 * @brief 一维栈布局：把 `area` 沿主轴依次切分给各项。
+	 *
+	 * * 固定尺寸项按给定值取用；
+	 * * `kUiSizeAuto` 项均分**剩余**空间（剩余为负时按 0 处理，避免负尺寸）；
+	 * * 交叉轴一律占满 `area`（需要单独对齐时调用方再 `UiAlignInRect`）。
+	 *
+	 * @param [IN] area 可用区域。
+	 * @param [IN] axis 主轴方向。
+	 * @param [IN] sizes 各项主尺寸（可含 `kUiSizeAuto`）。
+	 * @param [IN] gap 项间距。
+	 * @param [OUT] out 逐项矩形（数量与 `sizes` 一致）。
+	 * @param [OUT] usedExtent 实际占用主尺寸（含间距），可为空。
+	 */
+	void UiStackRects(const gd::RectF& area, UiAxis axis, const std::vector<float>& sizes, float gap,
+	                  std::vector<gd::RectF>& out, float* usedExtent = nullptr);
+
+	/**
+	 * @brief 换行流布局（图例条目、工具栏按钮组）。
+	 *
+	 * 沿主轴依次摆放，放不下时**换到下一行/列**；放不下的项（含之后的所有项）
+	 * 不再输出，其下标通过 `overflow` 返回 —— 调用方据此绘制 `+N` 之类的省略提示。
+	 *
+	 * @param [IN] area 可用区域。
+	 * @param [IN] axis 主轴方向（通常是水平）。
+	 * @param [IN] sizes 各项 (宽, 高)。
+	 * @param [IN] gap 项间距（主轴与交叉轴相同）。
+	 * @param [OUT] out 已放下的项矩形。
+	 * @param [OUT] overflow 首个未放下的项下标；全部放下时为 `sizes.size()`。
+	 * @return 实际占用的交叉轴尺寸（行数 × 行高）。
+	 */
+	float UiFlowRects(const gd::RectF& area, UiAxis axis, const std::vector<gd::SizeF>& sizes, float gap,
+	                  std::vector<gd::RectF>& out, std::size_t& overflow);
+
+	/** @brief 绝对布局：`outer` 左上角偏移 `(dx, dy)` 后取 `width × height`。 */
+	gd::RectF UiAbsRect(const gd::RectF& outer, float dx, float dy, float width, float height);
+
+	// ------------------------------------------------------------------
+	// 布局缓存
+	// ------------------------------------------------------------------
+
+	/**
+	 * @brief 一份被缓存下来的布局结果。
+	 *
+	 * `rects` / `values` 的含义由调用方约定（例如浮动面板的"标题栏 / ✕ / 徽标 / 逐行矩形"）。
+	 */
+	struct UiLayoutResult
+	{
+		std::uint64_t key = 0;				/**< 布局键（由调用方构造，必须覆盖**全部**影响几何的输入）。 */
+		gd::RectF bounds;					/**< 整体矩形。 */
+		std::vector<gd::RectF> rects;		/**< 逐项矩形。 */
+		std::vector<float> values;			/**< 附带数值（列宽 / 行高 / 内容总高等）。 */
+		std::uint64_t stamp = 0;			/**< 最近一次命中序号（用于淘汰最久未用项）。 */
+	};
+
+	/**
+	 * @brief 布局结果缓存（把"每帧被反复询问的几何"降到只算一次）。
+	 *
+	 * 设计要点：
+	 * * 用 `std::deque` 存条目 ⇒ `Store` 之后**已有元素引用依然有效**（`vector` 扩容会失效）；
+	 * * 条目数量很小（面板种类 × 网格数），线性查找比哈希更快，也避免哈希碰撞带来的诡异行为；
+	 * * **定向失效**：几何改变的那条路径必须显式 `Invalidate(key)`，
+	 *   **禁止**为了让缓存命中率好看而整体 `Clear()`（会让所有面板在同一帧全部重算）。
+	 */
+	class UiLayoutCache
+	{
+	public:
+		explicit UiLayoutCache(std::size_t capacity = 32);
+
+		/**
+		 * @brief 查找命中项。
+		 * @param [IN] key 布局键。
+		 * @return 命中返回条目指针（**内容不可修改**），未命中返回 nullptr。
+		 * @note 命中会刷新该条目的使用序号（因此本函数不是 `const`）。
+		 */
+		const UiLayoutResult* Find(std::uint64_t key);
+
+		/**
+		 * @brief 存入（同键覆盖）并返回稳定引用。
+		 * @param [IN] result 待存条目（`key` 必须已填）。
+		 * @return 缓存内条目的引用（有效期到下一次 `Store` 引发淘汰为止）。
+		 */
+		const UiLayoutResult& Store(UiLayoutResult result);
+
+		/** @brief 定向失效。 */
+		void Invalidate(std::uint64_t key);
+
+		/** @brief 全部清空（只在"数据层结构变化"这类场景使用）。 */
+		void Clear();
+
+		/** @brief 当前条目数（探针用）。 */
+		std::size_t Size() const { return m_entries.size(); }
+
+	private:
+		std::size_t m_capacity;					/**< 条目上限。 */
+		std::uint64_t m_stamp = 0;				/**< 递增使用序号。 */
+		std::deque<UiLayoutResult> m_entries;	/**< 条目（deque 保证引用稳定）。 */
+
+		/** @brief 淘汰最久未使用的条目，直到不超过上限。 */
+		void Trim();
+	};
+
+	/**
+	 * @brief 组合布局键（FNV-1a 风格的增量混合）。
+	 *
+	 * ⚠️ 键必须覆盖**全部**影响几何的输入；漏一个字段的症状是"布局不更新"
+	 * （与历史上"缓存键漏混字段 ⇒ 贴旧像素"是同一类 BUG）。
+	 */
+	std::uint64_t UiMixKey(std::uint64_t seed, std::uint64_t value);
+
+	/** @brief 浮点参与成键（按 1/1024 量化，避免亚像素抖动导致键频繁变化）。 */
+	std::uint64_t UiMixKeyFloat(std::uint64_t seed, float value);
+
+} // namespace jdi
+
+#endif // __UI_LAYOUT_HPP__

Components/Shared/Inc/UiWidget.hpp

@@ -0,0 +1,325 @@
+#ifndef __UI_WIDGET_HPP__
+#define __UI_WIDGET_HPP__
+
+#include <windows.h>
+#include <objidl.h>
+#include <gdiplus.h>
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+#include "Theme.hpp"
+#include "UiLayout.hpp"
+
+namespace jdi
+{
+
+	struct Theme;
+	struct UiFonts;
+
+	/**
+	 * @brief 布局测量上下文（由根节点统一下发，子节点只读）。
+	 */
+	struct UiMeasureContext
+	{
+		const Theme* theme = nullptr;		/**< 主题（子节点可能需要配色相关的尺寸）。 */
+		const UiFonts* fonts = nullptr;		/**< 字体（文本尺寸测量必需）。 */
+		float scale = 1.0f;					/**< 缩放系数（逻辑像素 → 设备像素）。 */
+		float availableWidth = -1.0f;		/**< 父给出的宽度上限（<0 表示不限）。 */
+		float availableHeight = -1.0f;		/**< 父给出的高度上限（<0 表示不限）。 */
+	};
+
+	/**
+	 * @brief 绘制上下文。
+	 *
+	 * ⚠️ **`dirty` 的语义（重要）**：空矩形表示"脏区未知 ⇒ 全画"；非空表示"只需保证这一块被更新"。
+	 * 基类在进入子节点前会把 `dirty` 与子节点矩形求交，为空即**整棵子树跳过** ——
+	 * 这是本框架唯一真正省时间的机制，禁止任何派生类把它退化成"父脏 ⇒ 子树全脏"。
+	 */
+	struct UiPaintContext
+	{
+		gd::Graphics* g = nullptr;			/**< 绘图上下文（共享的后备缓冲/离屏位图）。 */
+		gd::RectF dirty;					/**< 需要重绘的区域（客户区坐标）。 */
+		gd::RectF clip;						/**< 当前有效裁剪矩形（= 祖先与本节点矩形的交集）。 */
+		float scale = 1.0f;					/**< 缩放系数。 */
+		bool fastFrame = false;				/**< 交互帧：允许降级（**几何不得改变**，只允许关抗锯齿等）。 */
+
+		/** @brief 取与给定矩形求交后的绘制上下文（子节点用）。 */
+		UiPaintContext WithClip(const gd::RectF& rect) const;
+	};
+
+	/**
+	 * @brief 事件类型。
+	 */
+	enum class UiEventKind : int
+	{
+		NONE = 0,
+		MOUSE_MOVE,			/**< 鼠标移动（可能带按键）。 */
+		MOUSE_DOWN,			/**< 鼠标按下。 */
+		MOUSE_UP,			/**< 鼠标抬起。 */
+		MOUSE_DOUBLE_CLICK,	/**< 双击（**只有确实有双击语义的控件才应处理它**）。 */
+		MOUSE_WHEEL,		/**< 滚轮。 */
+		MOUSE_LEAVE,		/**< 指针离开该控件。 */
+		KEY_DOWN,			/**< 键盘按下。 */
+		CHAR,				/**< 字符输入。 */
+		QUERY_CURSOR		/**< 询问光标形态（结果写回 `cursor`）。 */
+	};
+
+	/** @brief 鼠标按键（与 `UiEventKind` 组合使用）。 */
+	enum class UiMouseButton : int
+	{
+		NONE = 0,
+		LEFT = 1,
+		MIDDLE = 2,
+		RIGHT = 3
+	};
+
+	/**
+	 * @brief 一个 UI 事件（客户区坐标）。
+	 */
+	struct UiEvent
+	{
+		UiEventKind kind = UiEventKind::NONE;	/**< 事件类型。 */
+		int x = 0;								/**< 鼠标横坐标。 */
+		int y = 0;								/**< 鼠标纵坐标。 */
+		UiMouseButton button = UiMouseButton::NONE;	/**< 涉及的按键。 */
+		int wheelDelta = 0;						/**< 滚轮增量（1 格 = 120）。 */
+		bool shift = false;						/**< Shift 是否按下。 */
+		bool control = false;					/**< Ctrl 是否按下。 */
+		WPARAM key = 0;							/**< 虚拟键码（`KEY_DOWN`）。 */
+		wchar_t character = 0;					/**< 字符（`CHAR`）。 */
+		HCURSOR cursor = nullptr;				/**< `QUERY_CURSOR` 的输出（nullptr = 未认领）。 */
+	};
+
+	/**
+	 * @brief 事件处理结果。
+	 *
+	 * 与旧架构（返回 `bool 要不要重绘`）的关键差别：**"消费"与"重绘"是两件事**。
+	 * 消费决定是否继续上抛；`dirty` 参与本帧脏区并集（为空表示"未知 ⇒ 取自身矩形"）。
+	 */
+	struct UiEventResult
+	{
+		bool consumed = false;		/**< 事件已被消费。 */
+		bool redraw = false;		/**< 需要重绘。 */
+		gd::RectF dirty;			/**< 需要重绘的矩形（客户区坐标；空 + `redraw` ⇒ 取自身矩形）。 */
+
+		/** @brief 构造"已消费且需要重绘自身"的结果。 */
+		static UiEventResult Handled();
+		/** @brief 构造"已消费但不需重绘"的结果（例如纯状态查询）。 */
+		static UiEventResult Swallowed();
+	};
+
+	/**
+	 * @brief UI 控件基类：树结构 + 两段式布局 + 脏区下探绘制 + 冒泡派发 + 交互仲裁。
+	 *
+	 * ## 为什么要这一层
+	 *
+	 * 旧架构是"并列大组件 + 手写优先级链"，每个叠加层都要把"几何 / 命中 / 绘制 / 缓存键"
+	 * 各写一遍（`PlotView` 已有 310 个方法 / 203 个成员）。这里把这些重复收敛成基类契约：
+	 *
+	 * * **布局只算一次**：`Measure` 自下而上、`Arrange` 自上而下；命中/绘制/光标读同一份 `m_bounds`。
+	 * * **裁剪契约统一**：`Paint` 进入时收紧 GDI+ 裁剪（`ctx.clip`），派生类必须把它传给
+	 *   `UiTextClipped` 等**GDI 绘制辅助函数**（GDI 文本不认 GDI+ 裁剪区，这是本项目反复踩到的坑）。
+	 * * **脏区下探**：`dirty ∩ bounds` 为空 ⇒ 整棵子树跳过。
+	 * * **交互仲裁**：capture / 模态 / 悬停链 / 光标链由基类提供，派生类只写自己的手势。
+	 *
+	 * ## 三条硬约束（改代码前先读）
+	 *
+	 * 1. **禁止"父脏 ⇒ 子树全脏"**：会把"只重绘一个网格/一个面板"打回整块重绘。
+	 * 2. **禁止把数据→像素管线（网格/曲线/采样点）做成控件节点**：布局与虚调用会进每帧热路径。
+	 * 3. **禁止每个控件自持位图**：内存按面积线性增长（128 网格已是 ≈250MB 量级）。
+	 */
+	class UiWidget
+	{
+	public:
+		UiWidget();
+		virtual ~UiWidget();
+
+		UiWidget(const UiWidget&) = delete;
+		UiWidget& operator=(const UiWidget&) = delete;
+
+		// ------------------------------------------------------------------
+		// 树结构
+		// ------------------------------------------------------------------
+
+		/** @brief 追加子节点（**追加到末尾 = 最上层**，绘制与命中都按此顺序）。 */
+		UiWidget& AddChild(std::unique_ptr<UiWidget> child);
+		/** @brief 移除子节点（不存在时无操作）。 */
+		void RemoveChild(UiWidget* child);
+		/** @brief 子节点集合（顺序 = z 序，末尾最上层）。 */
+		const std::vector<std::unique_ptr<UiWidget>>& Children() const { return m_children; }
+		/** @brief 父节点（根节点为 nullptr）。 */
+		UiWidget* Parent() const { return m_parent; }
+		/** @brief 根节点。 */
+		UiWidget* Root();
+		/** @brief 根节点（const）。 */
+		const UiWidget* Root() const;
+
+		// ------------------------------------------------------------------
+		// 布局
+		// ------------------------------------------------------------------
+
+		/** @brief 标记"期望尺寸"失效（会向根冒泡。只失效自己与**祖先**，不影响兄弟）。 */
+		void InvalidateMeasure();
+
+		/**
+		 * @brief 自下而上求期望尺寸（带缓存）。
+		 * @param [IN] ctx 测量上下文。
+		 * @return 期望尺寸（**含**自身内边距；不含外边距 —— 本项目没有外边距概念）。
+		 */
+		gd::SizeF Measure(const UiMeasureContext& ctx);
+
+		/** @brief 定位：写入自身矩形并回调 `OnArrange()`（派生容器在其中摆放子节点）。 */
+		void Arrange(const gd::RectF& bounds);
+
+		/** @brief 当前矩形（客户区坐标，整像素对齐由调用方保证）。 */
+		const gd::RectF& Bounds() const { return m_bounds; }
+		/** @brief 上一帧测量得到的期望尺寸。 */
+		gd::SizeF DesiredSize() const { return m_desiredSize; }
+
+		// ------------------------------------------------------------------
+		// 绘制
+		// ------------------------------------------------------------------
+
+		/** @brief 绘制自身与全部子节点（内部处理裁剪下探与脏区跳过）。 */
+		void Paint(UiPaintContext& ctx);
+
+		/** @brief 局部失效：与自身矩形求交后向根冒泡。 */
+		virtual void Invalidate(const gd::RectF& rect);
+		/** @brief 整棵子树失效。 */
+		void InvalidateAll();
+
+		/** @brief 取走累计的脏区（根节点用）。空矩形表示"无失效"。 */
+		gd::RectF TakeDirty();
+
+		// ------------------------------------------------------------------
+		// 事件
+		// ------------------------------------------------------------------
+
+		/** @brief 派发事件：捕获/模态路由 → 命中链（自最深向上冒泡）→ 自身 `OnEvent`。 */
+		UiEventResult Dispatch(UiEvent& event);
+
+		/** @brief 点是否落在自身矩形内（不含可见性/透明判断）。 */
+		bool Contains(int x, int y) const;
+
+		// ------------------------------------------------------------------
+		// 交互仲裁
+		// ------------------------------------------------------------------
+
+		/** @brief 请求独占鼠标（根节点记录；等价于 `SetCapture`）。 */
+		void CaptureMouse();
+		/** @brief 释放独占（**只有当前的捕获者**才会成功，避免错误释放别人的捕获）。 */
+		void ReleaseMouse();
+		/** @brief 当前持有捕获的控件（无则 nullptr）。 */
+		UiWidget* MouseCaptureWidget() const;
+
+		/** @brief 设为模态子树：根节点只向它派发事件（菜单/拾色器等浮层用）。 */
+		void SetModal(bool modal);
+		/** @brief 当前模态子树（无则 nullptr）。 */
+		UiWidget* ModalWidget() const;
+		/** @brief 是否处于模态（向上查找到根）。 */
+		bool IsModalActive() const { return ModalWidget() != nullptr; }
+
+		/** @brief 设为"命中透明"（纯装饰元素：不参与命中与光标链）。 */
+		void SetHitTransparent(bool value) { m_hitTransparent = value; }
+		/** @brief 是否命中透明。 */
+		bool HitTransparent() const { return m_hitTransparent; }
+
+		/** @brief 设置可见性（不可见 = 不参与绘制与命中，**但不影响布局**）。 */
+		void SetVisible(bool visible) { m_visible = visible; }
+		/** @brief 是否可见。 */
+		bool Visible() const { return m_visible; }
+
+		/** @brief 当前悬停的控件（根节点维护）。 */
+		UiWidget* HoverWidget() const;
+
+		/** @brief 请求键盘焦点（根节点记录；键盘/字符事件沿焦点链派发）。 */
+		void RequestFocus();
+		/** @brief 释放焦点（**只有当前的焦点持有者**才会成功）。 */
+		void ReleaseFocus();
+		/** @brief 当前持有焦点的控件（无则 nullptr）。 */
+		UiWidget* FocusWidget() const;
+
+		// ------------------------------------------------------------------
+		// 动画
+		// ------------------------------------------------------------------
+
+		/**
+		 * @brief 推进动画。
+		 * @param [IN] nowMs 当前时间（`GetTickCount64()`）。
+		 * @return 仍有动画进行中返回 true（宿主据此保持定时器）。
+		 */
+		bool AdvanceAnimation(std::int64_t nowMs);
+		/** @brief 是否仍有动画（不推进）。 */
+		bool AnimationActive() const;
+
+	protected:
+		/** @brief 推进**自身**动画（派生类覆写；返回"我这一层是否仍需继续推进"）。 */
+		virtual bool AdvanceAnimationSelf(std::int64_t nowMs) { (void)nowMs; return false; }
+		/** @brief **自身**是否仍有动画（派生类覆写）。 */
+		virtual bool AnimationActiveSelf() const { return false; }
+
+		/** @brief 计算期望尺寸（派生类实现；**不得**修改子节点集合或自身矩形）。 */
+		virtual gd::SizeF OnMeasure(const UiMeasureContext& ctx) = 0;
+		/** @brief 自身矩形已更新：派生容器在这里摆放子节点。 */
+		virtual void OnArrange() {}
+		/** @brief 绘制自身（**不要**在这里遍历子节点；基类会负责）。 */
+		virtual void OnPaint(UiPaintContext& ctx) = 0;
+		/** @brief 自身处理事件（子节点都未消费时才会被调用）。 */
+		virtual UiEventResult OnEvent(UiEvent& event) { (void)event; return UiEventResult(); }
+		/** @brief 该位置的光标形态（nullptr = 不认领，交给下层/宿主）。 */
+		virtual HCURSOR OnQueryCursor(int x, int y) { (void)x; (void)y; return nullptr; }
+
+		/**
+		 * @brief 内容指纹（缓存键的**唯一来源**）。
+		 *
+		 * 派生类必须把"会改变像素的**全部**状态"混进来；父层只负责聚合子节点的键。
+		 * 漏字段的症状是"贴旧像素"（本项目历史上至少 4 次真实 BUG 都是这个原因）。
+		 */
+		virtual std::uint64_t ContentKey() const { return 0; }
+		/** @brief 基类能提供的那部分键（矩形/可见性）。 */
+		std::uint64_t BaseContentKey() const;
+
+		/** @brief 把子节点 `Measure` 一遍（派生容器在 `OnMeasure` 里调用）。 */
+		void MeasureChildren(const UiMeasureContext& ctx);
+		/** @brief 子节点的期望尺寸（需先 `MeasureChildren`）。 */
+		gd::SizeF ChildDesiredSize(std::size_t index) const;
+
+		/** @brief 命中测试：返回最上层（z 序末尾）且包含该点的子孙控件。 */
+		UiWidget* HitTestDeep(int x, int y);
+		/** @brief 悬停链变化通知（默认无操作；需要"指针进入/离开"语义的控件可覆写）。 */
+		virtual void OnHoverChanged(bool entered) { (void)entered; }
+
+	private:
+		/** @brief 沿命中链派发（位置事件）；非位置事件沿子树顺序派发。 */
+		UiEventResult DispatchAlongHitPath(UiEvent& event);
+		/**
+		 * @brief 命中链（自**最深**的命中节点开始，逐个回溯到本节点）。
+		 *
+		 * 只把事件交给"鼠标真正压住的那一条路径"，**绝不**分发给同层兄弟 ——
+		 * 否则一个点击可能同时被视觉上位于下方的控件处理（两层都改状态）。
+		 */
+		void CollectHitChain(int x, int y, std::vector<UiWidget*>& chain);
+		/** @brief 更新悬停链（只在根节点调用）。 */
+		void UpdateHover(int x, int y);
+		/** @brief 是否需要重绘（脏区与自身矩形求交）。 */
+		bool DirtyIntersects(const gd::RectF& dirty) const;
+
+		UiWidget* m_parent = nullptr;						/**< 父节点。 */
+		std::vector<std::unique_ptr<UiWidget>> m_children;	/**< 子节点（顺序 = z 序）。 */
+		gd::RectF m_bounds;									/**< 当前矩形（客户区坐标）。 */
+		gd::SizeF m_desiredSize;							/**< 期望尺寸。 */
+		gd::RectF m_dirty;									/**< 累计脏区（自身坐标系）。 */
+		bool m_visible = true;								/**< 是否可见。 */
+		bool m_hitTransparent = false;						/**< 是否命中透明。 */
+		bool m_measureValid = false;						/**< 期望尺寸是否有效。 */
+
+		// 根节点专用状态。
+		UiWidget* m_capture = nullptr;						/**< 鼠标捕获者。 */
+		UiWidget* m_modal = nullptr;						/**< 模态子树。 */
+		UiWidget* m_hover = nullptr;						/**< 当前悬停控件。 */		UiWidget* m_focus = nullptr;							/**< 键盘焦点控件。 */	};
+
+} // namespace jdi
+
+#endif // __UI_WIDGET_HPP__

Components/Shared/Src/UiLayout.cpp

@@ -0,0 +1,357 @@
+#include "UiLayout.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace jdi
+{
+
+	UiInsets UiInsets::All(float value)
+	{
+		UiInsets insets;
+		insets.left = value;
+		insets.top = value;
+		insets.right = value;
+		insets.bottom = value;
+		return insets;
+	}
+
+	UiInsets UiInsets::Symmetric(float horizontal, float vertical)
+	{
+		UiInsets insets;
+		insets.left = horizontal;
+		insets.right = horizontal;
+		insets.top = vertical;
+		insets.bottom = vertical;
+		return insets;
+	}
+
+	UiInsets UiInsets::Scaled(float scale) const
+	{
+		UiInsets insets;
+		insets.left = left * scale;
+		insets.top = top * scale;
+		insets.right = right * scale;
+		insets.bottom = bottom * scale;
+		return insets;
+	}
+
+	bool UiRectHasArea(const gd::RectF& rect)
+	{
+		return rect.Width > 0.0f && rect.Height > 0.0f;
+	}
+
+	bool UiRectIntersect(const gd::RectF& a, const gd::RectF& b, gd::RectF& out)
+	{
+		if (!UiRectHasArea(a) || !UiRectHasArea(b))
+		{
+			out = gd::RectF();
+			return false;
+		}
+		const float left = std::max(a.X, b.X);
+		const float top = std::max(a.Y, b.Y);
+		const float right = std::min(a.X + a.Width, b.X + b.Width);
+		const float bottom = std::min(a.Y + a.Height, b.Y + b.Height);
+		if (right <= left || bottom <= top)
+		{
+			out = gd::RectF();
+			return false;
+		}
+		out = gd::RectF(left, top, right - left, bottom - top);
+		return true;
+	}
+
+	gd::RectF UiRectUnion(const gd::RectF& a, const gd::RectF& b)
+	{
+		if (!UiRectHasArea(a))
+		{
+			return b;
+		}
+		if (!UiRectHasArea(b))
+		{
+			return a;
+		}
+		const float left = std::min(a.X, b.X);
+		const float top = std::min(a.Y, b.Y);
+		const float right = std::max(a.X + a.Width, b.X + b.Width);
+		const float bottom = std::max(a.Y + a.Height, b.Y + b.Height);
+		return gd::RectF(left, top, right - left, bottom - top);
+	}
+
+	gd::RectF UiRectDeflate(const gd::RectF& rect, const UiInsets& insets)
+	{
+		const float width = rect.Width - insets.Horizontal();
+		const float height = rect.Height - insets.Vertical();
+		if (width <= 0.0f || height <= 0.0f)
+		{
+			return gd::RectF();
+		}
+		return gd::RectF(rect.X + insets.left, rect.Y + insets.top, width, height);
+	}
+
+	gd::RectF UiRectSnapInward(const gd::RectF& rect, float scale)
+	{
+		const float safeScale = (scale > 0.0f) ? scale : 1.0f;
+		const float x0 = std::ceil(rect.X * safeScale - 0.001f) / safeScale;
+		const float y0 = std::ceil(rect.Y * safeScale - 0.001f) / safeScale;
+		const float x1 = std::floor((rect.X + rect.Width) * safeScale + 0.001f) / safeScale;
+		const float y1 = std::floor((rect.Y + rect.Height) * safeScale + 0.001f) / safeScale;
+		if (x1 <= x0 || y1 <= y0)
+		{
+			return gd::RectF();
+		}
+		return gd::RectF(x0, y0, x1 - x0, y1 - y0);
+	}
+
+	gd::RectF UiAlignInRect(const gd::RectF& outer, float width, float height, UiAlign horizontal,
+	                        UiAlign vertical, float offsetX, float offsetY)
+	{
+		float boxWidth = width;
+		float boxHeight = height;
+		if (horizontal == UiAlign::STRETCH)
+		{
+			boxWidth = outer.Width;
+		}
+		if (vertical == UiAlign::STRETCH)
+		{
+			boxHeight = outer.Height;
+		}
+		boxWidth = std::min(boxWidth, outer.Width);
+		boxHeight = std::min(boxHeight, outer.Height);
+
+		float x = outer.X;
+		switch (horizontal)
+		{
+		case UiAlign::CENTER:
+			x = outer.X + (outer.Width - boxWidth) * 0.5f;
+			break;
+		case UiAlign::END:
+			x = outer.X + outer.Width - boxWidth;
+			break;
+		default:
+			break;
+		}
+		float y = outer.Y;
+		switch (vertical)
+		{
+		case UiAlign::CENTER:
+			y = outer.Y + (outer.Height - boxHeight) * 0.5f;
+			break;
+		case UiAlign::END:
+			y = outer.Y + outer.Height - boxHeight;
+			break;
+		default:
+			break;
+		}
+		return gd::RectF(x + offsetX, y + offsetY, boxWidth, boxHeight);
+	}
+
+	float UiStackExtent(const std::vector<float>& sizes, float gap)
+	{
+		float total = 0.0f;
+		std::size_t fixedCount = 0;
+		for (float size : sizes)
+		{
+			if (size >= 0.0f)
+			{
+				total += size;
+				++fixedCount;
+			}
+		}
+		if (fixedCount > 0 && sizes.size() > 1)
+		{
+			total += gap * static_cast<float>(sizes.size() - 1);
+		}
+		return total;
+	}
+
+	void UiStackRects(const gd::RectF& area, UiAxis axis, const std::vector<float>& sizes, float gap,
+	                  std::vector<gd::RectF>& out, float* usedExtent)
+	{
+		out.clear();
+		if (sizes.empty())
+		{
+			if (usedExtent != nullptr)
+			{
+				*usedExtent = 0.0f;
+			}
+			return;
+		}
+		const bool horizontal = (axis == UiAxis::HORIZONTAL);
+		const float totalExtent = horizontal ? area.Width : area.Height;
+		const float totalGap = (sizes.size() > 1) ? gap * static_cast<float>(sizes.size() - 1) : 0.0f;
+		const float fixedExtent = UiStackExtent(sizes, gap) - totalGap;
+
+		std::size_t autoCount = 0;
+		for (float size : sizes)
+		{
+			if (size < 0.0f)
+			{
+				++autoCount;
+			}
+		}
+		// 剩余空间不足时按 0 处理（**不允许**出现负尺寸：负宽高的矩形会画出反向的线）。
+		const float remaining = std::max(0.0f, totalExtent - fixedExtent - totalGap);
+		const float autoExtent = (autoCount > 0) ? (remaining / static_cast<float>(autoCount)) : 0.0f;
+
+		float cursor = horizontal ? area.X : area.Y;
+		out.reserve(sizes.size());
+		for (std::size_t index = 0; index < sizes.size(); ++index)
+		{
+			const float extent = (sizes[index] < 0.0f) ? autoExtent : std::max(0.0f, sizes[index]);
+			if (horizontal)
+			{
+				out.push_back(gd::RectF(cursor, area.Y, extent, area.Height));
+			}
+			else
+			{
+				out.push_back(gd::RectF(area.X, cursor, area.Width, extent));
+			}
+			cursor += extent;
+			if (index + 1 < sizes.size())
+			{
+				cursor += gap;
+			}
+		}
+		if (usedExtent != nullptr)
+		{
+			*usedExtent = cursor - (horizontal ? area.X : area.Y);
+		}
+	}
+
+	float UiFlowRects(const gd::RectF& area, UiAxis axis, const std::vector<gd::SizeF>& sizes, float gap,
+	                  std::vector<gd::RectF>& out, std::size_t& overflow)
+	{
+		out.clear();
+		overflow = sizes.size();
+		if (sizes.empty())
+		{
+			return 0.0f;
+		}
+		const bool horizontal = (axis == UiAxis::HORIZONTAL);
+		const float mainExtent = horizontal ? area.Width : area.Height;
+		const float crossExtent = horizontal ? area.Height : area.Width;
+
+		float main = 0.0f;			// 当前行内已用主轴长度
+		float cross = 0.0f;			// 当前行起点（交叉轴）
+		float lineCross = 0.0f;		// 当前行最大交叉尺寸
+		out.reserve(sizes.size());
+
+		for (std::size_t index = 0; index < sizes.size(); ++index)
+		{
+			const float itemMain = horizontal ? sizes[index].Width : sizes[index].Height;
+			const float itemCross = horizontal ? sizes[index].Height : sizes[index].Width;
+			const float needed = (main > 0.0f) ? (main + gap + itemMain) : itemMain;
+			if (needed > mainExtent && main > 0.0f)
+			{
+				// 换行
+				cross += lineCross + gap;
+				main = 0.0f;
+				lineCross = 0.0f;
+			}
+			if (itemMain > mainExtent || cross + itemCross > crossExtent)
+			{
+				overflow = index;
+				break;
+			}
+			const float offset = (main > 0.0f) ? (main + gap) : 0.0f;
+			const float x = horizontal ? (area.X + offset) : (area.X + cross);
+			const float y = horizontal ? (area.Y + cross) : (area.Y + offset);
+			out.push_back(gd::RectF(x, y, horizontal ? itemMain : itemCross,
+			                        horizontal ? itemCross : itemMain));
+			main += offset + itemMain;
+			lineCross = std::max(lineCross, itemCross);
+		}
+		return cross + lineCross;
+	}
+
+	gd::RectF UiAbsRect(const gd::RectF& outer, float dx, float dy, float width, float height)
+	{
+		return gd::RectF(outer.X + dx, outer.Y + dy, std::max(0.0f, width), std::max(0.0f, height));
+	}
+
+	std::uint64_t UiMixKey(std::uint64_t seed, std::uint64_t value)
+	{
+		// FNV-1a 64 位的一份变体：与项目里其它指纹（SceneContentHash 等）同一风格。
+		seed ^= value + 0x9E3779B97F4A7C15ull + (seed << 6) + (seed >> 2);
+		return seed;
+	}
+
+	std::uint64_t UiMixKeyFloat(std::uint64_t seed, float value)
+	{
+		// 量化到 1/1024 逻辑像素：亚像素抖动不应该让布局缓存反复失效。
+		const long long quantized = static_cast<long long>(std::llround(value * 1024.0f));
+		return UiMixKey(seed, static_cast<std::uint64_t>(quantized));
+	}
+
+	UiLayoutCache::UiLayoutCache(std::size_t capacity)
+	    : m_capacity(std::max<std::size_t>(1, capacity))
+	{
+	}
+
+	const UiLayoutResult* UiLayoutCache::Find(std::uint64_t key)
+	{
+		for (UiLayoutResult& entry : m_entries)
+		{
+			if (entry.key == key)
+			{
+				entry.stamp = ++m_stamp;
+				return &entry;
+			}
+		}
+		return nullptr;
+	}
+
+	const UiLayoutResult& UiLayoutCache::Store(UiLayoutResult result)
+	{
+		for (UiLayoutResult& entry : m_entries)
+		{
+			if (entry.key == result.key)
+			{
+				entry = std::move(result);
+				entry.stamp = ++m_stamp;
+				return entry;
+			}
+		}
+		result.stamp = ++m_stamp;
+		m_entries.push_back(std::move(result));
+		Trim();
+		// 淘汰只会从队首进行，而新条目在队尾 ⇒ 刚存入的条目一定仍然有效。
+		return m_entries.back();
+	}
+
+	void UiLayoutCache::Invalidate(std::uint64_t key)
+	{
+		for (auto iterator = m_entries.begin(); iterator != m_entries.end(); ++iterator)
+		{
+			if (iterator->key == key)
+			{
+				m_entries.erase(iterator);
+				return;
+			}
+		}
+	}
+
+	void UiLayoutCache::Clear()
+	{
+		m_entries.clear();
+	}
+
+	void UiLayoutCache::Trim()
+	{
+		while (m_entries.size() > m_capacity)
+		{
+			// 淘汰"最久未被命中"的条目（stamp 最小）。
+			auto oldest = m_entries.begin();
+			for (auto iterator = m_entries.begin(); iterator != m_entries.end(); ++iterator)
+			{
+				if (iterator->stamp < oldest->stamp)
+				{
+					oldest = iterator;
+				}
+			}
+			m_entries.erase(oldest);
+		}
+	}
+
+} // namespace jdi

Components/Shared/Src/UiWidget.cpp

@@ -0,0 +1,614 @@
+#include "UiWidget.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace jdi
+{
+
+	UiEventResult UiEventResult::Handled()
+	{
+		UiEventResult result;
+		result.consumed = true;
+		result.redraw = true;
+		return result;
+	}
+
+	UiEventResult UiEventResult::Swallowed()
+	{
+		UiEventResult result;
+		result.consumed = true;
+		result.redraw = false;
+		return result;
+	}
+
+	UiPaintContext UiPaintContext::WithClip(const gd::RectF& rect) const
+	{
+		UiPaintContext child = *this;
+		gd::RectF intersection;
+		if (UiRectIntersect(clip, rect, intersection))
+		{
+			child.clip = intersection;
+		}
+		else
+		{
+			child.clip = gd::RectF();
+		}
+		return child;
+	}
+
+	UiWidget::UiWidget() = default;
+
+	UiWidget::~UiWidget()
+	{
+		// 子节点析构前先把"指向自己的根级状态"清掉：否则根的 m_capture / m_modal / m_hover
+		// 会留下悬空指针（子节点被移除后又被派发事件 = 访问违例）。
+		UiWidget* root = Root();
+		if (root != nullptr && root != this)
+		{
+			if (root->m_capture == this)
+			{
+				root->m_capture = nullptr;
+			}
+			if (root->m_modal == this)
+			{
+				root->m_modal = nullptr;
+			}
+			if (root->m_hover == this)
+			{
+				root->m_hover = nullptr;
+			}
+		}
+	}
+
+	// ------------------------------------------------------------------
+	// 树结构
+	// ------------------------------------------------------------------
+
+	UiWidget& UiWidget::AddChild(std::unique_ptr<UiWidget> child)
+	{
+		if (child == nullptr)
+		{
+			return *this;
+		}
+		UiWidget* raw = child.get();
+		raw->m_parent = this;
+		m_children.push_back(std::move(child));
+		// 子节点的期望尺寸会影响自己 ⇒ 向上失效。
+		InvalidateMeasure();
+		return *this;
+	}
+
+	void UiWidget::RemoveChild(UiWidget* child)
+	{
+		if (child == nullptr)
+		{
+			return;
+		}
+		for (auto iterator = m_children.begin(); iterator != m_children.end(); ++iterator)
+		{
+			if (iterator->get() == child)
+			{
+				(*iterator)->m_parent = nullptr;
+				m_children.erase(iterator);
+				InvalidateMeasure();
+				return;
+			}
+		}
+	}
+
+	UiWidget* UiWidget::Root()
+	{
+		UiWidget* node = this;
+		while (node->m_parent != nullptr)
+		{
+			node = node->m_parent;
+		}
+		return node;
+	}
+
+	const UiWidget* UiWidget::Root() const
+	{
+		const UiWidget* node = this;
+		while (node->m_parent != nullptr)
+		{
+			node = node->m_parent;
+		}
+		return node;
+	}
+
+	// ------------------------------------------------------------------
+	// 布局
+	// ------------------------------------------------------------------
+
+	void UiWidget::InvalidateMeasure()
+	{
+		if (!m_measureValid)
+		{
+			// 已经失效 ⇒ 不必继续上溯（祖先此前也一定被失效过）。
+			return;
+		}
+		m_measureValid = false;
+		if (m_parent != nullptr)
+		{
+			m_parent->InvalidateMeasure();
+		}
+	}
+
+	gd::SizeF UiWidget::Measure(const UiMeasureContext& ctx)
+	{
+		const gd::SizeF size = m_measureValid ? m_desiredSize : OnMeasure(ctx);
+		m_desiredSize = size;
+		m_measureValid = true;
+		return m_desiredSize;
+	}
+
+	void UiWidget::Arrange(const gd::RectF& bounds)
+	{
+		m_bounds = bounds;
+		OnArrange();
+	}
+
+	void UiWidget::MeasureChildren(const UiMeasureContext& ctx)
+	{
+		for (const std::unique_ptr<UiWidget>& child : m_children)
+		{
+			if (child == nullptr || !child->m_visible)
+			{
+				continue;
+			}
+			child->Measure(ctx);
+		}
+	}
+
+	gd::SizeF UiWidget::ChildDesiredSize(std::size_t index) const
+	{
+		if (index >= m_children.size() || m_children[index] == nullptr)
+		{
+			return gd::SizeF(0.0f, 0.0f);
+		}
+		return m_children[index]->m_desiredSize;
+	}
+
+	// ------------------------------------------------------------------
+	// 绘制
+	// ------------------------------------------------------------------
+
+	bool UiWidget::DirtyIntersects(const gd::RectF& dirty) const
+	{
+		gd::RectF intersection;
+		return UiRectIntersect(dirty, m_bounds, intersection);
+	}
+
+	void UiWidget::Paint(UiPaintContext& ctx)
+	{
+		if (!m_visible || ctx.g == nullptr || !UiRectHasArea(m_bounds))
+		{
+			return;
+		}
+
+		// (1) 与脏区求交：**脏区为空表示"未知 ⇒ 全画"**。
+		gd::RectF effectiveDirty = ctx.dirty;
+		if (UiRectHasArea(effectiveDirty) && !DirtyIntersects(effectiveDirty))
+		{
+			// 本节点及其整棵子树都不在脏区内 ⇒ 直接跳过（这是本框架唯一真正省时间的机制）。
+			return;
+		}
+
+		// (2) 裁剪 = 祖先裁剪切 ∩ 自身矩形；脏区非空时再与脏区求交（只更新需要更新的部分）。
+		UiPaintContext local = ctx;
+		gd::RectF clip;
+		if (!UiRectIntersect(ctx.clip, m_bounds, clip))
+		{
+			return;		// 完全被祖先裁掉
+		}
+		if (UiRectHasArea(effectiveDirty))
+		{
+			gd::RectF clipWithDirty;
+			if (!UiRectIntersect(clip, effectiveDirty, clipWithDirty))
+			{
+				return;
+			}
+			clip = clipWithDirty;
+		}
+		local.clip = clip;
+
+		// (3) 收紧 GDI+ 裁剪。⚠️ 这里**只**约束 GDI+ 矢量绘制；GDI 绘制（`UiText` /
+		//     `UiFillRect` 的快路径 / `UiDrawSolidLines`）**不受**该裁剪约束 ⇒ 派生类必须把
+		//     `local.clip` 传给 `UiTextClipped` 一类带 `ETO_CLIPPED` 的辅助函数，
+		//     否则文字会画到本节点之外（本项目"滚动时文字串到标题栏/工具栏"就是这类 BUG）。
+		const int saveState = ctx.g->Save();
+		ctx.g->SetClip(local.clip, gd::CombineModeIntersect);
+
+		local.dirty = UiRectHasArea(effectiveDirty) ? clip : gd::RectF();
+		OnPaint(local);
+
+		// (4) 子节点：顺序 = z 序（末尾最上层），脏区向下取交集。
+		for (const std::unique_ptr<UiWidget>& child : m_children)
+		{
+			if (child == nullptr)
+			{
+				continue;
+			}
+			UiPaintContext childContext = local.WithClip(child->m_bounds);
+			childContext.dirty = local.dirty;
+			child->Paint(childContext);
+		}
+
+		ctx.g->Restore(saveState);
+	}
+
+	void UiWidget::Invalidate(const gd::RectF& rect)
+	{
+		if (!UiRectHasArea(rect))
+		{
+			return;
+		}
+		m_dirty = UiRectUnion(m_dirty, rect);
+		if (m_parent != nullptr)
+		{
+			// 向上冒泡的是"客户区坐标"的同一块矩形；父层只并集，**不清空**子节点的脏区。
+			m_parent->Invalidate(rect);
+		}
+	}
+
+	void UiWidget::InvalidateAll()
+	{
+		m_dirty = m_bounds;
+		if (m_parent != nullptr)
+		{
+			m_parent->Invalidate(m_bounds);
+		}
+		for (const std::unique_ptr<UiWidget>& child : m_children)
+		{
+			if (child != nullptr)
+			{
+				child->InvalidateAll();
+			}
+		}
+	}
+
+	gd::RectF UiWidget::TakeDirty()
+	{
+		const gd::RectF dirty = m_dirty;
+		m_dirty = gd::RectF();
+		return dirty;
+	}
+
+	// ------------------------------------------------------------------
+	// 事件
+	// ------------------------------------------------------------------
+
+	bool UiWidget::Contains(int x, int y) const
+	{
+		if (!m_visible || m_hitTransparent || !UiRectHasArea(m_bounds))
+		{
+			return false;
+		}
+		const float fx = static_cast<float>(x);
+		const float fy = static_cast<float>(y);
+		return fx >= m_bounds.X && fx < m_bounds.X + m_bounds.Width && fy >= m_bounds.Y &&
+		       fy < m_bounds.Y + m_bounds.Height;
+	}
+
+	UiWidget* UiWidget::HitTestDeep(int x, int y)
+	{
+		if (!Contains(x, y))
+		{
+			return nullptr;
+		}
+		// 反 z 序：末尾（最上层）优先。
+		for (auto iterator = m_children.rbegin(); iterator != m_children.rend(); ++iterator)
+		{
+			if (*iterator == nullptr)
+			{
+				continue;
+			}
+			if (UiWidget* hit = (*iterator)->HitTestDeep(x, y))
+			{
+				return hit;
+			}
+		}
+		return this;
+	}
+
+	UiEventResult UiWidget::Dispatch(UiEvent& event)
+	{
+		UiWidget* root = Root();
+		if (root == nullptr)
+		{
+			return UiEventResult();
+		}
+
+		const bool mouseEvent = (event.kind == UiEventKind::MOUSE_MOVE ||
+		                         event.kind == UiEventKind::MOUSE_DOWN ||
+		                         event.kind == UiEventKind::MOUSE_UP ||
+		                         event.kind == UiEventKind::MOUSE_DOUBLE_CLICK ||
+		                         event.kind == UiEventKind::MOUSE_WHEEL ||
+		                         event.kind == UiEventKind::QUERY_CURSOR);
+
+		// (1) 捕获优先：拖拽期间所有鼠标事件直接投给捕获者（与 Windows `SetCapture` 同义）。
+		if (mouseEvent && root->m_capture != nullptr)
+		{
+			return root->m_capture->OnEvent(event);
+		}
+
+		// (2) 模态：只向模态子树派发（菜单/拾色器等浮层）。
+		if (root->m_modal != nullptr)
+		{
+			return root->m_modal->DispatchAlongHitPath(event);
+		}
+
+		// (3) 悬停链（只在根节点维护：鼠标移动会改变悬停者）。
+		if (event.kind == UiEventKind::MOUSE_MOVE || event.kind == UiEventKind::MOUSE_LEAVE)
+		{
+			root->UpdateHover(event.x, event.y);
+		}
+
+		// (4) 键盘/字符：沿焦点链派发（无焦点时交给根，保证宿主级快捷键仍可用）。
+		if (event.kind == UiEventKind::KEY_DOWN || event.kind == UiEventKind::CHAR)
+		{
+			UiWidget* node = (root->m_focus != nullptr) ? root->m_focus : root;
+			for (; node != nullptr; node = node->m_parent)
+			{
+				UiEventResult result = node->OnEvent(event);
+				if (result.consumed)
+				{
+					return result;
+				}
+			}
+			return UiEventResult();
+		}
+
+		return DispatchAlongHitPath(event);
+	}
+
+	void UiWidget::CollectHitChain(int x, int y, std::vector<UiWidget*>& chain)
+	{
+		if (!Contains(x, y))
+		{
+			return;
+		}
+		chain.push_back(this);
+		// 反 z 序：末尾（最上层）优先；只进入**真正命中**的那一个子节点。
+		for (auto iterator = m_children.rbegin(); iterator != m_children.rend(); ++iterator)
+		{
+			if (*iterator == nullptr)
+			{
+				continue;
+			}
+			if ((*iterator)->Contains(x, y))
+			{
+				(*iterator)->CollectHitChain(x, y, chain);
+				return;
+			}
+		}
+	}
+
+	UiEventResult UiWidget::DispatchAlongHitPath(UiEvent& event)
+	{
+		if (!m_visible)
+		{
+			return UiEventResult();
+		}
+
+		const bool positional = (event.kind == UiEventKind::MOUSE_MOVE ||
+		                         event.kind == UiEventKind::MOUSE_DOWN ||
+		                         event.kind == UiEventKind::MOUSE_UP ||
+		                         event.kind == UiEventKind::MOUSE_DOUBLE_CLICK ||
+		                         event.kind == UiEventKind::MOUSE_WHEEL ||
+		                         event.kind == UiEventKind::QUERY_CURSOR);
+
+		if (!positional)
+		{
+			// 非位置事件（理论上已被 `Dispatch` 分流）：自身优先，再逐个子节点。
+			UiEventResult result = OnEvent(event);
+			if (result.consumed)
+			{
+				return result;
+			}
+			for (const std::unique_ptr<UiWidget>& child : m_children)
+			{
+				if (child == nullptr || !child->m_visible)
+				{
+					continue;
+				}
+				result = child->DispatchAlongHitPath(event);
+				if (result.consumed)
+				{
+					return result;
+				}
+			}
+			return UiEventResult();
+		}
+
+		std::vector<UiWidget*> chain;
+		CollectHitChain(event.x, event.y, chain);
+		if (chain.empty())
+		{
+			return UiEventResult();
+		}
+
+		// 自最深的命中节点向上冒泡：命中者优先，未消费才交给祖先（合法的"兜底"语义）。
+		for (UiWidget* node : chain)
+		{
+			if (event.kind == UiEventKind::QUERY_CURSOR)
+			{
+				if (HCURSOR cursor = node->OnQueryCursor(event.x, event.y))
+				{
+					event.cursor = cursor;
+					return UiEventResult::Swallowed();
+				}
+				continue;
+			}
+			UiEventResult result = node->OnEvent(event);
+			if (result.consumed)
+			{
+				return result;
+			}
+		}
+		if (event.kind == UiEventKind::QUERY_CURSOR && event.cursor != nullptr)
+		{
+			return UiEventResult::Swallowed();
+		}
+		return UiEventResult();
+	}
+
+	void UiWidget::UpdateHover(int x, int y)
+	{
+		UiWidget* target = (m_visible) ? HitTestDeep(x, y) : nullptr;
+		if (target == m_hover)
+		{
+			return;
+		}
+		UiWidget* previous = m_hover;
+		m_hover = target;
+		if (previous != nullptr)
+		{
+			previous->OnHoverChanged(false);
+			previous->Invalidate(previous->m_bounds);
+		}
+		if (target != nullptr)
+		{
+			target->OnHoverChanged(true);
+			target->Invalidate(target->m_bounds);
+		}
+	}
+
+	// ------------------------------------------------------------------
+	// 交互仲裁
+	// ------------------------------------------------------------------
+
+	void UiWidget::CaptureMouse()
+	{
+		UiWidget* root = Root();
+		if (root != nullptr)
+		{
+			root->m_capture = this;
+		}
+	}
+
+	void UiWidget::ReleaseMouse()
+	{
+		UiWidget* root = Root();
+		if (root != nullptr && root->m_capture == this)
+		{
+			root->m_capture = nullptr;
+		}
+	}
+
+	UiWidget* UiWidget::MouseCaptureWidget() const
+	{
+		const UiWidget* root = Root();
+		return (root != nullptr) ? root->m_capture : nullptr;
+	}
+
+	void UiWidget::SetModal(bool modal)
+	{
+		UiWidget* root = Root();
+		if (root == nullptr)
+		{
+			return;
+		}
+		if (modal)
+		{
+			root->m_modal = this;
+		}
+		else if (root->m_modal == this)
+		{
+			root->m_modal = nullptr;
+		}
+	}
+
+	UiWidget* UiWidget::ModalWidget() const
+	{
+		const UiWidget* root = Root();
+		return (root != nullptr) ? root->m_modal : nullptr;
+	}
+
+	UiWidget* UiWidget::HoverWidget() const
+	{
+		const UiWidget* root = Root();
+		return (root != nullptr) ? root->m_hover : nullptr;
+	}
+
+	void UiWidget::RequestFocus()
+	{
+		UiWidget* root = Root();
+		if (root == nullptr || root->m_focus == this)
+		{
+			return;
+		}
+		if (root->m_focus != nullptr)
+		{
+			root->m_focus->Invalidate(root->m_focus->m_bounds);
+		}
+		root->m_focus = this;
+		Invalidate(m_bounds);
+	}
+
+	void UiWidget::ReleaseFocus()
+	{
+		UiWidget* root = Root();
+		if (root != nullptr && root->m_focus == this)
+		{
+			root->m_focus = nullptr;
+			Invalidate(m_bounds);
+		}
+	}
+
+	UiWidget* UiWidget::FocusWidget() const
+	{
+		const UiWidget* root = Root();
+		return (root != nullptr) ? root->m_focus : nullptr;
+	}
+
+	// ------------------------------------------------------------------
+	// 动画
+	// ------------------------------------------------------------------
+
+	bool UiWidget::AdvanceAnimation(std::int64_t nowMs)
+	{
+		bool active = AdvanceAnimationSelf(nowMs);
+		for (const std::unique_ptr<UiWidget>& child : m_children)
+		{
+			if (child != nullptr && child->AdvanceAnimation(nowMs))
+			{
+				active = true;
+			}
+		}
+		return active;
+	}
+
+	bool UiWidget::AnimationActive() const
+	{
+		if (AnimationActiveSelf())
+		{
+			return true;
+		}
+		for (const std::unique_ptr<UiWidget>& child : m_children)
+		{
+			if (child != nullptr && child->AnimationActive())
+			{
+				return true;
+			}
+		}
+		return false;
+	}
+
+	// ------------------------------------------------------------------
+	// 缓存键
+	// ------------------------------------------------------------------
+
+	std::uint64_t UiWidget::BaseContentKey() const
+	{
+		std::uint64_t key = 0xCBF29CE484222325ull;
+		key = UiMixKeyFloat(key, m_bounds.X);
+		key = UiMixKeyFloat(key, m_bounds.Y);
+		key = UiMixKeyFloat(key, m_bounds.Width);
+		key = UiMixKeyFloat(key, m_bounds.Height);
+		key = UiMixKey(key, m_visible ? 1u : 0u);
+		return key;
+	}
+
+} // namespace jdi