docs: refresh editor xcui and material inspector pages

README.md

@@ -1,123 +1,179 @@
 # XCEngine
 
-`XCEngine` 是一个 Windows-first、editor-first 的 C++20 游戏引擎工作区。当前主线围绕 `RHI -> Rendering -> Editor -> Asset Pipeline -> Mono Scripting` 演进，目标不是堆 sample，而是把可运行的引擎与编辑器主链持续收口成型。
+`XCEngine` 是一个基于 `C++20` 的游戏引擎。当前代码中已经包含 `RHI`、`Rendering`、`Scene`、`Resources`、`Editor`、`Mono C# Scripting` 和 `XCUI` 相关模块；本 README 只描述当前已经实现或已经接入的能力。
 
-## 项目定位
+## 核心特性
 
-- `engine/` 提供核心静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Input`、`Audio`、`Scripting` 等模块。
-- `editor/` 是当前正式桌面编辑器，宿主基于 Win32 + D3D12，编辑器 target 名为 `XCEditor`，输出文件名为 `XCEngine.exe`。
-- `new_editor/` 是基于 `XCUI` 的新编辑器主线，当前仍在并行演进。
-- `project/` 是随仓库维护的示例工程，已经采用 `Assets + .meta + Library` 布局。
-- `tests/` 覆盖 Engine、Rendering、RHI、Editor、Scripting、UI 等主线模块。
+### 渲染
 
-## 当前能力
+- 内置跨后端 `RHI` 抽象层，当前支持 `D3D12`、`OpenGL`、`Vulkan`
+- 当前主渲染链为 `SceneRenderer -> CameraRenderer -> BuiltinForwardPipeline`
+- 已接入前向渲染主路径、透明路径和 skybox 路径
+- 已具备方向光阴影通路
+- 已具备 `object-id` pass，可用于编辑器拾取
+- 已具备选中描边、最终颜色合成和颜色缩放后处理 pass
+- 已具备无限网格 pass，可用于 Scene View
+- 已接入 `NanoVDB` 体积渲染 pass
+- `RenderSurface` 允许同一条渲染链服务于窗口输出、编辑器视口和离屏目标
 
-- `RHI` 当前维护 `D3D12 / OpenGL / Vulkan` 三个后端。
-- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链。
-- Scene View 已接通 object-id picking、selection outline、grid、overlay 与 gizmo 渲染。
-- 资源系统已采用 `AssetDatabase + Artifact + Library` 工作流，而不是简单文件直读。
-- `Material / Shader / Texture / Mesh` 已接入正式资源导入与运行时加载链路。
-- 编辑器已支持项目加载、Scene/Game viewport、Inspector、Hierarchy、Project 面板等基础闭环。
-- Mono C# 脚本运行时与项目脚本程序集构建链路已接入当前工作区。
-- `new_editor/` 正在推进 `XCUI` 宿主、控件与 shell 体系。
+### 场景与运行时
 
-## 仓库结构
+- 采用 `Scene / GameObject / Component` 结构
+- 已具备场景更新、运行时驱动和场景序列化能力
+- 内置常用组件，包括：
+  - `TransformComponent`
+  - `CameraComponent`
+  - `LightComponent`
+  - `MeshFilterComponent`
+  - `MeshRendererComponent`
+  - `VolumeRendererComponent`
+  - `AudioSourceComponent`
+  - `AudioListenerComponent`
+  - `ScriptComponent`
 
-- `engine/`：引擎核心实现与公共头文件。
-- `editor/`：当前正式编辑器与 viewport 接线。
-- `new_editor/`：XCUI 新编辑器主线。
-- `managed/`：`XCEngine.ScriptCore` 与示例托管程序集。
-- `project/`：示例工程与随仓库维护的资产。
-- `tests/`：单元测试、集成测试与阶段性回归入口。
-- `docs/`：架构说明、API 文档、计划与历史归档。
-- `mvs/`：原型、实验工程与外部参考材料。
+### 资源系统
 
-## 环境要求
+- 资源主线不是简单文件直读，而是 `AssetDatabase + Artifact + Library` 工作流
+- 已具备项目资产索引、导入、重导入和缓存维护链路
+- 已接入的资源类型包括：
+  - `Mesh`
+  - `Texture`
+  - `Shader`
+  - `Material`
+  - `AudioClip`
+  - `VolumeField`
+  - `UI Document`
+- 内置 `builtin://` 资源入口，可直接使用基础 mesh、材质等内置资源
 
