@nebula-spatial/viewer 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -2,30 +2,86 @@
 
 All notable changes to this package are documented in this file.
 
-## 0.4.3
-
-### Added
-
-- 公开 `AssetPhysicsState` 类型，在 `AssetPreviewSnapshot` 和 `AssetSession` 中增加可选 `physics` 状态，并提供可选 `AssetLoaderContext.reportSessionState()` 通知；现有 loader 无需实现这些新增成员。
-- FBX 外置纹理接入本地文件包与异步 `resourceResolver`，增加受限 TGA/DDS 解码、命名 UV 集、二维纹理变换及受限颜色分层合成；具体边界见 `FBX-MATERIAL-CONVERSION.md`。
-
-### Improved
-
-- 按 FBX 材质 ID、连接顺序及模板恢复材质参数，完善标量贴图通道、事务回滚、取消和资源释放；不支持或近似转换通过警告及诊断报告暴露。
-- 改善 USD 的 OmniPBR/PxrSurface 材质适配、索引 UV、GeomSubset 材质绑定与粗糙度贴图通道，区分视觉适配警告和物理故障。
-- 完善 URDF、MJCF、USD 碰撞几何与位姿同步，保留源格式碰撞定义，补充关节与运动学预览支持及回归测试。
-
-### Fixed
-
-- 物理编译或初始化失败时，在能够独立构建视觉预览的前提下保留资产；运行中的 step/reset 失败停止仿真、保留最后显示的视觉位姿并刷新能力状态，不再自动重启物理。
-- 物理不可用时保留置灰播放按钮，悬停显示物理故障原因并拦截播放，不被材质警告覆盖。
-
-### Behavior notes
-
-- `phase === 'ready'` 仅表示资产预览就绪，不保证物理可运行。宿主应检查 `capabilities.canPlay`，并使用 `physics.status === 'unavailable'` 下的 `issue` 展示原因；未提供物理状态不等于 `not-authored`。
-- FBX 加载完成等待纹理解码和转换；缺失、歧义、鉴权或解码失败按加载失败处理，不保证旧资产继续以缺贴图模型成功加载。
-- 本版本不承诺任意 FBX/自定义着色器无损转换或 Blender 像素一致；USD/URDF/MJCF 物理降级不掩盖取消或视觉加载失败。
-
+## 0.4.5
+
+### Added
+
+- 新增 USD 视觉材质适配支持矩阵，明确 `UsdPreviewSurface`、MaterialX Standard Surface、OmniPBR 和 OmniGlass 的已转换、有界近似及未适配范围。
+- 支持常量介质透明、`presence`、`opacityThreshold`、受限透明纹理、MaterialX 薄壁透射，以及 OmniGlass 的覆盖率、反射颜色、粗糙度和受限法线适配。
+- 支持 USD 实例材质代理中的可确定常量 `UsdPreviewSurface` 输入恢复；保留循环、歧义、程序节点和体积光学语义的诊断。
+- 本地 Viewer 文件包入口支持 `root.usd`、`root.usda`、`root.usdc` 和 `root.usdz`，不受上传顺序影响。
+- 支持浏览器 Xacro 子集展开，包含宏、属性、参数、条件、块参数、嵌套 include 与 ROS package 映射；不支持的 Python/ROS 语义会显式失败。
+- 支持 URDF mimic 联动、可行控制范围、浏览器 COLLADA 网格、内嵌材质，以及本地文件包目录浏览和入口切换。
+
+### Improved
+
+- 统一 URDF/MJCF 视觉材质的线性颜色、粗糙度、金属度、法线、透明度、发光和纹理通道转换，并补充纹理资源释放与诊断。
+- URDF 审查工作台补充惯性姿态、惯量信息展开、连续关节控制范围、关节扫描和侧栏交互保持。
+- USD 视觉过滤按 `purpose` 隔离辅助几何；修正世界侧关节参考系、单位/up-axis 转换和显式惯性处理。
+- 物理模型取景忽略环境平面，避免地面或辅助几何主导模型缩放；补充跨格式材质审计页面及 Chromium 验证脚本。
+- 恢复分离 USD 视觉树到刚体的引用归属，支持显式引用 Prim 路径与 defaultPrim 引用，并对歧义、缺失和格式错误保留诊断。
+
+### Fixed
+
+- 玻璃透射材质按 USD `doubleSided` 声明应用单面/双面策略，避免共享材质被错误修改；纯金属材质不被误判为玻璃。
+- 修复 USD 透明度、覆盖率阈值、透明纹理、OmniGlass 法线与反射参数的边界转换；无法可靠表达的体积吸收、实体光程和复杂光学效果继续报告诊断，不生成猜测值。
+- 允许具有完整显式质量、质心、惯量和主轴数据的 USD 刚体缺少碰撞几何；仅有不完整惯性时仍明确失败，不虚构碰撞形状。
+- 修复 URDF 固定轴 RPY、惯性坐标旋转、mimic 初始姿态与 MuJoCo equality 约束；修复 USD 聚合视觉网格不随对应刚体更新的问题。
+
+### Behavior notes
+
+- 本版本继续使用有边界的 Three.js 材质映射，不执行 MDL 或完整 MaterialX 节点网络，也不承诺与 Blender、Omniverse 或路径追踪渲染逐像素一致。
+- `USD-VISUAL-MATERIAL-SUPPORT.md` 随 npm 包发布，记录具体支持矩阵；材质适配报告和诊断仍是判断单个资产结果的依据。
+- Xacro 是受限浏览器预处理子集，不执行外部 ROS 命令或环境访问；复杂 Python/YAML 语义应先使用官方工具展开。
+- 本次发布只更新 Viewer；`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
+
+## 0.4.4
+
+### Added
+
+- 新增 URDF 审查工作台：模型结构树、搜索过滤、关节滑块与范围扫描、属性面板、XML 只读定位及仅报告确定错误的检查。
+- 公开 `AssetPreview.getInspection()`、插件侧 `ctx.asset.$inspection()` 和 `UrdfInspection` 快照/命令契约；支持关闭内置 URDF UI 或完全 Headless 自定义。
+- 增加关节轴与正转方向、质心、完整惯性张量对应的等效惯量盒可视化；选中部件的质心与惯量使用区别色，仿真运行时标记跟随实时位姿。
+- 新增视角 gizmo、可拖拽调宽及折叠的侧栏、深浅主题切换和 URDF playground 入口。
+
+### Improved
+
+- URDF 默认静止运动学预览，仅显式播放时懒初始化动力学；暂停后支持部件选择与关节控制，再次播放从当前姿态继续，重置恢复初始运动学状态。
+- 支持按住 R 配合鼠标左右移动调节关节，根据相机朝向、关节世界轴及鼠标位置判断方向；不提供 Shift 精调。
+- 使用模型局部 BVH 加速拾取，浅蓝材质高亮选中部件；优先定位关联关节，点击空白取消选择，自动展开选中项祖先并保留结构树滚动位置。
+- 统一 SVG 场景工具栏、输入控件与主题样式，放开轨道相机俯仰范围；本地上传组件加载成功后收起为右上角悬浮按钮，支持手动展开和收起。
+
+### Fixed
+
+- 修复关节滑块连续拖动和重建 UI 导致的结构树滚动跳变；仿真运行时禁用关节控制，保留物理拖拽。
+- 加固物理懒初始化期间的取消与资源释放，初始化失败仍保留运动学审查。
+- 初始化及手动调整姿态后检查实际碰撞边界，必要时下移查看器默认地面，避免初始穿透导致弹飞；不移动模型或资产自带地面，运行时地面保持固定。
+- 重置恢复初始安全物理地面，URDF 返回初始预览地面，不保留临时下移高度；暂停保持当前地面。
+
+## 0.4.3
+
+### Added
+
+- 公开 `AssetPhysicsState` 类型，在 `AssetPreviewSnapshot` 和 `AssetSession` 中增加可选 `physics` 状态，并提供可选 `AssetLoaderContext.reportSessionState()` 通知；现有 loader 无需实现这些新增成员。
+- FBX 外置纹理接入本地文件包与异步 `resourceResolver`，增加受限 TGA/DDS 解码、命名 UV 集、二维纹理变换及受限颜色分层合成；具体边界见 `FBX-MATERIAL-CONVERSION.md`。
+
+### Improved
+
+- 按 FBX 材质 ID、连接顺序及模板恢复材质参数，完善标量贴图通道、事务回滚、取消和资源释放；不支持或近似转换通过警告及诊断报告暴露。
+- 改善 USD 的 OmniPBR/PxrSurface 材质适配、索引 UV、GeomSubset 材质绑定与粗糙度贴图通道，区分视觉适配警告和物理故障。
+- 完善 URDF、MJCF、USD 碰撞几何与位姿同步，保留源格式碰撞定义，补充关节与运动学预览支持及回归测试。
+
+### Fixed
+
+- 物理编译或初始化失败时，在能够独立构建视觉预览的前提下保留资产；运行中的 step/reset 失败停止仿真、保留最后显示的视觉位姿并刷新能力状态，不再自动重启物理。
+- 物理不可用时保留置灰播放按钮，悬停显示物理故障原因并拦截播放，不被材质警告覆盖。
+
+### Behavior notes
+
+- `phase === 'ready'` 仅表示资产预览就绪，不保证物理可运行。宿主应检查 `capabilities.canPlay`，并使用 `physics.status === 'unavailable'` 下的 `issue` 展示原因；未提供物理状态不等于 `not-authored`。
+- FBX 加载完成等待纹理解码和转换；缺失、歧义、鉴权或解码失败按加载失败处理，不保证旧资产继续以缺贴图模型成功加载。
+- 本版本不承诺任意 FBX/自定义着色器无损转换或 Blender 像素一致；USD/URDF/MJCF 物理降级不掩盖取消或视觉加载失败。
+
 ## 0.4.2
 
 ### Fixed

package/README.md

@@ -258,30 +258,30 @@ preview.reset();
 preview.play();
 ```
 
