dsh-molbio-tools 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -10,6 +10,115 @@
   改为按**包名**引用后模块缓存问题随之消失——没有拷贝，也就没有需要保持同步的版本目录。
   下文历史条目里出现的 `vN` 目录保持原样，作为当时的记录。
 
+## [0.25.0] — 2026-11-10（浏览器内 3D 结构预览：真实原子模型）
+
+**工具数不变（64），benchmark 不变（65 题 / 64 覆盖）。** 这一版把结构文件接进已有的
+**Molbio** 右栏面板：选中 `.pdb` / `.ent` / `.cif` / `.mmcif` / `.sdf` / `.mol`，
+浏览器当场渲染一个可旋转、可缩放的**真实 3D 原子模型**（ball-and-stick / space-filling），
+不需要工具调用、不落盘 SVG、不弹系统查看器，也没有引入任何第三方库。
+
+> 0.25.0 在发布前从 2D PCA 投影改成了 3D。2D 预览只有一张固定投影，丢失深度、遮挡和
+> 原子空间关系；学术界常见的结构配图是立体原子/表面模型，而不是单张 PCA 线图。
+
+### 1. 解析：`structure-preview.mjs`
+
+- **PDB**：只读第一个 MODEL，跳过非 A/A 的 altLoc；读 `ATOM`/`HETATM` 的坐标、元素、
+  残基、链与 `CONECT`。
+- **mmCIF**：读 `_atom_site` 循环，quote 与 `;` 文本块都能切词；优先 `auth_*` 列，
+  缺列时回退 `label_*`；只取第一个 model。
+- **SDF/MOL**：只读第一条记录（`$$$$` 之前），解析 V2000 的原子与键；**V3000 明确拒绝**
+  并提示导出 V2000，而不是猜。
+- 解析器只负责坐标/元素/链/键；渲染在独立模块里，浏览器与 Node 测试共用同一份源码。
+
+### 2. 软件渲染：`structure-render.mjs`
+
+- **不依赖 WebGL / Three.js**：纯 JS 软件光栅化，返回 RGB 缓冲，Canvas 只负责
+  `putImageData`。这样同一套像素可以被 Node 测试和文档截图复用。
+- 透视投影 + **z-buffer** + 球面/柱面 Phong 光照 + 深度雾化；CPK 配色
+  （C 灰、N 蓝、O 红、S 黄、P 橙）。
+- 两种表示：**ball-and-stick**（小球 + 键）与 **space-filling**（范德华球）。
+- 键图：SDF 用显式键；PDB/mmCIF 用共价半径空间网格推断，并与 `CONECT` 合并
+  （1CRN 的 CONECT 只有 6 条，不能直接当完整键表）。
+- 边界：面板最多渲染 **12,000 个重原子**；水与氢默认不画；拖动时 1× 采样、松开后 2×；
+  单帧约 50–120 ms（1CRN 327 原子 / 1BNA 486 原子），不做分子表面、静电势或测量。
+- 明确写"preview, not for measurements"：这是看的模型，不是分析工具。
+
+### 3. 面板
+
+- Molbio tab 的文件分类新增 `structure`；列表、排序、元信息（标题/格式/原子数/链数/残基数）
+  复用现有状态机。
+- 结构记录改用 `<canvas>`：**拖拽旋转、滚轮缩放、双击复位**；工具栏切换
+  ball-and-stick / space-filling；元素图例与操作提示在画布下方。
+- 质粒图谱与 sequence logo 仍用原来的 SVG 宿主；只有结构记录走 canvas。
+- 只改浏览器半也改变了 `lib/client.js`，所以根包 `0.24.1 → 0.25.0`、面板包
+  `0.1.10 → 0.1.11` 同时升版本。
+
+### 4. 顺带修掉的 bundler 缺陷
+
+客户端 bundler 在生成 re-export 时丢掉了 imported name，产物里所有
+`browser-api.mjs` 再导出都变成 `require(target).undefined`。格式检查一直是绿的，但真实
+浏览器半会拿到 `undefined`。现在 re-export 保留 `imported`，并在 `test/client.mjs` 里
+加了"产物不得含 `require(...).undefined`"的结构断言。
+
+### 5. 测试与边界
+
+- `test/structure.mjs`：PDB/mmCIF/SDF 已知坐标与计数；共价键推断；渲染像素
+  （中心原子、非背景像素、确定性、两种表示、PNG 编码）；V3000/空坐标/原子 cap 的错误路径。
+- `test/panel-render.mjs`：真实 PDB 点选后 canvas 被绘制，拖拽会触发重绘。
+- `test/client.mjs`、`test/client-mount.mjs`、`test/contract.mjs`（17 项）与
+  `build/client-bundle.mjs --check` 全绿；工具数仍 64，benchmark 仍 65 题。
+- 没有采用 `ctx.documentPreviews.register`：现有 Molbio tab 已有文件列表、canvas 与错误态；
+  新增 keyed 容器换不来新的用户能力。
+- **不做**：卡通 ribbon、分子表面、静电势、对称、V3000、多 model 动画、测量工具。
+
+## [0.24.1] — 2026-11-08（输入边界与数据安全加固；工具数不变）
+
+**不新增工具：工具数保持 64，benchmark 保持 65 题 / 64 覆盖。** 这一版只修“已经在产品里、
+但不会报错的错”。面板包 `0.1.9 → 0.1.10`：两个客户端产物因 `seqio.mjs` /
+`protein-structure.mjs` 的加固改动而重建，按仓库规则必须升版本号，否则会用同一版本发不同字节。
+
+### 1. 数据安全与路径语义
+
+- `molbio_paper_export_bibtex`：自定义 `file` 不以 `.json` 结尾时，旧逻辑把库路径本身当
+  输出路径，BibTeX 会**覆盖文献库**。现在始终派生独立的 `.bib`（`refs.txt` →
+  `refs.txt.bib`），库文件保持不变。
+- 相对路径读取改为按**会话工作区**解析（`sandboxPolicy.resolve(...).workspaceRoot`），
+  不再落到 provider 的 `process.cwd()`；绝对路径行为不变。
+- 文献库/记录库加载时拒绝 `null` 或标量条目，返回带文件名的输入错误，而不是
+  `paperKey()` / `record.name.trim()` 抛出的原始 `TypeError`；协议重命名与新增使用
+  同一条重名规则；`molbio_paper_update` 在标题/URL/PMID 变化后重算派生 id。
+- `molbio_batch_analyze`：显式 `paths` 也受 `max_files` 约束；无法解析的路径变成一条
+  错误行而不是整批失败；glob 先转义反斜杠，`.` 不再被当通配符（`a.fa` 不会匹配
+  `aXfa`）。
+
+### 2. 并发声明与大输入
+
+- 四个总会写默认 SVG 的工具——`molbio_helical_wheel`、`molbio_hydropathy_plot`、
+  `molbio_protein_charge`、`molbio_dotplot`——以及带 `output_path` 的
+  `molbio_fasta_fastq extract` 改为 `safe: false`。旧谓词在 `output_path` 省略时
+  声称并发安全，而默认文件仍会被并发调用互相覆盖。
+- 图表/FASTQ/蛋白剖面不再把用户规模数组展开进 `Math.min(...)`/`Math.max(...)`：
+  200,000 行表格、130,000 条 reads 与长蛋白在文档声明的上限内不再抛 `RangeError`；
+  FASTQ 汇总改为单次流式计数，不再物化全部 Phred 值。
+- `molbio_pubmed_abstract` 的 efetch 传输失败改为具名输入错误，不再让原始异常逃出工具。
+
+### 3. 发布与仓库卫生
+
+- `.github/workflows/test.yml` 增加 `permissions: contents: read`；
+  `.gitignore` 忽略 `.codex-tmp/`。
+- `preset/install.mjs` 校验 `--profile`（字母/数字开头，仅 `._-`），避免 profile 名
+  经 Windows shell 时被当作命令元字符。
+- 同步多处注释里过时的工具数（57/60/62 → 64）。
+
+### 4. 验证与边界
+
+- `npm test` 全绿：smoke 64 工具、benchmark 65 题 / 64 覆盖、`preset-health` 29 行、
+  `release` 13 项；`build/client-bundle.mjs --check` 与 `build/preset-patch.mjs --check`
+  与源一致。
+- 不新增工具、不改 preset 行清单、不改 DSH 基线（0.2.2-rc.1）。
+- `benchmark-changed` 的 POSIX 路径断言在本地沙箱因 Node 无法 spawn `git` 未执行；
+  CI 会执行。这是沙箱限制，不是仓库缺陷。
+
 ## [0.24.0] — 2026-11-05（载体/接头污染筛查；FASTQ 修剪；接头表静默错修复）
 
 **工具数 62 → 64，benchmark 63 → 65 题（64/64 覆盖）。** 两块工作都来自候选池 survey：

