XCEngine/tests/UI/Editor/integration/README.md

# Editor UI Integration Validation

This directory contains editor-only XCUI manual validation scenarios.

Rules:

- Shared Core primitives stay in `tests/UI/Core/integration/`.
- Only editor-only shell, host, widget, and domain-integrated validation belongs here.
- Scenarios are organized as `tests/UI/Editor/integration/<category>/<scenario>/`.
- Each scenario owns its own `captures/` directory.

Layout:

- Primary categories are `shell/` and `state/`.
- `menu`, `workspace`, and `viewport` in scenario names describe contract families, not extra directory levels.
- `shared/`: shared host wrapper, scenario registry, shared theme
- `shell/workspace_shell_compose/`: split/tab/panel shell compose only
- `shell/editor_shell_compose/`: editor root shell compose only
- `shell/editor_shell_interaction/`: editor root shell interaction only
- `shell/dock_host_basic/`: DockHost interaction contract only
- `shell/panel_content_host_basic/`: external panel body mount/switch/unmount only
- `shell/menu_bar_basic/`: menu bar open/close/hover/dispatch only
- `shell/context_menu_basic/`: context menu root/submenu/dismiss/dispatch only
- `shell/panel_frame_basic/`: panel frame layout/state/hit-test only
- `shell/scroll_view_basic/`: ScrollView viewport, clip, thumb drag, wheel offset only
- `shell/property_grid_basic/`: PropertyGrid section toggle, field selection, value edit, keyboard navigation only
- `shell/bool_field_basic/`: BoolField click toggle, keyboard toggle, hover/focus/value feedback only
- `shell/number_field_basic/`: NumberField step buttons, direct text edit, Enter commit, Esc cancel only
- `shell/enum_field_basic/`: EnumField previous/next switch, keyboard switch, hover/focus/selection feedback only
- `shell/status_bar_basic/`: status bar slot/segment/hit-test only
- `shell/tree_view_basic/`: TreeView row layout, indent, disclosure, selection, focus, hit-test only
- `shell/tree_view_multiselect/`: TreeView multi-selection contract only
- `shell/list_view_basic/`: ListView row layout, selection, focus, keyboard navigation, hit-test only
- `shell/list_view_multiselect/`: ListView multi-selection contract only
- `shell/list_view_inline_rename/`: ListView inline rename/edit session only
- `shell/tab_strip_basic/`: tab strip layout/state/hit-test/close/navigation only
- `shell/viewport_slot_basic/`: viewport slot chrome/surface/status only
- `shell/viewport_shell_basic/`: viewport shell request/state compose only
- `shell/workspace_viewport_compose/`: workspace body external presentation compose only
- `shell/workspace_interaction_basic/`: workspace unified interaction only
- `state/panel_session_flow/`: panel session state flow only
- `state/panel_host_lifecycle/`: panel host attach/detach/show/hide/activate/focus contract only
- `state/layout_persistence/`: layout save/load/reset only
- `state/shortcut_dispatch/`: shortcut match/suppression/dispatch only
- `state/viewport_input_bridge_basic/`: viewport hover/focus/capture, local pointer coordinates, wheel/key/character bridge only

Scenarios:

- `editor.shell.workspace_shell_compose`
  Build target: `editor_ui_workspace_shell_compose_validation`
  Executable: `XCUIEditorWorkspaceShellComposeValidation.exe`
  Scope: DockHost compose, splitter drag, tab host, panel frame placeholders, workspace active-panel sync

- `editor.shell.editor_shell_compose`
  Build target: `editor_ui_editor_shell_compose_validation`
  Executable: `XCUIEditorShellComposeValidation.exe`
  Scope: root shell compose only; MenuBar / WorkspaceCompose / StatusBar three-band layout and workspace body embedding

- `editor.shell.editor_shell_interaction`
  Build target: `editor_ui_editor_shell_interaction_validation`
  Executable: `XCUIEditorShellInteractionValidation.exe`
  Scope: root shell unified interaction only; menu bar root switching, submenu hover chain, outside/Esc dismiss, command hook, menu-modal workspace shielding, and post-dismiss workspace interaction restore

