diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md
new file mode 100644
index 00000000..4ba4b8b3
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md
@@ -0,0 +1,31 @@
+# BuildBeginSceneViewportTransformGizmoLifecycleCommand
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoLifecycleCommand BuildBeginSceneViewportTransformGizmoLifecycleCommand(
+    const SceneViewportInteractionActions& actions);
+```
+
+## 作用
+
+根据点击动作生成 gizmo 拖拽 begin 命令。
+
+## 当前实现行为
+
+- 若 `actions.beginTransformGizmo == false`，返回空命令。
+- 否则返回：
+  - `stage = Begin`
+  - `gizmoKind = actions.hoveredGizmoKind`
+
+## 相关文档
+
+- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
+- [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md)
+- [SceneViewportInteractionActions](../SceneViewportInteractionActions/SceneViewportInteractionActions.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md
new file mode 100644
index 00000000..3f05a104
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md
@@ -0,0 +1,36 @@
+# BuildFrameSceneViewportTransformGizmoLifecycleCommand
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoLifecycleCommand BuildFrameSceneViewportTransformGizmoLifecycleCommand(
+    SceneViewportActiveGizmoKind activeGizmoKind,
+    bool leftMouseDown);
+```
+
+## 作用
+
+根据当前 active gizmo 和鼠标按键状态生成本帧的 update / end 生命周期命令。
+
+## 当前实现行为
+
+- 若 `activeGizmoKind == None`，返回空命令。
+- 否则：
+  - `leftMouseDown == true` 时生成 `Update`
+  - `leftMouseDown == false` 时生成 `End`
+- 返回命令中的 `gizmoKind` 直接取 `activeGizmoKind`。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 update / end 两种映射。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoFrameOptions.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoFrameOptions.md
new file mode 100644
index 00000000..a442e887
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoFrameOptions.md
@@ -0,0 +1,37 @@
+# BuildSceneViewportTransformGizmoFrameOptions
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoFrameOptions BuildSceneViewportTransformGizmoFrameOptions(
+    bool useCenterPivot,
+    bool localSpace,
+    bool usingTransformTool,
+    bool showingMoveGizmo,
+    bool showingRotateGizmo,
+    bool showingScaleGizmo);
+```
+
+## 作用
+
+把 gizmo 刷新所需的离散布尔参数收口成一个 `SceneViewportTransformGizmoFrameOptions`。
+
+## 当前实现行为
+
+- 当前只是把输入参数逐字段拷贝到返回结构。
+- 不做额外推导或一致性校验。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了各布尔字段会被原样拷贝。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoFrameOptions](SceneViewportTransformGizmoFrameOptions.md)
+- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoOverlaySubmission.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoOverlaySubmission.md
new file mode 100644
index 00000000..5f75c1a4
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoOverlaySubmission.md
@@ -0,0 +1,43 @@
+# BuildSceneViewportTransformGizmoOverlaySubmission
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoOverlaySubmission BuildSceneViewportTransformGizmoOverlaySubmission(
+    const SceneViewportTransformGizmoFrameState& frameState,
+    bool showingMoveGizmo,
+    const SceneViewportMoveGizmo& moveGizmo,
+    bool showingRotateGizmo,
+    const SceneViewportRotateGizmo& rotateGizmo,
+    bool showingScaleGizmo,
+    const SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+从本帧 gizmo frame state 和三个 gizmo 对象构建可提交的 overlay submission。
+
+## 当前实现行为
+
+- 调用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 从可见 gizmo 和 frame context 提取 draw-data 输入。
+- 再调用 `BuildSceneViewportTransformGizmoOverlayState(...)` 构造 gizmo overlay state。
+- `activeGizmoKind` 则通过 `GetActiveSceneViewportGizmoKind(...)` 从三个 gizmo 当前状态求得。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了：
+
+- move gizmo 可被打包进 submission
+- `activeGizmoKind` 和 `GizmoActive()` 语义正确
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md)
+- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md
new file mode 100644
index 00000000..811f5cbb
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md
@@ -0,0 +1,37 @@
+# BuildSceneViewportTransformGizmoRefreshRequest
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoRefreshRequest BuildSceneViewportTransformGizmoRefreshRequest(
+    IEditorContext& context,
+    const SceneViewportOverlayData& overlay,
+    const Math::Vector2& viewportSize,
+    const Math::Vector2& mousePosition,
+    const SceneViewportTransformGizmoFrameOptions& options);
+```
+
+## 作用
+
+把当前帧 gizmo 刷新输入收口成 coordinator 可消费的 request。
+
+## 当前实现行为
+
+- `context` 会以指针形式写入 `request.context`。
+- `overlay`、`viewportSize`、`mousePosition` 与 `options` 会被值拷贝到返回结构。
+- 该函数本身不做额外校验；请求是否有效由 `request.IsValid()` 判断。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 context 指针、overlay、viewportSize、mousePosition 和 options 都会被正确拷贝。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md)
+- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md
new file mode 100644
index 00000000..28345d88
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md
@@ -0,0 +1,35 @@
+# CancelSceneViewportTransformGizmoFrame
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+void CancelSceneViewportTransformGizmoFrame(
+    IEditorContext& context,
+    SceneViewportMoveGizmo& moveGizmo,
+    SceneViewportRotateGizmo& rotateGizmo,
+    SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+提供 coordinator 层的统一“取消当前 gizmo 拖拽”入口。
+
+## 当前实现行为
+
+- 当前只是转调 [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md)。
+- 不额外构建 frame state，也不生成 overlay submission。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前会调用该入口，验证 coordinator 层可统一触发取消流程。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/ExecuteSceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/ExecuteSceneViewportTransformGizmoLifecycleCommand.md
new file mode 100644
index 00000000..569adb1a
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/ExecuteSceneViewportTransformGizmoLifecycleCommand.md
@@ -0,0 +1,43 @@
+# ExecuteSceneViewportTransformGizmoLifecycleCommand
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+void ExecuteSceneViewportTransformGizmoLifecycleCommand(
+    const SceneViewportTransformGizmoLifecycleCommand& command,
+    IUndoManager& undoManager,
+    const SceneViewportTransformGizmoFrameState& frameState,
+    SceneViewportMoveGizmo& moveGizmo,
+    SceneViewportRotateGizmo& rotateGizmo,
+    SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+把生命周期命令分发到 move / rotate / scale gizmo 对象。
+
+## 当前实现行为
+
+- 按 `command.gizmoKind` 分发：
+  - `Move` -> `TryBeginDrag / UpdateDrag / EndDrag`
+  - `Rotate` -> `TryBeginDrag / UpdateDrag / EndDrag`
+  - `Scale` -> `TryBeginDrag / UpdateDrag / EndDrag`
+- 各分支会从 `frameState` 中取对应 context。
+- `None` 或未识别值时直接返回。
+
+## 当前边界
+
+- 该函数不负责生成命令，只负责执行。
+- 它也不处理 hover / selection / orientation click，那些在 `SceneViewportInteractionActions` 一侧。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
+- [SceneViewportInteractionActions](../SceneViewportInteractionActions/SceneViewportInteractionActions.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshAndSubmitSceneViewportTransformGizmoFrame.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshAndSubmitSceneViewportTransformGizmoFrame.md
new file mode 100644
index 00000000..a99cc4ce
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshAndSubmitSceneViewportTransformGizmoFrame.md
@@ -0,0 +1,38 @@
+# RefreshAndSubmitSceneViewportTransformGizmoFrame
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoFrameUpdate RefreshAndSubmitSceneViewportTransformGizmoFrame(
+    IViewportHostService& viewportHostService,
+    const SceneViewportTransformGizmoRefreshRequest& request,
+    SceneViewportMoveGizmo& moveGizmo,
+    SceneViewportRotateGizmo& rotateGizmo,
+    SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+刷新一帧 transform gizmo，并立即把 overlay submission 提交给 viewport host service。
+
+## 当前实现行为
+
+- 先调用 [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) 获得 `SceneViewportTransformGizmoFrameUpdate`。
+- 再调用 [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) 把 `update.overlaySubmission` 写回宿主服务。
+- 最终返回同一份 `update`，供调用方继续消费 `frameState`。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了它会同时刷新 move gizmo 上下文，并把 submission 写入 `IViewportHostService`。
+
+## 相关文档
+
+- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
+- [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md)
+- [SceneViewportInteractionFrame](../SceneViewportInteractionFrame/SceneViewportInteractionFrame.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md
new file mode 100644
index 00000000..6dd209b2
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md
@@ -0,0 +1,33 @@
+# RefreshSceneViewportTransformGizmoFrame
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoFrameUpdate RefreshSceneViewportTransformGizmoFrame(
+    const SceneViewportTransformGizmoRefreshRequest& request,
+    SceneViewportMoveGizmo& moveGizmo,
+    SceneViewportRotateGizmo& rotateGizmo,
+    SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+刷新一帧 transform gizmo，并同时生成可提交给宿主服务的 overlay submission。
+
+## 当前实现行为
+
+- 如果 `request.IsValid()` 为 `false`，当前直接返回默认构造的 `SceneViewportTransformGizmoFrameUpdate`。
+- 否则先调用 [RefreshSceneViewportTransformGizmos](../SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md) 得到 `frameState`。
+- 然后调用 [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) 生成 `overlaySubmission`。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoFrameUpdate](SceneViewportTransformGizmoFrameUpdate.md)
+- [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md)
+- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md
new file mode 100644
index 00000000..b94509f7
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md
@@ -0,0 +1,54 @@
+# SceneViewportTransformGizmoCoordinator
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `structs + enum + free functions`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+**描述**: 负责把 gizmo frame state 收口成可提交的 overlay state，并把 Scene View 中的 gizmo begin / update / end 推进收口成统一生命周期命令。
+
+## 概览
+
+这层 helper 位于 `SceneViewPanel` 与 `ViewportHostService` / 各 gizmo 对象之间。
+它当前解决两件事：
+
+- overlay 提交：把本帧 gizmo 状态转成 `SceneViewportTransformGizmoOverlaySubmission`
+- 生命周期推进：把 begin / update / end 统一成 `SceneViewportTransformGizmoLifecycleCommand`
+
+## 公开类型与函数
+
+| 成员 | 说明 |
+|------|------|
+| [SceneViewportTransformGizmoFrameOptions](SceneViewportTransformGizmoFrameOptions.md) | 每帧 gizmo 刷新所需的布尔配置。 |
+| [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md) | 一次 gizmo frame 刷新的完整输入包。 |
+| [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md) | 提交给宿主服务的 overlay submission。 |
+| [SceneViewportTransformGizmoLifecycleStage](SceneViewportTransformGizmoLifecycleStage.md) | gizmo 生命周期阶段枚举。 |
+| [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) | begin / update / end 命令包。 |
+| [SceneViewportTransformGizmoFrameUpdate](SceneViewportTransformGizmoFrameUpdate.md) | 一次 gizmo frame 刷新的完整输出。 |
+| [BuildSceneViewportTransformGizmoFrameOptions](BuildSceneViewportTransformGizmoFrameOptions.md) | 构建每帧 gizmo 布尔配置。 |
+| [BuildSceneViewportTransformGizmoRefreshRequest](BuildSceneViewportTransformGizmoRefreshRequest.md) | 构建 gizmo frame 刷新请求。 |
+| [CancelSceneViewportTransformGizmoFrame](CancelSceneViewportTransformGizmoFrame.md) | 取消当前帧正在进行的 gizmo 拖拽。 |
+| [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) | 刷新 gizmo frame 并生成 overlay submission。 |
+| [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) | 刷新 gizmo frame 并直接提交到 viewport host service。 |
+| [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) | 从 frame state 和 gizmo 对象生成 overlay submission。 |
+| [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) | 把 overlay submission 写回 viewport host service。 |
+| [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md) | 根据交互 action 生成 begin 命令。 |
+| [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md) | 根据 active gizmo 和鼠标状态生成 update / end 命令。 |
+| [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) | 把生命周期命令分发到 move / rotate / scale gizmo。 |
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前覆盖了：
+
+- frame options / refresh request 构造
+- refresh + submit 包装调用
+- begin / update / end 命令生成
+- overlay submission 构造
+- overlay submission 提交到 `IViewportHostService`
+
+## 相关文档
+
+- [Viewport](../Viewport.md)
+- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)
+- [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md
new file mode 100644
index 00000000..938e2265
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md
@@ -0,0 +1,30 @@
+# SceneViewportTransformGizmoFrameOptions
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `useCenterPivot` | `bool` | 是否使用中心 pivot。 |
+| `localSpace` | `bool` | 是否使用局部坐标空间。 |
+| `usingTransformTool` | `bool` | 是否处于联合 `Transform` 工具模式。 |
+| `showingMoveGizmo` | `bool` | 本帧是否显示 move gizmo。 |
+| `showingRotateGizmo` | `bool` | 本帧是否显示 rotate gizmo。 |
+| `showingScaleGizmo` | `bool` | 本帧是否显示 scale gizmo。 |
+
+## 当前语义
+
+- 这是传给 gizmo frame refresh 的轻量布尔配置。
+- 它把工具模式、pivot 模式和空间模式压平成 gizmo 刷新层真正消费的参数。
+- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md) 当前会构建并下发这份配置。
+
+## 相关文档
+
+- [BuildSceneViewportTransformGizmoFrameOptions](BuildSceneViewportTransformGizmoFrameOptions.md)
+- [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md)
+- [SceneViewportToolState](../SceneViewportInteractionFrame/SceneViewportToolState.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md
new file mode 100644
index 00000000..1776b62e
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md
@@ -0,0 +1,25 @@
+# SceneViewportTransformGizmoFrameUpdate
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `frameState` | `SceneViewportTransformGizmoFrameState` | 本帧 gizmo 刷新结果。 |
+| `overlaySubmission` | `SceneViewportTransformGizmoOverlaySubmission` | 可继续提交给宿主服务的 overlay submission。 |
+
+## 当前语义
+
+- 这是 `RefreshSceneViewportTransformGizmoFrame(...)` 与 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` 的统一返回结构。
+- 它同时保留 frame builder 的原始输出和 overlay 提交层的收口结果。
+
+## 相关文档
+
+- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
+- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md)
+- [SceneViewportTransformGizmoFrameState](../SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameState.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md
new file mode 100644
index 00000000..52622767
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md
@@ -0,0 +1,25 @@
+# SceneViewportTransformGizmoLifecycleCommand
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `stage` | `SceneViewportTransformGizmoLifecycleStage` | 本帧生命周期阶段。 |
+| `gizmoKind` | `SceneViewportActiveGizmoKind` | 要执行的 gizmo 类型。 |
+
+## 当前语义
+
+- `HasWork()` 当前要求 `stage != None` 且 `gizmoKind != None`。
+- 这是一份轻量命令对象，真正的 begin / update / end 分发由 `ExecuteSceneViewportTransformGizmoLifecycleCommand(...)` 完成。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [SceneViewportTransformGizmoLifecycleStage](SceneViewportTransformGizmoLifecycleStage.md)
+- [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md
new file mode 100644
index 00000000..1ca49e03
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md
@@ -0,0 +1,21 @@
+# SceneViewportTransformGizmoLifecycleStage
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `enum class`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 枚举值
+
+| 值 | 含义 |
+|------|------|
+| `None` | 无工作。 |
+| `Begin` | 开始拖拽。 |
+| `Update` | 持续更新拖拽。 |
+| `End` | 结束拖拽。 |
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md
new file mode 100644
index 00000000..5eae35a0
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md
@@ -0,0 +1,24 @@
+# SceneViewportTransformGizmoOverlaySubmission
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `overlayState` | `SceneViewportTransformGizmoOverlayState` | 本帧 gizmo overlay state。 |
+| `activeGizmoKind` | `SceneViewportActiveGizmoKind` | 当前 active gizmo 类型。 |
+
+## 当前语义
+
+- `GizmoActive()` 当前仅检查 `activeGizmoKind != None`。
+- 该结构把“本帧要提交给宿主服务的 overlay 数据”和“当前是否已有 gizmo 处于 active 状态”打包在一起。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
+- [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md
new file mode 100644
index 00000000..8c245f72
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md
@@ -0,0 +1,29 @@
+# SceneViewportTransformGizmoRefreshRequest
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `context` | `IEditorContext*` | 当前 editor context。 |
+| `overlay` | `SceneViewportOverlayData` | 当前帧 Scene View overlay 基础数据。 |
+| `viewportSize` | `Math::Vector2` | 当前视口尺寸。 |
+| `mousePosition` | `Math::Vector2` | 当前鼠标位置。 |
+| `options` | `SceneViewportTransformGizmoFrameOptions` | 本帧 gizmo 刷新配置。 |
+
+## 当前语义
+
+- 这是 coordinator 刷新一帧 gizmo 所需的完整输入包。
+- `IsValid()` 当前只要求 `context != nullptr`。
+- 其余字段即使为默认值，也允许下游继续刷新，只是会得到默认 / 空 gizmo frame state。
+
+## 相关文档
+
+- [BuildSceneViewportTransformGizmoRefreshRequest](BuildSceneViewportTransformGizmoRefreshRequest.md)
+- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
+- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md
new file mode 100644
index 00000000..f9083955
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md
@@ -0,0 +1,34 @@
+# SubmitSceneViewportTransformGizmoOverlaySubmission
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+
+## 签名
+
+```cpp
+void SubmitSceneViewportTransformGizmoOverlaySubmission(
+    IViewportHostService& viewportHostService,
+    const SceneViewportTransformGizmoOverlaySubmission& submission);
+```
+
+## 作用
+
+把构造好的 overlay submission 写入宿主服务。
+
+## 当前实现行为
+
+当前实现非常薄，只做一件事：
+
+```cpp
+viewportHostService.SetSceneViewTransformGizmoOverlayState(submission.overlayState);
+```
+
+它不会自行触发 frame data 重建；真正的重建发生在宿主服务下一次 `GetSceneViewEditorOverlayFrameData(...)` 时。
+
+## 相关文档
+
+- [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md)
+- [IViewportHostService Scene View Overlay Contracts](../IViewportHostService/SceneView-Overlay-Contracts.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildMoveGizmoContext.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildMoveGizmoContext.md
new file mode 100644
index 00000000..650f2b60
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildMoveGizmoContext.md
@@ -0,0 +1,36 @@
+# BuildMoveGizmoContext
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportMoveGizmoContext BuildMoveGizmoContext(
+    const SceneViewportSelectionGizmoState& selectionState,
+    const SceneViewportOverlayData& overlay,
+    const Math::Vector2& viewportSize,
+    const Math::Vector2& mousePosition,
+    bool localSpace);
+```
+
+## 作用
+
+根据当前选择状态和 Scene View overlay 信息构建 move gizmo 更新上下文。
+
+## 当前实现行为
+
+- 会写入 `overlay`、`viewportSize` 和 `mousePosition`。
+- `selectedObject` 取 `selectionState.primaryObject`。
+- `selectedObjects` 会完整带入，供 move gizmo 处理多对象平移。
+- `pivotWorldPosition` 直接复用 `selectionState.pivotWorldPosition`。
+- `axisOrientation` 在 local-space 模式下取主对象稳定世界旋转，否则取单位四元数。
+
+## 相关文档
+
+- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
+- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildRotateGizmoContext.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildRotateGizmoContext.md
new file mode 100644
index 00000000..7f914e35
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildRotateGizmoContext.md
@@ -0,0 +1,39 @@
+# BuildRotateGizmoContext
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportRotateGizmoContext BuildRotateGizmoContext(
+    const SceneViewportSelectionGizmoState& selectionState,
+    const SceneViewportOverlayData& overlay,
+    const Math::Vector2& viewportSize,
+    const Math::Vector2& mousePosition,
+    bool localSpace,
+    bool rotateAroundSharedPivot);
+```
+
+## 作用
+
+根据当前选择状态和 Scene View overlay 信息构建 rotate gizmo 更新上下文。
+
+## 当前实现行为
+
+- 会写入 `overlay`、`viewportSize` 和 `mousePosition`。
+- `selectedObject` 取主对象，`selectedObjects` 也会完整带入。
+- `pivotWorldPosition` 取当前选择快照的 pivot。
+- `axisOrientation` 在 local-space 模式下取主对象稳定世界旋转，否则取单位四元数。
+- 额外写入：
+  - `localSpace`
+  - `rotateAroundSharedPivot`
+
+## 相关文档
+
+- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
+- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildScaleGizmoContext.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildScaleGizmoContext.md
new file mode 100644
index 00000000..6a1d2256
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildScaleGizmoContext.md
@@ -0,0 +1,36 @@
+# BuildScaleGizmoContext
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportScaleGizmoContext BuildScaleGizmoContext(
+    const SceneViewportSelectionGizmoState& selectionState,
+    const SceneViewportOverlayData& overlay,
+    const Math::Vector2& viewportSize,
+    const Math::Vector2& mousePosition,
+    bool localSpace);
+```
+
+## 作用
+
+根据当前选择状态和 Scene View overlay 信息构建 scale gizmo 更新上下文。
+
+## 当前实现行为
+
+- 会写入 `overlay`、`viewportSize` 和 `mousePosition`。
+- `selectedObject` 仅绑定 `selectionState.primaryObject`。
+- `pivotWorldPosition` 取当前选择快照的 pivot。
+- `axisOrientation` 在 local-space 模式下取主对象稳定世界旋转，否则取单位四元数。
+- 当前这里不会填充 `uniformOnly`，该标志会由 [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 后续按工具模式写入。
+
+## 相关文档
+
+- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
+- [SceneViewportScaleGizmo](../SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md
new file mode 100644
index 00000000..8ea4f68c
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md
@@ -0,0 +1,36 @@
+# BuildSceneViewportSelectionGizmoState
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportSelectionGizmoState BuildSceneViewportSelectionGizmoState(
+    IEditorContext& context,
+    bool useCenterPivot);
+```
+
+## 作用
+
+从 editor 选择状态构建 transform gizmo 每帧需要的选择、pivot 和主对象朝向快照。
+
+## 当前实现行为
+
+- 从 `SelectionManager` 读取主选中实体与全选列表。
+- 通过 `SceneManager::GetEntity(...)` 过滤掉空实体 id 或无法解析的对象。
+- 如果 `primaryObject` 缺失但 `selectedObjects` 非空，当前会回退为最后一个可解析对象。
+- 如果有 `primaryObject` 但 `selectedObjects` 为空，当前会把它补进多选列表。
+- 若存在主对象，会计算并写入 `primaryWorldRotation`。
+- 若没有任何选中对象，直接返回默认状态。
+- `useCenterPivot == true` 时，会对所有选中对象的“中心世界位置”求平均。
+- `useCenterPivot == false` 时，pivot 取主对象 transform 位置。
+
+## 相关文档
+
+- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
+- [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md)
+- [ComputeStableWorldRotation](ComputeStableWorldRotation.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md
new file mode 100644
index 00000000..c27f8669
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md
@@ -0,0 +1,32 @@
+# CancelSceneViewportTransformGizmoDrags
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+void CancelSceneViewportTransformGizmoDrags(
+    IEditorContext& context,
+    SceneViewportMoveGizmo& moveGizmo,
+    SceneViewportRotateGizmo& rotateGizmo,
+    SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+统一取消当前正在进行的 move / rotate / scale gizmo 拖拽。
+
+## 当前实现行为
+
+- 会分别检查三个 gizmo 的 `IsActive()`。
+- 对处于 active 状态的 gizmo，调用 `CancelDrag(&context.GetUndoManager())`。
+- 对未激活的 gizmo 不做处理。
+
+## 相关文档
+
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
+- [CancelSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/ComputeStableWorldRotation.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/ComputeStableWorldRotation.md
new file mode 100644
index 00000000..6c513a0a
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/ComputeStableWorldRotation.md
@@ -0,0 +1,30 @@
+# ComputeStableWorldRotation
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+Math::Quaternion ComputeStableWorldRotation(const Components::GameObject* gameObject);
+```
+
+## 作用
+
+从对象及其父层级的 local rotation 计算一个稳定的世界旋转，供 gizmo 轴向使用。
+
+## 当前实现行为
+
+- `gameObject == nullptr` 或缺少 transform 时返回 `Math::Quaternion::Identity()`。
+- 当前会从对象自身 local rotation 开始，沿父层级逐级左乘父 local rotation。
+- 返回值会调用 `Normalized()`，避免累计后出现非规范四元数。
+
+## 相关文档
+
+- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
+- [BuildMoveGizmoContext](BuildMoveGizmoContext.md)
+- [BuildRotateGizmoContext](BuildRotateGizmoContext.md)
+- [BuildScaleGizmoContext](BuildScaleGizmoContext.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md
new file mode 100644
index 00000000..2ab68c3e
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md
@@ -0,0 +1,35 @@
+# GetActiveSceneViewportGizmoKind
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportActiveGizmoKind GetActiveSceneViewportGizmoKind(
+    const SceneViewportMoveGizmo& moveGizmo,
+    const SceneViewportRotateGizmo& rotateGizmo,
+    const SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+从三个 gizmo 当前 `IsActive()` 状态推导出本帧的 active gizmo 大类。
+
+## 当前实现行为
+
+- 按固定优先级检查：
+  - `moveGizmo.IsActive()`
+  - `rotateGizmo.IsActive()`
+  - `scaleGizmo.IsActive()`
+- 三者都不 active 时返回 `SceneViewportActiveGizmoKind::None`。
+- 如果出现多个 gizmo 同时 active 的异常情况，当前会按上面的检查顺序返回第一个命中的类型。
+
+## 相关文档
+
+- [SceneViewportActiveGizmoKind](SceneViewportActiveGizmoKind.md)
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
+- [BuildSceneViewportTransformGizmoOverlaySubmission](../SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoOverlaySubmission.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md
new file mode 100644
index 00000000..4827f324
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md
@@ -0,0 +1,28 @@
+# GetGameObjectCenterWorldPosition
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+Math::Vector3 GetGameObjectCenterWorldPosition(const Components::GameObject* gameObject);
+```
+
+## 作用
+
+计算对象的“中心世界位置”，供 center-pivot 模式聚合多选 pivot。
+
+## 当前实现行为
+
+- `gameObject == nullptr` 或缺少 transform 时返回 `Math::Vector3::Zero()`。
+- 若对象存在有效 `MeshFilterComponent`，且 mesh 非空并 `IsValid()`，则返回 `mesh->GetBounds().center` 经 transform 后的世界位置。
+- 否则回退到对象 transform 位置。
+
+## 相关文档
+
+- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
+- [GetGameObjectPivotWorldPosition](GetGameObjectPivotWorldPosition.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md
new file mode 100644
index 00000000..3d0d81e9
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md
@@ -0,0 +1,27 @@
+# GetGameObjectPivotWorldPosition
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+Math::Vector3 GetGameObjectPivotWorldPosition(const Components::GameObject* gameObject);
+```
+
+## 作用
+
+读取对象 transform 的世界位置，作为非 center-pivot 模式下的 gizmo pivot。
+
+## 当前实现行为
+
+- `gameObject == nullptr` 或缺少 transform 时返回 `Math::Vector3::Zero()`。
+- 其余情况下直接返回 `gameObject->GetTransform()->GetPosition()`。
+
+## 相关文档
+
+- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
+- [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md
new file mode 100644
index 00000000..dfc1b0f2
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md
@@ -0,0 +1,50 @@
+# RefreshSceneViewportTransformGizmos
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoFrameState RefreshSceneViewportTransformGizmos(
+    IEditorContext& context,
+    const SceneViewportOverlayData& overlay,
+    const Math::Vector2& viewportSize,
+    const Math::Vector2& mousePosition,
+    bool useCenterPivot,
+    bool localSpace,
+    bool usingTransformTool,
+    bool showingMoveGizmo,
+    SceneViewportMoveGizmo& moveGizmo,
+    bool showingRotateGizmo,
+    SceneViewportRotateGizmo& rotateGizmo,
+    bool showingScaleGizmo,
+    SceneViewportScaleGizmo& scaleGizmo);
+```
+
+## 作用
+
+完成一帧 transform gizmo 刷新，返回本帧 gizmo frame state。
+
+## 当前实现行为
+
+1. 先通过 [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 生成选择快照。
+2. 按显示开关构建 move / rotate / scale 三类 context。
+3. 如果某个 gizmo 正在拖拽，但当前对象已失效、主选中对象已切换，或该 gizmo 本帧被隐藏，则会调用 `CancelDrag(...)`。
+4. 对 scale gizmo，当前会把 `state.scaleContext.uniformOnly` 设为 `usingTransformTool`。
+5. 通过 [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md) 求出当前 active gizmo 类型。
+6. 更新所有可见 gizmo；如果已有别的 gizmo active，则把非活动 gizmo 的 `mousePosition` 改成 `(-1, -1)` 再调用 `Update(...)`，显式屏蔽 hover 竞争。
+
+## 当前使用位置
+
+- [RefreshSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md) 会直接包装这一步，并继续构建 overlay submission。
+- `SceneViewPanel.cpp` 当前通过 coordinator 间接使用它。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md)
+- [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md)
+- [RefreshSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md
new file mode 100644
index 00000000..a814f70b
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md
@@ -0,0 +1,28 @@
+# SceneViewportActiveGizmoKind
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `enum class`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 枚举值
+
+| 值 | 说明 |
+|----|------|
+| `None` | 当前没有 gizmo 处于 active 拖拽态。 |
+| `Move` | 当前由 move gizmo 持有拖拽。 |
+| `Rotate` | 当前由 rotate gizmo 持有拖拽。 |
+| `Scale` | 当前由 scale gizmo 持有拖拽。 |
+
+## 当前语义
+
+- 这是 Scene View transform gizmo 系统内部用来表达“谁正在持有交互”的统一枚举。
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 会用它屏蔽非活动 gizmo 的 hover 竞争。
+- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 也会用它驱动 begin / update / end 生命周期命令。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder.md)
+- [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md)
+- [SceneViewportTransformGizmoLifecycleCommand](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md
new file mode 100644
index 00000000..4d52be4c
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md
@@ -0,0 +1,30 @@
+# SceneViewportSelectionGizmoState
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `primaryObject` | `Components::GameObject*` | 当前主选中对象。 |
+| `selectedObjects` | `std::vector<Components::GameObject*>` | 当前可解析的选中对象集合。 |
+| `pivotWorldPosition` | `Math::Vector3` | 本帧 gizmo 应使用的世界 pivot。 |
+| `primaryWorldRotation` | `Math::Quaternion` | 主对象稳定世界旋转。 |
+
+## 当前语义
+
+- 这是 [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 的输出结构。
+- 当前实现会尽量保持 `primaryObject` 与 `selectedObjects` 自洽：
+  - 有多选但主对象缺失时，会回退到最后一个可解析对象。
+  - 只有主对象时，会把它补进 `selectedObjects`。
+- `pivotWorldPosition` 会按当前是否使用 center pivot 决定来源。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder.md)
+- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
+- [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameBuilder.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameBuilder.md
new file mode 100644
index 00000000..f4dd3aef
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameBuilder.md
@@ -0,0 +1,61 @@
+# SceneViewportTransformGizmoFrameBuilder
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `utility-header`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+**描述**: 统一组装 Scene View 每帧的 transform gizmo 选择状态、pivot、局部/全局朝向和三类 gizmo context，并负责在选择变化时取消失效拖拽。
+
+## 概述
+
+`SceneViewportTransformGizmoFrameBuilder.h` 处在当前 Scene View gizmo 交互链路的中间层。
+它不直接绘制 gizmo，也不直接处理 ImGui 输入，而是把“本帧该拿什么上下文去更新 move / rotate / scale gizmo”这件事集中到一个头文件里。
+
+它主要解决四类问题：
+
+1. 从 `SelectionManager + SceneManager` 还原当前选中对象集合。
+2. 计算本帧 gizmo 应使用的 pivot 与主对象世界朝向。
+3. 组装 move / rotate / scale 各自的 context。
+4. 在 gizmo 被隐藏、选择切换或实体失效时，及时取消旧拖拽。
+
+## 公开类型与函数
+
+| 成员 | 说明 |
+|------|------|
+| [SceneViewportActiveGizmoKind](SceneViewportActiveGizmoKind.md) | 当前处于 active 拖拽态的 gizmo 大类。 |
+| [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md) | 当前选择、pivot 和主对象朝向的聚合快照。 |
+| [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md) | 每帧 gizmo 刷新后的完整输出。 |
+| [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md) | 从三个 gizmo 当前状态推断 active gizmo 类型。 |
+| [ComputeStableWorldRotation](ComputeStableWorldRotation.md) | 计算主对象稳定世界旋转。 |
+| [GetGameObjectPivotWorldPosition](GetGameObjectPivotWorldPosition.md) | 读取对象 pivot 世界位置。 |
+| [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md) | 读取对象中心世界位置，优先使用 mesh bounds center。 |
+| [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) | 构建本帧选择与 pivot 快照。 |
+| [BuildMoveGizmoContext](BuildMoveGizmoContext.md) | 构建 move gizmo 本帧上下文。 |
+| [BuildRotateGizmoContext](BuildRotateGizmoContext.md) | 构建 rotate gizmo 本帧上下文。 |
+| [BuildScaleGizmoContext](BuildScaleGizmoContext.md) | 构建 scale gizmo 本帧上下文。 |
+| [CancelSceneViewportTransformGizmoDrags](CancelSceneViewportTransformGizmoDrags.md) | 统一取消正在进行的 gizmo 拖拽。 |
+| [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) | 完成一帧 gizmo context 刷新、拖拽校验和 gizmo 更新。 |
+
+## 当前实现边界
+
+- 这是 header-only helper，不持有持久状态。
+- 它解决的是“每帧上下文装配”，不是 gizmo overlay 提交或生命周期命令分发。
+- gizmo overlay state 的收口由 [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 负责。
+- 当前多选中心 pivot 只按对象中心平均，不做包围盒并集或加权计算。
+
+## 当前使用位置
+
+- `SceneViewPanel.cpp` 会按本帧工具状态、pivot 模式和坐标空间调用这组 helper。
+- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 会继续消费这里返回的 frame state，并收口成 overlay submission。
+- [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)、[SceneViewportRotateGizmo](../SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)、[SceneViewportScaleGizmo](../SceneViewportScaleGizmo/SceneViewportScaleGizmo.md) 都依赖这里生成的 context。
+
+## 相关文档
+
+- [当前模块](../Viewport.md)
+- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md)
+- [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
+- [SceneViewportRotateGizmo](../SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
+- [SceneViewportScaleGizmo](../SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)
+- [SceneView Interaction And Gizmo Model](../../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md)
diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameState.md
new file mode 100644
index 00000000..b1f90562
--- /dev/null
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameState.md
@@ -0,0 +1,30 @@
+# SceneViewportTransformGizmoFrameState
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `overlay` | `SceneViewportOverlayData` | 当前帧 Scene View 相机 / overlay 基础数据。 |
+| `selectionState` | `SceneViewportSelectionGizmoState` | 当前帧选中对象与 pivot 快照。 |
+| `moveContext` | `SceneViewportMoveGizmoContext` | move gizmo 本帧上下文。 |
+| `rotateContext` | `SceneViewportRotateGizmoContext` | rotate gizmo 本帧上下文。 |
+| `scaleContext` | `SceneViewportScaleGizmoContext` | scale gizmo 本帧上下文。 |
+| `activeGizmoKind` | `SceneViewportActiveGizmoKind` | 当前实际 active 的 gizmo 大类。 |
+
+## 当前语义
+
+- 这是 [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 的完整输出。
+- 它既保留三类 gizmo 的上下文，也保留本帧 active gizmo 判断结果，供 coordinator 后续继续处理。
+- 该结构本身不持有生命周期状态，只表达当前帧刷新后的快照。
+
+## 相关文档
+
+- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder.md)
+- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
+- [SceneViewportTransformGizmoFrameUpdate](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md)