package/README.md

@@ -383,7 +383,7 @@ mutations remain deferred"）。所以插件无法在工作区里合法地落一
 
 | 落点 | 内容 |
 | --- | --- |
-| **Molbio**（右栏 tab） | 列出当前会话工作区的序列文件，选中**当场在面板里画出来**：`.dna`/`.gb`/`.gbk` 出质粒图谱 + 特征表，`.fa`/`.fasta` 出序列标识图 |
+| **Molbio**（右栏 tab） | 列出当前会话工作区的序列与结构文件，选中**当场在面板里画出来**：`.dna`/`.gb`/`.gbk` 出质粒图谱 + 特征表，`.fa`/`.fasta` 出序列标识图，`.pdb`/`.cif`/`.sdf` 等出可旋转的 3D ball-and-stick / space-filling 模型 |
 | **Papers**（右栏 tab） | 把 `papers.json` 渲染成可搜索的阅读列表（标题直达 PubMed/原 URL） |
 | **图谱调用卡**（对话内） | 画图谱的工具**直接在对话里画出这次产出的图谱**，不必再去开文件 |
 
@@ -767,6 +767,8 @@ dsh-molbio-tools/
 ├── methylation.mjs  # 甲基化敏感位点检查 + 双酶切 buffer 兼容
 ├── protein.mjs      # 蛋白性质 / 肽段酶切 / 密码子优化
 ├── protein-structure.mjs # 螺旋轮与疏水性图
