docs: add Editor API documentation

docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md

@@ -0,0 +1,46 @@
+# AboutEditorDialog
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/AboutEditorDialog.h`
+
+**描述**: 绘制编辑器 About 模态弹窗。
+
+## 概述
+
+`DrawEditorAboutDialog` 是一个很轻量的 UI helper，用来响应主菜单 Help -> About 的弹窗请求。  
+它依赖 [`DeferredPopupState`](../PopupState/PopupState.md) 控制打开时机，并在弹窗中显示：
+
+- 编辑器名称
+- 简短说明文字
+- 固定日期信息
+- 当前项目路径
+
+## 当前实现
+
+- 弹窗 ID 固定为 `About XCEngine Editor`
+- 打开请求由 `popupState.ConsumeOpenRequest()` 驱动
+- 如果传入上下文，会显示 `context->GetProjectPath()`
+- 关闭方式只有一个 `Close` 按钮
+
+## 设计说明
+
+About 弹窗本身不是复杂系统，但把它收口成独立 helper 是合理的：
+
+- `MainMenuActionRouter` 不需要关心弹窗内部布局
+- `MenuBar` 不需要持有具体 UI 绘制细节
+- 日后扩展版本号、版权、第三方库列表时，改动面会更集中
+
+## 当前限制
+
+- 日期 `2026-03-27` 是硬编码文本，不是构建时自动注入
+- “UI Refactor in progress” 也是当前开发态说明，不是正式产品文案
+- 没有版本号、提交哈希或许可证信息
+
+## 相关文档
+
+- [UI](../UI.md)
+- [PopupState](../PopupState/PopupState.md)
+- [MainMenuActionRouter](../../Actions/MainMenuActionRouter/MainMenuActionRouter.md)

docs/api/XCEngine/Editor/UI/BaseTheme/BaseTheme.md

@@ -0,0 +1,49 @@
+# BaseTheme
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/BaseTheme.h`
+
+**描述**: 定义编辑器默认 Dear ImGui 主题的颜色与尺寸指标。
+
+## 概述
+
+`BaseTheme.h` 把编辑器默认外观拆成三层函数：
+
+- `ApplyBaseThemeColors`
+- `ApplyBaseThemeMetrics`
+- `ApplyBaseTheme`
+
+这让主题既能整体应用，也能在需要时分别覆盖颜色或间距。
+
+## 当前实现
+
+- 主题整体是偏中性、低饱和的灰色编辑器风格
+- Docking 标签、按钮、工具栏、表格、滚动条等颜色都在这里集中定义
+- 圆角、边框、间距和 padding 也都由这里设置
+- [`ImGuiSession`](../ImGuiSession/ImGuiSession.md) 和 `Theme.cpp` 会使用这组 helper
+
+## 设计说明
+
+商业编辑器通常不会把颜色和 spacing 散落在所有面板里，而是会先建立一套基础主题。  
+这样做的好处是：
+
+- 新面板默认继承统一视觉语言
+- 后续品牌化或皮肤切换时有一个集中入口
+- 设计 token 和实际 ImGui style 之间的边界更清楚
+
+当前实现已经具备这个方向，虽然还不是完整可换肤系统。
+
+## 当前限制
+
+- 主题参数主要是硬编码值
+- 没有亮色主题或用户配置
+- 主题切换和局部覆盖机制尚未成体系
+
+## 相关文档
+
+- [UI](../UI.md)
+- [StyleTokens](../StyleTokens/StyleTokens.md)
+- [ImGuiSession](../ImGuiSession/ImGuiSession.md)

docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md

@@ -0,0 +1,38 @@
+# ConsoleFilterState
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `class`
+
+**源文件**: `editor/src/UI/ConsoleFilterState.h`
+
+**描述**: 保存 Console 面板的日志等级过滤开关。
+
+## 概述
+
+`ConsoleFilterState` 是一个很小的状态对象，负责决定哪些日志等级会在 Console 面板中显示。
+
+当前内部维护三组布尔值：
+
+- `m_showInfo`
+- `m_showWarning`
+- `m_showError`
+
+## 当前实现
+
+- `ShowInfo()` / `ShowWarning()` / `ShowError()` 返回可写引用，便于直接绑定工具栏切换按钮
+- `Allows()` 的等级映射如下：
+  - `Verbose` / `Debug` / `Info` 归到 Info
+  - `Warning` 归到 Warning
+  - `Error` / `Fatal` 归到 Error
+
+## 设计说明
+
+这种“三档过滤”很像商业编辑器控制台的第一层筛选：先把低成本的等级过滤做好，再考虑更重的搜索、分类和标签系统。  
+对于当前阶段的编辑器，这已经能显著提升日志可读性。
+
+## 相关文档
+
+- [UI](../UI.md)
+- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md)
+- [ConsolePanel](../../panels/ConsolePanel/ConsolePanel.md)

