dsh-3d-viewer 0.1.0 → 0.1.1

package/README.md

@@ -1,20 +1,25 @@
-# 3D Viewer
+<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 | [中文](README.zh.md)
+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](assets/preview.png)
+![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` already bundles Three.js, the loaders, and four HDRIs; no Node.js or npm download is needed at runtime, and React comes from DSH.
+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.0` to pin a version).
+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.
@@ -25,7 +30,7 @@ Distributed as the npm package `dsh-3d-viewer`. The prebuilt `client.js` already
 
 Use this for offline or intranet distribution.
 
-1. Unpack the plugin directory anywhere; it must contain `package.json`, `client.js`, `index.js`, and `cordis.patch.yml`.
+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**.
@@ -38,7 +43,7 @@ Use this for offline or intranet distribution.
 
 ### Requirements
 
-- DSH Desktop.
+- 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.
 
@@ -60,6 +65,8 @@ Use this for offline or intranet distribution.
 
 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.
@@ -78,6 +85,7 @@ Notes:
 
 | 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 |
@@ -87,7 +95,7 @@ Notes:
 | `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 decoding, PMREM construction, and environment map caching |
+| `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 |
@@ -97,11 +105,10 @@ Notes:
 | `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 |
-| `src/generated/hdri-data.js` | Generated embedded HDRI data; do not edit by hand |
 | `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/` | HDRI source files |
+| `assets/hdri/` | Packaged HDRI files served by the host route (Poly Haven CC0) |
 
 ## License
 
-MIT; see [LICENSE](LICENSE). Third-party notices are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), including Three.js (MIT) and Poly Haven HDRIs (CC0; see [assets/hdri/LICENSE.md](assets/hdri/LICENSE.md)). React is provided by DSH and is not distributed with this package.
+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,20 +1,25 @@
-# 3D Viewer
+<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](README.md) | 中文
+[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 预览](assets/preview.png)
+![3D Viewer 预览](https://raw.githubusercontent.com/ybniaobu/dsh-3d-viewer/main/assets/preview.png)
 
 ## 安装与启用
 
-插件通过 npm 包 `dsh-3d-viewer` 分发。包内 `client.js` 已打包 Three.js、各类 Loader 和四张 HDRI；运行时不需 Node.js 或 npm，React 由 DSH 提供。
+插件通过 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.0`。
+3. 输入 `dsh-3d-viewer`；需要固定版本时写 `dsh-3d-viewer@0.1.1`。
 4. **Registry** 选择 npm 官方源（国内也可用 npmmirror）。
 5. 点击 **Install**，在 **Installed plugins（已安装插件）** 中确认 **3D Viewer** 为 **On**。
 6. 回到会话打开模型。若没有出现预览，先刷新页面；仍未出现时重启 DSH。
@@ -25,7 +30,7 @@
 
 适合离线或内网分发。
 
-1. 把插件目录解压到任意位置，目录需包含 `package.json`、`client.js`、`index.js`、`cordis.patch.yml`。
+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**。
@@ -38,7 +43,7 @@
 
 ### 运行要求
 
-- DSH Desktop。
+- DSH Desktop 0.2.2-rc.1 或更高版本（在 0.2.2-rc.1 上构建和测试）。
 - 支持 WebGL 2，否则预览会报错。
 - 模型文件位于会话工作区内，可通过右侧边栏的 **Files** 打开。
 
@@ -60,6 +65,8 @@
 
 外部资源（FBX/glTF 贴图、glTF `.bin`、OBJ MTL 与贴图）均从会话工作区读取。
 
+四个环境是例外：HDRI 随插件包分发，由宿主端从本机 DSH 服务器的 `/dsh-3d-viewer/hdri/` 只读路由提供，切换环境不会联网。
+
 补充说明：
 
 - **所有格式**：文件自带的灯光、相机和音频节点会被移除，预览统一使用自己的灯光和相机。
@@ -78,6 +85,7 @@
 
 | 路径 | 职责 |
 | --- | --- |
+| `index.js` | 宿主端：注册只读的 `/dsh-3d-viewer/hdri/` 路由，提供包内 HDRI 文件 |
 | `src/client.js` | 插件入口；按格式注册 document preview 与 Sidebar slot |
 | `src/formats.js` | 格式注册表：id、扩展名、标题/徽标文案和格式归一化 |
 | `src/bytes.js` | 共用的字节、文本、路径、MIME、base64 辅助函数与取消错误 |
@@ -87,7 +95,7 @@
 | `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 构建、环境贴图缓存 |
+| `src/scene/environment.js` | 从宿主路由获取 HDRI、解码、构建 PMREM 并按 id 缓存 |
 | `src/scene/materials.js` | Phong/Lambert → PBR 转换、材质预设、线框材质 |
 | `src/scene/ground.js` | 无限网格 shader 与阴影接收面；网格像素图全页只生成一次 |
 | `src/scene/animation.js` | AnimationMixer、片段时间轴和进度通知 |
@@ -97,11 +105,10 @@
 | `src/loaders/gltf.js` | glTF/GLB 外部 buffer/贴图预取（按资源去重）、动画挂载和资源清理 |
 | `src/model.js` | FBX / OBJ / STL 同步解析、统计、资源释放 |
 | `src/vendor/FBXLoaderPbr.js` | vendored Three.js FBXLoader，额外读取金属度/粗糙度自定义属性 |
-| `src/generated/hdri-data.js` | 构建生成的内置 HDRI 数据，不要手改 |
 | `tests/run.mjs` | 测试入口：每个 `tests/*.mjs` 都在独立进程中运行 |
 | `icon.svg` | 插件图标；DSH 元信息要求它位于包根目录 |
-| `assets/hdri/` | HDRI 源文件 |
+| `assets/hdri/` | 由宿主路由提供的 HDRI 文件（Poly Haven CC0） |
 
 ## 许可证
 
-MIT，见 [LICENSE](LICENSE)。第三方声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)，包括 Three.js（MIT）与 Poly Haven HDRI（CC0，见 [assets/hdri/LICENSE.md](assets/hdri/LICENSE.md)）。React 由 DSH 提供，不随包分发。
+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 提供，不随包分发。

package/THIRD_PARTY_NOTICES.md

@@ -43,7 +43,9 @@ THE SOFTWARE.
 [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). CC0 requires no
 attribution; the source links and license note are kept in
 [assets/hdri/LICENSE.md](assets/hdri/LICENSE.md) for provenance.
-The HDRIs are embedded into `client.js` as base64 data URLs at build time.
+The HDRIs ship as files in the package and are served at runtime by the
+plugin's Host route (`/dsh-3d-viewer/hdri/`); they are not embedded in
+`client.js`.
 
 ## React
 

package/assets/hdri/LICENSE.md

@@ -12,5 +12,6 @@ provenance.
 | `indoor.hdr` | [Lythwood Room](https://polyhaven.com/a/lythwood_room) | `https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/lythwood_room_1k.hdr` |
 | `studio.hdr` | [Studio Small 09](https://polyhaven.com/a/studio_small_09) | `https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/studio_small_09_1k.hdr` |
 
-The files are embedded into `src/generated/hdri-data.js` at build time so the
-client bundle does not depend on a separate asset URL or network request.
+The files ship inside the plugin package and are served at runtime by the
+plugin's Host route (`/dsh-3d-viewer/hdri/`), so the client bundle does not
+embed them and no network request is made.