dsh-file-explorer-preview-molstar

中文 | English

A DSH Web plugin that adds a Mol* 3D structure viewer to dsh-file-explorer, overriding its plain previews for protein-structure and small-molecule files.

Select a .cif / .pdb (or any supported format below) in the file explorer and the preview panel renders an interactive 3D model instead of raw text.

Screenshots

Dark theme	Light theme

Features

• 3D structure viewer built on molstar (PluginContext + a minimal canvas — no full Mol* UI).
• Representation presets: Auto / Cartoon / Ball & Stick / Molecular surface.
• Coloring by default / chain / entity, reset camera, spin toggle, and a dark/light background that follows DSH's data-ds-dark-theme.
• Status bar with the format badge and atom/residue/chain counts.
• Localized toolbar/status copy (中文 / English).
• Large & binary files: for files over the core's 2 MiB text cap (returned as the text-large kind since dsh-file-explorer v0.3.0), and for .bcif, the plugin fetches raw bytes through the core's fileExplorer.readRawFile (standard in dsh-file-explorer v0.1.0+).

Supported formats

Extension	Format
cif mmcif mcif	mmCIF
bcif	BinaryCIF
pdb ent	PDB
pdbqt	PDBQT
pqr	PQR
sdf sd	SDF
mol	MOL
mol2	MOL2
xyz	XYZ
gro	GRO

Install

From the Git repository

dsh plugin --profile web add github:wolfsonliu/dsh-file-explorer-preview-molstar
dsh web

From source

git clone https://github.com/wolfsonliu/dsh-file-explorer-preview-molstar
cd dsh-file-explorer-preview-molstar
npm install
npm run build
dsh plugin --profile web add .
dsh web

Dependencies

This plugin requires @dsh-external/dsh-file-explorer v0.1.0 or later — it injects the fileExplorer cordis service (registerViewer / registerPreview / writeFile / readRawFile). Install and enable dsh-file-explorer before this plugin:

# install the core from git
dsh plugin --profile web add github:wolfsonliu/dsh-file-explorer

# or, from source
git clone https://github.com/wolfsonliu/dsh-file-explorer
cd dsh-file-explorer
npm install && npm run build
dsh plugin --profile web add .

For local development, this repo's devDependencies resolves @dsh-external/dsh-file-explorer's ./client type definitions. Point it at your checkout or your registry's published package before npm install.

For files ≤ 2 MiB the plugin parses the text preview content directly. For larger text files (text-large since v0.3.0) and .bcif, the plugin uses readRawFile to fetch raw bytes — a standard part of the FileExplorerService contract since dsh-file-explorer v0.1.0. Since dsh-file-explorer v0.7.0 the plugin passes an AbortSignal so the in-flight read is aborted when you switch files or close the preview.

On dsh-file-explorer v0.9.0+ the plugin registers one named viewer via registerViewer — id: 'molstar', label Mol* Structure — across every supported extension, so the Open with… menu and the preview-panel viewer switcher show a proper name instead of the generic "Extension viewer". On older cores (pre-v0.9.0) it falls back to one registerPreview per extension.

Limitations

• Requires a WebGL-capable browser.
• Read-only preview (no editing).
• Trajectories and density maps (.dcd, .nc, .map) are out of scope.

Development

npm run check   # tsc type check
npm test        # vitest unit tests
npm run build   # tsc + tsdown (single-file lib/client.js bundling molstar)

The real WebGL mount cannot run under jsdom; verify it with dsh web and a structure file in examples/.

After npm run build, hard-refresh the browser (Ctrl/Cmd+Shift+R): dsh web may keep serving a cached plugin bundle, so a soft reload can leave your latest build unused.

Acknowledgments

This plugin is built on Mol* (/ˈmol-star/), a next-generation technology stack for (not only) macromolecular structure data, jointly initiated by PDBe and RCSB PDB.

When using Mol*, please cite:

David Sehnal, Sebastian Bittrich, Mandar Deshpande, Radka Svobodová, Karel Berka, Václav Bazgier, Sameer Velankar, Stephen K Burley, Jaroslav Koča, Alexander S Rose: Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures, Nucleic Acids Research, 2021; https://doi.org/10.1093/nar/gkab314.

License

MIT