docs/api/XCEngine/Editor/UI/ConsoleLogFormatter/ConsoleLogFormatter.md

@@ -0,0 +1,44 @@
+# ConsoleLogFormatter
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/ConsoleLogFormatter.h`
+
+**描述**: 把 `Debug::LogEntry` 转换为 Console 面板展示文本。
+
+## 概述
+
+`ConsoleLogFormatter.h` 负责把引擎日志记录格式化为用户在 Console 面板里看到的单行文本。  
+当前主要入口：
+
+- `ConsoleLogPrefix`
+- `BuildConsoleLogText`
+
+## 当前实现
+
+- `Info` / `Debug` / `Verbose` 会被统一格式化为 `[INFO]`
+- `Warning` 会格式化为 `[WARN]`
+- `Error` / `Fatal` 会格式化为 `[ERROR]`
+- 最终文本格式是：`[PREFIX] [Category] message`
+
+## 设计说明
+
+把格式化独立出来很有必要，因为：
+
+- 日志采集层不应关心 UI 文本长什么样
+- Console 面板也不应自己拼接 category 和 level
+- 后续如果引入时间戳、来源文件、富文本高亮，只需要收敛改这一层
+
+## 当前限制
+
+- 当前格式是纯文本单行
+- 没有时间戳、线程号或源码位置
+- `Debug` 和 `Verbose` 被归并到 Info，颗粒度较粗
+
+## 相关文档
+
+- [UI](../UI.md)
+- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md)
+- [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md)

docs/api/XCEngine/Editor/UI/Core/Core.md

@@ -0,0 +1,46 @@
+# Core
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/Core.h`
+
+**描述**: 提供更高层 UI helper 依赖的底层 ImGui 包装，包括控制行、样式栈、弹窗包装和工具栏按钮。
+
+## 概述
+
+不要把这个文件和 `Editor/Core` 子模块混淆。  
+`UI/Core.h` 是 UI 辅助层自己的基础工具头，许多上层 helper 都会依赖它，包括：
+
+- 控件行绘制 `DrawControlRow`
+- 样式压栈 / 出栈辅助
+- 带统一 padding 的 Popup 包装
+- `ToolbarButton`
+- 当前窗口底边线绘制
+
+## 当前实现
+
+- `DrawControlRow` 用 ImGui table 实现“标签列 + 控件列”的双列布局
+- `BeginPopup` / `BeginPopupContextItem` / `BeginModalPopup` 都会统一应用 popup window padding
+- `BeginDisabled` / `EndDisabled` 做了条件包装，便于上层少写分支
+- 这是 [`ScalarControls`](../ScalarControls/ScalarControls.md) 与 [`VectorControls`](../VectorControls/VectorControls.md) 的基础依赖
+
+## 设计说明
+
+这类“内部基础 UI helper”在商业编辑器里很常见。  
+原因是 ImGui 原生 API 非常灵活，但如果每个面板都直接手写 style push/pop、table 布局和 popup 细节，代码会很快失控。  
+先建立一层统一的 UI Core，能让上层组件写得更稳、更少样板代码。
+
+## 当前限制
+
+- 这层仍然是 inline helper 集合，不是完整 widget framework
+- 样式栈安全主要依赖调用约定，没有更强的静态约束
+- 仍然明显偏向当前编辑器自己的使用场景
+
+## 相关文档
+
+- [UI](../UI.md)
+- [ScalarControls](../ScalarControls/ScalarControls.md)
+- [VectorControls](../VectorControls/VectorControls.md)
+- [PropertyGrid](../PropertyGrid/PropertyGrid.md)

docs/api/XCEngine/Editor/UI/DockHostStyle/DockHostStyle.md

