chore: snapshot editor work and restore tests

Key points:\n- restore the tests tree removed by bc47e6e\n- capture current editor workspace, scene, and docs reshuffle changes\n- keep local cloud.nvdb resources ignored from this commit
2026-04-25 22:11:47 +08:00
parent 9ab1beb2c4
commit 12b71a319f
911 changed files with 3518184 additions and 1823 deletions
--- a/tests/UI/Core/integration/shared/CMakeLists.txt
+++ b/tests/UI/Core/integration/shared/CMakeLists.txt
@@ -0,0 +1,65 @@
+file(TO_CMAKE_PATH "${CMAKE_SOURCE_DIR}" XCENGINE_CORE_UI_TESTS_REPO_ROOT_PATH)
+file(TO_CMAKE_PATH "${CMAKE_BINARY_DIR}" XCENGINE_CORE_UI_TESTS_BUILD_ROOT_PATH)
+
+add_library(core_ui_validation_registry STATIC
+    src/CoreValidationScenario.cpp
+)
+
+target_include_directories(core_ui_validation_registry
+    PUBLIC
+        ${CMAKE_CURRENT_SOURCE_DIR}/src
+        ${CMAKE_SOURCE_DIR}/engine/include
+)
+
+target_compile_definitions(core_ui_validation_registry
+    PUBLIC
+        XCENGINE_CORE_UI_TESTS_REPO_ROOT="${XCENGINE_CORE_UI_TESTS_REPO_ROOT_PATH}"
+)
+
+if(MSVC)
+    target_compile_options(core_ui_validation_registry PRIVATE /utf-8 /FS)
+    set_property(TARGET core_ui_validation_registry PROPERTY
+        MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+endif()
+
+target_link_libraries(core_ui_validation_registry
+    PUBLIC
+        XCEngine
+)
+
+add_library(core_ui_integration_host STATIC
+    src/AutoScreenshot.cpp
+    src/Application.cpp
+    src/DragDropValidationScene.cpp
+    src/NativeRenderer.cpp
+    src/PopupMenuOverlayValidationScene.cpp
+)
+
+target_include_directories(core_ui_integration_host
+    PUBLIC
+        ${CMAKE_CURRENT_SOURCE_DIR}/src
+        ${CMAKE_SOURCE_DIR}/engine/include
+)
+
+target_compile_definitions(core_ui_integration_host
+    PUBLIC
+        UNICODE
+        _UNICODE
+        XCENGINE_CORE_UI_TESTS_REPO_ROOT="${XCENGINE_CORE_UI_TESTS_REPO_ROOT_PATH}"
+        XCENGINE_CORE_UI_TESTS_BUILD_ROOT="${XCENGINE_CORE_UI_TESTS_BUILD_ROOT_PATH}"
+)
+
+if(MSVC)
+    target_compile_options(core_ui_integration_host PRIVATE /utf-8 /FS)
+    set_property(TARGET core_ui_integration_host PROPERTY
+        MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+endif()
+
+target_link_libraries(core_ui_integration_host
+    PUBLIC
+        core_ui_validation_registry
+        XCEngine
+        d2d1.lib
+        dwrite.lib
+        windowscodecs.lib
+)
--- a/tests/UI/Core/integration/shared/src/Application.cpp
+++ b/tests/UI/Core/integration/shared/src/Application.cpp
@@ -0,0 +1,874 @@
+#include "Application.h"
+
+#include <XCEngine/Input/InputTypes.h>
+
+#include <algorithm>
+#include <chrono>
+#include <filesystem>
+#include <sstream>
+#include <string>
+#include <system_error>
+#include <unordered_set>
+#include <vector>
+
+#ifndef XCENGINE_CORE_UI_TESTS_REPO_ROOT
+#define XCENGINE_CORE_UI_TESTS_REPO_ROOT "."
+#endif
+
+#ifndef XCENGINE_CORE_UI_TESTS_BUILD_ROOT
+#define XCENGINE_CORE_UI_TESTS_BUILD_ROOT "."
+#endif
+
+namespace XCEngine::Tests::CoreUI {
+
+namespace {
+
+using ::XCEngine::UI::UIColor;
+using ::XCEngine::UI::UIDrawData;
+using ::XCEngine::UI::UIDrawList;
+using ::XCEngine::UI::UIInputEvent;
+using ::XCEngine::UI::UIInputEventType;
+using ::XCEngine::UI::UIPoint;
+using ::XCEngine::UI::UIPointerButton;
+using ::XCEngine::UI::UIRect;
+using ::XCEngine::UI::Runtime::UIScreenFrameInput;
+using ::XCEngine::Input::KeyCode;
+
+constexpr const wchar_t* kWindowClassName = L"XCUICoreValidationHost";
+constexpr const wchar_t* kWindowTitle = L"XCUI Core Validation";
+constexpr auto kReloadPollInterval = std::chrono::milliseconds(150);
+
+constexpr UIColor kOverlayBgColor(0.10f, 0.10f, 0.10f, 0.95f);
+constexpr UIColor kOverlayBorderColor(0.25f, 0.25f, 0.25f, 1.0f);
+constexpr UIColor kOverlayTextPrimary(0.93f, 0.93f, 0.93f, 1.0f);
+constexpr UIColor kOverlayTextMuted(0.70f, 0.70f, 0.70f, 1.0f);
+constexpr UIColor kOverlaySuccess(0.82f, 0.82f, 0.82f, 1.0f);
+constexpr UIColor kOverlayFallback(0.56f, 0.56f, 0.56f, 1.0f);
+
+Application* GetApplicationFromWindow(HWND hwnd) {
+    return reinterpret_cast<Application*>(GetWindowLongPtrW(hwnd, GWLP_USERDATA));
+}
+
+std::filesystem::path GetRepoRootPath() {
+    std::string root = XCENGINE_CORE_UI_TESTS_REPO_ROOT;
+    if (root.size() >= 2u && root.front() == '"' && root.back() == '"') {
+        root = root.substr(1u, root.size() - 2u);
+    }
+    return std::filesystem::path(root).lexically_normal();
+}
+
+std::filesystem::path GetBuildRootPath() {
+    std::string root = XCENGINE_CORE_UI_TESTS_BUILD_ROOT;
+    if (root.size() >= 2u && root.front() == '"' && root.back() == '"') {
+        root = root.substr(1u, root.size() - 2u);
+    }
+    return std::filesystem::path(root).lexically_normal();
+}
+
+bool TryMakeRepoRelativePath(
+    const std::filesystem::path& absolutePath,
+    std::filesystem::path& outRelativePath) {
+    std::error_code errorCode = {};
+    outRelativePath = std::filesystem::relative(
+        absolutePath,
+        GetRepoRootPath(),
+        errorCode);
+    if (errorCode || outRelativePath.empty()) {
+        return false;
+    }
+
+    for (const auto& part : outRelativePath) {
+        if (part == "..") {
+            return false;
+        }
+    }
+    return true;
+}
+
+std::filesystem::path ResolveCaptureOutputRoot(
+    const std::filesystem::path& sourceCaptureRoot) {
+    const std::filesystem::path normalizedSourcePath =
+        sourceCaptureRoot.lexically_normal();
+    std::filesystem::path relativePath = {};
+    if (TryMakeRepoRelativePath(normalizedSourcePath, relativePath)) {
+        return (GetBuildRootPath() / relativePath).lexically_normal();
+    }
+
+    return (GetBuildRootPath() / "ui_test_captures" / normalizedSourcePath.filename())
+        .lexically_normal();
+}
+
+std::string TruncateText(const std::string& text, std::size_t maxLength) {
+    if (text.size() <= maxLength) {
+        return text;
+    }
+
+    if (maxLength <= 3u) {
+        return text.substr(0, maxLength);
+    }
+
+    return text.substr(0, maxLength - 3u) + "...";
+}
+
+std::string ExtractStateKeyTail(const std::string& stateKey) {
+    if (stateKey.empty()) {
+        return "-";
+    }
+
+    const std::size_t separator = stateKey.find_last_of('/');
+    if (separator == std::string::npos || separator + 1u >= stateKey.size()) {
+        return stateKey;
+    }
+
+    return stateKey.substr(separator + 1u);
+}
+
+std::string FormatFloat(float value) {
+    std::ostringstream stream;
+    stream.setf(std::ios::fixed, std::ios::floatfield);
+    stream.precision(1);
+    stream << value;
+    return stream.str();
+}
+
+std::string FormatPoint(const UIPoint& point) {
+    return "(" + FormatFloat(point.x) + ", " + FormatFloat(point.y) + ")";
+}
+
+std::string FormatRect(const UIRect& rect) {
+    return "(" + FormatFloat(rect.x) +
+        ", " + FormatFloat(rect.y) +
+        ", " + FormatFloat(rect.width) +
+        ", " + FormatFloat(rect.height) +
+        ")";
+}
+
+std::int32_t MapVirtualKeyToUIKeyCode(WPARAM wParam) {
+    switch (wParam) {
+    case 'A': return static_cast<std::int32_t>(KeyCode::A);
+    case 'B': return static_cast<std::int32_t>(KeyCode::B);
+    case 'C': return static_cast<std::int32_t>(KeyCode::C);
+    case 'D': return static_cast<std::int32_t>(KeyCode::D);
+    case 'E': return static_cast<std::int32_t>(KeyCode::E);
+    case 'F': return static_cast<std::int32_t>(KeyCode::F);
+    case 'G': return static_cast<std::int32_t>(KeyCode::G);
+    case 'H': return static_cast<std::int32_t>(KeyCode::H);
+    case 'I': return static_cast<std::int32_t>(KeyCode::I);
+    case 'J': return static_cast<std::int32_t>(KeyCode::J);
+    case 'K': return static_cast<std::int32_t>(KeyCode::K);
+    case 'L': return static_cast<std::int32_t>(KeyCode::L);
+    case 'M': return static_cast<std::int32_t>(KeyCode::M);
+    case 'N': return static_cast<std::int32_t>(KeyCode::N);
+    case 'O': return static_cast<std::int32_t>(KeyCode::O);
+    case 'P': return static_cast<std::int32_t>(KeyCode::P);
+    case 'Q': return static_cast<std::int32_t>(KeyCode::Q);
+    case 'R': return static_cast<std::int32_t>(KeyCode::R);
+    case 'S': return static_cast<std::int32_t>(KeyCode::S);
+    case 'T': return static_cast<std::int32_t>(KeyCode::T);
+    case 'U': return static_cast<std::int32_t>(KeyCode::U);
+    case 'V': return static_cast<std::int32_t>(KeyCode::V);
+    case 'W': return static_cast<std::int32_t>(KeyCode::W);
+    case 'X': return static_cast<std::int32_t>(KeyCode::X);
+    case 'Y': return static_cast<std::int32_t>(KeyCode::Y);
+    case 'Z': return static_cast<std::int32_t>(KeyCode::Z);
+    case '0': return static_cast<std::int32_t>(KeyCode::Zero);
+    case '1': return static_cast<std::int32_t>(KeyCode::One);
+    case '2': return static_cast<std::int32_t>(KeyCode::Two);
+    case '3': return static_cast<std::int32_t>(KeyCode::Three);
+    case '4': return static_cast<std::int32_t>(KeyCode::Four);
+    case '5': return static_cast<std::int32_t>(KeyCode::Five);
+    case '6': return static_cast<std::int32_t>(KeyCode::Six);
+    case '7': return static_cast<std::int32_t>(KeyCode::Seven);
+    case '8': return static_cast<std::int32_t>(KeyCode::Eight);
+    case '9': return static_cast<std::int32_t>(KeyCode::Nine);
+    case VK_SPACE: return static_cast<std::int32_t>(KeyCode::Space);
+    case VK_TAB: return static_cast<std::int32_t>(KeyCode::Tab);
+    case VK_RETURN: return static_cast<std::int32_t>(KeyCode::Enter);
+    case VK_ESCAPE: return static_cast<std::int32_t>(KeyCode::Escape);
+    case VK_SHIFT: return static_cast<std::int32_t>(KeyCode::LeftShift);
+    case VK_CONTROL: return static_cast<std::int32_t>(KeyCode::LeftCtrl);
+    case VK_MENU: return static_cast<std::int32_t>(KeyCode::LeftAlt);
+    case VK_UP: return static_cast<std::int32_t>(KeyCode::Up);
+    case VK_DOWN: return static_cast<std::int32_t>(KeyCode::Down);
+    case VK_LEFT: return static_cast<std::int32_t>(KeyCode::Left);
+    case VK_RIGHT: return static_cast<std::int32_t>(KeyCode::Right);
+    case VK_HOME: return static_cast<std::int32_t>(KeyCode::Home);
+    case VK_END: return static_cast<std::int32_t>(KeyCode::End);
+    case VK_PRIOR: return static_cast<std::int32_t>(KeyCode::PageUp);
+    case VK_NEXT: return static_cast<std::int32_t>(KeyCode::PageDown);
+    case VK_DELETE: return static_cast<std::int32_t>(KeyCode::Delete);
+    case VK_BACK: return static_cast<std::int32_t>(KeyCode::Backspace);
+    case VK_F1: return static_cast<std::int32_t>(KeyCode::F1);
+    case VK_F2: return static_cast<std::int32_t>(KeyCode::F2);
+    case VK_F3: return static_cast<std::int32_t>(KeyCode::F3);
+    case VK_F4: return static_cast<std::int32_t>(KeyCode::F4);
+    case VK_F5: return static_cast<std::int32_t>(KeyCode::F5);
+    case VK_F6: return static_cast<std::int32_t>(KeyCode::F6);
+    case VK_F7: return static_cast<std::int32_t>(KeyCode::F7);
+    case VK_F8: return static_cast<std::int32_t>(KeyCode::F8);
+    case VK_F9: return static_cast<std::int32_t>(KeyCode::F9);
+    case VK_F10: return static_cast<std::int32_t>(KeyCode::F10);
+    case VK_F11: return static_cast<std::int32_t>(KeyCode::F11);
+    case VK_F12: return static_cast<std::int32_t>(KeyCode::F12);
+    default: return static_cast<std::int32_t>(KeyCode::None);
+    }
+}
+
+bool IsRepeatKeyMessage(LPARAM lParam) {
+    return (static_cast<unsigned long>(lParam) & (1ul << 30)) != 0ul;
+}
+
+} // namespace
+
+Application::Application(std::string requestedScenarioId)
+    : m_screenPlayer(m_documentHost)
+    , m_requestedScenarioId(std::move(requestedScenarioId)) {
+}
+
+int Application::Run(HINSTANCE hInstance, int nCmdShow) {
+    if (!Initialize(hInstance, nCmdShow)) {
+        Shutdown();
+        return 1;
+    }
+
+    MSG message = {};
+    while (message.message != WM_QUIT) {
+        if (PeekMessageW(&message, nullptr, 0U, 0U, PM_REMOVE)) {
+            TranslateMessage(&message);
+            DispatchMessageW(&message);
+            continue;
+        }
+
+        RenderFrame();
+        Sleep(8);
+    }
+
+    Shutdown();
+    return static_cast<int>(message.wParam);
+}
+
+bool Application::Initialize(HINSTANCE hInstance, int nCmdShow) {
+    m_hInstance = hInstance;
+
+    WNDCLASSEXW windowClass = {};
+    windowClass.cbSize = sizeof(windowClass);
+    windowClass.style = CS_HREDRAW | CS_VREDRAW;
+    windowClass.lpfnWndProc = &Application::WndProc;
+    windowClass.hInstance = hInstance;
+    windowClass.hCursor = LoadCursorW(nullptr, IDC_ARROW);
+    windowClass.lpszClassName = kWindowClassName;
+
+    m_windowClassAtom = RegisterClassExW(&windowClass);
+    if (m_windowClassAtom == 0) {
+        return false;
+    }
+
+    m_hwnd = CreateWindowExW(
+        0,
+        kWindowClassName,
+        kWindowTitle,
+        WS_OVERLAPPEDWINDOW | WS_VISIBLE,
+        CW_USEDEFAULT,
+        CW_USEDEFAULT,
+        1440,
+        900,
+        nullptr,
+        nullptr,
+        hInstance,
+        this);
+    if (m_hwnd == nullptr) {
+        return false;
+    }
+
+    ShowWindow(m_hwnd, nCmdShow);
+    UpdateWindow(m_hwnd);
+
+    if (!m_renderer.Initialize(m_hwnd)) {
+        return false;
+    }
+
+    m_startTime = std::chrono::steady_clock::now();
+    m_lastFrameTime = m_startTime;
+    const CoreValidationScenario* initialScenario = m_requestedScenarioId.empty()
+        ? &GetDefaultCoreValidationScenario()
+        : FindCoreValidationScenario(m_requestedScenarioId);
+    if (initialScenario == nullptr) {
+        initialScenario = &GetDefaultCoreValidationScenario();
+    }
+    m_autoScreenshot.Initialize(
+        ResolveCaptureOutputRoot(initialScenario->captureRootPath));
+    LoadStructuredScreen("startup");
+    return true;
+}
+
+void Application::Shutdown() {
+    m_autoScreenshot.Shutdown();
+    m_screenPlayer.Unload();
+    m_trackedFiles.clear();
+    m_screenAsset = {};
+    m_useStructuredScreen = false;
+    m_runtimeStatus.clear();
+    m_runtimeError.clear();
+    m_frameIndex = 0;
+
+    m_renderer.Shutdown();
+
+    if (m_hwnd != nullptr && IsWindow(m_hwnd)) {
+        DestroyWindow(m_hwnd);
+    }
+    m_hwnd = nullptr;
+
+    if (m_windowClassAtom != 0 && m_hInstance != nullptr) {
+        UnregisterClassW(kWindowClassName, m_hInstance);
+        m_windowClassAtom = 0;
+    }
+}
+
+void Application::RenderFrame() {
+    if (m_hwnd == nullptr) {
+        return;
+    }
+
+    RECT clientRect = {};
+    GetClientRect(m_hwnd, &clientRect);
+    const float width = static_cast<float>((std::max)(clientRect.right - clientRect.left, 1L));
+    const float height = static_cast<float>((std::max)(clientRect.bottom - clientRect.top, 1L));
+
+    const auto now = std::chrono::steady_clock::now();
+    double deltaTimeSeconds = std::chrono::duration<double>(now - m_lastFrameTime).count();
+    if (deltaTimeSeconds <= 0.0) {
+        deltaTimeSeconds = 1.0 / 60.0;
+    }
+    m_lastFrameTime = now;
+
+    RefreshStructuredScreen();
+    std::vector<UIInputEvent> frameEvents = std::move(m_pendingInputEvents);
+    m_pendingInputEvents.clear();
+
+    UIDrawData drawData = {};
+    const UIRect viewportRect(0.0f, 0.0f, width, height);
+    const bool windowFocused = GetForegroundWindow() == m_hwnd;
+    if (m_activeScenario != nullptr &&
+        m_activeScenario->id == PopupMenuOverlayValidationScene::ScenarioId) {
+        m_popupMenuOverlayScene.Update(frameEvents, viewportRect, windowFocused);
+    }
+    if (m_activeScenario != nullptr &&
+        m_activeScenario->id == DragDropValidationScene::ScenarioId) {
+        m_dragDropValidationScene.Update(frameEvents, viewportRect, windowFocused);
+    }
+
+    if (m_useStructuredScreen && m_screenPlayer.IsLoaded()) {
+        UIScreenFrameInput input = {};
+        input.viewportRect = viewportRect;
+        input.events = std::move(frameEvents);
+        input.deltaTimeSeconds = deltaTimeSeconds;
+        input.frameIndex = ++m_frameIndex;
+        input.focused = windowFocused;
+
+        const auto& frame = m_screenPlayer.Update(input);
+        for (const auto& drawList : frame.drawData.GetDrawLists()) {
+            drawData.AddDrawList(drawList);
+        }
+
+        m_runtimeStatus = m_activeScenario != nullptr
+            ? m_activeScenario->displayName
+            : "Core UI Validation";
+        m_runtimeError = frame.errorMessage;
+    }
+
+    if (m_activeScenario != nullptr &&
+        m_activeScenario->id == PopupMenuOverlayValidationScene::ScenarioId) {
+        m_popupMenuOverlayScene.AppendDrawData(drawData, viewportRect);
+    }
+    if (m_activeScenario != nullptr &&
+        m_activeScenario->id == DragDropValidationScene::ScenarioId) {
+        m_dragDropValidationScene.AppendDrawData(drawData, viewportRect);
+    }
+
+    if (drawData.Empty()) {
+        m_runtimeStatus = "Core UI Validation | Load Error";
+        if (m_runtimeError.empty() && !m_screenPlayer.IsLoaded()) {
+            m_runtimeError = m_screenPlayer.GetLastError();
+        }
+    }
+
+    AppendRuntimeOverlay(drawData, width, height);
+
+    const bool framePresented = m_renderer.Render(drawData);
+    m_autoScreenshot.CaptureIfRequested(
+        m_renderer,
+        drawData,
+        static_cast<unsigned int>(width),
+        static_cast<unsigned int>(height),
+        framePresented);
+}
+
+void Application::OnResize(UINT width, UINT height) {
+    if (width == 0 || height == 0) {
+        return;
+    }
+
+    m_renderer.Resize(width, height);
+}
+
+void Application::QueuePointerEvent(UIInputEventType type, UIPointerButton button, WPARAM wParam, LPARAM lParam) {
+    UIInputEvent event = {};
+    event.type = type;
+    event.pointerButton = button;
+    event.position = UIPoint(
+        static_cast<float>(GET_X_LPARAM(lParam)),
+        static_cast<float>(GET_Y_LPARAM(lParam)));
+    event.modifiers = m_inputModifierTracker.BuildPointerModifiers(static_cast<size_t>(wParam));
+    m_pendingInputEvents.push_back(event);
+}
+
+void Application::QueuePointerLeaveEvent() {
+    UIInputEvent event = {};
+    event.type = UIInputEventType::PointerLeave;
+    if (m_hwnd != nullptr) {
+        POINT clientPoint = {};
+        GetCursorPos(&clientPoint);
+        ScreenToClient(m_hwnd, &clientPoint);
+        event.position = UIPoint(static_cast<float>(clientPoint.x), static_cast<float>(clientPoint.y));
+    }
+    m_pendingInputEvents.push_back(event);
+}
+
+void Application::QueuePointerWheelEvent(short wheelDelta, WPARAM wParam, LPARAM lParam) {
+    if (m_hwnd == nullptr) {
+        return;
+    }
+
+    POINT screenPoint = {
+        GET_X_LPARAM(lParam),
+        GET_Y_LPARAM(lParam)
+    };
+    ScreenToClient(m_hwnd, &screenPoint);
+
+    UIInputEvent event = {};
+    event.type = UIInputEventType::PointerWheel;
+    event.position = UIPoint(static_cast<float>(screenPoint.x), static_cast<float>(screenPoint.y));
+    event.wheelDelta = static_cast<float>(wheelDelta);
+    event.modifiers = m_inputModifierTracker.BuildPointerModifiers(static_cast<size_t>(wParam));
+    m_pendingInputEvents.push_back(event);
+}
+
+void Application::QueueKeyEvent(UIInputEventType type, WPARAM wParam, LPARAM lParam) {
+    UIInputEvent event = {};
+    event.type = type;
+    event.keyCode = MapVirtualKeyToUIKeyCode(wParam);
+    event.modifiers = m_inputModifierTracker.ApplyKeyMessage(type, wParam, lParam);
+    event.repeat = IsRepeatKeyMessage(lParam);
+    m_pendingInputEvents.push_back(event);
+}
+
+void Application::QueueCharacterEvent(WPARAM wParam, LPARAM) {
+    UIInputEvent event = {};
+    event.type = UIInputEventType::Character;
+    event.character = static_cast<std::uint32_t>(wParam);
+    event.modifiers = m_inputModifierTracker.GetCurrentModifiers();
+    m_pendingInputEvents.push_back(event);
+}
+
+void Application::QueueWindowFocusEvent(UIInputEventType type) {
+    UIInputEvent event = {};
+    event.type = type;
+    m_pendingInputEvents.push_back(event);
+}
+
+bool Application::LoadStructuredScreen(const char* triggerReason) {
+    (void)triggerReason;
+    std::string scenarioLoadWarning = {};
+    const CoreValidationScenario* scenario = m_requestedScenarioId.empty()
+        ? &GetDefaultCoreValidationScenario()
+        : FindCoreValidationScenario(m_requestedScenarioId);
+    if (scenario == nullptr) {
+        scenario = &GetDefaultCoreValidationScenario();
+        scenarioLoadWarning = "Unknown validation scenario: " + m_requestedScenarioId;
+    }
+
+    m_activeScenario = scenario;
+    m_screenAsset = {};
+    m_screenAsset.screenId = scenario->id;
+    m_screenAsset.documentPath = scenario->documentPath.string();
+    m_screenAsset.themePath = scenario->themePath.string();
+
+    const bool loaded = m_screenPlayer.Load(m_screenAsset);
+    m_useStructuredScreen = loaded;
+    m_runtimeStatus = loaded ? scenario->displayName : "Core UI Validation | Load Error";
+    m_runtimeError = loaded
+        ? scenarioLoadWarning
+        : (scenarioLoadWarning.empty()
+            ? m_screenPlayer.GetLastError()
+            : scenarioLoadWarning + " | " + m_screenPlayer.GetLastError());
+    m_dragDropValidationScene.Reset();
+    m_popupMenuOverlayScene.Reset();
+    RebuildTrackedFileStates();
+    return loaded;
+}
+
+void Application::RefreshStructuredScreen() {
+    const auto now = std::chrono::steady_clock::now();
+    if (m_lastReloadPollTime.time_since_epoch().count() != 0 &&
+        now - m_lastReloadPollTime < kReloadPollInterval) {
+        return;
+    }
+
+    m_lastReloadPollTime = now;
+    if (DetectTrackedFileChange()) {
+        LoadStructuredScreen("reload");
+    }
+}
+
+void Application::RebuildTrackedFileStates() {
+    namespace fs = std::filesystem;
+
+    m_trackedFiles.clear();
+    std::unordered_set<std::string> seenPaths = {};
+    std::error_code errorCode = {};
+
+    auto appendTrackedPath = [&](const std::string& rawPath) {
+        if (rawPath.empty()) {
+            return;
+        }
+
+        const fs::path normalizedPath = fs::path(rawPath).lexically_normal();
+        const std::string key = normalizedPath.string();
+        if (!seenPaths.insert(key).second) {
+            return;
+        }
+
+        TrackedFileState state = {};
+        state.path = normalizedPath;
+        state.exists = fs::exists(normalizedPath, errorCode);
+        errorCode.clear();
+        if (state.exists) {
+            state.writeTime = fs::last_write_time(normalizedPath, errorCode);
+            errorCode.clear();
+        }
+        m_trackedFiles.push_back(std::move(state));
+    };
+
+    appendTrackedPath(m_screenAsset.documentPath);
+    appendTrackedPath(m_screenAsset.themePath);
+
+    if (const auto* document = m_screenPlayer.GetDocument(); document != nullptr) {
+        for (const std::string& dependency : document->dependencies) {
+            appendTrackedPath(dependency);
+        }
+    }
+}
+
+bool Application::DetectTrackedFileChange() const {
+    namespace fs = std::filesystem;
+
+    std::error_code errorCode = {};
+    for (const TrackedFileState& trackedFile : m_trackedFiles) {
+        const bool existsNow = fs::exists(trackedFile.path, errorCode);
+        errorCode.clear();
+        if (existsNow != trackedFile.exists) {
+            return true;
+        }
+
+        if (!existsNow) {
+            continue;
+        }
+
+        const auto writeTimeNow = fs::last_write_time(trackedFile.path, errorCode);
+        errorCode.clear();
+        if (writeTimeNow != trackedFile.writeTime) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+void Application::AppendRuntimeOverlay(UIDrawData& drawData, float width, float height) const {
+    const bool authoredMode = m_useStructuredScreen && m_screenPlayer.IsLoaded();
+    const float panelWidth = authoredMode ? 460.0f : 360.0f;
+    std::vector<std::string> detailLines = {};
+    detailLines.push_back(
+        authoredMode
+            ? "Hot reload watches authored UI resources."
+            : "Authored validation scene failed to load.");
+    if (m_activeScenario != nullptr) {
+        detailLines.push_back("Scenario: " + m_activeScenario->id);
+    }
+
+    if (authoredMode) {
+        const auto& inputDebug = m_documentHost.GetInputDebugSnapshot();
+        const auto& scrollDebug = m_documentHost.GetScrollDebugSnapshot();
+        detailLines.push_back(
+            "Hover | Focus: " +
+            ExtractStateKeyTail(inputDebug.hoveredStateKey) +
+            " | " +
+            ExtractStateKeyTail(inputDebug.focusedStateKey));
+        detailLines.push_back(
+            "Active | Capture: " +
+            ExtractStateKeyTail(inputDebug.activeStateKey) +
+            " | " +
+            ExtractStateKeyTail(inputDebug.captureStateKey));
+        detailLines.push_back(
+            "Scope W/P/Wg: " +
+            ExtractStateKeyTail(inputDebug.windowScopeStateKey) +
+            " | " +
+            ExtractStateKeyTail(inputDebug.panelScopeStateKey) +
+            " | " +
+            ExtractStateKeyTail(inputDebug.widgetScopeStateKey));
+        detailLines.push_back(
+            std::string("Text input: ") +
+            (inputDebug.textInputActive ? "active" : "idle"));
+        if (!inputDebug.recentShortcutCommandId.empty()) {
+            detailLines.push_back(
+                "Recent shortcut: " +
+                inputDebug.recentShortcutScope +
+                " -> " +
+                inputDebug.recentShortcutCommandId);
+            detailLines.push_back(
+                std::string("Recent shortcut state: ") +
+                (inputDebug.recentShortcutHandled
+                    ? "handled"
+                    : (inputDebug.recentShortcutSuppressed ? "suppressed" : "observed")) +
+                " @ " +
+                ExtractStateKeyTail(inputDebug.recentShortcutOwnerStateKey));
+        } else {
+            detailLines.push_back("Recent shortcut: none");
+        }
+        if (!inputDebug.lastEventType.empty()) {
+            const std::string eventPosition = inputDebug.lastEventType == "KeyDown" ||
+                    inputDebug.lastEventType == "KeyUp" ||
+                    inputDebug.lastEventType == "Character" ||
+                    inputDebug.lastEventType == "FocusGained" ||
+                    inputDebug.lastEventType == "FocusLost"
+                ? std::string()
+                : " at " + FormatPoint(inputDebug.pointerPosition);
+            detailLines.push_back(
+                "Last input: " +
+                inputDebug.lastEventType +
+                eventPosition);
+            detailLines.push_back(
+                "Route: " +
+                inputDebug.lastTargetKind +
+                " -> " +
+                ExtractStateKeyTail(inputDebug.lastTargetStateKey));
+            if (!inputDebug.lastShortcutCommandId.empty()) {
+                detailLines.push_back(
+                    "Shortcut: " +
+                    inputDebug.lastShortcutScope +
+                    " -> " +
+                    inputDebug.lastShortcutCommandId);
+                detailLines.push_back(
+                    std::string("Shortcut state: ") +
+                    (inputDebug.lastShortcutHandled
+                        ? "handled"
+                        : (inputDebug.lastShortcutSuppressed ? "suppressed" : "observed")) +
+                    " @ " +
+                    ExtractStateKeyTail(inputDebug.lastShortcutOwnerStateKey));
+            }
+            detailLines.push_back(
+                "Last event result: " +
+                (inputDebug.lastResult.empty() ? std::string("n/a") : inputDebug.lastResult));
+        }
+        detailLines.push_back(
+            "Scroll target | Primary: " +
+            ExtractStateKeyTail(scrollDebug.lastTargetStateKey) +
+            " | " +
+            ExtractStateKeyTail(scrollDebug.primaryTargetStateKey));
+        detailLines.push_back(
+            "Scroll offset B/A: " +
+            FormatFloat(scrollDebug.lastOffsetBefore) +
+            " -> " +
+            FormatFloat(scrollDebug.lastOffsetAfter) +
+            " | overflow " +
+            FormatFloat(scrollDebug.lastOverflow));
+        detailLines.push_back(
+            "Scroll H/T: " +
+            std::to_string(scrollDebug.handledWheelEventCount) +
+            "/" +
+            std::to_string(scrollDebug.totalWheelEventCount) +
+            " | " +
+            (scrollDebug.lastResult.empty() ? std::string("n/a") : scrollDebug.lastResult));
+    }
+
+    if (m_autoScreenshot.HasPendingCapture()) {
+        detailLines.push_back("Shot pending...");
+    } else if (!m_autoScreenshot.GetLastCaptureSummary().empty()) {
+        detailLines.push_back(TruncateText(m_autoScreenshot.GetLastCaptureSummary(), 78u));
+    } else {
+        detailLines.push_back(
+            "Screenshots: F12 -> " +
+            TruncateText(
+                m_autoScreenshot.GetLatestCapturePath().parent_path().string(),
+                60u));
+    }
+
+    if (!m_runtimeError.empty()) {
+        detailLines.push_back(TruncateText(m_runtimeError, 78u));
+    } else if (!m_autoScreenshot.GetLastCaptureError().empty()) {
+        detailLines.push_back(TruncateText(m_autoScreenshot.GetLastCaptureError(), 78u));
+    } else if (!authoredMode) {
+        detailLines.push_back("No fallback sandbox is rendered in this host.");
+    }
+
+    const float panelHeight = 38.0f + static_cast<float>(detailLines.size()) * 18.0f;
+    const UIRect panelRect(width - panelWidth - 16.0f, height - panelHeight - 42.0f, panelWidth, panelHeight);
+
+    UIDrawList& overlay = drawData.EmplaceDrawList("Core UI Validation Overlay");
+    overlay.AddFilledRect(panelRect, kOverlayBgColor, 10.0f);
+    overlay.AddRectOutline(panelRect, kOverlayBorderColor, 1.0f, 10.0f);
+    overlay.AddFilledRect(
+        UIRect(panelRect.x + 12.0f, panelRect.y + 14.0f, 8.0f, 8.0f),
+        authoredMode ? kOverlaySuccess : kOverlayFallback,
+        4.0f);
+    overlay.AddText(
+        UIPoint(panelRect.x + 28.0f, panelRect.y + 10.0f),
+        m_runtimeStatus.empty() ? "Core UI Validation" : m_runtimeStatus,
+        kOverlayTextPrimary,
+        14.0f);
+
+    float detailY = panelRect.y + 30.0f;
+    for (std::size_t index = 0; index < detailLines.size(); ++index) {
+        const bool lastLine = index + 1u == detailLines.size();
+        overlay.AddText(
+            UIPoint(panelRect.x + 28.0f, detailY),
+            detailLines[index],
+            lastLine && (!m_runtimeError.empty() || !m_autoScreenshot.GetLastCaptureError().empty())
+                ? kOverlayFallback
+                : kOverlayTextMuted,
+            12.0f);
+        detailY += 18.0f;
+    }
+}
+
+std::filesystem::path Application::ResolveRepoRelativePath(const char* relativePath) {
+    return (GetRepoRootPath() / relativePath).lexically_normal();
+}
+
+LRESULT CALLBACK Application::WndProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam) {
+    if (message == WM_NCCREATE) {
+        const auto* createStruct = reinterpret_cast<CREATESTRUCTW*>(lParam);
+        auto* application = reinterpret_cast<Application*>(createStruct->lpCreateParams);
+        SetWindowLongPtrW(hwnd, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(application));
+        return TRUE;
+    }
+
+    Application* application = GetApplicationFromWindow(hwnd);
+    switch (message) {
+    case WM_SIZE:
+        if (application != nullptr && wParam != SIZE_MINIMIZED) {
+            application->OnResize(static_cast<UINT>(LOWORD(lParam)), static_cast<UINT>(HIWORD(lParam)));
+        }
+        return 0;
+    case WM_PAINT:
+        if (application != nullptr) {
+            PAINTSTRUCT paintStruct = {};
+            BeginPaint(hwnd, &paintStruct);
+            application->RenderFrame();
+            EndPaint(hwnd, &paintStruct);
+            return 0;
+        }
+        break;
+    case WM_MOUSEMOVE:
+        if (application != nullptr) {
+            if (!application->m_trackingMouseLeave) {
+                TRACKMOUSEEVENT trackMouseEvent = {};
+                trackMouseEvent.cbSize = sizeof(trackMouseEvent);
+                trackMouseEvent.dwFlags = TME_LEAVE;
+                trackMouseEvent.hwndTrack = hwnd;
+                if (TrackMouseEvent(&trackMouseEvent)) {
+                    application->m_trackingMouseLeave = true;
+                }
+            }
+            application->QueuePointerEvent(UIInputEventType::PointerMove, UIPointerButton::None, wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_MOUSELEAVE:
+        if (application != nullptr) {
+            application->m_trackingMouseLeave = false;
+            application->QueuePointerLeaveEvent();
+            return 0;
+        }
+        break;
+    case WM_LBUTTONDOWN:
+        if (application != nullptr) {
+            SetFocus(hwnd);
+            SetCapture(hwnd);
+            application->QueuePointerEvent(UIInputEventType::PointerButtonDown, UIPointerButton::Left, wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_LBUTTONUP:
+        if (application != nullptr) {
+            if (GetCapture() == hwnd) {
+                ReleaseCapture();
+            }
+            application->QueuePointerEvent(UIInputEventType::PointerButtonUp, UIPointerButton::Left, wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_MOUSEWHEEL:
+        if (application != nullptr) {
+            application->QueuePointerWheelEvent(GET_WHEEL_DELTA_WPARAM(wParam), wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_SETFOCUS:
+        if (application != nullptr) {
+            application->m_inputModifierTracker.SyncFromSystemState();
+            application->QueueWindowFocusEvent(UIInputEventType::FocusGained);
+            return 0;
+        }
+        break;
+    case WM_KILLFOCUS:
+        if (application != nullptr) {
+            application->m_inputModifierTracker.Reset();
+            application->QueueWindowFocusEvent(UIInputEventType::FocusLost);
+            return 0;
+        }
+        break;
+    case WM_KEYDOWN:
+    case WM_SYSKEYDOWN:
+        if (application != nullptr) {
+            if (wParam == VK_F12) {
+                application->m_autoScreenshot.RequestCapture("manual_f12");
+            }
+            application->QueueKeyEvent(UIInputEventType::KeyDown, wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_KEYUP:
+    case WM_SYSKEYUP:
+        if (application != nullptr) {
+            application->QueueKeyEvent(UIInputEventType::KeyUp, wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_CHAR:
+        if (application != nullptr) {
+            application->QueueCharacterEvent(wParam, lParam);
+            return 0;
+        }
+        break;
+    case WM_ERASEBKGND:
+        return 1;
+    case WM_DESTROY:
+        if (application != nullptr) {
+            application->m_hwnd = nullptr;
+        }
+        PostQuitMessage(0);
+        return 0;
+    default:
+        break;
+    }
+
+    return DefWindowProcW(hwnd, message, wParam, lParam);
+}
+
+int RunCoreUIValidationApp(HINSTANCE hInstance, int nCmdShow, std::string requestedScenarioId) {
+    Application application(std::move(requestedScenarioId));
+    return application.Run(hInstance, nCmdShow);
+}
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/Application.h
+++ b/tests/UI/Core/integration/shared/src/Application.h
@@ -0,0 +1,87 @@
+#pragma once
+
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+
+#include "AutoScreenshot.h"
+#include "CoreValidationScenario.h"
+#include "DragDropValidationScene.h"
+#include "InputModifierTracker.h"
+#include "NativeRenderer.h"
+#include "PopupMenuOverlayValidationScene.h"
+
+#include <XCEngine/UI/Runtime/UIScreenDocumentHost.h>
+#include <XCEngine/UI/Runtime/UIScreenPlayer.h>
+
+#include <windows.h>
+#include <windowsx.h>
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <string>
+#include <vector>
+
+namespace XCEngine::Tests::CoreUI {
+
+class Application {
+public:
+    explicit Application(std::string requestedScenarioId = {});
+
+    int Run(HINSTANCE hInstance, int nCmdShow);
+
+private:
+    struct TrackedFileState {
+        std::filesystem::path path = {};
+        std::filesystem::file_time_type writeTime = {};
+        bool exists = false;
+    };
+
+    static LRESULT CALLBACK WndProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam);
+
+    bool Initialize(HINSTANCE hInstance, int nCmdShow);
+    void Shutdown();
+    void RenderFrame();
+    void OnResize(UINT width, UINT height);
+    void QueuePointerEvent(::XCEngine::UI::UIInputEventType type, ::XCEngine::UI::UIPointerButton button, WPARAM wParam, LPARAM lParam);
+    void QueuePointerLeaveEvent();
+    void QueuePointerWheelEvent(short wheelDelta, WPARAM wParam, LPARAM lParam);
+    void QueueKeyEvent(::XCEngine::UI::UIInputEventType type, WPARAM wParam, LPARAM lParam);
+    void QueueCharacterEvent(WPARAM wParam, LPARAM lParam);
+    void QueueWindowFocusEvent(::XCEngine::UI::UIInputEventType type);
+    bool LoadStructuredScreen(const char* triggerReason);
+    void RefreshStructuredScreen();
+    void RebuildTrackedFileStates();
+    bool DetectTrackedFileChange() const;
+    void AppendRuntimeOverlay(::XCEngine::UI::UIDrawData& drawData, float width, float height) const;
+    static std::filesystem::path ResolveRepoRelativePath(const char* relativePath);
+
+    HWND m_hwnd = nullptr;
+    HINSTANCE m_hInstance = nullptr;
+    ATOM m_windowClassAtom = 0;
+    Host::NativeRenderer m_renderer;
+    Host::AutoScreenshotController m_autoScreenshot;
+    ::XCEngine::UI::Runtime::UIDocumentScreenHost m_documentHost;
+    ::XCEngine::UI::Runtime::UIScreenPlayer m_screenPlayer;
+    ::XCEngine::UI::Runtime::UIScreenAsset m_screenAsset = {};
+    const CoreValidationScenario* m_activeScenario = nullptr;
+    std::string m_requestedScenarioId = {};
+    std::vector<TrackedFileState> m_trackedFiles = {};
+    std::chrono::steady_clock::time_point m_startTime = {};
+    std::chrono::steady_clock::time_point m_lastFrameTime = {};
+    std::chrono::steady_clock::time_point m_lastReloadPollTime = {};
+    std::uint64_t m_frameIndex = 0;
+    std::vector<::XCEngine::UI::UIInputEvent> m_pendingInputEvents = {};
+    Host::InputModifierTracker m_inputModifierTracker = {};
+    DragDropValidationScene m_dragDropValidationScene = {};
+    PopupMenuOverlayValidationScene m_popupMenuOverlayScene = {};
+    bool m_trackingMouseLeave = false;
+    bool m_useStructuredScreen = false;
+    std::string m_runtimeStatus = {};
+    std::string m_runtimeError = {};
+};
+
+int RunCoreUIValidationApp(HINSTANCE hInstance, int nCmdShow, std::string requestedScenarioId = {});
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/AutoScreenshot.cpp
+++ b/tests/UI/Core/integration/shared/src/AutoScreenshot.cpp
@@ -0,0 +1,224 @@
+#include "AutoScreenshot.h"
+
+#include "NativeRenderer.h"
+
+#include <chrono>
+#include <cctype>
+#include <cstdlib>
+#include <cstdio>
+#include <sstream>
+#include <system_error>
+#include <vector>
+
+#include <windows.h>
+
+namespace XCEngine::Tests::CoreUI::Host {
+
+namespace {
+
+bool IsAutoCaptureOnStartupEnabled() {
+    const char* value = std::getenv("XCUI_AUTO_CAPTURE_ON_STARTUP");
+    if (value == nullptr || value[0] == '\0') {
+        return false;
+    }
+
+    std::string normalized = value;
+    for (char& character : normalized) {
+        character = static_cast<char>(std::tolower(static_cast<unsigned char>(character)));
+    }
+
+    return normalized != "0" &&
+        normalized != "false" &&
+        normalized != "off" &&
+        normalized != "no";
+}
+
+std::filesystem::path GetExecutableDirectory() {
+    std::vector<wchar_t> buffer(MAX_PATH);
+    while (true) {
+        const DWORD copied = ::GetModuleFileNameW(
+            nullptr,
+            buffer.data(),
+            static_cast<DWORD>(buffer.size()));
+        if (copied == 0u) {
+            return std::filesystem::current_path().lexically_normal();
+        }
+
+        if (copied < buffer.size() - 1u) {
+            return std::filesystem::path(std::wstring(buffer.data(), copied))
+                .parent_path()
+                .lexically_normal();
+        }
+
+        buffer.resize(buffer.size() * 2u);
+    }
+}
+
+std::filesystem::path ResolveBuildCaptureRoot(const std::filesystem::path& requestedCaptureRoot) {
+    std::filesystem::path captureRoot = GetExecutableDirectory() / "captures";
+    const std::filesystem::path scenarioPath = requestedCaptureRoot.parent_path().filename();
+    if (!scenarioPath.empty() && scenarioPath != "captures") {
+        captureRoot /= scenarioPath;
+    }
+
+    return captureRoot.lexically_normal();
+}
+
+} // namespace
+
+void AutoScreenshotController::Initialize(const std::filesystem::path& captureRoot) {
+    m_captureRoot = ResolveBuildCaptureRoot(captureRoot);
+    m_historyRoot = (m_captureRoot / "history").lexically_normal();
+    m_latestCapturePath = (m_captureRoot / "latest.png").lexically_normal();
+    m_captureCount = 0;
+    m_capturePending = false;
+    m_pendingReason.clear();
+    m_lastCaptureSummary = "Output: " + m_captureRoot.string();
+    m_lastCaptureError.clear();
+    if (IsAutoCaptureOnStartupEnabled()) {
+        RequestCapture("startup");
+    }
+}
+
+void AutoScreenshotController::Shutdown() {
+    m_capturePending = false;
+    m_pendingReason.clear();
+}
+
+void AutoScreenshotController::RequestCapture(std::string reason) {
+    m_pendingReason = reason.empty() ? "capture" : std::move(reason);
+    m_capturePending = true;
+}
+
+void AutoScreenshotController::CaptureIfRequested(
+    NativeRenderer& renderer,
+    const ::XCEngine::UI::UIDrawData& drawData,
+    unsigned int width,
+    unsigned int height,
+    bool framePresented) {
+    if (!m_capturePending || !framePresented || drawData.Empty() || width == 0u || height == 0u) {
+        return;
+    }
+
+    std::error_code errorCode = {};
+    std::filesystem::create_directories(m_captureRoot, errorCode);
+    if (errorCode) {
+        m_lastCaptureError = "Failed to create screenshot directory: " + m_captureRoot.string();
+        m_lastCaptureSummary = "AutoShot failed";
+        m_capturePending = false;
+        return;
+    }
+
+    std::filesystem::create_directories(m_historyRoot, errorCode);
+    if (errorCode) {
+        m_lastCaptureError = "Failed to create screenshot directory: " + m_historyRoot.string();
+        m_lastCaptureSummary = "AutoShot failed";
+        m_capturePending = false;
+        return;
+    }
+
+    std::string captureError = {};
+    const std::filesystem::path historyPath = BuildHistoryCapturePath(m_pendingReason);
+    if (!renderer.CaptureToPng(drawData, width, height, historyPath, captureError)) {
+        m_lastCaptureError = std::move(captureError);
+        m_lastCaptureSummary = "AutoShot failed";
+        m_capturePending = false;
+        return;
+    }
+
+    errorCode.clear();
+    std::filesystem::copy_file(
+        historyPath,
+        m_latestCapturePath,
+        std::filesystem::copy_options::overwrite_existing,
+        errorCode);
+    if (errorCode) {
+        m_lastCaptureError = "Failed to update latest screenshot: " + m_latestCapturePath.string();
+        m_lastCaptureSummary = "AutoShot failed";
+        m_capturePending = false;
+        return;
+    }
+
+    ++m_captureCount;
+    m_lastCaptureError.clear();
+    m_lastCaptureSummary = "Shot: latest.png | " + historyPath.filename().string();
+    m_capturePending = false;
+    m_pendingReason.clear();
+}
+
+bool AutoScreenshotController::HasPendingCapture() const {
+    return m_capturePending;
+}
+
+const std::filesystem::path& AutoScreenshotController::GetLatestCapturePath() const {
+    return m_latestCapturePath;
+}
+
+const std::string& AutoScreenshotController::GetLastCaptureSummary() const {
+    return m_lastCaptureSummary;
+}
+
+const std::string& AutoScreenshotController::GetLastCaptureError() const {
+    return m_lastCaptureError;
+}
+
+std::filesystem::path AutoScreenshotController::BuildHistoryCapturePath(std::string_view reason) const {
+    std::ostringstream filename;
+    filename << BuildTimestampString()
+             << '_'
+             << (m_captureCount + 1u)
+             << '_'
+             << SanitizeReason(reason)
+             << ".png";
+    return (m_historyRoot / filename.str()).lexically_normal();
+}
+
+std::string AutoScreenshotController::BuildTimestampString() {
+    const auto now = std::chrono::system_clock::now();
+    const std::time_t currentTime = std::chrono::system_clock::to_time_t(now);
+    std::tm localTime = {};
+    localtime_s(&localTime, &currentTime);
+
+    char buffer[32] = {};
+    std::snprintf(
+        buffer,
+        sizeof(buffer),
+        "%04d%02d%02d_%02d%02d%02d",
+        localTime.tm_year + 1900,
+        localTime.tm_mon + 1,
+        localTime.tm_mday,
+        localTime.tm_hour,
+        localTime.tm_min,
+        localTime.tm_sec);
+    return buffer;
+}
+
+std::string AutoScreenshotController::SanitizeReason(std::string_view reason) {
+    std::string sanitized = {};
+    sanitized.reserve(reason.size());
+
+    bool lastWasSeparator = false;
+    for (const unsigned char value : reason) {
+        if (std::isalnum(value)) {
+            sanitized.push_back(static_cast<char>(std::tolower(value)));
+            lastWasSeparator = false;
+            continue;
+        }
+
+        if (!lastWasSeparator) {
+            sanitized.push_back('_');
+            lastWasSeparator = true;
+        }
+    }
+
+    while (!sanitized.empty() && sanitized.front() == '_') {
+        sanitized.erase(sanitized.begin());
+    }
+    while (!sanitized.empty() && sanitized.back() == '_') {
+        sanitized.pop_back();
+    }
+
+    return sanitized.empty() ? "capture" : sanitized;
+}
+
+} // namespace XCEngine::Tests::CoreUI::Host
--- a/tests/UI/Core/integration/shared/src/AutoScreenshot.h
+++ b/tests/UI/Core/integration/shared/src/AutoScreenshot.h
@@ -0,0 +1,52 @@
+#pragma once
+
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+
+#include <XCEngine/UI/DrawData.h>
+
+#include <cstdint>
+#include <filesystem>
+#include <string>
+#include <string_view>
+
+namespace XCEngine::Tests::CoreUI::Host {
+
+class NativeRenderer;
+
+class AutoScreenshotController {
+public:
+    void Initialize(const std::filesystem::path& captureRoot);
+    void Shutdown();
+
+    void RequestCapture(std::string reason);
+    void CaptureIfRequested(
+        NativeRenderer& renderer,
+        const ::XCEngine::UI::UIDrawData& drawData,
+        unsigned int width,
+        unsigned int height,
+        bool framePresented);
+
+    bool HasPendingCapture() const;
+    const std::filesystem::path& GetLatestCapturePath() const;
+    const std::string& GetLastCaptureSummary() const;
+    const std::string& GetLastCaptureError() const;
+
+private:
+    std::filesystem::path BuildHistoryCapturePath(std::string_view reason) const;
+
+    static std::string BuildTimestampString();
+    static std::string SanitizeReason(std::string_view reason);
+
+    std::filesystem::path m_captureRoot = {};
+    std::filesystem::path m_historyRoot = {};
+    std::filesystem::path m_latestCapturePath = {};
+    std::string m_pendingReason = {};
+    std::string m_lastCaptureSummary = {};
+    std::string m_lastCaptureError = {};
+    std::uint64_t m_captureCount = 0;
+    bool m_capturePending = false;
+};
+
+} // namespace XCEngine::Tests::CoreUI::Host
--- a/tests/UI/Core/integration/shared/src/CoreValidationScenario.cpp
+++ b/tests/UI/Core/integration/shared/src/CoreValidationScenario.cpp
@@ -0,0 +1,154 @@
+#include "CoreValidationScenario.h"
+
+#include <array>
+
+#ifndef XCENGINE_CORE_UI_TESTS_REPO_ROOT
+#define XCENGINE_CORE_UI_TESTS_REPO_ROOT "."
+#endif
+
+namespace XCEngine::Tests::CoreUI {
+
+namespace {
+
+namespace fs = std::filesystem;
+
+fs::path RepoRootPath() {
+    std::string root = XCENGINE_CORE_UI_TESTS_REPO_ROOT;
+    if (root.size() >= 2u && root.front() == '"' && root.back() == '"') {
+        root = root.substr(1u, root.size() - 2u);
+    }
+    return fs::path(root).lexically_normal();
+}
+
+fs::path RepoRelative(const char* relativePath) {
+    return (RepoRootPath() / relativePath).lexically_normal();
+}
+
+const std::array<CoreValidationScenario, 11>& GetCoreValidationScenarios() {
+    static const std::array<CoreValidationScenario, 11> scenarios = { {
+        {
+            "core.input.drag_drop_basic",
+            UIValidationDomain::Core,
+            "input",
+            "Core Input | Drag Drop Contract",
+            RepoRelative("tests/UI/Core/integration/input/drag_drop_basic/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/input/drag_drop_basic/captures")
+        },
+        {
+            "core.input.keyboard_focus",
+            UIValidationDomain::Core,
+            "input",
+            "Core Input | Keyboard Focus",
+            RepoRelative("tests/UI/Core/integration/input/keyboard_focus/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/input/keyboard_focus/captures")
+        },
+        {
+            "core.input.popup_menu_overlay",
+            UIValidationDomain::Core,
+            "input",
+            "Core Input | Popup Menu Overlay",
+            RepoRelative("tests/UI/Core/integration/input/popup_menu_overlay/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/input/popup_menu_overlay/captures")
+        },
+        {
+            "core.input.pointer_states",
+            UIValidationDomain::Core,
+            "input",
+            "Core Input | Pointer States",
+            RepoRelative("tests/UI/Core/integration/input/pointer_states/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/input/pointer_states/captures")
+        },
+        {
+            "core.input.scroll_view",
+            UIValidationDomain::Core,
+            "input",
+            "Core Input | Scroll View",
+            RepoRelative("tests/UI/Core/integration/input/scroll_view/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/input/scroll_view/captures")
+        },
+        {
+            "core.input.shortcut_scope",
+            UIValidationDomain::Core,
+            "input",
+            "Core Input | Shortcut Scope",
+            RepoRelative("tests/UI/Core/integration/input/shortcut_scope/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/input/shortcut_scope/captures")
+        },
+        {
+            "core.layout.splitter_resize",
+            UIValidationDomain::Core,
+            "layout",
+            "Core Layout | Splitter Resize",
+            RepoRelative("tests/UI/Core/integration/layout/splitter_resize/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/layout/splitter_resize/captures")
+        },
+        {
+            "core.layout.tab_strip_selection",
+            UIValidationDomain::Core,
+            "layout",
+            "Core Layout | TabStrip Selection",
+            RepoRelative("tests/UI/Core/integration/layout/tab_strip_selection/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/layout/tab_strip_selection/captures")
+        },
+        {
+            "core.layout.workspace_compose",
+            UIValidationDomain::Core,
+            "layout",
+            "Core Layout | Workspace Compose",
+            RepoRelative("tests/UI/Core/integration/layout/workspace_compose/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/layout/workspace_compose/captures")
+        },
+        {
+            "core.style.theme_tokens",
+            UIValidationDomain::Core,
+            "style",
+            "Core Style | Theme Tokens",
+            RepoRelative("tests/UI/Core/integration/style/theme_tokens/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/style/theme_tokens/captures")
+        },
+        {
+            "core.text.utf8_focus_surface",
+            UIValidationDomain::Core,
+            "text",
+            "Core Text | UTF-8 Focus Surface",
+            RepoRelative("tests/UI/Core/integration/text/utf8_focus_surface/View.xcui"),
+            RepoRelative("tests/UI/Core/integration/shared/themes/core_validation.xctheme"),
+            RepoRelative("tests/UI/Core/integration/text/utf8_focus_surface/captures")
+        }
+    } };
+    return scenarios;
+}
+
+} // namespace
+
+const CoreValidationScenario& GetDefaultCoreValidationScenario() {
+    for (const CoreValidationScenario& scenario : GetCoreValidationScenarios()) {
+        if (scenario.id == "core.input.keyboard_focus") {
+            return scenario;
+        }
+    }
+
+    return GetCoreValidationScenarios().front();
+}
+
+const CoreValidationScenario* FindCoreValidationScenario(std::string_view id) {
+    for (const CoreValidationScenario& scenario : GetCoreValidationScenarios()) {
+        if (scenario.id == id) {
+            return &scenario;
+        }
+    }
+
+    return nullptr;
+}
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/CoreValidationScenario.h
+++ b/tests/UI/Core/integration/shared/src/CoreValidationScenario.h
@@ -0,0 +1,26 @@
+#pragma once
+
+#include <filesystem>
+#include <string>
+#include <string_view>
+
+namespace XCEngine::Tests::CoreUI {
+
+enum class UIValidationDomain : unsigned char {
+    Core = 0
+};
+
+struct CoreValidationScenario {
+    std::string id = {};
+    UIValidationDomain domain = UIValidationDomain::Core;
+    std::string categoryId = {};
+    std::string displayName = {};
+    std::filesystem::path documentPath = {};
+    std::filesystem::path themePath = {};
+    std::filesystem::path captureRootPath = {};
+};
+
+const CoreValidationScenario& GetDefaultCoreValidationScenario();
+const CoreValidationScenario* FindCoreValidationScenario(std::string_view id);
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/DragDropValidationScene.cpp
+++ b/tests/UI/Core/integration/shared/src/DragDropValidationScene.cpp
@@ -0,0 +1,504 @@
+#include "DragDropValidationScene.h"
+
+#include <XCEngine/Input/InputTypes.h>
+
+#include <array>
+#include <string>
+#include <utility>
+
+namespace XCEngine::Tests::CoreUI {
+
+namespace {
+
+using ::XCEngine::Input::KeyCode;
+using ::XCEngine::UI::UIColor;
+using ::XCEngine::UI::UIDrawData;
+using ::XCEngine::UI::UIDrawList;
+using ::XCEngine::UI::UIInputEvent;
+using ::XCEngine::UI::UIInputEventType;
+using ::XCEngine::UI::UIPoint;
+using ::XCEngine::UI::UIPointerButton;
+using ::XCEngine::UI::UIRect;
+using ::XCEngine::UI::Widgets::BeginUIDragDrop;
+using ::XCEngine::UI::Widgets::CancelUIDragDrop;
+using ::XCEngine::UI::Widgets::EndUIDragDrop;
+using ::XCEngine::UI::Widgets::HasResolvedUIDragDropTarget;
+using ::XCEngine::UI::Widgets::IsUIDragDropInProgress;
+using ::XCEngine::UI::Widgets::UIDragDropOperation;
+using ::XCEngine::UI::Widgets::UIDragDropPayload;
+using ::XCEngine::UI::Widgets::UIDragDropResult;
+using ::XCEngine::UI::Widgets::UIDragDropSourceDescriptor;
+using ::XCEngine::UI::Widgets::UIDragDropTargetDescriptor;
+using ::XCEngine::UI::Widgets::UpdateUIDragDropPointer;
+using ::XCEngine::UI::Widgets::UpdateUIDragDropTarget;
+
+constexpr UIColor kLabPanelBg(0.12f, 0.12f, 0.12f, 1.0f);
+constexpr UIColor kLabPanelBorder(0.24f, 0.24f, 0.24f, 1.0f);
+constexpr UIColor kStatusBg(0.16f, 0.16f, 0.16f, 1.0f);
+constexpr UIColor kCardBg(0.18f, 0.18f, 0.18f, 1.0f);
+constexpr UIColor kCardHover(0.24f, 0.24f, 0.24f, 1.0f);
+constexpr UIColor kCardBorder(0.32f, 0.32f, 0.32f, 1.0f);
+constexpr UIColor kAccept(0.36f, 0.46f, 0.36f, 1.0f);
+constexpr UIColor kAcceptBorder(0.56f, 0.72f, 0.56f, 1.0f);
+constexpr UIColor kReject(0.34f, 0.22f, 0.22f, 1.0f);
+constexpr UIColor kRejectBorder(0.72f, 0.38f, 0.38f, 1.0f);
+constexpr UIColor kGhostBg(0.28f, 0.28f, 0.28f, 0.95f);
+constexpr UIColor kGhostBorder(0.78f, 0.78f, 0.78f, 1.0f);
+constexpr UIColor kTextPrimary(0.93f, 0.93f, 0.93f, 1.0f);
+constexpr UIColor kTextMuted(0.72f, 0.72f, 0.72f, 1.0f);
+constexpr UIColor kTextWeak(0.56f, 0.56f, 0.56f, 1.0f);
+constexpr UIColor kTextSuccess(0.62f, 0.82f, 0.62f, 1.0f);
+constexpr UIColor kTextDanger(0.84f, 0.48f, 0.48f, 1.0f);
+
+constexpr std::uint64_t kTextureSourceOwnerId = 1001u;
+constexpr std::uint64_t kEntitySourceOwnerId = 1002u;
+constexpr std::uint64_t kProjectTargetOwnerId = 2001u;
+constexpr std::uint64_t kHierarchyTargetOwnerId = 2002u;
+
+std::string DescribeOperation(UIDragDropOperation operation) {
+    switch (operation) {
+    case UIDragDropOperation::Copy:
+        return "Copy";
+    case UIDragDropOperation::Move:
+        return "Move";
+    case UIDragDropOperation::Link:
+        return "Link";
+    default:
+        return "(none)";
+    }
+}
+
+void DrawPanel(
+    UIDrawList& drawList,
+    const UIRect& rect,
+    const UIColor& fillColor,
+    const UIColor& borderColor,
+    float rounding) {
+    drawList.AddFilledRect(rect, fillColor, rounding);
+    drawList.AddRectOutline(rect, borderColor, 1.0f, rounding);
+}
+
+void DrawCard(
+    UIDrawList& drawList,
+    const UIRect& rect,
+    std::string_view title,
+    std::string_view subtitle,
+    const UIColor& fillColor,
+    const UIColor& borderColor) {
+    DrawPanel(drawList, rect, fillColor, borderColor, 10.0f);
+    drawList.AddText(UIPoint(rect.x + 14.0f, rect.y + 12.0f), std::string(title), kTextPrimary, 15.0f);
+    drawList.AddText(UIPoint(rect.x + 14.0f, rect.y + 34.0f), std::string(subtitle), kTextMuted, 12.0f);
+}
+
+UIDragDropSourceDescriptor BuildTextureSource(const UIPoint& pointerPosition) {
+    UIDragDropSourceDescriptor source = {};
+    source.ownerId = kTextureSourceOwnerId;
+    source.sourceId = "project.texture";
+    source.pointerDownPosition = pointerPosition;
+    source.payload = UIDragDropPayload{ "asset.texture", "tex-001", "Checker.png" };
+    source.allowedOperations = UIDragDropOperation::Copy | UIDragDropOperation::Move;
+    source.activationDistance = 6.0f;
+    return source;
+}
+
+UIDragDropSourceDescriptor BuildEntitySource(const UIPoint& pointerPosition) {
+    UIDragDropSourceDescriptor source = {};
+    source.ownerId = kEntitySourceOwnerId;
+    source.sourceId = "hierarchy.entity";
+    source.pointerDownPosition = pointerPosition;
+    source.payload = UIDragDropPayload{ "scene.entity", "entity-hero", "HeroRoot" };
+    source.allowedOperations = UIDragDropOperation::Move;
+    source.activationDistance = 6.0f;
+    return source;
+}
+
+UIDragDropTargetDescriptor BuildProjectTarget() {
+    static constexpr std::array<std::string_view, 2> kAcceptedTypes = {
+        "asset.texture",
+        "asset.material"
+    };
+
+    UIDragDropTargetDescriptor target = {};
+    target.ownerId = kProjectTargetOwnerId;
+    target.targetId = "project.browser";
+    target.acceptedPayloadTypes = kAcceptedTypes;
+    target.acceptedOperations =
+        UIDragDropOperation::Copy |
+        UIDragDropOperation::Move;
+    target.preferredOperation = UIDragDropOperation::Copy;
+    return target;
+}
+
+UIDragDropTargetDescriptor BuildHierarchyTarget() {
+    static constexpr std::array<std::string_view, 1> kAcceptedTypes = {
+        "scene.entity"
+    };
+
+    UIDragDropTargetDescriptor target = {};
+    target.ownerId = kHierarchyTargetOwnerId;
+    target.targetId = "hierarchy.parent";
+    target.acceptedPayloadTypes = kAcceptedTypes;
+    target.acceptedOperations = UIDragDropOperation::Move;
+    target.preferredOperation = UIDragDropOperation::Move;
+    return target;
+}
+
+} // namespace
+
+void DragDropValidationScene::Reset() {
+    m_dragState = {};
+    m_pointerPosition = {};
+    m_hasPointer = false;
+    m_resultText = "Result: Ready";
+    m_lastDropText = "(none)";
+}
+
+void DragDropValidationScene::Update(
+    const std::vector<UIInputEvent>& events,
+    const UIRect& viewportRect,
+    bool windowFocused) {
+    const Geometry geometry = BuildGeometry(viewportRect);
+
+    if (!windowFocused &&
+        IsUIDragDropInProgress(m_dragState)) {
+        HandleCancel("Result: focus lost, drag cancelled");
+    }
+
+    for (const UIInputEvent& event : events) {
+        switch (event.type) {
+        case UIInputEventType::PointerMove:
+            m_pointerPosition = event.position;
+            m_hasPointer = true;
+            HandlePointerMove(geometry, event.position);
+            break;
+        case UIInputEventType::PointerLeave:
+            m_hasPointer = false;
+            break;
+        case UIInputEventType::PointerButtonDown:
+            if (event.pointerButton == UIPointerButton::Left) {
+                m_pointerPosition = event.position;
+                m_hasPointer = true;
+                HandlePointerDown(geometry, event.position);
+            }
+            break;
+        case UIInputEventType::PointerButtonUp:
+            if (event.pointerButton == UIPointerButton::Left) {
+                m_pointerPosition = event.position;
+                m_hasPointer = true;
+                HandlePointerUp(geometry, event.position);
+            }
+            break;
+        case UIInputEventType::KeyDown:
+            if (event.keyCode == static_cast<std::int32_t>(KeyCode::Escape)) {
+                HandleCancel("Result: Escape cancelled current drag");
+            }
+            break;
+        case UIInputEventType::FocusLost:
+            HandleCancel("Result: focus lost, drag cancelled");
+            break;
+        default:
+            break;
+        }
+    }
+}
+
+void DragDropValidationScene::AppendDrawData(
+    UIDrawData& drawData,
+    const UIRect& viewportRect) const {
+    const Geometry geometry = BuildGeometry(viewportRect);
+    const bool hoverTexture = m_hasPointer && RectContains(geometry.textureSourceRect, m_pointerPosition);
+    const bool hoverEntity = m_hasPointer && RectContains(geometry.entitySourceRect, m_pointerPosition);
+    const bool hoverProject = m_hasPointer && RectContains(geometry.projectTargetRect, m_pointerPosition);
+    const bool hoverHierarchy = m_hasPointer && RectContains(geometry.hierarchyTargetRect, m_pointerPosition);
+    const bool dragProject =
+        m_dragState.active && m_dragState.targetOwnerId == kProjectTargetOwnerId;
+    const bool dragHierarchy =
+        m_dragState.active && m_dragState.targetOwnerId == kHierarchyTargetOwnerId;
+    const bool rejectProject =
+        m_dragState.active && hoverProject && !dragProject;
+    const bool rejectHierarchy =
+        m_dragState.active && hoverHierarchy && !dragHierarchy;
+
+    UIDrawList& drawList = drawData.EmplaceDrawList("Core Drag Drop Primitive Lab");
+    DrawPanel(drawList, geometry.labRect, kLabPanelBg, kLabPanelBorder, 12.0f);
+    DrawPanel(drawList, geometry.statusRect, kStatusBg, kCardBorder, 10.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 14.0f, geometry.statusRect.y + 12.0f),
+        "测试内容：Core Drag / Drop Contract",
+        kTextPrimary,
+        14.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 14.0f, geometry.statusRect.y + 34.0f),
+        m_resultText,
+        kTextMuted,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 14.0f, geometry.statusRect.y + 54.0f),
+        "Payload: " + (m_dragState.payload.label.empty() ? std::string("(none)") : m_dragState.payload.label),
+        kTextMuted,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 280.0f, geometry.statusRect.y + 34.0f),
+        std::string("Armed: ") + (m_dragState.armed ? "true" : "false"),
+        m_dragState.armed ? kTextPrimary : kTextWeak,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 280.0f, geometry.statusRect.y + 54.0f),
+        std::string("Active: ") + (m_dragState.active ? "true" : "false"),
+        m_dragState.active ? kTextSuccess : kTextWeak,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 430.0f, geometry.statusRect.y + 34.0f),
+        "Hover Target: " +
+            (m_dragState.targetId.empty() ? std::string("(none)") : m_dragState.targetId),
+        kTextMuted,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 430.0f, geometry.statusRect.y + 54.0f),
+        "Preview Op: " + DescribeOperation(m_dragState.previewOperation),
+        m_dragState.previewOperation == UIDragDropOperation::None ? kTextWeak : kTextSuccess,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 650.0f, geometry.statusRect.y + 34.0f),
+        "Last Drop: " + m_lastDropText,
+        kTextMuted,
+        12.0f);
+
+    DrawCard(
+        drawList,
+        geometry.sourcesRect,
+        "Sources",
+        "按下 source 后先保持，越过阈值才会进入 active。",
+        kCardBg,
+        kCardBorder);
+    DrawCard(
+        drawList,
+        geometry.targetsRect,
+        "Targets",
+        "右侧同时展示 accept / reject 与预览操作。",
+        kCardBg,
+        kCardBorder);
+
+    DrawCard(
+        drawList,
+        geometry.textureSourceRect,
+        "Texture Asset",
+        "type=asset.texture | Copy/Move",
+        hoverTexture ? kCardHover : kCardBg,
+        kCardBorder);
+    drawList.AddText(
+        UIPoint(geometry.textureSourceRect.x + 14.0f, geometry.textureSourceRect.y + 58.0f),
+        "Checker.png",
+        kTextPrimary,
+        13.0f);
+
+    DrawCard(
+        drawList,
+        geometry.entitySourceRect,
+        "Scene Entity",
+        "type=scene.entity | Move only",
+        hoverEntity ? kCardHover : kCardBg,
+        kCardBorder);
+    drawList.AddText(
+        UIPoint(geometry.entitySourceRect.x + 14.0f, geometry.entitySourceRect.y + 58.0f),
+        "HeroRoot",
+        kTextPrimary,
+        13.0f);
+
+    DrawCard(
+        drawList,
+        geometry.projectTargetRect,
+        "Project Browser",
+        "accepts asset.texture / asset.material | preferred Copy",
+        dragProject ? kAccept : (rejectProject ? kReject : (hoverProject ? kCardHover : kCardBg)),
+        dragProject ? kAcceptBorder : (rejectProject ? kRejectBorder : kCardBorder));
+    drawList.AddText(
+        UIPoint(geometry.projectTargetRect.x + 14.0f, geometry.projectTargetRect.y + 58.0f),
+        dragProject ? "Accepting current payload" : "拖入 texture 时应显示 Copy",
+        dragProject ? kTextSuccess : (rejectProject ? kTextDanger : kTextMuted),
+        12.0f);
+
+    DrawCard(
+        drawList,
+        geometry.hierarchyTargetRect,
+        "Hierarchy Parent",
+        "accepts scene.entity | preferred Move",
+        dragHierarchy ? kAccept : (rejectHierarchy ? kReject : (hoverHierarchy ? kCardHover : kCardBg)),
+        dragHierarchy ? kAcceptBorder : (rejectHierarchy ? kRejectBorder : kCardBorder));
+    drawList.AddText(
+        UIPoint(geometry.hierarchyTargetRect.x + 14.0f, geometry.hierarchyTargetRect.y + 58.0f),
+        dragHierarchy ? "Accepting current payload" : "拖入 entity 时应显示 Move",
+        dragHierarchy ? kTextSuccess : (rejectHierarchy ? kTextDanger : kTextMuted),
+        12.0f);
+
+    if (m_dragState.active) {
+        const UIRect ghostRect(
+            m_pointerPosition.x + 16.0f,
+            m_pointerPosition.y + 12.0f,
+            188.0f,
+            64.0f);
+        DrawPanel(drawList, ghostRect, kGhostBg, kGhostBorder, 8.0f);
+        drawList.AddText(
+            UIPoint(ghostRect.x + 12.0f, ghostRect.y + 12.0f),
+            m_dragState.payload.label.empty() ? std::string("(payload)") : m_dragState.payload.label,
+            kTextPrimary,
+            14.0f);
+        drawList.AddText(
+            UIPoint(ghostRect.x + 12.0f, ghostRect.y + 34.0f),
+            "type=" + m_dragState.payload.typeId + " | op=" + DescribeOperation(m_dragState.previewOperation),
+            kTextMuted,
+            12.0f);
+    }
+}
+
+DragDropValidationScene::Geometry DragDropValidationScene::BuildGeometry(
+    const UIRect& viewportRect) const {
+    Geometry geometry = {};
+    const float availableWidth = (std::max)(720.0f, viewportRect.width - 48.0f);
+    const float availableHeight = (std::max)(360.0f, viewportRect.height - 256.0f);
+    geometry.labRect = UIRect(
+        24.0f,
+        220.0f,
+        (std::min)(980.0f, availableWidth),
+        (std::min)(460.0f, availableHeight));
+    geometry.statusRect = UIRect(
+        geometry.labRect.x + 20.0f,
+        geometry.labRect.y + 18.0f,
+        geometry.labRect.width - 40.0f,
+        84.0f);
+    geometry.sourcesRect = UIRect(
+        geometry.labRect.x + 20.0f,
+        geometry.statusRect.y + geometry.statusRect.height + 18.0f,
+        280.0f,
+        geometry.labRect.height - 140.0f);
+    geometry.targetsRect = UIRect(
+        geometry.sourcesRect.x + geometry.sourcesRect.width + 18.0f,
+        geometry.sourcesRect.y,
+        geometry.labRect.width - 338.0f,
+        geometry.sourcesRect.height);
+    geometry.textureSourceRect = UIRect(
+        geometry.sourcesRect.x + 14.0f,
+        geometry.sourcesRect.y + 54.0f,
+        geometry.sourcesRect.width - 28.0f,
+        96.0f);
+    geometry.entitySourceRect = UIRect(
+        geometry.textureSourceRect.x,
+        geometry.textureSourceRect.y + geometry.textureSourceRect.height + 16.0f,
+        geometry.textureSourceRect.width,
+        96.0f);
+    geometry.projectTargetRect = UIRect(
+        geometry.targetsRect.x + 14.0f,
+        geometry.targetsRect.y + 54.0f,
+        geometry.targetsRect.width - 28.0f,
+        112.0f);
+    geometry.hierarchyTargetRect = UIRect(
+        geometry.projectTargetRect.x,
+        geometry.projectTargetRect.y + geometry.projectTargetRect.height + 18.0f,
+        geometry.projectTargetRect.width,
+        112.0f);
+    return geometry;
+}
+
+void DragDropValidationScene::HandlePointerDown(
+    const Geometry& geometry,
+    const UIPoint& position) {
+    if (RectContains(geometry.textureSourceRect, position)) {
+        BeginUIDragDrop(BuildTextureSource(position), m_dragState);
+        SetResult("Result: armed Texture Asset, move beyond threshold to activate");
+        return;
+    }
+    if (RectContains(geometry.entitySourceRect, position)) {
+        BeginUIDragDrop(BuildEntitySource(position), m_dragState);
+        SetResult("Result: armed Scene Entity, move beyond threshold to activate");
+    }
+}
+
+void DragDropValidationScene::HandlePointerMove(
+    const Geometry& geometry,
+    const UIPoint& position) {
+    if (!IsUIDragDropInProgress(m_dragState)) {
+        return;
+    }
+
+    UIDragDropResult result = {};
+    UpdateUIDragDropPointer(m_dragState, position, &result);
+    if (result.activated) {
+        SetResult("Result: drag became active after crossing activation distance");
+    }
+    UpdateHoveredTarget(geometry, position);
+}
+
+void DragDropValidationScene::HandlePointerUp(
+    const Geometry& geometry,
+    const UIPoint& position) {
+    if (!IsUIDragDropInProgress(m_dragState)) {
+        return;
+    }
+
+    UpdateHoveredTarget(geometry, position);
+    UIDragDropResult result = {};
+    if (!EndUIDragDrop(m_dragState, result)) {
+        return;
+    }
+
+    if (result.completed) {
+        m_lastDropText =
+            result.payloadItemId + " -> " + result.targetId + " (" + DescribeOperation(result.operation) + ")";
+        SetResult("Result: drop completed on " + result.targetId + " with " + DescribeOperation(result.operation));
+        return;
+    }
+
+    SetResult("Result: pointer released without accepted target, drag cancelled");
+}
+
+void DragDropValidationScene::HandleCancel(std::string reason) {
+    if (!IsUIDragDropInProgress(m_dragState)) {
+        return;
+    }
+
+    UIDragDropResult result = {};
+    CancelUIDragDrop(m_dragState, &result);
+    SetResult(std::move(reason));
+}
+
+void DragDropValidationScene::UpdateHoveredTarget(
+    const Geometry& geometry,
+    const UIPoint& position) {
+    if (!m_dragState.active) {
+        return;
+    }
+
+    UIDragDropResult result = {};
+    if (RectContains(geometry.projectTargetRect, position)) {
+        const UIDragDropTargetDescriptor projectTarget = BuildProjectTarget();
+        UpdateUIDragDropTarget(m_dragState, &projectTarget, &result);
+    } else if (RectContains(geometry.hierarchyTargetRect, position)) {
+        const UIDragDropTargetDescriptor hierarchyTarget = BuildHierarchyTarget();
+        UpdateUIDragDropTarget(m_dragState, &hierarchyTarget, &result);
+    } else {
+        UpdateUIDragDropTarget(m_dragState, nullptr, &result);
+    }
+
+    if (result.targetChanged) {
+        if (!HasResolvedUIDragDropTarget(m_dragState)) {
+            SetResult("Result: current hover target rejects payload type or operation");
+        } else {
+            SetResult("Result: hover target accepts payload with " + DescribeOperation(m_dragState.previewOperation));
+        }
+    }
+}
+
+void DragDropValidationScene::SetResult(std::string text) {
+    m_resultText = std::move(text);
+}
+
+bool DragDropValidationScene::RectContains(
+    const UIRect& rect,
+    const UIPoint& position) {
+    return position.x >= rect.x &&
+        position.x <= rect.x + rect.width &&
+        position.y >= rect.y &&
+        position.y <= rect.y + rect.height;
+}
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/DragDropValidationScene.h
+++ b/tests/UI/Core/integration/shared/src/DragDropValidationScene.h
@@ -0,0 +1,62 @@
+#pragma once
+
+#include <XCEngine/UI/DrawData.h>
+#include <XCEngine/UI/Widgets/UIDragDropInteraction.h>
+
+#include <string>
+#include <vector>
+
+namespace XCEngine::Tests::CoreUI {
+
+class DragDropValidationScene {
+public:
+    static constexpr const char* ScenarioId = "core.input.drag_drop_basic";
+
+    void Reset();
+    void Update(
+        const std::vector<::XCEngine::UI::UIInputEvent>& events,
+        const ::XCEngine::UI::UIRect& viewportRect,
+        bool windowFocused);
+    void AppendDrawData(
+        ::XCEngine::UI::UIDrawData& drawData,
+        const ::XCEngine::UI::UIRect& viewportRect) const;
+
+private:
+    struct Geometry {
+        ::XCEngine::UI::UIRect labRect = {};
+        ::XCEngine::UI::UIRect statusRect = {};
+        ::XCEngine::UI::UIRect sourcesRect = {};
+        ::XCEngine::UI::UIRect targetsRect = {};
+        ::XCEngine::UI::UIRect textureSourceRect = {};
+        ::XCEngine::UI::UIRect entitySourceRect = {};
+        ::XCEngine::UI::UIRect projectTargetRect = {};
+        ::XCEngine::UI::UIRect hierarchyTargetRect = {};
+    };
+
+    Geometry BuildGeometry(const ::XCEngine::UI::UIRect& viewportRect) const;
+    void HandlePointerDown(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position);
+    void HandlePointerMove(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position);
+    void HandlePointerUp(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position);
+    void HandleCancel(std::string reason);
+    void UpdateHoveredTarget(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position);
+    void SetResult(std::string text);
+    static bool RectContains(
+        const ::XCEngine::UI::UIRect& rect,
+        const ::XCEngine::UI::UIPoint& position);
+
+    ::XCEngine::UI::Widgets::UIDragDropState m_dragState = {};
+    ::XCEngine::UI::UIPoint m_pointerPosition = {};
+    bool m_hasPointer = false;
+    std::string m_resultText = "Result: Ready";
+    std::string m_lastDropText = "(none)";
+};
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/InputModifierTracker.h
+++ b/tests/UI/Core/integration/shared/src/InputModifierTracker.h
@@ -0,0 +1,253 @@
+#pragma once
+
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+
+#include <XCEngine/UI/Types.h>
+
+#include <windows.h>
+
+#include <cstddef>
+#include <cstdint>
+
+namespace XCEngine::Tests::CoreUI::Host {
+
+class InputModifierTracker {
+public:
+    void Reset() {
+        m_leftShift = false;
+        m_rightShift = false;
+        m_leftControl = false;
+        m_rightControl = false;
+        m_leftAlt = false;
+        m_rightAlt = false;
+        m_leftSuper = false;
+        m_rightSuper = false;
+        m_leftMouse = false;
+        m_rightMouse = false;
+        m_middleMouse = false;
+        m_x1Mouse = false;
+        m_x2Mouse = false;
+    }
+
+    void SyncFromSystemState() {
+        m_leftShift = (GetKeyState(VK_LSHIFT) & 0x8000) != 0;
+        m_rightShift = (GetKeyState(VK_RSHIFT) & 0x8000) != 0;
+        m_leftControl = (GetKeyState(VK_LCONTROL) & 0x8000) != 0;
+        m_rightControl = (GetKeyState(VK_RCONTROL) & 0x8000) != 0;
+        m_leftAlt = (GetKeyState(VK_LMENU) & 0x8000) != 0;
+        m_rightAlt = (GetKeyState(VK_RMENU) & 0x8000) != 0;
+        m_leftSuper = (GetKeyState(VK_LWIN) & 0x8000) != 0;
+        m_rightSuper = (GetKeyState(VK_RWIN) & 0x8000) != 0;
+        m_leftMouse = (GetKeyState(VK_LBUTTON) & 0x8000) != 0;
+        m_rightMouse = (GetKeyState(VK_RBUTTON) & 0x8000) != 0;
+        m_middleMouse = (GetKeyState(VK_MBUTTON) & 0x8000) != 0;
+        m_x1Mouse = (GetKeyState(VK_XBUTTON1) & 0x8000) != 0;
+        m_x2Mouse = (GetKeyState(VK_XBUTTON2) & 0x8000) != 0;
+    }
+
+    ::XCEngine::UI::UIInputModifiers GetCurrentModifiers() const {
+        return BuildModifiers();
+    }
+
+    ::XCEngine::UI::UIInputModifiers BuildPointerModifiers(std::size_t wParam) const {
+        ::XCEngine::UI::UIInputModifiers modifiers = BuildModifiers();
+        ApplyPointerWParam(modifiers, wParam);
+        return modifiers;
+    }
+
+    ::XCEngine::UI::UIInputModifiers ApplyPointerMessage(
+        ::XCEngine::UI::UIInputEventType type,
+        ::XCEngine::UI::UIPointerButton button,
+        std::size_t wParam) {
+        ::XCEngine::UI::UIInputModifiers modifiers = BuildPointerModifiers(wParam);
+        if (type == ::XCEngine::UI::UIInputEventType::PointerButtonDown) {
+            SetPointerButton(modifiers, button, true);
+        } else if (type == ::XCEngine::UI::UIInputEventType::PointerButtonUp) {
+            SetPointerButton(modifiers, button, false);
+        }
+
+        ApplyPointerState(modifiers);
+        return BuildModifiers();
+    }
+
+    ::XCEngine::UI::UIInputModifiers ApplyKeyMessage(
+        ::XCEngine::UI::UIInputEventType type,
+        WPARAM wParam,
+        LPARAM lParam) {
+        if (type == ::XCEngine::UI::UIInputEventType::KeyDown) {
+            SetModifierState(ResolveModifierKey(wParam, lParam), true);
+        } else if (type == ::XCEngine::UI::UIInputEventType::KeyUp) {
+            SetModifierState(ResolveModifierKey(wParam, lParam), false);
+        }
+
+        return BuildModifiers();
+    }
+
+private:
+    enum class ModifierKey : std::uint8_t {
+        None = 0,
+        LeftShift,
+        RightShift,
+        LeftControl,
+        RightControl,
+        LeftAlt,
+        RightAlt,
+        LeftSuper,
+        RightSuper
+    };
+
+    static bool IsExtendedKey(LPARAM lParam) {
+        return (static_cast<std::uint32_t>(lParam) & 0x01000000u) != 0u;
+    }
+
+    static std::uint32_t ExtractScanCode(LPARAM lParam) {
+        return (static_cast<std::uint32_t>(lParam) >> 16u) & 0xffu;
+    }
+
+    static ModifierKey ResolveModifierKey(WPARAM wParam, LPARAM lParam) {
+        switch (static_cast<std::uint32_t>(wParam)) {
+        case VK_SHIFT: {
+            const UINT shiftVirtualKey = MapVirtualKeyW(ExtractScanCode(lParam), MAPVK_VSC_TO_VK_EX);
+            return shiftVirtualKey == VK_RSHIFT
+                ? ModifierKey::RightShift
+                : ModifierKey::LeftShift;
+        }
+        case VK_LSHIFT:
+            return ModifierKey::LeftShift;
+        case VK_RSHIFT:
+            return ModifierKey::RightShift;
+        case VK_CONTROL:
+            return IsExtendedKey(lParam)
+                ? ModifierKey::RightControl
+                : ModifierKey::LeftControl;
+        case VK_LCONTROL:
+            return ModifierKey::LeftControl;
+        case VK_RCONTROL:
+            return ModifierKey::RightControl;
+        case VK_MENU:
+            return IsExtendedKey(lParam)
+                ? ModifierKey::RightAlt
+                : ModifierKey::LeftAlt;
+        case VK_LMENU:
+            return ModifierKey::LeftAlt;
+        case VK_RMENU:
+            return ModifierKey::RightAlt;
+        case VK_LWIN:
+            return ModifierKey::LeftSuper;
+        case VK_RWIN:
+            return ModifierKey::RightSuper;
+        default:
+            return ModifierKey::None;
+        }
+    }
+
+    static void ApplyPointerWParam(
+        ::XCEngine::UI::UIInputModifiers& modifiers,
+        std::size_t wParam) {
+        modifiers.shift = modifiers.shift || (wParam & MK_SHIFT) != 0;
+        modifiers.control = modifiers.control || (wParam & MK_CONTROL) != 0;
+        modifiers.leftMouse = (wParam & MK_LBUTTON) != 0;
+        modifiers.rightMouse = (wParam & MK_RBUTTON) != 0;
+        modifiers.middleMouse = (wParam & MK_MBUTTON) != 0;
+        modifiers.x1Mouse = (wParam & MK_XBUTTON1) != 0;
+        modifiers.x2Mouse = (wParam & MK_XBUTTON2) != 0;
+    }
+
+    static void SetPointerButton(
+        ::XCEngine::UI::UIInputModifiers& modifiers,
+        ::XCEngine::UI::UIPointerButton button,
+        bool pressed) {
+        switch (button) {
+        case ::XCEngine::UI::UIPointerButton::Left:
+            modifiers.leftMouse = pressed;
+            break;
+        case ::XCEngine::UI::UIPointerButton::Right:
+            modifiers.rightMouse = pressed;
+            break;
+        case ::XCEngine::UI::UIPointerButton::Middle:
+            modifiers.middleMouse = pressed;
+            break;
+        case ::XCEngine::UI::UIPointerButton::X1:
+            modifiers.x1Mouse = pressed;
+            break;
+        case ::XCEngine::UI::UIPointerButton::X2:
+            modifiers.x2Mouse = pressed;
+            break;
+        case ::XCEngine::UI::UIPointerButton::None:
+        default:
+            break;
+        }
+    }
+
+    void ApplyPointerState(const ::XCEngine::UI::UIInputModifiers& modifiers) {
+        m_leftMouse = modifiers.leftMouse;
+        m_rightMouse = modifiers.rightMouse;
+        m_middleMouse = modifiers.middleMouse;
+        m_x1Mouse = modifiers.x1Mouse;
+        m_x2Mouse = modifiers.x2Mouse;
+    }
+
+    void SetModifierState(ModifierKey key, bool pressed) {
+        switch (key) {
+        case ModifierKey::LeftShift:
+            m_leftShift = pressed;
+            break;
+        case ModifierKey::RightShift:
+            m_rightShift = pressed;
+            break;
+        case ModifierKey::LeftControl:
+            m_leftControl = pressed;
+            break;
+        case ModifierKey::RightControl:
+            m_rightControl = pressed;
+            break;
+        case ModifierKey::LeftAlt:
+            m_leftAlt = pressed;
+            break;
+        case ModifierKey::RightAlt:
+            m_rightAlt = pressed;
+            break;
+        case ModifierKey::LeftSuper:
+            m_leftSuper = pressed;
+            break;
+        case ModifierKey::RightSuper:
+            m_rightSuper = pressed;
+            break;
+        case ModifierKey::None:
+        default:
+            break;
+        }
+    }
+
+    ::XCEngine::UI::UIInputModifiers BuildModifiers() const {
+        ::XCEngine::UI::UIInputModifiers modifiers = {};
+        modifiers.shift = m_leftShift || m_rightShift;
+        modifiers.control = m_leftControl || m_rightControl;
+        modifiers.alt = m_leftAlt || m_rightAlt;
+        modifiers.super = m_leftSuper || m_rightSuper;
+        modifiers.leftMouse = m_leftMouse;
+        modifiers.rightMouse = m_rightMouse;
+        modifiers.middleMouse = m_middleMouse;
+        modifiers.x1Mouse = m_x1Mouse;
+        modifiers.x2Mouse = m_x2Mouse;
+        return modifiers;
+    }
+
+    bool m_leftShift = false;
+    bool m_rightShift = false;
+    bool m_leftControl = false;
+    bool m_rightControl = false;
+    bool m_leftAlt = false;
+    bool m_rightAlt = false;
+    bool m_leftSuper = false;
+    bool m_rightSuper = false;
+    bool m_leftMouse = false;
+    bool m_rightMouse = false;
+    bool m_middleMouse = false;
+    bool m_x1Mouse = false;
+    bool m_x2Mouse = false;
+};
+
+} // namespace XCEngine::Tests::CoreUI::Host
--- a/tests/UI/Core/integration/shared/src/NativeRenderer.cpp
+++ b/tests/UI/Core/integration/shared/src/NativeRenderer.cpp
@@ -0,0 +1,561 @@
+#include "NativeRenderer.h"
+
+#include <algorithm>
+#include <cmath>
+#include <filesystem>
+
+namespace XCEngine::Tests::CoreUI::Host {
+
+namespace {
+
+D2D1_RECT_F ToD2DRect(const ::XCEngine::UI::UIRect& rect) {
+    return D2D1::RectF(rect.x, rect.y, rect.x + rect.width, rect.y + rect.height);
+}
+
+D2D1_COLOR_F ToD2DColorValue(const ::XCEngine::UI::UIColor& color) {
+    return D2D1::ColorF(color.r, color.g, color.b, color.a);
+}
+
+std::string HrToString(const char* operation, HRESULT hr) {
+    char buffer[128] = {};
+    sprintf_s(buffer, "%s failed with hr=0x%08X.", operation, static_cast<unsigned int>(hr));
+    return buffer;
+}
+
+void FillLinearGradientRect(
+    ID2D1RenderTarget& renderTarget,
+    const ::XCEngine::UI::UIDrawCommand& command) {
+    const D2D1_RECT_F rect = ToD2DRect(command.rect);
+    const D2D1_GRADIENT_STOP stops[2] = {
+        D2D1::GradientStop(0.0f, ToD2DColorValue(command.color)),
+        D2D1::GradientStop(1.0f, ToD2DColorValue(command.secondaryColor))
+    };
+
+    Microsoft::WRL::ComPtr<ID2D1GradientStopCollection> stopCollection;
+    if (FAILED(renderTarget.CreateGradientStopCollection(
+            stops,
+            2u,
+            stopCollection.ReleaseAndGetAddressOf()))) {
+        return;
+    }
+
+    const D2D1_POINT_2F startPoint = D2D1::Point2F(rect.left, rect.top);
+    const D2D1_POINT_2F endPoint =
+        command.gradientDirection == ::XCEngine::UI::UILinearGradientDirection::Vertical
+            ? D2D1::Point2F(rect.left, rect.bottom)
+            : D2D1::Point2F(rect.right, rect.top);
+
+    Microsoft::WRL::ComPtr<ID2D1LinearGradientBrush> gradientBrush;
+    if (FAILED(renderTarget.CreateLinearGradientBrush(
+            D2D1::LinearGradientBrushProperties(startPoint, endPoint),
+            stopCollection.Get(),
+            gradientBrush.ReleaseAndGetAddressOf()))) {
+        return;
+    }
+
+    if (command.rounding > 0.0f) {
+        renderTarget.FillRoundedRectangle(
+            D2D1::RoundedRect(rect, command.rounding, command.rounding),
+            gradientBrush.Get());
+        return;
+    }
+
+    renderTarget.FillRectangle(rect, gradientBrush.Get());
+}
+
+} // namespace
+
+bool NativeRenderer::Initialize(HWND hwnd) {
+    Shutdown();
+
+    if (hwnd == nullptr) {
+        return false;
+    }
+
+    m_hwnd = hwnd;
+    if (FAILED(D2D1CreateFactory(D2D1_FACTORY_TYPE_SINGLE_THREADED, m_d2dFactory.ReleaseAndGetAddressOf()))) {
+        Shutdown();
+        return false;
+    }
+
+    if (FAILED(DWriteCreateFactory(
+            DWRITE_FACTORY_TYPE_SHARED,
+            __uuidof(IDWriteFactory),
+            reinterpret_cast<IUnknown**>(m_dwriteFactory.ReleaseAndGetAddressOf())))) {
+        Shutdown();
+        return false;
+    }
+
+    return EnsureRenderTarget();
+}
+
+void NativeRenderer::Shutdown() {
+    m_textFormats.clear();
+    m_solidBrush.Reset();
+    m_renderTarget.Reset();
+    m_wicFactory.Reset();
+    m_dwriteFactory.Reset();
+    m_d2dFactory.Reset();
+    if (m_wicComInitialized) {
+        CoUninitialize();
+        m_wicComInitialized = false;
+    }
+    m_hwnd = nullptr;
+}
+
+void NativeRenderer::Resize(UINT width, UINT height) {
+    if (!m_renderTarget || width == 0 || height == 0) {
+        return;
+    }
+
+    const HRESULT hr = m_renderTarget->Resize(D2D1::SizeU(width, height));
+    if (hr == D2DERR_RECREATE_TARGET) {
+        DiscardRenderTarget();
+    }
+}
+
+bool NativeRenderer::Render(const ::XCEngine::UI::UIDrawData& drawData) {
+    if (!EnsureRenderTarget()) {
+        return false;
+    }
+
+    const bool rendered = RenderToTarget(*m_renderTarget.Get(), *m_solidBrush.Get(), drawData);
+    const HRESULT hr = m_renderTarget->EndDraw();
+    if (hr == D2DERR_RECREATE_TARGET) {
+        DiscardRenderTarget();
+        return false;
+    }
+
+    return rendered && SUCCEEDED(hr);
+}
+
+bool NativeRenderer::CaptureToPng(
+    const ::XCEngine::UI::UIDrawData& drawData,
+    UINT width,
+    UINT height,
+    const std::filesystem::path& outputPath,
+    std::string& outError) {
+    outError.clear();
+    if (width == 0 || height == 0) {
+        outError = "CaptureToPng rejected an empty render size.";
+        return false;
+    }
+
+    if (!m_d2dFactory || !m_dwriteFactory) {
+        outError = "CaptureToPng requires an initialized NativeRenderer.";
+        return false;
+    }
+
+    if (!EnsureWicFactory(outError)) {
+        return false;
+    }
+
+    std::error_code errorCode = {};
+    std::filesystem::create_directories(outputPath.parent_path(), errorCode);
+    if (errorCode) {
+        outError = "Failed to create screenshot directory: " + outputPath.parent_path().string();
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IWICBitmap> bitmap;
+    HRESULT hr = m_wicFactory->CreateBitmap(
+        width,
+        height,
+        GUID_WICPixelFormat32bppPBGRA,
+        WICBitmapCacheOnLoad,
+        bitmap.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        outError = HrToString("IWICImagingFactory::CreateBitmap", hr);
+        return false;
+    }
+
+    const D2D1_RENDER_TARGET_PROPERTIES renderTargetProperties = D2D1::RenderTargetProperties(
+        D2D1_RENDER_TARGET_TYPE_DEFAULT,
+        D2D1::PixelFormat(DXGI_FORMAT_B8G8R8A8_UNORM, D2D1_ALPHA_MODE_PREMULTIPLIED));
+
+    Microsoft::WRL::ComPtr<ID2D1RenderTarget> offscreenRenderTarget;
+    hr = m_d2dFactory->CreateWicBitmapRenderTarget(
+        bitmap.Get(),
+        renderTargetProperties,
+        offscreenRenderTarget.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        outError = HrToString("ID2D1Factory::CreateWicBitmapRenderTarget", hr);
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<ID2D1SolidColorBrush> offscreenBrush;
+    hr = offscreenRenderTarget->CreateSolidColorBrush(
+        D2D1::ColorF(1.0f, 1.0f, 1.0f, 1.0f),
+        offscreenBrush.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        outError = HrToString("ID2D1RenderTarget::CreateSolidColorBrush", hr);
+        return false;
+    }
+
+    const bool rendered = RenderToTarget(*offscreenRenderTarget.Get(), *offscreenBrush.Get(), drawData);
+    hr = offscreenRenderTarget->EndDraw();
+    if (!rendered || FAILED(hr)) {
+        outError = HrToString("ID2D1RenderTarget::EndDraw", hr);
+        return false;
+    }
+
+    const std::wstring wideOutputPath = outputPath.wstring();
+    Microsoft::WRL::ComPtr<IWICStream> stream;
+    hr = m_wicFactory->CreateStream(stream.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        outError = HrToString("IWICImagingFactory::CreateStream", hr);
+        return false;
+    }
+
+    hr = stream->InitializeFromFilename(wideOutputPath.c_str(), GENERIC_WRITE);
+    if (FAILED(hr)) {
+        outError = HrToString("IWICStream::InitializeFromFilename", hr);
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IWICBitmapEncoder> encoder;
+    hr = m_wicFactory->CreateEncoder(GUID_ContainerFormatPng, nullptr, encoder.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        outError = HrToString("IWICImagingFactory::CreateEncoder", hr);
+        return false;
+    }
+
+    hr = encoder->Initialize(stream.Get(), WICBitmapEncoderNoCache);
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapEncoder::Initialize", hr);
+        return false;
+    }
+
+    Microsoft::WRL::ComPtr<IWICBitmapFrameEncode> frame;
+    Microsoft::WRL::ComPtr<IPropertyBag2> propertyBag;
+    hr = encoder->CreateNewFrame(frame.ReleaseAndGetAddressOf(), propertyBag.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapEncoder::CreateNewFrame", hr);
+        return false;
+    }
+
+    hr = frame->Initialize(propertyBag.Get());
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapFrameEncode::Initialize", hr);
+        return false;
+    }
+
+    hr = frame->SetSize(width, height);
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapFrameEncode::SetSize", hr);
+        return false;
+    }
+
+    WICPixelFormatGUID pixelFormat = GUID_WICPixelFormat32bppPBGRA;
+    hr = frame->SetPixelFormat(&pixelFormat);
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapFrameEncode::SetPixelFormat", hr);
+        return false;
+    }
+
+    hr = frame->WriteSource(bitmap.Get(), nullptr);
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapFrameEncode::WriteSource", hr);
+        return false;
+    }
+
+    hr = frame->Commit();
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapFrameEncode::Commit", hr);
+        return false;
+    }
+
+    hr = encoder->Commit();
+    if (FAILED(hr)) {
+        outError = HrToString("IWICBitmapEncoder::Commit", hr);
+        return false;
+    }
+
+    return true;
+}
+
+bool NativeRenderer::EnsureRenderTarget() {
+    if (!m_hwnd || !m_d2dFactory || !m_dwriteFactory) {
+        return false;
+    }
+
+    return CreateDeviceResources();
+}
+
+bool NativeRenderer::EnsureWicFactory(std::string& outError) {
+    outError.clear();
+    if (m_wicFactory) {
+        return true;
+    }
+
+    const HRESULT initHr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
+    if (FAILED(initHr) && initHr != RPC_E_CHANGED_MODE) {
+        outError = HrToString("CoInitializeEx", initHr);
+        return false;
+    }
+    if (SUCCEEDED(initHr)) {
+        m_wicComInitialized = true;
+    }
+
+    const HRESULT factoryHr = CoCreateInstance(
+        CLSID_WICImagingFactory,
+        nullptr,
+        CLSCTX_INPROC_SERVER,
+        IID_PPV_ARGS(m_wicFactory.ReleaseAndGetAddressOf()));
+    if (FAILED(factoryHr)) {
+        outError = HrToString("CoCreateInstance(CLSID_WICImagingFactory)", factoryHr);
+        return false;
+    }
+
+    return true;
+}
+
+void NativeRenderer::DiscardRenderTarget() {
+    m_solidBrush.Reset();
+    m_renderTarget.Reset();
+}
+
+bool NativeRenderer::CreateDeviceResources() {
+    if (m_renderTarget) {
+        return true;
+    }
+
+    RECT clientRect = {};
+    GetClientRect(m_hwnd, &clientRect);
+    const UINT width = static_cast<UINT>((std::max)(clientRect.right - clientRect.left, 1L));
+    const UINT height = static_cast<UINT>((std::max)(clientRect.bottom - clientRect.top, 1L));
+
+    const D2D1_RENDER_TARGET_PROPERTIES renderTargetProps = D2D1::RenderTargetProperties();
+    const D2D1_HWND_RENDER_TARGET_PROPERTIES hwndProps = D2D1::HwndRenderTargetProperties(
+        m_hwnd,
+        D2D1::SizeU(width, height));
+
+    if (FAILED(m_d2dFactory->CreateHwndRenderTarget(
+            renderTargetProps,
+            hwndProps,
+            m_renderTarget.ReleaseAndGetAddressOf()))) {
+        return false;
+    }
+
+    if (FAILED(m_renderTarget->CreateSolidColorBrush(
+            D2D1::ColorF(1.0f, 1.0f, 1.0f, 1.0f),
+            m_solidBrush.ReleaseAndGetAddressOf()))) {
+        DiscardRenderTarget();
+        return false;
+    }
+
+    m_renderTarget->SetTextAntialiasMode(D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE);
+    return true;
+}
+
+bool NativeRenderer::RenderToTarget(
+    ID2D1RenderTarget& renderTarget,
+    ID2D1SolidColorBrush& solidBrush,
+    const ::XCEngine::UI::UIDrawData& drawData) {
+    renderTarget.SetTextAntialiasMode(D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE);
+    renderTarget.BeginDraw();
+    renderTarget.Clear(D2D1::ColorF(0.04f, 0.05f, 0.06f, 1.0f));
+
+    std::vector<D2D1_RECT_F> clipStack = {};
+    for (const ::XCEngine::UI::UIDrawList& drawList : drawData.GetDrawLists()) {
+        for (const ::XCEngine::UI::UIDrawCommand& command : drawList.GetCommands()) {
+            RenderCommand(renderTarget, solidBrush, command, clipStack);
+        }
+    }
+
+    while (!clipStack.empty()) {
+        renderTarget.PopAxisAlignedClip();
+        clipStack.pop_back();
+    }
+
+    return true;
+}
+
+void NativeRenderer::RenderCommand(
+    ID2D1RenderTarget& renderTarget,
+    ID2D1SolidColorBrush& solidBrush,
+    const ::XCEngine::UI::UIDrawCommand& command,
+    std::vector<D2D1_RECT_F>& clipStack) {
+    solidBrush.SetColor(ToD2DColor(command.color));
+
+    switch (command.type) {
+    case ::XCEngine::UI::UIDrawCommandType::FilledRect: {
+        const D2D1_RECT_F rect = ToD2DRect(command.rect);
+        if (command.rounding > 0.0f) {
+            renderTarget.FillRoundedRectangle(
+                D2D1::RoundedRect(rect, command.rounding, command.rounding),
+                &solidBrush);
+        } else {
+            renderTarget.FillRectangle(rect, &solidBrush);
+        }
+        break;
+    }
+    case ::XCEngine::UI::UIDrawCommandType::FilledRectLinearGradient:
+        FillLinearGradientRect(renderTarget, command);
+        break;
+    case ::XCEngine::UI::UIDrawCommandType::RectOutline: {
+        const D2D1_RECT_F rect = ToD2DRect(command.rect);
+        const float thickness = command.thickness > 0.0f ? command.thickness : 1.0f;
+        if (command.rounding > 0.0f) {
+            renderTarget.DrawRoundedRectangle(
+                D2D1::RoundedRect(rect, command.rounding, command.rounding),
+                &solidBrush,
+                thickness);
+        } else {
+            renderTarget.DrawRectangle(rect, &solidBrush, thickness);
+        }
+        break;
+    }
+    case ::XCEngine::UI::UIDrawCommandType::Line:
+        renderTarget.DrawLine(
+            D2D1::Point2F(command.position.x, command.position.y),
+            D2D1::Point2F(command.uvMin.x, command.uvMin.y),
+            &solidBrush,
+            command.thickness > 0.0f ? command.thickness : 1.0f);
+        break;
+    case ::XCEngine::UI::UIDrawCommandType::FilledCircle:
+        if (command.radius > 0.0f) {
+            renderTarget.FillEllipse(
+                D2D1::Ellipse(
+                    D2D1::Point2F(command.position.x, command.position.y),
+                    command.radius,
+                    command.radius),
+                &solidBrush);
+        }
+        break;
+    case ::XCEngine::UI::UIDrawCommandType::CircleOutline:
+        if (command.radius > 0.0f) {
+            renderTarget.DrawEllipse(
+                D2D1::Ellipse(
+                    D2D1::Point2F(command.position.x, command.position.y),
+                    command.radius,
+                    command.radius),
+                &solidBrush,
+                command.thickness > 0.0f ? command.thickness : 1.0f);
+        }
+        break;
+    case ::XCEngine::UI::UIDrawCommandType::Text: {
+        if (command.text.empty()) {
+            break;
+        }
+
+        const float fontSize = command.fontSize > 0.0f ? command.fontSize : 16.0f;
+        IDWriteTextFormat* textFormat = GetTextFormat(fontSize);
+        if (textFormat == nullptr) {
+            break;
+        }
+
+        const std::wstring text = Utf8ToWide(command.text);
+        if (text.empty()) {
+            break;
+        }
+
+        const D2D1_SIZE_F targetSize = renderTarget.GetSize();
+        const D2D1_RECT_F layoutRect = D2D1::RectF(
+            command.position.x,
+            command.position.y,
+            targetSize.width,
+            command.position.y + fontSize * 1.8f);
+        renderTarget.DrawTextW(
+            text.c_str(),
+            static_cast<UINT32>(text.size()),
+            textFormat,
+            layoutRect,
+            &solidBrush,
+            D2D1_DRAW_TEXT_OPTIONS_CLIP,
+            DWRITE_MEASURING_MODE_NATURAL);
+        break;
+    }
+    case ::XCEngine::UI::UIDrawCommandType::Image: {
+        if (!command.texture.IsValid()) {
+            break;
+        }
+
+        const D2D1_RECT_F rect = ToD2DRect(command.rect);
+        renderTarget.DrawRectangle(rect, &solidBrush, 1.0f);
+        break;
+    }
+    case ::XCEngine::UI::UIDrawCommandType::PushClipRect: {
+        const D2D1_RECT_F rect = ToD2DRect(command.rect);
+        renderTarget.PushAxisAlignedClip(rect, D2D1_ANTIALIAS_MODE_PER_PRIMITIVE);
+        clipStack.push_back(rect);
+        break;
+    }
+    case ::XCEngine::UI::UIDrawCommandType::PopClipRect: {
+        if (!clipStack.empty()) {
+            renderTarget.PopAxisAlignedClip();
+            clipStack.pop_back();
+        }
+        break;
+    }
+    default:
+        break;
+    }
+}
+
+IDWriteTextFormat* NativeRenderer::GetTextFormat(float fontSize) {
+    if (!m_dwriteFactory) {
+        return nullptr;
+    }
+
+    const int key = static_cast<int>(std::lround(fontSize * 10.0f));
+    const auto found = m_textFormats.find(key);
+    if (found != m_textFormats.end()) {
+        return found->second.Get();
+    }
+
+    Microsoft::WRL::ComPtr<IDWriteTextFormat> textFormat;
+    const HRESULT hr = m_dwriteFactory->CreateTextFormat(
+        L"Segoe UI",
+        nullptr,
+        DWRITE_FONT_WEIGHT_REGULAR,
+        DWRITE_FONT_STYLE_NORMAL,
+        DWRITE_FONT_STRETCH_NORMAL,
+        fontSize,
+        L"",
+        textFormat.ReleaseAndGetAddressOf());
+    if (FAILED(hr)) {
+        return nullptr;
+    }
+
+    textFormat->SetTextAlignment(DWRITE_TEXT_ALIGNMENT_LEADING);
+    textFormat->SetParagraphAlignment(DWRITE_PARAGRAPH_ALIGNMENT_NEAR);
+    textFormat->SetWordWrapping(DWRITE_WORD_WRAPPING_NO_WRAP);
+
+    IDWriteTextFormat* result = textFormat.Get();
+    m_textFormats.emplace(key, std::move(textFormat));
+    return result;
+}
+
+D2D1_COLOR_F NativeRenderer::ToD2DColor(const ::XCEngine::UI::UIColor& color) {
+    return ToD2DColorValue(color);
+}
+
+std::wstring NativeRenderer::Utf8ToWide(std::string_view text) {
+    if (text.empty()) {
+        return {};
+    }
+
+    const int sizeNeeded = MultiByteToWideChar(
+        CP_UTF8,
+        0,
+        text.data(),
+        static_cast<int>(text.size()),
+        nullptr,
+        0);
+    if (sizeNeeded <= 0) {
+        return {};
+    }
+
+    std::wstring wideText(static_cast<size_t>(sizeNeeded), L'\0');
+    MultiByteToWideChar(
+        CP_UTF8,
+        0,
+        text.data(),
+        static_cast<int>(text.size()),
+        wideText.data(),
+        sizeNeeded);
+    return wideText;
+}
+
+} // namespace XCEngine::Tests::CoreUI::Host
--- a/tests/UI/Core/integration/shared/src/NativeRenderer.h
+++ b/tests/UI/Core/integration/shared/src/NativeRenderer.h
@@ -0,0 +1,65 @@
+#pragma once
+
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+
+#include <XCEngine/UI/DrawData.h>
+
+#include <d2d1.h>
+#include <dwrite.h>
+#include <wincodec.h>
+#include <windows.h>
+#include <wrl/client.h>
+
+#include <filesystem>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <vector>
+
+namespace XCEngine::Tests::CoreUI::Host {
+
+class NativeRenderer {
+public:
+    bool Initialize(HWND hwnd);
+    void Shutdown();
+    void Resize(UINT width, UINT height);
+    bool Render(const ::XCEngine::UI::UIDrawData& drawData);
+    bool CaptureToPng(
+        const ::XCEngine::UI::UIDrawData& drawData,
+        UINT width,
+        UINT height,
+        const std::filesystem::path& outputPath,
+        std::string& outError);
+
+private:
+    bool EnsureRenderTarget();
+    bool EnsureWicFactory(std::string& outError);
+    void DiscardRenderTarget();
+    bool CreateDeviceResources();
+    bool RenderToTarget(
+        ID2D1RenderTarget& renderTarget,
+        ID2D1SolidColorBrush& solidBrush,
+        const ::XCEngine::UI::UIDrawData& drawData);
+    void RenderCommand(
+        ID2D1RenderTarget& renderTarget,
+        ID2D1SolidColorBrush& solidBrush,
+        const ::XCEngine::UI::UIDrawCommand& command,
+        std::vector<D2D1_RECT_F>& clipStack);
+
+    IDWriteTextFormat* GetTextFormat(float fontSize);
+    static D2D1_COLOR_F ToD2DColor(const ::XCEngine::UI::UIColor& color);
+    static std::wstring Utf8ToWide(std::string_view text);
+
+    HWND m_hwnd = nullptr;
+    Microsoft::WRL::ComPtr<ID2D1Factory> m_d2dFactory;
+    Microsoft::WRL::ComPtr<IDWriteFactory> m_dwriteFactory;
+    Microsoft::WRL::ComPtr<IWICImagingFactory> m_wicFactory;
+    Microsoft::WRL::ComPtr<ID2D1HwndRenderTarget> m_renderTarget;
+    Microsoft::WRL::ComPtr<ID2D1SolidColorBrush> m_solidBrush;
+    std::unordered_map<int, Microsoft::WRL::ComPtr<IDWriteTextFormat>> m_textFormats;
+    bool m_wicComInitialized = false;
+};
+
+} // namespace XCEngine::Tests::CoreUI::Host
--- a/tests/UI/Core/integration/shared/src/PopupMenuOverlayValidationScene.cpp
+++ b/tests/UI/Core/integration/shared/src/PopupMenuOverlayValidationScene.cpp
@@ -0,0 +1,471 @@
+#include "PopupMenuOverlayValidationScene.h"
+
+#include <XCEngine/Input/InputTypes.h>
+
+#include <algorithm>
+#include <string>
+#include <utility>
+
+namespace XCEngine::Tests::CoreUI {
+
+namespace {
+
+using ::XCEngine::Input::KeyCode;
+using ::XCEngine::UI::UIColor;
+using ::XCEngine::UI::UIDrawData;
+using ::XCEngine::UI::UIDrawList;
+using ::XCEngine::UI::UIInputEvent;
+using ::XCEngine::UI::UIInputEventType;
+using ::XCEngine::UI::UIInputPath;
+using ::XCEngine::UI::UIPoint;
+using ::XCEngine::UI::UIRect;
+using ::XCEngine::UI::UISize;
+using ::XCEngine::UI::Widgets::ResolvePopupPlacementRect;
+using ::XCEngine::UI::Widgets::UIPopupDismissReason;
+using ::XCEngine::UI::Widgets::UIPopupOverlayEntry;
+using ::XCEngine::UI::Widgets::UIPopupPlacement;
+
+constexpr UIColor kLabPanelBg(0.12f, 0.12f, 0.12f, 1.0f);
+constexpr UIColor kLabPanelBorder(0.24f, 0.24f, 0.24f, 1.0f);
+constexpr UIColor kStatusBg(0.16f, 0.16f, 0.16f, 1.0f);
+constexpr UIColor kStatusBorder(0.28f, 0.28f, 0.28f, 1.0f);
+constexpr UIColor kControlBg(0.22f, 0.22f, 0.22f, 1.0f);
+constexpr UIColor kControlHover(0.31f, 0.31f, 0.31f, 1.0f);
+constexpr UIColor kControlDisabled(0.18f, 0.18f, 0.18f, 1.0f);
+constexpr UIColor kPopupBg(0.17f, 0.17f, 0.17f, 1.0f);
+constexpr UIColor kPopupHover(0.30f, 0.30f, 0.30f, 1.0f);
+constexpr UIColor kPopupBorder(0.38f, 0.38f, 0.38f, 1.0f);
+constexpr UIColor kScrim(0.05f, 0.05f, 0.05f, 0.48f);
+constexpr UIColor kTextPrimary(0.93f, 0.93f, 0.93f, 1.0f);
+constexpr UIColor kTextMuted(0.72f, 0.72f, 0.72f, 1.0f);
+
+const UIInputPath kTriggerPath = { 10u, 11u };
+const UIInputPath kBackgroundButtonPath = { 20u, 21u };
+const UIInputPath kRootSurfacePath = { 30u, 31u };
+const UIInputPath kRootActionPath = { 30u, 31u, 32u };
+const UIInputPath kRootSubmenuPath = { 30u, 31u, 33u };
+const UIInputPath kChildSurfacePath = { 40u, 41u };
+const UIInputPath kChildActionPath = { 40u, 41u, 42u };
+
+std::string DescribePath(const UIInputPath& path) {
+    if (path == kTriggerPath) {
+        return "Open Menu";
+    }
+    if (path == kBackgroundButtonPath) {
+        return "Background Button";
+    }
+    if (path == kRootActionPath) {
+        return "Root Action";
+    }
+    if (path == kRootSubmenuPath) {
+        return "Open Submenu";
+    }
+    if (path == kRootSurfacePath) {
+        return "Root Popup Surface";
+    }
+    if (path == kChildActionPath) {
+        return "Leaf Action";
+    }
+    if (path == kChildSurfacePath) {
+        return "Child Popup Surface";
+    }
+    return "Overlay Blank";
+}
+
+void DrawPanel(
+    UIDrawList& drawList,
+    const UIRect& rect,
+    const UIColor& fillColor,
+    const UIColor& borderColor,
+    float rounding) {
+    drawList.AddFilledRect(rect, fillColor, rounding);
+    drawList.AddRectOutline(rect, borderColor, 1.0f, rounding);
+}
+
+void DrawLabel(
+    UIDrawList& drawList,
+    const UIRect& rect,
+    std::string text,
+    const UIColor& textColor,
+    float fontSize = 13.0f) {
+    drawList.AddText(
+        UIPoint(rect.x + 12.0f, rect.y + 10.0f),
+        std::move(text),
+        textColor,
+        fontSize);
+}
+
+} // namespace
+
+void PopupMenuOverlayValidationScene::Reset() {
+    m_popupModel = {};
+    m_pointerPosition = {};
+    m_hasPointer = false;
+    m_backgroundClickCount = 0;
+    m_resultText = "Result: Ready";
+}
+
+void PopupMenuOverlayValidationScene::Update(
+    const std::vector<UIInputEvent>& events,
+    const UIRect& viewportRect,
+    bool windowFocused) {
+    (void)windowFocused;
+    const Geometry geometry = BuildGeometry(viewportRect);
+
+    for (const UIInputEvent& event : events) {
+        switch (event.type) {
+        case UIInputEventType::PointerMove:
+            m_pointerPosition = event.position;
+            m_hasPointer = true;
+            HandlePointerHover(geometry, event.position);
+            break;
+        case UIInputEventType::PointerLeave:
+            m_hasPointer = false;
+            break;
+        case UIInputEventType::PointerButtonDown:
+            if (event.pointerButton == ::XCEngine::UI::UIPointerButton::Left) {
+                m_pointerPosition = event.position;
+                m_hasPointer = true;
+                HandlePointerDown(geometry, event.position);
+            }
+            break;
+        case UIInputEventType::KeyDown:
+            if (event.keyCode == static_cast<std::int32_t>(KeyCode::Escape)) {
+                HandleEscapeKey();
+            }
+            break;
+        case UIInputEventType::FocusLost: {
+            const auto dismissResult = m_popupModel.DismissFromFocusLoss({});
+            if (dismissResult.changed) {
+                SetResult("Result: window focus lost, popup chain closed");
+            }
+            break;
+        }
+        default:
+            break;
+        }
+    }
+}
+
+void PopupMenuOverlayValidationScene::AppendDrawData(
+    UIDrawData& drawData,
+    const UIRect& viewportRect) const {
+    const Geometry geometry = BuildGeometry(viewportRect);
+    const UIInputPath hoverPath =
+        m_hasPointer ? HitTest(geometry, m_pointerPosition) : UIInputPath();
+
+    UIDrawList& drawList = drawData.EmplaceDrawList("Core Popup Menu Overlay Lab");
+    DrawPanel(drawList, geometry.labRect, kLabPanelBg, kLabPanelBorder, 12.0f);
+    DrawPanel(drawList, geometry.backgroundButtonRect, kControlBg, kStatusBorder, 8.0f);
+    DrawLabel(
+        drawList,
+        geometry.backgroundButtonRect,
+        "Background Button",
+        !HasOpenPopups() && hoverPath == kBackgroundButtonPath ? kTextPrimary : kTextMuted);
+
+    if (HasOpenPopups()) {
+        drawList.AddFilledRect(geometry.labRect, kScrim, 12.0f);
+    }
+
+    DrawPanel(drawList, geometry.statusRect, kStatusBg, kStatusBorder, 10.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 12.0f, geometry.statusRect.y + 10.0f),
+        "测试内容：Core Popup / Menu Overlay Primitive",
+        kTextPrimary,
+        14.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 12.0f, geometry.statusRect.y + 32.0f),
+        m_resultText,
+        kTextMuted,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 12.0f, geometry.statusRect.y + 50.0f),
+        "Popup Chain: " + FormatPopupChain(),
+        kTextMuted,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 320.0f, geometry.statusRect.y + 32.0f),
+        "Hover: " + DescribeHoverTarget(geometry),
+        kTextMuted,
+        12.0f);
+    drawList.AddText(
+        UIPoint(geometry.statusRect.x + 320.0f, geometry.statusRect.y + 50.0f),
+        "Background Hits: " + std::to_string(m_backgroundClickCount),
+        kTextMuted,
+        12.0f);
+
+    const UIColor triggerColor =
+        hoverPath == kTriggerPath ? kControlHover : kControlBg;
+    DrawPanel(drawList, geometry.triggerRect, triggerColor, kStatusBorder, 8.0f);
+    DrawLabel(drawList, geometry.triggerRect, "Open Menu", kTextPrimary);
+
+    if (IsRootOpen()) {
+        DrawPanel(drawList, geometry.rootPopupRect, kPopupBg, kPopupBorder, 10.0f);
+
+        const UIColor rootActionColor =
+            hoverPath == kRootActionPath ? kPopupHover : kPopupBg;
+        DrawPanel(drawList, geometry.rootActionRect, rootActionColor, kStatusBorder, 8.0f);
+        DrawLabel(drawList, geometry.rootActionRect, "Root Action", kTextPrimary);
+
+        const UIColor submenuColor =
+            hoverPath == kRootSubmenuPath || hoverPath == kChildSurfacePath || hoverPath == kChildActionPath
+            ? kPopupHover
+            : kPopupBg;
+        DrawPanel(drawList, geometry.rootSubmenuRect, submenuColor, kStatusBorder, 8.0f);
+        DrawLabel(drawList, geometry.rootSubmenuRect, "Open Submenu   >", kTextPrimary);
+    }
+
+    if (IsSubmenuOpen()) {
+        DrawPanel(drawList, geometry.childPopupRect, kPopupBg, kPopupBorder, 10.0f);
+        const UIColor childActionColor =
+            hoverPath == kChildActionPath ? kPopupHover : kPopupBg;
+        DrawPanel(drawList, geometry.childActionRect, childActionColor, kStatusBorder, 8.0f);
+        DrawLabel(drawList, geometry.childActionRect, "Leaf Action", kTextPrimary);
+    }
+}
+
+PopupMenuOverlayValidationScene::Geometry PopupMenuOverlayValidationScene::BuildGeometry(
+    const UIRect& viewportRect) const {
+    Geometry geometry = {};
+
+    const float availableWidth = (std::max)(280.0f, viewportRect.width - 48.0f);
+    const float availableHeight = (std::max)(280.0f, viewportRect.height - 244.0f);
+    geometry.labRect = UIRect(
+        24.0f,
+        220.0f,
+        (std::min)(760.0f, availableWidth),
+        (std::min)(380.0f, availableHeight));
+
+    geometry.statusRect = UIRect(
+        geometry.labRect.x + 20.0f,
+        geometry.labRect.y + 20.0f,
+        geometry.labRect.width - 40.0f,
+        78.0f);
+    geometry.triggerRect = UIRect(
+        geometry.labRect.x + 20.0f,
+        geometry.statusRect.y + geometry.statusRect.height + 18.0f,
+        126.0f,
+        40.0f);
+    geometry.backgroundButtonRect = UIRect(
+        geometry.labRect.x + geometry.labRect.width - 220.0f,
+        geometry.labRect.y + geometry.labRect.height - 64.0f,
+        180.0f,
+        40.0f);
+
+    const auto rootPlacement = ResolvePopupPlacementRect(
+        geometry.triggerRect,
+        UISize(220.0f, 112.0f),
+        geometry.labRect,
+        UIPopupPlacement::BottomStart);
+    geometry.rootPopupRect = rootPlacement.rect;
+    geometry.rootActionRect = UIRect(
+        geometry.rootPopupRect.x + 10.0f,
+        geometry.rootPopupRect.y + 10.0f,
+        geometry.rootPopupRect.width - 20.0f,
+        40.0f);
+    geometry.rootSubmenuRect = UIRect(
+        geometry.rootPopupRect.x + 10.0f,
+        geometry.rootPopupRect.y + 58.0f,
+        geometry.rootPopupRect.width - 20.0f,
+        40.0f);
+
+    const auto childPlacement = ResolvePopupPlacementRect(
+        geometry.rootSubmenuRect,
+        UISize(180.0f, 60.0f),
+        geometry.labRect,
+        UIPopupPlacement::RightStart);
+    geometry.childPopupRect = childPlacement.rect;
+    geometry.childActionRect = UIRect(
+        geometry.childPopupRect.x + 10.0f,
+        geometry.childPopupRect.y + 10.0f,
+        geometry.childPopupRect.width - 20.0f,
+        40.0f);
+    return geometry;
+}
+
+UIInputPath PopupMenuOverlayValidationScene::HitTest(
+    const Geometry& geometry,
+    const UIPoint& position) const {
+    if (IsSubmenuOpen()) {
+        if (RectContains(geometry.childActionRect, position)) {
+            return kChildActionPath;
+        }
+        if (RectContains(geometry.childPopupRect, position)) {
+            return kChildSurfacePath;
+        }
+    }
+
+    if (IsRootOpen()) {
+        if (RectContains(geometry.rootActionRect, position)) {
+            return kRootActionPath;
+        }
+        if (RectContains(geometry.rootSubmenuRect, position)) {
+            return kRootSubmenuPath;
+        }
+        if (RectContains(geometry.rootPopupRect, position)) {
+            return kRootSurfacePath;
+        }
+    }
+
+    if (RectContains(geometry.triggerRect, position)) {
+        return kTriggerPath;
+    }
+
+    if (!HasOpenPopups() && RectContains(geometry.backgroundButtonRect, position)) {
+        return kBackgroundButtonPath;
+    }
+
+    return {};
+}
+
+void PopupMenuOverlayValidationScene::HandlePointerDown(
+    const Geometry& geometry,
+    const UIPoint& position) {
+    const UIInputPath hitPath = HitTest(geometry, position);
+    if (hitPath == kTriggerPath) {
+        if (IsRootOpen()) {
+            m_popupModel.CloseAll(UIPopupDismissReason::Programmatic);
+            SetResult("Result: root popup closed");
+        } else {
+            OpenRootPopup(geometry);
+            SetResult("Result: root popup opened");
+        }
+        return;
+    }
+
+    if (hitPath == kRootActionPath) {
+        m_popupModel.CloseAll(UIPopupDismissReason::Programmatic);
+        SetResult("Result: Root Action dispatched");
+        return;
+    }
+
+    if (hitPath == kRootSubmenuPath) {
+        if (!IsSubmenuOpen()) {
+            OpenSubmenuPopup(geometry);
+            SetResult("Result: submenu opened");
+        }
+        return;
+    }
+
+    if (hitPath == kChildActionPath) {
+        m_popupModel.CloseAll(UIPopupDismissReason::Programmatic);
+        SetResult("Result: Leaf Action dispatched");
+        return;
+    }
+
+    const auto dismissResult = m_popupModel.DismissFromPointerDown(hitPath);
+    if (dismissResult.changed) {
+        if (dismissResult.closedPopupIds.size() == 1u &&
+            dismissResult.closedPopupIds.front() == "submenu") {
+            SetResult("Result: click stayed in root popup, submenu closed");
+        } else {
+            SetResult("Result: click hit overlay blank, popup chain closed");
+        }
+        return;
+    }
+
+    if (hitPath == kBackgroundButtonPath) {
+        ++m_backgroundClickCount;
+        SetResult("Result: Background Button dispatched #" + std::to_string(m_backgroundClickCount));
+        return;
+    }
+}
+
+void PopupMenuOverlayValidationScene::HandlePointerHover(
+    const Geometry& geometry,
+    const UIPoint& position) {
+    const UIInputPath hitPath = HitTest(geometry, position);
+    if (!IsRootOpen()) {
+        return;
+    }
+
+    if (hitPath == kRootSubmenuPath && !IsSubmenuOpen()) {
+        OpenSubmenuPopup(geometry);
+        SetResult("Result: submenu opened by hover");
+        return;
+    }
+
+    if (hitPath == kRootActionPath && IsSubmenuOpen()) {
+        m_popupModel.ClosePopup("submenu", UIPopupDismissReason::Programmatic);
+        SetResult("Result: submenu collapsed by hover");
+    }
+}
+
+void PopupMenuOverlayValidationScene::HandleEscapeKey() {
+    const auto dismissResult = m_popupModel.DismissFromEscape();
+    if (dismissResult.changed) {
+        SetResult("Result: Escape closed topmost popup");
+    }
+}
+
+void PopupMenuOverlayValidationScene::OpenRootPopup(const Geometry& geometry) {
+    UIPopupOverlayEntry entry = {};
+    entry.popupId = "root";
+    entry.anchorRect = geometry.triggerRect;
+    entry.anchorPath = kTriggerPath;
+    entry.surfacePath = kRootSurfacePath;
+    entry.placement = UIPopupPlacement::BottomStart;
+    m_popupModel.OpenPopup(std::move(entry));
+}
+
+void PopupMenuOverlayValidationScene::OpenSubmenuPopup(const Geometry& geometry) {
+    UIPopupOverlayEntry entry = {};
+    entry.popupId = "submenu";
+    entry.parentPopupId = "root";
+    entry.anchorRect = geometry.rootSubmenuRect;
+    entry.anchorPath = kRootSubmenuPath;
+    entry.surfacePath = kChildSurfacePath;
+    entry.placement = UIPopupPlacement::RightStart;
+    m_popupModel.OpenPopup(std::move(entry));
+}
+
+void PopupMenuOverlayValidationScene::SetResult(std::string text) {
+    m_resultText = std::move(text);
+}
+
+std::string PopupMenuOverlayValidationScene::FormatPopupChain() const {
+    if (!HasOpenPopups()) {
+        return "(empty)";
+    }
+
+    std::string chain = {};
+    const auto& popups = m_popupModel.GetPopupChain();
+    for (std::size_t index = 0; index < popups.size(); ++index) {
+        if (!chain.empty()) {
+            chain += " > ";
+        }
+        chain += popups[index].popupId;
+    }
+    return chain;
+}
+
+std::string PopupMenuOverlayValidationScene::DescribeHoverTarget(const Geometry& geometry) const {
+    if (!m_hasPointer) {
+        return "(none)";
+    }
+
+    return DescribePath(HitTest(geometry, m_pointerPosition));
+}
+
+bool PopupMenuOverlayValidationScene::HasOpenPopups() const {
+    return m_popupModel.HasOpenPopups();
+}
+
+bool PopupMenuOverlayValidationScene::IsRootOpen() const {
+    return m_popupModel.FindPopup("root") != nullptr;
+}
+
+bool PopupMenuOverlayValidationScene::IsSubmenuOpen() const {
+    return m_popupModel.FindPopup("submenu") != nullptr;
+}
+
+bool PopupMenuOverlayValidationScene::RectContains(
+    const UIRect& rect,
+    const UIPoint& position) {
+    return position.x >= rect.x &&
+        position.x <= rect.x + rect.width &&
+        position.y >= rect.y &&
+        position.y <= rect.y + rect.height;
+}
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/src/PopupMenuOverlayValidationScene.h
+++ b/tests/UI/Core/integration/shared/src/PopupMenuOverlayValidationScene.h
@@ -0,0 +1,69 @@
+#pragma once
+
+#include <XCEngine/UI/DrawData.h>
+#include <XCEngine/UI/Widgets/UIPopupOverlayModel.h>
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace XCEngine::Tests::CoreUI {
+
+class PopupMenuOverlayValidationScene {
+public:
+    static constexpr const char* ScenarioId = "core.input.popup_menu_overlay";
+
+    void Reset();
+    void Update(
+        const std::vector<::XCEngine::UI::UIInputEvent>& events,
+        const ::XCEngine::UI::UIRect& viewportRect,
+        bool windowFocused);
+    void AppendDrawData(
+        ::XCEngine::UI::UIDrawData& drawData,
+        const ::XCEngine::UI::UIRect& viewportRect) const;
+
+private:
+    struct Geometry {
+        ::XCEngine::UI::UIRect labRect = {};
+        ::XCEngine::UI::UIRect statusRect = {};
+        ::XCEngine::UI::UIRect triggerRect = {};
+        ::XCEngine::UI::UIRect backgroundButtonRect = {};
+        ::XCEngine::UI::UIRect rootPopupRect = {};
+        ::XCEngine::UI::UIRect rootActionRect = {};
+        ::XCEngine::UI::UIRect rootSubmenuRect = {};
+        ::XCEngine::UI::UIRect childPopupRect = {};
+        ::XCEngine::UI::UIRect childActionRect = {};
+    };
+
+    Geometry BuildGeometry(const ::XCEngine::UI::UIRect& viewportRect) const;
+    ::XCEngine::UI::UIInputPath HitTest(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position) const;
+    void HandlePointerDown(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position);
+    void HandlePointerHover(
+        const Geometry& geometry,
+        const ::XCEngine::UI::UIPoint& position);
+    void HandleEscapeKey();
+    void OpenRootPopup(const Geometry& geometry);
+    void OpenSubmenuPopup(const Geometry& geometry);
+    void SetResult(std::string text);
+    std::string FormatPopupChain() const;
+    std::string DescribeHoverTarget(const Geometry& geometry) const;
+    bool HasOpenPopups() const;
+    bool IsRootOpen() const;
+    bool IsSubmenuOpen() const;
+
+    static bool RectContains(
+        const ::XCEngine::UI::UIRect& rect,
+        const ::XCEngine::UI::UIPoint& position);
+
+    ::XCEngine::UI::Widgets::UIPopupOverlayModel m_popupModel = {};
+    ::XCEngine::UI::UIPoint m_pointerPosition = {};
+    bool m_hasPointer = false;
+    std::uint32_t m_backgroundClickCount = 0;
+    std::string m_resultText = "Result: Ready";
+};
+
+} // namespace XCEngine::Tests::CoreUI
--- a/tests/UI/Core/integration/shared/themes/core_validation.xctheme
+++ b/tests/UI/Core/integration/shared/themes/core_validation.xctheme
@@ -0,0 +1,65 @@
+<Theme name="CoreValidationTheme">
+  <Tokens>
+    <Color name="color.bg.workspace" value="#1C1C1C" />
+    <Color name="color.bg.panel" value="#292929" />
+    <Color name="color.bg.accent" value="#3A3A3A" />
+    <Color name="color.bg.selection" value="#4A4A4A" />
+    <Color name="color.style.warm" value="#4A3426" />
+    <Color name="color.style.cool" value="#243C4C" />
+    <Color name="color.style.borderWarm" value="#D0925B" />
+    <Color name="color.style.borderCool" value="#6BA3C7" />
+    <Color name="color.style.buttonAccent" value="#4B5E7B" />
+    <Color name="color.text.primary" value="#EEEEEE" />
+    <Color name="color.text.muted" value="#B0B0B0" />
+    <Spacing name="space.panel" value="12" />
+    <Spacing name="space.shell" value="18" />
+    <Spacing name="space.loose" value="18" />
+    <Radius name="radius.panel" value="10" />
+    <Radius name="radius.control" value="8" />
+    <Radius name="radius.loose" value="16" />
+  </Tokens>
+
+  <Widgets>
+    <Widget type="View" style="CoreWorkspace">
+      <Property name="background" value="color.bg.workspace" />
+      <Property name="padding" value="space.shell" />
+    </Widget>
+
+    <Widget type="Card" style="CorePanel">
+      <Property name="background" value="color.bg.panel" />
+      <Property name="radius" value="radius.panel" />
+      <Property name="padding" value="space.panel" />
+    </Widget>
+
+    <Widget type="Card" style="CoreStyleWarmCard">
+      <Property name="background" value="color.style.warm" />
+      <Property name="borderColor" value="color.style.borderWarm" />
+      <Property name="borderWidth" value="1" />
+      <Property name="padding" value="space.loose" />
+      <Property name="radius" value="radius.loose" />
+    </Widget>
+
+    <Widget type="Card" style="CoreStyleCoolCard">
+      <Property name="background" value="color.style.cool" />
+      <Property name="borderColor" value="color.style.borderCool" />
+      <Property name="borderWidth" value="1" />
+      <Property name="padding" value="space.loose" />
+      <Property name="radius" value="radius.loose" />
+    </Widget>
+
+    <Widget type="Button" style="CoreChip">
+      <Property name="background" value="color.bg.selection" />
+      <Property name="radius" value="radius.control" />
+    </Widget>
+
+    <Widget type="Button" style="CoreStyleAccentButton">
+      <Property name="background" value="color.style.buttonAccent" />
+      <Property name="radius" value="radius.control" />
+    </Widget>
+
+    <Widget type="Text" style="CoreTextMuted">
+      <Property name="foreground" value="color.text.muted" />
+      <Property name="fontSize" value="14" />
+    </Widget>
+  </Widgets>
+</Theme>