- `editor.shell.dock_host_basic`
  Build target: `editor_ui_dock_host_basic_validation`
  Executable: `XCUIEditorDockHostBasicValidation.exe`
  Scope: `UpdateUIEditorDockHostInteraction(...)` basic contract only; splitter drag, tab activate/close, standalone panel activate/close, pointer capture/release request, workspace active-panel sync

- `editor.shell.panel_content_host_basic`
  Build target: `editor_ui_panel_content_host_basic_validation`
  Executable: `XCUIEditorPanelContentHostBasicValidation.exe`
  Scope: external HostedContent body mount/switch/unmount only; DockHost 只画 frame chrome，真实 body 由 content host 接管

- `editor.shell.menu_bar_basic`
  Build target: `editor_ui_menu_bar_basic_validation`
  Executable: `XCUIEditorMenuBarBasicValidation.exe`
  Scope: menu bar open/close, hover, dismiss, menu command dispatch only

- `editor.shell.context_menu_basic`
  Build target: `editor_ui_context_menu_basic_validation`
  Executable: `XCUIEditorContextMenuBasicValidation.exe`
  Scope: context menu root anchor, submenu hover, outside/Esc dismiss, command dispatch only

- `editor.shell.panel_frame_basic`
  Build target: `editor_ui_panel_frame_basic_validation`
  Executable: `XCUIEditorPanelFrameBasicValidation.exe`
  Scope: panel frame header/body/footer layout, focus/active/hover chrome, pin/close hit target only

- `editor.shell.scroll_view_basic`
  Build target: `editor_ui_scroll_view_basic_validation`
  Executable: `XCUIEditorScrollViewBasicValidation.exe`
  Scope: ScrollView viewport clip, wheel scrolling, thumb drag, focus, and hit-test only

- `editor.shell.property_grid_basic`
  Build target: `editor_ui_property_grid_basic_validation`
  Executable: `XCUIEditorPropertyGridBasicValidation.exe`
  Scope: PropertyGrid 基础控件验证；只检查 section toggle、field selection、value edit、Enter/Esc、keyboard navigation，不涉及业务 Inspector

- `editor.shell.bool_field_basic`
  Build target: `editor_ui_bool_field_basic_validation`
  Executable: `XCUIEditorBoolFieldBasicValidation.exe`
  Scope: BoolField 基础控件契约；只验证点击切换、Space/Enter 切换、hover/focus/value/result 联动

- `editor.shell.number_field_basic`
  Build target: `editor_ui_number_field_basic_validation`
  Executable: `XCUIEditorNumberFieldBasicValidation.exe`
  Scope: NumberField 基础控件契约；只验证步进按钮、直接字符编辑、Enter 提交、Esc 取消、hover/focus/result 联动

- `editor.shell.enum_field_basic`
  Build target: `editor_ui_enum_field_basic_validation`
  Executable: `XCUIEditorEnumFieldBasicValidation.exe`
  Scope: EnumField 基础控件契约；只验证前后切换按钮、Left/Right/Home/End 键盘切换、hover/focus/result 联动

- `editor.shell.status_bar_basic`
  Build target: `editor_ui_status_bar_basic_validation`
  Executable: `XCUIEditorStatusBarBasicValidation.exe`
  Scope: status bar slot layout, hover/active segment hit target, separator layout only

- `editor.shell.tree_view_basic`
  Build target: `editor_ui_tree_view_basic_validation`
  Executable: `XCUIEditorTreeViewBasicValidation.exe`
  Scope: TreeView 基础控件验证；只检查行缩进、disclosure 展开/折叠、selection、hover/focus 和 hit-test，不涉及业务面板

- `editor.shell.tree_view_multiselect`
  Build target: `editor_ui_tree_view_multiselect_validation`
  Executable: `XCUIEditorTreeViewMultiSelectValidation.exe`
  Scope: TreeView 多选契约验证；只检查 Ctrl/Shift 多选、锚点、右键命中已选集合、键盘范围扩选、expanded/visible/current 同步，不涉及业务面板

