docs: formalize scene viewport shader resource docs

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

@@ -0,0 +1,39 @@
+# SceneViewportGridPassData
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h`
+
+## 描述
+
+Scene View 网格 pass 的 editor 侧输入快照。
+
+## 当前字段
+
+- `valid`
+- `cameraPosition`
+- `cameraForward`
+- `cameraRight`
+- `cameraUp`
+- `verticalFovDegrees`
+- `nearClipPlane`
+- `farClipPlane`
+- `orbitDistance`
+
+## 当前语义
+
+- 这组字段与 runtime `Rendering::Passes::InfiniteGridPassData` 一一对应。
+- 它本身不包含样式、shader 路径或 `RenderSurface` 信息，只描述当前 Scene View 相机姿态。
+- `orbitDistance` 也会被原样传给 runtime 结构；但当前 `BuildInfiniteGridParameters(...)` 仍不会用它参与网格参数推导。
+
+## 测试覆盖
+
+- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 `BuildSceneViewportGridPassData(...)` 会把 Scene View overlay 中的相机字段正确拷贝到这里。
+
+## 相关文档
+
+- [SceneViewportPassSpecs](SceneViewportPassSpecs.md)
+- [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md)
+- [InfiniteGridPassData](../../../Rendering/Passes/BuiltinInfiniteGridPass/InfiniteGridPassData.md)

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

@@ -0,0 +1,42 @@
+# SceneViewportPassSpecs
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `header-helper + structs`
+
+**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h`
+
+**描述**: Scene View 渲染计划与底层 runtime pass 之间的数据适配头，负责把 editor 侧的网格与选中描边配置转换成 `BuiltinInfiniteGridPass` / `BuiltinObjectIdOutlinePass` 可直接消费的结构。
+
+## 概览
+
+`SceneViewportPassSpecs.h` 当前只做轻量数据桥接，不自己创建任何 `RenderPass` 或 GPU 资源。
+
+它主要服务两条路径：
+
+- 网格路径：`SceneViewportGridPassData` -> [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) -> `Rendering::Passes::InfiniteGridPassData`
+- 选中描边路径：`SceneViewportSelectionOutlineStyle` -> [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) -> `Rendering::Passes::ObjectIdOutlineStyle`
+
+## 公开类型与函数
+
+| 成员 | 说明 |
+|------|------|
+| [SceneViewportGridPassData](SceneViewportGridPassData.md) | editor 侧网格 pass 输入快照。 |
+| [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) | 把 editor 网格数据拷贝成 runtime infinite-grid 输入。 |
+| [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) | editor 侧选中描边样式。 |
+| [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) | 把 editor 描边样式拷贝成 runtime outline 样式。 |
+
+## 当前使用位置
+
+- `ViewportHostRenderFlowUtils.h` 当前构建这两个 editor 侧结构。
+- `SceneViewportGridPass.cpp` 和 `SceneViewportSelectionOutlinePass.cpp` 会把它们进一步转换成 runtime pass 输入。
+- `tests/Editor/test_viewport_render_flow_utils.cpp` 覆盖了这两组数据的默认值和拷贝行为。
+
+## 相关文档
+
+- [SceneViewportGridPassData](SceneViewportGridPassData.md)
+- [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md)
+- [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md)
+- [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md)
+- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md)
+- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)

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