-### 公开物理状态与会话通知
-
-包入口导出 `AssetPhysicsState`，可通过 `preview.getSnapshot().physics` 或原有订阅回调读取：
-
-```ts
-import type { AssetPhysicsState } from '@nebula-spatial/viewer';
-
-const physics: AssetPhysicsState | null | undefined = preview.getSnapshot().physics;
-if (physics?.status === 'unavailable') {
-  console.warn(physics.issue.message);
-}
-```
-
-- `not-authored`：未声明驱动当前仿真的动力学定义，作为静态或运动学资产预览。
-- `ready`：物理已就绪；播放操作仍应检查 `snapshot.capabilities.canPlay`。
-- `unavailable`：物理准备或运行失败，`issue` 提供原因。
-- `null` 或未提供：会话未报告物理状态，不能等同于 `not-authored`。
-
-资产的 `phase === 'ready'` 与物理可用性相互独立。运行中的 step/reset 失败会停止仿真，
-保留视觉对象及最后显示的位姿，更新能力与物理状态，并上报非致命错误；不会自动重启物理。
-自定义 loader 可通过可选的 `AssetSession.physics` 提供状态，并在就绪后调用
-`context.reportSessionState?.()` 通知 Viewer 刷新 capabilities、physics 和 warning。
-现有 loader 不必实现这些可选成员；自定义 UI 应订阅状态变化，而不是仅以加载完成判断能否播放。
-
+### 公开物理状态与会话通知
+
+包入口导出 `AssetPhysicsState`，可通过 `preview.getSnapshot().physics` 或原有订阅回调读取：
+
+```ts
+import type { AssetPhysicsState } from '@nebula-spatial/viewer';
+
+const physics: AssetPhysicsState | null | undefined = preview.getSnapshot().physics;
+if (physics?.status === 'unavailable') {
+  console.warn(physics.issue.message);
+}
+```
+
+- `not-authored`：未声明驱动当前仿真的动力学定义，作为静态或运动学资产预览。
+- `ready`：物理已就绪；播放操作仍应检查 `snapshot.capabilities.canPlay`。
+- `unavailable`：物理准备或运行失败，`issue` 提供原因。
+- `null` 或未提供：会话未报告物理状态，不能等同于 `not-authored`。
+
+资产的 `phase === 'ready'` 与物理可用性相互独立。运行中的 step/reset 失败会停止仿真，
+保留视觉对象及最后显示的位姿，更新能力与物理状态，并上报非致命错误；不会自动重启物理。
+自定义 loader 可通过可选的 `AssetSession.physics` 提供状态，并在就绪后调用
+`context.reportSessionState?.()` 通知 Viewer 刷新 capabilities、physics 和 warning。
+现有 loader 不必实现这些可选成员；自定义 UI 应订阅状态变化，而不是仅以加载完成判断能否播放。
+
 ### 远端仿真资产与格式识别边界
 
 省略 `format` 与 `format: 'auto'` 等价：只按明确扩展名或已注册 loader 的明确 `match()` 结果识别。