- `editor.shell.tree_view_inline_rename`
  Build target: `editor_ui_tree_view_inline_rename_validation`
  Executable: `XCUIEditorTreeViewInlineRenameValidation.exe`
  Scope: TreeView inline rename 契约验证；只检查 F2 开启、字符编辑、Enter 提交、Esc 取消、点击外部结束编辑，以及标签写回

- `editor.shell.list_view_basic`
  Build target: `editor_ui_list_view_basic_validation`
  Executable: `XCUIEditorListViewBasicValidation.exe`
  Scope: ListView 基础控件验证；只检查 row 排列、selection、hover/focus、Up/Down/Home/End 键盘导航和 hit-test，不涉及业务面板

- `editor.shell.list_view_multiselect`
  Build target: `editor_ui_list_view_multiselect_validation`
  Executable: `XCUIEditorListViewMultiSelectValidation.exe`
  Scope: ListView 多选契约验证；只检查 Ctrl/Shift 多选、锚点、右键命中已选集合、键盘范围扩选、current/primary 同步，不涉及业务面板

- `editor.shell.list_view_inline_rename`
  Build target: `editor_ui_list_view_inline_rename_validation`
  Executable: `XCUIEditorListViewInlineRenameValidation.exe`
  Scope: ListView inline rename 契约验证；只检查 F2 开启、字符编辑、Enter 提交、Esc 取消、点击外部结束编辑，以及标签写回

- `editor.shell.tab_strip_basic`
  Build target: `editor_ui_tab_strip_basic_validation`
  Executable: `XCUIEditorTabStripBasicValidation.exe`
  Scope: tab header layout, selected/hover/focus, close hit target, close fallback, Left/Right/Home/End navigation only

- `editor.shell.viewport_slot_basic`
  Build target: `editor_ui_viewport_slot_basic_validation`
  Executable: `XCUIEditorViewportSlotBasicValidation.exe`
  Scope: viewport top bar / surface / status bar layout, hover/focus/active/capture, texture vs fallback only

- `editor.shell.viewport_shell_basic`
  Build target: `editor_ui_viewport_shell_basic_validation`
  Executable: `XCUIEditorViewportShellBasicValidation.exe`
  Scope: `ResolveUIEditorViewportShellRequest(...)` + `UpdateUIEditorViewportShell(...)` basic contract, TopBar / BottomBar request-size sync, input rect + hover/focus/capture state sync only

- `editor.shell.workspace_viewport_compose`
  Build target: `editor_ui_workspace_viewport_compose_validation`
  Executable: `XCUIEditorWorkspaceViewportComposeValidation.exe`
  Scope: `ResolveUIEditorWorkspaceComposeRequest(...)` + `UpdateUIEditorWorkspaceCompose(...)` body presentation contract only; selected Scene tab body is hosted by `ViewportShell`, switching back to Document restores DockHost placeholder

- `editor.shell.workspace_interaction_basic`
  Build target: `editor_ui_workspace_interaction_basic_validation`
  Executable: `XCUIEditorWorkspaceInteractionBasicValidation.exe`
  Scope: `UpdateUIEditorWorkspaceInteraction(...)` unified contract only; DockHost splitter/tab interaction plus ViewportShell body focus/capture routing in the same workspace layer

- `editor.state.panel_session_flow`
  Build target: `editor_ui_panel_session_flow_validation`
  Executable: `XCUIEditorPanelSessionFlowValidation.exe`
  Scope: command dispatch + workspace controller + open/close/show/hide/activate

- `editor.state.panel_host_lifecycle`
  Build target: `editor_ui_panel_host_lifecycle_validation`
  Executable: `XCUIEditorPanelHostLifecycleValidation.exe`
  Scope: panel host attach/detach/show/hide/activate/focus lifecycle only; active/focus decoupling and hidden-tab attached state

- `editor.state.layout_persistence`
  Build target: `editor_ui_layout_persistence_validation`
  Executable: `XCUIEditorLayoutPersistenceValidation.exe`
  Scope: layout snapshot + serialize/deserialize + invalid payload reject

