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/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