@@ -0,0 +1,35 @@
+# DockHostStyle
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `class`
+
+**源文件**: `editor/src/UI/DockHostStyle.h`
+
+**描述**: 为主 DockSpace 应用一组临时样式覆盖的 RAII scope。
+
+## 概述
+
+`DockHostStyleScope` 的角色很单一：在进入主 DockSpace 绘制前压入一组 docking 相关样式，在离开时自动恢复。
+
+它主要服务于 [`DockLayoutController`](../../Layout/DockLayoutController/DockLayoutController.md)。
+
+## 当前实现
+
+- 构造时 `PushStyleVar` 5 次，`PushStyleColor` 7 次
+- 覆盖内容主要是：
+  - Dock tab padding
+  - Tab 边框与 overline
+  - Tab 的普通 / hover / selected / dimmed 颜色
+- 析构时自动对称 `Pop`
+
+## 设计说明
+
+这是一种标准 RAII UI 封装。  
+对于 ImGui 这种依赖成对 push/pop 的库，scope 包装几乎是最稳妥的工程化手段之一，能显著减少忘记恢复样式导致的串色问题。
+
+## 相关文档
+
+- [UI](../UI.md)
+- [StyleTokens](../StyleTokens/StyleTokens.md)
+- [DockLayoutController](../../Layout/DockLayoutController/DockLayoutController.md)

docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md

@@ -0,0 +1,51 @@
+# ImGuiBackendBridge
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `class`
+
+**源文件**: `editor/src/UI/ImGuiBackendBridge.h`
+
+**描述**: 封装 Dear ImGui Win32 + D3D12 backend 的初始化、逐帧驱动和窗口消息桥接。
+
+## 概述
+
+`ImGuiBackendBridge` 是编辑器 UI 栈里很关键但很底层的一环。  
+它不创建 ImGui context，也不负责布局，而是把现有 context 接到具体平台和渲染后端上。
+
+当前核心职责：
+
+- 初始化 `imgui_impl_win32`
+- 初始化 `imgui_impl_dx12`
+- 每帧调用 backend 的 `NewFrame`
+- 把 `ImGui::GetDrawData()` 提交到 D3D12 command list
+- 处理 Win32 消息转发
+
+## 当前实现
+
+- `Initialize()` 需要 `HWND`、`ID3D12Device*` 和 SRV heap
+- 默认 frame count 为 `3`
+- 默认 back buffer format 为 `DXGI_FORMAT_R8G8B8A8_UNORM`
+- `HandleWindowMessage()` 是静态 helper，直接转发给 `ImGui_ImplWin32_WndProcHandler`
+
+## 设计说明
+
+把 backend 绑定层单独抽出来，有两个很现实的好处：
+
+- `Application` 不需要直接依赖第三方 backend 细节
+- 如果未来替换成别的渲染后端或宿主窗口层，修改点更集中
+
+在商业级编辑器里，这一层通常都存在，即使名字不同，本质上也是“UI 平台绑定桥”。
+
+## 当前限制
+
+- 当前明确绑定 Win32 + D3D12
+- 没有重复初始化保护之外的更复杂状态机
+- 不负责 ImGui context 生命周期，那部分由 [`ImGuiSession`](../ImGuiSession/ImGuiSession.md) 管理
+
+## 相关文档
+
+- [UI](../UI.md)
+- [ImGuiSession](../ImGuiSession/ImGuiSession.md)
+- [Application](../../Application/Application.md)
+- [D3D12WindowRenderer](../../Platform/D3D12WindowRenderer/D3D12WindowRenderer.md)

docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md

@@ -0,0 +1,38 @@
+# ImGuiSession
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `class`
+
+**源文件**: `editor/src/UI/ImGuiSession.h`
+
+**描述**: 管理编辑器的 ImGui 上下文、布局 ini 文件位置、基础字体配置和默认主题应用。
+
+## 概述
+
+`ImGuiSession` 负责的是 ImGui 自身的生命周期和持久化布局配置。
+
+它当前主要做三件事：
+
+- 创建/销毁 ImGui context
+- 把布局 ini 文件放到 `<project>/.xceditor/imgui_layout.ini`
+- 配置默认字体并应用基础主题
+
+## 当前实现说明
+
+- `Initialize(projectPath)` 会开启 `ImGuiConfigFlags_DockingEnable`。
+- 字体优先尝试加载 `C:/Windows/Fonts/msyh.ttc`，失败时回退到 ImGui 默认字体。
+- `Shutdown()` 会先保存设置，再销毁当前 context。
+- `SaveSettings()` 只在 context 存在且 ini 路径非空时生效。
+
+## 当前实现边界
+
+- 当前字体路径写死为 Windows 字体目录。
+- 当前 ini 文件位置策略是项目局部目录，而不是全局用户目录。
+- 当前主要负责会话和基础样式，不处理平台/渲染后端桥接。
+
+## 相关文档
+
+- [UI](../UI.md)
+- [Application](../../Application/Application.md)
+- [Win32EditorHost](../../Platform/Win32EditorHost/Win32EditorHost.md)