-当前推荐在 Windows 上构建和运行。
+### 脚本系统
+
+- 可选启用基于 `Mono` 的 `C#` 脚本运行时
+- 托管程序集分为：
+  - `XCEngine.ScriptCore`
+  - `GameScripts`
+- 脚本组件由 `ScriptComponent` 承载
+- 引擎当前支持脚本类发现、字段元数据读取、默认值读取和字段存储
+- 支持脚本字段 override 持久化与运行时同步
+- 编辑器已接入项目脚本程序集重建与脚本运行时重载
+
+### 编辑器
+
+- 当前正式编辑器是基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
+- 当前已具备以下基础工作流：
+  - `Hierarchy`
+  - `Inspector`
+  - `Project`
+  - `Console`
+  - `Scene View`
+  - `Game View`
+- `Scene View` 已接入：
+  - object-id picking
+  - selection outline
+  - overlay
+  - transform gizmo
+  - infinite grid
+- `Inspector` 已能处理常规组件检查，也已接入 `ScriptComponent` 与材质资源检查路径
+- 编辑器能够识别项目目录、加载项目资源、接通 `Library/ScriptAssemblies` 中的脚本程序集
+
+### UI 与 XCUI
+
+- 引擎内部包含 retained-mode UI 基础设施
+- 已具备：
+  - 布局系统
+  - 样式系统
+  - 焦点控制
+  - 输入分发
+  - 快捷键分发
+  - 文本输入编辑
+  - 选择模型
+  - 拖拽交互模型
+- 运行时 UI 主链包括：
+  - `UIScreenDocumentHost`
+  - `UIScreenPlayer`
+  - `UISystem`
+- 新编辑器路线基于 `XCUIEditorLib` 推进，当前已经包含树视图、列表视图、菜单、标签条、属性网格、字段控件、workspace / dock / viewport shell 等基础组件
+
+### 音频
+
+- 已具备 `AudioSystem`
+- 已接入 `AudioSourceComponent` 与 `AudioListenerComponent`
+- 当前代码中已包含 `AudioMixer` 和多种效果器/分析器实现入口：
+  - `Equalizer`
+  - `FFTFilter`
+  - `Reverbation`
+  - `HRTF`
+
+### 测试
+
+- 引擎不是“只靠手工点点看”的状态，当前已具备大规模测试树
+- 覆盖范围包括：
+  - Engine 基础模块
+  - Rendering
+  - RHI
+  - Editor
+  - Scripting
+  - UI
+- `RHI` 集成测试使用统一基准图做 golden-image 对比
+- `XCUI` 当前也有独立的 unit / integration 验证链路
+
+## 当前实现范围
+
+- 当前正式编辑器为基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
+- 当前 `RHI` 后端为 `D3D12`、`OpenGL`、`Vulkan`
+- 当前项目资产工作流已经接入 `AssetDatabase + Artifact + Library`
+- 当前 `Mono C#` 脚本程序集与运行时链路已经接入
+- 当前 `XCUI` 新编辑器路线仍在继续实现中
+
+## 快速开始
+
+推荐环境：
 
 - Windows 10/11
 - Visual Studio 2022 / MSVC v143
 - CMake 3.15+
 - Vulkan SDK
 - .NET SDK
-- Git LFS
 
-脚本运行时启用时，还需要：
-
-- 可用的 Mono 依赖，默认路径来自 `参考/Fermion/Fermion/external/mono`
-
-补充说明：
-
-- 当前根 CMake 配置里，`Vulkan SDK` 仍是硬依赖。
-- NanoVDB 头文件是可选能力，仅影响 `.nvdb` 体积资源支持。
-- 如果仓库里的大资源依赖 Git LFS，请先执行 `git lfs pull`。
-
-## 快速开始
-
-### 1. 配置
+配置工程：
 
 ```powershell
 cmake -S . -B build -A x64
 ```
 