@@ -0,0 +1,33 @@
+# SceneViewportSelectionOutlineStyle
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h`
+
+## 描述
+
+Scene View 选中描边 pass 的 editor 侧样式配置。
+
+## 当前字段与默认值
+
+- `outlineColor = Math::Color(1.0f, 0.4f, 0.0f, 1.0f)`
+- `outlineWidthPixels = 2.0f`
+- `debugSelectionMask = false`
+
+## 当前语义
+
+- 这组字段与 runtime `Rendering::Passes::ObjectIdOutlineStyle` 一一对应。
+- 默认样式就是当前 Scene View 常见的橙色、`2px` 选中描边。
+- `debugSelectionMask` 打开时，底层 outline pass 会切换到调试遮罩输出语义，而不是正常描边合成。
+
+## 测试覆盖
+
+- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了默认样式和 debug 样式构建结果。
+
+## 相关文档
+
+- [SceneViewportPassSpecs](SceneViewportPassSpecs.md)
+- [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md)
+- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md)

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

@@ -0,0 +1,37 @@
+# ToBuiltinSceneViewportGridPassData
+
+把 editor 侧网格输入拷贝成 runtime infinite-grid 输入。
+
+```cpp
+inline Rendering::Passes::InfiniteGridPassData ToBuiltinSceneViewportGridPassData(
+    const SceneViewportGridPassData& data);
+```
+
+## 参数
+
+- `data` - editor 侧网格 pass 输入。
+
+## 当前语义
+
+- 当前实现只是字段逐项拷贝：
+  - `valid`
+  - `cameraPosition`
+  - `cameraForward`
+  - `cameraRight`
+  - `cameraUp`
+  - `verticalFovDegrees`
+  - `nearClipPlane`
+  - `farClipPlane`
+  - `orbitDistance`
+- 它不做坐标变换、默认值修正或单位换算。
+
+## 调用方影响
+
+- `SceneViewportGridPassRenderer` 最终会把转换结果交给 runtime [BuiltinInfiniteGridPass](../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)。
+- 因为这里只做拷贝，所以如果 editor 侧输入本身无效，runtime 行为也会直接继承这一状态。
+
+## 相关文档
+
+- [SceneViewportPassSpecs](SceneViewportPassSpecs.md)
+- [SceneViewportGridPassData](SceneViewportGridPassData.md)
+- [InfiniteGridPassData](../../../Rendering/Passes/BuiltinInfiniteGridPass/InfiniteGridPassData.md)

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

@@ -0,0 +1,30 @@
+# ToBuiltinSceneViewportSelectionOutlineStyle
+
+把 editor 侧选中描边样式拷贝成 runtime outline 样式。
+
+```cpp
+inline Rendering::Passes::ObjectIdOutlineStyle ToBuiltinSceneViewportSelectionOutlineStyle(
+    const SceneViewportSelectionOutlineStyle& style);
+```
+
+## 参数
+
+- `style` - editor 侧描边样式。
+
+## 当前语义
+
+- 当前实现只做字段逐项拷贝：
+  - `outlineColor`
+  - `outlineWidthPixels`
+  - `debugSelectionMask`
+- 不做颜色空间转换、宽度 clamp 或额外策略判断。
+
+## 调用方影响
+
+- `SceneViewportSelectionOutlinePassRenderer` 会把转换结果直接交给 runtime [BuiltinObjectIdOutlinePass](../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)。
+
+## 相关文档
+
+- [SceneViewportPassSpecs](SceneViewportPassSpecs.md)
+- [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md)
+- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md)

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

@@ -0,0 +1,31 @@
+# Detail::BuildSceneViewportEditorResourcePath
+
+把 editor 资源相对路径拼成 repo 内绝对资源路径。
+
+```cpp
+inline Containers::String BuildSceneViewportEditorResourcePath(const std::filesystem::path& relativePath);
+```
+
+## 参数
+
+- `relativePath` - `editor/resources/` 下的相对路径。
+
+## 当前语义
+
+- 当前实现会拼接：
+
+```text
+{repo root}/editor/resources/{relativePath}
+```
+
+- 然后再调用 [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) 输出规范化结果。
+
+## 返回值
+
+- 规范化后的绝对资源路径字符串。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md)
+- [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md)

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

@@ -0,0 +1,21 @@
+# GetSceneViewportCameraGizmoIconPath
+
+返回 Scene View camera gizmo icon 的资源路径。
+
+```cpp
+inline Containers::String GetSceneViewportCameraGizmoIconPath();
+```
+
+## 当前语义
+
+- 当前实现把 `Icons/camera_gizmo.png` 交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)。
+- 返回值指向 repo 内 `editor/resources/Icons/camera_gizmo.png`。
+
+## 测试覆盖
+
+- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径，且目标 icon 文件存在。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)

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

@@ -0,0 +1,27 @@
+# GetSceneViewportInfiniteGridShaderPath
+
+返回 Scene View infinite-grid shader 的资源路径。
+
+```cpp
+inline Containers::String GetSceneViewportInfiniteGridShaderPath();
+```
+
+## 当前语义
+
+- 当前实现把相对路径：
+
+```text
+shaders/scene-viewport/infinite-grid/infinite-grid.shader
+```
+
+交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终得到 repo 内 `editor/resources/` 下的绝对路径。
+
+## 测试覆盖
+
+- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径、目标文件存在，并且 `ShaderLoader` 能成功加载该 shader。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)
+- [BuiltinInfiniteGridPass](../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)

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

@@ -0,0 +1,21 @@
+# GetSceneViewportMainLightGizmoIconPath
+
+返回 Scene View main-light gizmo icon 的资源路径。
+
+```cpp
+inline Containers::String GetSceneViewportMainLightGizmoIconPath();
+```
+
+## 当前语义
+
+- 当前实现把 `Icons/main_light_gizmo.png` 交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)。
+- 返回值指向 repo 内 `editor/resources/Icons/main_light_gizmo.png`。
+
+## 测试覆盖
+
+- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径，且目标 icon 文件存在。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)

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

@@ -0,0 +1,27 @@
+# GetSceneViewportObjectIdOutlineShaderPath
+
+返回 Scene View object-id outline shader 的资源路径。
+
+```cpp
+inline Containers::String GetSceneViewportObjectIdOutlineShaderPath();
+```
+
+## 当前语义
+
+- 当前实现把相对路径：
+
+```text
+shaders/scene-viewport/object-id-outline/object-id-outline.shader
+```
+
+交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终得到 repo 内 `editor/resources/` 下的绝对路径。
+
+## 测试覆盖
+
+- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的路径存在，并且 `ResourceManager` 能按该路径加载 outline shader。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)
+- [BuiltinObjectIdOutlinePass](../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)

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

@@ -0,0 +1,25 @@
+# Detail::GetSceneViewportResourceRepoRootPath
+
+返回当前 Scene View 资源路径拼接使用的 repo root。
+
+```cpp
+inline std::filesystem::path GetSceneViewportResourceRepoRootPath();
+```
+
+## 当前语义
+
+- 如果定义了编译宏 `XCENGINE_EDITOR_REPO_ROOT`，当前实现会直接把该宏值转换成 `std::filesystem::path`。
+- 否则会以当前头文件 `__FILE__` 为起点，连续 `parent_path()` 三次回退到 repo root。
+
+## 设计含义
+
+- 这让编辑器既可以在已知 repo root 的构建环境下使用固定路径，也可以在本地源码树中按相对位置推导资源根目录。
+
+## 返回值
+
+- 推导出的 repo root 路径。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)

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

@@ -0,0 +1,30 @@
+# Detail::NormalizeSceneViewportResourcePath
+
+把 `std::filesystem::path` 规范化并转成 `Containers::String`。
+
+```cpp
+inline Containers::String NormalizeSceneViewportResourcePath(const std::filesystem::path& path);
+```
+
+## 当前语义
+
+- 当前实现等价于：
+
+```cpp
+return Containers::String(path.lexically_normal().generic_string().c_str());
+```
+
+- 这意味着它会先做 `lexically_normal()`，再统一输出使用 `/` 分隔的 generic path 字符串。
+
+## 参数
+
+- `path` - 待规范化的文件系统路径。
+
+## 返回值
+
+- 规范化后的 `Containers::String` 路径。
+
+## 相关文档
+
+- [SceneViewportResourcePaths](SceneViewportResourcePaths.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)

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

@@ -0,0 +1,49 @@
+# SceneViewportResourcePaths
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `inline helper header`
+
+**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h`
+
+**描述**: 为 Scene View 相关 shader 与 icon 资源生成 repo 内绝对路径的 inline helper 头文件。
+
+## 概览
+
+`SceneViewportResourcePaths.h` 当前是 Scene View 资源路径解析的实际定义位置。
+
+它负责：
+
+- 定位 editor repo root。
+- 把相对路径拼到 `editor/resources/` 下。
+- 规范化为 `Containers::String`。
+- 返回 infinite-grid shader、object-id outline shader、camera icon、main-light icon 的绝对路径。
+
+`SceneViewportShaderPaths.h` 当前只是包含这个头文件的轻量兼容层。
+
+## 公开 helper
+
+| 成员 | 说明 |
+|------|------|
+| [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) | 规范化 `std::filesystem::path` 并转成 `Containers::String`。 |
+| [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) | 推导 repo root。 |
+| [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) | 把相对路径拼到 `editor/resources/` 下。 |
+| [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) | 返回 Scene View infinite-grid shader 路径。 |
+| [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) | 返回 Scene View object-id outline shader 路径。 |
+| [GetSceneViewportCameraGizmoIconPath](GetSceneViewportCameraGizmoIconPath.md) | 返回 camera gizmo icon 路径。 |
+| [GetSceneViewportMainLightGizmoIconPath](GetSceneViewportMainLightGizmoIconPath.md) | 返回 main-light gizmo icon 路径。 |
+
+## 测试覆盖
+
+- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这些 helper 返回的路径是绝对路径、文件实际存在，并能成功加载 Scene View shader 资源。
+
+## 相关文档
+
+- [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md)
+- [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md)
+- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)
+- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md)
+- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md)
+- [GetSceneViewportCameraGizmoIconPath](GetSceneViewportCameraGizmoIconPath.md)
+- [GetSceneViewportMainLightGizmoIconPath](GetSceneViewportMainLightGizmoIconPath.md)
+- [SceneViewportShaderPaths](../SceneViewportShaderPaths/SceneViewportShaderPaths.md)

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