@@ -328,11 +328,32 @@ Viewer 自动识别所有资产形态，也不能把本地样本验证等同于
 
 ### USD 视觉材质适配与诊断
 
+OmniPBR 是 NVIDIA 的 MDL 材质模板，不等于 OpenUSD 的 UsdPreviewSurface。
+本查看器做有边界的 Three.js 参数/纹理映射，不执行 MDL，也不承诺完整等价。
+支持独立灰度 roughness/metallic 贴图，以及 ORM 的明确粗糙度/金属度通道；
+非灰度独立图不猜测 mono 规则。0–1 influence 按
+`constant * (1 - influence) + texture * influence` 混合原始数据像素，输出 8 位标量纹理，
+因此存在量化误差；未声明的粗糙度/金属度常量采用 OmniPBR 默认值 0.5/0。
+支持 `diffuse_tint` 和已有 `normalmap_texture`，默认法线强度为 1，按默认 DirectX V
+切线翻转处理；明确的 U/V 翻转参数优先。仍限定单位 UV 变换和数据纹理色彩空间。
+Opacity 遵守 enable 开关、常量阈值与贴图 alpha/average/maximum 采样（luminance 暂不支持），
+属于 cutout/覆盖率近似，不是玻璃透射。自发光遵守开关及强度，但仍报告辐射度等价性限制。
+非默认 specular_level、AO-to-diffuse、复杂 UV/投影、细节法线、自发光贴图组合与 OmniGlass
+仍有未支持部分；具体以逐材质报告为准，不能用“无报错”代替原渲染器画面对照。
+
+完整的 USD 材质支持矩阵与限制见 [USD-VISUAL-MATERIAL-SUPPORT.md](./USD-VISUAL-MATERIAL-SUPPORT.md)。
+
 USD 仿真继续以 OpenUSD Stage 和 USD Physics 为语义权威；视觉适配层只在
 `@openusd-wasm/three-loader` 完成标准几何、材质绑定、`UsdPreviewSurface`、受支持纹理和
 PBR 参数转换之后查漏补缺。它不会重建 loader 已正确生成的材质，也不会修改刚体、关节、碰撞体
 或 MuJoCo 绑定。
 