+├── structure-preview.mjs # PDB/mmCIF/SDF 解析器（浏览器面板）
+├── structure-render.mjs # 软件光栅化 3D ball-and-stick / space-filling 渲染器
 ├── protein-charge.mjs # 电荷-pH 滴定曲线 + pI（bjellqvist/emboss 两套 pK）
 ├── genbank.mjs      # GenBank flatfile 解析器
 ├── snapgene.mjs     # SnapGene .dna 二进制解析器

package/batch.mjs

@@ -46,7 +46,11 @@ export function detectBatchFormat(path, text) {
 /** Convert a simple basename glob (*, ?) to a RegExp. */
 export function globToRegExp(pattern) {
   const source = String(pattern)
-    .replace(/[.+^$()|[\]{}]/g, '\$&')
+    // A literal backslash must be escaped before anything else; otherwise the
+    // following replaceAll calls turn it into a regex escape instead of a
+    // filename character.
+    .replaceAll('\\', '\\\\')
+    .replace(/[.+^$()|[\]{}]/g, '\\$&')
     .replaceAll('*', '.*')
     .replaceAll('?', '.');
   return new RegExp('^' + source + '$', 'i');

package/benchmark/changed.mjs

@@ -19,9 +19,10 @@
  * consequences of a helper module being imported by feature modules — a real
  * dependency, but not the tool's IMPLEMENTATION.
  *
- * Measured, not guessed: 26 of the 57 tools call bindings from more than one
- * module. So a per-file → tool map is not a partition, it is a graph, and the
- * honest model is:
+ * Measured, not guessed: 26 of the tools call bindings from more than one
+ * module (measured when the suite covered 57; the graph property, not the
+ * count, is what matters). So a per-file → tool map is not a partition, it is
+ * a graph, and the honest model is:
  *
  *     changed file → the module(s) it belongs to
  *                  → every module that transitively depends on them

package/benchmark/profile.mjs

@@ -5,7 +5,7 @@
  *
  * ── Why a hand-built profile exists at all ──────────────────────────────────
  *
- * The model-facing way to get the 57 tools is the "Molecular Biology Lab" agent
+ * The model-facing way to get the 64 tools is the "Molecular Biology Lab" agent
  * preset, and the benchmark would obviously rather run THAT than a
  * reconstruction of it. It cannot: `dsh-headless` refuses a preset for a
  * structural reason, not a configuration one —

package/build/browser-api.mjs

@@ -5,12 +5,13 @@
  * re-exported from the SAME source files the Node plugin ships, so the browser
  * bundle can never drift from the plugin's behaviour.
  *
- * Only these modules are browser-safe (they import nothing but `./lib.mjs`,
- * which is pure computation): lib, genbank, snapgene, plasmid, msa, logo,
- * crispr, align, seqio, plot, design. The Node-only ones (view, papers,
- * records, sanger, protein is fine but unused here, index) are deliberately
- * absent — importing them would drag `node:child_process` and friends into the
- * browser bundle, which the bundler rejects loudly.
+ * Only these modules are browser-safe (they import nothing but `./lib.mjs` and
+ * `./svgio.mjs`, which are pure computation): lib, genbank, snapgene, plasmid,
+ * msa, logo, crispr, align, seqio, plot, design, protein-structure,
+ * structure-preview, structure-render. The Node-only ones (view, papers, records,
+ * sanger, index)
+ * are deliberately absent — importing them would drag `node:child_process` and
+ * friends into the browser bundle, which the bundler rejects loudly.
  */
 export {
   DNA_BASES,
@@ -53,4 +54,13 @@ export {
 export { designTaqmanProbes, evaluateProbe, probeCandidates } from '../taqman.mjs';
 export { checkMultiplex } from '../multiplex.mjs';
 export { helicalWheel, hydropathyProfile, renderHelicalWheel, renderHydropathyPlot } from '../protein-structure.mjs';
+export { STRUCTURE_EXTENSIONS, parseStructureText, structureFormatOf } from '../structure-preview.mjs';
+export {
+  DEFAULT_STRUCTURE_VIEW,
+  MAX_RENDER_ATOMS,
+  STRUCTURE_ELEMENT_COLORS,
+  STRUCTURE_REPRESENTATIONS,
+  inferStructureBonds,
+  renderStructureImage,
+} from '../structure-render.mjs';
 export { analyzeMethylation, bufferReport, planDoubleDigest } from '../methylation.mjs';

package/build/client-bundle-core.mjs

@@ -79,7 +79,10 @@ function parseModule(source, path) {
   for (const match of source.matchAll(EXPORT_LIST_RE)) {
     for (const name of parseNames(match[1], path)) exports.push({ local: name.local, source: null });
   }
-  for (const name of reexports) exports.push({ local: name.local, source: name.specifier });
+  // The imported name is what the target namespace must be read for; dropping
+  // it emitted `exports.x = require(target).undefined` for EVERY re-export,
+  // which silently broke browser-api.mjs while the format checks stayed green.
+  for (const name of reexports) exports.push({ local: name.local, imported: name.imported, source: name.specifier });
   const listCount = (source.match(EXPORT_LIST_RE) ?? []).length;
   const reexportCount = (source.match(REEXPORT_RE) ?? []).length;
   const keywordCount = (source.match(/^export\s/gm) ?? []).length;

package/build/client-bundle.mjs

@@ -40,7 +40,7 @@ const checkOnly = process.argv.slice(2).includes('--check');
 /**
  * The bundles to emit. The SAME browser half ships through two channels:
  *
- * - `dsh-molbio-tools` — the plugin package: one install gives the 57 tools
+ * - `dsh-molbio-tools` — the plugin package: one install gives the 64 tools
  *   plus the panel (its host half also registers the tools).
  * - `dsh-molbio-panel` — a panel-only package: installing it adds the tab to a
  *   profile WITHOUT dragging the tools into every session of that profile,

package/build/client-entry.mjs

@@ -53,9 +53,14 @@ import {
   parseAlignmentFile,
   parseLibrary,
   parsePlasmidFile,
+  parseStructureFile,
   plasmidSvg,
   readWorkspaceText,
   sortEntries,
+  structureImage,
+  DEFAULT_STRUCTURE_VIEW,
+  STRUCTURE_ELEMENT_COLORS,
+  STRUCTURE_REPRESENTATIONS,
 } from './panel-core.mjs';
 
 /** This implementation's identity, and the key its body/title register under. */
@@ -135,6 +140,20 @@ const styles = {
   error: { color: 'var(--dsh-danger, #c0392b)', padding: '10px 12px', whiteSpace: 'pre-wrap' },
   muted: { opacity: 0.6, padding: '10px 12px' },
   svg: { maxWidth: '100%', height: 'auto' },
+  canvas: { maxWidth: '100%', height: 'auto', display: 'block', border: '1px solid var(--dsh-border, #e3e6ea)', borderRadius: '6px', cursor: 'grab', touchAction: 'none', background: '#f7f9fb' },
+  button: (active) => ({
+    fontSize: '11px',
+    padding: '2px 8px',
+    cursor: 'pointer',
+    border: '1px solid var(--dsh-border, #e3e6ea)',
+    borderRadius: '4px',
+    background: active ? 'var(--dsh-selected, #eaf2ff)' : 'transparent',
+    fontWeight: active ? 600 : 400,
+    color: 'inherit',
+  }),
+  legend: { display: 'flex', gap: '10px', flexWrap: 'wrap', marginTop: '8px', fontSize: '11px', opacity: 0.75 },
+  legendItem: { display: 'inline-flex', alignItems: 'center', gap: '4px' },
+  legendDot: { width: '9px', height: '9px', borderRadius: '50%', display: 'inline-block' },
   table: { borderCollapse: 'collapse', marginTop: '12px', fontSize: '12px', width: '100%' },
   th: { textAlign: 'left', padding: '4px 8px', borderBottom: '1px solid var(--dsh-border, #e3e6ea)', opacity: 0.7, fontWeight: 600 },
   td: { padding: '3px 8px', borderBottom: '1px solid var(--dsh-border-soft, #f0f2f5)' },
@@ -147,7 +166,11 @@ function MolbioPanel({ sessionId, remote, useSessions }) {
   const [selected, setSelected] = useState(null);
   const [record, setRecord] = useState(null);
   const [status, setStatus] = useState({ kind: cwd === undefined ? 'waiting' : 'loading' });
+  const [view, setView] = useState({ ...DEFAULT_STRUCTURE_VIEW });
+  const [dragging, setDragging] = useState(false);
   const svgHost = useRef(null);
+  const canvasHost = useRef(null);
+  const drag = useRef(null);
 
   // Directory listing, re-read when the session's workspace root changes.
   useEffect(() => {
@@ -177,8 +200,13 @@ function MolbioPanel({ sessionId, remote, useSessions }) {
         const kind = classifyEntry(selected);
         const parsed = kind === 'plasmid'
           ? { kind, ...parsePlasmidFile(selected.name, bytes) }
-          : { kind, ...parseAlignmentFile(bytes) };
+          : kind === 'alignment'
+            ? { kind, ...parseAlignmentFile(bytes) }
+            : { kind, ...parseStructureFile(selected.name, bytes) };
         setRecord(parsed);
+        // A new structure starts from the same deterministic camera; the
+        // previous file's yaw/pitch would be meaningless on a different molecule.
+        if (parsed.kind === 'structure') setView({ ...DEFAULT_STRUCTURE_VIEW });
         setStatus({ kind: 'ready' });
       })
       .catch((error) => {
@@ -198,7 +226,7 @@ function MolbioPanel({ sessionId, remote, useSessions }) {
     const host = svgHost.current;
     if (host === null) return;
     host.replaceChildren();
-    if (record === null || status.kind !== 'ready') return;
+    if (record === null || status.kind !== 'ready' || record.kind === 'structure') return;
     // The renderer refuses what it cannot draw (renderPlasmidMap caps a map at
     // 200 features). Letting that throw out of the effect leaves the pane empty
     // with no explanation, so it becomes the pane's error state instead.
@@ -219,15 +247,90 @@ function MolbioPanel({ sessionId, remote, useSessions }) {
     host.append(document.importNode(svg, true));
   }, [record, status.kind]);
 
+  // Structures are rasterized into an RGB buffer and painted into a canvas.
+  // The renderer is deterministic and shared with the Node tests; only the
+  // canvas plumbing lives here. During a drag the frame drops to 1x
+  // supersampling and returns to 2x when the pointer is released.
+  useEffect(() => {
+    if (record === null || record.kind !== 'structure' || status.kind !== 'ready') return;
+    const canvas = canvasHost.current;
+    if (canvas === null || typeof canvas.getContext !== 'function') return;
+    const context = canvas.getContext('2d');
+    if (context === null || typeof context.createImageData !== 'function') return;
+    const width = Number.isInteger(canvas.width) ? canvas.width : 640;
+    const height = Number.isInteger(canvas.height) ? canvas.height : 480;
+    let image;
+    try {
+      image = structureImage(record, {
+        width,
+        height,
+        yaw: view.yaw,
+        pitch: view.pitch,
+        zoom: view.zoom,
+        representation: view.representation,
+        // Large assemblies stay at interaction quality even when settled;
+        // 2× sampling is reserved for the small structures it visibly helps.
+        supersample: dragging || record.atoms.length > 4000 ? 1 : 2,
+      });
+    } catch (error) {
+      setStatus({ kind: 'error', message: String(error?.message ?? error) });
+      return;
+    }
+    const imageData = context.createImageData(width, height);
+    for (let source = 0, target = 0; source < image.rgb.length; source += 3, target += 4) {
+      imageData.data[target] = image.rgb[source];
+      imageData.data[target + 1] = image.rgb[source + 1];
+      imageData.data[target + 2] = image.rgb[source + 2];
+      imageData.data[target + 3] = 255;
+    }
+    context.putImageData(imageData, 0, 0);
+  }, [record, status.kind, view, dragging]);
+
+  const startDrag = (event) => {
+    if (typeof event?.currentTarget?.setPointerCapture === 'function' && event.pointerId !== undefined) {
+      try {
+        event.currentTarget.setPointerCapture(event.pointerId);
+      } catch {
+        // A synthetic pointer without capture support is still draggable.
+      }
+    }
+    drag.current = { x: event.clientX, y: event.clientY, yaw: view.yaw, pitch: view.pitch };
+    setDragging(true);
+  };
+
+  const moveDrag = (event) => {
+    const start = drag.current;
+    if (start === null) return;
+    const yaw = start.yaw + (event.clientX - start.x) * 0.01;
+    const pitch = Math.max(-1.4, Math.min(1.4, start.pitch - (event.clientY - start.y) * 0.01));
+    setView((current) => ({ ...current, yaw, pitch }));
+  };
+
+  const endDrag = () => {
+    drag.current = null;
+    setDragging(false);
+  };
+
+  const zoomView = (event) => {
+    // preventDefault keeps the sidebar from scrolling while the wheel zooms.
+    if (typeof event.preventDefault === 'function') event.preventDefault();
+    setView((current) => ({
+      ...current,
+      zoom: Math.max(0.35, Math.min(5, current.zoom * Math.exp(-Number(event.deltaY ?? 0) * 0.001))),
+    }));
+  };
+
+  const resetView = () => setView({ ...DEFAULT_STRUCTURE_VIEW });
+
   const openable = useMemo(() => entries.filter(isOpenable), [entries]);
 
-  const head = h('div', { style: styles.listHead }, 'Sequence files');
+  const head = h('div', { style: styles.listHead }, 'Sequence & structure files');
   const list = h(
     'div',
     { style: styles.list },
     head,
     ...(openable.length === 0
-      ? [h('div', { key: 'none', style: styles.muted }, 'No .dna / .gb / .gbk / .fasta files in this workspace')]
+      ? [h('div', { key: 'none', style: styles.muted }, 'No .dna / .gb / .gbk / .fasta / .pdb / .cif / .sdf files in this workspace')]
       : openable.map((entry) => {
         const kind = classifyEntry(entry);
         return h(
@@ -282,6 +385,40 @@ function MolbioPanel({ sessionId, remote, useSessions }) {
       h('span', null, `${record.rows[0]?.length ?? 0} aligned columns`)));
     body.push(h('div', { key: 'svg', ref: svgHost, style: styles.svg }));
   }
+  if (status.kind === 'ready' && record !== null && record.kind === 'structure') {
+    body.push(h('div', { key: 'meta', style: styles.meta },
+      h('span', null, record.title === '' ? record.name : record.title),
+      h('span', null, record.format.toUpperCase()),
+      h('span', null, `${record.atoms.length} atoms`),
+      h('span', null, `${record.chain_count} chain(s)`),
+      h('span', null, `${record.residue_count} residue(s)`)));
+    body.push(h('div', { key: 'controls', style: styles.meta },
+      ...STRUCTURE_REPRESENTATIONS.map((representation) => h('button', {
+        key: representation,
+        style: styles.button(view.representation === representation),
+        onClick: () => setView((current) => ({ ...current, representation })),
+      }, representation === 'ball-and-stick' ? 'Ball & stick' : 'Space filling')),
+      h('button', { key: 'reset', style: styles.button(false), onClick: resetView }, 'Reset view')));
+    body.push(h('canvas', {
+      key: 'canvas',
+      ref: canvasHost,
+      width: 640,
+      height: 480,
+      style: styles.canvas,
+      onPointerDown: startDrag,
+      onPointerMove: moveDrag,
+      onPointerUp: endDrag,
+      onPointerCancel: endDrag,
+      onWheel: zoomView,
+      onDoubleClick: resetView,
+      'aria-label': '3D structure preview; drag to rotate, wheel to zoom',
+    }));
+    body.push(h('div', { key: 'legend', style: styles.legend },
+      ...['C', 'N', 'O', 'S', 'P'].map((element) => h('span', { key: element, style: styles.legendItem },
+        h('span', { style: { ...styles.legendDot, background: STRUCTURE_ELEMENT_COLORS[element] } }),
+        element))));
+    body.push(h('div', { key: 'note', style: styles.note }, 'Software-rendered 3D model. Drag to rotate, wheel to zoom. Ball-and-stick / space-filling; not for measurements.'));
+  }
 
   return h('div', { style: styles.root }, list, h('div', { style: styles.main }, ...body));
 }

package/build/panel-core.mjs

@@ -18,6 +18,12 @@ import {
   columnComposition,
   renderSequenceLogo,
   progressiveAlign,
+  parseStructureText,
+  renderStructureImage,
+  DEFAULT_STRUCTURE_VIEW,
+  STRUCTURE_ELEMENT_COLORS,
+  STRUCTURE_EXTENSIONS,
+  STRUCTURE_REPRESENTATIONS,
 } from './browser-api.mjs';
 
 /** Extensions the panel can open, mapped to the parser that handles them. */
@@ -36,6 +42,9 @@ export const ALIGNMENT_EXTENSIONS = {
   fas: 'fasta',
 };
 
+/** Structure formats the panel opens, mapped to the parser kind. */
+export { DEFAULT_STRUCTURE_VIEW, STRUCTURE_ELEMENT_COLORS, STRUCTURE_EXTENSIONS, STRUCTURE_REPRESENTATIONS };
+
 /** Lowercase extension without the dot, or '' when there is none. */
 export function extensionOf(name) {
   const match = /\.([A-Za-z0-9]+)$/.exec(String(name));
@@ -45,7 +54,7 @@ export function extensionOf(name) {
 /**
  * How the panel should treat one workspace entry.
  * @param {{name?: string, type?: string}} entry a `workspaceFiles.list` row.
- * @returns {'plasmid'|'alignment'|'other'|'directory'}
+ * @returns {'plasmid'|'alignment'|'structure'|'other'|'directory'}
  */
 export function classifyEntry(entry) {
   if (entry === null || typeof entry !== 'object') return 'other';
@@ -54,18 +63,19 @@ export function classifyEntry(entry) {
   const extension = extensionOf(entry.name ?? '');
   if (PLASMID_EXTENSIONS[extension] !== undefined) return 'plasmid';
   if (ALIGNMENT_EXTENSIONS[extension] !== undefined) return 'alignment';
+  if (STRUCTURE_EXTENSIONS[extension] !== undefined) return 'structure';
   return 'other';
 }
 
 /** Whether the panel can open this entry at all. */
 export function isOpenable(entry) {
   const kind = classifyEntry(entry);
-  return kind === 'plasmid' || kind === 'alignment';
+  return kind === 'plasmid' || kind === 'alignment' || kind === 'structure';
 }
 
-/** Sort entries: plasmid files first, then alignments, then the rest, by name. */
+/** Sort entries: plasmid files first, then alignments, structures, the rest. */
 export function sortEntries(entries) {
-  const rank = { plasmid: 0, alignment: 1, other: 2, directory: 3 };
+  const rank = { plasmid: 0, alignment: 1, structure: 2, other: 3, directory: 4 };
   return [...entries].sort((left, right) => {
     const byKind = rank[classifyEntry(left)] - rank[classifyEntry(right)];
     if (byKind !== 0) return byKind;
@@ -164,6 +174,44 @@ export function plasmidSvg(record, options = {}) {
   });
 }
 
+/**
+ * Parse a structure file into the record the panel draws.
+ *
+ * The size guard is the same browser-specific cap as {@link parsePlasmidFile}:
+ * parsing runs on the UI thread, so a 200 MB PDB must be refused with a message
+ * rather than freeze the tab. The format comes from the extension, exactly as
+ * the Node tools choose their parser.
+ * @param {string} name file name.
+ * @param {Uint8Array} bytes raw file content.
+ * @returns {object} a parseStructureText record.
+ */
+export function parseStructureFile(name, bytes) {
+  if (!(bytes instanceof Uint8Array)) throw new MolbioInputError('file content must be a Uint8Array');
+  const extension = extensionOf(name);
+  const format = STRUCTURE_EXTENSIONS[extension];
+  if (format === undefined) {
+    throw new MolbioInputError(`the panel does not open .${extension} structure files; use .pdb, .ent, .cif, .mmcif, .sdf or .mol`);
+  }
+  if (bytes.length > MAX_PANEL_FILE_BYTES) {
+    throw new MolbioInputError(
+      `${name} is ${(bytes.length / 1024 / 1024).toFixed(1)} MB; the panel opens structure files up to ${MAX_PANEL_FILE_BYTES / 1024 / 1024} MB`,
+    );
+  }
+  return parseStructureText(format, new TextDecoder('utf-8').decode(bytes), name);
+}
+
+/**
+ * Render a parsed structure to an RGB buffer for the canvas.
+ * @param {object} record a {@link parseStructureFile} result.
+ * @param {{width?: number, height?: number, yaw?: number, pitch?: number,
+ *   zoom?: number, representation?: string, supersample?: 1|2}} [options]
+ * @returns {{width:number, height:number, rgb:Uint8Array, atoms:number,
+ *   bonds:number, representation:string}}
+ */
+export function structureImage(record, options = {}) {
+  return renderStructureImage(record, options);
+}
+
 /**
  * Parse an alignment file (FASTA) into the rows the logo needs.
  * @param {Uint8Array} bytes raw FASTA content.

package/build/preset-patch.mjs

@@ -101,7 +101,7 @@ const ANCHOR = [
   '#',
   '# Keep the tool in the PRESET and only the anchor here. An earlier version of',
   "# this file inserted a host row for the tool itself (`name: dsh-molbio-tools`),",
-  "# which both registered all 60 tools globally and collided with the preset's own",
+  "# which both registered every tool globally and collided with the preset's own",
   '# copy of that row:',
   '#',
   '#     broken: "tool-molbio (...): never started"',

package/build/release-preflight.mjs

@@ -41,7 +41,7 @@ import { gunzipSync } from 'node:zlib';
  * The two npm entries this repository publishes, in publish order.
  *
  * THEY DO NOT SHARE A VERSION LINE, and that is deliberate rather than an
- * oversight to be "fixed" here. The root package carries the 62 tools and moves
+ * oversight to be "fixed" here. The root package carries the 64 tools and moves
  * with every toolset release; `dsh-molbio-panel` carries only the browser panel
  * and moves when the panel's own artifact moves. The tag names the ROOT version
  * (`v0.19.0`), and each entry is checked against its own declared version —