@@ -1,31 +1,31 @@
 # Detail::BuildSceneViewportShaderPath
 
-把 Scene View shader 相对路径拼成 repo 内绝对资源路径字符串。
+当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。
 
-```cpp
+## 当前状态
-inline Containers::String BuildSceneViewportShaderPath(const std::filesystem::path& relativePath);
-```
 
-## 行为说明
+- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `BuildSceneViewportShaderPath(...)`。
+- 路径构建职责已经迁移到 [Detail::BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md)。
 
-当前实现会拼接：
+## 迁移方式
+
+- 如果旧调用点想得到：
 
 ```text
 {repo root}/editor/resources/shaders/scene-viewport/{relativePath}
 ```
 
-然后再调用 [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) 输出规范化结果。
+- 当前应改为调用 `BuildSceneViewportEditorResourcePath()`，并传入完整相对路径：
 
-## 参数
+```text
+shaders/scene-viewport/{relativePath}
+```
 
-- `relativePath` - `scene-viewport` 目录下的相对 shader 路径。
+- 如果目标只是 infinite-grid 或 object-id outline shader，优先直接使用更高层的专用 getter。
-
-## 返回值
-
-- `Containers::String` - 规范化后的完整资源路径。
 
 ## 相关文档
 
 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md)
-- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md)
+- [BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md)
-- [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md)
+- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md)
+- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md)

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