+USD 视觉引用归属：当视觉几何位于独立聚合树、刚体树中的 `Visual` Prim 通过 USD reference 指向该聚合树时，Viewer 会按引用的目标 Prim 路径将网格绑定到对应刚体，使其跟随 MuJoCo 运行时位姿。支持显式引用 Prim 路径及 defaultPrim 引用；多个刚体映射到同一视觉尾路径、引用元数据缺失或格式无法解析时不会猜测归属，而是保留视觉诊断。
+实例化材质：当 Loader 遗漏实例代理中的 Shader 时，适配层沿 `outputs:surface` 读取
+标准 `UsdPreviewSurface`，解析其输入到材质实例常量的连接，再复用 Loader 的材质转换。
+当前只补齐可确定解析的常量网络；缺失、循环、歧义连接或纹理/程序节点网络保留原诊断。
+不会解除 Stage 实例化、修改 USD 文件或改变物理定义。
+
 视觉拓扑补齐遵循原始 USD 数据，不进行猜测：
 
 - 在三角面、四边形或多边形的三角化面角与 Loader 输出可逐项核对时，按 `primvars:st:indices`
@@ -611,6 +632,43 @@ CAD 类型改为 `ViewerCadUiOptions`、`ViewerCadUiParts`、`ViewerCadUiKeyboar
 - [ ] Draco、MuJoCo、OpenUSD runtime URL 由宿主明确配置并已在真实部署路径验证。
 - [ ] 远端资产的 CORS、MIME、鉴权、相对资源路径以及 USD 的跨源隔离已端到端验证。
 
+## URDF Viewer 审查工作台（0.4.4）
+
+URDF 默认打开为静止的**运动学预览**：关节控制由确定性 FK 驱动，不会自动加载或启动 MuJoCo。只有用户调用 `preview.play()`、`ctx.commands.play()` 或点击内置“动力学仿真”播放按钮后，Viewer 才按需初始化现有物理运行时。
+
+内置工作台包括可折叠结构树、搜索/过滤、关节滑块与范围扫描、Collision/关节轴与正方向/质心/惯量覆盖层、属性面板、XML 只读定位，以及只报告确定错误的严格检查。可通过 `ui.urdf: false` 关闭内置界面，或通过 `ui.preset: 'none'` 完全 Headless 使用。
+
+### 交互与仿真状态
+
+- 默认不打开全部关节轴；选中部件时显示关联关节轴，启用关节轴开关后显示全部关节轴。
+- 可用滑块或按住 **R + 鼠标左右移动**调节选中可动关节；方向结合相机朝向、关节世界轴及鼠标位置计算，未启用 Shift 精调。
+- 仿真运行时关节控制与部件选择只读，但保留物理拖拽；关节轴、质心、惯量可以开关并跟随实时姿态。
+- 暂停后恢复点选与关节调整，再次播放使用当前姿态；重置恢复初始运动学状态。选中关节时，其 child link 的质心和惯量使用区别色。
+- 场景工具栏提供播放/暂停、重置、地面显隐、适应视图及主题切换；侧栏支持调宽和折叠，结构树选择保留滚动位置。
+
+### 默认地面的防穿透与重置
+
+默认物理地面在初始化及手动调整姿态后按编译后的碰撞边界检查；必要时只下移查看器自动添加的地面，不移动模型或修改资产自带地面。运行过程中地面保持固定，可视地面跟随物理地面高度。
+
+暂停保留当前地面；重置恢复初始化时的安全物理高度，URDF 返回初始预览地面。再次启动仍检查穿透。此机制不修复资产内部碰撞体互相穿透等其他物理问题。
+
+### 自定义审查界面
+
+```ts
+const preview = await viewer.openAsset(source, { format: 'urdf' });
+const inspection = preview.getInspection();
+
+if (inspection?.kind === 'urdf') {
+  const stop = inspection.subscribe(snapshot => renderRobotReview(snapshot));
+  inspection.select('joint:elbow');
+  inspection.setJointValue('elbow', 0.5);
+  inspection.setOverlay('jointAxis', true);
+  // preview.play(); // 明确调用后才初始化并启动动力学仿真
+  stop();
+}
+```
+
+插件使用 `ctx.asset.$inspection()` 读取同一审查会话，通过 `ctx.commands.play/pause()` 控制动力学。完整交互、架构、状态所有权、严格规则和扩展方式见 [`docs/urdf-reviewer-interaction-design.md`](../../docs/urdf-reviewer-interaction-design.md)。
 ## 通用 Three.js 对象
 
 Viewer 同样可管理非 CAD 的 `Object3D`：
@@ -674,6 +732,8 @@ npm run build --workspace @nebula-spatial/viewer
 
 ### USD / Isaac Sim 物理映射边界
 
+USD 转换生成的 MuJoCo 碰撞几何使用 `margin="0"`，不额外膨胀接触表面，以保留资产预留的窄缝。该策略不关闭碰撞，也不修改拖拽力。PhysX `contactOffset/restOffset` 不直接等价于 MuJoCo `margin/gap`，目前不做一比一映射；不声明跨引擎接触行为完全一致。
+
 查看器遵循 OpenUSD `UsdPhysics` 的基础刚体语义：`PhysicsCollisionAPI` 单独应用表示静态碰撞体，和 `PhysicsRigidBodyAPI` 同时应用表示动态刚体；同一刚体下可以包含多个碰撞形状。场景单位、Z/Y-up、Cube/Sphere/Cylinder/Capsule/Mesh 碰撞体、静态碰撞体、质量/密度、自由刚体初始速度和基础关节会在可验证的范围内映射到 MuJoCo。
 
 Isaac Sim/PhysX 专有的碰撞近似、碰撞组、simulation owner、求解器/CCD、接触模型和逐对关节碰撞过滤不保证等价转换。无法可靠映射的属性会写入 `diagnostics.droppedFeatures`，不会伪造一个看似正确的 MJCF 结果；若基础几何或刚体语义无法建立，则按 USD 物理降级策略处理。
@@ -697,11 +757,47 @@ ShininessExponent 按 Blender 导入约定直接映射粗糙度，透明通道
 FBX 外置纹理支持入口相对路径、本地文件包和异步 resourceResolver。仅在文件名唯一时
 容许扁平文件选择；重名歧义、缺失、鉴权/解码错误按加载失败处理，不静默忽略。
 ready 等待纹理解码及转换完成；中断和关闭清理源纹理、转换纹理与临时 object URL。
-支持命名 UV 集到 uv/uv1/uv2/uv3 的绑定及二维平移、缩放；W 轴旋转采用显式兼容规则并报告近似。
-颜色分层仅支持同尺寸、同 UV/采样配置及不透明底层下的受限合成，不支持任意分层或自定义 shader。
-近似与不支持项通过 AssetPreviewSnapshot.warning 和 material.userData.fbxConversionReport 报告。
-除浏览器可解码图像外，已接入受限 TGA/DDS 专用解码；不支持任意 DDS 编码或内嵌 DDS。
+支持命名 UV 集到 uv/uv1/uv2/uv3 的绑定及二维平移、缩放；W 轴旋转采用显式兼容规则并报告近似。
+颜色分层仅支持同尺寸、同 UV/采样配置及不透明底层下的受限合成，不支持任意分层或自定义 shader。
+近似与不支持项通过 AssetPreviewSnapshot.warning 和 material.userData.fbxConversionReport 报告。
+除浏览器可解码图像外，已接入受限 TGA/DDS 专用解码；不支持任意 DDS 编码或内嵌 DDS。
 详细支持范围、资源所有权及验证边界见 [FBX-MATERIAL-CONVERSION.md](./FBX-MATERIAL-CONVERSION.md)。
 
 材质参数对齐不等于截图逐像素对齐：还需相同 HDR、环境旋转、曝光、视角与色彩管理。
 Viewer 不会为了匹配单个 Blender 截图而覆盖全局曝光或灯光。
+
+## Xacro preview
+
+`.xacro` and `.urdf.xacro` use `xacro-parser@0.3.11` as an optional, lazily loaded
+preprocessing stage before the existing URDF kinematic review. They do not autoplay.
+Upload the entire description directory, not only its entry XML, or provide a
+`baseUrl` / `resourceResolver` for includes and meshes.
+
+```ts
+const preview = viewer.openAsset({ kind: 'files', entry: 'robot/urdf/main.urdf.xacro', files }, {
+  xacro: {
+    arguments: { prefix: 'arm_', size: 0.2 },
+    packages: { robot_description: 'robot' },
+  },
+});
+await preview.ready;
+```
+
+`xacro.packages` maps ROS package names to directories relative to the uploaded
+file package or `baseUrl`. Local `package.xml` files supply mappings automatically;
+explicit mappings override discovery. Ambiguous package names fail. External ROS
+commands and environment access are not executed. Mesh/texture `package://` paths
+use the same mapping. Resource requests retain the existing resolver and abort signal.
+
+Supported subset: macros, properties, arguments/defaults, numeric expressions,
+if/unless, block parameters and nested includes. Python expressions are **not**
+fully compatible: `xacro.load_yaml`, include namespaces, dynamic `xacro:call`, and
+`param:=^|default` are unsupported. Expansion errors are fatal `E_XACRO_EXPAND`
+errors; there is no fallback that renders incomplete raw Xacro as URDF. Inputs are
+limited to 4 MiB each and 128 include reads, but this is not a sandbox or a complete
+CPU/memory limit for untrusted macro expansion.
+
+Review source ranges are labeled `(expanded URDF)`; they do not map back to the
+original macro definition. The current Universal Robots ROS2 description uses
+Python/YAML expressions and is not covered by this browser subset. For full ROS
+compatibility, expand with the official Xacro tool first and open the resulting URDF.

