dsh-3d-viewer 0.1.1 → 0.2.0

package/README.md

@@ -1,114 +1,180 @@
-<div align="center">
-  <img src="https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/icon-180.png" alt="3D Viewer icon" width="96" height="96">
-  <h1 align="center">3D Viewer</h1>
-</div>
-
-English | [中文](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/README.zh.md)
-
-[![GitHub](https://img.shields.io/badge/GitHub-ybniaobu-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/ybniaobu/dsh-3d-viewer) [![npm](https://img.shields.io/badge/npm-dsh--3d--viewer-CB3837?logo=npm&logoColor=white&style=flat-square)](https://www.npmjs.com/package/dsh-3d-viewer?activeTab=readme)
-
-Preview FBX, OBJ, glTF, GLB, and STL models from the current session's workspace in DSH's right sidebar. No uploads or network: open a model, orbit, zoom, switch materials and environments, and play embedded animations.
-
-![3D Viewer preview](https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/preview.png)
-
-## Installation and enabling
-
-Distributed as the npm package `dsh-3d-viewer`. The prebuilt `client.js` bundles Three.js and the loaders; the four HDRI files ship in the package and are served by a small read-only host route on the local DSH server, so no network access is needed at runtime. React comes from DSH.
-
-### Install from npm (recommended)
-
-1. Open DSH Desktop and choose **Plugins** in the sidebar.
-2. Click **Add plugin** → **Install a third-party plugin**.
-3. Enter `dsh-3d-viewer` (or `dsh-3d-viewer@0.1.1` to pin a version).
-4. Set **Registry** to the official npm registry (npmmirror also works in mainland China).
-5. Click **Install**, then confirm **3D Viewer** is **On** under **Installed plugins**.
-6. Open a model from any session. If no preview appears, refresh the page; if it still does not, restart DSH.
-
-> **Updating**: remove the old version under **Plugins**, then install the new one with a higher version.
-
-### Install from a local directory (optional)
-
-Use this for offline or intranet distribution.
-
-1. Unpack the plugin directory anywhere; it must contain `package.json`, `client.js`, `index.js`, `cordis.patch.yml`, and the `assets/hdri/` directory.
-2. Open DSH Desktop and choose **Plugins** in the sidebar.
-3. Click **Add plugin** → **Install a third-party plugin**.
-4. Enter the directory's absolute path (for example `F:\plugins\dsh-3d-viewer`) and click **Install**.
-5. Confirm **3D Viewer** is **On** under **Installed plugins**.
-6. Open a model from any session. If no preview appears, refresh the page; if it still does not, restart DSH.
-
-> Local installs link to the directory rather than copying it. Do not move, rename, or delete it, or DSH may not find the plugin on the next start.
->
-> Plugins run inside the DSH process; install only trusted sources.
-
-### Requirements
-
-- DSH Desktop 0.2.2-rc.1 or newer (built and tested on 0.2.2-rc.1).
-- WebGL 2 support; otherwise the preview reports an error.
-- Model files in the session workspace, reachable through **Files** in the right sidebar.
-
-## Open a model
-
-1. Open any session and click the right-sidebar button at the top-right of the conversation.
-2. Open **Files** in the sidebar (or press `Mod+P`).
-3. Click any `.fbx`, `.obj`, `.gltf`, `.glb`, or `.stl` file.
-4. The model opens in a preview tab. Large files and the first environment switch may take a few seconds.
-
-## Supported formats
-
-| Format | Support |
-| --- | --- |
-| **FBX** | Meshes, hierarchy, materials, embedded textures, animations, and node data |
-| **OBJ** | Polygons, `o`/`g` groups, normals, UVs, vertex colors, line/point primitives, `mtllib`/MTL, and common textures |
-| **glTF / GLB** | Animations, skinning, embedded resources, and external `.bin` files and textures |
-| **STL** | ASCII and binary STL; neutral double-sided PBR material; binary vertex colors preserved |
-
-External resources (FBX/glTF textures, glTF `.bin`, OBJ MTL and textures) are read from the session workspace.
-
-The four environments are the exception: the HDRIs ship inside the plugin package, and the Host half serves them from the local DSH server on `/dsh-3d-viewer/hdri/`, so switching environments never touches the network.
-
-Notes:
-
-- **All formats**: lights, cameras, and audio embedded in the file are removed; the preview uses its own lighting and camera.
-- **FBX**: a missing external texture warns but does not block geometry.
-- **OBJ**: a missing MTL falls back to default materials; missing textures use white placeholders.
-- **glTF / GLB**: resources shared by several primitives are read once.
-- **STL**: no materials or animations.
-
-### Not supported
-
-- glTF extensions that need extra decoders: Draco, Meshopt, KTX2.
-- Texture formats DSH cannot decode directly: TGA, DDS, EXR, and similar (shown as white placeholders).
-- MTL `map_Ks` / `map_Ns` are not fully mapped to PBR yet (`Kd/Ks/Ns/d` and diffuse/normal/bump/emissive/alpha/displacement textures are supported).
-
-## Code structure
-
-| Path | Responsibility |
-| --- | --- |
-| `index.js` | Host half: registers the read-only `/dsh-3d-viewer/hdri/` route that serves the packaged HDRIs |
-| `src/client.js` | Plugin entry; registers document previews and Sidebar slots per format |
-| `src/formats.js` | Format registry: ids, extensions, title/badge keys, and format normalization |
-| `src/bytes.js` | Shared byte, text, path, MIME, and base64 helpers plus the cancellation error |
-| `src/ui/ModelViewer.js` | Viewer container: loading/error state, format binding, and scene lifecycle |
-| `src/ui/ViewerSurface.js` | Pure presentation: toolbar, stats, animation bar, and status overlay; renderable without WebGL |
-| `src/ui/AnimationBar.js` | Animation transport; playback state and 30 Hz progress updates re-render only this small component |
-| `src/ui/chrome.js`, `icons.js`, `primitives.js` | Toolbar, data-driven material/environment popovers, stats panel, icons, and formatting |
-| `src/ui/styles.js`, `dictionaries.js`, `options.js` | Styles, English/Chinese copy, and UI options |
-| `src/scene/createSceneView.js` | Scene orchestration: renderer, camera, controls, lifecycle |
-| `src/scene/environment.js` | HDRI fetch from the host route, decode, PMREM construction, and per-id caching |
-| `src/scene/materials.js` | Phong/Lambert → PBR conversion, material presets, and wireframe material |
-| `src/scene/ground.js` | Infinite grid shader and shadow receiver; grid pixels are generated once per page |
-| `src/scene/animation.js` | AnimationMixer, clip timeline, and progress notifications |
-| `src/scene/camera.js`, `lighting.js`, `render-loop.js`, `postprocessing.js`, `blue-noise.js` | Framing and keyboard orbit, lighting, frame scheduling, MSAA/ACES post-processing, and blue-noise dithering |
-| `src/loaders/workspace.js` | `resourceAddress` parsing, workspaceFiles reads, absolute-path fallback, texture Blob/white fallback, and resource cleanup |
-| `src/loaders/model-loader.js` | Async FBX / OBJ / glTF / GLB / STL loading and table-driven format dispatch |
-| `src/loaders/gltf.js` | glTF/GLB external buffer/texture prefetch (deduplicated by resource), animation wiring, and cleanup |
-| `src/model.js` | Synchronous FBX / OBJ / STL parsing, stats, and resource disposal |
-| `src/vendor/FBXLoaderPbr.js` | Vendored Three.js FBXLoader with metalness/roughness custom-attribute support |
-| `tests/run.mjs` | Test entry; each `tests/*.mjs` runs in its own process |
-| `icon.svg` | Plugin icon; DSH metadata requires it at the package root |
-| `assets/hdri/` | Packaged HDRI files served by the host route (Poly Haven CC0) |
-
-## License
-
-MIT; see [LICENSE](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/LICENSE). Third-party notices are in [THIRD_PARTY_NOTICES.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/THIRD_PARTY_NOTICES.md), including Three.js (MIT) and Poly Haven HDRIs (CC0; see [assets/hdri/LICENSE.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/assets/hdri/LICENSE.md)). React is provided by DSH and is not distributed with this package.
+<div align="center">
+  <img src="https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/icon-180.png" alt="3D Viewer icon" width="96" height="96">
+  <h1 align="center">3D Viewer</h1>
+</div>
+
+English | [中文](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/README.zh.md)
+
+[![GitHub](https://img.shields.io/badge/GitHub-ybniaobu-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/ybniaobu/dsh-3d-viewer) [![npm](https://img.shields.io/badge/npm-dsh--3d--viewer-CB3837?logo=npm&logoColor=white&style=flat-square)](https://www.npmjs.com/package/dsh-3d-viewer?activeTab=readme)
+
+Preview FBX, OBJ, glTF, GLB, and STL models plus TGA, EXR, and HDR textures from the current session's workspace in DSH's right sidebar. Open a model, orbit, zoom, auto-rotate, switch materials and environments, and play embedded animations.
+
+![3D Viewer preview](https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/preview.png)
+
+## Installation and enabling
+
+Distributed as the npm package `dsh-3d-viewer`. The prebuilt `dist/client.js` contains the viewer and Three.js core; model loaders and TGA, EXR, and HDR decoders are package-local lazy chunks fetched only on first use. The four HDRI files ship in the package and are served by a small read-only host route on the local DSH server. React comes from DSH.
+
+### Install from npm (recommended)
+
+1. Open DSH Desktop and choose **Plugins** in the sidebar.
+2. Click **Add plugin** → **Install a third-party plugin**.
+3. Enter `dsh-3d-viewer` (or `dsh-3d-viewer@0.2.0` to pin a version).
+4. Set **Registry** to the official npm registry (npmmirror also works in mainland China).
+5. Click **Install**, then confirm **3D Viewer** is **On** under **Installed plugins**.
+
+> **Updating**: remove the old version under **Plugins**, then install the new one with a higher version.
+
+### Install from a local directory (optional)
+
+Use this for offline or intranet distribution.
+
+1. Unpack the plugin directory anywhere; it must contain `package.json`, `dist/client.js` plus its chunks, `index.js`, `cordis.patch.yml`, and the `assets/hdri/` directory.
+2. Open DSH Desktop and choose **Plugins** in the sidebar.
+3. Click **Add plugin** → **Install a third-party plugin**.
+4. Enter the directory's absolute path (for example `F:\plugins\dsh-3d-viewer`) and click **Install**.
+5. Confirm **3D Viewer** is **On** under **Installed plugins**.
+
+> Local installs link to the directory rather than copying it. Do not move, rename, or delete it, or DSH may not find the plugin on the next start.
+>
+> Plugins run inside the DSH process; install only trusted sources.
+
+### Requirements
+
+- DSH Desktop 0.2.2-rc.1 or newer (built and tested on 0.2.2-rc.1).
+- WebGL 2 support; otherwise the preview reports an error.
+- Model and texture files in the session workspace, reachable through **Files** in the right sidebar.
+
+## Open a model or texture
+
+In any session, open the right sidebar, then **Files** (`Mod+P`), and click an `.fbx`, `.obj`, `.gltf`, `.glb`, `.stl`, `.tga`, `.exr`, or `.hdr` file. It opens in a preview tab; large files and the first environment switch may take a few seconds.
+
+If no preview appears, refresh the page; if it still does not, restart DSH.
+
+## Supported formats
+
+| Format | Support |
+| --- | --- |
+| **FBX** | Meshes, hierarchy, materials, embedded textures, animations, and node data |
+| **OBJ** | Polygons, `o`/`g` groups, normals, UVs, vertex colors, line/point primitives, `mtllib`/MTL, and common textures |
+| **glTF, GLB** | Animations, skinning, embedded resources, and external `.bin` files and textures |
+| **STL** | ASCII and binary STL; neutral double-sided PBR material; binary vertex colors preserved |
+| **TGA, EXR, HDR** | Standalone texture previews and sidecar textures for FBX and OBJ; see [Texture previews](#texture-previews) |
+
+External resources (FBX and glTF textures, glTF `.bin`, OBJ MTL and textures) are read from the session workspace.
+
+Notes:
+
+- **All formats**: lights, cameras, and audio embedded in the file are removed; the preview uses its own lighting and camera.
+- **FBX**: a missing external texture warns but does not block geometry.
+- **OBJ**: a missing MTL falls back to default materials; missing textures use white placeholders.
+- **glTF, GLB**: resources shared by several primitives are read once.
+- **STL**: no materials or animations.
+
+### Texture previews
+
+TGA, EXR, and HDR files can be opened directly from **Files**. The same decoders are used for external FBX and OBJ texture references.
+
+| Format | Decoded data | Preview behavior |
+| --- | --- | --- |
+| **TGA** | 8-bit RGBA (RGBA8) | Pixel data is shown directly; alpha is preserved. |
+| **EXR** | 16-bit half float or 32-bit float, 1–4 channels | Linear HDR data is tone-mapped to SDR for display. |
+| **HDR** | Radiance RGBE, decoded to 16-bit half float by default | Linear HDR data is tone-mapped to SDR for display. |
+
+- EXR and HDR previews use exposure 1 and Reinhard tone mapping before sRGB output; material rendering keeps the linear values.
+- The metadata badge shows dimensions, per-channel bit depth, and the current zoom percentage.
+- Direct previews support wheel zoom, drag-to-pan when zoomed, **Fit** / double-click reset, and **Flip Y** for bottom-up sources.
+- Decoder chunks are fetched only on first use; opening a PNG or JPEG, or a model that never uses TGA, EXR, or HDR, does not download them.
+
+### Not supported
+
+- glTF extensions that need extra decoders: Draco, Meshopt, KTX2.
+- Texture formats without a bundled decoder: DDS, KTX2, PVR, and similar (shown as white placeholders).
+- MTL `map_Ks` / `map_Ns` are not fully mapped to PBR yet (`Kd/Ks/Ns/d` and diffuse/normal/bump/emissive/alpha/displacement textures are supported).
+
+## Code structure
+
+### Host and package
+
+| Path | Responsibility |
+| --- | --- |
+| `index.js` | Host half: registers the read-only `/dsh-3d-viewer/hdri` route |
+| `cordis.patch.yml` | Bundle patch that inserts the plugin row |
+| `package.json` | DSH manifest, exports, engines, and package file list |
+| `dist/client.js` | Prebuilt client entry served through `exports["./client"]` |
+| `dist/client.*.js` | Lazy format and texture decoder chunks, colocated with the entry |
+| `icon.svg` | Plugin icon required at the package root |
+| `locale/*.json` | English/Chinese UI dictionaries |
+| `assets/hdri/` | Packaged Poly Haven CC0 HDRIs served by the host route |
+
+### Client entry and shared data
+
+| Path | Responsibility |
+| --- | --- |
+| `src/client.js` | Registers document previews and Sidebar slots for each format |
+| `src/formats.js` | Model format ids, extensions, titles, and normalization |
+| `src/texture-formats.js` | Standalone texture format ids, extensions, and titles |
+| `src/bytes.js` | Byte, text, path, MIME, and base64 helpers plus cancellation |
+| `src/model.js` | Model stats, embedded-node stripping, and resource disposal |
+
+### UI
+
+| Path | Responsibility |
+| --- | --- |
+| `src/ui/model-viewer.js` | Viewer container: load lifecycle, settings, and status |
+| `src/ui/viewer-surface.js` | Pure presentation: toolbar, stats, animation bar, and overlay |
+| `src/ui/texture-viewer.js` | Standalone TGA, EXR, HDR texture preview, tone mapping, wheel zoom, pan, and vertical flip |
+| `src/ui/animation-bar.js` | Animation transport and progress updates |
+| `src/ui/chrome.js` | Toolbar, material/environment popovers, and stats panel |
+| `src/ui/primitives.js` | Shared small UI primitives |
+| `src/ui/icons.js` | Inline icons |
+| `src/ui/styles.js` | Scoped styles |
+| `src/ui/dictionaries.js` | English/Chinese copy |
+| `src/ui/options.js` | Material and environment option metadata |
+
+### Scene
+
+| Path | Responsibility |
+| --- | --- |
+| `src/scene/create-scene-view.js` | Scene orchestration: renderer, camera, controls, and loop |
+| `src/scene/renderer.js` | Renderer creation and fixed Three settings |
+| `src/scene/renderer-pool.js` | Renderer and PMREM reuse across views |
+| `src/scene/environment.js` | HDRI fetch, PMREM construction, and per-id cache |
+| `src/scene/materials.js` | Phong/Lambert → PBR conversion, presets, and wireframe |
+| `src/scene/ground.js` | Infinite grid shader and shadow receiver |
+| `src/scene/animation.js` | AnimationMixer, clip timeline, and progress |
+| `src/scene/camera.js` | Framing, keyboard orbit, and clip planes |
+| `src/scene/lighting.js` | Key/fill lighting and shadows |
+| `src/scene/render-loop.js` | Coalescing frame scheduler |
+| `src/scene/postprocessing.js` | MSAA/ACES pass and dithering |
+| `src/scene/blue-noise.js` | Blue-noise texture |
+| `src/scene/viewer-error.js` | Typed preview errors |
+
+### Loaders and chunks
+
+| Path | Responsibility |
+| --- | --- |
+| `src/loaders/model-loader.js` | Lazy chunk dispatch and format loading |
+| `src/loaders/fbx.js` | FBX parsing and texture sidecars |
+| `src/loaders/obj.js` | OBJ parsing and MTL/texture resolution |
+| `src/loaders/stl.js` | STL parsing |
+| `src/loaders/gltf.js` | glTF, GLB buffers, textures, animations, and cleanup |
+| `src/loaders/workspace.js` | Resource addresses, workspace reads, TGA, EXR, HDR dispatch, and texture fallback |
+| `src/loaders/chunk-require.js` | `require.async` bridge for DSH package chunks |
+| `src/loaders/three-bridge.js` | Curated Three exports shared with lazy chunks |
+| `src/loaders/chunks/*.js` | One entry per lazy format or texture chunk |
+| `src/vendor/fbx-loader-pbr.js` | Vendored Three FBXLoader with PBR custom attributes |
+
+### Build and tests
+
+| Path | Responsibility |
+| --- | --- |
+| `build.mjs` | Bundles `dist/client.js`, format chunks, and texture chunks |
+| `tests/run.mjs` | Runs each `tests/*.mjs` in its own process |
+| `tests/*.mjs` | Loaders, renderer pool, HDRI route, SSR, manifest, chunks, and texture previews |
+
+Naming: source files use `kebab-case`; React components and classes use `PascalCase`; functions and variables use `camelCase`; module constants use `UPPER_SNAKE_CASE`. Vendored loader internals keep their upstream names.
+
+## License
+
+MIT; see [LICENSE](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/LICENSE). Third-party notices are in [THIRD_PARTY_NOTICES.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/THIRD_PARTY_NOTICES.md), including Three.js (MIT) and Poly Haven HDRIs (CC0; see [assets/hdri/LICENSE.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/assets/hdri/LICENSE.md)). React is provided by DSH and is not distributed with this package.

package/README.zh.md

@@ -1,114 +1,180 @@
-<div align="center">
-  <img src="https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/icon-180.png" alt="3D Viewer 图标" width="96" height="96">
-  <h1 align="center">3D Viewer</h1>
-</div>
-
-[English](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/README.md) | 中文
-
-[![GitHub](https://img.shields.io/badge/GitHub-ybniaobu-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/ybniaobu/dsh-3d-viewer) [![npm](https://img.shields.io/badge/npm-dsh--3d--viewer-CB3837?logo=npm&logoColor=white&style=flat-square)](https://www.npmjs.com/package/dsh-3d-viewer?activeTab=readme)
-
-在 DSH 右侧边栏预览当前会话工作区里的 FBX、OBJ、glTF、GLB、STL 模型。无需上传或联网：打开模型即可旋转、缩放、切换材质与环境，并播放内置动画。
-
-![3D Viewer 预览](https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/preview.png)
-
-## 安装与启用
-
-插件通过 npm 包 `dsh-3d-viewer` 分发。包内 `client.js` 已打包 Three.js 与各类 Loader；四张 HDRI 以文件形式随包分发，由一段只读的宿主路由从本机 DSH 服务器提供，运行时不需联网，也不需 Node.js 或 npm。React 由 DSH 提供。
-
-### 从 npm 安装（推荐）
-
-1. 打开 DSH Desktop，点击侧边栏的 **Plugins（插件）**。
-2. 点击 **Add plugin（添加插件）** → **Install a third-party plugin（安装第三方插件）**。
-3. 输入 `dsh-3d-viewer`；需要固定版本时写 `dsh-3d-viewer@0.1.1`。
-4. **Registry** 选择 npm 官方源（国内也可用 npmmirror）。
-5. 点击 **Install**，在 **Installed plugins（已安装插件）** 中确认 **3D Viewer** 为 **On**。
-6. 回到会话打开模型。若没有出现预览，先刷新页面；仍未出现时重启 DSH。
-
-> **更新**：先在 **Plugins** 中移除旧版本，再安装更高版本的新包。
-
-### 从本地目录安装（可选）
-
-适合离线或内网分发。
-
-1. 把插件目录解压到任意位置，目录需包含 `package.json`、`client.js`、`index.js`、`cordis.patch.yml` 和 `assets/hdri/` 目录。
-2. 打开 DSH Desktop，点击侧边栏的 **Plugins（插件）**。
-3. 点击 **Add plugin（添加插件）** → **Install a third-party plugin（安装第三方插件）**。
-4. 填入插件目录的绝对路径（例如 `F:\plugins\dsh-3d-viewer`），点击 **Install**。
-5. 在 **Installed plugins（已安装插件）** 中确认 **3D Viewer** 为 **On**。
-6. 回到会话打开模型。若没有出现预览，先刷新页面；仍未出现时重启 DSH。
-
-> 本地安装以链接方式引用目录，安装后不要移动、重命名或删除它，否则 DSH 下次启动可能找不到插件。
->
-> 插件代码在 DSH 进程中运行，请只安装可信来源。
-
-### 运行要求
-
-- DSH Desktop 0.2.2-rc.1 或更高版本（在 0.2.2-rc.1 上构建和测试）。
-- 支持 WebGL 2，否则预览会报错。
-- 模型文件位于会话工作区内，可通过右侧边栏的 **Files** 打开。
-
-## 打开一个模型
-
-1. 打开任意会话，点击对话右上角的右侧边栏按钮。
-2. 在右侧边栏打开 **Files**（也可按 `Mod+P`）。
-3. 点击任意 `.fbx`、`.obj`、`.gltf`、`.glb` 或 `.stl` 文件。
-4. 模型在预览标签中打开。大文件和第一次切换环境可能需要几秒钟。
-
-## 支持的文件格式
-
-| 格式 | 支持内容 |
-| --- | --- |
-| **FBX** | 网格、层级、材质、内嵌贴图、动画、节点数据 |
-| **OBJ** | 多边形、`o`/`g` 分组、法线、UV、顶点色、线与点图元、`mtllib`/MTL、常用贴图 |
-| **glTF / GLB** | 动画、蒙皮、内嵌资源、外部 `.bin` 与贴图 |
-| **STL** | ASCII 与二进制 STL；中性双面 PBR 材质；保留二进制顶点色 |
-
-外部资源（FBX/glTF 贴图、glTF `.bin`、OBJ MTL 与贴图）均从会话工作区读取。
-
-四个环境是例外：HDRI 随插件包分发，由宿主端从本机 DSH 服务器的 `/dsh-3d-viewer/hdri/` 只读路由提供，切换环境不会联网。
-
-补充说明：
-
-- **所有格式**：文件自带的灯光、相机和音频节点会被移除，预览统一使用自己的灯光和相机。
-- **FBX**：外部贴图缺失时仅告警，不阻断几何显示。
-- **OBJ**：缺少 MTL 时回退默认材质；贴图缺失时使用白色占位。
-- **glTF / GLB**：多个图元共用的资源只读取一次。
-- **STL**：没有材质和动画。
-
-### 暂不支持
-
-- 需要额外解码器的 glTF 扩展：Draco、Meshopt、KTX2。
-- DSH 无法直接解码的贴图格式：TGA、DDS、EXR 等（显示白色占位）。
-- MTL 的 `map_Ks` / `map_Ns` 尚未完整映射到 PBR（`Kd/Ks/Ns/d` 和 diffuse/normal/bump/emissive/alpha/displacement 贴图已支持）。
-
-## 代码结构
-
-| 路径 | 职责 |
-| --- | --- |
-| `index.js` | 宿主端：注册只读的 `/dsh-3d-viewer/hdri/` 路由，提供包内 HDRI 文件 |
-| `src/client.js` | 插件入口；按格式注册 document preview 与 Sidebar slot |
-| `src/formats.js` | 格式注册表：id、扩展名、标题/徽标文案和格式归一化 |
-| `src/bytes.js` | 共用的字节、文本、路径、MIME、base64 辅助函数与取消错误 |
-| `src/ui/ModelViewer.js` | 渲染体容器，管理加载/错误状态、格式绑定与场景生命周期 |
-| `src/ui/ViewerSurface.js` | 纯展示层：工具条、统计、动画条和状态浮层，可脱离 WebGL 渲染 |
-| `src/ui/AnimationBar.js` | 动画工具条；播放状态与 30Hz 进度更新只重渲染这个小组件 |
-| `src/ui/chrome.js`、`icons.js`、`primitives.js` | 工具条、数据驱动的材质/环境弹层、统计面板、图标与格式化 |
-| `src/ui/styles.js`、`dictionaries.js`、`options.js` | 样式、中英文案和 UI 选项 |
-| `src/scene/createSceneView.js` | 场景编排：renderer、camera、controls、生命周期 |
-| `src/scene/environment.js` | 从宿主路由获取 HDRI、解码、构建 PMREM 并按 id 缓存 |
-| `src/scene/materials.js` | Phong/Lambert → PBR 转换、材质预设、线框材质 |
-| `src/scene/ground.js` | 无限网格 shader 与阴影接收面；网格像素图全页只生成一次 |
-| `src/scene/animation.js` | AnimationMixer、片段时间轴和进度通知 |
-| `src/scene/camera.js`、`lighting.js`、`render-loop.js`、`postprocessing.js`、`blue-noise.js` | 取景与键盘旋转、灯光、帧调度、MSAA/ACES 后处理与蓝色噪声抖动 |
-| `src/loaders/workspace.js` | `resourceAddress` 解析、workspaceFiles 读取、绝对路径回退、贴图 Blob/白占位与资源回收 |
-| `src/loaders/model-loader.js` | FBX / OBJ / glTF / GLB / STL 异步加载与表驱动格式分派 |
-| `src/loaders/gltf.js` | glTF/GLB 外部 buffer/贴图预取（按资源去重）、动画挂载和资源清理 |
-| `src/model.js` | FBX / OBJ / STL 同步解析、统计、资源释放 |
-| `src/vendor/FBXLoaderPbr.js` | vendored Three.js FBXLoader，额外读取金属度/粗糙度自定义属性 |
-| `tests/run.mjs` | 测试入口：每个 `tests/*.mjs` 都在独立进程中运行 |
-| `icon.svg` | 插件图标；DSH 元信息要求它位于包根目录 |
-| `assets/hdri/` | 由宿主路由提供的 HDRI 文件（Poly Haven CC0） |
-
-## 许可证
-
-MIT，见 [LICENSE](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/LICENSE)。第三方声明见 [THIRD_PARTY_NOTICES.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/THIRD_PARTY_NOTICES.md)，包括 Three.js（MIT）与 Poly Haven HDRI（CC0，见 [assets/hdri/LICENSE.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/assets/hdri/LICENSE.md)）。React 由 DSH 提供，不随包分发。
+<div align="center">
+  <img src="https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/icon-180.png" alt="3D Viewer 图标" width="96" height="96">
+  <h1 align="center">3D Viewer</h1>
+</div>
+
+[English](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/README.md) | 中文
+
+[![GitHub](https://img.shields.io/badge/GitHub-ybniaobu-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/ybniaobu/dsh-3d-viewer) [![npm](https://img.shields.io/badge/npm-dsh--3d--viewer-CB3837?logo=npm&logoColor=white&style=flat-square)](https://www.npmjs.com/package/dsh-3d-viewer?activeTab=readme)
+
+在 DSH 右侧边栏预览当前会话工作区里的 FBX、OBJ、glTF、GLB、STL 模型，以及 TGA、EXR、HDR 纹理。打开模型即可旋转、缩放、自动旋转、切换材质与环境，并播放内置动画。
+
+![3D Viewer 预览](https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/preview.png)
+
+## 安装与启用
+
+插件通过 npm 包 `dsh-3d-viewer` 分发。包内 `dist/client.js` 包含查看器与 Three.js 核心；模型 Loader 与 TGA、EXR、HDR 解码器都是包内懒加载 chunk，只在首次使用时加载。四张 HDRI 随包分发，由只读宿主路由从本机 DSH 服务器提供。React 由 DSH 提供。
+
+### 从 npm 安装（推荐）
+
+1. 打开 DSH Desktop，点击侧边栏的 **Plugins（插件）**。
+2. 点击 **Add plugin（添加插件）** → **Install a third-party plugin（安装第三方插件）**。
+3. 输入 `dsh-3d-viewer`；需要固定版本时写 `dsh-3d-viewer@0.2.0`。
+4. **Registry** 选择 npm 官方源（国内也可用 npmmirror）。
+5. 点击 **Install**，在 **Installed plugins（已安装插件）** 中确认 **3D Viewer** 为 **On**。
+
+> **更新**：先在 **Plugins** 中移除旧版本，再安装更高版本的新包。
+
+### 从本地目录安装（可选）
+
+适合离线或内网分发。
+
+1. 把插件目录解压到任意位置，目录需包含 `package.json`、`dist/client.js` 及其 chunks、`index.js`、`cordis.patch.yml` 和 `assets/hdri/` 目录。
+2. 打开 DSH Desktop，点击侧边栏的 **Plugins（插件）**。
+3. 点击 **Add plugin（添加插件）** → **Install a third-party plugin（安装第三方插件）**。
+4. 填入插件目录的绝对路径（例如 `F:\plugins\dsh-3d-viewer`），点击 **Install**。
+5. 在 **Installed plugins（已安装插件）** 中确认 **3D Viewer** 为 **On**。
+
+> 本地安装以链接方式引用目录，安装后不要移动、重命名或删除它，否则 DSH 下次启动可能找不到插件。
+>
+> 插件代码在 DSH 进程中运行，请只安装可信来源。
+
+### 运行要求
+
+- DSH Desktop 0.2.2-rc.1 或更高版本（在 0.2.2-rc.1 上构建和测试）。
+- 支持 WebGL 2，否则预览会报错。
+- 模型和纹理文件位于会话工作区内，可通过右侧边栏的 **Files** 打开。
+
+## 打开模型或纹理
+
+在任意会话中打开右侧边栏，再打开 **Files**（`Mod+P`），点击 `.fbx`、`.obj`、`.gltf`、`.glb`、`.stl`、`.tga`、`.exr` 或 `.hdr` 文件，即可在预览标签中打开。大文件和第一次切换环境可能需要几秒钟。
+
+若没有出现预览，先刷新页面；仍未出现时重启 DSH。
+
+## 支持的文件格式
+
+| 格式 | 支持内容 |
+| --- | --- |
+| **FBX** | 网格、层级、材质、内嵌贴图、动画、节点数据 |
+| **OBJ** | 多边形、`o`/`g` 分组、法线、UV、顶点色、线与点图元、`mtllib`/MTL、常用贴图 |
+| **glTF、GLB** | 动画、蒙皮、内嵌资源、外部 `.bin` 与贴图 |
+| **STL** | ASCII 与二进制 STL；中性双面 PBR 材质；保留二进制顶点色 |
+| **TGA、EXR、HDR** | 独立纹理预览，以及 FBX、OBJ 的 sidecar 贴图；见下方 [纹理预览](#纹理预览) |
+
+外部资源（FBX、glTF 贴图、glTF `.bin`、OBJ MTL 与贴图）均从会话工作区读取。
+
+补充说明：
+
+- **所有格式**：文件自带的灯光、相机和音频节点会被移除，预览统一使用自己的灯光和相机。
+- **FBX**：外部贴图缺失时仅告警，不阻断几何显示。
+- **OBJ**：缺少 MTL 时回退默认材质；贴图缺失时使用白色占位。
+- **glTF、GLB**：多个图元共用的资源只读取一次。
+- **STL**：没有材质和动画。
+
+### 纹理预览
+
+TGA、EXR、HDR 文件可以直接从 **Files** 打开；同一套解码器也用于 FBX、OBJ 的外部贴图引用。
+
+| 格式 | 解码数据 | 预览行为 |
+| --- | --- | --- |
+| **TGA** | 8-bit RGBA（RGBA8） | 直接显示像素数据，保留 alpha。 |
+| **EXR** | 16-bit half float 或 32-bit float，1–4 通道 | 线性 HDR 数据经色调映射后显示。 |
+| **HDR** | Radiance RGBE，默认解码为 16-bit half float | 线性 HDR 数据经色调映射后显示。 |
+
+- EXR、HDR 预览使用曝光 1 和 Reinhard 色调映射，再输出 sRGB；材质渲染仍使用线性值。
+- 元信息显示尺寸、每通道位深和当前缩放比例。
+- 独立预览支持滚轮缩放、放大后拖拽平移、**适应窗口** / 双击复位，以及 **垂直翻转**。
+- 解码 chunk 只在首次使用时加载；打开 PNG、JPEG 或不使用 TGA、EXR、HDR 的模型不会下载它们。
+
+### 暂不支持
+
+- 需要额外解码器的 glTF 扩展：Draco、Meshopt、KTX2。
+- 暂无内置解码器的贴图格式：DDS、KTX2、PVR 等（显示白色占位）。
+- MTL 的 `map_Ks` / `map_Ns` 尚未完整映射到 PBR（`Kd/Ks/Ns/d` 和 diffuse/normal/bump/emissive/alpha/displacement 贴图已支持）。
+
+## 代码结构
+
+### 宿主与打包
+
+| 路径 | 职责 |
+| --- | --- |
+| `index.js` | 宿主端：注册只读的 `/dsh-3d-viewer/hdri` 路由 |
+| `cordis.patch.yml` | 插入插件行的 bundle patch |
+| `package.json` | DSH manifest、exports、engines 和打包文件列表 |
+| `dist/client.js` | 预构建客户端入口，经 `exports["./client"]` 提供 |
+| `dist/client.*.js` | FBX、OBJ、glTF、GLB、STL 与 TGA、EXR、HDR 懒加载 chunk，与入口同目录 |
+| `icon.svg` | DSH 元信息要求的包根图标 |
+| `locale/*.json` | 中英文 UI 字典 |
+| `assets/hdri/` | 由宿主路由提供的 Poly Haven CC0 HDRI |
+
+### 客户端入口与共享数据
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/client.js` | 按格式注册 document preview 与 Sidebar slot |
+| `src/formats.js` | 模型格式 id、扩展名、标题与归一化 |
+| `src/texture-formats.js` | 独立纹理格式的 id、扩展名与标题 |
+| `src/bytes.js` | 字节、文本、路径、MIME、base64 辅助与取消错误 |
+| `src/model.js` | 模型统计、内嵌节点剥离与资源释放 |
+
+### UI
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/ui/model-viewer.js` | 渲染体容器：加载生命周期、设置与状态 |
+| `src/ui/viewer-surface.js` | 纯展示：工具条、统计、动画条与状态浮层 |
+| `src/ui/texture-viewer.js` | TGA、EXR、HDR 独立纹理预览、色调映射、滚轮缩放、拖拽平移与垂直翻转 |
+| `src/ui/animation-bar.js` | 动画播放控制与进度更新 |
+| `src/ui/chrome.js` | 工具条、材质/环境弹层与统计面板 |
+| `src/ui/primitives.js` | 共用小组件 |
+| `src/ui/icons.js` | 内联图标 |
+| `src/ui/styles.js` | 作用域样式 |
+| `src/ui/dictionaries.js` | 中英文案 |
+| `src/ui/options.js` | 材质/环境选项元数据 |
+
+### 场景
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/scene/create-scene-view.js` | 场景编排：renderer、camera、controls、渲染循环 |
+| `src/scene/renderer.js` | Renderer 创建与固定的 Three 设置 |
+| `src/scene/renderer-pool.js` | 跨视图复用 renderer 与 PMREM |
+| `src/scene/environment.js` | HDRI 获取、PMREM 构建与按 id 缓存 |
+| `src/scene/materials.js` | Phong/Lambert → PBR、材质预设与线框 |
+| `src/scene/ground.js` | 无限网格 shader 与阴影接收面 |
+| `src/scene/animation.js` | AnimationMixer、片段时间轴与进度 |
+| `src/scene/camera.js` | 取景、键盘旋转与裁剪面 |
+| `src/scene/lighting.js` | 主/补光与阴影 |
+| `src/scene/render-loop.js` | 合并帧调度 |
+| `src/scene/postprocessing.js` | MSAA/ACES 与抖动 |
+| `src/scene/blue-noise.js` | 蓝噪声贴图 |
+| `src/scene/viewer-error.js` | 类型化预览错误 |
+
+### 加载器与 chunks
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/loaders/model-loader.js` | 懒加载 chunk 分派与格式加载 |
+| `src/loaders/fbx.js` | FBX 解析与贴图 sidecar |
+| `src/loaders/obj.js` | OBJ 解析与 MTL/贴图解析 |
+| `src/loaders/stl.js` | STL 解析 |
+| `src/loaders/gltf.js` | glTF、GLB buffer、贴图、动画与清理 |
+| `src/loaders/workspace.js` | 资源地址、工作区读取、TGA、EXR、HDR 分派与贴图回退 |
+| `src/loaders/chunk-require.js` | DSH 包 chunk 的 `require.async` 桥 |
+| `src/loaders/three-bridge.js` | 与懒加载 chunk 共享的 Three 导出 |
+| `src/loaders/chunks/*.js` | 每个懒加载格式/纹理 chunk 一个入口 |
+| `src/vendor/fbx-loader-pbr.js` | vendored Three FBXLoader，额外支持 PBR 自定义属性 |
+
+### 构建与测试
+
+| 路径 | 职责 |
+| --- | --- |
+| `build.mjs` | 构建 `dist/client.js`、格式 chunk 与纹理 chunk |
+| `tests/run.mjs` | 每个 `tests/*.mjs` 在独立进程中运行 |
+| `tests/*.mjs` | loader、renderer pool、HDRI 路由、SSR、manifest、chunks 与纹理预览 |
+
+命名规范：源码文件用 `kebab-case`；React 组件和类用 `PascalCase`；函数和变量用 `camelCase`；模块常量用 `UPPER_SNAKE_CASE`。vendored loader 的内部实现保留上游命名。
+
+## 许可证
+
+MIT，见 [LICENSE](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/LICENSE)。第三方声明见 [THIRD_PARTY_NOTICES.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/THIRD_PARTY_NOTICES.md)，包括 Three.js（MIT）与 Poly Haven HDRI（CC0，见 [assets/hdri/LICENSE.md](https://github.com/ybniaobu/dsh-3d-viewer/blob/main/assets/hdri/LICENSE.md)）。React 由 DSH 提供，不随包分发。