@@ -1,31 +1,18 @@
 # GetSceneViewportInfiniteGridShaderPath
 
-返回 Scene View 无限网格 shader 的资源路径。
+通过兼容头 `SceneViewportShaderPaths.h` 可见的 Scene View infinite-grid shader 路径 helper。
 
 ```cpp
 inline Containers::String GetSceneViewportInfiniteGridShaderPath();
 ```
 
-## 行为说明
+## 当前语义
 
-当前实现把相对路径：
+- 当前函数的真实声明位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)，`SceneViewportShaderPaths.h` 只是通过 `#include` 把它重新暴露给旧调用点。
-
+- 因此路径解析、规范化和测试覆盖，都应以资源路径头的文档为准。
-```text
-infinite-grid/infinite-grid.shader
-```
-
-交给 [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)，最终得到 repo 内 `editor/resources/shaders/scene-viewport/infinite-grid/infinite-grid.shader` 的规范化字符串路径。
-
-## 当前使用位置
-
-- `SceneViewportGridPassRenderer` 构造时把这个路径交给 Runtime 侧 `BuiltinInfiniteGridPass`
-
-## 返回值
-
-- `Containers::String` - 无限网格 shader 路径。
 
 ## 相关文档
 
 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md)
-- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)
+- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md)
-- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md)
+- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)

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

