@chocozhang/three-model-render 1.0.3 → 1.0.5

package/dist/index.mjs

@@ -8,25 +8,35 @@ import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUti
 import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
 
 /**
- * 给子模型添加头顶标签（支持 Mesh 和 Group）- 优化版
+ * @file labelManager.ts
+ * @description
+ * Manages HTML labels attached to 3D objects. Efficiently updates label positions based on camera movement.
  *
- * ✨ 性能优化：
- * - 缓存包围盒，避免每帧重复计算
- * - 支持暂停/恢复更新
- * - 可配置更新间隔，降低 CPU 占用
- * - 只在可见时更新，隐藏时自动暂停
+ * @best-practice
+ * - Use `addChildModelLabels` to label parts of a loaded model.
+ * - Labels are HTML elements overlaid on the canvas.
+ * - Supports performance optimization via caching and visibility culling.
+ */
+/**
+ * Add overhead labels to child models (supports Mesh and Group)
+ *
+ * Features:
+ * - Caches bounding boxes to avoid repetitive calculation every frame
+ * - Supports pause/resume
+ * - Configurable update interval to reduce CPU usage
+ * - Automatically pauses when hidden
  *
- * @param camera THREE.Camera - 场景摄像机
- * @param renderer THREE.WebGLRenderer - 渲染器，用于屏幕尺寸
- * @param parentModel THREE.Object3D - FBX 根节点或 Group
- * @param modelLabelsMap Record<string,string> - 模型 name → 标签文字 映射表
- * @param options LabelOptions - 可选标签样式配置
- * @returns LabelManager - 包含 pause/resume/dispose 的管理接口
+ * @param camera THREE.Camera - Scene camera
+ * @param renderer THREE.WebGLRenderer - Renderer, used for screen size
+ * @param parentModel THREE.Object3D - FBX root node or Group
+ * @param modelLabelsMap Record<string,string> - Map of model name to label text
+ * @param options LabelOptions - Optional label style configuration
+ * @returns LabelManager - Management interface containing pause/resume/dispose
  */
 function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, options) {
-    // 防御性检查：确保 parentModel 已加载
+    // Defensive check: ensure parentModel is loaded
     if (!parentModel || typeof parentModel.traverse !== 'function') {
-        console.error('parentModel 无效，请确保 FBX 模型已加载完成');
+        console.error('parentModel invalid, please ensure the FBX model is loaded');
         return {
             pause: () => { },
             resume: () => { },
@@ -34,48 +44,47 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
             isRunning: () => false
         };
     }
-    // 配置项
-    const enableCache = (options === null || options === void 0 ? void 0 : options.enableCache) !== false;
-    const updateInterval = (options === null || options === void 0 ? void 0 : options.updateInterval) || 0;
-    // 创建标签容器，绝对定位，放在 body 中
+    // Configuration
+    const enableCache = options?.enableCache !== false;
+    const updateInterval = options?.updateInterval || 0;
+    // Create label container, absolute positioning, attached to body
     const container = document.createElement('div');
     container.style.position = 'absolute';
     container.style.top = '0';
     container.style.left = '0';
-    container.style.pointerEvents = 'none'; // 避免阻挡鼠标事件
+    container.style.pointerEvents = 'none'; // Avoid blocking mouse events
     container.style.zIndex = '1000';
     document.body.appendChild(container);
     const labels = [];
-    // 状态管理
+    // State management
     let rafId = null;
     let isPaused = false;
     let lastUpdateTime = 0;
-    // 遍历所有子模型
+    // Traverse all child models
     parentModel.traverse((child) => {
-        var _a;
-        // 只处理 Mesh 或 Group
+        // Only process Mesh or Group
         if ((child.isMesh || child.type === 'Group')) {
-            // 动态匹配 name，防止 undefined
-            const labelText = (_a = Object.entries(modelLabelsMap).find(([key]) => child.name.includes(key))) === null || _a === void 0 ? void 0 : _a[1];
+            // Dynamic matching of name to prevent undefined
+            const labelText = Object.entries(modelLabelsMap).find(([key]) => child.name.includes(key))?.[1];
             if (!labelText)
-                return; // 没有匹配标签则跳过
-            // 创建 DOM 标签
+                return; // Skip if no matching label
+            // Create DOM label
             const el = document.createElement('div');
             el.innerText = labelText;
-            // 样式直接在 JS 中定义，可通过 options 覆盖
+            // Styles defined in JS, can be overridden via options
             el.style.position = 'absolute';
-            el.style.color = (options === null || options === void 0 ? void 0 : options.color) || '#fff';
-            el.style.background = (options === null || options === void 0 ? void 0 : options.background) || 'rgba(0,0,0,0.6)';
-            el.style.padding = (options === null || options === void 0 ? void 0 : options.padding) || '4px 8px';
-            el.style.borderRadius = (options === null || options === void 0 ? void 0 : options.borderRadius) || '4px';
-            el.style.fontSize = (options === null || options === void 0 ? void 0 : options.fontSize) || '14px';
-            el.style.transform = 'translate(-50%, -100%)'; // 让标签在模型正上方
+            el.style.color = options?.color || '#fff';
+            el.style.background = options?.background || 'rgba(0,0,0,0.6)';
+            el.style.padding = options?.padding || '4px 8px';
+            el.style.borderRadius = options?.borderRadius || '4px';
+            el.style.fontSize = options?.fontSize || '14px';
+            el.style.transform = 'translate(-50%, -100%)'; // Position label directly above the model
             el.style.whiteSpace = 'nowrap';
             el.style.pointerEvents = 'none';
             el.style.transition = 'opacity 0.2s ease';
-            // 加入容器
+            // Append to container
             container.appendChild(el);
-            // 初始化缓存
+            // Initialize cache
             const cachedBox = new THREE.Box3().setFromObject(child);
             const center = new THREE.Vector3();
             cachedBox.getCenter(center);
@@ -90,7 +99,7 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         }
     });
     /**
-     * 更新缓存的包围盒（仅在模型变换时调用）
+     * Update cached bounding box (called only when model transforms)
      */
     const updateCache = (labelData) => {
         labelData.cachedBox.setFromObject(labelData.object);
@@ -100,18 +109,18 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         labelData.needsUpdate = false;
     };
     /**
-     * 获取对象顶部世界坐标（使用缓存）
+     * Get object top world coordinates (using cache)
      */
     const getObjectTopPosition = (labelData) => {
         if (enableCache) {
-            // 检查对象是否发生变换
+            // Check if object has transformed
             if (labelData.needsUpdate || labelData.object.matrixWorldNeedsUpdate) {
                 updateCache(labelData);
             }
             return labelData.cachedTopPos;
         }
         else {
-            // 不使用缓存，每次都重新计算
+            // Do not use cache, recalculate every time
             const box = new THREE.Box3().setFromObject(labelData.object);
             const center = new THREE.Vector3();
             box.getCenter(center);
@@ -119,15 +128,15 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         }
     };
     /**
-     * 更新标签位置函数
+     * Update label positions function
      */
     function updateLabels(timestamp = 0) {
-        // 检查是否暂停
+        // Check pause state
         if (isPaused) {
             rafId = null;
             return;
         }
-        // 检查更新间隔
+        // Check update interval
         if (updateInterval > 0 && timestamp - lastUpdateTime < updateInterval) {
             rafId = requestAnimationFrame(updateLabels);
             return;
@@ -137,22 +146,22 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         const height = renderer.domElement.clientHeight;
         labels.forEach((labelData) => {
             const { el } = labelData;
-            const pos = getObjectTopPosition(labelData); // 使用缓存的顶部坐标
-            pos.project(camera); // 转到屏幕坐标
-            const x = (pos.x * 0.5 + 0.5) * width; // 屏幕 X
-            const y = (-(pos.y * 0.5) + 0.5) * height; // 屏幕 Y
-            // 控制标签显示/隐藏（摄像机后方隐藏）
+            const pos = getObjectTopPosition(labelData); // Use cached top position
+            pos.project(camera); // Convert to screen coordinates
+            const x = (pos.x * 0.5 + 0.5) * width; // Screen X
+            const y = (-(pos.y * 0.5) + 0.5) * height; // Screen Y
+            // Control label visibility (hidden when behind camera)
             const isVisible = pos.z < 1;
             el.style.opacity = isVisible ? '1' : '0';
             el.style.display = isVisible ? 'block' : 'none';
-            el.style.transform = `translate(-50%, -100%) translate(${x}px, ${y}px)`; // 屏幕位置
+            el.style.transform = `translate(-50%, -100%) translate(${x}px, ${y}px)`; // Screen position
         });
-        rafId = requestAnimationFrame(updateLabels); // 循环更新
+        rafId = requestAnimationFrame(updateLabels); // Loop update
     }
-    // 启动更新
+    // Start update
     updateLabels();
     /**
-     * 暂停更新
+     * Pause updates
      */
     const pause = () => {
         isPaused = true;
@@ -162,7 +171,7 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         }
     };
     /**
-     * 恢复更新
+     * Resume updates
      */
     const resume = () => {
         if (!isPaused)
@@ -171,11 +180,11 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         updateLabels();
     };
     /**
-     * 检查是否正在运行
+     * Check if running
      */
     const isRunning = () => !isPaused;
     /**
-     * 清理函数：卸载所有 DOM 标签，取消动画，避免内存泄漏
+     * Cleanup function: Remove all DOM labels, cancel animation, avoid memory leaks
      */
     const dispose = () => {
         pause();
@@ -197,36 +206,45 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
     };
 }
 