- `editor.state.shortcut_dispatch`
  Build target: `editor_ui_shortcut_dispatch_validation`
  Executable: `XCUIEditorShortcutDispatchValidation.exe`
  Scope: shortcut match + scope + suppression + command dispatch

- `editor.state.viewport_input_bridge_basic`
  Build target: `editor_ui_viewport_input_bridge_basic_validation`
  Executable: `XCUIEditorViewportInputBridgeBasicValidation.exe`
  Scope: viewport hover/focus/capture, local pointer coordinates, wheel/key/character bridge only

Run:

```bash
cmake --build build --config Debug --target editor_ui_integration_tests
```

Auto capture:

- Set `XCUI_AUTO_CAPTURE_ON_STARTUP=1` before launching a validation executable to force a first-frame screenshot into that scenario's `captures/` directory.
- Manual validation still uses `F12`; startup auto capture is only for deterministic self-check / automation.

Selected controls:

- `shell/workspace_shell_compose/`
  Drag splitters, switch `Document A/B/C`, close tabs or side panels, press `Reset`, press `F12`.

- `shell/editor_shell_compose/`
  Click `切到 Scene / 切到 Document`, toggle `TopBar / BottomBar / Texture`, inspect `MenuBar Rect / Workspace Rect / StatusBar Rect / Selected Presentation / Request Size`, press `Reset`, press `截图` or `F12`.

- `shell/editor_shell_interaction/`
  Click `File / Window`, hover `Workspace Tools`, click outside the menu or press `Esc`, then click `Document` or drag a splitter, inspect `Open Root / Popup Chain / Submenu Path / Selected Presentation / Active Panel / Host Capture / Result`, press `Reset`, `Capture`, or `F12`.

- `shell/dock_host_basic/`
  Drag `root-split`, click `Document A`, close `Document B`, click `Details`, close `Console`, inspect `Hover / Result / Active Panel / Visible Panels / Capture / split ratio`, press `Reset`, `Capture`, or `F12`.

- `shell/panel_content_host_basic/`
  Click `Activate Doc A / Activate Doc B / Activate Console / Close Inspector / Open Inspector`, inspect `Mounted Panels / Events` 和蓝色 external body，按 `Capture` 或 `F12`。

- `shell/menu_bar_basic/`
  Click `File / Window / Layout`, move the mouse across menu items, click outside the menu or press `Esc`, press `F12`.

- `shell/context_menu_basic/`
  Right click inside `Context Target`, hover `Workspace Tools`, click actions, click outside the menu or press `Esc`, press `F12`.

- `shell/panel_frame_basic/`
  Move the mouse over the preview panel, click `Body / Pin / Close`, toggle `Active / Focus / Closable / Footer`, press `F12`.

- `shell/scroll_view_basic/`
  把鼠标移到右侧日志区内滚轮滚动，拖拽 scrollbar thumb，检查 `Hover / Focused / Thumb Dragging / Offset / Has Scrollbar / Result`，按 `重置`、`截图(F12)` 或直接按 `F12`。

- `shell/bool_field_basic/`
  先看顶部中文说明，再点击 `BoolField` 的 row 或 toggle；控件获得 focus 后按 `Space / Enter`，检查 `Hover / Focused / Value / Result` 是否同步更新，按 `重置`、`截图(F12)` 或直接按 `F12`。
- `shell/number_field_basic/`
  先看顶部中文说明，再点击 `- / +` 检查步进；点击数值框后直接输入字符并按 `Enter` 提交，或按 `Esc` 取消，检查 `Hover / Focused / Editing / Value / Result`，按 `重置`、`截图(F12)` 或直接按 `F12`。
- `shell/enum_field_basic/`
  先看顶部中文说明，再点击 `< / >` 切换选项；控件获得 focus 后按 `Left / Right / Home / End`，检查 `Hover / Focused / Selected / Result`，按 `重置`、`截图(F12)` 或直接按 `F12`。
- `shell/status_bar_basic/`
  Move the mouse across leading/trailing segments, click interactive segments, toggle focus/active, press `F12`.