@@ -1,31 +1,18 @@
 # GetSceneViewportObjectIdOutlineShaderPath
 
-返回 Scene View object-id outline shader 的资源路径。
+通过兼容头 `SceneViewportShaderPaths.h` 可见的 Scene View object-id outline shader 路径 helper。
 
 ```cpp
 inline Containers::String GetSceneViewportObjectIdOutlineShaderPath();
 ```
 
-## 行为说明
+## 当前语义
 
-当前实现把相对路径：
+- 当前函数的真实声明位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)，`SceneViewportShaderPaths.h` 只是通过 `#include` 把它重新暴露给旧调用点。
-
+- 因此路径解析、规范化和测试覆盖，都应以资源路径头的文档为准。
-```text
-object-id-outline/object-id-outline.shader
-```
-
-交给 [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)，最终得到 repo 内 `editor/resources/shaders/scene-viewport/object-id-outline/object-id-outline.shader` 的规范化字符串路径。
-
-## 当前使用位置
-
-- `SceneViewportSelectionOutlinePassRenderer` 构造时把这个路径交给 Runtime 侧 `BuiltinObjectIdOutlinePass`
-
-## 返回值
-
-- `Containers::String` - object-id outline shader 路径。
 
 ## 相关文档
 
 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md)
-- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)
+- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md)
-- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)
+- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)

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

@@ -1,27 +1,20 @@
 # Detail::GetSceneViewportShaderRepoRootPath
 
-返回当前 Scene View shader 路径拼接所使用的 repo root。
+当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。
 
-```cpp
+## 当前状态
-inline std::filesystem::path GetSceneViewportShaderRepoRootPath();
-```
 
-## 行为说明
+- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `GetSceneViewportShaderRepoRootPath()`。
+- repo root 推导逻辑已经迁移到 [Detail::GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md)。
 
-当前实现有两条路径：
+## 迁移方式
 
-- 如果定义了 `XCENGINE_EDITOR_REPO_ROOT`
+- 旧调用点应改为使用 `GetSceneViewportResourceRepoRootPath()`。
-  - 直接把这个编译时宏转成 `std::filesystem::path`
+- 新 helper 仍保留原先的两条分支：
-- 否则
+  - 优先使用 `XCENGINE_EDITOR_REPO_ROOT`
-  - 以当前头文件 `__FILE__` 为起点，连续 `parent_path()` 三次回退到 repo root
+  - 否则基于 `__FILE__` 回退推导 repo root
-
-这让编辑器既可以在已知 repo root 的构建环境下直接使用固定路径，也可以在本地源码树里按相对位置回推。
-
-## 返回值
-
-- `std::filesystem::path` - 当前推导出的 repo root。
 
 ## 相关文档
 
 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md)
-- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)
+- [GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md)

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

@@ -1,34 +1,18 @@
 # Detail::NormalizeSceneViewportShaderPath
 
-把 `std::filesystem::path` 规范化并转成 `Containers::String`。
+当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。
 
-```cpp
+## 当前状态
-inline Containers::String NormalizeSceneViewportShaderPath(const std::filesystem::path& path);
-```
 
-## 行为说明
+- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `NormalizeSceneViewportShaderPath(...)`。
+- 规范化逻辑已经迁移到 [Detail::NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md)。
 