-如果本地暂时没有 Mono 依赖，可以先关闭脚本运行时：
+如果当前不需要 Mono 脚本运行时：
 
 ```powershell
 cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
 ```
 
-### 2. 构建当前编辑器
+构建当前正式编辑器：
 
 ```powershell
 cmake --build build --config Debug --target XCEditor
 ```
 
-编辑器产物路径：
-
-- `editor/bin/Debug/XCEngine.exe`
-
-### 3. 运行编辑器
+运行：
 
 ```powershell
 .\editor\bin\Debug\XCEngine.exe
 ```
 
-显式指定工程目录：
-
-```powershell
-.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\Project
-```
-
-### 4. 构建项目脚本程序集
-
-如果你要验证 `ScriptComponent`、脚本类发现或 Inspector 字段编辑，先构建：
+如需构建项目脚本程序集：
 
 ```powershell
 cmake --build build --config Debug --target xcengine_project_managed_assemblies
 ```
 
-### 5. 可选构建 XCUI 新编辑器
+如需构建 XCUI 新编辑器宿主：
 
 ```powershell
 cmake --build build --config Debug --target XCUIEditorApp
 ```
 
-产物路径通常为：
-
-- `new_editor/bin/Debug/XCUIEditor.exe`
-
-## 测试
-
-列出测试：
+## 测试入口
 
 ```powershell
 ctest --test-dir build -N -C Debug
-```
-
-运行测试：
-
-```powershell
 ctest --test-dir build -C Debug --output-on-failure
 ```
 
@@ -128,24 +184,15 @@ cmake --build build --config Debug --target editor_tests
 cmake --build build --config Debug --target rendering_all_tests
 cmake --build build --config Debug --target rhi_all_tests
 cmake --build build --config Debug --target scripting_tests