package/USD-VISUAL-MATERIAL-SUPPORT.md

@@ -0,0 +1,51 @@
+# USD 视觉材质适配矩阵
+
+> 更新日期：2026-09-22
+>
+> 本文描述浏览器 Viewer 当前对 USD 材质的**语义转换与视觉近似边界**，不是渲染器等价性声明。没有资产资源、没有材质连接或缺少可靠光学数据时，适配层不会生成替代内容。
+
+## 判定等级
+
+| 等级 | 含义 |
+|---|---|
+| 原生保留 | Loader 已能正确表达，适配层不重建或只做诊断清理。 |
+| 已转换 | 源参数和资源可以确定映射到 Three.js 材质。 |
+| 有界近似 | 可以表达主要视觉意图，但与源渲染器、MDL、MaterialX 或路径追踪不保证等价。 |
+| 未适配 | 当前没有可靠的映射；保留 Loader 输出并报告限制。 |
+| 不处理 | 需要缺失资源、未知节点语义或无法从资产确定的数据；禁止猜测。 |
+
+## 当前支持矩阵
+
+| 材质体系 / 功能 | 当前视觉结果 | 已覆盖内容 | 尚未适配或有边界的内容 | 处理原则 |
+|---|---|---|---|---|
+| `UsdPreviewSurface` 不透明 | 原生保留 | 常量颜色、粗糙度、金属度等由 Loader 提供 | 复杂节点网络依赖 Loader 能力 | 不重复转换已正确支持的材质 |
+| `UsdPreviewSurface` 常量介质透明 | 有界近似 | `opacityMode=transparent`、常量 IOR、`MeshPhysicalMaterial.transmission`、反射保留 | Three.js 与 PreviewSurface 的透射瓣、粗糙度和多层透射不完全等价 | 不把所有 opacity 机械转换为玻璃 |
+| `UsdPreviewSurface` `presence` | 已转换（常量） | 整体覆盖率、零值消失、中间值透明 | 纹理驱动和复杂连接 | 不与玻璃 transmission 混淆 |
+| `UsdPreviewSurface` `opacityThreshold` | 已转换（受限） | 常量小于阈值裁切，大于等于阈值保留 | 复杂纹理过滤、跨渲染器阈值边缘差异 | 不将裁切误作连续半透明 |
+| `UsdPreviewSurface` 透明纹理 | 已转换（受限） | raw、UV0、明确通道、scale/bias、支持的 wrap 模式 | 非 raw 色彩空间、复杂 UV、多节点合成 | 只重排已有像素，不生成纹理 |
+| `UsdPreviewSurface` 纯金属透明 | 有界近似 | 保留纯金属镜面响应，不转成玻璃 | 半金属、复杂 specular workflow | 金属和玻璃分支严格区分 |
+| MaterialX Standard Surface 薄壁透射 | 有界近似 | 常量 opacity 与 transmission 分离；Loader 透射结果保留 | 完整 MaterialX 节点执行、复杂组合和多层透射 | 不把 transmission_depth 当几何壁厚 |
+| MaterialX 实体透射 | 未适配关键效果 | 保留可表达的表面透射 | 体积颜色、吸收、内部光程 | 缺少可靠光程时不猜测 thickness |
+| OmniPBR 基础颜色 | 已转换 / 有界近似 | 常量颜色、已有 diffuse texture | 复杂 UV、程序化节点 | 只使用资产已有资源 |
+| OmniPBR ORM | 已转换（受限） | raw ORM 的粗糙度 G、金属度 B、影响权重 | 非 raw、复杂 UV、无效资源 | 通道重排和线性混合需可确定 |
+| OmniPBR AO | 有界近似 | 有效 AO 纹理、raw、支持 UV、`aoMapIntensity` | OmniPBR AO 对漫反射的精确调制；`aoMap` 是 Three.js 间接光近似 | `ao_to_diffuse=0` 不报有效缺失 |
+| OmniPBR 法线 / bump | 有界近似 | 已有法线纹理、强度和切线方向的受限映射 | 复杂节点、未知切线约定 | 缺失法线不生成替代 |
+| OmniGlass 常量薄壁 | 有界近似 | IOR、粗糙度、表面透射、覆盖率、反射颜色、受限法线纹理 | MDL 完整执行、复杂纹理和多层光学 | 保留 DoubleSide 策略边界，不改普通材质 |
+| OmniGlass `cutout_opacity` | 已转换（常量） | `enable_opacity`、常量覆盖率、阈值边界 | opacity 纹理和复杂连接 | 覆盖率不当作 transmission |
+| OmniGlass 实体玻璃 | 未适配关键效果 | 表面透射和可表达的 IOR/粗糙度 | 体积吸收、`depth` 对应的光程、实体颜色 | 不把 `depth` 当 thickness 或 attenuationDistance |
+| 玻璃 DoubleSide 策略 | 已转换（有条件） | 透射材质：显式 `doubleSided=false` 用 FrontSide；true 或未声明用 DoubleSide | 未能读取源属性时不猜测 | 其他材质保持原有 side |
+
+## 当前明确不伪造的内容
+
+- 缺失或无法解码的纹理、法线、粗糙度、AO 和 ORM 资源；
+- 未知 MDL / MaterialX 节点的输出；
+- OmniGlass / MaterialX 的实体内部光程、体积吸收和真实壁厚；
+- 不能从几何确定的 `thickness`、`attenuationDistance` 或吸收距离；
+- 通过修改背景、排序、颜色或强制双面制造“看起来更像”的资产特例；
+- 把 Storm、Three.js 实时结果或 Loader 成功解析当作 Cycles、RTX 或 Karma 的最终真值。
+
+## 验证范围
+
+当前回归覆盖常量透明、`presence`、阈值裁切、纯金属透明、MaterialX 薄壁/实体边界、OmniPBR ORM/AO 受限路径、OmniGlass 常量参数、法线纹理和玻璃单双面策略。
+
+测试通过只表示代码路径和诊断契约符合预期，不表示所有 USD 材质与源渲染器逐像素一致。对于复杂资产，仍需结合源材质终端、资源清单和目标渲染器单独判断。