-当前实现等价于：
+## 迁移方式
 
-```cpp
+- 旧调用点应改为使用 `NormalizeSceneViewportResourcePath()`。
-return Containers::String(path.lexically_normal().generic_string().c_str());
+- 新 helper 仍然执行 `lexically_normal().generic_string()` 并返回 `Containers::String`，只是名字从 shader 专用改成了更通用的 resource 路径语义。
-```
-
-这意味着：
-
-- 会先做 `lexically_normal()`
-- 输出统一使用 `/` 分隔的 generic path
-- 返回类型是 Editor / Rendering 侧常用的 `Containers::String`
-
-## 参数
-
-- `path` - 待规范化的文件系统路径。
-
-## 返回值
-
-- `Containers::String` - 规范化后的字符串路径。
 
 ## 相关文档
 
 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md)
-- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)
+- [NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md)

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

@@ -2,54 +2,43 @@
 
 **命名空间**: `XCEngine::Editor`
 
-**类型**: `inline helper header`
+**类型**: `compatibility header`
 
 **源文件**: `editor/src/Viewport/SceneViewportShaderPaths.h`
 
-**描述**: 为 Scene View 的 editor-owned GPU pass 生成 repo 内 shader 资源路径。
+**描述**: 当前仅作为兼容层存在的 Scene View 资源路径头文件，头文件本体只包含 `SceneViewportResourcePaths.h`，不再自己定义 helper。
 
 ## 概览
 
-`SceneViewportShaderPaths.h` 是一个纯 inline helper 头文件。它不负责加载 shader，也不触碰 `AssetDatabase`；当前职责只是把 repo 根目录和 Scene View shader 相对路径拼成稳定的 `Containers::String`。
+`SceneViewportShaderPaths.h` 现在的实现只有一行：
 
-这组 helper 当前服务于两条 editor-owned pass 路径：
+```cpp
+#include "SceneViewportResourcePaths.h"
+```
 
-- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md)
+这意味着：
-- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)
 
-## 当前实现行为
+- 当前实际的路径 helper 定义位置已经迁移到 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)。
+- 保留这个头文件主要是为了兼容仍然 `#include "Viewport/SceneViewportShaderPaths.h"` 的现有调用点。
+- 新代码若要理解真实声明和语义，应优先看 `SceneViewportResourcePaths.h` 对应的文档。
+
+## 当前可见能力
+
+- 通过包含链，调用方仍可拿到：
+  - [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md)
+  - [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md)
+- 但这两个 helper 的真实声明已经位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)。
+
+## 迁移说明
+
+下列旧页面保留为迁移说明，因为这些 helper 名已经不再是当前头文件里的真实声明：
 
-- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md)
-  - 优先使用编译宏 `XCENGINE_EDITOR_REPO_ROOT`
-  - 否则回退到基于 `__FILE__` 的相对路径推导
 - [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)
-  - 会把 repo root、`editor/resources/shaders/scene-viewport/` 和传入相对路径拼接起来
 - [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md)
-  - 把 `std::filesystem::path` 规范化成 `Containers::String`
+- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md)
-- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md)
-  - 返回无限网格 shader 路径
-- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md)
-  - 返回 object-id outline shader 路径
-
-## 当前使用位置
-
-- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp`
-  - `SceneViewportGridPassRenderer` 构造时调用 `GetSceneViewportInfiniteGridShaderPath()`
-- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp`
-  - `SceneViewportSelectionOutlinePassRenderer` 构造时调用 `GetSceneViewportObjectIdOutlineShaderPath()`
-
-## 当前限制
-
-- 这里只负责拼路径，不验证目标文件是否存在
-- 路径策略当前写死在 repo 内 `editor/resources/shaders/scene-viewport/`
-- Detail 命名空间下的 helper 也是 header 内直接暴露的 inline 实现，不是独立编译单元
 
 ## 相关文档
 
-- [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md)
+- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)
-- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md)
-- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)
 - [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md)
 - [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md)
-- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md)
-- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)