-// src/utils/hoverBreathEffectByNameSingleton.ts
 /**
- * 创建单例高亮器 —— 推荐在 mounted 时创建一次
- * 返回 { updateHighlightNames, dispose, getHoveredName } 接口
+ * @file hoverEffect.ts
+ * @description
+ * Singleton highlight effect manager. Uses OutlinePass to create a breathing highlight effect on hovered objects.
+ *
+ * @best-practice
+ * - Initialize once in your setup/mounted hook.
+ * - Call `updateHighlightNames` to filter which objects are interactive.
+ * - Automatically handles mousemove throttling and cleanup on dispose.
+ */
+/**
+ * Create a singleton highlighter - Recommended to create once on mount
+ * Returns { updateHighlightNames, dispose, getHoveredName } interface
  *
- * ✨ 性能优化：
- * - 无 hover 对象时自动暂停动画
- * - mousemove 节流处理，避免过度计算
- * - 使用 passive 事件监听器提升滚动性能
+ * Features:
+ * - Automatically pauses animation when no object is hovered
+ * - Throttles mousemove events to avoid excessive calculation
+ * - Uses passive event listeners to improve scrolling performance
  */
 function enableHoverBreath(opts) {
-    const { camera, scene, renderer, outlinePass, highlightNames = null, minStrength = 2, maxStrength = 5, speed = 4, throttleDelay = 16, // 默认约 60fps
+    const { camera, scene, renderer, outlinePass, highlightNames = null, minStrength = 2, maxStrength = 5, speed = 4, throttleDelay = 16, // Default ~60fps
      } = opts;
     const raycaster = new THREE.Raycaster();
     const mouse = new THREE.Vector2();
     let hovered = null;
     let time = 0;
     let animationId = null;
-    // highlightSet: null 表示 all; empty Set 表示 none
+    // highlightSet: null means all; empty Set means none
     let highlightSet = highlightNames === null ? null : new Set(highlightNames);
-    // 节流相关
+    // Throttling related
     let lastMoveTime = 0;
     let rafPending = false;
     function setHighlightNames(names) {
         highlightSet = names === null ? null : new Set(names);
-        // 如果当前 hovered 不在新名单中，及时清理 selection
+        // If current hovered object is not in the new list, clean up selection immediately
         if (hovered && highlightSet && !highlightSet.has(hovered.name)) {
             hovered = null;
             outlinePass.selectedObjects = [];
-            // 暂停动画
+            // Pause animation
             if (animationId !== null) {
                 cancelAnimationFrame(animationId);
                 animationId = null;
@@ -234,13 +252,13 @@ function enableHoverBreath(opts) {
         }
     }
     /**
-     * 节流版本的 mousemove 处理
+     * Throttled mousemove handler
      */
     function onMouseMove(ev) {
         const now = performance.now();
-        // 节流：如果距上次处理时间小于阈值，跳过
+        // Throttle: if time since last process is less than threshold, skip
         if (now - lastMoveTime < throttleDelay) {
-            // 使用 RAF 延迟处理，避免丢失最后一次事件
+            // Use RAF to process the latest event later, ensuring the last event isn't lost
             if (!rafPending) {
                 rafPending = true;
                 requestAnimationFrame(() => {
@@ -254,24 +272,24 @@ function enableHoverBreath(opts) {
         processMouseMove(ev);
     }
     /**
-     * 实际的 mousemove 逻辑
+     * Actual mousemove logic
      */
     function processMouseMove(ev) {
         const rect = renderer.domElement.getBoundingClientRect();
         mouse.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
         mouse.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
         raycaster.setFromCamera(mouse, camera);
-        // 深度检测 scene 的所有子对象（true）
+        // Deep detect all children of the scene (true)
         const intersects = raycaster.intersectObjects(scene.children, true);
         if (intersects.length > 0) {
             const obj = intersects[0].object;
-            // 判断是否允许被高亮
+            // Determine if it is allowed to be highlighted
             const allowed = highlightSet === null ? true : highlightSet.has(obj.name);
             if (allowed) {
                 if (hovered !== obj) {
                     hovered = obj;
                     outlinePass.selectedObjects = [obj];
-                    // 启动动画（如果未运行）
+                    // Start animation (if not running)
                     if (animationId === null) {
                         animate();
                     }
@@ -281,7 +299,7 @@ function enableHoverBreath(opts) {
                 if (hovered !== null) {
                     hovered = null;
                     outlinePass.selectedObjects = [];
-                    // 停止动画
+                    // Stop animation
                     if (animationId !== null) {
                         cancelAnimationFrame(animationId);
                         animationId = null;
@@ -293,7 +311,7 @@ function enableHoverBreath(opts) {
             if (hovered !== null) {
                 hovered = null;
                 outlinePass.selectedObjects = [];
-                // 停止动画
+                // Stop animation
                 if (animationId !== null) {
                     cancelAnimationFrame(animationId);
                     animationId = null;
@@ -302,10 +320,10 @@ function enableHoverBreath(opts) {
         }
     }
     /**
-     * 动画循环 - 只在有 hovered 对象时运行
+     * Animation loop - only runs when there is a hovered object
      */
     function animate() {
-        // 如果没有 hovered 对象，停止动画
+        // If no hovered object, stop animation
         if (!hovered) {
             animationId = null;
             return;
@@ -315,11 +333,11 @@ function enableHoverBreath(opts) {
         const strength = minStrength + ((Math.sin(time) + 1) / 2) * (maxStrength - minStrength);
         outlinePass.edgeStrength = strength;
     }
-    // 启动（只调用一次）
-    // 使用 passive 提升滚动性能
+    // Start (called only once)
+    // Use passive to improve scrolling performance
     renderer.domElement.addEventListener('mousemove', onMouseMove, { passive: true });
-    // 注意：不在这里启动 animate，等有 hover 对象时再启动
-    // refresh: 如果你在某些情况下需要强制清理 selectedObjects
+    // Note: Do not start animate here, wait until there is a hover object
+    // refresh: Forcibly clean up selectedObjects if needed
     function refreshSelection() {
         if (hovered && highlightSet && !highlightSet.has(hovered.name)) {
             hovered = null;
@@ -340,7 +358,7 @@ function enableHoverBreath(opts) {
             animationId = null;
         }
         outlinePass.selectedObjects = [];
-        // 清空引用
+        // Clear references
         hovered = null;
         highlightSet = null;
     }
@@ -353,23 +371,33 @@ function enableHoverBreath(opts) {
 }
 
 /**
- * 初始化描边相关信息（包含 OutlinePass）- 优化版
+ * @file postProcessing.ts
+ * @description
+ * Manages the post-processing chain, specifically for Outline effects and Gamma correction.
  *
- * ✨ 功能增强：
- * - 支持窗口 resize 自动更新
- * - 可配置分辨率缩放提升性能
- * - 完善的资源释放管理
+ * @best-practice
+ * - call `initPostProcessing` after creating your renderer and scene.
+ * - Use the returned `composer` in your render loop instead of `renderer.render`.
+ * - Handles resizing automatically via the `resize` method.
+ */
+/**
+ * Initialize outline-related information (contains OutlinePass)
+ *
+ * Capabilities:
+ * - Supports automatic update on window resize
+ * - Configurable resolution scale for performance improvement
+ * - Comprehensive resource disposal management
  *
  * @param renderer THREE.WebGLRenderer
  * @param scene THREE.Scene
  * @param camera THREE.Camera
- * @param options PostProcessingOptions - 可选配置
- * @returns PostProcessingManager - 包含 composer/outlinePass/resize/dispose 的管理接口
+ * @param options PostProcessingOptions - Optional configuration
+ * @returns PostProcessingManager - Management interface containing composer/outlinePass/resize/dispose
  */
 function initPostProcessing(renderer, scene, camera, options = {}) {
-    // 默认配置
+    // Default configuration
     const { edgeStrength = 4, edgeGlow = 1, edgeThickness = 2, visibleEdgeColor = '#ffee00', hiddenEdgeColor = '#000000', resolutionScale = 1.0 } = options;
-    // 获取渲染器实际尺寸
+    // Get renderer actual size
     const getSize = () => {
         const width = renderer.domElement.clientWidth;
         const height = renderer.domElement.clientHeight;
@@ -379,12 +407,12 @@ function initPostProcessing(renderer, scene, camera, options = {}) {
         };
     };
     const size = getSize();
-    // 创建 EffectComposer
+    // Create EffectComposer
     const composer = new EffectComposer(renderer);
-    // 基础 RenderPass
+    // Basic RenderPass
     const renderPass = new RenderPass(scene, camera);
     composer.addPass(renderPass);
-    // OutlinePass 用于模型描边
+    // OutlinePass for model outlining
     const outlinePass = new OutlinePass(new THREE.Vector2(size.width, size.height), scene, camera);
     outlinePass.edgeStrength = edgeStrength;
     outlinePass.edgeGlow = edgeGlow;
@@ -392,34 +420,34 @@ function initPostProcessing(renderer, scene, camera, options = {}) {
     outlinePass.visibleEdgeColor.set(visibleEdgeColor);
     outlinePass.hiddenEdgeColor.set(hiddenEdgeColor);
     composer.addPass(outlinePass);
-    // Gamma 校正
+    // Gamma correction
     const gammaPass = new ShaderPass(GammaCorrectionShader);
     composer.addPass(gammaPass);
     /**
-     * resize 处理函数
-     * @param width 可选宽度，不传则使用 renderer.domElement 的实际宽度
-     * @param height 可选高度，不传则使用 renderer.domElement 的实际高度
+     * Handle resize
+     * @param width Optional width, uses renderer.domElement actual width if not provided
+     * @param height Optional height, uses renderer.domElement actual height if not provided
      */
     const resize = (width, height) => {
         const actualSize = width !== undefined && height !== undefined
             ? { width: Math.floor(width * resolutionScale), height: Math.floor(height * resolutionScale) }
             : getSize();
-        // 更新 composer 尺寸
+        // Update composer size
         composer.setSize(actualSize.width, actualSize.height);
-        // 更新 outlinePass 分辨率
+        // Update outlinePass resolution
         outlinePass.resolution.set(actualSize.width, actualSize.height);
     };
     /**
-     * 释放资源
+     * Dispose resources
      */
     const dispose = () => {
-        // 释放所有 passes
+        // Dipose all passes
         composer.passes.forEach(pass => {
             if (pass.dispose) {
                 pass.dispose();
             }
         });
-        // 清空 passes 数组
+        // Clear passes array
         composer.passes.length = 0;
     };
     return {
@@ -431,28 +459,99 @@ function initPostProcessing(renderer, scene, camera, options = {}) {
 }
 
 /**
- * 创建模型点击高亮工具（OutlinePass 版）- 优化版
+ * ResourceManager
+ * Handles tracking and disposal of Three.js objects to prevent memory leaks.
+ */
+class ResourceManager {
+    constructor() {
+        this.geometries = new Set();
+        this.materials = new Set();
+        this.textures = new Set();
+        this.objects = new Set();
+    }
+    /**
+     * Track an object and its resources recursively
+     */
+    track(object) {
+        this.objects.add(object);
+        object.traverse((child) => {
+            if (child.isMesh) {
+                const mesh = child;
+                if (mesh.geometry)
+                    this.geometries.add(mesh.geometry);
+                if (mesh.material) {
+                    if (Array.isArray(mesh.material)) {
+                        mesh.material.forEach(m => this.trackMaterial(m));
+                    }
+                    else {
+                        this.trackMaterial(mesh.material);
+                    }
+                }
+            }
+        });
+        return object;
+    }
+    trackMaterial(material) {
+        this.materials.add(material);
+        // Track textures in material
+        for (const value of Object.values(material)) {
+            if (value instanceof THREE.Texture) {
+                this.textures.add(value);
+            }
+        }
+    }
+    /**
+     * Dispose all tracked resources
+     */
+    dispose() {
+        this.geometries.forEach(g => g.dispose());
+        this.materials.forEach(m => m.dispose());
+        this.textures.forEach(t => t.dispose());
+        this.objects.forEach(obj => {
+            if (obj.parent) {
+                obj.parent.remove(obj);
+            }
+        });
+        this.geometries.clear();
+        this.materials.clear();
+        this.textures.clear();
+        this.objects.clear();
+    }
+}
+
+/**
+ * @file clickHandler.ts
+ * @description
+ * Tool for handling model clicks and highlighting (OutlinePass version).
  *
- * ✨ 功能增强：
- * - 使用 AbortController 统一管理事件生命周期
- * - 支持防抖处理避免频繁触发
- * - 可自定义 Raycaster 参数
- * - 根据相机距离动态调整描边厚度
+ * @best-practice
+ * - Use `createModelClickHandler` to setup interaction.
+ * - Handles debouncing and click threshold automatically.
+ * - Cleanup using the returned dispose function.
+ */
+/**
+ * Create Model Click Highlight Tool (OutlinePass Version) - Optimized
+ *
+ * Features:
+ * - Uses AbortController to unify event lifecycle management
+ * - Supports debounce to avoid frequent triggering
+ * - Customizable Raycaster parameters
+ * - Dynamically adjusts outline thickness based on camera distance
  *
- * @param camera 相机
- * @param scene 场景
- * @param renderer 渲染器
- * @param outlinePass 已初始化的 OutlinePass
- * @param onClick 点击回调
- * @param options 可选配置
- * @returns dispose 函数，用于清理事件和资源
+ * @param camera Camera
+ * @param scene Scene
+ * @param renderer Renderer
+ * @param outlinePass Initialized OutlinePass
+ * @param onClick Click callback
+ * @param options Optional configuration
+ * @returns Dispose function, used to clean up events and resources
  */
 function createModelClickHandler(camera, scene, renderer, outlinePass, onClick, options = {}) {
-    // 配置项
+    // Configuration
     const { clickThreshold = 3, debounceDelay = 0, raycasterParams = {}, enableDynamicThickness = true, minThickness = 1, maxThickness = 10 } = options;
     const raycaster = new THREE.Raycaster();
     const mouse = new THREE.Vector2();
-    // 应用 raycaster 自定义参数
+    // Apply Raycaster custom parameters
     if (raycasterParams.near !== undefined)
         raycaster.near = raycasterParams.near;
     if (raycasterParams.far !== undefined)
@@ -469,25 +568,25 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
     let startY = 0;
     let selectedObject = null;
     let debounceTimer = null;
-    // 使用 AbortController 统一管理事件
+    // Use AbortController to manage events uniformly
     const abortController = new AbortController();
     const signal = abortController.signal;
-    /** 恢复对象高亮（清空 OutlinePass.selectedObjects） */
+    /** Restore object highlight (Clear OutlinePass.selectedObjects) */
     function restoreObject() {
         outlinePass.selectedObjects = [];
     }
-    /** 鼠标按下记录位置 */
+    /** Record mouse down position */
     function handleMouseDown(event) {
         startX = event.clientX;
         startY = event.clientY;
     }
-    /** 鼠标抬起判定点击或拖动（带防抖） */
+    /** Mouse up determines click or drag (with debounce) */
     function handleMouseUp(event) {
         const dx = Math.abs(event.clientX - startX);
         const dy = Math.abs(event.clientY - startY);
         if (dx > clickThreshold || dy > clickThreshold)
-            return; // 拖动不触发点击
-        // 防抖处理
+            return; // Drag does not trigger click
+        // Debounce processing
         if (debounceDelay > 0) {
             if (debounceTimer !== null) {
                 clearTimeout(debounceTimer);
@@ -501,7 +600,7 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
             processClick(event);
         }
     }
-    /** 实际的点击处理逻辑 */
+    /** Actual click processing logic */
     function processClick(event) {
         const rect = renderer.domElement.getBoundingClientRect();
         mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
@@ -510,59 +609,67 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
         const intersects = raycaster.intersectObjects(scene.children, true);
         if (intersects.length > 0) {
             let object = intersects[0].object;
-            // 点击不同模型，先清除之前高亮
+            // Click different model, clear previous highlight first
             if (selectedObject && selectedObject !== object)
                 restoreObject();
             selectedObject = object;
-            // highlightObject(selectedObject); // 可选：是否自动高亮
+            // highlightObject(selectedObject); // Optional: whether to auto highlight
             onClick(selectedObject, {
-                name: selectedObject.name || '未命名模型',
+                name: selectedObject.name || 'Unnamed Model',
                 position: selectedObject.getWorldPosition(new THREE.Vector3()),
                 uuid: selectedObject.uuid
             });
         }
         else {
-            // 点击空白 → 清除高亮
+            // Click blank -> Clear highlight
             if (selectedObject)
                 restoreObject();
             selectedObject = null;
             onClick(null);
         }
     }
-    // 使用 AbortController 的 signal 注册事件
+    // Register events using signal from AbortController
     renderer.domElement.addEventListener('mousedown', handleMouseDown, { signal });
     renderer.domElement.addEventListener('mouseup', handleMouseUp, { signal });
-    /** 销毁函数：解绑事件并清除高亮 */
+    /** Dispose function: Unbind events and clear highlight */
     return () => {
-        // 清理防抖定时器
+        // Clear debounce timer
         if (debounceTimer !== null) {
             clearTimeout(debounceTimer);
             debounceTimer = null;
         }
-        // 一次性解绑所有事件
+        // Unbind all events at once
         abortController.abort();
-        // 清除高亮
+        // Clear highlight
         restoreObject();
-        // 清空引用
+        // Clear reference
         selectedObject = null;
     };
 }
 
-// src/utils/ArrowGuide.ts
 /**
- * ArrowGuide - 优化版
- * 箭头引导效果工具，支持高亮模型并淡化其他对象
+ * @file arrowGuide.ts
+ * @description
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
+ *
+ * @best-practice
+ * - Use `highlight` to focus on specific models.
+ * - Automatically manages materials and memory using WeakMap.
+ * - Call `dispose` when component unmounts.
+ */
+/**
+ * ArrowGuide - Optimized Version
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
  *
- * ✨ 优化内容：
- * - 使用 WeakMap 自动回收材质，避免内存泄漏
- * - 使用 AbortController 管理事件生命周期
- * - 添加材质复用机制，减少重复创建
- * - 改进 dispose 逻辑，确保完全释放资源
- * - 添加错误处理和边界检查
+ * Features:
+ * - Uses WeakMap for automatic material recycling, preventing memory leaks
+ * - Uses AbortController to manage event lifecycle
+ * - Adds material reuse mechanism to reuse materials
+ * - Improved dispose logic ensuring complete resource release
+ * - Adds error handling and boundary checks
  */
 class ArrowGuide {
     constructor(renderer, camera, scene, options) {
-        var _a, _b, _c;
         this.renderer = renderer;
         this.camera = camera;
         this.scene = scene;
@@ -573,45 +680,45 @@ class ArrowGuide {
         this.clickThreshold = 10;
         this.raycaster = new THREE.Raycaster();
         this.mouse = new THREE.Vector2();
-        // ✨ 使用 WeakMap 自动回收材质（GC 友好）
+        // Use WeakMap for automatic material recycling (GC friendly)
         this.originalMaterials = new WeakMap();
         this.fadedMaterials = new WeakMap();
-        // ✨ AbortController 用于事件管理
+        // AbortController for event management
         this.abortController = null;
-        // 配置：非高亮透明度和亮度
+        // Config: Non-highlight opacity and brightness
         this.fadeOpacity = 0.5;
         this.fadeBrightness = 0.1;
-        this.clickThreshold = (_a = options === null || options === void 0 ? void 0 : options.clickThreshold) !== null && _a !== void 0 ? _a : 10;
-        this.ignoreRaycastNames = new Set((options === null || options === void 0 ? void 0 : options.ignoreRaycastNames) || []);
-        this.fadeOpacity = (_b = options === null || options === void 0 ? void 0 : options.fadeOpacity) !== null && _b !== void 0 ? _b : 0.5;
-        this.fadeBrightness = (_c = options === null || options === void 0 ? void 0 : options.fadeBrightness) !== null && _c !== void 0 ? _c : 0.1;
+        this.clickThreshold = options?.clickThreshold ?? 10;
+        this.ignoreRaycastNames = new Set(options?.ignoreRaycastNames || []);
+        this.fadeOpacity = options?.fadeOpacity ?? 0.5;
+        this.fadeBrightness = options?.fadeBrightness ?? 0.1;
         this.abortController = new AbortController();
         this.initEvents();
     }
-    // —— 工具：缓存原材质（仅首次）
+    // Tool: Cache original material (first time only)
     cacheOriginalMaterial(mesh) {
         if (!this.originalMaterials.has(mesh)) {
             this.originalMaterials.set(mesh, mesh.material);
         }
     }
-    // —— 工具：为某个材质克隆一个"半透明版本"，保留所有贴图与参数
+    // Tool: Clone a "translucent version" for a material, preserving all maps and parameters
     makeFadedClone(mat) {
         const clone = mat.clone();
         const c = clone;
-        // 只改透明相关参数，不改 map / normalMap / roughnessMap 等细节
+        // Only modify transparency parameters, do not modify detail maps like map / normalMap / roughnessMap
         c.transparent = true;
         if (typeof c.opacity === 'number')
             c.opacity = this.fadeOpacity;
         if (c.color && c.color.isColor) {
-            c.color.multiplyScalar(this.fadeBrightness); // 颜色整体变暗
+            c.color.multiplyScalar(this.fadeBrightness); // Darken color overall
         }
-        // 为了让箭头在透明建筑后也能顺畅显示，常用策略：不写深度，仅测试深度
+        // Common strategy for fluid display behind transparent objects: do not write depth, only test depth
         clone.depthWrite = false;
         clone.depthTest = true;
         clone.needsUpdate = true;
         return clone;
     }
-    // —— 工具：为 mesh.material（可能是数组）批量克隆"半透明版本"
+    // Tool: Batch clone "translucent version" for mesh.material (could be array)
     createFadedMaterialFrom(mesh) {
         const orig = mesh.material;
         if (Array.isArray(orig)) {
@@ -620,7 +727,7 @@ class ArrowGuide {
         return this.makeFadedClone(orig);
     }
     /**
-     * 设置箭头 Mesh
+     * Set Arrow Mesh
      */
     setArrowMesh(mesh) {
         this.lxMesh = mesh;
@@ -636,15 +743,15 @@ class ArrowGuide {
             mesh.visible = false;
         }
         catch (error) {
-            console.error('ArrowGuide: 设置箭头材质失败', error);
+            console.error('ArrowGuide: Failed to set arrow material', error);
         }
     }
     /**
-     * 高亮指定模型
+     * Highlight specified models
      */
     highlight(models) {
         if (!models || models.length === 0) {
-            console.warn('ArrowGuide: 高亮模型列表为空');
+            console.warn('ArrowGuide: Highlight model list is empty');
             return;
         }
         this.modelBrightArr = models;
@@ -653,9 +760,9 @@ class ArrowGuide {
             this.lxMesh.visible = true;
         this.applyHighlight();
     }
-    // ✅ 应用高亮效果：非高亮模型保留细节 → 使用"克隆后的半透明材质"
+    // Apply highlight effect: Non-highlighted models preserve details -> use "cloned translucent material"
     applyHighlight() {
-        // ✨ 使用 Set 提升查找性能
+        // Use Set to improve lookup performance
         const keepMeshes = new Set();
         this.modelBrightArr.forEach(obj => {
             obj.traverse(child => {
@@ -667,21 +774,21 @@ class ArrowGuide {
             this.scene.traverse(obj => {
                 if (obj.isMesh) {
                     const mesh = obj;
-                    // 缓存原材质（用于恢复）
+                    // Cache original material (for restoration)
                     this.cacheOriginalMaterial(mesh);
                     if (!keepMeshes.has(mesh)) {
-                        // 非高亮：如果还没给它生成过"半透明克隆材质"，就创建一次
+                        // Non-highlighted: if no "translucent clone material" generated yet, create one
                         if (!this.fadedMaterials.has(mesh)) {
                             const faded = this.createFadedMaterialFrom(mesh);
                             this.fadedMaterials.set(mesh, faded);
                         }
-                        // 替换为克隆材质（保留所有贴图/法线等细节）
+                        // Replace with clone material (preserve all maps/normals details)
                         const fadedMat = this.fadedMaterials.get(mesh);
                         if (fadedMat)
                             mesh.material = fadedMat;
                     }
                     else {
-                        // 高亮对象：确保回到原材质（避免上一次高亮后遗留）
+                        // Highlighted object: ensure return to original material (avoid leftover from previous highlight)
                         const orig = this.originalMaterials.get(mesh);
                         if (orig && mesh.material !== orig) {
                             mesh.material = orig;
@@ -692,16 +799,16 @@ class ArrowGuide {
             });
         }
         catch (error) {
-            console.error('ArrowGuide: 应用高亮失败', error);
+            console.error('ArrowGuide: Failed to apply highlight', error);
         }
     }
-    // ✅ 恢复为原材质 & 释放克隆材质
+    // Restore to original material & dispose clone material
     restore() {
         this.flowActive = false;
         if (this.lxMesh)
             this.lxMesh.visible = false;
         try {
-            // ✨ 收集所有需要释放的材质
+            // Collect all materials to dispose
             const materialsToDispose = [];
             this.scene.traverse(obj => {
                 if (obj.isMesh) {
@@ -711,7 +818,7 @@ class ArrowGuide {
                         mesh.material = orig;
                         mesh.material.needsUpdate = true;
                     }
-                    // ✨ 收集待释放的淡化材质
+                    // Collect faded materials to dispose
                     const faded = this.fadedMaterials.get(mesh);
                     if (faded) {
                         if (Array.isArray(faded)) {
@@ -723,24 +830,24 @@ class ArrowGuide {
                     }
                 }
             });
-            // ✨ 批量释放材质（不触碰贴图资源）
+            // Batch dispose materials (do not touch texture resources)
             materialsToDispose.forEach(mat => {
                 try {
                     mat.dispose();
                 }
                 catch (error) {
-                    console.error('ArrowGuide: 释放材质失败', error);
+                    console.error('ArrowGuide: Failed to dispose material', error);
                 }
             });
-            // ✨ 创建新的 WeakMap（相当于清空）
+            // Create new WeakMap (equivalent to clearing)
             this.fadedMaterials = new WeakMap();
         }
         catch (error) {
-            console.error('ArrowGuide: 恢复材质失败', error);
+            console.error('ArrowGuide: Failed to restore material', error);
         }
     }
     /**
-     * 动画更新（每帧调用）
+     * Animation update (called every frame)
      */
     animate() {
         if (!this.flowActive || !this.lxMesh)
@@ -754,16 +861,16 @@ class ArrowGuide {
             }
         }
         catch (error) {
-            console.error('ArrowGuide: 动画更新失败', error);
+            console.error('ArrowGuide: Animation update failed', error);
         }
     }
     /**
-     * 初始化事件监听器
+     * Initialize event listeners
      */
     initEvents() {
         const dom = this.renderer.domElement;
         const signal = this.abortController.signal;
-        // ✨ 使用 AbortController signal 自动管理事件生命周期
+        // Use AbortController signal to automatically manage event lifecycle
         dom.addEventListener('pointerdown', (e) => {
             this.pointerDownPos.set(e.clientX, e.clientY);
         }, { signal });
@@ -771,7 +878,7 @@ class ArrowGuide {
             const dx = Math.abs(e.clientX - this.pointerDownPos.x);
             const dy = Math.abs(e.clientY - this.pointerDownPos.y);
             if (dx > this.clickThreshold || dy > this.clickThreshold)
-                return; // 拖拽
+                return; // Dragging
             const rect = dom.getBoundingClientRect();
             this.mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
             this.mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
@@ -785,21 +892,21 @@ class ArrowGuide {
                 return true;
             });
             if (filtered.length === 0)
-                this.restore(); // 点击空白恢复
+                this.restore(); // Click blank space to restore
         }, { signal });
     }
     /**
-     * 释放所有资源
+     * Dispose all resources
      */
     dispose() {
-        // ✨ 先恢复材质
+        // Restore materials first
         this.restore();
-        // ✨ 使用 AbortController 一次性解绑所有事件
+        // Unbind all events at once using AbortController
         if (this.abortController) {
             this.abortController.abort();
             this.abortController = null;
         }
-        // ✨ 清空引用
+        // Clear references
         this.modelBrightArr = [];
         this.lxMesh = null;
         this.fadedMaterials = new WeakMap();
@@ -808,50 +915,59 @@ class ArrowGuide {
     }
 }
 
-// utils/LiquidFillerGroup.ts
 /**
- * LiquidFillerGroup - 优化版
- * 支持单模型或多模型液位动画、独立颜色控制
+ * @file liquidFiller.ts
+ * @description
+ * Liquid filling effect for single or multiple models using local clipping planes.
  *
- * ✨ 优化内容：
- * - 使用 renderer.domElement 替代 window 事件
- * - 使用 AbortController 管理事件生命周期
- * - 添加错误处理和边界检查
- * - 优化动画管理，避免内存泄漏
- * - 完善资源释放逻辑
+ * @best-practice
+ * - Use `fillTo` to animate liquid level.
+ * - Supports multiple independent liquid levels.
+ * - Call `dispose` to clean up resources and event listeners.
+ */
+/**
+ * LiquidFillerGroup - Optimized
+ * Supports single or multi-model liquid level animation with independent color control.
+ *
+ * Features:
+ * - Uses renderer.domElement instead of window events
+ * - Uses AbortController to manage event lifecycle
+ * - Adds error handling and boundary checks
+ * - Optimized animation management to prevent memory leaks
+ * - Comprehensive resource disposal logic
  */
 class LiquidFillerGroup {
     /**
-     * 构造函数
-     * @param models 单个或多个 THREE.Object3D
-     * @param scene 场景
-     * @param camera 相机
-     * @param renderer 渲染器
-     * @param defaultOptions 默认液体选项
-     * @param clickThreshold 点击阈值，单位像素
+     * Constructor
+     * @param models Single or multiple THREE.Object3D
+     * @param scene Scene
+     * @param camera Camera
+     * @param renderer Renderer
+     * @param defaultOptions Default liquid options
+     * @param clickThreshold Click threshold in pixels
      */
     constructor(models, scene, camera, renderer, defaultOptions, clickThreshold = 10) {
         this.items = [];
         this.raycaster = new THREE.Raycaster();
         this.pointerDownPos = new THREE.Vector2();
         this.clickThreshold = 10;
-        this.abortController = null; // ✨ 事件管理器
-        /** pointerdown 记录位置 */
+        this.abortController = null; // Event manager
+        /** pointerdown record position */
         this.handlePointerDown = (event) => {
             this.pointerDownPos.set(event.clientX, event.clientY);
         };
-        /** pointerup 判断点击空白，恢复原始材质 */
+        /** pointerup check click blank, restore original material */
         this.handlePointerUp = (event) => {
             const dx = event.clientX - this.pointerDownPos.x;
             const dy = event.clientY - this.pointerDownPos.y;
             const distance = Math.sqrt(dx * dx + dy * dy);
             if (distance > this.clickThreshold)
-                return; // 拖拽不触发
-            // ✨ 使用 renderer.domElement 的实际尺寸
+                return; // Do not trigger on drag
+            // Use renderer.domElement actual size
             const rect = this.renderer.domElement.getBoundingClientRect();
             const pointerNDC = new THREE.Vector2(((event.clientX - rect.left) / rect.width) * 2 - 1, -((event.clientY - rect.top) / rect.height) * 2 + 1);
             this.raycaster.setFromCamera(pointerNDC, this.camera);
-            // 点击空白 -> 所有模型恢复
+            // Click blank -> Restore all models
             const intersectsAny = this.items.some(item => this.raycaster.intersectObject(item.model, true).length > 0);
             if (!intersectsAny) {
                 this.restoreAll();
@@ -861,18 +977,17 @@ class LiquidFillerGroup {
         this.camera = camera;
         this.renderer = renderer;
         this.clickThreshold = clickThreshold;
-        // ✨ 创建 AbortController 用于事件管理
+        // Create AbortController for event management
         this.abortController = new AbortController();
         const modelArray = Array.isArray(models) ? models : [models];
         modelArray.forEach(model => {
-            var _a, _b, _c;
             try {
                 const options = {
-                    color: (_a = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.color) !== null && _a !== void 0 ? _a : 0x00ff00,
-                    opacity: (_b = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.opacity) !== null && _b !== void 0 ? _b : 0.6,
-                    speed: (_c = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.speed) !== null && _c !== void 0 ? _c : 0.05,
+                    color: defaultOptions?.color ?? 0x00ff00,
+                    opacity: defaultOptions?.opacity ?? 0.6,
+                    speed: defaultOptions?.speed ?? 0.05,
                 };
-                // 保存原始材质
+                // Save original materials
                 const originalMaterials = new Map();
                 model.traverse(obj => {
                     if (obj.isMesh) {
@@ -880,12 +995,12 @@ class LiquidFillerGroup {
                         originalMaterials.set(mesh, mesh.material);
                     }
                 });
-                // ✨ 边界检查：确保有材质可以保存
+                // Boundary check: ensure there are materials to save
                 if (originalMaterials.size === 0) {
-                    console.warn('LiquidFillerGroup: 模型没有 Mesh 对象', model);
+                    console.warn('LiquidFillerGroup: Model has no Mesh objects', model);
                     return;
                 }
-                // 应用淡线框材质
+                // Apply faded wireframe material
                 model.traverse(obj => {
                     if (obj.isMesh) {
                         const mesh = obj;
@@ -897,7 +1012,7 @@ class LiquidFillerGroup {
                         });
                     }
                 });
-                // 创建液体 Mesh
+                // Create liquid Mesh
                 const geometries = [];
                 model.traverse(obj => {
                     if (obj.isMesh) {
@@ -908,12 +1023,12 @@ class LiquidFillerGroup {
                     }
                 });
                 if (geometries.length === 0) {
-                    console.warn('LiquidFillerGroup: 模型没有几何体', model);
+                    console.warn('LiquidFillerGroup: Model has no geometries', model);
                     return;
                 }
                 const mergedGeometry = BufferGeometryUtils.mergeGeometries(geometries, false);
                 if (!mergedGeometry) {
-                    console.error('LiquidFillerGroup: 几何体合并失败', model);
+                    console.error('LiquidFillerGroup: Failed to merge geometries', model);
                     return;
                 }
                 const material = new THREE.MeshPhongMaterial({
@@ -924,7 +1039,7 @@ class LiquidFillerGroup {
                 });
                 const liquidMesh = new THREE.Mesh(mergedGeometry, material);
                 this.scene.add(liquidMesh);
-                // 设置 clippingPlane
+                // Set clippingPlane
                 const clipPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0);
                 const mat = liquidMesh.material;
                 mat.clippingPlanes = [clipPlane];
@@ -935,41 +1050,41 @@ class LiquidFillerGroup {
                     clipPlane,
                     originalMaterials,
                     options,
-                    animationId: null // ✨ 初始化动画 ID
+                    animationId: null // Initialize animation ID
                 });
             }
             catch (error) {
-                console.error('LiquidFillerGroup: 初始化模型失败', model, error);
+                console.error('LiquidFillerGroup: Failed to initialize model', model, error);
             }
         });
-        // ✨ 使用 renderer.domElement 替代 window，使用 AbortController signal
+        // Use renderer.domElement instead of window, use AbortController signal
         const signal = this.abortController.signal;
         this.renderer.domElement.addEventListener('pointerdown', this.handlePointerDown, { signal });
         this.renderer.domElement.addEventListener('pointerup', this.handlePointerUp, { signal });
     }
     /**
-   * 设置液位
-   * @param models 单个模型或模型数组
-   * @param percent 液位百分比 0~1
-   */
+     * Set liquid level
+     * @param models Single model or array of models
+     * @param percent Liquid level percentage 0~1
+     */
     fillTo(models, percent) {
-        // ✨ 边界检查
+        // Boundary check
         if (percent < 0 || percent > 1) {
-            console.warn('LiquidFillerGroup: percent 必须在 0~1 之间', percent);
+            console.warn('LiquidFillerGroup: percent must be between 0 and 1', percent);
             percent = Math.max(0, Math.min(1, percent));
         }
         const modelArray = Array.isArray(models) ? models : [models];
         modelArray.forEach(model => {
             const item = this.items.find(i => i.model === model);
             if (!item) {
-                console.warn('LiquidFillerGroup: 未找到模型', model);
+                console.warn('LiquidFillerGroup: Model not found', model);
                 return;
             }
             if (!item.liquidMesh) {
-                console.warn('LiquidFillerGroup: liquidMesh 已被释放', model);
+                console.warn('LiquidFillerGroup: liquidMesh already disposed', model);
                 return;
             }
-            // ✨ 取消之前的动画
+            // Cancel previous animation
             if (item.animationId !== null) {
                 cancelAnimationFrame(item.animationId);
                 item.animationId = null;
@@ -997,14 +1112,14 @@ class LiquidFillerGroup {
                 animate();
             }
             catch (error) {
-                console.error('LiquidFillerGroup: fillTo 执行失败', model, error);
+                console.error('LiquidFillerGroup: fillTo execution failed', model, error);
             }
         });
     }
-    /** 设置多个模型液位，percentList 与 items 顺序对应 */
+    /** Set multiple model levels, percentList corresponds to items order */
     fillToAll(percentList) {
         if (percentList.length !== this.items.length) {
-            console.warn(`LiquidFillerGroup: percentList 长度 (${percentList.length}) 与 items 长度 (${this.items.length}) 不匹配`);
+            console.warn(`LiquidFillerGroup: percentList length (${percentList.length}) does not match items length (${this.items.length})`);
         }
         percentList.forEach((p, idx) => {
             if (idx < this.items.length) {
@@ -1012,17 +1127,17 @@ class LiquidFillerGroup {
             }
         });
     }
-    /** 恢复单个模型原始材质并移除液体 */
+    /** Restore single model original material and remove liquid */
     restore(model) {
         const item = this.items.find(i => i.model === model);
         if (!item)
             return;
-        // ✨ 取消动画
+        // Cancel animation
         if (item.animationId !== null) {
             cancelAnimationFrame(item.animationId);
             item.animationId = null;
         }
-        // 恢复原始材质
+        // Restore original material
         item.model.traverse(obj => {
             if (obj.isMesh) {
                 const mesh = obj;
@@ -1031,7 +1146,7 @@ class LiquidFillerGroup {
                     mesh.material = original;
             }
         });
-        // 释放液体 Mesh
+        // Dispose liquid Mesh
         if (item.liquidMesh) {
             this.scene.remove(item.liquidMesh);
             item.liquidMesh.geometry.dispose();
@@ -1044,50 +1159,60 @@ class LiquidFillerGroup {
             item.liquidMesh = null;
         }
     }
-    /** 恢复所有模型 */
+    /** Restore all models */
     restoreAll() {
         this.items.forEach(item => this.restore(item.model));
     }
-    /** 销毁方法，释放事件和资源 */
+    /** Dispose method, release events and resources */
     dispose() {
-        // ✨ 先恢复所有模型
+        // Restore all models first
         this.restoreAll();
-        // ✨ 使用 AbortController 一次性解绑所有事件
+        // Unbind all events at once using AbortController
         if (this.abortController) {
             this.abortController.abort();
             this.abortController = null;
         }
-        // ✨ 清空 items
+        // Clear items
         this.items.length = 0;
     }
 }
 
-// src/utils/followModels.ts - 优化版
-// ✨ 使用 WeakMap 跟踪动画，支持取消
+/**
+ * @file followModels.ts
+ * @description
+ * Camera utility to automatically follow and focus on 3D models.
+ * It smoothly moves the camera to an optimal viewing position relative to the target object(s).
+ *
+ * @best-practice
+ * - Use `followModels` to focus on a newly selected object.
+ * - Call `cancelFollow` before starting a new manual camera interaction if needed.
+ * - Adjust `padding` to control how tight the camera framing is.
+ */
+// Use WeakMap to track animations, allowing for cancellation
 const _animationMap = new WeakMap();
 /**
- * 推荐角度枚举，便于快速选取常见视角
+ * Recommended camera angles for quick selection of common views
  */
 const FOLLOW_ANGLES = {
-    /** 等距斜视（默认视角）- 适合建筑、机械设备展示 */
+    /** Isometric view (default) - suitable for architecture, mechanical equipment */
     ISOMETRIC: { azimuth: Math.PI / 4, elevation: Math.PI / 4 },
-    /** 正前视角 - 适合正面展示、UI 对齐 */
+    /** Front view - suitable for frontal display, UI alignment */
     FRONT: { azimuth: 0, elevation: 0 },
-    /** 右侧视角 - 适合机械剖面、侧视检查 */
+    /** Right view - suitable for mechanical sections, side inspection */
     RIGHT: { azimuth: Math.PI / 2, elevation: 0 },
-    /** 左侧视角 */
+    /** Left view */
     LEFT: { azimuth: -Math.PI / 2, elevation: 0 },
-    /** 后视角 */
+    /** Back view */
     BACK: { azimuth: Math.PI, elevation: 0 },
-    /** 顶视图 - 适合地图、平面布局展示 */
+    /** Top view - suitable for maps, layout display */
     TOP: { azimuth: 0, elevation: Math.PI / 2 },
-    /** 低角度俯视 - 适合车辆、人物等近地物体 */
+    /** Low angle view - suitable for vehicles, characters near the ground */
     LOW_ANGLE: { azimuth: Math.PI / 4, elevation: Math.PI / 6 },
-    /** 高角度俯视 - 适合鸟瞰、全景浏览 */
+    /** High angle view - suitable for bird's eye view, panoramic browsing */
     HIGH_ANGLE: { azimuth: Math.PI / 4, elevation: Math.PI / 3 }
 };
 /**
- * 缓动函数集合
+ * Collection of easing functions
  */
 const EASING_FUNCTIONS = {
     linear: (t) => t,
@@ -1096,20 +1221,20 @@ const EASING_FUNCTIONS = {
     easeIn: (t) => t * t * t
 };
 /**
- * 自动将相机移到目标的斜上角位置，并保证目标在可视范围内（平滑过渡）- 优化版
+ * Automatically moves the camera to a diagonal position relative to the target,
+ * ensuring the target is within the field of view (smooth transition).
  *
- * ✨ 优化内容：
- * - 支持多种缓动函数
- * - 添加进度回调
- * - 支持取消动画
- * - WeakMap 跟踪防止泄漏
- * - 完善错误处理
+ * Features:
+ * - Supports multiple easing functions
+ * - Adds progress callback
+ * - Supports animation cancellation
+ * - Uses WeakMap to track and prevent memory leaks
+ * - Robust error handling
  */
 function followModels(camera, targets, options = {}) {
-    var _a, _b, _c, _d, _e, _f;
-    // ✨ 取消之前的动画
+    // Cancel previous animation
     cancelFollow(camera);
-    // ✨ 边界检查
+    // Boundary check
     const arr = [];
     if (!targets)
         return Promise.resolve();
@@ -1118,31 +1243,31 @@ function followModels(camera, targets, options = {}) {
     else
         arr.push(targets);
     if (arr.length === 0) {
-        console.warn('followModels: 目标对象为空');
+        console.warn('followModels: Target object is empty');
         return Promise.resolve();
     }
     try {
         const box = new THREE.Box3();
         arr.forEach((o) => box.expandByObject(o));
-        // ✨ 检查包围盒有效性
+        // Check bounding box validity
         if (!isFinite(box.min.x) || !isFinite(box.max.x)) {
-            console.warn('followModels: 包围盒计算失败');
+            console.warn('followModels: Failed to calculate bounding box');
             return Promise.resolve();
         }
         const sphere = new THREE.Sphere();
         box.getBoundingSphere(sphere);
         const center = sphere.center.clone();
         const radiusBase = Math.max(0.001, sphere.radius);
-        const duration = (_a = options.duration) !== null && _a !== void 0 ? _a : 700;
-        const padding = (_b = options.padding) !== null && _b !== void 0 ? _b : 1.0;
+        const duration = options.duration ?? 700;
+        const padding = options.padding ?? 1.0;
         const minDistance = options.minDistance;
         const maxDistance = options.maxDistance;
-        const controls = (_c = options.controls) !== null && _c !== void 0 ? _c : null;
-        const azimuth = (_d = options.azimuth) !== null && _d !== void 0 ? _d : Math.PI / 4;
-        const elevation = (_e = options.elevation) !== null && _e !== void 0 ? _e : Math.PI / 4;
-        const easing = (_f = options.easing) !== null && _f !== void 0 ? _f : 'easeOut';
+        const controls = options.controls ?? null;
+        const azimuth = options.azimuth ?? Math.PI / 4;
+        const elevation = options.elevation ?? Math.PI / 4;
+        const easing = options.easing ?? 'easeOut';
         const onProgress = options.onProgress;
-        // ✨ 获取缓动函数
+        // Get easing function
         const easingFn = EASING_FUNCTIONS[easing] || EASING_FUNCTIONS.easeOut;
         let distance = 10;
         if (camera.isPerspectiveCamera) {
@@ -1162,7 +1287,7 @@ function followModels(camera, targets, options = {}) {
         else {
             distance = camera.position.distanceTo(center);
         }
-        // 根据 azimuth / elevation 计算方向
+        // Calculate direction based on azimuth / elevation
         const hx = Math.sin(azimuth);
         const hz = Math.cos(azimuth);
         const dir = new THREE.Vector3(hx * Math.cos(elevation), Math.sin(elevation), hz * Math.cos(elevation)).normalize();
@@ -1175,7 +1300,6 @@ function followModels(camera, targets, options = {}) {
         const startTime = performance.now();
         return new Promise((resolve) => {
             const step = (now) => {
-                var _a;
                 const elapsed = now - startTime;
                 const t = Math.min(1, duration > 0 ? elapsed / duration : 1);
                 const k = easingFn(t);
@@ -1189,14 +1313,16 @@ function followModels(camera, targets, options = {}) {
                 else {
                     camera.lookAt(endTarget);
                 }
-                (_a = camera.updateProjectionMatrix) === null || _a === void 0 ? void 0 : _a.call(camera);
-                // ✨ 调用进度回调
+                if (camera.updateProjectionMatrix) {
+                    camera.updateProjectionMatrix();
+                }
+                // Call progress callback
                 if (onProgress) {
                     try {
                         onProgress(t);
                     }
                     catch (error) {
-                        console.error('followModels: 进度回调错误', error);
+                        console.error('followModels: Progress callback error', error);
                     }
                 }
                 if (t < 1) {
@@ -1222,12 +1348,12 @@ function followModels(camera, targets, options = {}) {
         });
     }
     catch (error) {
-        console.error('followModels: 执行失败', error);
+        console.error('followModels: Execution failed', error);
         return Promise.reject(error);
     }
 }
 /**
- * ✨ 取消相机的跟随动画
+ * Cancel the camera follow animation
  */
 function cancelFollow(camera) {
     const rafId = _animationMap.get(camera);
@@ -1237,42 +1363,47 @@ function cancelFollow(camera) {
     }
 }
 
-// src/utils/setView.ts - 优化版
 /**
- * 平滑切换相机到模型的最佳视角 - 优化版
+ * @file setView.ts
+ * @description
+ * Utility to smoothly transition the camera to preset views (Front, Back, Top, Isometric, etc.).
+ *
+ * @best-practice
+ * - Use `setView` for UI buttons that switch camera angles.
+ * - Leverage `ViewPresets` for readable code when using standard views.
+ */
+/**
+ * Smoothly switches the camera to the optimal angle for the model.
  *
- * ✨ 优化内容：
- * - 复用 followModels 逻辑，避免代码重复
- * - 支持更多视角
- * - 配置选项增强
- * - 返回 Promise 支持链式调用
- * - 支持取消动画
+ * Features:
+ * - Reuses followModels logic to avoid code duplication
+ * - Supports more angles
+ * - Enhanced configuration options
+ * - Returns Promise to support chaining
+ * - Supports animation cancellation
  *
- * @param camera       THREE.PerspectiveCamera 相机实例
- * @param controls     OrbitControls 控制器实例
- * @param targetObj    THREE.Object3D 模型对象
- * @param position     视角位置
- * @param options      配置选项
+ * @param camera       THREE.PerspectiveCamera instance
+ * @param controls     OrbitControls instance
+ * @param targetObj    THREE.Object3D model object
+ * @param position     View position
+ * @param options      Configuration options
  * @returns Promise<void>
  */
 function setView(camera, controls, targetObj, position = 'front', options = {}) {
     const { distanceFactor = 0.8, duration = 1000, easing = 'easeInOut', onProgress } = options;
-    // ✨ 边界检查
+    // Boundary check
     if (!targetObj) {
-        console.warn('setView: 目标对象为空');
+        console.warn('setView: Target object is empty');
         return Promise.reject(new Error('Target object is required'));
     }
     try {
-        // 计算包围盒
+        // Calculate bounding box
         const box = new THREE.Box3().setFromObject(targetObj);
         if (!isFinite(box.min.x)) {
-            console.warn('setView: 包围盒计算失败');
+            console.warn('setView: Failed to calculate bounding box');
             return Promise.reject(new Error('Invalid bounding box'));
         }
-        const center = box.getCenter(new THREE.Vector3());
-        const size = box.getSize(new THREE.Vector3());
-        const maxSize = Math.max(size.x, size.y, size.z);
-        // ✨ 使用映射表简化视角计算
+        // Use mapping table for creating view angles
         const viewAngles = {
             'front': { azimuth: 0, elevation: 0 },
             'back': { azimuth: Math.PI, elevation: 0 },
@@ -1283,7 +1414,7 @@ function setView(camera, controls, targetObj, position = 'front', options = {})
             'iso': { azimuth: Math.PI / 4, elevation: Math.PI / 4 }
         };
         const angle = viewAngles[position] || viewAngles.front;
-        // ✨ 复用 followModels，避免代码重复
+        // Reuse followModels to avoid code duplication
         return followModels(camera, targetObj, {
             duration,
             padding: distanceFactor,
@@ -1295,191 +1426,194 @@ function setView(camera, controls, targetObj, position = 'front', options = {})
         });
     }
     catch (error) {
-        console.error('setView: 执行失败', error);
+        console.error('setView: Execution failed', error);
         return Promise.reject(error);
     }
 }
 /**
- * ✨ 取消视角切换动画
+ * Cancel view switch animation
  */
 function cancelSetView(camera) {
     cancelFollow(camera);
 }
 /**
- * ✨ 预设视角快捷方法
+ * Preset view shortcut methods
  */
 const ViewPresets = {
     /**
-     * 前视图
+     * Front View
      */
     front: (camera, controls, target, options) => setView(camera, controls, target, 'front', options),
     /**
-     * 等距视图
+     * Isometric View
      */
     isometric: (camera, controls, target, options) => setView(camera, controls, target, 'iso', options),
     /**
-     * 顶视图
+     * Top View
      */
     top: (camera, controls, target, options) => setView(camera, controls, target, 'top', options)
 };
 
-/******************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */
-/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
-
-
-function __awaiter(thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-}
-
-typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+let globalConfig = {
+    dracoDecoderPath: '/draco/',
+    ktx2TranscoderPath: '/basis/',
 };
+/**
+ * Update global loader configuration (e.g., set path to CDN)
+ */
+function setLoaderConfig(config) {
+    globalConfig = { ...globalConfig, ...config };
+}
+/**
+ * Get current global loader configuration
+ */
+function getLoaderConfig() {
+    return globalConfig;
+}
 
+/**
+ * @file modelLoader.ts
+ * @description
+ * Utility to load 3D models (GLTF, FBX, OBJ, PLY, STL) from URLs.
+ *
+ * @best-practice
+ * - Use `loadModelByUrl` for a unified loading interface.
+ * - Supports Draco compression and KTX2 textures for GLTF.
+ * - Includes optimization options like geometry merging and texture downscaling.
+ */
 const DEFAULT_OPTIONS$1 = {
     useKTX2: false,
     mergeGeometries: false,
     maxTextureSize: null,
     useSimpleMaterials: false,
     skipSkinned: true,
+    useCache: true,
 };
-/** 自动根据扩展名决定启用哪些选项（智能判断） */
+const modelCache = new Map();
+/** Automatically determine which options to enable based on extension (smart judgment) */
 function normalizeOptions(url, opts) {
     const ext = (url.split('.').pop() || '').toLowerCase();
-    const merged = Object.assign(Object.assign({}, DEFAULT_OPTIONS$1), opts);
+    const merged = { ...DEFAULT_OPTIONS$1, ...opts };
     if (ext === 'gltf' || ext === 'glb') {
-        // gltf/glb 默认尝试 draco/ktx2，如果用户没填
+        const globalConfig = getLoaderConfig();
+        // gltf/glb defaults to trying draco/ktx2 if user didn't specify
         if (merged.dracoDecoderPath === undefined)
-            merged.dracoDecoderPath = '/draco/';
+            merged.dracoDecoderPath = globalConfig.dracoDecoderPath;
         if (merged.useKTX2 === undefined)
             merged.useKTX2 = true;
         if (merged.ktx2TranscoderPath === undefined)
-            merged.ktx2TranscoderPath = '/basis/';
+            merged.ktx2TranscoderPath = globalConfig.ktx2TranscoderPath;
     }
     else {
-        // fbx/obj/ply/stl 等不需要 draco/ktx2
+        // fbx/obj/ply/stl etc. do not need draco/ktx2
         merged.dracoDecoderPath = null;
         merged.ktx2TranscoderPath = null;
         merged.useKTX2 = false;
     }
     return merged;
 }
-function loadModelByUrl(url_1) {
-    return __awaiter(this, arguments, void 0, function* (url, options = {}) {
-        var _a, _b;
-        if (!url)
-            throw new Error('url required');
-        const ext = (url.split('.').pop() || '').toLowerCase();
-        const opts = normalizeOptions(url, options);
-        const manager = (_a = opts.manager) !== null && _a !== void 0 ? _a : new THREE.LoadingManager();
-        let loader;
-        if (ext === 'gltf' || ext === 'glb') {
-            const { GLTFLoader } = yield import('three/examples/jsm/loaders/GLTFLoader.js');
-            const gltfLoader = new GLTFLoader(manager);
-            if (opts.dracoDecoderPath) {
-                const { DRACOLoader } = yield import('three/examples/jsm/loaders/DRACOLoader.js');
-                const draco = new DRACOLoader();
-                draco.setDecoderPath(opts.dracoDecoderPath);
-                gltfLoader.setDRACOLoader(draco);
-            }
-            if (opts.useKTX2 && opts.ktx2TranscoderPath) {
-                const { KTX2Loader } = yield import('three/examples/jsm/loaders/KTX2Loader.js');
-                const ktx2Loader = new KTX2Loader().setTranscoderPath(opts.ktx2TranscoderPath);
-                gltfLoader.__ktx2Loader = ktx2Loader;
-            }
-            loader = gltfLoader;
-        }
-        else if (ext === 'fbx') {
-            const { FBXLoader } = yield import('three/examples/jsm/loaders/FBXLoader.js');
-            loader = new FBXLoader(manager);
-        }
-        else if (ext === 'obj') {
-            const { OBJLoader } = yield import('three/examples/jsm/loaders/OBJLoader.js');
-            loader = new OBJLoader(manager);
-        }
-        else if (ext === 'ply') {
-            const { PLYLoader } = yield import('three/examples/jsm/loaders/PLYLoader.js');
-            loader = new PLYLoader(manager);
-        }
-        else if (ext === 'stl') {
-            const { STLLoader } = yield import('three/examples/jsm/loaders/STLLoader.js');
-            loader = new STLLoader(manager);
+async function loadModelByUrl(url, options = {}) {
+    if (!url)
+        throw new Error('url required');
+    const ext = (url.split('.').pop() || '').toLowerCase();
+    const opts = normalizeOptions(url, options);
+    const manager = opts.manager ?? new THREE.LoadingManager();
+    // Cache key includes URL and relevant optimization options
+    const cacheKey = `${url}_${opts.mergeGeometries}_${opts.maxTextureSize}_${opts.useSimpleMaterials}`;
+    if (opts.useCache && modelCache.has(cacheKey)) {
+        return modelCache.get(cacheKey).clone();
+    }
+    let loader;
+    if (ext === 'gltf' || ext === 'glb') {
+        const { GLTFLoader } = await import('three/examples/jsm/loaders/GLTFLoader.js');
+        const gltfLoader = new GLTFLoader(manager);
+        if (opts.dracoDecoderPath) {
+            const { DRACOLoader } = await import('three/examples/jsm/loaders/DRACOLoader.js');
+            const draco = new DRACOLoader();
+            draco.setDecoderPath(opts.dracoDecoderPath);
+            gltfLoader.setDRACOLoader(draco);
         }
-        else {
-            throw new Error(`Unsupported model extension: .${ext}`);
-        }
-        const object = yield new Promise((resolve, reject) => {
-            loader.load(url, (res) => {
-                var _a;
-                if (ext === 'gltf' || ext === 'glb') {
-                    const sceneObj = res.scene || res;
-                    // --- 关键：把 animations 暴露到 scene.userData（或 scene.animations）上 ---
-                    // 这样调用方只要拿到 sceneObj，就能通过 sceneObj.userData.animations 读取到 clips
-                    sceneObj.userData = (sceneObj === null || sceneObj === void 0 ? void 0 : sceneObj.userData) || {};
-                    sceneObj.userData.animations = (_a = res.animations) !== null && _a !== void 0 ? _a : [];
-                    resolve(sceneObj);
-                }
-                else {
-                    resolve(res);
-                }
-            }, undefined, (err) => reject(err));
-        });
-        // 优化
-        object.traverse((child) => {
-            var _a, _b, _c;
-            const mesh = child;
-            if (mesh.isMesh && mesh.geometry && !mesh.geometry.isBufferGeometry) {
-                try {
-                    mesh.geometry = (_c = (_b = (_a = new THREE.BufferGeometry()).fromGeometry) === null || _b === void 0 ? void 0 : _b.call(_a, mesh.geometry)) !== null && _c !== void 0 ? _c : mesh.geometry;
-                }
-                catch (_d) { }
-            }
-        });
-        if (opts.maxTextureSize && opts.maxTextureSize > 0)
-            downscaleTexturesInObject(object, opts.maxTextureSize);
-        if (opts.useSimpleMaterials) {
-            object.traverse((child) => {
-                const m = child.material;
-                if (!m)
-                    return;
-                if (Array.isArray(m))
-                    child.material = m.map((mat) => toSimpleMaterial(mat));
-                else
-                    child.material = toSimpleMaterial(m);
-            });
+        if (opts.useKTX2 && opts.ktx2TranscoderPath) {
+            const { KTX2Loader } = await import('three/examples/jsm/loaders/KTX2Loader.js');
+            const ktx2Loader = new KTX2Loader().setTranscoderPath(opts.ktx2TranscoderPath);
+            gltfLoader.__ktx2Loader = ktx2Loader;
         }
-        if (opts.mergeGeometries) {
-            try {
-                yield tryMergeGeometries(object, { skipSkinned: (_b = opts.skipSkinned) !== null && _b !== void 0 ? _b : true });
+        loader = gltfLoader;
+    }
+    else if (ext === 'fbx') {
+        const { FBXLoader } = await import('three/examples/jsm/loaders/FBXLoader.js');
+        loader = new FBXLoader(manager);
+    }
+    else if (ext === 'obj') {
+        const { OBJLoader } = await import('three/examples/jsm/loaders/OBJLoader.js');
+        loader = new OBJLoader(manager);
+    }
+    else if (ext === 'ply') {
+        const { PLYLoader } = await import('three/examples/jsm/loaders/PLYLoader.js');
+        loader = new PLYLoader(manager);
+    }
+    else if (ext === 'stl') {
+        const { STLLoader } = await import('three/examples/jsm/loaders/STLLoader.js');
+        loader = new STLLoader(manager);
+    }
+    else {
+        throw new Error(`Unsupported model extension: .${ext}`);
+    }
+    const object = await new Promise((resolve, reject) => {
+        loader.load(url, (res) => {
+            if (ext === 'gltf' || ext === 'glb') {
+                const sceneObj = res.scene || res;
+                // --- Critical: Expose animations to scene.userData (or scene.animations) ---
+                // So the caller can access clips simply by getting sceneObj.userData.animations
+                sceneObj.userData = sceneObj?.userData || {};
+                sceneObj.userData.animations = res.animations ?? [];
+                resolve(sceneObj);
             }
-            catch (e) {
-                console.warn('mergeGeometries failed', e);
+            else {
+                resolve(res);
+            }
+        }, undefined, (err) => reject(err));
+    });
+    // Optimize
+    object.traverse((child) => {
+        const mesh = child;
+        if (mesh.isMesh && mesh.geometry && !mesh.geometry.isBufferGeometry) {
+            try {
+                mesh.geometry = new THREE.BufferGeometry().fromGeometry?.(mesh.geometry) ?? mesh.geometry;
             }
+            catch { }
         }
-        return object;
     });
+    if (opts.maxTextureSize && opts.maxTextureSize > 0)
+        await downscaleTexturesInObject(object, opts.maxTextureSize);
+    if (opts.useSimpleMaterials) {
+        object.traverse((child) => {
+            const m = child.material;
+            if (!m)
+                return;
+            if (Array.isArray(m))
+                child.material = m.map((mat) => toSimpleMaterial(mat));
+            else
+                child.material = toSimpleMaterial(m);
+        });
+    }
+    if (opts.mergeGeometries) {
+        try {
+            await tryMergeGeometries(object, { skipSkinned: opts.skipSkinned ?? true });
+        }
+        catch (e) {
+            console.warn('mergeGeometries failed', e);
+        }
+    }
+    if (opts.useCache) {
+        modelCache.set(cacheKey, object);
+        return object.clone();
+    }
+    return object;
 }
-/** 运行时下采样网格中的贴图到 maxSize（canvas drawImage）以节省 GPU 内存 */
-function downscaleTexturesInObject(obj, maxSize) {
+/** Runtime downscale textures in mesh to maxSize (createImageBitmap or canvas) to save GPU memory */
+async function downscaleTexturesInObject(obj, maxSize) {
+    const tasks = [];
     obj.traverse((ch) => {
         if (!ch.isMesh)
             return;
@@ -1498,115 +1632,128 @@ function downscaleTexturesInObject(obj, maxSize) {
             const max = maxSize;
             if (image.width <= max && image.height <= max)
                 return;
-            // downscale using canvas (sync, may be heavy for many textures)
-            try {
-                const scale = Math.min(max / image.width, max / image.height);
-                const canvas = document.createElement('canvas');
-                canvas.width = Math.floor(image.width * scale);
-                canvas.height = Math.floor(image.height * scale);
-                const ctx = canvas.getContext('2d');
-                if (ctx) {
-                    ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
-                    const newTex = new THREE.Texture(canvas);
-                    newTex.needsUpdate = true;
-                    // copy common settings (encoding etc)
-                    newTex.encoding = tex.encoding;
-                    mat[p] = newTex;
+            tasks.push((async () => {
+                try {
+                    const scale = Math.min(max / image.width, max / image.height);
+                    const newWidth = Math.floor(image.width * scale);
+                    const newHeight = Math.floor(image.height * scale);
+                    let newSource;
+                    if (typeof createImageBitmap !== 'undefined') {
+                        newSource = await createImageBitmap(image, {
+                            resizeWidth: newWidth,
+                            resizeHeight: newHeight,
+                            resizeQuality: 'high'
+                        });
+                    }
+                    else {
+                        // Fallback for environments without createImageBitmap
+                        const canvas = document.createElement('canvas');
+                        canvas.width = newWidth;
+                        canvas.height = newHeight;
+                        const ctx = canvas.getContext('2d');
+                        if (ctx) {
+                            ctx.drawImage(image, 0, 0, newWidth, newHeight);
+                            newSource = canvas;
+                        }
+                    }
+                    if (newSource) {
+                        const newTex = new THREE.Texture(newSource);
+                        newTex.needsUpdate = true;
+                        newTex.encoding = tex.encoding;
+                        mat[p] = newTex;
+                    }
                 }
-            }
-            catch (e) {
-                console.warn('downscale texture failed', e);
-            }
+                catch (e) {
+                    console.warn('downscale texture failed', e);
+                }
+            })());
         });
     });
+    await Promise.all(tasks);
 }
 /**
- * 尝试合并 object 中的几何体（只合并：非透明、非 SkinnedMesh、attribute 集合兼容的 BufferGeometry）
- * - 合并前会把每个 mesh 的几何体应用 world matrix（so merged geometry in world space）
- * - 合并会按材质 UUID 分组（不同材质不能合并）
- * - 合并函数会兼容 BufferGeometryUtils 的常见导出名
+ * Try to merge geometries in object (Only merge: non-transparent, non-SkinnedMesh, attribute compatible BufferGeometry)
+ * - Before merging, apply world matrix to each mesh's geometry (so merged geometry is in world space)
+ * - Merging will group by material UUID (different materials cannot be merged)
+ * - Merge function is compatible with common export names of BufferGeometryUtils
  */
-function tryMergeGeometries(root, opts) {
-    return __awaiter(this, void 0, void 0, function* () {
-        // collect meshes by material uuid
-        const groups = new Map();
-        root.traverse((ch) => {
-            var _a;
-            if (!ch.isMesh)
-                return;
-            const mesh = ch;
-            if (opts.skipSkinned && mesh.isSkinnedMesh)
-                return;
-            const mat = mesh.material;
-            // don't merge transparent or morph-enabled or skinned meshes
-            if (!mesh.geometry || mesh.visible === false)
-                return;
-            if (mat && mat.transparent)
-                return;
-            const geom = mesh.geometry.clone();
-            mesh.updateWorldMatrix(true, false);
-            geom.applyMatrix4(mesh.matrixWorld);
-            // ensure attributes compatible? we'll rely on merge function to return null if incompatible
-            const key = (mat && mat.uuid) || 'default';
-            const bucket = (_a = groups.get(key)) !== null && _a !== void 0 ? _a : { material: mat !== null && mat !== void 0 ? mat : new THREE.MeshStandardMaterial(), geoms: [] };
-            bucket.geoms.push(geom);
-            groups.set(key, bucket);
-            // mark for removal (we'll remove meshes after)
-            mesh.userData.__toRemoveForMerge = true;
-        });
-        if (groups.size === 0)
+async function tryMergeGeometries(root, opts) {
+    // collect meshes by material uuid
+    const groups = new Map();
+    root.traverse((ch) => {
+        if (!ch.isMesh)
             return;
-        // dynamic import BufferGeometryUtils and find merge function name
-        const bufUtilsMod = yield import('three/examples/jsm/utils/BufferGeometryUtils.js');
-        // use || chain (avoid mixing ?? with || without parentheses)
-        const mergeFn = bufUtilsMod.mergeBufferGeometries ||
-            bufUtilsMod.mergeGeometries ||
-            bufUtilsMod.mergeBufferGeometries || // defensive duplicate
-            bufUtilsMod.mergeGeometries;
-        if (!mergeFn)
-            throw new Error('No merge function found in BufferGeometryUtils');
-        // for each group, try merge
-        for (const [key, { material, geoms }] of groups) {
-            if (geoms.length <= 1) {
-                // nothing to merge
-                continue;
-            }
-            // call merge function - signature typically mergeBufferGeometries(array, useGroups)
-            const merged = mergeFn(geoms, false);
-            if (!merged) {
-                console.warn('merge returned null for group', key);
-                continue;
+        const mesh = ch;
+        if (opts.skipSkinned && mesh.isSkinnedMesh)
+            return;
+        const mat = mesh.material;
+        // don't merge transparent or morph-enabled or skinned meshes
+        if (!mesh.geometry || mesh.visible === false)
+            return;
+        if (mat && mat.transparent)
+            return;
+        const geom = mesh.geometry.clone();
+        mesh.updateWorldMatrix(true, false);
+        geom.applyMatrix4(mesh.matrixWorld);
+        // ensure attributes compatible? we'll rely on merge function to return null if incompatible
+        const key = (mat && mat.uuid) || 'default';
+        const bucket = groups.get(key) ?? { material: mat ?? new THREE.MeshStandardMaterial(), geoms: [] };
+        bucket.geoms.push(geom);
+        groups.set(key, bucket);
+        // mark for removal (we'll remove meshes after)
+        mesh.userData.__toRemoveForMerge = true;
+    });
+    if (groups.size === 0)
+        return;
+    // dynamic import BufferGeometryUtils and find merge function name
+    const bufUtilsMod = await import('three/examples/jsm/utils/BufferGeometryUtils.js');
+    // use || chain (avoid mixing ?? with || without parentheses)
+    const mergeFn = bufUtilsMod.mergeBufferGeometries ||
+        bufUtilsMod.mergeGeometries ||
+        bufUtilsMod.mergeBufferGeometries || // defensive duplicate
+        bufUtilsMod.mergeGeometries;
+    if (!mergeFn)
+        throw new Error('No merge function found in BufferGeometryUtils');
+    // for each group, try merge
+    for (const [key, { material, geoms }] of groups) {
+        if (geoms.length <= 1) {
+            // nothing to merge
+            continue;
+        }
+        // call merge function - signature typically mergeBufferGeometries(array, useGroups)
+        const merged = mergeFn(geoms, false);
+        if (!merged) {
+            console.warn('merge returned null for group', key);
+            continue;
+        }
+        // create merged mesh at root (world-space geometry already applied)
+        const mergedMesh = new THREE.Mesh(merged, material);
+        root.add(mergedMesh);
+    }
+    // now remove original meshes flagged for removal
+    const toRemove = [];
+    root.traverse((ch) => {
+        if (ch.userData?.__toRemoveForMerge)
+            toRemove.push(ch);
+    });
+    toRemove.forEach((m) => {
+        if (m.parent)
+            m.parent.remove(m);
+        // free original resources (geometries already cloned/applied), but careful with shared materials
+        if (m.isMesh) {
+            const mm = m;
+            try {
+                mm.geometry.dispose();
             }
-            // create merged mesh at root (world-space geometry already applied)
-            const mergedMesh = new THREE.Mesh(merged, material);
-            root.add(mergedMesh);
+            catch { }
+            // we do NOT dispose material because it may be reused by mergedMesh
         }
-        // now remove original meshes flagged for removal
-        const toRemove = [];
-        root.traverse((ch) => {
-            var _a;
-            if ((_a = ch.userData) === null || _a === void 0 ? void 0 : _a.__toRemoveForMerge)
-                toRemove.push(ch);
-        });
-        toRemove.forEach((m) => {
-            if (m.parent)
-                m.parent.remove(m);
-            // free original resources (geometries already cloned/applied), but careful with shared materials
-            if (m.isMesh) {
-                const mm = m;
-                try {
-                    mm.geometry.dispose();
-                }
-                catch (_a) { }
-                // we do NOT dispose material because it may be reused by mergedMesh
-            }
-        });
     });
 }
 /* ---------------------
-   释放工具
+   Dispose Utils
    --------------------- */
-/** 彻底释放对象：几何体，材质和其贴图（危险：共享资源会被释放） */
+/** Completely dispose object: geometry, material and its textures (Danger: shared resources will be disposed) */
 function disposeObject(obj) {
     if (!obj)
         return;
@@ -1617,7 +1764,7 @@ function disposeObject(obj) {
                 try {
                     m.geometry.dispose();
                 }
-                catch (_a) { }
+                catch { }
             }
             const mat = m.material;
             if (mat) {
@@ -1629,7 +1776,7 @@ function disposeObject(obj) {
         }
     });
 }
-/** 释放材质及其贴图 */
+/** Dispose material and its textures */
 function disposeMaterial(mat) {
     if (!mat)
         return;
@@ -1639,232 +1786,244 @@ function disposeMaterial(mat) {
             try {
                 mat[k].dispose();
             }
-            catch (_a) { }
+            catch { }
         }
     });
     try {
         if (typeof mat.dispose === 'function')
             mat.dispose();
     }
-    catch (_a) { }
+    catch { }
+}
+// Helper to convert to simple material (stub)
+function toSimpleMaterial(mat) {
+    // Basic implementation, preserve color/map
+    const m = new THREE.MeshBasicMaterial();
+    if (mat.color)
+        m.color.copy(mat.color);
+    if (mat.map)
+        m.map = mat.map;
+    return m;
 }
 
-/** 默认值 */
+/**
+ * @file skyboxLoader.ts
+ * @description
+ * Utility for loading skyboxes (CubeTexture or Equirectangular/HDR).
+ *
+ * @best-practice
+ * - Use `loadSkybox` for a unified interface.
+ * - Supports internal caching to avoid reloading the same skybox.
+ * - Can set background and environment map independently.
+ */
+/** Default Values */
 const DEFAULT_OPTIONS = {
     setAsBackground: true,
     setAsEnvironment: true,
     useSRGBEncoding: true,
     cache: true
 };
-/** 内部缓存：key -> { handle, refCount } */
+/** Internal Cache: key -> { handle, refCount } */
 const cubeCache = new Map();
 const equirectCache = new Map();
 /* -------------------------------------------
-   公共函数：加载 skybox（自动选 cube 或 equirect）
+   Public Function: Load skybox (Automatically choose cube or equirect)
    ------------------------------------------- */
 /**
- * 加载立方体贴图（6张）
- * @param renderer THREE.WebGLRenderer - 用于 PMREM 生成环境贴图
+ * Load Cube Texture (6 images)
+ * @param renderer THREE.WebGLRenderer - Used for PMREM generating environment map
  * @param scene THREE.Scene
- * @param paths string[] 6 张图片地址，顺序：[px, nx, py, ny, pz, nz]
+ * @param paths string[] 6 image paths, order: [px, nx, py, ny, pz, nz]
  * @param opts SkyboxOptions
  */
-function loadCubeSkybox(renderer_1, scene_1, paths_1) {
-    return __awaiter(this, arguments, void 0, function* (renderer, scene, paths, opts = {}) {
-        var _a, _b;
-        const options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), opts);
-        if (!Array.isArray(paths) || paths.length !== 6)
-            throw new Error('cube skybox requires 6 image paths');
-        const key = paths.join('|');
-        // 缓存处理
-        if (options.cache && cubeCache.has(key)) {
-            const rec = cubeCache.get(key);
-            rec.refCount += 1;
-            // reapply to scene (in case it was removed)
-            if (options.setAsBackground)
-                scene.background = rec.handle.backgroundTexture;
-            if (options.setAsEnvironment && rec.handle.envRenderTarget)
-                scene.environment = rec.handle.envRenderTarget.texture;
-            return rec.handle;
-        }
-        // 加载立方体贴图
-        const loader = new THREE.CubeTextureLoader();
-        const texture = yield new Promise((resolve, reject) => {
-            loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
-        });
-        // 设置编码与映射
-        if (options.useSRGBEncoding)
-            texture.encoding = THREE.sRGBEncoding;
-        texture.mapping = THREE.CubeReflectionMapping;
-        // apply as background if required
+async function loadCubeSkybox(renderer, scene, paths, opts = {}) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    if (!Array.isArray(paths) || paths.length !== 6)
+        throw new Error('cube skybox requires 6 image paths');
+    const key = paths.join('|');
+    // Cache handling
+    if (options.cache && cubeCache.has(key)) {
+        const rec = cubeCache.get(key);
+        rec.refCount += 1;
+        // reapply to scene (in case it was removed)
         if (options.setAsBackground)
-            scene.background = texture;
-        // environment: use PMREM to produce a proper prefiltered env map for PBR
-        let pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE.PMREMGenerator(renderer);
-        (_b = pmremGenerator.compileCubemapShader) === null || _b === void 0 ? void 0 : _b.call(pmremGenerator);
-        // fromCubemap might be available in your three.js; fallback to fromEquirectangular approach if not
-        let envRenderTarget = null;
-        if (pmremGenerator.fromCubemap) {
-            envRenderTarget = pmremGenerator.fromCubemap(texture);
+            scene.background = rec.handle.backgroundTexture;
+        if (options.setAsEnvironment && rec.handle.envRenderTarget)
+            scene.environment = rec.handle.envRenderTarget.texture;
+        return rec.handle;
+    }
+    // Load cube texture
+    const loader = new THREE.CubeTextureLoader();
+    const texture = await new Promise((resolve, reject) => {
+        loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
+    });
+    // Set encoding and mapping
+    if (options.useSRGBEncoding)
+        texture.encoding = THREE.sRGBEncoding;
+    texture.mapping = THREE.CubeReflectionMapping;
+    // apply as background if required
+    if (options.setAsBackground)
+        scene.background = texture;
+    // environment: use PMREM to produce a proper prefiltered env map for PBR
+    let pmremGenerator = options.pmremGenerator ?? new THREE.PMREMGenerator(renderer);
+    pmremGenerator.compileCubemapShader?.( /* optional */);
+    // fromCubemap might be available in your three.js; fallback to fromEquirectangular approach if not
+    let envRenderTarget = null;
+    if (pmremGenerator.fromCubemap) {
+        envRenderTarget = pmremGenerator.fromCubemap(texture);
+    }
+    else {
+        // Fallback: render cube to env map by using generator.fromEquirectangular with a converted equirect if needed.
+        // Simpler fallback: use the cube texture directly as environment (less correct for reflections).
+        envRenderTarget = null;
+    }
+    if (options.setAsEnvironment) {
+        if (envRenderTarget) {
+            scene.environment = envRenderTarget.texture;
         }
         else {
-            // Fallback: render cube to env map by using generator.fromEquirectangular with a converted equirect if needed.
-            // Simpler fallback: use the cube texture directly as environment (less correct for reflections).
-            envRenderTarget = null;
+            // fallback: use cube texture directly (works but not prefiltered)
+            scene.environment = texture;
         }
-        if (options.setAsEnvironment) {
-            if (envRenderTarget) {
-                scene.environment = envRenderTarget.texture;
+    }
+    const handle = {
+        key,
+        backgroundTexture: options.setAsBackground ? texture : null,
+        envRenderTarget: envRenderTarget,
+        pmremGenerator: options.pmremGenerator ? null : pmremGenerator, // only dispose if we created it
+        setAsBackground: !!options.setAsBackground,
+        setAsEnvironment: !!options.setAsEnvironment,
+        dispose() {
+            // remove from scene
+            if (options.setAsBackground && scene.background === texture)
+                scene.background = null;
+            if (options.setAsEnvironment && scene.environment) {
+                // only clear if it's the same texture we set
+                if (envRenderTarget && scene.environment === envRenderTarget.texture)
+                    scene.environment = null;
+                else if (scene.environment === texture)
+                    scene.environment = null;
             }
-            else {
-                // fallback: use cube texture directly (works but not prefiltered)
-                scene.environment = texture;
-            }
-        }
-        const handle = {
-            key,
-            backgroundTexture: options.setAsBackground ? texture : null,
-            envRenderTarget: envRenderTarget,
-            pmremGenerator: options.pmremGenerator ? null : pmremGenerator, // only dispose if we created it
-            setAsBackground: !!options.setAsBackground,
-            setAsEnvironment: !!options.setAsEnvironment,
-            dispose() {
-                // remove from scene
-                if (options.setAsBackground && scene.background === texture)
-                    scene.background = null;
-                if (options.setAsEnvironment && scene.environment) {
-                    // only clear if it's the same texture we set
-                    if (envRenderTarget && scene.environment === envRenderTarget.texture)
-                        scene.environment = null;
-                    else if (scene.environment === texture)
-                        scene.environment = null;
-                }
-                // dispose resources only if not cached/shared
-                if (envRenderTarget) {
-                    try {
-                        envRenderTarget.dispose();
-                    }
-                    catch (_a) { }
-                }
+            // dispose resources only if not cached/shared
+            if (envRenderTarget) {
                 try {
-                    texture.dispose();
+                    envRenderTarget.dispose();
                 }
-                catch (_b) { }
-                // dispose pmremGenerator we created
-                if (!options.pmremGenerator && pmremGenerator) {
-                    try {
-                        pmremGenerator.dispose();
-                    }
-                    catch (_c) { }
+                catch { }
+            }
+            try {
+                texture.dispose();
+            }
+            catch { }
+            // dispose pmremGenerator we created
+            if (!options.pmremGenerator && pmremGenerator) {
+                try {
+                    pmremGenerator.dispose();
                 }
+                catch { }
             }
-        };
-        if (options.cache)
-            cubeCache.set(key, { handle, refCount: 1 });
-        return handle;
-    });
+        }
+    };
+    if (options.cache)
+        cubeCache.set(key, { handle, refCount: 1 });
+    return handle;
 }
 /**
- * 加载等距/单图（支持 HDR via RGBELoader）
+ * Load Equirectangular/Single Image (Supports HDR via RGBELoader)
  * @param renderer THREE.WebGLRenderer
  * @param scene THREE.Scene
  * @param url string - *.hdr, *.exr, *.jpg, *.png
  * @param opts SkyboxOptions
  */
-function loadEquirectSkybox(renderer_1, scene_1, url_1) {
-    return __awaiter(this, arguments, void 0, function* (renderer, scene, url, opts = {}) {
-        var _a, _b;
-        const options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), opts);
-        const key = url;
-        if (options.cache && equirectCache.has(key)) {
-            const rec = equirectCache.get(key);
-            rec.refCount += 1;
-            if (options.setAsBackground)
-                scene.background = rec.handle.backgroundTexture;
-            if (options.setAsEnvironment && rec.handle.envRenderTarget)
-                scene.environment = rec.handle.envRenderTarget.texture;
-            return rec.handle;
-        }
-        // 动态导入 RGBELoader（用于 .hdr/.exr），如果加载的是普通 jpg/png 可直接用 TextureLoader
-        const isHDR = /\.hdr$|\.exr$/i.test(url);
-        let hdrTexture;
-        if (isHDR) {
-            const { RGBELoader } = yield import('three/examples/jsm/loaders/RGBELoader.js');
-            hdrTexture = yield new Promise((resolve, reject) => {
-                new RGBELoader().load(url, (tex) => resolve(tex), undefined, (err) => reject(err));
-            });
-            // RGBE textures typically use LinearEncoding
-            hdrTexture.encoding = THREE.LinearEncoding;
-        }
-        else {
-            // ordinary image - use TextureLoader
-            const loader = new THREE.TextureLoader();
-            hdrTexture = yield new Promise((resolve, reject) => {
-                loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
-            });
-            if (options.useSRGBEncoding)
-                hdrTexture.encoding = THREE.sRGBEncoding;
-        }
-        // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
-        const pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE.PMREMGenerator(renderer);
-        (_b = pmremGenerator.compileEquirectangularShader) === null || _b === void 0 ? void 0 : _b.call(pmremGenerator);
-        const envRenderTarget = pmremGenerator.fromEquirectangular(hdrTexture);
-        // envTexture to use for scene.environment
-        const envTexture = envRenderTarget.texture;
-        // set background and/or environment
-        if (options.setAsBackground) {
-            // for background it's ok to use the equirect texture directly or the envTexture
-            // envTexture is cubemap-like and usually better for reflections; using it as background creates cube-projected look
-            scene.background = envTexture;
-        }
-        if (options.setAsEnvironment) {
-            scene.environment = envTexture;
-        }
-        // We can dispose the original hdrTexture (the PMREM target contains the needed data)
-        try {
-            hdrTexture.dispose();
-        }
-        catch (_c) { }
-        const handle = {
-            key,
-            backgroundTexture: options.setAsBackground ? envTexture : null,
-            envRenderTarget,
-            pmremGenerator: options.pmremGenerator ? null : pmremGenerator,
-            setAsBackground: !!options.setAsBackground,
-            setAsEnvironment: !!options.setAsEnvironment,
-            dispose() {
-                if (options.setAsBackground && scene.background === envTexture)
-                    scene.background = null;
-                if (options.setAsEnvironment && scene.environment === envTexture)
-                    scene.environment = null;
+async function loadEquirectSkybox(renderer, scene, url, opts = {}) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    const key = url;
+    if (options.cache && equirectCache.has(key)) {
+        const rec = equirectCache.get(key);
+        rec.refCount += 1;
+        if (options.setAsBackground)
+            scene.background = rec.handle.backgroundTexture;
+        if (options.setAsEnvironment && rec.handle.envRenderTarget)
+            scene.environment = rec.handle.envRenderTarget.texture;
+        return rec.handle;
+    }
+    // Dynamically import RGBELoader (for .hdr/.exr), if loading normal jpg/png directly use TextureLoader
+    const isHDR = /\.hdr$|\.exr$/i.test(url);
+    let hdrTexture;
+    if (isHDR) {
+        const { RGBELoader } = await import('three/examples/jsm/loaders/RGBELoader.js');
+        hdrTexture = await new Promise((resolve, reject) => {
+            new RGBELoader().load(url, (tex) => resolve(tex), undefined, (err) => reject(err));
+        });
+        // RGBE textures typically use LinearEncoding
+        hdrTexture.encoding = THREE.LinearEncoding;
+    }
+    else {
+        // ordinary image - use TextureLoader
+        const loader = new THREE.TextureLoader();
+        hdrTexture = await new Promise((resolve, reject) => {
+            loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
+        });
+        if (options.useSRGBEncoding)
+            hdrTexture.encoding = THREE.sRGBEncoding;
+    }
+    // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
+    const pmremGenerator = options.pmremGenerator ?? new THREE.PMREMGenerator(renderer);
+    pmremGenerator.compileEquirectangularShader?.();
+    const envRenderTarget = pmremGenerator.fromEquirectangular(hdrTexture);
+    // envTexture to use for scene.environment
+    const envTexture = envRenderTarget.texture;
+    // set background and/or environment
+    if (options.setAsBackground) {
+        // for background it's ok to use the equirect texture directly or the envTexture
+        // envTexture is cubemap-like and usually better for reflections; using it as background creates cube-projected look
+        scene.background = envTexture;
+    }
+    if (options.setAsEnvironment) {
+        scene.environment = envTexture;
+    }
+    // We can dispose the original hdrTexture (the PMREM target contains the needed data)
+    try {
+        hdrTexture.dispose();
+    }
+    catch { }
+    const handle = {
+        key,
+        backgroundTexture: options.setAsBackground ? envTexture : null,
+        envRenderTarget,
+        pmremGenerator: options.pmremGenerator ? null : pmremGenerator,
+        setAsBackground: !!options.setAsBackground,
+        setAsEnvironment: !!options.setAsEnvironment,
+        dispose() {
+            if (options.setAsBackground && scene.background === envTexture)
+                scene.background = null;
+            if (options.setAsEnvironment && scene.environment === envTexture)
+                scene.environment = null;
+            try {
+                envRenderTarget.dispose();
+            }
+            catch { }
+            if (!options.pmremGenerator && pmremGenerator) {
                 try {
-                    envRenderTarget.dispose();
-                }
-                catch (_a) { }
-                if (!options.pmremGenerator && pmremGenerator) {
-                    try {
-                        pmremGenerator.dispose();
-                    }
-                    catch (_b) { }
+                    pmremGenerator.dispose();
                 }
+                catch { }
             }
-        };
-        if (options.cache)
-            equirectCache.set(key, { handle, refCount: 1 });
-        return handle;
-    });
+        }
+    };
+    if (options.cache)
+        equirectCache.set(key, { handle, refCount: 1 });
+    return handle;
 }
-function loadSkybox(renderer_1, scene_1, params_1) {
-    return __awaiter(this, arguments, void 0, function* (renderer, scene, params, opts = {}) {
-        if (params.type === 'cube')
-            return loadCubeSkybox(renderer, scene, params.paths, opts);
-        return loadEquirectSkybox(renderer, scene, params.url, opts);
-    });
+async function loadSkybox(renderer, scene, params, opts = {}) {
+    if (params.type === 'cube')
+        return loadCubeSkybox(renderer, scene, params.paths, opts);
+    return loadEquirectSkybox(renderer, scene, params.url, opts);
 }
 /* -------------------------
-   缓存/引用计数 辅助方法
+   Cache / Reference Counting Helper Methods
    ------------------------- */
-/** 释放一个缓存的 skybox（会减少 refCount，refCount=0 时才真正 dispose） */
+/** Release a cached skybox (decrements refCount, only truly disposes when refCount=0) */
 function releaseSkybox(handle) {
     // check cube cache
     if (cubeCache.has(handle.key)) {
@@ -1889,85 +2048,94 @@ function releaseSkybox(handle) {
     // handle.dispose()
 }
 
-// utils/BlueSkyManager.ts - 优化版
 /**
- * BlueSkyManager - 优化版
+ * @file blueSkyManager.ts
+ * @description
+ * Global singleton manager for loading and managing HDR/EXR blue sky environment maps.
+ *
+ * @best-practice
+ * - Call `init` once before use.
+ * - Use `loadAsync` to load skyboxes with progress tracking.
+ * - Automatically handles PMREM generation for realistic lighting.
+ */
+/**
+ * BlueSkyManager - Optimized
  * ---------------------------------------------------------
- * 一个全局单例管理器，用于加载和管理基于 HDR/EXR 的蓝天白云环境贴图。
+ * A global singleton manager for loading and managing HDR/EXR based blue sky environment maps.
  *
- * ✨ 优化内容：
- * - 添加加载进度回调
- * - 支持加载取消
- * - 完善错误处理
- * - 返回 Promise 支持异步
- * - 添加加载状态管理
+ * Features:
+ * - Adds load progress callback
+ * - Supports load cancellation
+ * - Improved error handling
+ * - Returns Promise for async operation
+ * - Adds loading state management
  */
 class BlueSkyManager {
     constructor() {
-        /** 当前环境贴图的 RenderTarget，用于后续释放 */
+        /** RenderTarget for current environment map, used for subsequent disposal */
         this.skyRT = null;
-        /** 是否已经初始化 */
+        /** Whether already initialized */
         this.isInitialized = false;
-        /** ✨ 当前加载器，用于取消加载 */
+        /** Current loader, used for cancelling load */
         this.currentLoader = null;
-        /** ✨ 加载状态 */
+        /** Loading state */
         this.loadingState = 'idle';
     }
     /**
-     * 初始化
+     * Initialize
      * ---------------------------------------------------------
-     * 必须在使用 BlueSkyManager 之前调用一次。
-     * @param renderer WebGLRenderer 实例
-     * @param scene Three.js 场景
-     * @param exposure 曝光度 (默认 1.0)
+     * Must be called once before using BlueSkyManager.
+     * @param renderer WebGLRenderer instance
+     * @param scene Three.js Scene
+     * @param exposure Exposure (default 1.0)
      */
     init(renderer, scene, exposure = 1.0) {
         if (this.isInitialized) {
-            console.warn('BlueSkyManager: 已经初始化，跳过重复初始化');
+            console.warn('BlueSkyManager: Already initialized, skipping duplicate initialization');
             return;
         }
         this.renderer = renderer;
         this.scene = scene;
-        // 使用 ACESFilmicToneMapping，效果更接近真实
+        // Use ACESFilmicToneMapping, effect is closer to reality
         this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
         this.renderer.toneMappingExposure = exposure;
-        // 初始化 PMREM 生成器（全局只需一个）
+        // Initialize PMREM generator (only one needed globally)
         this.pmremGen = new THREE.PMREMGenerator(renderer);
         this.pmremGen.compileEquirectangularShader();
         this.isInitialized = true;
     }
     /**
-     * ✨ 加载蓝天 HDR/EXR 贴图并应用到场景（Promise 版本）
+     * Load blue sky HDR/EXR map and apply to scene (Promise version)
      * ---------------------------------------------------------
-     * @param exrPath HDR/EXR 文件路径
-     * @param options 加载选项
+     * @param exrPath HDR/EXR file path
+     * @param options Load options
      * @returns Promise<void>
      */
     loadAsync(exrPath, options = {}) {
         if (!this.isInitialized) {
             return Promise.reject(new Error('BlueSkyManager not initialized!'));
         }
-        // ✨ 取消之前的加载
+        // Cancel previous load
         this.cancelLoad();
         const { background = true, onProgress, onComplete, onError } = options;
         this.loadingState = 'loading';
         this.currentLoader = new EXRLoader();
         return new Promise((resolve, reject) => {
             this.currentLoader.load(exrPath, 
-            // 成功回调
+            // Success callback
             (texture) => {
                 try {
-                    // 设置贴图为球面反射映射
+                    // Set texture mapping to EquirectangularReflectionMapping
                     texture.mapping = THREE.EquirectangularReflectionMapping;
-                    // 清理旧的环境贴图
+                    // Clear old environment map
                     this.dispose();
-                    // 用 PMREM 生成高效的环境贴图
+                    // Generate efficient environment map using PMREM
                     this.skyRT = this.pmremGen.fromEquirectangular(texture);
-                    // 应用到场景：环境光照 & 背景
+                    // Apply to scene: Environment Lighting & Background
                     this.scene.environment = this.skyRT.texture;
                     if (background)
                         this.scene.background = this.skyRT.texture;
-                    // 原始 HDR/EXR 贴图用完即销毁，节省内存
+                    // Dispose original HDR/EXR texture immediately to save memory
                     texture.dispose();
                     this.loadingState = 'loaded';
                     this.currentLoader = null;
@@ -1985,14 +2153,14 @@ class BlueSkyManager {
                     reject(error);
                 }
             }, 
-            // 进度回调
+            // Progress callback
             (xhr) => {
                 if (onProgress && xhr.lengthComputable) {
                     const progress = xhr.loaded / xhr.total;
                     onProgress(progress);
                 }
             }, 
-            // 错误回调
+            // Error callback
             (err) => {
                 this.loadingState = 'error';
                 this.currentLoader = null;
@@ -2004,10 +2172,10 @@ class BlueSkyManager {
         });
     }
     /**
-     * 加载蓝天 HDR/EXR 贴图并应用到场景（同步 API，保持向后兼容）
+     * Load blue sky HDR/EXR map and apply to scene (Sync API, for backward compatibility)
      * ---------------------------------------------------------
-     * @param exrPath HDR/EXR 文件路径
-     * @param background 是否应用为场景背景 (默认 true)
+     * @param exrPath HDR/EXR file path
+     * @param background Whether to apply as scene background (default true)
      */
     load(exrPath, background = true) {
         this.loadAsync(exrPath, { background }).catch((error) => {
@@ -2015,32 +2183,32 @@ class BlueSkyManager {
         });
     }
     /**
-     * ✨ 取消当前加载
+     * Cancel current load
      */
     cancelLoad() {
         if (this.currentLoader) {
-            // EXRLoader 本身没有 abort 方法，但我们可以清空引用
+            // EXRLoader itself does not have abort method, but we can clear the reference
             this.currentLoader = null;
             this.loadingState = 'idle';
         }
     }
     /**
-     * ✨ 获取加载状态
+     * Get loading state
      */
     getLoadingState() {
         return this.loadingState;
     }
     /**
-     * ✨ 是否正在加载
+     * Is loading
      */
     isLoading() {
         return this.loadingState === 'loading';
     }
     /**
-     * 释放当前的天空贴图资源
+     * Release current sky texture resources
      * ---------------------------------------------------------
-     * 仅清理 skyRT，不销毁 PMREM
-     * 适用于切换 HDR/EXR 文件时调用
+     * Only cleans up skyRT, does not destroy PMREM
+     * Suitable for calling when switching HDR/EXR files
      */
     dispose() {
         if (this.skyRT) {
@@ -2054,53 +2222,61 @@ class BlueSkyManager {
             this.scene.environment = null;
     }
     /**
-     * 完全销毁 BlueSkyManager
+     * Completely destroy BlueSkyManager
      * ---------------------------------------------------------
-     * 包括 PMREMGenerator 的销毁
-     * 通常在场景彻底销毁或应用退出时调用
+     * Includes destruction of PMREMGenerator
+     * Usually called when the scene is completely destroyed or the application exits
      */
     destroy() {
-        var _a;
         this.cancelLoad();
         this.dispose();
-        (_a = this.pmremGen) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.pmremGen?.dispose();
         this.isInitialized = false;
         this.loadingState = 'idle';
     }
 }
 /**
- * 🌐 全局单例
+ * Global Singleton
  * ---------------------------------------------------------
- * 直接导出一个全局唯一的 BlueSkyManager 实例，
- * 保证整个应用中只用一个 PMREMGenerator，性能最佳。
+ * Directly export a globally unique BlueSkyManager instance,
+ * Ensuring only one PMREMGenerator is used throughout the application for best performance.
  */
 const BlueSky = new BlueSkyManager();
 
 /**
- * 创建模型标签（带连线和脉冲圆点）- 优化版
+ * @file modelsLabel.ts
+ * @description
+ * Creates interactive 2D labels (DOM elements) attached to 3D objects with connecting lines.
+ *
+ * @best-practice
+ * - Use `createModelsLabel` to annotate parts of a model.
+ * - Supports fading endpoints, pulsing dots, and custom styling.
+ * - Performance optimized with caching and RAF throttling.
+ */
+/**
+ * Create Model Labels (with connecting lines and pulsing dots) - Optimized
  *
- * ✨ 优化内容：
- * - 支持暂停/恢复更新
- * - 可配置更新间隔
- * - 淡入淡出效果
- * - 缓存包围盒计算
- * - RAF 管理优化
+ * Features:
+ * - Supports pause/resume
+ * - Configurable update interval
+ * - Fade in/out effects
+ * - Cached bounding box calculation
+ * - RAF management optimization
  */
 function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, options) {
-    var _a, _b, _c, _d, _e, _f;
     const cfg = {
-        fontSize: (options === null || options === void 0 ? void 0 : options.fontSize) || '12px',
-        color: (options === null || options === void 0 ? void 0 : options.color) || '#ffffff',
-        background: (options === null || options === void 0 ? void 0 : options.background) || '#1890ff',
-        padding: (options === null || options === void 0 ? void 0 : options.padding) || '6px 10px',
-        borderRadius: (options === null || options === void 0 ? void 0 : options.borderRadius) || '6px',
-        lift: (_a = options === null || options === void 0 ? void 0 : options.lift) !== null && _a !== void 0 ? _a : 100,
-        dotSize: (_b = options === null || options === void 0 ? void 0 : options.dotSize) !== null && _b !== void 0 ? _b : 6,
-        dotSpacing: (_c = options === null || options === void 0 ? void 0 : options.dotSpacing) !== null && _c !== void 0 ? _c : 2,
-        lineColor: (options === null || options === void 0 ? void 0 : options.lineColor) || 'rgba(200,200,200,0.7)',
-        lineWidth: (_d = options === null || options === void 0 ? void 0 : options.lineWidth) !== null && _d !== void 0 ? _d : 1,
-        updateInterval: (_e = options === null || options === void 0 ? void 0 : options.updateInterval) !== null && _e !== void 0 ? _e : 0, // ✨ 默认每帧更新
-        fadeInDuration: (_f = options === null || options === void 0 ? void 0 : options.fadeInDuration) !== null && _f !== void 0 ? _f : 300, // ✨ 淡入时长
+        fontSize: options?.fontSize || '12px',
+        color: options?.color || '#ffffff',
+        background: options?.background || '#1890ff',
+        padding: options?.padding || '6px 10px',
+        borderRadius: options?.borderRadius || '6px',
+        lift: options?.lift ?? 100,
+        dotSize: options?.dotSize ?? 6,
+        dotSpacing: options?.dotSpacing ?? 2,
+        lineColor: options?.lineColor || 'rgba(200,200,200,0.7)',
+        lineWidth: options?.lineWidth ?? 1,
+        updateInterval: options?.updateInterval ?? 0, // Default update every frame
+        fadeInDuration: options?.fadeInDuration ?? 300, // Fade-in duration
     };
     const container = document.createElement('div');
     container.style.position = 'absolute';
@@ -2123,13 +2299,13 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
     svg.style.zIndex = '1';
     container.appendChild(svg);
     let currentModel = parentModel;
-    let currentLabelsMap = Object.assign({}, modelLabelsMap);
+    let currentLabelsMap = { ...modelLabelsMap };
     let labels = [];
     let isActive = true;
-    let isPaused = false; // ✨ 暂停状态
-    let rafId = null; // ✨ RAF ID
-    let lastUpdateTime = 0; // ✨ 上次更新时间
-    // ✨ 注入样式（带淡入动画）
+    let isPaused = false;
+    let rafId = null;
+    let lastUpdateTime = 0;
+    // Inject styles (with fade-in animation)
     const styleId = 'three-model-label-styles';
     if (!document.getElementById(styleId)) {
         const style = document.createElement('style');
@@ -2168,14 +2344,14 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
     `;
         document.head.appendChild(style);
     }
-    // ✨ 获取或更新缓存的顶部位置
+    // Get or update cached top position
     const getObjectTopPosition = (labelData) => {
         const obj = labelData.object;
-        // 如果有缓存且对象没有变换，直接返回
+        // If cached and object hasn't transformed, return cached
         if (labelData.cachedTopPos && !obj.matrixWorldNeedsUpdate) {
             return labelData.cachedTopPos.clone();
         }
-        // 重新计算
+        // Recalculate
         const box = new THREE.Box3().setFromObject(obj);
         labelData.cachedBox = box;
         if (!box.isEmpty()) {
@@ -2204,9 +2380,8 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
         if (!currentModel)
             return;
         currentModel.traverse((child) => {
-            var _a;
             if (child.isMesh || child.type === 'Group') {
-                const labelText = (_a = Object.entries(currentLabelsMap).find(([key]) => child.name.includes(key))) === null || _a === void 0 ? void 0 : _a[1];
+                const labelText = Object.entries(currentLabelsMap).find(([key]) => child.name.includes(key))?.[1];
                 if (!labelText)
                     return;
                 const wrapper = document.createElement('div');
@@ -2253,20 +2428,20 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
                     wrapper,
                     dot,
                     line,
-                    cachedBox: null, // ✨ 初始化缓存
+                    cachedBox: null, // Initialize cache
                     cachedTopPos: null
                 });
             }
         });
     };
     rebuildLabels();
-    // ✨ 优化的更新函数
+    // Optimized update function
     const updateLabels = (timestamp) => {
         if (!isActive || isPaused) {
             rafId = null;
             return;
         }
-        // ✨ 节流处理
+        // Throttle
         if (cfg.updateInterval > 0 && timestamp - lastUpdateTime < cfg.updateInterval) {
             rafId = requestAnimationFrame(updateLabels);
             return;
@@ -2279,7 +2454,7 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
         svg.setAttribute('height', `${height}`);
         labels.forEach((labelData) => {
             const { el, wrapper, dot, line } = labelData;
-            const topWorld = getObjectTopPosition(labelData); // ✨ 使用缓存
+            const topWorld = getObjectTopPosition(labelData); // Use cache
             const topNDC = topWorld.clone().project(camera);
             const modelX = (topNDC.x * 0.5 + 0.5) * width + rect.left;
             const modelY = (-(topNDC.y * 0.5) + 0.5) * height + rect.top;
@@ -2311,10 +2486,10 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
             rebuildLabels();
         },
         updateLabelsMap(newMap) {
-            currentLabelsMap = Object.assign({}, newMap);
+            currentLabelsMap = { ...newMap };
             rebuildLabels();
         },
-        // ✨ 暂停更新
+        // Pause update
         pause() {
             isPaused = true;
             if (rafId !== null) {
@@ -2322,7 +2497,7 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
                 rafId = null;
             }
         },
-        // ✨ 恢复更新
+        // Resume update
         resume() {
             if (!isPaused)
                 return;
@@ -2343,10 +2518,34 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
     };
 }
 
+/**
+ * @file exploder.ts
+ * @description
+ * GroupExploder - Three.js based model explosion effect tool (Vue3 + TS Support)
+ * ----------------------------------------------------------------------
+ * This tool is used to perform "explode / restore" animations on a set of specified Meshes:
+ *  - Initialize only once (onMounted)
+ *  - Supports dynamic switching of models and automatically restores the explosion state of the previous model
+ *  - Supports multiple arrangement modes (ring / spiral / grid / radial)
+ *  - Supports automatic transparency for non-exploded objects (dimOthers)
+ *  - Supports automatic camera positioning to the best observation point
+ *  - All animations use native requestAnimationFrame
+ *
+ * @best-practice
+ * - Initialize in `onMounted`.
+ * - Use `setMeshes` to update the active set of meshes to explode.
+ * - Call `explode()` to trigger the effect and `restore()` to reset.
+ */
 function easeInOutQuad(t) {
     return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
 }
 class GroupExploder {
+    /**
+     * Constructor
+     * @param scene Three.js Scene instance
+     * @param camera Three.js Camera (usually PerspectiveCamera)
+     * @param controls OrbitControls instance (must be bound to camera)
+     */
     constructor(scene, camera, controls) {
         // sets and snapshots
         this.currentSet = null;
@@ -2378,211 +2577,210 @@ class GroupExploder {
         this.log('init() called');
     }
     /**
-     * setMeshes(newSet):
+     * Set the current set of meshes for explosion.
      * - Detects content-level changes even if same Set reference is used.
      * - Preserves prevSet/stateMap to allow async restore when needed.
      * - Ensures stateMap contains snapshots for *all meshes in the new set*.
+     * @param newSet The new set of meshes
+     * @param contextId Optional context ID to distinguish business scenarios
      */
-    setMeshes(newSet, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            const autoRestorePrev = (_a = options === null || options === void 0 ? void 0 : options.autoRestorePrev) !== null && _a !== void 0 ? _a : true;
-            const restoreDuration = (_b = options === null || options === void 0 ? void 0 : options.restoreDuration) !== null && _b !== void 0 ? _b : 300;
-            this.log(`setMeshes called. newSetSize=${newSet ? newSet.size : 0}, autoRestorePrev=${autoRestorePrev}`);
-            // If the newSet is null and currentSet is null -> nothing
-            if (!newSet && !this.currentSet) {
-                this.log('setMeshes: both newSet and currentSet are null, nothing to do');
-                return;
-            }
-            // If both exist and are the same reference, we still must detect content changes.
-            const sameReference = this.currentSet === newSet;
-            // Prepare prevSet snapshot (we copy current to prev)
-            if (this.currentSet) {
-                this.prevSet = this.currentSet;
-                this.prevStateMap = new Map(this.stateMap);
-                this.log(`setMeshes: backed up current->prev prevSetSize=${this.prevSet.size}`);
-            }
-            else {
-                this.prevSet = null;
-                this.prevStateMap = new Map();
-            }
-            // If we used to be exploded and need to restore prevSet, do that first (await)
-            if (this.prevSet && autoRestorePrev && this.isExploded) {
-                this.log('setMeshes: need to restore prevSet before applying newSet');
-                yield this.restoreSet(this.prevSet, this.prevStateMap, restoreDuration, { debug: true });
-                this.log('setMeshes: prevSet restore done');
-                this.prevStateMap.clear();
-                this.prevSet = null;
-            }
-            // Now register newSet: we clear and rebuild stateMap carefully.
-            // But we must handle the case where caller reuses same Set object and just mutated elements.
-            // We will compute additions and removals.
-            const oldSet = this.currentSet;
-            this.currentSet = newSet;
-            // If newSet is null -> simply clear stateMap
-            if (!this.currentSet) {
-                this.stateMap.clear();
-                this.log('setMeshes: newSet is null -> cleared stateMap');
-                this.isExploded = false;
+    async setMeshes(newSet, options) {
+        const autoRestorePrev = options?.autoRestorePrev ?? true;
+        const restoreDuration = options?.restoreDuration ?? 300;
+        this.log(`setMeshes called. newSetSize=${newSet ? newSet.size : 0}, autoRestorePrev=${autoRestorePrev}`);
+        // If the newSet is null and currentSet is null -> nothing
+        if (!newSet && !this.currentSet) {
+            this.log('setMeshes: both newSet and currentSet are null, nothing to do');
+            return;
+        }
+        // If both exist and are the same reference, we still must detect content changes.
+        const sameReference = this.currentSet === newSet;
+        // Prepare prevSet snapshot (we copy current to prev)
+        if (this.currentSet) {
+            this.prevSet = this.currentSet;
+            this.prevStateMap = new Map(this.stateMap);
+            this.log(`setMeshes: backed up current->prev prevSetSize=${this.prevSet.size}`);
+        }
+        else {
+            this.prevSet = null;
+            this.prevStateMap = new Map();
+        }
+        // If we used to be exploded and need to restore prevSet, do that first (await)
+        if (this.prevSet && autoRestorePrev && this.isExploded) {
+            this.log('setMeshes: need to restore prevSet before applying newSet');
+            await this.restoreSet(this.prevSet, this.prevStateMap, restoreDuration, { debug: true });
+            this.log('setMeshes: prevSet restore done');
+            this.prevStateMap.clear();
+            this.prevSet = null;
+        }
+        // Now register newSet: we clear and rebuild stateMap carefully.
+        // But we must handle the case where caller reuses same Set object and just mutated elements.
+        // We will compute additions and removals.
+        const oldSet = this.currentSet;
+        this.currentSet = newSet;
+        // If newSet is null -> simply clear stateMap
+        if (!this.currentSet) {
+            this.stateMap.clear();
+            this.log('setMeshes: newSet is null -> cleared stateMap');
+            this.isExploded = false;
+            return;
+        }
+        // If we have oldSet (could be same reference) then compute diffs
+        if (oldSet) {
+            // If same reference but size or content differs -> handle diffs
+            const wasSameRef = sameReference;
+            let added = [];
+            let removed = [];
+            // Build maps of membership
+            const oldMembers = new Set(Array.from(oldSet));
+            const newMembers = new Set(Array.from(this.currentSet));
+            // find removals
+            oldMembers.forEach((m) => {
+                if (!newMembers.has(m))
+                    removed.push(m);
+            });
+            // find additions
+            newMembers.forEach((m) => {
+                if (!oldMembers.has(m))
+                    added.push(m);
+            });
+            if (wasSameRef && added.length === 0 && removed.length === 0) {
+                // truly identical (no content changes)
+                this.log('setMeshes: same reference and identical contents -> nothing to update');
                 return;
             }
-            // If we have oldSet (could be same reference) then compute diffs
-            if (oldSet) {
-                // If same reference but size or content differs -> handle diffs
-                const wasSameRef = sameReference;
-                let added = [];
-                let removed = [];
-                // Build maps of membership
-                const oldMembers = new Set(Array.from(oldSet));
-                const newMembers = new Set(Array.from(this.currentSet));
-                // find removals
-                oldMembers.forEach((m) => {
-                    if (!newMembers.has(m))
-                        removed.push(m);
-                });
-                // find additions
-                newMembers.forEach((m) => {
-                    if (!oldMembers.has(m))
-                        added.push(m);
-                });
-                if (wasSameRef && added.length === 0 && removed.length === 0) {
-                    // truly identical (no content changes)
-                    this.log('setMeshes: same reference and identical contents -> nothing to update');
-                    return;
+            this.log(`setMeshes: diff detected -> added=${added.length}, removed=${removed.length}`);
+            // Remove snapshots for removed meshes
+            removed.forEach((m) => {
+                if (this.stateMap.has(m)) {
+                    this.stateMap.delete(m);
                 }
-                this.log(`setMeshes: diff detected -> added=${added.length}, removed=${removed.length}`);
-                // Remove snapshots for removed meshes
-                removed.forEach((m) => {
-                    if (this.stateMap.has(m)) {
-                        this.stateMap.delete(m);
-                    }
-                });
-                // Ensure snapshots exist for current set members (create for newly added meshes)
-                yield this.ensureSnapshotsForSet(this.currentSet);
-                this.log(`setMeshes: after diff handling, stateMap size=${this.stateMap.size}`);
-                this.isExploded = false;
-                return;
-            }
-            else {
-                // no oldSet -> brand new registration
-                this.stateMap.clear();
-                yield this.ensureSnapshotsForSet(this.currentSet);
-                this.log(`setMeshes: recorded stateMap entries for newSet size=${this.stateMap.size}`);
-                this.isExploded = false;
-                return;
-            }
-        });
+            });
+            // Ensure snapshots exist for current set members (create for newly added meshes)
+            await this.ensureSnapshotsForSet(this.currentSet);
+            this.log(`setMeshes: after diff handling, stateMap size=${this.stateMap.size}`);
+            this.isExploded = false;
+            return;
+        }
+        else {
+            // no oldSet -> brand new registration
+            this.stateMap.clear();
+            await this.ensureSnapshotsForSet(this.currentSet);
+            this.log(`setMeshes: recorded stateMap entries for newSet size=${this.stateMap.size}`);
+            this.isExploded = false;
+            return;
+        }
     }
     /**
      * ensureSnapshotsForSet: for each mesh in set, ensure stateMap has an entry.
      * If missing, record current matrixWorld as originalMatrixWorld (best-effort).
      */
-    ensureSnapshotsForSet(set) {
-        return __awaiter(this, void 0, void 0, function* () {
-            set.forEach((m) => {
+    async ensureSnapshotsForSet(set) {
+        set.forEach((m) => {
+            try {
+                m.updateMatrixWorld(true);
+            }
+            catch { }
+            if (!this.stateMap.has(m)) {
                 try {
-                    m.updateMatrixWorld(true);
+                    this.stateMap.set(m, {
+                        originalParent: m.parent || null,
+                        originalMatrixWorld: (m.matrixWorld && m.matrixWorld.clone()) || new THREE.Matrix4().copy(m.matrix),
+                    });
+                    // Also store in userData for extra resilience
+                    m.userData.__originalMatrixWorld = this.stateMap.get(m).originalMatrixWorld.clone();
                 }
-                catch (_a) { }
-                if (!this.stateMap.has(m)) {
-                    try {
-                        this.stateMap.set(m, {
-                            originalParent: m.parent || null,
-                            originalMatrixWorld: (m.matrixWorld && m.matrixWorld.clone()) || new THREE.Matrix4().copy(m.matrix),
-                        });
-                        // Also store in userData for extra resilience
-                        m.userData.__originalMatrixWorld = this.stateMap.get(m).originalMatrixWorld.clone();
-                    }
-                    catch (e) {
-                        this.log(`ensureSnapshotsForSet: failed to snapshot mesh ${m.name || m.id}: ${e.message}`);
-                    }
+                catch (e) {
+                    this.log(`ensureSnapshotsForSet: failed to snapshot mesh ${m.name || m.id}: ${e.message}`);
                 }
-            });
+            }
         });
     }
     /**
      * explode: compute targets first, compute targetBound using targets + mesh radii,
      * animate camera to that targetBound, then animate meshes to targets.
      */
-    explode(opts) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            if (!this.currentSet || this.currentSet.size === 0) {
-                this.log('explode: empty currentSet, nothing to do');
-                return;
+    async explode(opts) {
+        if (!this.currentSet || this.currentSet.size === 0) {
+            this.log('explode: empty currentSet, nothing to do');
+            return;
+        }
+        const { spacing = 2, duration = 1000, lift = 0.5, cameraPadding = 1.5, mode = 'spiral', dimOthers = { enabled: true, opacity: 0.25 }, debug = false, } = opts || {};
+        this.log(`explode called. setSize=${this.currentSet.size}, mode=${mode}, spacing=${spacing}, duration=${duration}, lift=${lift}, dim=${dimOthers.enabled}`);
+        this.cancelAnimations();
+        const meshes = Array.from(this.currentSet);
+        // ensure snapshots exist for any meshes that may have been added after initial registration
+        await this.ensureSnapshotsForSet(this.currentSet);
+        // compute center/radius from current meshes (fallback)
+        const initial = this.computeBoundingSphereForMeshes(meshes);
+        const center = initial.center;
+        const baseRadius = Math.max(1, initial.radius);
+        this.log(`explode: initial center=${center.toArray().map((n) => n.toFixed(3))}, baseRadius=${baseRadius.toFixed(3)}`);
+        // compute targets (pure calculation)
+        const targets = this.computeTargetsByMode(meshes, center, baseRadius + spacing, { lift, mode });
+        this.log(`explode: computed ${targets.length} target positions`);
+        // compute target-based bounding sphere (targets + per-mesh radius)
+        const targetBound = this.computeBoundingSphereForPositionsAndMeshes(targets, meshes);
+        this.log(`explode: targetBound center=${targetBound.center.toArray().map((n) => n.toFixed(3))}, radius=${targetBound.radius.toFixed(3)}`);
+        await this.animateCameraToFit(targetBound.center, targetBound.radius, { duration: Math.min(600, duration), padding: cameraPadding });
+        this.log('explode: camera animation to target bound completed');
+        // apply dim if needed with context id
+        const contextId = dimOthers?.enabled ? this.applyDimToOthers(meshes, dimOthers.opacity ?? 0.25, { debug }) : null;
+        if (contextId)
+            this.log(`explode: applied dim for context ${contextId}`);
+        // capture starts after camera move
+        const starts = meshes.map((m) => {
+            const v = new THREE.Vector3();
+            try {
+                m.getWorldPosition(v);
             }
-            const { spacing = 2, duration = 1000, lift = 0.5, cameraPadding = 1.5, mode = 'spiral', dimOthers = { enabled: true, opacity: 0.25 }, debug = false, } = opts || {};
-            this.log(`explode called. setSize=${this.currentSet.size}, mode=${mode}, spacing=${spacing}, duration=${duration}, lift=${lift}, dim=${dimOthers.enabled}`);
-            this.cancelAnimations();
-            const meshes = Array.from(this.currentSet);
-            // ensure snapshots exist for any meshes that may have been added after initial registration
-            yield this.ensureSnapshotsForSet(this.currentSet);
-            // compute center/radius from current meshes (fallback)
-            const initial = this.computeBoundingSphereForMeshes(meshes);
-            const center = initial.center;
-            const baseRadius = Math.max(1, initial.radius);
-            this.log(`explode: initial center=${center.toArray().map((n) => n.toFixed(3))}, baseRadius=${baseRadius.toFixed(3)}`);
-            // compute targets (pure calculation)
-            const targets = this.computeTargetsByMode(meshes, center, baseRadius + spacing, { lift, mode });
-            this.log(`explode: computed ${targets.length} target positions`);
-            // compute target-based bounding sphere (targets + per-mesh radius)
-            const targetBound = this.computeBoundingSphereForPositionsAndMeshes(targets, meshes);
-            this.log(`explode: targetBound center=${targetBound.center.toArray().map((n) => n.toFixed(3))}, radius=${targetBound.radius.toFixed(3)}`);
-            yield this.animateCameraToFit(targetBound.center, targetBound.radius, { duration: Math.min(600, duration), padding: cameraPadding });
-            this.log('explode: camera animation to target bound completed');
-            // apply dim if needed with context id
-            const contextId = (dimOthers === null || dimOthers === void 0 ? void 0 : dimOthers.enabled) ? this.applyDimToOthers(meshes, (_a = dimOthers.opacity) !== null && _a !== void 0 ? _a : 0.25, { debug }) : null;
-            if (contextId)
-                this.log(`explode: applied dim for context ${contextId}`);
-            // capture starts after camera move
-            const starts = meshes.map((m) => {
-                const v = new THREE.Vector3();
-                try {
-                    m.getWorldPosition(v);
-                }
-                catch (_a) {
-                    // fallback to originalMatrixWorld if available
-                    const st = this.stateMap.get(m);
-                    if (st)
-                        v.setFromMatrixPosition(st.originalMatrixWorld);
-                }
-                return v;
-            });
-            const startTime = performance.now();
-            const total = Math.max(1, duration);
-            const tick = (now) => {
-                const t = Math.min(1, (now - startTime) / total);
-                const eased = easeInOutQuad(t);
-                for (let i = 0; i < meshes.length; i++) {
-                    const m = meshes[i];
-                    const s = starts[i];
-                    const tar = targets[i];
-                    const cur = s.clone().lerp(tar, eased);
-                    if (m.parent) {
-                        const local = cur.clone();
-                        m.parent.worldToLocal(local);
-                        m.position.copy(local);
-                    }
-                    else {
-                        m.position.copy(cur);
-                    }
-                    m.updateMatrix();
-                }
-                if (this.controls && typeof this.controls.update === 'function')
-                    this.controls.update();
-                if (t < 1) {
-                    this.animId = requestAnimationFrame(tick);
+            catch {
+                // fallback to originalMatrixWorld if available
+                const st = this.stateMap.get(m);
+                if (st)
+                    v.setFromMatrixPosition(st.originalMatrixWorld);
+            }
+            return v;
+        });
+        const startTime = performance.now();
+        const total = Math.max(1, duration);
+        const tick = (now) => {
+            const t = Math.min(1, (now - startTime) / total);
+            const eased = easeInOutQuad(t);
+            for (let i = 0; i < meshes.length; i++) {
+                const m = meshes[i];
+                const s = starts[i];
+                const tar = targets[i];
+                const cur = s.clone().lerp(tar, eased);
+                if (m.parent) {
+                    const local = cur.clone();
+                    m.parent.worldToLocal(local);
+                    m.position.copy(local);
                 }
                 else {
-                    this.animId = null;
-                    this.isExploded = true;
-                    this.log(`explode: completed. contextId=${contextId !== null && contextId !== void 0 ? contextId : 'none'}`);
+                    m.position.copy(cur);
                 }
-            };
-            this.animId = requestAnimationFrame(tick);
-            return;
-        });
+                m.updateMatrix();
+            }
+            if (this.controls && typeof this.controls.update === 'function')
+                this.controls.update();
+            if (t < 1) {
+                this.animId = requestAnimationFrame(tick);
+            }
+            else {
+                this.animId = null;
+                this.isExploded = true;
+                this.log(`explode: completed. contextId=${contextId ?? 'none'}`);
+            }
+        };
+        this.animId = requestAnimationFrame(tick);
+        return;
     }
+    /**
+     * Restore all exploded meshes to their original transform:
+     * - Supports smooth animation
+     * - Automatically cancels transparency
+     */
     restore(duration = 400) {
         if (!this.currentSet || this.currentSet.size === 0) {
             this.log('restore: no currentSet to restore');
@@ -2599,7 +2797,7 @@ class GroupExploder {
      */
     restoreSet(set, stateMap, duration = 400, opts) {
         if (!set || set.size === 0) {
-            if (opts === null || opts === void 0 ? void 0 : opts.debug)
+            if (opts?.debug)
                 this.log('restoreSet: empty set, nothing to restore');
             return Promise.resolve();
         }
@@ -2612,12 +2810,12 @@ class GroupExploder {
             try {
                 m.updateMatrixWorld(true);
             }
-            catch (_a) { }
+            catch { }
             const s = new THREE.Vector3();
             try {
                 m.getWorldPosition(s);
             }
-            catch (_b) {
+            catch {
                 s.set(0, 0, 0);
             }
             starts.push(s);
@@ -2715,7 +2913,7 @@ class GroupExploder {
         });
     }
     // material dim with context id
-    applyDimToOthers(explodingMeshes, opacity = 0.25, opts) {
+    applyDimToOthers(explodingMeshes, opacity = 0.25, _opts) {
         const contextId = `ctx_${Date.now()}_${Math.floor(Math.random() * 10000)}`;
         const explodingSet = new Set(explodingMeshes);
         const touched = new Set();
@@ -2726,11 +2924,10 @@ class GroupExploder {
             if (explodingSet.has(mesh))
                 return;
             const applyMat = (mat) => {
-                var _a;
                 if (!this.materialSnaps.has(mat)) {
                     this.materialSnaps.set(mat, {
                         transparent: !!mat.transparent,
-                        opacity: (_a = mat.opacity) !== null && _a !== void 0 ? _a : 1,
+                        opacity: mat.opacity ?? 1,
                         depthWrite: mat.depthWrite,
                     });
                 }
@@ -2757,7 +2954,7 @@ class GroupExploder {
         return contextId;
     }
     // clean contexts for meshes (restore materials whose contexts are removed)
-    cleanContextsForMeshes(meshes) {
+    cleanContextsForMeshes(_meshes) {
         // conservative strategy: for each context we created, delete it and restore materials accordingly
         for (const [contextId, mats] of Array.from(this.contextMaterials.entries())) {
             mats.forEach((mat) => {
@@ -2871,7 +3068,7 @@ class GroupExploder {
                     }
                 }
             }
-            catch (_a) {
+            catch {
                 radius = 0;
             }
             if (!isFinite(radius) || radius < 0 || radius > 1e8)
@@ -2894,10 +3091,9 @@ class GroupExploder {
     }
     // computeTargetsByMode (unchanged logic but pure function)
     computeTargetsByMode(meshes, center, baseRadius, opts) {
-        var _a, _b;
         const n = meshes.length;
-        const lift = (_a = opts.lift) !== null && _a !== void 0 ? _a : 0.5;
-        const mode = (_b = opts.mode) !== null && _b !== void 0 ? _b : 'ring';
+        const lift = opts.lift ?? 0.5;
+        const mode = opts.mode ?? 'ring';
         const targets = [];
         if (mode === 'ring') {
             for (let i = 0; i < n; i++) {
@@ -2939,274 +3135,244 @@ class GroupExploder {
         return targets;
     }
     animateCameraToFit(targetCenter, targetRadius, opts) {
-        var _a, _b, _c;
-        const duration = (_a = opts === null || opts === void 0 ? void 0 : opts.duration) !== null && _a !== void 0 ? _a : 600;
-        const padding = (_b = opts === null || opts === void 0 ? void 0 : opts.padding) !== null && _b !== void 0 ? _b : 1.5;
+        const duration = opts?.duration ?? 600;
+        const padding = opts?.padding ?? 1.5;
         if (!(this.camera instanceof THREE.PerspectiveCamera)) {
             if (this.controls && this.controls.target) {
-                this.controls.target.copy(targetCenter);
-                if (typeof this.controls.update === 'function')
-                    this.controls.update();
+                // Fallback for non-PerspectiveCamera
+                const startTarget = this.controls.target.clone();
+                const startPos = this.camera.position.clone();
+                const endTarget = targetCenter.clone();
+                const dir = startPos.clone().sub(startTarget).normalize();
+                const dist = startPos.distanceTo(startTarget);
+                const endPos = endTarget.clone().add(dir.multiplyScalar(dist));
+                const startTime = performance.now();
+                const tick = (now) => {
+                    const t = Math.min(1, (now - startTime) / duration);
+                    const k = easeInOutQuad(t);
+                    if (this.controls && this.controls.target) {
+                        this.controls.target.lerpVectors(startTarget, endTarget, k);
+                    }
+                    this.camera.position.lerpVectors(startPos, endPos, k);
+                    if (this.controls?.update)
+                        this.controls.update();
+                    if (t < 1) {
+                        this.cameraAnimId = requestAnimationFrame(tick);
+                    }
+                    else {
+                        this.cameraAnimId = null;
+                    }
+                };
+                this.cameraAnimId = requestAnimationFrame(tick);
             }
             return Promise.resolve();
         }
-        const cam = this.camera;
-        const fov = (cam.fov * Math.PI) / 180;
-        const safeRadius = isFinite(targetRadius) && targetRadius > 0 ? targetRadius : 1;
-        const desiredDistance = Math.min(1e6, (safeRadius * ((_c = opts === null || opts === void 0 ? void 0 : opts.padding) !== null && _c !== void 0 ? _c : padding)) / Math.sin(fov / 2));
-        const camPos = cam.position.clone();
-        const dir = camPos.clone().sub(targetCenter);
-        if (dir.length() === 0)
+        // PerspectiveCamera logic
+        const fov = THREE.MathUtils.degToRad(this.camera.fov);
+        const aspect = this.camera.aspect;
+        // Calculate distance needed to fit the sphere
+        // tan(fov/2) = radius / distance  => distance = radius / tan(fov/2)
+        // We also consider aspect ratio for horizontal fit
+        const distV = targetRadius / Math.sin(fov / 2);
+        const distH = targetRadius / Math.sin(Math.min(fov, fov * aspect) / 2); // approximate
+        const dist = Math.max(distV, distH) * padding;
+        const startPos = this.camera.position.clone();
+        const startTarget = this.controls?.target ? this.controls.target.clone() : new THREE.Vector3(); // assumption
+        if (!this.controls?.target) {
+            this.camera.getWorldDirection(startTarget);
+            startTarget.add(startPos);
+        }
+        // Determine end position: keep current viewing direction relative to center
+        const dir = startPos.clone().sub(startTarget).normalize();
+        if (dir.lengthSq() < 0.001)
             dir.set(0, 0, 1);
-        else
-            dir.normalize();
-        const newCamPos = targetCenter.clone().add(dir.multiplyScalar(desiredDistance));
-        const startPos = cam.position.clone();
-        const startTarget = (this.controls && this.controls.target) ? (this.controls.target.clone()) : this.getCameraLookAtPoint();
         const endTarget = targetCenter.clone();
-        const startTime = performance.now();
+        const endPos = endTarget.clone().add(dir.multiplyScalar(dist));
         return new Promise((resolve) => {
+            const startTime = performance.now();
             const tick = (now) => {
-                const t = Math.min(1, (now - startTime) / Math.max(1, duration));
-                const eased = easeInOutQuad(t);
-                cam.position.lerpVectors(startPos, newCamPos, eased);
-                if (this.controls && this.controls.target)
-                    this.controls.target.lerpVectors(startTarget, endTarget, eased);
-                cam.updateProjectionMatrix();
-                if (this.controls && typeof this.controls.update === 'function')
-                    this.controls.update();
-                if (t < 1)
+                const t = Math.min(1, (now - startTime) / duration);
+                const k = easeInOutQuad(t);
+                this.camera.position.lerpVectors(startPos, endPos, k);
+                if (this.controls && this.controls.target) {
+                    this.controls.target.lerpVectors(startTarget, endTarget, k);
+                    this.controls.update?.();
+                }
+                else {
+                    this.camera.lookAt(endTarget); // simple lookAt if no controls
+                }
+                if (t < 1) {
                     this.cameraAnimId = requestAnimationFrame(tick);
+                }
                 else {
                     this.cameraAnimId = null;
-                    this.log(`animateCameraToFit: done. center=${targetCenter.toArray().map((n) => n.toFixed(2))}, radius=${targetRadius.toFixed(2)}`);
                     resolve();
                 }
             };
             this.cameraAnimId = requestAnimationFrame(tick);
         });
     }
-    getCameraLookAtPoint() {
-        const dir = new THREE.Vector3();
-        this.camera.getWorldDirection(dir);
-        return this.camera.position.clone().add(dir.multiplyScalar(10));
-    }
+    /**
+     * Cancel all running animations
+     */
     cancelAnimations() {
-        if (this.animId) {
+        if (this.animId !== null) {
             cancelAnimationFrame(this.animId);
             this.animId = null;
         }
-        if (this.cameraAnimId) {
+        if (this.cameraAnimId !== null) {
             cancelAnimationFrame(this.cameraAnimId);
             this.cameraAnimId = null;
         }
     }
+    /**
+     * Dispose: remove listener, cancel animation, clear references
+     */
     dispose() {
-        return __awaiter(this, arguments, void 0, function* (restoreBefore = true) {
-            this.cancelAnimations();
-            if (restoreBefore && this.isExploded) {
-                try {
-                    yield this.restore(200);
-                }
-                catch (_a) { }
-            }
-            // force restore of materials
-            for (const [mat, ctxs] of Array.from(this.materialContexts.entries())) {
-                const snap = this.materialSnaps.get(mat);
-                if (snap) {
-                    mat.transparent = snap.transparent;
-                    mat.opacity = snap.opacity;
-                    if (typeof snap.depthWrite !== 'undefined')
-                        mat.depthWrite = snap.depthWrite;
-                    mat.needsUpdate = true;
-                }
-                this.materialContexts.delete(mat);
-                this.materialSnaps.delete(mat);
-            }
-            this.contextMaterials.clear();
-            this.stateMap.clear();
-            this.prevStateMap.clear();
-            this.currentSet = null;
-            this.prevSet = null;
-            this.isInitialized = false;
-            this.isExploded = false;
-            this.log('dispose: cleaned up');
-        });
+        this.cancelAnimations();
+        this.currentSet = null;
+        this.prevSet = null;
+        this.stateMap.clear();
+        this.prevStateMap.clear();
+        this.materialContexts.clear();
+        this.materialSnaps.clear();
+        this.contextMaterials.clear();
+        this.log('dispose() called, resources cleaned up');
     }
 }
 
 /**
- * 自动设置相机与基础灯光 - 优化版
- *
- * ✨ 优化内容：
- * - 添加灯光强度调整方法
- * - 完善错误处理
- * - 优化dispose逻辑
- *
- * - camera: THREE.PerspectiveCamera（会被移动并指向模型中心）
- * - scene: THREE.Scene（会把新创建的 light group 加入 scene）
- * - model: THREE.Object3D 已加载的模型（任意 transform/坐标）
- * - options: 可选配置（见 AutoSetupOptions）
- *
- * 返回 AutoSetupHandle，调用方在组件卸载/切换时请调用 handle.dispose()
+ * @file autoSetup.ts
+ * @description
+ * Automatically sets up the camera and basic lighting scene based on the model's bounding box.
  */
-function autoSetupCameraAndLight(camera, scene, model, options = {}) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    // ✨ 边界检查
-    if (!camera || !scene || !model) {
-        throw new Error('autoSetupCameraAndLight: camera, scene, model are required');
-    }
+/**
+ * Fit camera to object bounding box
+ */
+function fitCameraToObject(camera, object, padding = 1.2, elevation = 0.2) {
+    const box = new THREE.Box3().setFromObject(object);
+    if (!isFinite(box.min.x))
+        return { center: new THREE.Vector3(), radius: 0 };
+    const sphere = new THREE.Sphere();
+    box.getBoundingSphere(sphere);
+    const center = sphere.center.clone();
+    const radius = Math.max(0.001, sphere.radius);
+    const fov = (camera.fov * Math.PI) / 180;
+    const halfFov = fov / 2;
+    const sinHalfFov = Math.max(Math.sin(halfFov), 0.001);
+    const distance = (radius * padding) / sinHalfFov;
+    const dir = new THREE.Vector3(0, Math.sin(elevation), Math.cos(elevation)).normalize();
+    const desiredPos = center.clone().add(dir.multiplyScalar(distance));
+    camera.position.copy(desiredPos);
+    camera.lookAt(center);
+    camera.near = Math.max(0.001, radius / 1000);
+    camera.far = Math.max(1000, radius * 50);
+    camera.updateProjectionMatrix();
+    return { center, radius };
+}
+/**
+ * Setup default lighting for a model
+ */
+function setupDefaultLights(scene, model, options = {}) {
+    const box = new THREE.Box3().setFromObject(model);
+    const sphere = new THREE.Sphere();
+    box.getBoundingSphere(sphere);
+    const center = sphere.center.clone();
+    const radius = Math.max(0.001, sphere.radius);
     const opts = {
-        padding: (_a = options.padding) !== null && _a !== void 0 ? _a : 1.2,
-        elevation: (_b = options.elevation) !== null && _b !== void 0 ? _b : 0.2,
-        enableShadows: (_c = options.enableShadows) !== null && _c !== void 0 ? _c : false,
-        shadowMapSize: (_d = options.shadowMapSize) !== null && _d !== void 0 ? _d : 1024,
-        directionalCount: (_e = options.directionalCount) !== null && _e !== void 0 ? _e : 4,
-        setMeshShadowProps: (_f = options.setMeshShadowProps) !== null && _f !== void 0 ? _f : true,
-        renderer: (_g = options.renderer) !== null && _g !== void 0 ? _g : null,
+        padding: options.padding ?? 1.2,
+        elevation: options.elevation ?? 0.2,
+        enableShadows: options.enableShadows ?? false,
+        shadowMapSize: options.shadowMapSize ?? 1024,
+        directionalCount: options.directionalCount ?? 4,
+        setMeshShadowProps: options.setMeshShadowProps ?? true,
+        renderer: options.renderer ?? null,
     };
-    try {
-        // --- 1) 计算包围数据
-        const box = new THREE.Box3().setFromObject(model);
-        // ✨ 检查包围盒有效性
-        if (!isFinite(box.min.x)) {
-            throw new Error('autoSetupCameraAndLight: Invalid bounding box');
+    if (opts.renderer && opts.enableShadows) {
+        opts.renderer.shadowMap.enabled = true;
+        opts.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    }
+    const lightsGroup = new THREE.Group();
+    lightsGroup.name = 'autoSetupLightsGroup';
+    lightsGroup.position.copy(center);
+    scene.add(lightsGroup);
+    const hemi = new THREE.HemisphereLight(0xffffff, 0x444444, 0.6);
+    hemi.position.set(0, radius * 2.0, 0);
+    lightsGroup.add(hemi);
+    const ambient = new THREE.AmbientLight(0xffffff, 0.25);
+    lightsGroup.add(ambient);
+    const dirCount = Math.max(1, Math.floor(opts.directionalCount));
+    const dirs = [new THREE.Vector3(0, 1, 0)];
+    for (let i = 0; i < dirCount; i++) {
+        const angle = (i / dirCount) * Math.PI * 2;
+        const v = new THREE.Vector3(Math.cos(angle), 0.3, Math.sin(angle)).normalize();
+        dirs.push(v);
+    }
+    const shadowCamSize = Math.max(1, radius * 1.5);
+    dirs.forEach((d, i) => {
+        const light = new THREE.DirectionalLight(0xffffff, i === 0 ? 1.5 : 1.2);
+        light.position.copy(d.clone().multiplyScalar(radius * 2.5));
+        light.target.position.copy(center);
+        light.name = `auto_dir_${i}`;
+        lightsGroup.add(light);
+        lightsGroup.add(light.target);
+        if (opts.enableShadows) {
+            light.castShadow = true;
+            light.shadow.mapSize.width = opts.shadowMapSize;
+            light.shadow.mapSize.height = opts.shadowMapSize;
+            const cam = light.shadow.camera;
+            const s = shadowCamSize;
+            cam.left = -s;
+            cam.right = s;
+            cam.top = s;
+            cam.bottom = -s;
+            cam.near = 0.1;
+            cam.far = radius * 10 + 50;
+            light.shadow.bias = -5e-4;
         }
-        const sphere = new THREE.Sphere();
-        box.getBoundingSphere(sphere);
-        const center = sphere.center.clone();
-        const radius = Math.max(0.001, sphere.radius);
-        // --- 2) 计算相机位置
-        const fov = (camera.fov * Math.PI) / 180;
-        const halfFov = fov / 2;
-        const sinHalfFov = Math.max(Math.sin(halfFov), 0.001);
-        const distance = (radius * opts.padding) / sinHalfFov;
-        const dir = new THREE.Vector3(0, Math.sin(opts.elevation), Math.cos(opts.elevation)).normalize();
-        const desiredPos = center.clone().add(dir.multiplyScalar(distance));
-        camera.position.copy(desiredPos);
-        camera.lookAt(center);
-        camera.near = Math.max(0.001, radius / 1000);
-        camera.far = Math.max(1000, radius * 50);
-        camera.updateProjectionMatrix();
-        // --- 3) 启用阴影
-        if (opts.renderer && opts.enableShadows) {
-            opts.renderer.shadowMap.enabled = true;
-            opts.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
-        }
-        // --- 4) 创建灯光组
-        const lightsGroup = new THREE.Group();
-        lightsGroup.name = 'autoSetupLightsGroup';
-        lightsGroup.position.copy(center);
-        scene.add(lightsGroup);
-        // 4.1 基础光
-        const hemi = new THREE.HemisphereLight(0xffffff, 0x444444, 0.6);
-        hemi.name = 'auto_hemi';
-        hemi.position.set(0, radius * 2.0, 0);
-        lightsGroup.add(hemi);
-        const ambient = new THREE.AmbientLight(0xffffff, 0.25);
-        ambient.name = 'auto_ambient';
-        lightsGroup.add(ambient);
-        // 4.2 方向光
-        const dirCount = Math.max(1, Math.floor(opts.directionalCount));
-        const directionalLights = [];
-        const dirs = [];
-        dirs.push(new THREE.Vector3(0, 1, 0));
-        for (let i = 0; i < Math.max(1, dirCount); i++) {
-            const angle = (i / Math.max(1, dirCount)) * Math.PI * 2;
-            const v = new THREE.Vector3(Math.cos(angle), 0.3, Math.sin(angle)).normalize();
-            dirs.push(v);
-        }
-        const shadowCamSize = Math.max(1, radius * 1.5);
-        for (let i = 0; i < dirs.length; i++) {
-            const d = dirs[i];
-            const light = new THREE.DirectionalLight(0xffffff, i === 0 ? 1.5 : 1.2);
-            light.position.copy(d.clone().multiplyScalar(radius * 2.5));
-            light.target.position.copy(center);
-            light.name = `auto_dir_${i}`;
-            lightsGroup.add(light);
-            lightsGroup.add(light.target);
-            if (opts.enableShadows) {
-                light.castShadow = true;
-                light.shadow.mapSize.width = opts.shadowMapSize;
-                light.shadow.mapSize.height = opts.shadowMapSize;
-                const cam = light.shadow.camera;
-                const s = shadowCamSize;
-                cam.left = -s;
-                cam.right = s;
-                cam.top = s;
-                cam.bottom = -s;
-                cam.near = 0.1;
-                cam.far = radius * 10 + 50;
-                light.shadow.bias = -0.0005;
-            }
-            directionalLights.push(light);
-        }
-        // 4.3 点光补光
-        const fill1 = new THREE.PointLight(0xffffff, 0.5, radius * 4);
-        fill1.position.copy(center).add(new THREE.Vector3(radius * 0.5, 0.2 * radius, 0));
-        fill1.name = 'auto_fill1';
-        lightsGroup.add(fill1);
-        const fill2 = new THREE.PointLight(0xffffff, 0.3, radius * 3);
-        fill2.position.copy(center).add(new THREE.Vector3(-radius * 0.5, -0.2 * radius, 0));
-        fill2.name = 'auto_fill2';
-        lightsGroup.add(fill2);
-        // --- 5) 设置 Mesh 阴影属性
-        if (opts.setMeshShadowProps) {
-            model.traverse((ch) => {
-                if (ch.isMesh) {
-                    const mesh = ch;
-                    const isSkinned = mesh.isSkinnedMesh;
-                    mesh.castShadow = opts.enableShadows && !isSkinned ? true : mesh.castShadow;
-                    mesh.receiveShadow = opts.enableShadows ? true : mesh.receiveShadow;
+    });
+    if (opts.setMeshShadowProps) {
+        model.traverse((ch) => {
+            if (ch.isMesh) {
+                const mesh = ch;
+                const isSkinned = mesh.isSkinnedMesh;
+                mesh.castShadow = opts.enableShadows && !isSkinned ? true : mesh.castShadow;
+                mesh.receiveShadow = opts.enableShadows ? true : mesh.receiveShadow;
+            }
+        });
+    }
+    const handle = {
+        lightsGroup,
+        center,
+        radius,
+        updateLightIntensity(factor) {
+            lightsGroup.traverse((node) => {
+                if (node.isLight) {
+                    const light = node;
+                    light.intensity *= factor; // Simple implementation
                 }
             });
-        }
-        // --- 6) 返回 handle ---
-        const handle = {
-            lightsGroup,
-            center,
-            radius,
-            // ✨ 新增灯光强度调整
-            updateLightIntensity(factor) {
-                lightsGroup.traverse((node) => {
-                    if (node.isLight) {
-                        const light = node;
-                        const originalIntensity = parseFloat(light.name.split('_').pop() || '1');
-                        light.intensity = originalIntensity * Math.max(0, factor);
-                    }
-                });
-            },
-            dispose: () => {
-                try {
-                    // 移除灯光组
-                    if (lightsGroup.parent)
-                        lightsGroup.parent.remove(lightsGroup);
-                    // 清理阴影资源
-                    lightsGroup.traverse((node) => {
-                        if (node.isLight) {
-                            const l = node;
-                            if (l.shadow && l.shadow.map) {
-                                try {
-                                    l.shadow.map.dispose();
-                                }
-                                catch (err) {
-                                    console.warn('Failed to dispose shadow map:', err);
-                                }
-                            }
-                        }
-                    });
-                }
-                catch (error) {
-                    console.error('autoSetupCameraAndLight: dispose failed', error);
+        },
+        dispose: () => {
+            if (lightsGroup.parent)
+                lightsGroup.parent.remove(lightsGroup);
+            lightsGroup.traverse((node) => {
+                if (node.isLight) {
+                    const l = node;
+                    if (l.shadow && l.shadow.map)
+                        l.shadow.map.dispose();
                 }
-            }
-        };
-        return handle;
-    }
-    catch (error) {
-        console.error('autoSetupCameraAndLight: setup failed', error);
-        throw error;
-    }
+            });
+        }
+    };
+    return handle;
+}
+/**
+ * Automatically setup camera and basic lighting (Combine fitCameraToObject and setupDefaultLights)
+ */
+function autoSetupCameraAndLight(camera, scene, model, options = {}) {
+    fitCameraToObject(camera, model, options.padding, options.elevation);
+    return setupDefaultLights(scene, model, options);
 }
 
 /**
@@ -3216,8 +3382,8 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
  * @packageDocumentation
  */
 // Core utilities
-// Version
-const VERSION = '1.0.0';
+// Version (keep in sync with package.json)
+const VERSION = '1.0.4';
 
-export { ArrowGuide, BlueSky, FOLLOW_ANGLES, GroupExploder, LiquidFillerGroup, VERSION, ViewPresets, addChildModelLabels, autoSetupCameraAndLight, cancelFollow, cancelSetView, createModelClickHandler, createModelsLabel, disposeMaterial, disposeObject, enableHoverBreath, followModels, initPostProcessing, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox, setView };
+export { ArrowGuide, BlueSky, FOLLOW_ANGLES, GroupExploder, LiquidFillerGroup, ResourceManager, VERSION, ViewPresets, addChildModelLabels, autoSetupCameraAndLight, cancelFollow, cancelSetView, createModelClickHandler, createModelsLabel, disposeMaterial, disposeObject, enableHoverBreath, fitCameraToObject, followModels, getLoaderConfig, initPostProcessing, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox, setLoaderConfig, setView, setupDefaultLights };
 //# sourceMappingURL=index.mjs.map