package/dist/assets/types.d.ts

@@ -1,8 +1,9 @@
+import type { AssetInspection } from '../inspection/types';
 import type { Object3D, WebGLRenderer, Scene, Camera, Box3, ColorRepresentation } from 'three';
 import type { CadLoadSource, CadOpenOptions } from '../cad/types';
 import type { ViewerViewMode } from '../types';
 export type AssetPreviewKind = 'cad' | 'model' | 'simulation';
-export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'fbx' | 'urdf' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
+export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'fbx' | 'urdf' | 'xacro' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
 export type AssetFormat = BuiltinAssetFormat | (string & {});
 export interface AssetFileEntry {
     readonly path: string;
@@ -25,6 +26,12 @@ export interface ViewerAssetOptions {
     readonly mujocoBaseUrl?: string;
 }
 export interface OpenAssetOptions {
+    /** Browser Xacro subset; unsupported Python/ROS features fail explicitly. */
+    readonly xacro?: {
+        readonly arguments?: Readonly<Record<string, string | number | boolean>>;
+        /** ROS package name -> directory relative to the asset package/baseUrl. */
+        readonly packages?: Readonly<Record<string, string>>;
+    };
     readonly simulationTheme?: 'dark' | 'light';
     readonly format?: AssetFormat | 'auto';
     readonly filename?: string;
@@ -88,7 +95,7 @@ export interface AssetWarningSnapshot {
 }
 /** Physics availability is independent of the visual asset's ready phase. */
 export type AssetPhysicsState = {
-    readonly status: 'not-authored' | 'ready';
+    readonly status: 'not-authored' | 'available' | 'initializing' | 'ready';
 } | {
     readonly status: 'unavailable';
     readonly issue: AssetWarningSnapshot;
@@ -125,6 +132,7 @@ export interface AssetControlState {
     readonly upAxis: AssetUpAxis | null;
 }
 export interface AssetPreview {
+    getInspection(): AssetInspection | null;
     getPhysicsProperties(): Readonly<Record<string, unknown>> | null;
     /** USD visual report and diagnostics, including static assets. */
     getVisualDiagnostics?(): Readonly<Record<string, unknown>> | null;
@@ -196,6 +204,9 @@ export interface AssetLoaderContext {
     reportSessionState?(): void;
 }
 export interface AssetSession {
+    readonly autoPlay?: boolean;
+    readonly inspection?: AssetInspection | null;
+    isPlaying?(): boolean;
     setTheme?(theme: 'dark' | 'light'): void;
     beforeRender?(renderer: WebGLRenderer, scene: Scene, camera: Camera): (() => void) | void;
     getPhysicsProperties?(): Readonly<Record<string, unknown>> | null;