@file-viewer/renderer-3d 2.1.29 → 2.2.0

package/README.en.md

@@ -1,6 +1,6 @@
 # @file-viewer/renderer-3d
 
-Standalone 3D model renderer package for Flyfish File Viewer. It uses Three.js, OrbitControls, and format-specific Three.js loaders to preview GLB/GLTF, OBJ, STL, PLY, FBX, DAE, 3DS, 3MF, AMF, USD, KMZ, PCD, VRML, XYZ, VTK, and related model files directly in the browser.
+Standalone 3D model renderer for Flyfish File Viewer. It uses Three.js, OrbitControls, and lazy format-specific loaders for GLB / GLTF, OBJ, STL, PLY, FBX, DAE, 3DS, 3MF, AMF, USD, KMZ, PCD, VRML, XYZ, VTK, and related files. STEP / STP, IGES / IGS, and BREP use a local OCCT worker for real geometry decoding and rendering.
 
 ## Usage
 
@@ -11,24 +11,29 @@ import { modelRenderer } from '@file-viewer/renderer-3d'
 const options = {
   rendererMode: 'replace',
   renderers: modelRenderer,
+  model: {
+    workerUrl: '/viewer-assets/wasm/model/occt-worker.js',
+    runtimeUrl: '/viewer-assets/wasm/model/occt-import-js.js',
+    wasmUrl: '/viewer-assets/wasm/model/occt-import-js.wasm',
+    workerTimeoutMs: 120_000,
+  },
 }
 ```
 
-You can combine it with other renderer packages:
+`modelRenderer` can be combined with CAD and other renderer packages, or consumed through `@file-viewer/preset-all`. Full packages and `@file-viewer/vite-plugin` prepare the default offline assets. A renderer-only integration must self-host the OCCT worker, runtime, WASM, and both license notices.
 
-```ts
-import { modelRenderer } from '@file-viewer/renderer-3d'
-import { cadRenderer } from '@file-viewer/renderer-cad'
+Default paths:
 
-const options = {
-  rendererMode: 'replace',
-  renderers: [modelRenderer, cadRenderer],
-}
-```
+- `wasm/model/occt-worker.js`
+- `wasm/model/occt-import-js.js`
+- `wasm/model/occt-import-js.wasm`
+
+For subpath deployments or a dedicated asset origin, provide final URLs through `options.model.workerUrl`, `runtimeUrl`, and `wasmUrl`. There is no runtime CDN fallback. A strict CSP must allow that origin in `worker-src`, `script-src`, and `connect-src`; some browsers also require `script-src 'wasm-unsafe-eval'`.
 
-## Capabilities
+## Boundaries
 
-- Supports WebGL preview, orbit controls, fit-to-view, grid, axes, wireframe, and auto-rotate.
-- For `gltf`, `dae`, and `fbx` files with external textures or binary resources, the original URL directory is used as the resource base.
-- STEP, IGES, IFC, 3DM, and BREP entries use `@file-viewer/geometry-engine` for lightweight signature detection and accurate conversion guidance; full decoding should keep evolving through dedicated OpenCascade / web-ifc / rhino3dm WASM renderer paths.
-- `@file-viewer/core` no longer bundles the 3D renderer and no longer depends directly on `three`. Install this package explicitly for 3D model preview, or use `@file-viewer/preset-all`, which aggregates this renderer automatically.
+- STEP / STP, IGES / IGS, and BREP are tessellated by `occt-import-js` / OpenCascade in a worker. Assembly hierarchy, instances, normals, and face colors are preserved when the Three.js scene is built.
+- General models support WebGL orbit controls, fit-to-view, grid, axes, wireframe, and auto-rotate. External textures or binary resources referenced by `gltf`, `dae`, and `fbx` continue to resolve against the original file URL directory.
+- Unified global zoom: the renderer registers the standard zoom provider, so the outer toolbar's zoom in, zoom out, reset, and fit actions control the camera. Wheel, trackpad, and pinch zoom also update the shared zoom state.
+- IFC and 3DM currently provide signature detection and explicit integration guidance only. They still need dedicated `web-ifc` / That Open and `rhino3dm` renderers and are not reported as successful previews.
+- `@file-viewer/core` does not bundle Three.js or a geometry kernel. Install this renderer, the matching preset, or a full package when model preview is required.

package/README.md

@@ -1,6 +1,6 @@
 # @file-viewer/renderer-3d
 
-Flyfish File Viewer 的独立 3D 模型 renderer 包。它使用 Three.js、OrbitControls 和按格式异步加载的 Three.js loaders，为 GLB/GLTF、OBJ、STL、PLY、FBX、DAE、3DS、3MF、AMF、USD、KMZ、PCD、VRML、XYZ、VTK 等模型提供浏览器端只读预览。
+Flyfish File Viewer 的独立 3D 模型 renderer。它使用 Three.js、OrbitControls 和按格式异步加载的 loader，在浏览器内预览 GLB / GLTF、OBJ、STL、PLY、FBX、DAE、3DS、3MF、AMF、USD、KMZ、PCD、VRML、XYZ、VTK 等模型；STEP / STP、IGES / IGS 和 BREP 则通过本地 OCCT Worker 完成真实几何解析和渲染。
 
 ## 用法
 
@@ -11,24 +11,29 @@ import { modelRenderer } from '@file-viewer/renderer-3d'
 const options = {
   rendererMode: 'replace',
   renderers: modelRenderer,
+  model: {
+    workerUrl: '/viewer-assets/wasm/model/occt-worker.js',
+    runtimeUrl: '/viewer-assets/wasm/model/occt-import-js.js',
+    wasmUrl: '/viewer-assets/wasm/model/occt-import-js.wasm',
+    workerTimeoutMs: 120_000,
+  },
 }
 ```
 
-也可以和其他 renderer 一起组合：
+也可以把 `modelRenderer` 与 CAD 等 renderer 组合，或直接使用已经聚合它的 `@file-viewer/preset-all`。full 包和 `@file-viewer/vite-plugin` 会准备默认离线资产；只安装 renderer 时，需要自行托管 OCCT Worker、runtime、WASM 和两个许可证文件。
 
