Add XCUI input focus shortcut MVP

docs/plan/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md

@@ -0,0 +1,140 @@
+# XCUI Input / Focus / Shortcut Subplan 完成归档
+
+日期：`2026-04-04`
+
+## 1. 归档结论
+
+`Subplan-04` 在其原始定义边界内已经完成，可以归档。
+
+这里的“完成”指的是：
+
+- 已建立 XCUI 输入事件基础模型
+- 已建立焦点、激活路径、指针捕获路径三套状态管理
+- 已建立 capture / target / bubble 三阶段输入路由
+- 已建立 shortcut scope 与命令匹配机制
+- 已建立统一的 `UIInputDispatcher`
+- 已补齐最小单元测试并完成通过验证
+
+这里的“完成”不包括：
+
+- Win32 原生消息采集
+- ImGui / Editor 侧的输入桥接
+- 文本输入控件级别的 IME 细节
+
+这些内容本来就不在 `Subplan-04` 的负责边界里，后续应由 `Subplan-05`、`Subplan-08`、`Subplan-09` 等继续接手。
+
+## 2. 本次落地内容
+
+### 2.1 输入事件模型
+
+已扩展 `UIInputEvent`：
+
+- `PointerEnter`
+- `PointerLeave`
+- `pointerId`
+- `timestampNanoseconds`
+- `repeat`
+- `synthetic`
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Types.h`
+
+### 2.2 焦点与路径模型
+
+已补齐：
+
+- `UIElementId`
+- `UIInputPath`
+- `UIFocusController`
+- `UIFocusChange`
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Input/UIInputPath.h`
+- `engine/include/XCEngine/UI/Input/UIFocusController.h`
+- `engine/src/UI/Input/UIInputPath.cpp`
+- `engine/src/UI/Input/UIFocusController.cpp`
+
+### 2.3 Shortcut 系统
+
+已补齐：
+
+- `UIShortcutScope`
+- `UIShortcutChord`
+- `UIShortcutBinding`
+- `UIShortcutRegistry`
+- shortcut scope 优先级匹配规则
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Input/UIShortcutRegistry.h`
+- `engine/src/UI/Input/UIShortcutRegistry.cpp`
+
+### 2.4 输入路由与统一分发器
+
+已补齐：
+
+- `UIInputRouter`
+- `UIInputRoutingPlan`
+- `UIInputRoutingStep`
+- `UIInputDispatcher`
+
+相关文件：
+
+- `engine/include/XCEngine/UI/Input/UIInputRouter.h`
+- `engine/include/XCEngine/UI/Input/UIInputDispatcher.h`
+- `engine/src/UI/Input/UIInputRouter.cpp`
+- `engine/src/UI/Input/UIInputDispatcher.cpp`
+
+## 3. 测试与验证
+
+新增测试：
+
+- `tests/Input/test_xcui_input_dispatcher.cpp`
+
+已完成验证：
+
+- `cmake --build build --config Debug --target input_tests`
+- `ctest -C Debug -R "XCUI.*" --output-on-failure`
+
+验证结果：
+
+- `6 / 6` 通过
+
+覆盖点包括：
+
+- focus path 切换
+- capture path 优先级
+- keyboard routed path 顺序
+- shortcut scope 匹配优先级
+- pointer down / pointer up 对 active path 的影响
+- shortcut 命中后优先消费、跳过普通 routing
+
+## 4. 对后续 subplan 的可复用输出
+
+当前已经可以被后续直接依赖的稳定入口：
+
+- `XCEngine::UI::UIInputPath`
+- `XCEngine::UI::UIFocusController`
+- `XCEngine::UI::UIShortcutRegistry`
+- `XCEngine::UI::UIInputRouter`
+- `XCEngine::UI::UIInputDispatcher`
+
+后续建议对接方式：
+
+- `Subplan-05`：负责把 ImGui/平台输入桥接进这套 dispatcher
+- `Subplan-08`：负责把 menu / dock / panel shell 的 shortcut scope 接进 registry
+- `Subplan-09`：负责把 viewport shell 的 pointer / focus / capture 接进 routing
+
+## 5. 原 subplan 文件
+
+原始 subplan 文件保留在：
+
+- `docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md`
+
+其状态应视为：
+
+- 已完成
+- 已归档
+- 不再作为活跃开发计划继续扩写