docs/api/XCEngine/Editor/UI/PanelChrome/PanelChrome.md

@@ -0,0 +1,45 @@
+# PanelChrome
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/PanelChrome.h`
+
+**描述**: 提供编辑器面板窗口、工具栏和内容区的 RAII 外壳。
+
+## 概述
+
+`PanelChrome.h` 让各个面板可以用统一方式搭建三段式结构：
+
+- `PanelWindowScope`
+- `PanelToolbarScope`
+- `PanelContentScope`
+
+这几乎就是当前编辑器所有面板的“标准壳层”。
+
+## 当前实现
+
+- 三个 scope 都在构造时 Begin，在析构时 End
+- 会统一应用窗口 padding、工具栏背景色、item spacing 等样式
+- `PanelToolbarScope` 还会在退出时绘制底部分隔线
+
+从 `HierarchyPanel`、`ProjectPanel`、`ConsolePanel`、`InspectorPanel` 当前实现看，这套壳层已经成为面板 UI 的主路径。
+
+## 设计说明
+
+这是很典型的商业编辑器代码组织方式：  
+先把窗口 chrome 标准化，再让具体面板只关心业务内容。
+
+收益非常直接：
+
+- 面板外观一致
+- Begin/End 对称性更安全
+- 工具栏和内容区的布局约束自然统一
+
+## 相关文档
+
+- [UI](../UI.md)
+- [StyleTokens](../StyleTokens/StyleTokens.md)
+- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md)
+- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md)

docs/api/XCEngine/Editor/UI/PopupState/PopupState.md

@@ -0,0 +1,49 @@
+# PopupState
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/PopupState.h`
+
+**描述**: 提供延迟弹窗、定向弹窗、文本输入弹窗和行内重命名状态容器。
+
+## 概述
+
+`PopupState.h` 当前包含四类非常实用的 UI 状态辅助类型：
+
+- `DeferredPopupState`
+- `TargetedPopupState<T>`
+- `TextInputPopupState<BufferCapacity>`
+- `InlineTextEditState<ItemId, BufferCapacity>`
+
+它们共同解决一个问题：把 ImGui 的即时模式弹窗交互变成可维护的状态机。
+
+## 当前实现
+
+- `DeferredPopupState` 负责“下一帧打开弹窗”
+- `TargetedPopupState<T>` 在打开弹窗的同时绑定一个目标对象
+- `TextInputPopupState` 内置固定容量字符缓冲区，适合创建目录等对话框
+- `InlineTextEditState` 适合 Hierarchy 中的行内重命名
+
+## 设计说明
+
+即时模式 UI 最大的痛点之一，就是弹窗、右键菜单和重命名输入框的状态容易散。  
+把这些交互状态抽成小类型，是非常划算的工程化投资：
+
+- 面板类不会充满零散布尔标志和字符数组
+- 打开请求和真正 `OpenPopup()` 的时机能被清晰区分
+- 复用性很好，多个面板都能直接用
+
+## 当前限制
+
+- 输入缓冲区容量是模板常量，需要调用者自己选大小
+- 没有更复杂的校验、历史记录或多字段表单状态
+- 目标对象状态主要依赖值拷贝或轻量句柄，不负责更深生命周期管理
+
+## 相关文档
+
+- [UI](../UI.md)
+- [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md)
+- [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md)
+- [AboutEditorDialog](../AboutEditorDialog/AboutEditorDialog.md)

docs/api/XCEngine/Editor/UI/PropertyGrid/PropertyGrid.md