-```ts
-import { modelRenderer } from '@file-viewer/renderer-3d'
-import { cadRenderer } from '@file-viewer/renderer-cad'
+默认路径为：
 
-const options = {
-  rendererMode: 'replace',
-  renderers: [modelRenderer, cadRenderer],
-}
-```
+- `wasm/model/occt-worker.js`
+- `wasm/model/occt-import-js.js`
+- `wasm/model/occt-import-js.wasm`
+
+部署在子路径或独立资产域名时，通过 `options.model.workerUrl`、`runtimeUrl`、`wasmUrl` 传入最终 URL。不要使用运行时 CDN 回退。严格 CSP 需要在 `worker-src`、`script-src` 和 `connect-src` 中允许对应来源；部分浏览器还需要 `script-src 'wasm-unsafe-eval'`。
 
 ## 能力边界
 
-- 支持 WebGL 交互预览、轨道控制、适配视图、网格、坐标轴、线框和自动旋转。
-- `gltf` / `dae` / `fbx` 等带外部贴图或二进制资源的格式，会以原始 `url` 的目录作为资源基准继续加载。
-- STEP、IGES、IFC、3DM、BREP 等工程 B-Rep / BIM 格式入口会通过 `@file-viewer/geometry-engine` 做轻量签名识别和明确转换说明；完整解析应继续沿 OpenCascade / web-ifc / rhino3dm 独立 WASM renderer 路线演进。
-- `@file-viewer/core` 已不再内置 3D renderer，也不再直接依赖 `three`。需要 3D 模型预览时，请显式安装本包，或使用会自动聚合本包的 `@file-viewer/preset-all`。
+- STEP / STP、IGES / IGS、BREP：在 Worker 中使用 `occt-import-js` / OpenCascade 三角化，保留装配层级、实例、法线和面颜色，再构建 Three.js 场景。
+- 通用模型：支持 WebGL 轨道控制、适配视图、网格、坐标轴、线框和自动旋转。`gltf` / `dae` / `fbx` 的外部贴图或二进制资源继续以原始 `url` 目录为基准加载。
+- 全局统一缩放：renderer 注册标准缩放 provider，因此外层工具栏的放大、缩小、比例重置和适配视图会直接控制相机；滚轮、触控板和捏合缩放也会同步更新全局比例状态。
+- IFC、3DM：当前只做签名识别和明确的接入提示，仍需分别接入 `web-ifc` / That Open 与 `rhino3dm`，不会显示成成功预览。
+- `@file-viewer/core` 不内置 Three.js 或几何内核。需要模型预览时请显式安装本包、相应 preset，或 full 包。

package/dist/model.js

