dsh-3d-viewer 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-3d-viewer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+<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>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.

package/README.zh.md

@@ -0,0 +1,114 @@
+<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 提供，不随包分发。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,54 @@
+# Third-party notices
+
+This project's own source code is licensed under the MIT License; see
+[LICENSE](LICENSE). The following third-party components are included in or
+used by this package.
+
+## Three.js
+
+`client.js` bundles the following MIT-licensed Three.js code:
+
+- Three.js core (`three`)
+- `FBXLoader`, `OBJLoader`, `MTLLoader`, `GLTFLoader`, `STLLoader`, `OrbitControls`, `HDRLoader`
+- `EffectComposer`, `RenderPass`, `ShaderPass`
+- Three.js addon dependencies used by the loaders (`fflate`, `NURBSCurve`)
+
+`src/vendor/FBXLoaderPbr.js` is a modified copy of Three.js's `FBXLoader`.
+
+The MIT License
+
+Copyright © 2010-2026 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## Poly Haven HDRIs
+
+`assets/hdri/*.hdr` are Poly Haven assets released under
+[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 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
+
+The viewer source imports React, but the production bundle externalizes it
+(`--external:react`). React is supplied by the DSH host at runtime and is not
+included in this package.

package/assets/hdri/LICENSE.md

@@ -0,0 +1,17 @@
+# HDRI assets
+
+All four 1k HDRIs are downloaded from [Poly Haven](https://polyhaven.com/) and
+are licensed under [CC0](https://polyhaven.com/license). They can be used
+commercially without attribution; the source links below are recorded for
+provenance.
+
+| File | Source | Download |
+| --- | --- | --- |
+| `nature.hdr` | [Forest Slope](https://polyhaven.com/a/forest_slope) | `https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/forest_slope_1k.hdr` |
+| `city.hdr` | [Potsdamer Platz](https://polyhaven.com/a/potsdamer_platz) | `https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/potsdamer_platz_1k.hdr` |
+| `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 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.