@@ -0,0 +1,49 @@
+# PropertyGrid
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/PropertyGrid.h`
+
+**描述**: 在 Inspector 中提供统一的属性行控件，并集成交互式撤销辅助。
+
+## 概述
+
+`PropertyGrid.h` 是当前 Inspector 属性编辑体验的中枢之一。  
+它在 [`ScalarControls`](../ScalarControls/ScalarControls.md) 和 [`VectorControls`](../VectorControls/VectorControls.md) 之上封装了一组更贴近 Inspector 语义的 API：
+
+- `DrawPropertyFloat`
+- `DrawPropertyBool`
+- `DrawPropertyColor4`
+- `DrawPropertyCombo`
+- `DrawPropertyVec3Input`
+- `ApplyPropertyChange`
+
+## 当前实现
+
+- 统一使用 `InspectorPropertyLabelWidth()` 作为标签列宽
+- `ApplyPropertyChange` 在字段变化时可选地调用 `undoManager->BeginInteractiveChange()`
+- 具体组件编辑器通常会先调用 `DrawProperty*`，再把结果交给 `ApplyPropertyChange`
+
+## 设计说明
+
+商业编辑器里的 Inspector 很少直接暴露底层控件 API，而是会先收口成属性网格层。  
+这样做的好处是：
+
+- 全部组件 editor 的标签宽度、排版和交互节奏统一
+- 撤销系统可以自然嵌入属性修改路径
+- 组件编辑器代码更接近“编辑语义”，而不是原始 ImGui 调用
+
+## 当前限制
+
+- 目前仍然是手写属性 helper，不是基于反射的通用属性系统
+- `ApplyPropertyChange` 只负责开始交互式改动，最终收尾仍要靠 Inspector 路由层
+- 主要面向 Inspector，不是通用任意表单框架
+
+## 相关文档
+
+- [UI](../UI.md)
+- [ScalarControls](../ScalarControls/ScalarControls.md)
+- [VectorControls](../VectorControls/VectorControls.md)
+- [TransformComponentEditor](../../ComponentEditors/TransformComponentEditor/TransformComponentEditor.md)

docs/api/XCEngine/Editor/UI/ScalarControls/ScalarControls.md

@@ -0,0 +1,46 @@
+# ScalarControls
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/ScalarControls.h`
+
+**描述**: 提供基于双列表格布局的标量属性控件，如 float、int、bool、颜色和下拉框。
+
+## 概述
+
+`ScalarControls.h` 封装的是 Inspector 最基础的输入部件：
+
+- `DrawFloat`
+- `DrawInt`
+- `DrawBool`
+- `DrawColor3`
+- `DrawColor4`
+- `DrawSliderFloat`
+- `DrawSliderInt`
+- `DrawCombo`
+
+## 当前实现
+
+- 所有控件都建立在 [`DrawControlRow`](../Core/Core.md) 之上
+- 默认列宽来自 `DefaultControlLabelWidth()`
+- 每个控件都统一使用 `##value` 作为内部 item id 后缀，并通过外层 `PushID(label)` 隔离
+
+## 设计说明
+
+这层的价值在于把“输入控件长什么样”从组件编辑器里抽出来。  
+否则每个组件 editor 都会重复写：
+
+- 两列表格
+- 标签列宽
+- `SetNextItemWidth`
+- 不同控件的 ImGui 参数模板
+
+`ScalarControls` 让上层代码只保留业务字段名和少量范围参数。
+
+## 相关文档
+
+- [UI](../UI.md)
+- [Core](../Core/Core.md)
+- [PropertyGrid](../PropertyGrid/PropertyGrid.md)

docs/api/XCEngine/Editor/UI/SceneStatusWidget/SceneStatusWidget.md