@@ -1,7 +1,8 @@
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { createFileViewerViewStateChange, createFileViewerViewStateChangeEmitter, createFileViewerTranslator, registerFileViewerViewStateProvider, unregisterFileViewerViewStateProvider, } from '@file-viewer/core';
-import { formatGeometryKernelNotice, inspectGeometryKernelFile, isGeometryKernelFormat, } from '@file-viewer/geometry-engine';
+import { createFileViewerViewStateChange, createFileViewerViewStateChangeEmitter, createFileViewerZoomChangeEmitter, createFileViewerTranslator, registerFileViewerZoomProvider, registerFileViewerViewStateProvider, resolveFileViewerColorScheme, resolveFileViewerLocale, resolveFileViewerModelAssetUrls, resolveFileViewerRuntimeAssetBaseUrl, unregisterFileViewerZoomProvider, unregisterFileViewerViewStateProvider, } from '@file-viewer/core';
+import { formatGeometryKernelNotice, importOcctGeometryFile, inspectGeometryKernelFile, isGeometryKernelFormat, } from '@file-viewer/geometry-engine';
+import { buildOcctThreeObject } from './occtModel.js';
 const modelStyle = `
 .model-viewer{display:flex;height:100%;min-height:100%;flex-direction:column;background:#f8fafc;color:#162333}
 .model-viewer *{box-sizing:border-box}
@@ -25,11 +26,37 @@ const modelStyle = `
 [data-viewer-theme='dark'] .model-meta{color:#94a3b8}
 [data-viewer-theme='dark'] .model-meta strong{color:#5eead4}
 [data-viewer-theme='dark'] .model-state{background:rgba(15,23,42,.88);color:#cbd5e1}
+.model-viewer[data-model-theme='dark']{background:#101820;color:#e5eef8}
+.model-viewer[data-model-theme='dark'] .model-toolbar{border-color:rgba(148,163,184,.18);background:#111827}
+.model-viewer[data-model-theme='dark'] .model-actions button{background:#1f2937;color:#cbd5e1}
+.model-viewer[data-model-theme='dark'] .model-actions button.active,.model-viewer[data-model-theme='dark'] .model-actions button:hover{background:rgba(45,212,191,.14);color:#5eead4}
+.model-viewer[data-model-theme='dark'] .model-meta{color:#94a3b8}
+.model-viewer[data-model-theme='dark'] .model-meta strong{color:#5eead4}
+.model-viewer[data-model-theme='dark'] .model-state{background:rgba(15,23,42,.88);color:#cbd5e1}
 @media (prefers-color-scheme:dark){[data-viewer-theme='system'] .model-viewer{background:#101820;color:#e5eef8}[data-viewer-theme='system'] .model-toolbar{border-color:rgba(148,163,184,.18);background:#111827}[data-viewer-theme='system'] .model-actions button{background:#1f2937;color:#cbd5e1}[data-viewer-theme='system'] .model-actions button.active,[data-viewer-theme='system'] .model-actions button:hover{background:rgba(45,212,191,.14);color:#5eead4}[data-viewer-theme='system'] .model-meta{color:#94a3b8}[data-viewer-theme='system'] .model-meta strong{color:#5eead4}[data-viewer-theme='system'] .model-state{background:rgba(15,23,42,.88);color:#cbd5e1}}
 @media (max-width:720px){.model-toolbar{min-height:64px;align-items:flex-start;flex-direction:column;gap:8px;padding:8px 10px}.model-meta{width:100%;justify-content:flex-start}}
 `;
 class ModelPreviewNotice extends Error {
 }
+const MODEL_MIN_ZOOM = 0.1;
+const MODEL_MAX_ZOOM = 20;
+const MODEL_ZOOM_STEP = 1.2;
+const MODEL_THEME_PALETTES = {
+    light: {
+        background: 0xf8fafc,
+        gridCenter: 0xb9c6d4,
+        gridLine: 0xdde5ed,
+        hemisphereSky: 0xffffff,
+        hemisphereGround: 0xd7dee8,
+    },
+    dark: {
+        background: 0x0d141c,
+        gridCenter: 0x526579,
+        gridLine: 0x263544,
+        hemisphereSky: 0xdbeafe,
+        hemisphereGround: 0x172231,
+    },
+};
 const createStyle = () => {
     const style = document.createElement('style');
     style.textContent = modelStyle;
@@ -59,6 +86,29 @@ const normalizeError = (reason) => {
         return String(reason);
     }
 };
+const isWorkerBootstrapFailure = (reason) => {
+    const errorName = reason && typeof reason === 'object' && 'name' in reason
+        ? String(reason.name || '')
+        : '';
+    if (errorName === 'SecurityError' || errorName === 'NetworkError') {
+        return true;
+    }
+    return /worker failed to load|worker-src|content security policy|importscripts|script error|loading (?:the )?wasm|fetching of the wasm failed/i
+        .test(normalizeError(reason));
+};
+const canUseWorkerUrlFromDocument = (workerUrl, documentRef) => {
+    const location = documentRef.defaultView?.location;
+    if (!location) {
+        return true;
+    }
+    try {
+        const resolved = new URL(workerUrl, documentRef.baseURI);
+        return resolved.protocol === 'blob:' || resolved.origin === location.origin;
+    }
+    catch {
+        return true;
+    }
+};
 const getResourcePath = (sourceUrl) => {
     if (!sourceUrl) {
         return '';
@@ -72,22 +122,57 @@ const getResourcePath = (sourceUrl) => {
         return slashIndex >= 0 ? clean.slice(0, slashIndex + 1) : '';
     }
 };
-const disposeMaterial = (material) => {
-    const materials = Array.isArray(material) ? material : [material];
-    materials.forEach(item => item.dispose());
-};
 const disposeObject = (object) => {
+    const disposedGeometries = new Set();
+    const disposedMaterials = new Set();
+    const disposedTextures = new Set();
+    const disposedSkeletons = new Set();
+    const disposeTexture = (value) => {
+        if (value instanceof THREE.Texture && !disposedTextures.has(value)) {
+            disposedTextures.add(value);
+            value.dispose();
+        }
+    };
+    const disposeMaterial = (material) => {
+        if (disposedMaterials.has(material)) {
+            return;
+        }
+        disposedMaterials.add(material);
+        Object.values(material).forEach(value => {
+            disposeTexture(value);
+            if (Array.isArray(value)) {
+                value.forEach(disposeTexture);
+            }
+        });
+        if (material instanceof THREE.ShaderMaterial) {
+            Object.values(material.uniforms).forEach(uniform => {
+                disposeTexture(uniform?.value);
+                if (Array.isArray(uniform?.value)) {
+                    uniform.value.forEach(disposeTexture);
+                }
+            });
+        }
+        material.dispose();
+    };
     object.traverse(child => {
         const mesh = child;
         const points = child;
-        if (mesh.geometry) {
+        if (mesh.geometry && !disposedGeometries.has(mesh.geometry)) {
+            disposedGeometries.add(mesh.geometry);
             mesh.geometry.dispose();
         }
         if (mesh.material) {
-            disposeMaterial(mesh.material);
+            const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+            materials.forEach(disposeMaterial);
         }
         if (points.material) {
-            disposeMaterial(points.material);
+            const materials = Array.isArray(points.material) ? points.material : [points.material];
+            materials.forEach(disposeMaterial);
+        }
+        const skinnedMesh = child;
+        if (skinnedMesh.isSkinnedMesh && !disposedSkeletons.has(skinnedMesh.skeleton)) {
+            disposedSkeletons.add(skinnedMesh.skeleton);
+            skinnedMesh.skeleton.dispose();
         }
     });
 };
@@ -109,12 +194,20 @@ export default async function renderModel(buffer, target, type = 'glb', context)
     let modelRoot = null;
     let gridHelper = null;
     let axesHelper = null;
+    let hemisphereLight = null;
+    let themeObserver = null;
+    let stopSystemThemeListener = null;
+    let activeDarkMode = null;
     let resizeObserver = null;
     let animationFrame = 0;
     let activeVersion = 0;
+    let modelMeshCount = 0;
+    let zoomBaselineDistance = 0;
+    let controlsStartScale = 1;
     let mixer = null;
-    const clock = new THREE.Clock();
+    const timer = new THREE.Timer();
     const viewStateEmitter = createFileViewerViewStateChangeEmitter();
+    const zoomEmitter = createFileViewerZoomChangeEmitter();
     const root = createElement('div', 'model-viewer');
     const toolbar = createElement('div', 'model-toolbar');
     const actions = createElement('div', 'model-actions');
@@ -130,6 +223,9 @@ export default async function renderModel(buffer, target, type = 'glb', context)
     const canvas = document.createElement('canvas');
     const state = createElement('div', 'model-state', t('model.state.loading'));
     const buttons = [fitButton, rotateButton, wireframeButton, gridButton, axesButton];
+    root.dataset.modelFormat = normalizedType;
+    root.dataset.modelStatus = status;
+    root.dataset.modelMeshCount = '0';
     buttons.forEach(button => {
         button.type = 'button';
     });
@@ -156,6 +252,8 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         gridButton.classList.toggle('active', showGrid);
         axesButton.classList.toggle('active', showAxes);
         summaryText.textContent = objectSummary;
+        root.dataset.modelStatus = status;
+        root.dataset.modelMeshCount = String(modelMeshCount);
         state.hidden = status === 'ready';
         state.classList.toggle('error', status === 'error');
         if (status === 'loading') {
@@ -187,18 +285,65 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         }
         return new THREE.Vector3(x, y, z);
     };
-    const getModelViewState = () => ({
-        renderer: 'model',
-        extra: {
-            status,
-            cameraPosition: vectorToArray(camera?.position),
-            cameraTarget: vectorToArray(controls?.target),
-            autoRotate,
-            wireframe,
-            showGrid,
-            showAxes,
-        },
-    });
+    const getModelScale = () => {
+        if (!camera || !controls || zoomBaselineDistance <= 0) {
+            return 1;
+        }
+        const distance = camera.position.distanceTo(controls.target);
+        return distance > 0
+            ? THREE.MathUtils.clamp(zoomBaselineDistance / distance, MODEL_MIN_ZOOM, MODEL_MAX_ZOOM)
+            : 1;
+    };
+    const getModelZoomState = () => {
+        const scale = getModelScale();
+        const ready = status === 'ready' && Boolean(modelRoot && camera && controls && zoomBaselineDistance > 0);
+        return {
+            scale,
+            label: `${Math.round(scale * 100)}%`,
+            canZoomIn: ready && scale < MODEL_MAX_ZOOM - 0.001,
+            canZoomOut: ready && scale > MODEL_MIN_ZOOM + 0.001,
+            canReset: ready && Math.abs(scale - 1) > 0.005,
+            minScale: MODEL_MIN_ZOOM,
+            maxScale: MODEL_MAX_ZOOM,
+        };
+    };
+    const setModelZoom = (requestedScale, source = 'api', action = 'zoom-change', notify = true) => {
+        if (!camera || !controls || zoomBaselineDistance <= 0) {
+            return getModelZoomState();
+        }
+        const scale = THREE.MathUtils.clamp(requestedScale, MODEL_MIN_ZOOM, MODEL_MAX_ZOOM);
+        const direction = camera.position.clone().sub(controls.target);
+        if (direction.lengthSq() < 1e-8) {
+            direction.set(1, 0.62, 1);
+        }
+        direction.normalize();
+        camera.position.copy(controls.target).addScaledVector(direction, zoomBaselineDistance / scale);
+        camera.updateProjectionMatrix();
+        controls.update();
+        zoomEmitter.emit();
+        if (notify) {
+            emitViewStateChange(action, source);
+        }
+        return getModelZoomState();
+    };
+    const getModelViewState = () => {
+        const zoom = getModelZoomState();
+        return {
+            renderer: 'model',
+            scale: zoom.scale,
+            zoom,
+            extra: {
+                status,
+                cameraPosition: vectorToArray(camera?.position),
+                cameraTarget: vectorToArray(controls?.target),
+                zoomBaselineDistance,
+                autoRotate,
+                wireframe,
+                showGrid,
+                showAxes,
+            },
+        };
+    };
     const emitViewStateChange = (action, source = 'viewer') => {
         const state = getModelViewState();
         viewStateEmitter.emit(createFileViewerViewStateChange(state, { action, source }));
@@ -208,6 +353,11 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         const source = applyOptions.source || 'api';
         const action = applyOptions.action || 'restore';
         const notify = applyOptions.notify !== false;
+        const baseline = Number(state.extra?.zoomBaselineDistance);
+        if (Number.isFinite(baseline) && baseline > 0) {
+            zoomBaselineDistance = baseline;
+        }
+        const hasCameraSnapshot = Array.isArray(state.extra?.cameraPosition);
         if (camera) {
             camera.position.copy(readVector(state.extra?.cameraPosition, camera.position));
             camera.updateProjectionMatrix();
@@ -216,6 +366,13 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             controls.target.copy(readVector(state.extra?.cameraTarget, controls.target));
             controls.update();
         }
+        const requestedScale = Number(state.scale ?? state.zoom?.scale);
+        if (!hasCameraSnapshot && Number.isFinite(requestedScale) && requestedScale > 0) {
+            setModelZoom(requestedScale, source, action, false);
+        }
+        else {
+            zoomEmitter.emit();
+        }
         if (typeof state.extra?.autoRotate === 'boolean') {
             autoRotate = state.extra.autoRotate;
         }
@@ -247,7 +404,90 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         camera.aspect = width / height;
         camera.updateProjectionMatrix();
     };
+    const findThemeHost = () => {
+        let current = root;
+        while (current) {
+            if (current.hasAttribute('data-viewer-theme')) {
+                return current;
+            }
+            const parentElement = current.parentElement;
+            if (parentElement) {
+                current = parentElement;
+                continue;
+            }
+            const nodeRoot = current.getRootNode();
+            current = 'host' in nodeRoot ? nodeRoot.host : null;
+        }
+        return null;
+    };
+    const systemThemeQuery = target.ownerDocument.defaultView?.matchMedia?.('(prefers-color-scheme: dark)');
+    const readDarkMode = () => {
+        const themeValue = findThemeHost()?.dataset.viewerTheme || context?.options?.theme;
+        const declaredTheme = themeValue === 'light' || themeValue === 'dark' || themeValue === 'system'
+            ? themeValue
+            : undefined;
+        return resolveFileViewerColorScheme(declaredTheme, systemThemeQuery?.matches ?? false) === 'dark';
+    };
+    const replaceGridHelper = (darkMode) => {
+        if (!scene) {
+            return;
+        }
+        const palette = darkMode ? MODEL_THEME_PALETTES.dark : MODEL_THEME_PALETTES.light;
+        const previous = gridHelper;
+        const next = new THREE.GridHelper(10, 10, palette.gridCenter, palette.gridLine);
+        next.visible = showGrid;
+        if (previous) {
+            next.scale.copy(previous.scale);
+            scene.remove(previous);
+            disposeObject(previous);
+        }
+        gridHelper = next;
+        scene.add(next);
+    };
+    const applyModelTheme = (force = false) => {
+        const darkMode = readDarkMode();
+        root.dataset.modelTheme = darkMode ? 'dark' : 'light';
+        if (!force && activeDarkMode === darkMode) {
+            return;
+        }
+        activeDarkMode = darkMode;
+        const palette = darkMode ? MODEL_THEME_PALETTES.dark : MODEL_THEME_PALETTES.light;
+        renderer?.setClearColor(palette.background, 1);
+        if (scene) {
+            scene.background = new THREE.Color(palette.background);
+        }
+        if (hemisphereLight) {
+            hemisphereLight.color.setHex(palette.hemisphereSky);
+            hemisphereLight.groundColor.setHex(palette.hemisphereGround);
+        }
+        canvas.style.colorScheme = darkMode ? 'dark' : 'light';
+        replaceGridHelper(darkMode);
+    };
+    const observeModelTheme = () => {
+        const themeHost = findThemeHost();
+        const MutationObserverCtor = target.ownerDocument.defaultView?.MutationObserver;
+        if (themeHost && MutationObserverCtor) {
+            themeObserver = new MutationObserverCtor(() => applyModelTheme());
+            themeObserver.observe(themeHost, {
+                attributes: true,
+                attributeFilter: ['data-viewer-theme'],
+            });
+        }
+        if (!systemThemeQuery) {
+            return;
+        }
+        const onSystemThemeChange = () => applyModelTheme();
+        if (typeof systemThemeQuery.addEventListener === 'function') {
+            systemThemeQuery.addEventListener('change', onSystemThemeChange);
+            stopSystemThemeListener = () => systemThemeQuery.removeEventListener('change', onSystemThemeChange);
+        }
+        else {
+            systemThemeQuery.addListener(onSystemThemeChange);
+            stopSystemThemeListener = () => systemThemeQuery.removeListener(onSystemThemeChange);
+        }
+    };
     const ensureScene = () => {
+        const initializeTheme = !scene || !gridHelper;
         if (!renderer) {
             renderer = new THREE.WebGLRenderer({
                 antialias: true,
@@ -257,21 +497,17 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             });
             renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
             renderer.outputColorSpace = THREE.SRGBColorSpace;
-            renderer.setClearColor(0xf8fafc, 1);
         }
         if (!scene) {
             scene = new THREE.Scene();
-            scene.background = new THREE.Color(0xf8fafc);
-            const hemiLight = new THREE.HemisphereLight(0xffffff, 0xd7dee8, 2.4);
-            scene.add(hemiLight);
+            hemisphereLight = new THREE.HemisphereLight(0xffffff, 0xd7dee8, 2.4);
+            scene.add(hemisphereLight);
             const keyLight = new THREE.DirectionalLight(0xffffff, 2.2);
             keyLight.position.set(8, 10, 8);
             scene.add(keyLight);
             const fillLight = new THREE.DirectionalLight(0xffffff, 0.9);
             fillLight.position.set(-7, 5, -4);
             scene.add(fillLight);
-            gridHelper = new THREE.GridHelper(10, 10, 0xcbd5e1, 0xe2e8f0);
-            scene.add(gridHelper);
             axesHelper = new THREE.AxesHelper(3);
             scene.add(axesHelper);
         }
@@ -286,16 +522,22 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             controls.screenSpacePanning = true;
             controls.autoRotateSpeed = 1.2;
         }
+        applyModelTheme(initializeTheme);
         updateHelperVisibility();
         resize();
     };
     const clearModel = () => {
         if (modelRoot && scene) {
+            mixer?.stopAllAction();
+            mixer?.uncacheRoot(modelRoot);
             scene.remove(modelRoot);
             disposeObject(modelRoot);
         }
         modelRoot = null;
+        modelMeshCount = 0;
+        zoomBaselineDistance = 0;
         mixer = null;
+        zoomEmitter.emit();
     };
     const createSurfaceMaterial = () => new THREE.MeshStandardMaterial({
         color: 0x4f8fba,
@@ -341,6 +583,7 @@ export default async function renderModel(buffer, target, type = 'glb', context)
     };
     const summarizeModel = (object) => {
         const { meshes, points } = countMeshes(object);
+        modelMeshCount = meshes;
         const parts = [];
         if (meshes) {
             parts.push(t('model.summary.meshes', { count: meshes }));
@@ -367,22 +610,50 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             size,
         };
     };
-    const fitToView = (source = 'viewer') => {
+    const fitToView = (source = 'viewer', request) => {
         if (!modelRoot || !camera || !controls) {
-            return;
+            return getModelZoomState();
         }
         const box = new THREE.Box3().setFromObject(modelRoot);
-        const size = box.getSize(new THREE.Vector3());
         const center = box.getCenter(new THREE.Vector3());
-        const radius = Math.max(size.x, size.y, size.z, 1);
-        const distance = radius / (2 * Math.tan(THREE.MathUtils.degToRad(camera.fov / 2))) * 1.65;
+        const sphere = box.getBoundingSphere(new THREE.Sphere());
+        const radius = Math.max(sphere.radius, 0.5);
+        const rect = stage.getBoundingClientRect();
+        const width = Math.max(1, rect.width || canvas.clientWidth);
+        const height = Math.max(1, rect.height || canvas.clientHeight);
+        const aspect = Math.max(0.01, width / height);
+        const verticalFov = THREE.MathUtils.degToRad(camera.fov);
+        const horizontalFov = 2 * Math.atan(Math.tan(verticalFov / 2) * aspect);
+        const verticalDistance = radius / Math.max(Math.sin(verticalFov / 2), 0.01);
+        const horizontalDistance = radius / Math.max(Math.sin(horizontalFov / 2), 0.01);
+        const mode = request?.mode || 'contain';
+        let distance = mode === 'cover'
+            ? Math.min(verticalDistance, horizontalDistance)
+            : mode === 'width'
+                ? horizontalDistance
+                : mode === 'height'
+                    ? verticalDistance
+                    : Math.max(verticalDistance, horizontalDistance);
+        const padding = Math.max(0, request?.padding ?? 28);
+        const paddingRatio = THREE.MathUtils.clamp(1 - (padding * 2) / Math.min(width, height), 0.2, 1);
+        distance = Math.max(distance / paddingRatio, 0.01);
+        const direction = camera.position.clone().sub(controls.target);
+        if (direction.lengthSq() < 1e-8) {
+            direction.set(1, 0.62, 1);
+        }
+        direction.normalize();
+        zoomBaselineDistance = distance;
         camera.near = Math.max(distance / 1000, 0.01);
         camera.far = Math.max(distance * 1000, 1000);
-        camera.position.copy(center).add(new THREE.Vector3(distance, distance * 0.62, distance));
+        camera.position.copy(center).addScaledVector(direction, distance);
         camera.updateProjectionMatrix();
         controls.target.copy(center);
+        controls.minDistance = distance / MODEL_MAX_ZOOM;
+        controls.maxDistance = distance / MODEL_MIN_ZOOM;
         controls.update();
+        zoomEmitter.emit();
         emitViewStateChange('fit', source);
+        return getModelZoomState();
     };
     const applyModelFit = (request) => {
         if (!modelRoot || !camera || !controls) {
@@ -395,12 +666,13 @@ export default async function renderModel(buffer, target, type = 'glb', context)
                 provider: 'view-state',
             };
         }
-        fitToView(request.source);
+        const zoom = fitToView(request.source, request);
         const state = getModelViewState();
         return {
             applied: true,
             mode: request.mode,
             resize: request.resize,
+            scale: zoom.scale,
             source: request.source,
             provider: 'view-state',
             state,
@@ -490,9 +762,50 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         const { KMZLoader } = await import('three/addons/loaders/KMZLoader.js');
         return new KMZLoader().parse(buffer).scene;
     };
+    const parseOcct = async (modelType) => {
+        const modelOptions = context?.options?.model;
+        const documentBaseUrl = resolveFileViewerRuntimeAssetBaseUrl(target.ownerDocument);
+        const assets = resolveFileViewerModelAssetUrls(modelOptions, documentBaseUrl);
+        const params = Object.fromEntries([
+            ['linearUnit', modelOptions?.linearUnit],
+            ['linearDeflectionType', modelOptions?.linearDeflectionType],
+            ['linearDeflection', modelOptions?.linearDeflection],
+            ['angularDeflection', modelOptions?.angularDeflection],
+        ].filter(([, value]) => value !== undefined));
+        const workerPreferred = modelOptions?.useWorker !== false &&
+            canUseWorkerUrlFromDocument(assets.workerUrl, target.ownerDocument);
+        const importOptions = {
+            ...assets,
+            useWorker: workerPreferred,
+            timeoutMs: modelOptions?.workerTimeoutMs,
+            params,
+            signal: context?.signal,
+        };
+        root.dataset.modelImport = workerPreferred ? 'worker' : 'main-thread';
+        let result;
+        try {
+            result = await importOcctGeometryFile(buffer, modelType, importOptions);
+        }
+        catch (workerError) {
+            if (!workerPreferred || context?.signal?.aborted || !isWorkerBootstrapFailure(workerError)) {
+                throw workerError;
+            }
+            root.dataset.modelImport = 'main-thread-fallback';
+            try {
+                result = await importOcctGeometryFile(buffer, modelType, {
+                    ...importOptions,
+                    useWorker: false,
+                });
+            }
+            catch (fallbackError) {
+                throw new Error(`${normalizeError(workerError)} Main-thread fallback failed: ${normalizeError(fallbackError)}`);
+            }
+        }
+        return buildOcctThreeObject(result, wireframe).object;
+    };
     const explainEngineeringModel = (modelType) => {
         const inspection = inspectGeometryKernelFile(buffer, modelType);
-        const notice = formatGeometryKernelNotice(inspection.format || modelType);
+        const notice = formatGeometryKernelNotice(inspection.format || modelType, resolveFileViewerLocale(context?.options));
         const signature = inspection.signature ? t('model.notice.signature', { signature: inspection.signature }) : '';
         const warnings = inspection.warnings.length ? ` ${inspection.warnings.join(' ')}` : '';
         throw new ModelPreviewNotice(`${signature}${notice}${warnings}`);
@@ -549,9 +862,10 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             case 'stp':
             case 'iges':
             case 'igs':
+            case 'brep':
+                return parseOcct(modelType);
             case 'ifc':
             case '3dm':
-            case 'brep':
                 return explainEngineeringModel(modelType);
             case 'pcd':
                 return parsePcd();
@@ -574,6 +888,7 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         const version = ++activeVersion;
         status = 'loading';
         errorMessage = '';
+        modelMeshCount = 0;
         objectSummary = t('model.state.loadingSummary');
         updateUi();
         ensureScene();
@@ -586,26 +901,34 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             await addModelToScene(object);
             status = 'ready';
             updateUi();
+            zoomEmitter.emit();
+            emitViewStateChange('init', 'viewer');
         }
         catch (reason) {
             if (version !== activeVersion) {
                 return;
             }
+            if (context?.signal?.aborted) {
+                return;
+            }
             if (!(reason instanceof ModelPreviewNotice)) {
                 console.error(reason);
             }
             status = 'error';
+            modelMeshCount = 0;
             errorMessage = normalizeError(reason) || t('model.error.parseFailed', { type: normalizedType.toUpperCase() });
             updateUi();
+            zoomEmitter.emit();
         }
     };
-    const renderFrame = () => {
+    const renderFrame = (timestamp) => {
         if (!renderer || !scene || !camera || !controls) {
             return;
         }
+        timer.update(timestamp);
+        const delta = timer.getDelta();
         controls.autoRotate = autoRotate;
-        controls.update();
-        const delta = clock.getDelta();
+        controls.update(delta);
         mixer?.update(delta);
         renderer.render(scene, camera);
         animationFrame = window.requestAnimationFrame(renderFrame);
@@ -616,7 +939,16 @@ export default async function renderModel(buffer, target, type = 'glb', context)
         }
         updateUi();
     };
+    const onControlsStart = () => {
+        controlsStartScale = getModelScale();
+    };
     const onControlsEnd = () => {
+        const scale = getModelScale();
+        if (Math.abs(scale - controlsStartScale) > 0.002) {
+            zoomEmitter.emit();
+            emitViewStateChange('zoom-change', 'user');
+            return;
+        }
         emitViewStateChange('camera-change', 'user');
     };
     fitButton.addEventListener('click', () => fitToView('user'));
@@ -642,8 +974,19 @@ export default async function renderModel(buffer, target, type = 'glb', context)
     });
     updateUi();
     ensureScene();
+    observeModelTheme();
     const controlsWithEvents = controls;
+    controlsWithEvents?.addEventListener('start', onControlsStart);
     controlsWithEvents?.addEventListener('end', onControlsEnd);
+    registerFileViewerZoomProvider(root, {
+        zoomIn: () => setModelZoom(getModelScale() * MODEL_ZOOM_STEP, 'user', 'zoom-in'),
+        zoomOut: () => setModelZoom(getModelScale() / MODEL_ZOOM_STEP, 'user', 'zoom-out'),
+        resetZoom: () => setModelZoom(1, 'user', 'zoom-reset'),
+        setZoom: scale => setModelZoom(scale, 'api', 'zoom-change'),
+        fit: applyModelFit,
+        getState: getModelZoomState,
+        subscribe: zoomEmitter.subscribe,
+    });
     registerFileViewerViewStateProvider(root, {
         getState: getModelViewState,
         applyState: applyModelViewState,
@@ -652,9 +995,9 @@ export default async function renderModel(buffer, target, type = 'glb', context)
     });
     resizeObserver = new ResizeObserver(resize);
     resizeObserver.observe(canvas);
-    clock.start();
+    timer.connect(target.ownerDocument);
     renderFrame();
-    void loadModel();
+    await loadModel();
     return {
         $el: root,
         unmount() {
@@ -662,18 +1005,29 @@ export default async function renderModel(buffer, target, type = 'glb', context)
             window.cancelAnimationFrame(animationFrame);
             resizeObserver?.disconnect();
             resizeObserver = null;
+            themeObserver?.disconnect();
+            themeObserver = null;
+            stopSystemThemeListener?.();
+            stopSystemThemeListener = null;
             clearModel();
+            controlsWithEvents?.removeEventListener('start', onControlsStart);
             controlsWithEvents?.removeEventListener('end', onControlsEnd);
+            unregisterFileViewerZoomProvider(root);
             unregisterFileViewerViewStateProvider(root);
             controls?.dispose();
             controls = null;
+            if (scene) {
+                disposeObject(scene);
+            }
             renderer?.dispose();
+            renderer?.renderLists.dispose();
             renderer = null;
-            clock.stop();
+            timer.dispose();
             scene = null;
             camera = null;
             gridHelper = null;
             axesHelper = null;
+            hemisphereLight = null;
             target.replaceChildren();
         },
     };

package/dist/occtModel.d.ts

@@ -0,0 +1,13 @@
+import * as THREE from 'three';
+import type { GeometryKernelImportResult } from '@file-viewer/geometry-engine';
+export interface OcctThreeObjectStats {
+    meshCount: number;
+    nodeCount: number;
+    triangleCount: number;
+    vertexCount: number;
+}
+export interface OcctThreeObjectResult {
+    object: THREE.Group;
+    stats: OcctThreeObjectStats;
+}
+export declare const buildOcctThreeObject: (result: GeometryKernelImportResult, wireframe?: boolean) => OcctThreeObjectResult;

package/dist/occtModel.js

@@ -0,0 +1,185 @@
+import * as THREE from 'three';
+const DEFAULT_SURFACE_COLOR = new THREE.Color(0x4f8fba);
+const readColor = (value) => {
+    if (!value || value.length < 3) {
+        return DEFAULT_SURFACE_COLOR.clone();
+    }
+    const components = value.slice(0, 3).map(Number);
+    if (components.some(component => !Number.isFinite(component))) {
+        return DEFAULT_SURFACE_COLOR.clone();
+    }
+    const [red, green, blue] = components.map(component => THREE.MathUtils.clamp(component, 0, 1));
+    return new THREE.Color(red, green, blue);
+};
+const createMaterial = (color, wireframe) => new THREE.MeshStandardMaterial({
+    color,
+    metalness: 0.06,
+    roughness: 0.72,
+    side: THREE.DoubleSide,
+    wireframe,
+});
+const hasOnlyFiniteNumbers = (values) => {
+    for (let index = 0; index < values.length; index += 1) {
+        if (!Number.isFinite(Number(values[index]))) {
+            return false;
+        }
+    }
+    return true;
+};
+const normalizeFaces = (faces, triangleCount) => {
+    return (faces || [])
+        .map(face => ({
+        ...face,
+        first: Math.max(0, Math.floor(Number(face.first))),
+        last: Math.min(triangleCount - 1, Math.floor(Number(face.last))),
+    }))
+        .filter(face => face.first <= face.last && face.first < triangleCount)
+        .sort((left, right) => left.first - right.first);
+};
+const buildGeometry = (source) => {
+    const sourcePositions = source.attributes?.position?.array || [];
+    const sourceIndices = source.index?.array || [];
+    if (sourcePositions.length < 9 || sourcePositions.length % 3 !== 0) {
+        throw new Error(`OCCT mesh ${source.name || '(unnamed)'} has invalid vertex data.`);
+    }
+    if (!hasOnlyFiniteNumbers(sourcePositions)) {
+        throw new Error(`OCCT mesh ${source.name || '(unnamed)'} has invalid vertex data.`);
+    }
+    if (sourceIndices.length < 3 || sourceIndices.length % 3 !== 0) {
+        throw new Error(`OCCT mesh ${source.name || '(unnamed)'} has invalid triangle data.`);
+    }
+    const vertexCount = sourcePositions.length / 3;
+    for (let index = 0; index < sourceIndices.length; index += 1) {
+        const vertexIndex = Number(sourceIndices[index]);
+        if (!Number.isInteger(vertexIndex) || vertexIndex < 0 || vertexIndex >= vertexCount) {
+            throw new Error(`OCCT mesh ${source.name || '(unnamed)'} has an invalid triangle index.`);
+        }
+    }
+    const positions = Float32Array.from(sourcePositions);
+    const indices = Uint32Array.from(sourceIndices);
+    const geometry = new THREE.BufferGeometry();
+    geometry.name = source.name || '';
+    geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+    geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+    const normals = source.attributes?.normal?.array;
+    const hasValidNormals = normals &&
+        normals.length === positions.length &&
+        hasOnlyFiniteNumbers(normals);
+    if (hasValidNormals) {
+        geometry.setAttribute('normal', new THREE.Float32BufferAttribute(Float32Array.from(normals), 3));
+    }
+    else {
+        geometry.computeVertexNormals();
+    }
+    geometry.computeBoundingBox();
+    geometry.computeBoundingSphere();
+    return geometry;
+};
+const buildMaterials = (geometry, source, wireframe) => {
+    const baseColor = readColor(source.color);
+    const materials = [createMaterial(baseColor, wireframe)];
+    const materialByColor = new Map();
+    const triangleCount = (geometry.index?.count || 0) / 3;
+    const faces = normalizeFaces(source.brep_faces, triangleCount);
+    if (!faces.length) {
+        return materials;
+    }
+    let cursor = 0;
+    for (const face of faces) {
+        if (face.first > cursor) {
+            geometry.addGroup(cursor * 3, (face.first - cursor) * 3, 0);
+        }
+        const faceColor = face.color ? readColor(face.color) : baseColor;
+        const colorKey = face.color ? faceColor.getHexString() : 'base';
+        let materialIndex = colorKey === 'base' ? 0 : materialByColor.get(colorKey);
+        if (materialIndex === undefined) {
+            materialIndex = materials.length;
+            materialByColor.set(colorKey, materialIndex);
+            materials.push(createMaterial(faceColor, wireframe));
+        }
+        const start = Math.max(cursor, face.first);
+        if (face.last >= start) {
+            geometry.addGroup(start * 3, (face.last - start + 1) * 3, materialIndex);
+            cursor = face.last + 1;
+        }
+    }
+    if (cursor < triangleCount) {
+        geometry.addGroup(cursor * 3, (triangleCount - cursor) * 3, 0);
+    }
+    return materials;
+};
+const createMeshFactory = (source, wireframe) => {
+    const geometry = buildGeometry(source);
+    const materials = buildMaterials(geometry, source, wireframe);
+    return () => {
+        const mesh = new THREE.Mesh(geometry, materials.length === 1 ? materials[0] : materials);
+        mesh.name = source.name || '';
+        mesh.castShadow = false;
+        mesh.receiveShadow = false;
+        return mesh;
+    };
+};
+export const buildOcctThreeObject = (result, wireframe = false) => {
+    if (!result.success || !result.meshes.length) {
+        throw new Error('The OpenCascade result does not contain renderable geometry.');
+    }
+    const meshFactories = result.meshes.map(mesh => createMeshFactory(mesh, wireframe));
+    const referencedMeshes = new Set();
+    let nodeCount = 0;
+    const buildNode = (node) => {
+        const group = new THREE.Group();
+        group.name = node.name || '';
+        nodeCount += 1;
+        for (const meshIndex of node.meshes || []) {
+            const factory = meshFactories[meshIndex];
+            if (!factory) {
+                continue;
+            }
+            referencedMeshes.add(meshIndex);
+            group.add(factory());
+        }
+        for (const child of node.children || []) {
+            group.add(buildNode(child));
+        }
+        return group;
+    };
+    const object = result.root
+        ? buildNode(result.root)
+        : new THREE.Group();
+    object.name ||= 'OCCT model';
+    const unassigned = new THREE.Group();
+    unassigned.name = 'Unassigned geometry';
+    meshFactories.forEach((factory, index) => {
+        if (!referencedMeshes.has(index)) {
+            unassigned.add(factory());
+        }
+    });
+    if (unassigned.children.length) {
+        nodeCount += 1;
+        object.add(unassigned);
+    }
+    // STEP/IGES mechanical models conventionally use Z-up, while the shared
+    // Three.js stage uses Y-up. Keep the grid and orbit controls intuitive.
+    object.rotation.x = -Math.PI / 2;
+    object.updateMatrixWorld(true);
+    const stats = {
+        meshCount: 0,
+        nodeCount,
+        triangleCount: 0,
+        vertexCount: 0,
+    };
+    object.traverse(child => {
+        const mesh = child;
+        if (!mesh.isMesh || !mesh.geometry.getAttribute('position')) {
+            return;
+        }
+        stats.meshCount += 1;
+        stats.vertexCount += mesh.geometry.getAttribute('position').count;
+        stats.triangleCount += (mesh.geometry.index?.count || 0) / 3;
+    });
+    if (!stats.meshCount) {
+        throw new Error('The OpenCascade hierarchy does not reference any renderable meshes.');
+    }
+    object.userData.fileViewerGeometryStats = stats;
+    return { object, stats };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/renderer-3d",
-  "version": "2.1.29",
+  "version": "2.2.0",
   "private": false,
   "type": "module",
   "description": "Standalone 3D model renderer plugin for Flyfish File Viewer powered by Three.js loaders and OrbitControls.",
@@ -57,8 +57,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@file-viewer/core": "2.1.29",
-    "@file-viewer/geometry-engine": "2.1.29",
+    "@file-viewer/core": "2.2.0",
+    "@file-viewer/geometry-engine": "2.2.0",
     "three": "^0.184.0"
   },
   "devDependencies": {