+cmake --build build --config Debug --target core_ui_all_tests
+cmake --build build --config Debug --target editor_ui_all_tests
+cmake --build build --config Debug --target runtime_ui_all_tests
 ```
 
-更细的测试组织与约定见 [tests/TEST_SPEC.md](tests/TEST_SPEC.md)。
-
 ## 文档入口
 
-- 编辑器说明：[editor/README.md](editor/README.md)
-- API 文档入口：[docs/api/main.md](docs/api/main.md)
-- 架构蓝图：[docs/blueprint.md](docs/blueprint.md)
-- Editor 架构说明：[docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md)
-- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)
-- 协作约定：[AGENT.md](AGENT.md)
-
-## 当前状态
-
-`XCEngine` 仍处于高频迭代阶段，但当前仓库已经不是“零散原型集合”，而是一个以编辑器工作流为中心持续收口的引擎工作区。接口、目录和构建细节仍可能调整，但主线方向已经比较明确：
-
-- 稳定 `RHI / Rendering / Asset Pipeline / Editor` 主链。
-- 继续推进 `Mono Scripting` 与项目脚本工作流。
-- 推进 `XCUI` 新编辑器主线从组件库走向完整宿主。
-
+- `docs/api/main.md`
+- `editor/README.md`
+- `tests/TEST_SPEC.md`
+- `docs/plan/Editor架构说明.md`
+- `docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md`

docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md

@@ -33,8 +33,8 @@
 
 ## 当前调用链
 
-- `XCUIDemoPanel::Render()` 当前每帧都会 `BeginFrame() -> Submit(drawData) -> EndFrame(ImGui::GetWindowDrawList())`。
 - `tests/Editor/test_xcui_imgui_transition_backend.cpp` 当前直接验证了 pending state 重置和 flush 后 `ImDrawList` 顶点 / 命令缓冲被写入。
+- 当前代码树里已经没有 `editor/src/panels/XCUIDemoPanel.h/.cpp`；旧版 demo panel 文档仅作为历史迁移锚点保留，不再代表真实 source-backed 调用链。
 
 ## 当前实现边界
 
@@ -46,4 +46,5 @@
 
 - [XCUIBackend](../XCUIBackend.md)
 - [DrawData](../../../UI/DrawData/DrawData.md)
+- [XCUIDemoRuntime](../XCUIDemoRuntime/XCUIDemoRuntime.md)
 - [XCUIDemoPanel](../../panels/XCUIDemoPanel/XCUIDemoPanel.md)

docs/api/XCEngine/Editor/XCUIBackend/XCUIBackend.md

@@ -15,7 +15,7 @@
 
 ## 当前定位
 
-- `ImGuiTransitionBackend` 已经接上真实测试和 demo 面板，是当前过渡期可运行的桥接器。
+- `ImGuiTransitionBackend` 是当前唯一 source-backed、可直接落到 Dear ImGui `ImDrawList` 的 XCUI 过渡桥接器；当前代码树里已经没有 `XCUIDemoPanel` 这类 demo 面板调用链。
 - `XCUIDemoRuntime` 目前只有头文件声明，还没有 `.cpp` 和真实调用链，更像后续 demo runtime 的占位入口。
 
 ## 相关文档

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialState/MaterialInspectorMaterialState.md

@@ -0,0 +1,62 @@
+# MaterialInspectorMaterialState
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `state structs`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialState.h`
+
+**描述**: Material Inspector 的本地编辑状态模型，集中保存标签、keyword、属性、render-state 覆盖和加载/dirty/error 标志。
+
+## 概述
+
+`MaterialInspectorMaterialState.h` 不是一个 panel，而是 `InspectorPanel` 中材质资产编辑流程使用的状态容器集合。当前主要包括：
+
+- `MaterialTagEditRow`
+  - 一行 tag 名/值编辑缓存。
+- `MaterialKeywordState`
+  - 单个 shader keyword 的值和是否需要序列化。
+- `MaterialPropertyState`
+  - 单个材质属性的编辑态，覆盖 float/int/bool/texture 等值。
+- `MaterialAssetState`
+  - 整个材质资产当前在 Inspector 中的编辑快照。
+
+## 当前状态内容
+
+`MaterialAssetState` 当前收口了：
+
+- 资产路径、全路径和显示名
+- `shaderPath` 文本缓冲
+- `renderQueue`
+- `renderState` 与 `hasRenderStateOverride`
+- `tags`
+- `keywords`
+- `properties`
+- `errorMessage`
+- `dirty`
+- `loaded`
+
+这说明 Inspector 当前并不是直接把 `Material` 运行时对象原地当作 UI 状态使用，而是维护一份偏 authoring/editor 语义的独立快照。
+
+## Reset 语义
+
+`MaterialAssetState::Reset()` 当前会：
+
+- 清空路径、名称和错误信息
+- 把 `shaderPath` 缓冲归零
+- 把 `renderQueue` 还原到 `Geometry`
+- 清空 `renderState` override 标志和内容
+- 清空 tags / keywords / properties
+- 把 `dirty` 与 `loaded` 复位为 `false`
+
+## 当前使用位置
+
+- `editor/src/panels/InspectorPanel.h`
+- `editor/src/panels/InspectorPanel.cpp`
+- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md) 会基于这份状态做同步与序列化
+
+## 相关文档
+
+- [panels](../panels.md)
+- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
+- [Material](../../../Resources/Material/Material/Material.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/ApplyMaterialAuthoringPresenceToState.md

@@ -0,0 +1,23 @@
+# ApplyMaterialAuthoringPresenceToState
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free function`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: 根据材质源文本里实际出现的 `keywords`、`properties`、`textures` 与 `renderState` 字段，回填 `MaterialAssetState` 的 authored/serialized 标记。
+
+## 当前行为
+
+- 会先解析 source text 中是否存在 `renderState`
+- 普通属性从 `properties` 对象取键集合
+- texture/cubemap 属性从 `textures` 对象取键集合
+- keyword 从 `keywords` 数组取值集合
+- 最终把这些 presence 信息写回 `state.keywords` 与 `state.properties`
+
+## 相关文档
+
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+- [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/BuildMaterialAssetFileText.md

@@ -0,0 +1,30 @@
+# BuildMaterialAssetFileText
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free function`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: 把 `MaterialAssetState` 编码成最终材质资产 JSON 文本，并省略未序列化的默认项。
+
+## 当前行为
+
+- 会写出 `shader` 与 `renderQueue`
+- 非空 `tags` 会编码成对象
+- 只输出 `serialized == true` 的 keyword
+- 只输出 `serialized == true` 的普通属性与 texture 属性
+- `hasRenderStateOverride == true` 时才写出 `renderState`
+- 最终返回带换行的完整 JSON 字符串
+
+## 测试
+
+- `tests/Editor/test_material_inspector_material_state_io.cpp` 覆盖：
+  - 省略默认值与未序列化条目
+  - 写出 texture 覆盖
+  - 写出 render-state 覆盖
+
+## 相关文档
+
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/CollectMaterialPropertyStates.md

@@ -0,0 +1,22 @@
+# CollectMaterialPropertyStates
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free function`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: 从运行时 `Material` 收集 Inspector 可编辑的 `MaterialPropertyState` 列表，并按 shader schema 或名字排序。
+
+## 当前行为
+
+- 先读取 `Material::GetProperties()`
+- 若材质带有效 shader schema，则优先按 shader property 顺序排序
+- 若没有 schema，则退回名字排序
+- texture/cubemap 属性会额外尝试解析当前 texture binding 路径
+
+## 相关文档
+
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+- [Material](../../../Resources/Material/Material/Material.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/IsTextureMaterialPropertyType.md

@@ -0,0 +1,20 @@
+# IsTextureMaterialPropertyType
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free function`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: 判断给定 `MaterialPropertyType` 是否属于 texture 或 cubemap 一类需要走 texture authoring 分支的属性。
+
+## 当前行为
+
+- 对 `Texture` 和 `Cubemap` 返回 `true`
+- 其它属性类型返回 `false`
+- `ApplyMaterialAuthoringPresenceToState(...)` 与 `BuildMaterialAssetFileText(...)` 会用它区分 `textures` 和普通 `properties`
+
+## 相关文档
+
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md

@@ -0,0 +1,69 @@
+# MaterialInspectorMaterialStateIO
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free functions`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: Material Inspector 状态与 shader/material/source text 之间的同步 helper，负责属性快照收集、schema 对齐、authoring presence 标记和材质文件文本生成。
+
+## 概述
+
+`MaterialInspectorMaterialStateIO` 把 Material Inspector 的几条关键数据流集中到一起：
+
+1. 从运行时 `Material` 收集可编辑属性状态
+2. 按 shader schema 把现有状态重排、补齐或丢弃
+3. 根据 source text 标记哪些 keyword / property / texture 真正来自作者输入
+4. 把编辑状态重新编码成材质资产文本
+
+## 公开函数
+
+| 函数 | 说明 |
+|------|------|
+| [IsTextureMaterialPropertyType](IsTextureMaterialPropertyType.md) | 判断属性是否属于 texture/cubemap。 |
+| [CollectMaterialPropertyStates](CollectMaterialPropertyStates.md) | 从 `Material` 收集并排序属性编辑状态。 |
+| [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md) | 以 shader schema 为准同步 keyword 与 property 列表，同时尽量保留兼容旧值。 |
+| [ResetMaterialPropertyStateToShaderDefault](ResetMaterialPropertyStateToShaderDefault.md) | 把指定属性恢复到 shader 默认值，并清除 serialized 标志。 |
+| [ApplyMaterialAuthoringPresenceToState](ApplyMaterialAuthoringPresenceToState.md) | 从原始 source text 判断哪些 keyword / property / texture 真正出现在 authoring 文本里。 |
+| [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md) | 按当前状态生成材质资产 JSON 文本。 |
+
+## 当前实现行为
+
+- `CollectMaterialPropertyStates(...)` 会优先按 shader property 顺序排序；没有 shader schema 时才退回名字排序。
+- `SyncMaterialAssetStateWithShader(...)` 会保留“同名且类型兼容”的旧编辑值，同时丢弃陈旧属性。
+- shader pass 里声明的 keyword 会被整理成 `MaterialKeywordState`；之前已启用的 keyword 会尽量保留 `serialized` 状态。
+- `ApplyMaterialAuthoringPresenceToState(...)` 会区分：
+  - `properties`
+  - `textures`
+  - `keywords`
+  - `renderState`
+  这样 Inspector 可以知道某项是默认值，还是作者在材质文件里显式写过的覆盖。
+- `BuildMaterialAssetFileText(...)` 会省略未序列化的默认项，只写当前确实需要落盘的字段。
+- `BuildMaterialAssetFileText(...)` 同时负责把 `renderQueue`、tags、textures 和 `renderState` override 编码成最终 JSON。
+
+## 测试
+
+- `tests/Editor/test_material_inspector_material_state_io.cpp` 当前覆盖：
+  - 只标记 source authored 的 entries
+  - 按 shader schema 保留兼容 override 并丢弃陈旧属性
+  - 把声明过的 keyword 补成 disabled entries
+  - 恢复 shader 默认值
+  - 省略未序列化默认值
+  - 写出 texture 与 render-state 覆盖
+
+## 相关函数页面
+
+- [IsTextureMaterialPropertyType](IsTextureMaterialPropertyType.md)
+- [CollectMaterialPropertyStates](CollectMaterialPropertyStates.md)
+- [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md)
+- [ResetMaterialPropertyStateToShaderDefault](ResetMaterialPropertyStateToShaderDefault.md)
+- [ApplyMaterialAuthoringPresenceToState](ApplyMaterialAuthoringPresenceToState.md)
+- [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md)
+
+## 相关文档
+
+- [panels](../panels.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+- [Material](../../../Resources/Material/Material/Material.md)
+- [Shader](../../../Resources/Shader/Shader/Shader.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/ResetMaterialPropertyStateToShaderDefault.md

@@ -0,0 +1,21 @@
+# ResetMaterialPropertyStateToShaderDefault
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free function`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: 把指定材质属性恢复到 shader 默认值，并清除该属性的 `serialized` 覆盖标志。
+
+## 当前行为
+
+- 只有 shader 有效、属性名非空且目标属性存在时才可能成功
+- 会在 shader 默认属性列表中查找同名同类型的默认值
+- 成功后把属性值恢复为默认值，并把 `serialized` 置回 `false`
+
+## 相关文档
+
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+- [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md)

docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO/SyncMaterialAssetStateWithShader.md

@@ -0,0 +1,22 @@
+# SyncMaterialAssetStateWithShader
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `free function`
+
+**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+**描述**: 以 shader schema 为准重建 `MaterialAssetState` 的 property/keyword 列表，同时尽量保留兼容的已有编辑值。
+
+## 当前行为
+
+- shader 无效时会清空 `keywords` 与 `properties`
+- 会先生成 shader 默认属性状态，再把“同名且类型兼容”的旧值拷回去
+- 陈旧或已不在 schema 内的属性会被丢弃
+- keyword 列表按 shader pass 声明重建，并尽量保留旧的 `serialized` 状态
+
+## 相关文档
+
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
+- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+- [Shader](../../../Resources/Shader/Shader/Shader.md)

docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md

@@ -2,46 +2,22 @@
 
 **命名空间**: `XCEngine::Editor`
 
-**类型**: `class`
+**类型**: `historical page`
 
-**源文件**: `editor/src/panels/XCUIDemoPanel.h`
+**描述**: 历史保留页，记录旧版 editor 曾存在的 XCUI demo panel。当前 `editor/src/panels` 源树里已经没有对应 header，因此这页不再作为 source-backed 的 active panel 文档。
 
-**描述**: 一个编辑器工作区面板，用固定 demo draw list 演示“XCUI draw command -> ImGuiTransitionBackend -> ImDrawList”的过渡渲染链。
+## 当前状态
 
-## 概览
+- 旧文档引用的 `editor/src/panels/XCUIDemoPanel.h` 已不在当前代码树中。
+- 当前 `editor/src/panels` 更接近真实结构的新增 source-backed 页面是：
+  - [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+  - [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
+- 因此这页应被理解为历史迁移记录，而不是当前 editor 面板目录的 canonical 入口。
 
-`XCUIDemoPanel` 当前不是完整 XCUI runtime 的宿主，而是一个很轻的过渡演示面板。
+## 保留原因
 
-按 `XCUIDemoPanel.cpp` 的当前实现，它每帧会：
-
-1. 打开普通 `PanelWindowScope`
-2. 创建一个内容区 canvas
-3. 直接构造一份 `UIDrawData`
-4. 交给 `ImGuiTransitionBackend` 刷到当前 ImGui 窗口 draw list
-
-## 当前行为
-
-- 构造函数把面板标题固定成 `"XCUI Demo"`。
-- `Render()` 会在内容区尺寸太小时直接 `Dummy(...)` 后返回，不生成 draw data。
-- 内部 `BuildXCUIDemoDrawList(...)` 当前写死了：
-  - 背景卡片
-  - 文本标题
-  - primitive set / backend flow 说明
-  - 底部 footer 文案
-- 当前 demo 数据完全由 `XCUIDemoPanel.cpp` 内部拼装，不依赖 `XCUIDemoRuntime`。
-
-## 当前调用链
-
-- `editor/src/Core/EditorWorkspace.h` 当前会在工作区初始化时 `m_panels.Emplace<XCUIDemoPanel>()`。
-- `Render()` 最终通过成员 `m_backend` 调用：
-  - `BeginFrame()`
-  - `Submit(drawData)`
-  - `EndFrame(ImGui::GetWindowDrawList())`
-
-## 当前边界
-
-- 这是展示过渡后端的 demo panel，不是正式 editor XCUI shell。
-- 当前没有独立单测；它的关键桥接行为主要由 `tests/Editor/test_xcui_imgui_transition_backend.cpp` 间接覆盖。
+- 旧版文档树里它曾经用于说明 XCUI 到 ImGui 过渡渲染链的实验性 panel。
+- 当前保留该页，主要是避免旧链接直接失效，并为后续文档重构提供迁移锚点。
 
 ## 相关文档
 

docs/api/XCEngine/Editor/panels/panels.md

@@ -33,7 +33,8 @@
 - [SceneViewPanel](SceneViewPanel/SceneViewPanel.md)
 - [GameViewPanel](GameViewPanel/GameViewPanel.md)
 - [ViewportPanelContent](ViewportPanelContent/ViewportPanelContent.md)
-- [XCUIDemoPanel](XCUIDemoPanel/XCUIDemoPanel.md)
+- [MaterialInspectorMaterialState](MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
+- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
 
 ## 分层关系
 
@@ -63,11 +64,18 @@
 
 这几页则更多承担“把视口请求嵌入面板”的职责，真正的渲染仍由 `ViewportHostService` 管理。
 
-### XCUI 过渡演示面板
+### Inspector 材质状态 helper
 
-- `XCUIDemoPanel`
+- `MaterialInspectorMaterialState`
+- `MaterialInspectorMaterialStateIO`
 
-它当前不是正式 XCUI shell，而是把 `UIDrawData` 通过 `ImGuiTransitionBackend` 刷到 ImGui 的演示入口。
+这两页不是 panel 本体，而是挂在 `editor/src/panels` 目录下、服务 `InspectorPanel` 材质 authoring 流程的状态与 I/O helper。
+
+### 历史过渡页面
+
+- [XCUIDemoPanel](XCUIDemoPanel/XCUIDemoPanel.md)
+
+这是一页保留的历史文档；当前 `editor/src/panels` 源树里已经没有对应 header。
 
 ## 当前实现特点
 

docs/api/XCEngine/UI/DrawData/DrawData.md

@@ -43,7 +43,7 @@
 - `tests/Editor/test_xcui_draw_data.cpp` 当前直接验证 `UIDrawList` 的命令顺序、payload 保真和 `UIDrawData` 的多列表聚合计数。
 - `editor/src/XCUIBackend/ImGuiTransitionBackend.h` 当前是最直接的消费端，把 `PushClipRect` / `PopClipRect` / `Text` / `Image` 等命令映射到 ImGui。
 - `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前在 UI runtime 渲染阶段创建 draw list，并把 `drawListCount`、`commandCount` 统计写回运行结果。
-- `new_editor/src/Widgets/UIEditorPanelFrame.cpp`、`editor/src/panels/XCUIDemoPanel.cpp` 和多组 editor integration 测试当前直接构建 `UIDrawList`。
+- `new_editor/src/Shell/UIEditorPanelFrame.cpp` 和多组 editor integration 测试当前直接构建 `UIDrawList`；旧版 `editor/src/panels/XCUIDemoPanel.cpp` 已不在当前代码树中。
 
 ## 相关文档