@@ -0,0 +1,36 @@
+# SceneStatusWidget
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/SceneStatusWidget.h`
+
+**描述**: 在主菜单栏右侧绘制当前场景文件状态，并在悬停时提供详细提示。
+
+## 概述
+
+`DrawSceneStatusWidget` 是一个很小但很有价值的状态反馈组件。  
+它会把当前场景的保存状态浓缩成菜单栏右侧的一段文本，并在悬停时展开 tooltip。
+
+## 当前实现
+
+- dirty 场景会以前缀 `* ` 标记
+- 没有场景路径时会显示 `Unsaved.xc`
+- 有路径时只显示文件名
+- tooltip 中会进一步展示：
+  - 场景名
+  - 文件名
+  - 状态 `Modified / Saved`
+  - 完整路径或“尚未保存”提示
+
+## 设计说明
+
+这非常符合商业编辑器的 UI 习惯：  
+把高频状态压缩成轻量但始终可见的角落信息，而不是每次都让用户去打开另一个面板确认场景是否已保存。
+
+## 相关文档
+
+- [UI](../UI.md)
+- [MainMenuActionRouter](../../Actions/MainMenuActionRouter/MainMenuActionRouter.md)
+- [SceneManager](../../Managers/SceneManager/SceneManager.md)

docs/api/XCEngine/Editor/UI/StyleTokens/StyleTokens.md

@@ -0,0 +1,46 @@
+# StyleTokens
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/StyleTokens.h`
+
+**描述**: 统一定义编辑器 UI 使用的颜色、尺寸、间距和布局 token。
+
+## 概述
+
+`StyleTokens.h` 是当前 UI 层的设计 token 中心。  
+它集中提供了大量 inline token helper，例如：
+
+- Dock 标签颜色
+- 工具栏高度与 padding
+- 资产网格尺寸
+- Inspector 标签列宽
+- 弹窗按钮尺寸
+- 向量控件按钮颜色
+- Console 状态颜色
+
+## 设计说明
+
+这是商业编辑器 UI 非常推荐的做法。  
+不要在控件代码里到处写 `6.0f`、`0.24f`、`104.0f` 这种魔法数字，而应先抽象成 token。
+
+收益包括：
+
+- 调整风格时能集中修改
+- 命名本身就表达设计意图
+- 高层 widget 与具体数值解耦
+
+## 当前限制
+
+- 仍然是 header inline 常量函数，而不是数据驱动主题系统
+- token 数量已经较多，后续可能需要再分层
+- 当前主要围绕唯一默认主题设计
+
+## 相关文档
+
+- [UI](../UI.md)
+- [BaseTheme](../BaseTheme/BaseTheme.md)
+- [PanelChrome](../PanelChrome/PanelChrome.md)
+- [Widgets](../Widgets/Widgets.md)

docs/api/XCEngine/Editor/UI/UI.md

@@ -0,0 +1,50 @@
+# UI
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `submodule`
+
+**描述**: 编辑器 ImGui 基础设施、主题、控件与面板绘制辅助层。
+
+## 概述
+
+`UI` 子模块当前内容很多，但核心方向很清楚：
+
+- 维护 ImGui 会话与布局文件
+- 封装统一视觉主题
+- 提供属性面板、工具栏、菜单、场景状态等 UI 辅助
+
+已文档化的核心页面：
+
+- [ImGuiSession](ImGuiSession/ImGuiSession.md)
+- [ImGuiBackendBridge](ImGuiBackendBridge/ImGuiBackendBridge.md)
+- [BaseTheme](BaseTheme/BaseTheme.md)
+- [StyleTokens](StyleTokens/StyleTokens.md)
+- [Core](Core/Core.md)
+- [PanelChrome](PanelChrome/PanelChrome.md)
+- [Widgets](Widgets/Widgets.md)
+- [PopupState](PopupState/PopupState.md)
+- [ScalarControls](ScalarControls/ScalarControls.md)
+- [VectorControls](VectorControls/VectorControls.md)
+- [PropertyGrid](PropertyGrid/PropertyGrid.md)
+- [DockHostStyle](DockHostStyle/DockHostStyle.md)
+- [ConsoleFilterState](ConsoleFilterState/ConsoleFilterState.md)
+- [ConsoleLogFormatter](ConsoleLogFormatter/ConsoleLogFormatter.md)
+- [SceneStatusWidget](SceneStatusWidget/SceneStatusWidget.md)
+- [AboutEditorDialog](AboutEditorDialog/AboutEditorDialog.md)
+
+`UI/UI.h` 本身只是聚合入口，真正值得阅读的是这些分层 helper：
+
+- `ImGuiSession + ImGuiBackendBridge` 负责上下文与后端绑定
+- `BaseTheme + StyleTokens` 负责视觉规范
+- `Core + PanelChrome + Widgets` 负责通用交互壳层
+- `ScalarControls + VectorControls + PropertyGrid` 负责 Inspector 表单体验
+
+这样拆分的好处，是把 Dear ImGui 容易失控的即时模式代码收束成一套可复用部件库。
+
+## 相关文档
+
+- [Editor 模块](../Editor.md)
+- [Application](../Application/Application.md)
+- [Platform](../Platform/Platform.md)
+- [Editor Architecture And Workflow](../../../_guides/Editor/Editor-Architecture-And-Workflow.md)

