docs: add scene viewport overlay helper docs

docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md

@@ -0,0 +1,70 @@
+# SceneViewportEditorOverlayData
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `enum classes + structs`
+
+**源文件**: `editor/src/Viewport/SceneViewportEditorOverlayData.h`
+
+**描述**: 定义 Scene View editor overlay 的深度模式、sprite 类型、屏幕三角形、命中记录以及按帧缓存的聚合数据。
+
+## 概述
+
+这个头文件解决的是“怎么把 Scene View 里需要额外显示的 editor overlay 内容表达出来”。
+
+它和 [IViewportHostService](../IViewportHostService/IViewportHostService.md) 里的 `SceneViewportOverlayData` 不同：
+
+- `SceneViewportOverlayData` 描述的是相机姿态与投影视角。
+- `SceneViewportOverlayFrameData` 描述的是这一帧到底要画哪些线、哪些 sprite、哪些 screen triangle，以及哪些命中记录。
+
+可以把它理解成 Scene View overlay builder、overlay hit-test 与 overlay pass 之间共享的数据协议。
+
+## 公开类型
+
+| 成员 | 说明 |
+|------|------|
+| `SceneViewportOverlayDepthMode` | 当前只有 `DepthTested` 与 `AlwaysOnTop` 两类深度模式。 |
+| `SceneViewportOverlaySpriteTextureKind` | 当前只区分 `Camera` 与 `Light` 两类 sprite。 |
+| `SceneViewportOverlayHandleKind` | overlay 命中记录的语义种类，例如 scene icon、move axis、rotate axis 等。 |
+| `SceneViewportOverlayHandleShape` | 当前 handle 的几何命中形状。 |
+| `SceneViewportOverlayLinePrimitive` | 一条世界空间线段。 |
+| `SceneViewportOverlaySpritePrimitive` | 一个世界空间图标 sprite。 |
+| `SceneViewportOverlayScreenTrianglePrimitive` | 一个屏幕空间三角形 primitive。 |
+| `SceneViewportOverlayHandleRecord` | 一条统一的命中记录。 |
+| `SceneViewportOverlayHandleHitResult` | 一次 overlay handle hit-test 的结果。 |
+| `SceneViewportOverlayFrameData` | 一帧 overlay 的聚合结果。 |
+
+## 当前实现行为
+
+- `worldLines` 使用世界空间起点/终点，真正投影与渲染在后续 pass 里完成。
+- `worldSprites` 使用世界坐标、像素尺寸和 `textureKind`，而不是直接持有 `ImTextureID`。
+- `screenTriangles` 当前主要承载 transform gizmo 的屏幕空间几何。
+- `handleRecords` 当前统一覆盖 scene icon 与 transform gizmo 的命中记录。
+- `SceneViewportOverlayFrameData::HasOverlayPrimitives()` 会同时检查 `worldLines`、`worldSprites` 与 `screenTriangles`。
+- `HasWorldOverlay()` 当前直接复用 `HasOverlayPrimitives()`。
+
+## 设计说明
+
+这里同时保留了世界空间 primitive、屏幕空间三角形和统一 handle 记录，原因很明确：
+
+- GPU pass 需要消费世界线段、sprite 和屏幕三角形。
+- 命中系统需要消费统一的 `handleRecords`。
+- builder / provider / hit-test / pass 可以围绕同一份 frame data 协作，而不是各自维护一套格式。
+
+## 生命周期与线程语义
+
+- 这些结构体都是纯帧数据，没有独立资源释放逻辑。
+- 当前由 [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) 构建，再交给 [SceneViewportOverlayHitTester](../SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md) 和 [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) 使用。
+
+## 当前限制
+
+- 当前 sprite 类型只有相机和灯光两种。
+- 当前深度模式是离散的枚举，不支持更复杂的深度偏移或分层策略。
+- `FrameData` 不包含 ImGui HUD 层；HUD 仍由 [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) 独立负责。
+
+## 相关文档
+
+- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+- [SceneViewportOverlayHitTester](../SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md)
+- [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md)
+- [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Build.md

@@ -0,0 +1,97 @@
+# SceneViewportOverlayBuilder::Build
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportOverlayFrameData Build(
+    IEditorContext& context,
+    const SceneViewportOverlayData& overlay,
+    uint32_t viewportWidth,
+    uint32_t viewportHeight,
+    const std::vector<uint64_t>& selectedObjectIds,
+    const SceneViewportTransformGizmoOverlayState* transformGizmoOverlayState = nullptr) const;
+```
+
+## 作用
+
+基于当前 builder 持有的 provider registry，构建一帧 Scene View editor overlay 数据。
+
+## 当前实现行为
+
+### 1. 先初始化返回值
+
+函数一开始会创建：
+
+```cpp
+SceneViewportOverlayFrameData frameData = {};
+frameData.overlay = overlay;
+```
+
+因此即使后续走早退路径，返回值里也会保留传入的 `overlay` 快照。
+
+### 2. 无效输入时直接返回空 frame
+
+当前会在以下任一条件成立时直接返回：
+
+- `overlay.valid == false`
+- `viewportWidth == 0`
+- `viewportHeight == 0`
+- `context.GetSceneManager().GetScene() == nullptr`
+
+这里不会抛异常，也不会尝试构建部分 overlay。
+
+### 3. 组装 build context 并交给 provider registry
+
+当前实现会构造一份：
+
+```cpp
+SceneViewportOverlayBuildContext{
+    &context,
+    scene,
+    &overlay,
+    viewportWidth,
+    viewportHeight,
+    &selectedObjectIds,
+    transformGizmoOverlayState
+}
+```
+
+然后调用：
+
+```cpp
+m_providerRegistry.AppendOverlay(buildContext, frameData);
+```
+
+这意味着：
+
+- `Build(...)` 自己不直接生成 camera / light / gizmo 图元
+- 具体追加哪些 `worldSprites`、`worldLines`、`screenTriangles`、`handleRecords` 由当前 registry 中的 provider 决定
+- 输出顺序当前跟随 provider 的注册顺序
+
+## 默认 builder 的输出来源
+
+默认构造的 builder 当前使用 [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)，所以默认 `Build(...)` 的 editor overlay 主要来自：
+
+- [CreateSceneViewportCameraOverlayProvider](../SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md)
+- [CreateSceneViewportLightOverlayProvider](../SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md)
+- [CreateSceneViewportTransformGizmoOverlayProvider](../SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md)
+
+## 当前实现边界
+
+- 该方法不缓存构建结果；每次调用都会重新走一遍 registry 分发。
+- 该方法只构建数据，不负责 Scene View overlay pass 或 ImGui HUD 绘制。
+- 若调用方传入自定义 registry，返回内容会随自定义 provider 集合变化。
+
+## 相关文档
+
+- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder.md)
+- [Constructor](Constructor.md)
+- [GetProviderRegistry](GetProviderRegistry.md)
+- [SceneViewportOverlayBuildContext](../SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md)
+- [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Constructor.md

@@ -0,0 +1,64 @@
+# SceneViewportOverlayBuilder::SceneViewportOverlayBuilder
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `constructor`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportOverlayBuilder();
+explicit SceneViewportOverlayBuilder(SceneViewportOverlayProviderRegistry providerRegistry);
+```
+
+## 作用
+
+创建一个持有 provider registry 的 Scene View 世界 overlay builder。
+
+## 当前实现行为
+
+### 默认构造
+
+默认构造函数当前等价于：
+
+```cpp
+SceneViewportOverlayBuilder::SceneViewportOverlayBuilder()
+    : m_providerRegistry(BuildDefaultSceneViewportOverlayProviderRegistry()) {
+}
+```
+
+因此默认 builder 会直接接管一份包含以下 provider 的 registry：
+
+1. camera overlay provider
+2. light overlay provider
+3. transform-gizmo overlay provider
+
+### 传入自定义 registry
+
+第二个重载当前等价于：
+
+```cpp
+SceneViewportOverlayBuilder::SceneViewportOverlayBuilder(
+    SceneViewportOverlayProviderRegistry providerRegistry)
+    : m_providerRegistry(std::move(providerRegistry)) {
+}
+```
+
+这说明：
+
+- builder 会按值接管调用方提供的 registry
+- registry 内部 provider 的所有权也会一起转移
+- 后续 [Build](Build.md) 只会使用这份 registry
+
+## 当前实现边界
+
+- 构造阶段不访问 scene、selection 或 GPU 资源。
+- 实际 overlay 内容仍取决于后续 `Build(...)` 时传入的 context 与 gizmo state。
+
+## 相关文档
+
+- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder.md)
+- [Build](Build.md)
+- [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/GetProviderRegistry.md

@@ -0,0 +1,51 @@
+# SceneViewportOverlayBuilder::GetProviderRegistry
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayBuilder.h`
+
+## 签名
+
+```cpp
+const SceneViewportOverlayProviderRegistry& GetProviderRegistry() const;
+SceneViewportOverlayProviderRegistry& GetProviderRegistry();
+```
+
+## 作用
+
+访问 builder 当前持有的 provider registry。
+
+## 当前实现行为
+
+两个重载当前都只是直接返回成员引用：
+
+```cpp
+return m_providerRegistry;
+```
+
+因此：
+
+- `const` 重载适合读取当前 registry 配置
+- 可变重载允许调用方继续向 registry 注册或调整 provider
+
+对可变重载返回值的修改，会影响后续 [Build](Build.md) 使用的 provider 集合。
+
+## 所有权与生命周期
+
+- 返回的是对内部成员的引用，不是拷贝。
+- registry 及其内部 provider 的所有权仍然属于 `SceneViewportOverlayBuilder`。
+- 只要 builder 存活，这个引用就保持有效；builder 销毁后引用随之失效。
+
+## 当前实现边界
+
+- 该方法本身不触发 overlay 重建。
+- 该方法不做空值检查；builder 始终持有一份 registry 成员。
+
+## 相关文档
+
+- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder.md)
+- [Constructor](Constructor.md)
+- [Build](Build.md)
+- [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md

@@ -0,0 +1,76 @@
+# SceneViewportOverlayBuilder
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `class`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayBuilder.h`
+
+**描述**: 持有一个 [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md)，把 Scene View editor overlay 的 build context 分发给各个 provider，并汇总成一帧 [SceneViewportOverlayFrameData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)。
+
+## 概览
+
+`SceneViewportOverlayBuilder` 当前已经不是“无状态 helper + static Build(...)”。
+
+按 `SceneViewportOverlayBuilder.h/.cpp` 的当前实现，它内部直接持有：
+
+```cpp
+SceneViewportOverlayProviderRegistry m_providerRegistry = {};
+```
+
+而 [Build](Build.md) 做的事情也不再是自己硬编码相机 / 灯光 / gizmo overlay 细节，而是：
+
+1. 检查 `overlay`、视口尺寸和当前 scene 是否有效。
+2. 组装一份 [SceneViewportOverlayBuildContext](../SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md)。
+3. 调用 `m_providerRegistry.AppendOverlay(...)`，把 provider 输出追加进同一份 `SceneViewportOverlayFrameData`。
+
+因此，“这一帧 Scene View 里会出现哪些 scene icon、world line、screen triangle、handle record”，当前取决于 builder 持有的 provider registry，而不是这个类本身写死的图元集合。
+
+## 默认 registry 语义
+
+[Constructor](Constructor.md) 的默认路径当前会调用 [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)，因此默认 builder 会聚合：
+
+- camera overlay provider
+- light overlay provider
+- transform gizmo overlay provider
+
+## 生命周期与所有权
+
+- builder 按值持有 `SceneViewportOverlayProviderRegistry`
+- registry 再按 `std::unique_ptr` 持有各个 provider
+- builder 本身不持有 GPU 资源，也不缓存 frame data
+- Scene View overlay 的缓存当前由 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 负责，而不是由 builder 负责
+
+这意味着它更像“provider 聚合器”，而不是“Scene View overlay 缓存器”。
+
+## 当前公开成员
+
+| 成员 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 创建默认 builder，或接管一份自定义 provider registry。 |
+| [Build](Build.md) | 基于当前 registry 构建一帧 editor overlay 数据。 |
+| [GetProviderRegistry](GetProviderRegistry.md) | 访问 builder 当前持有的 provider registry。 |
+
+## 与测试的对应关系
+
+`tests/Editor/test_scene_viewport_overlay_providers.cpp` 当前覆盖了：
+
+- registry 会按注册顺序追加 provider 输出。
+- 默认 builder 会聚合 camera / light provider 的输出。
+- 传入 `SceneViewportTransformGizmoOverlayState` 时，builder 会把 gizmo provider 产出的 `screenTriangles / handleRecords` 一并带上。
+
+## 当前实现边界
+
+- builder 只负责组装 `SceneViewportOverlayBuildContext` 并分发给 provider，不负责 GPU pass 或 ImGui HUD 绘制。
+- provider 的执行顺序当前就是 registry 的注册顺序。
+- 默认 registry 当前会注册 camera / light / transform gizmo 三类 provider；更多 overlay 需要通过 provider 扩展进入这条链路。
+
+## 相关文档
+
+- [Constructor](Constructor.md)
+- [Build](Build.md)
+- [GetProviderRegistry](GetProviderRegistry.md)
+- [SceneViewportOverlayProviders](../SceneViewportOverlayProviders/SceneViewportOverlayProviders.md)
+- [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md)
+- [SceneViewportOverlayBuildContext](../SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHandleBuilder/BuildSceneViewportTransformGizmoHandleBuildInputs.md

@@ -0,0 +1,47 @@
+# BuildSceneViewportTransformGizmoHandleBuildInputs
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function overloads`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayHandleBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportTransformGizmoHandleBuildInputs BuildSceneViewportTransformGizmoHandleBuildInputs(
+    bool showingMoveGizmo,
+    const SceneViewportMoveGizmo& moveGizmo,
+    const SceneViewportMoveGizmoContext& moveGizmoContext,
+    bool showingRotateGizmo,
+    const SceneViewportRotateGizmo& rotateGizmo,
+    const SceneViewportRotateGizmoContext& rotateGizmoContext,
+    bool showingScaleGizmo,
+    const SceneViewportScaleGizmo& scaleGizmo,
+    const SceneViewportScaleGizmoContext& scaleGizmoContext);
+
+SceneViewportTransformGizmoHandleBuildInputs BuildSceneViewportTransformGizmoHandleBuildInputs(
+    const SceneViewportTransformGizmoOverlayState& state);
+```
+
+## 作用
+
+构建 `SceneViewportTransformGizmoHandleBuildInputs`。
+
+## 当前实现行为
+
+- 第一组 overload 从 gizmo 对象 + context 出发：
+  - 只在 `showing*Gizmo == true` 且 `selectedObject != nullptr` 时带入对应 draw data 与实体 id。
+- 第二组 overload 从 `SceneViewportTransformGizmoOverlayState` 反向恢复输入包：
+  - 只在 `has*Gizmo == true` 时带入对应数据。
+
+## 当前使用位置
+
+- `SceneViewportTransformGizmoCoordinator.cpp` 当前使用第一组 overload。
+- `SceneViewportOverlayProviders.cpp` 当前在消费 gizmo overlay state 时使用第二组 overload。
+
+## 相关文档
+
+- [SceneViewportOverlayHandleBuilder](SceneViewportOverlayHandleBuilder.md)
+- [SceneViewportTransformGizmoHandleBuildInputs](SceneViewportTransformGizmoHandleBuildInputs.md)
+- [SceneViewportTransformGizmoOverlayState](SceneViewportTransformGizmoOverlayState.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHandleBuilder/BuildSceneViewportTransformGizmoOverlayFrameData.md

@@ -0,0 +1,33 @@
+# BuildSceneViewportTransformGizmoOverlayFrameData
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayHandleBuilder.h`
+
+## 签名
+
+```cpp
+SceneViewportOverlayFrameData BuildSceneViewportTransformGizmoOverlayFrameData(
+    const SceneViewportOverlayData& overlay,
+    const SceneViewportTransformGizmoHandleBuildInputs& inputs);
+```
+
+## 作用
+
+把 gizmo overlay 输入转换成 canonical `SceneViewportOverlayFrameData`。
+
+## 当前实现行为
+
+- 先把 `overlay` 写入返回值的 `frameData.overlay`。
+- 再调用内部 helper：
+  - `AppendTransformGizmoScreenTriangles(...)`
+  - `AppendTransformGizmoHandleRecords(...)`
+- 输出结果会同时包含用于绘制的 `screenTriangles` 和用于命中的 `handleRecords`。
+
+## 相关文档
+
+- [SceneViewportOverlayHandleBuilder](SceneViewportOverlayHandleBuilder.md)
+- [SceneViewportTransformGizmoHandleBuildInputs](SceneViewportTransformGizmoHandleBuildInputs.md)
+- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHandleBuilder/SceneViewportTransformGizmoHandleBuildInputs.md

@@ -0,0 +1,29 @@
+# SceneViewportTransformGizmoHandleBuildInputs
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayHandleBuilder.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `moveGizmo` | `const SceneViewportMoveGizmoDrawData*` | move gizmo draw data。 |
+| `moveEntityId` | `uint64_t` | move gizmo 对应实体 id。 |
+| `rotateGizmo` | `const SceneViewportRotateGizmoDrawData*` | rotate gizmo draw data。 |
+| `rotateEntityId` | `uint64_t` | rotate gizmo 对应实体 id。 |
+| `scaleGizmo` | `const SceneViewportScaleGizmoDrawData*` | scale gizmo draw data。 |
+| `scaleEntityId` | `uint64_t` | scale gizmo 对应实体 id。 |
+
+## 当前语义
+
+- 这是 overlay 构建阶段的中间输入包，不是长期缓存对象。
+- 它允许调用方按可见 gizmo 选择性带入 move / rotate / scale 三组 draw data。
+
+## 相关文档
+
+- [SceneViewportOverlayHandleBuilder](SceneViewportOverlayHandleBuilder.md)
+- [SceneViewportTransformGizmoOverlayState](SceneViewportTransformGizmoOverlayState.md)
+- [BuildSceneViewportTransformGizmoHandleBuildInputs](BuildSceneViewportTransformGizmoHandleBuildInputs.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHandleBuilder/SceneViewportTransformGizmoOverlayState.md

@@ -0,0 +1,35 @@
+# SceneViewportTransformGizmoOverlayState
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayHandleBuilder.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `hasMoveGizmo` | `bool` | 当前是否存在 move gizmo overlay。 |
+| `moveGizmo` | `SceneViewportMoveGizmoDrawData` | move gizmo draw data 快照。 |
+| `moveEntityId` | `uint64_t` | move gizmo 对应实体。 |
+| `hasRotateGizmo` | `bool` | 当前是否存在 rotate gizmo overlay。 |
+| `rotateGizmo` | `SceneViewportRotateGizmoDrawData` | rotate gizmo draw data 快照。 |
+| `rotateEntityId` | `uint64_t` | rotate gizmo 对应实体。 |
+| `hasScaleGizmo` | `bool` | 当前是否存在 scale gizmo overlay。 |
+| `scaleGizmo` | `SceneViewportScaleGizmoDrawData` | scale gizmo draw data 快照。 |
+| `scaleEntityId` | `uint64_t` | scale gizmo 对应实体。 |
+
+## 当前语义
+
+- 这是可提交给 `IViewportHostService::SetSceneViewTransformGizmoOverlayState(...)` 的 gizmo overlay state。
+- `HasAnyVisibleGizmo()` 当前会结合 `has*` 与各 draw data 的 `visible` 位判断是否真有可见 gizmo。
+
+## 测试覆盖
+
+`tests/Editor/test_scene_viewport_overlay_providers.cpp` 和 `tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前都直接消费这一结构。
+
+## 相关文档
+
+- [SceneViewportOverlayHandleBuilder](SceneViewportOverlayHandleBuilder.md)
+- [SceneViewportTransformGizmoHandleBuildInputs](SceneViewportTransformGizmoHandleBuildInputs.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md

@@ -0,0 +1,76 @@
+# SceneViewportOverlayHitTester
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `utility-header`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayHitTester.h`
+
+**描述**: 基于 overlay `handleRecords` 对 Scene View 鼠标位置做命中测试，并返回当前最佳命中结果。
+
+## 概览
+
+`SceneViewportOverlayHitTester` 解决的是“从 canonical overlay frame 里找出鼠标当前最可能命中的 handle”。
+
+它不重新计算 gizmo 几何，而是直接消费 [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) 产出的 `handleRecords`。
+
+## 当前公开入口
+
+- `HitTestSceneViewportOverlayHandles(...)`
+
+## 当前判定规则
+
+当前支持的 handle shape 包括：
+
+- `WorldRect`
+- `ScreenSegment`
+- `ScreenRect`
+- `ScreenQuad`
+
+命中成功后，最佳结果的选择顺序是：
+
+1. `priority` 更高者优先
+2. 同优先级下 `depth` 更近者优先
+3. 深度近似相同时 `distanceSq` 更小者优先
+
+## 当前实现特征
+
+- `WorldRect` 会先投影到屏幕再判断。
+- `ScreenSegment` 使用线段距离平方与 `hitThicknessPixels`。
+- `ScreenQuad` 使用逐边叉积判断点是否落在四边形内。
+- 输出的 `SceneViewportOverlayHandleHitResult` 会保留：
+  - `kind`
+  - `handleId`
+  - `entityId`
+  - `priority`
+  - `distanceSq`
+  - `depth`
+
+## 当前使用位置
+
+当前主调用方不再是 `SceneViewPanel` 直接调用，而是：
+
+- [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md)
+  的 request 重载内部先调用它
+- 随后再和 HUD 命中做统一仲裁
+
+因此面板当前只需构造 `SceneViewportInteractionResolveRequest`，不再自己手工串联命中函数。
+
+## 与测试的对应关系
+
+`tests/Editor/test_scene_viewport_interaction_resolver.cpp` 当前覆盖了：
+
+- request 重载会实际走 `HitTestSceneViewportOverlayHandles(...)` 路径。
+- 由它产出的 overlay handle 候选会继续参与和 HUD 命中的统一仲裁。
+
+## 当前实现边界
+
+- 这里只处理当前帧 overlay 几何，不持有历史状态。
+- 它只解析世界 overlay / gizmo handle，不处理 HUD orientation gizmo。
+- HUD 命中由 [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) 负责，统一排序由 resolver 完成。
+
+## 相关文档
+
+- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)
+- [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md)
+- [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md

@@ -0,0 +1,45 @@
+# BuildDefaultSceneViewportOverlayProviderRegistry
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+## 签名
+
+```cpp
+SceneViewportOverlayProviderRegistry BuildDefaultSceneViewportOverlayProviderRegistry();
+```
+
+## 作用
+
+构造当前 Scene View 默认使用的 overlay provider registry。
+
+## 当前实现行为
+
+当前实现会：
+
+1. 构造一个空的 `SceneViewportOverlayProviderRegistry`
+2. 先注册 [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md)
+3. 再注册 [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md)
+4. 最后注册 [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md)
+5. 返回 registry
+
+## 当前语义边界
+
+- 当前默认 registry 包含相机 provider、灯光 provider 与 transform gizmo provider 三项。
+- 注册顺序是契约的一部分，因为 registry 追加输出时会保留顺序。
+
+## 当前调用链
+
+[SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+的默认构造路径当前就使用这条函数来准备 provider registry。
+
+## 相关文档
+
+- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md)
+- [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md)
+- [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md)
+- [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md)
+- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md

@@ -0,0 +1,42 @@
+# CreateSceneViewportCameraOverlayProvider
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+## 签名
+
+```cpp
+std::unique_ptr<ISceneViewportOverlayProvider> CreateSceneViewportCameraOverlayProvider();
+```
+
+## 作用
+
+创建内建的 Scene View 相机 overlay provider。
+
+## 当前实现行为
+
+当前返回一个内部 `SceneViewportCameraOverlayProvider` 实例。
+它在有效上下文下会做两类事：
+
+- 遍历场景里已启用相机，为其追加相机图标 sprite
+- 对当前选中的已启用相机，追加视锥线框辅助几何
+
+## 当前语义边界
+
+- provider 只处理“相机相关 overlay”，不会生成灯光辅助内容。
+- 只有对象处于激活层级且带有效 `Transform` 时，当前实现才会继续构建对应 overlay。
+
+## 测试锚点
+
+`tests/Editor/test_scene_viewport_overlay_providers.cpp`
+中的 `CameraProviderBuildsSceneIconAndSelectedFrustum`
+当前覆盖了它的主要输出路径。
+
+## 相关文档
+
+- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md)
+- [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md)
+- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md

@@ -0,0 +1,42 @@
+# CreateSceneViewportLightOverlayProvider
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+## 签名
+
+```cpp
+std::unique_ptr<ISceneViewportOverlayProvider> CreateSceneViewportLightOverlayProvider();
+```
+
+## 作用
+
+创建内建的 Scene View 灯光 overlay provider。
+
+## 当前实现行为
+
+当前返回一个内部 `SceneViewportLightOverlayProvider` 实例。
+它在有效上下文下会做两类事：
+
+- 遍历场景里已启用灯光，为其追加灯光图标 sprite
+- 对当前选中的已启用方向光，追加方向环与射线辅助几何
+
+## 当前语义边界
+
+- provider 只处理“灯光相关 overlay”。
+- 额外辅助几何当前只覆盖 `Directional` 光源；点光和聚光不会生成同级别 helper。
+
+## 测试锚点
+
+`tests/Editor/test_scene_viewport_overlay_providers.cpp`
+中的 `LightProviderBuildsSceneIconAndSelectedDirectionalHelper`
+当前覆盖了它的主要输出路径。
+
+## 相关文档
+
+- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md)
+- [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md)
+- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md

@@ -0,0 +1,39 @@
+# CreateSceneViewportTransformGizmoOverlayProvider
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+## 签名
+
+```cpp
+std::unique_ptr<ISceneViewportOverlayProvider> CreateSceneViewportTransformGizmoOverlayProvider();
+```
+
+## 作用
+
+创建内建的 Scene View transform gizmo overlay provider。
+
+## 当前实现行为
+
+当前返回一个内部 `SceneViewportTransformGizmoOverlayProvider` 实例。
+它在有效上下文下会做两类事：
+
+- 检查 `context.transformGizmoOverlayState` 是否存在且至少有一类 gizmo 可见
+- 把这份 gizmo state 重新转回 `SceneViewportTransformGizmoHandleBuildInputs`，并向 `frameData` 追加：
+  - `screenTriangles`
+  - `handleRecords`
+
+## 当前语义边界
+
+- provider 本身不参与 gizmo 数学刷新，也不负责拖拽生命周期。
+- 它只消费已经准备好的 draw data 快照，把它写回统一的 editor overlay frame data。
+
+## 相关文档
+
+- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md)
+- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md)
+- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/ISceneViewportOverlayProvider.md

@@ -0,0 +1,41 @@
+# ISceneViewportOverlayProvider
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface-like abstract class`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+**描述**: 单个 Scene View 世界 overlay provider 的抽象接口。
+
+## 概述
+
+`ISceneViewportOverlayProvider` 定义了一类很明确的职责：
+
+- 给自己起一个稳定名字
+- 在给定构建上下文下，把本 provider 负责的 overlay 基元追加进 `SceneViewportOverlayFrameData`
+
+按当前实现，内建 provider 只有两种：
+
+- 相机 provider
+- 灯光 provider
+
+它们都在 `SceneViewportOverlayProviders.cpp` 里以内部类实现，再通过工厂函数暴露。
+
+## 当前接口语义
+
+- `GetName()` 返回 provider 名字，当前主要用于调试 / 诊断。
+- `AppendOverlay(...)` 接收只读构建上下文和可写 `frameData`，把本 provider 负责的图标或线段追加进去。
+- provider 可以选择在上下文无效、对象未启用或当前没有匹配对象时直接 no-op。
+
+## 当前实现边界
+
+- 这个接口本身不管理注册顺序；顺序由 [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) 决定。
+- 它也不负责渲染；只是生成 overlay 数据。
+
+## 相关文档
+
+- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md)
+- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md)
+- [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md)
+- [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md

@@ -0,0 +1,57 @@
+# SceneViewportOverlayBuildContext
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+**描述**: 一帧 Scene View editor overlay 构建所需的借用输入集合。
+
+## 概述
+
+`SceneViewportOverlayBuildContext` 不拥有任何资源。
+它只是把 provider 构建阶段真正需要的几个只读入口打包到一起：
+
+- 当前 editor 上下文
+- 当前场景
+- 当前 Scene View 相机 overlay 数据
+- 当前视口尺寸
+- 当前选中对象 ID 列表
+- 当前帧 transform gizmo overlay state
+
+## 字段
+
+| 字段 | 说明 |
+|------|------|
+| `editorContext` | 当前 `IEditorContext`，供 provider 读取 editor 级状态。 |
+| `scene` | 当前场景，只读查询入口。 |
+| `overlay` | 当前 Scene View 相机投影与朝向数据。 |
+| `viewportWidth` / `viewportHeight` | 当前视口像素尺寸。 |
+| `selectedObjectIds` | 当前选中对象 ID 列表。 |
+| `transformGizmoOverlayState` | 当前帧 transform gizmo draw data 快照；可为空。 |
+
+## `IsValid()` 语义
+
+当前 `IsValid()` 只有在下面条件同时满足时才返回 `true`：
+
+- `editorContext != nullptr`
+- `scene != nullptr`
+- `overlay != nullptr`
+- `overlay->valid == true`
+- `viewportWidth > 0`
+- `viewportHeight > 0`
+- `selectedObjectIds != nullptr`
+
+`transformGizmoOverlayState` 不参与 `IsValid()` 判定；只有需要 gizmo 几何的 provider 才会额外检查它。
+
+## 当前语义边界
+
+- 它只是一组借用指针 / 标量，不负责生命周期管理。
+- provider 当前普遍把“`context.IsValid()` 为假时直接 no-op”当作统一的失败路径。
+
+## 相关文档
+
+- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md)
+- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md)
+- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md

@@ -0,0 +1,54 @@
+# SceneViewportOverlayProviderRegistry
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `class`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+**描述**: 维护一组 `ISceneViewportOverlayProvider`，并按注册顺序把它们的输出追加到同一帧 overlay 数据中。
+
+## 概述
+
+`SceneViewportOverlayProviderRegistry` 是 provider 体系的聚合层。
+它内部持有：
+
+```cpp
+std::vector<std::unique_ptr<ISceneViewportOverlayProvider>> m_providers;
+```
+
+因此 provider 所有权当前完全由 registry 接管。
+
+## 当前公开行为
+
+### `AddProvider(...)`
+
+- 传入空指针时直接 no-op
+- 非空时把 provider 追加到 `m_providers` 末尾
+
+### `GetProviderCount()`
+
+- 返回当前注册 provider 数量
+
+### `GetProvider(index)`
+
+- 索引合法时返回对应 provider 观察指针
+- 越界时返回 `nullptr`
+
+### `AppendOverlay(...)`
+
+- 若 `context.IsValid()` 为假，直接 no-op
+- 否则按注册顺序遍历所有非空 provider
+- 对每个 provider 调用 `provider->AppendOverlay(context, frameData)`
+
+## 顺序语义
+
+当前 registry 明确保留注册顺序。
+`tests/Editor/test_scene_viewport_overlay_providers.cpp`
+里的 `AppendsProvidersInRegistrationOrder` 就在验证这一点。
+
+## 相关文档
+
+- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md)
+- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md)
+- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md)

docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviders.md

@@ -0,0 +1,66 @@
+# SceneViewportOverlayProviders
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct + interface + registry + factory functions`
+
+**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h`
+
+**描述**: 定义 Scene View editor overlay provider 的构建上下文、provider 接口、注册表以及默认相机 / 灯光 / transform gizmo provider 工厂。
+
+## 概述
+
+这个头文件把 Scene View editor overlay 的“语义生成”进一步拆成了 provider 体系：
+
+- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md)
+  提供一帧 overlay 构建所需的只读输入
+- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md)
+  定义单个 overlay provider 的统一接口
+- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md)
+  负责按注册顺序汇总多个 provider
+- 默认工厂函数
+  返回相机 provider、灯光 provider、transform gizmo provider，以及三者组合成的默认 registry
+
+按当前实现，[SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+默认持有的就是 [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md)
+构造出来的 registry。
+
+## 当前默认 provider 语义
+
+- 相机 provider 会给已启用相机生成场景图标。
+- 当相机对象被选中时，还会生成相机视锥辅助线框。
+- 灯光 provider 会给已启用灯光生成场景图标。
+- 当方向光对象被选中时，还会生成方向环与射线辅助几何。
+- transform gizmo provider 会把当前 `SceneViewportTransformGizmoOverlayState` 里的 draw data 转成 `screenTriangles` 与 `handleRecords`。
+
+## 公开类型
+
+| 成员 | 说明 |
+|------|------|
+| [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) | 一帧 overlay 构建所需的只读上下文。 |
+| [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) | 单个 overlay provider 的抽象接口。 |
+| [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) | provider 聚合与顺序分发容器。 |
+
+## 公开函数
+
+| 函数 | 说明 |
+|------|------|
+| [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) | 创建内建相机 overlay provider。 |
+| [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) | 创建内建灯光 overlay provider。 |
+| [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md) | 创建内建 transform gizmo overlay provider。 |
+| [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) | 构建默认 registry，当前按“相机后灯光后 transform gizmo”顺序注册。 |
+
+## 测试锚点
+
+`tests/Editor/test_scene_viewport_overlay_providers.cpp` 当前覆盖了：
+
+- registry 按注册顺序追加 provider 输出
+- 相机 provider 的图标与选中视锥生成
+- 灯光 provider 的图标与选中方向光辅助几何生成
+- transform gizmo provider 的 `screenTriangles / handleRecords` 追加
+
+## 相关文档
+
+- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
+- [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md)

docs/api/XCEngine/Editor/Viewport/Viewport.md

@@ -35,6 +35,14 @@
   把 HUD 命中与 overlay handle 命中合并成统一交互结果。
 - [SceneViewportInteractionActions](SceneViewportInteractionActions/SceneViewportInteractionActions.md)
   把交互结果折叠成 hover / click action，并分发 selection / orientation 对齐。
+- [SceneViewportEditorOverlayData](SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
+  定义 world line、sprite、screen triangle 与 handle record 组成的 canonical overlay 帧协议。
+- [SceneViewportOverlayProviders](SceneViewportOverlayProviders/SceneViewportOverlayProviders.md)
+  定义相机 / 灯光 / transform gizmo overlay provider 接口、registry 与默认工厂。
+- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+  按 provider registry 聚合一帧 Scene View editor overlay 数据。
+- [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md)
+  基于 overlay `handleRecords` 对鼠标位置做命中测试，并给 resolver 提供候选结果。
 - [SceneViewportMoveGizmo](SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
   处理轴向 / 平面位移 gizmo 的绘制数据、命中与多对象拖拽事务。
 - [SceneViewportRotateGizmo](SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
@@ -70,6 +78,10 @@
 - [ViewportObjectIdPicker](ViewportObjectIdPicker/ViewportObjectIdPicker.md)
 - [SceneViewportHudOverlay](SceneViewportHudOverlay/SceneViewportHudOverlay.md)
 - [SceneViewportOrientationGizmo](SceneViewportOrientationGizmo/SceneViewportOrientationGizmo.md)
+- [SceneViewportEditorOverlayData](SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
+- [SceneViewportOverlayProviders](SceneViewportOverlayProviders/SceneViewportOverlayProviders.md)
+- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
+- [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md)
 - [SceneViewportMoveGizmo](SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
 - [SceneViewportRotateGizmo](SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
 - [SceneViewportScaleGizmo](SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)