docs: expand editor workspace API docs

docs/api/XCEngine/Editor/Core/EditorWorkspace/Attach.md

@@ -0,0 +1,47 @@
+# EditorWorkspace::Attach
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method`
+
+**源文件**: `editor/src/Core/EditorWorkspace.h`
+
+## 签名
+
+```cpp
+void Attach(IEditorContext& context);
+```
+
+## 作用
+
+初始化当前编辑器工作区，创建面板集合、菜单栏、Dock 布局控制器，并接入项目与场景启动流程。
+
+## 当前实现行为
+
+- 会先清空 `PanelCollection`，并把 `IEditorContext` 注入进去。
+- 随后按固定顺序创建工作区核心面板:
+  - `MenuBar`
+  - `HierarchyPanel`
+  - `SceneViewPanel`
+  - `GameViewPanel`
+  - `InspectorPanel`
+  - `ConsolePanel`
+  - `ProjectPanel`
+- 然后创建 `DockLayoutController`。
+- 在面板对象创建完成后，会执行一组工作区级初始化动作:
+  - `ProjectPanel::Initialize(projectPath)`
+  - `Commands::LoadStartupScene(context)`
+  - `m_playSessionController.Attach(context)`
+  - `m_dockLayoutController->Attach(context)`
+  - `m_panels.AttachAll()`
+
+## 设计含义
+
+- `EditorWorkspace` 当前不仅负责“挂面板”，还承担了项目打开后的默认工作区启动编排。
+- 启动场景加载发生在工作区 attach 阶段，而不是更晚的按需面板渲染阶段。
+
+## 相关文档
+
+- [EditorWorkspace](EditorWorkspace.md)
+- [Detach](Detach.md)
+- [Panel Update, Event Dispatch And Render](Update-DispatchEvent-And-Render.md)

docs/api/XCEngine/Editor/Core/EditorWorkspace/Detach.md

@@ -0,0 +1,45 @@
+# EditorWorkspace::Detach
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method`
+
+**源文件**: `editor/src/Core/EditorWorkspace.h`
+
+## 签名
+
+```cpp
+void Detach(IEditorContext& context);
+```
+
+## 作用
+
+拆除当前工作区，并在 UI 销毁前完成 play session 收口、脏场景保存和 Dock/面板清理。
+
+## 当前实现行为
+
+- 会先调用 `m_playSessionController.Detach(context)`，收口当前 play mode 相关状态。
+- 然后调用:
+
+```cpp
+Commands::SaveDirtySceneWithFallback(context, BuildFallbackScenePath(context));
+```
+
+这意味着工作区退出前会优先尝试保存脏场景，回退路径固定为 `<Project>/Assets/Scenes/Main.xc`。
+- 若存在 `DockLayoutController`，则先 `Detach()` 再释放其对象。
+- 最后依次:
+  - `m_panels.DetachAll()`
+  - `m_panels.Clear()`
+  - 清空 `m_menuBar`
+  - 清空 `m_projectPanel`
+
+## 当前实现边界
+
+- 当前 fallback scene path 是硬编码规则，不读取更细粒度工作区配置。
+- `Detach(...)` 假设自己持有的是当前唯一工作区，不处理多工作区切换。
+
+## 相关文档
+
+- [EditorWorkspace](EditorWorkspace.md)
+- [Attach](Attach.md)
+- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md)

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

@@ -31,6 +31,12 @@
 - `Detach(IEditorContext&)` 会在拆除 UI 前调用 `SaveDirtySceneWithFallback()` 保存脏场景。
 - `Update(float)`、`DispatchEvent(void*)` 和 `Render()` 都只是把行为转发给面板集合与 dock 控制器。
 
+## 公开 API
+
+- [Attach](Attach.md)
+- [Detach](Detach.md)
+- [Update / DispatchEvent / Render](Update-DispatchEvent-And-Render.md)
+
 ## 当前实现边界
 
 - 默认工作区结构目前是硬编码的。

docs/api/XCEngine/Editor/Core/EditorWorkspace/Update-DispatchEvent-And-Render.md

@@ -0,0 +1,62 @@
+# EditorWorkspace::Update / DispatchEvent / Render
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `methods`
+
+**源文件**: `editor/src/Core/EditorWorkspace.h`
+
+## 签名
+
+```cpp
+void Update(float dt);
+void DispatchEvent(void* event);
+void Render();
+```
+
+## 作用
+
+驱动当前工作区的逐帧更新、事件转发与最终 UI 渲染。
+
+## 当前实现行为
+
+### `Update(float dt)`
+
+- 每帧都会先调用 `ResourceManager::Get().UpdateAsyncLoads()`。
+- 如果 `PanelCollection` 当前已经持有有效的 `IEditorContext`，则会先执行:
+
+```cpp
+m_playSessionController.Update(*context, dt);
+```
+
+- 最后调用 `m_panels.UpdateAll(dt)`。
+
+### `DispatchEvent(void* event)`
+
+- 当前只是直接把事件转发给 `m_panels.DispatchEvent(event)`。
+- 事件路由本身由各面板和 action route 继续处理。
+
+### `Render()`
+
+- 如果存在 `MenuBar`，会先绘制 `RenderChrome()`。
+- 如果存在 `DockLayoutController`，会绘制 `RenderDockspace()`。
+- 然后调用 `m_panels.RenderAll(m_menuBar)` 渲染全部面板内容。
+- 最后若存在 `MenuBar`，再绘制 `RenderOverlays()`。
+
+## 设计含义
+
+- `EditorWorkspace` 本身更像工作区级 orchestration 层，而不是具体 UI 逻辑实现层。
+- 它决定的是“先谁后谁”的整体调度顺序:
+  - 资源异步加载更新
+  - play session 更新
+  - 面板更新
+  - 菜单栏 chrome
+  - dockspace
+  - 面板主体
+  - 菜单叠加层
+
+## 相关文档
+
+- [EditorWorkspace](EditorWorkspace.md)
+- [Attach](Attach.md)
+- [Detach](Detach.md)