- `shell/tree_view_basic/`
  先看顶部中文说明“这个测试在验证什么功能”，再点击 disclosure 和树节点行，检查 `Hover / Focused / Selected / Expanded / Visible / Result`，按 `重置`、`截图(F12)` 或直接按 `F12`。

- `shell/tree_view_multiselect/`
  先看顶部中文说明“这个测试在验证什么功能”，再分别执行 `单击`、`Ctrl+单击`、`Shift+单击`、`Shift+Up/Down/Home/End`、`Right Click`，检查 `Primary / Selected Count / Selected Ids / Anchor / Current / Expanded / Visible / Result`。

- `shell/tree_view_inline_rename/`
  先看顶部中文说明“这个测试在验证什么功能”，再依次执行 `单击`、`F2`、输入字符、`Enter / Esc / 点击外部`，检查 `Rename Active / Rename Item / Draft / Committed / Result`。

- `shell/list_view_basic/`
  先看顶部中文说明“这个测试在验证什么功能”，再点击列表行，并在列表获得 focus 后按 `Up / Down / Home / End`，检查 `Hover / Focused / Selected / Current / Result`，按 `重置`、`截图(F12)` 或直接按 `F12`。

- `shell/list_view_multiselect/`
  先看顶部中文说明“这个测试在验证什么功能”，再分别执行 `单击`、`Ctrl+单击`、`Shift+单击`、`Shift+Up/Down/Home/End`、`Right Click`，检查 `Primary / Selected Count / Selected Ids / Anchor / Current / Result`。

- `shell/list_view_inline_rename/`
  先看顶部中文说明“这个测试在验证什么功能”，再依次执行 `单击`、`F2`、输入字符、`Enter / Esc / 点击外部`，检查 `Rename Active / Rename Item / Draft / Committed / Result`。
- `shell/tab_strip_basic/`
  Click `Document A / B / C`, click `X` on closable tabs, click content to focus, press `Left / Right / Home / End`, press `Reset`, press `F12`.

- `shell/viewport_slot_basic/`
  Hover toolbar / surface / status bar, click surface to focus, hold and release left mouse to inspect capture, toggle `TopBar / StatusBar / Texture / Aspect`, press `F12`.

- `shell/viewport_shell_basic/`
  Hover / click / drag the viewport shell surface, toggle `TopBar / BottomBar / Texture`, inspect left-side `Request Size / Input Rect / Hover Hit / Hover / Focus / Capture / Result`, press `Reset`, press `截图` or `F12`.

- `shell/workspace_viewport_compose/`
  Click `切到 Scene / 切到 Document`, toggle `TopBar / BottomBar / Texture`, hover or click the center viewport only when `Scene` is selected, inspect `Selected Presentation / Request Size / Hover / Focus / Capture / Result`, press `Reset`, press `截图` or `F12`.

- `shell/workspace_interaction_basic/`
  Click the center `Viewport` body to inspect unified focus/capture routing, click `Document` to verify fallback to DockHost placeholder, drag `root-split` to verify layout sync, inspect `Selected Presentation / Active Panel / Host Capture / root-split ratio`, press `Reset`, `Capture`, or `F12`.

- `state/panel_session_flow/`
  Click `Hide Active / Show Doc A / Close Doc B / Open Doc B / Activate Details / Reset`, press `F12`.

- `state/panel_host_lifecycle/`
  Click `Hide Active / Close Doc B / Open Doc B / Activate Details / Focus Active / Clear Focus / Reset`, inspect `Events` and the three host cards, press `Capture` or `F12`.

- `state/layout_persistence/`
  Click `Hide Active -> Save Layout -> Close Doc B -> Load Layout`, click `Load Invalid`, press `F12`.

- `state/shortcut_dispatch/`
  Press `Ctrl+P / Ctrl+H / Ctrl+W / Ctrl+O / Ctrl+R`, toggle `Text Input`, press `F12`.

- `state/viewport_input_bridge_basic/`
  Hover surface, click and drag outside, roll the wheel, press `A / W / F / Space`, type characters, click outside to clear focus, press `F12`.