docs/api/XCEngine/Editor/UI/VectorControls/VectorControls.md

@@ -0,0 +1,49 @@
+# VectorControls
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/VectorControls.h`
+
+**描述**: 提供向量属性的多轴输入控件，支持带重置按钮和纯输入两种模式。
+
+## 概述
+
+`VectorControls.h` 当前提供：
+
+- `DrawVec2`
+- `DrawVec3`
+- `DrawVec3Input`
+- 更底层的 `DrawAxisFloatControls`
+
+它是 Transform 类组件编辑体验的核心基础。
+
+## 当前实现
+
+- `DrawVec3` / `DrawVec2` 提供带轴按钮的重置式控件
+- `DrawVec3Input` 提供更紧凑的纯输入版本
+- 可选输出 `isActive`，用于让 Inspector 感知控件是否仍在持续拖拽
+- 每个轴以 `AxisFloatControlSpec` 描述
+
+## 设计说明
+
+相比直接把 `Vector3` 画成三个普通 `DragFloat`，这种按轴组织的控件更符合编辑器习惯：
+
+- X/Y/Z 维度更直观
+- 重置按钮更利于快速归零
+- 更容易和交互式撤销衔接
+
+这和 Unity Inspector 中 Transform 的体验方向是相近的，只是当前实现更轻量。
+
+## 当前限制
+
+- 只覆盖 `Vector2` / `Vector3`
+- 没有 quaternion、rect、bounds 等更复杂类型控件
+- 没有多对象混合值显示
+
+## 相关文档
+
+- [UI](../UI.md)
+- [PropertyGrid](../PropertyGrid/PropertyGrid.md)
+- [TransformComponentEditor](../../ComponentEditors/TransformComponentEditor/TransformComponentEditor.md)

docs/api/XCEngine/Editor/UI/Widgets/Widgets.md

@@ -0,0 +1,52 @@
+# Widgets
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `header-helper`
+
+**源文件**: `editor/src/UI/Widgets.h`
+
+**描述**: 提供更接近编辑器业务语义的中高层 widget，如菜单命令、层级树节点、资产格子、组件区块和对话框按钮行。
+
+## 概述
+
+如果说 [`Core`](../Core/Core.md) 是底层 UI 包装，那么 `Widgets.h` 就是更贴近编辑器业务的通用组件库。  
+当前文件涵盖的内容很多，主要可以分成几类：
+
+- 菜单与命令：`MenuCommand`、`DrawMenuScope`、`DrawMenuCommands`
+- 工具栏：搜索框、标签、切换按钮、面包屑
+- Hierarchy / Project：`DrawHierarchyNode`、`DrawAssetTile`、`DrawAssetIcon`
+- Inspector：`BeginComponentSection`
+- 对话框与 tooltip：`DrawDialogActionRow`、`BeginTitledPopup`、`BeginTitledTooltip`
+- Console：`DrawConsoleLogRow`
+
+## 设计说明
+
+这类文件在商业编辑器里通常非常关键，因为它决定了“多个面板是否共享同一种交互语言”。  
+比如：
+
+- Hierarchy 节点的点击、展开和双击
+- Project 资源网格的卡片样式
+- Inspector 组件区块的标题和右键菜单
+
+如果这些都散落在各个面板里，最终 UI 行为会越来越不一致。
+
+## 当前实现特征
+
+- `MenuCommand` 把菜单项和分隔线统一成一个小数据结构
+- `AssetTileResult`、`HierarchyNodeResult` 等结果结构让调用方更容易写流程判断
+- 组件区块与工具栏、搜索框都已经形成可复用构件
+
+## 当前限制
+
+- 仍然是 header inline helpers，而不是独立 widget 类库
+- 某些 widget 仍然高度耦合当前编辑器视觉风格
+- 还没有更高级的虚拟列表、树过滤高亮或多列资源浏览控件
+
+## 相关文档
+
+- [UI](../UI.md)
+- [Core](../Core/Core.md)
+- [StyleTokens](../StyleTokens/StyleTokens.md)
+- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md)
+- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md)