dsh-molbio-tools 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -10,6 +10,67 @@
   改为按**包名**引用后模块缓存问题随之消失——没有拷贝，也就没有需要保持同步的版本目录。
   下文历史条目里出现的 `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 覆盖。** 这一版只修“已经在产品里、

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/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-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/docs/client-panel.md

@@ -10,14 +10,14 @@
 
 | 落点 | 内容 | 数据来源 |
 | --- | --- | --- |
-| **Molbio**（右栏 tab） | 列出会话工作区里的序列文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图 | `workspaceFiles.readAll`（二进制，含 SnapGene） |
+| **Molbio**（右栏 tab） | 列出会话工作区里的序列与结构文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图；`.pdb`/`.ent`/`.cif`/`.mmcif`/`.sdf`/`.mol` → 可旋转的 3D ball-and-stick / space-filling 模型 | `workspaceFiles.readAll` / `readBytes`（二进制，含 SnapGene 与结构文件） |
 | **Papers**（右栏 tab） | 把 `molbio_paper_*` 工具维护的 `papers.json` 渲染成可搜索的阅读列表 + 详情面板（标题/作者/期刊/年份/PMID/URL/标签/笔记，标题链接到 PubMed 或原 URL） | `workspaceFiles.read`（文本） |
 | **图谱调用卡**（`tool.call.toolview`） | `molbio_plasmid_map` / `molbio_plasmid_map_file` 的调用卡：在对话里直接画出这次调用产出的图谱（摘要行 + 写入路径），失败时显示错误文本与 Inspect 入口 | 工具自己声明的 `output.presentationMeta`（见下） |
 | **图形调用卡**（`tool.call.toolview`） | `molbio_sequence_logo` / `molbio_grna_design` 的调用卡：logo 直接画图；gRNA 画 `map_path` 并列出前 5 条 guide（无 map 时仍有摘要与表格） | 同上，kind = `molbio-figure` |
 | **PubMed API key**（`plugins.detail.section`） | 插件 → 已安装插件 → `dsh-molbio-tools` 详情页里的一段表单：password 输入 + Save/Remove，状态只报「已配置 / 来源 / 未配置」，永不回显值 | `ctx.remote.credentials.describe` / `set` / `unset`（host 的凭据 seam） |
 
-**解析与渲染全部在浏览器里跑本仓库自己的模块**（`lib/genbank/snapgene/plasmid/msa/logo`），
-不经过任何工具调用、不落盘 SVG、不弹系统查看器。
+**解析与渲染全部在浏览器里跑本仓库自己的模块**（`lib/genbank/snapgene/plasmid/msa/logo`
+与 `structure-preview` / `structure-render`），不经过任何工具调用、不落盘 SVG、不弹系统查看器。
 
 ### 调用卡的数据通路（`presentationMeta`）
 
@@ -174,8 +174,9 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
    生效、以及坏库时列表仍宣称"还没有文献"。插件详情页的 key 段也被真实驱动：
    `describe` → 输入 → Save（trim 后写入 `NCBI_API_KEY`）→ 状态刷新 + 清空输入 → Remove →
    provider 拒绝时消息原样显示。
-4. **数据通路（质粒）**：真实 pUC118 `.dna` → 记录（名称/长度/拓扑/特征，AmpR 2102-2962
-   反链）→ SVG；GenBank 文本路径与 Node 工具解析结果**逐字段一致**；FASTA → 比对 → logo；
+4. **数据通路（质粒 / 比对 / 结构）**：真实 pUC118 `.dna` → 记录（名称/长度/拓扑/特征，
+   AmpR 2102-2962 反链）→ SVG；GenBank 文本路径与 Node 工具解析结果**逐字段一致**；
+   FASTA → 比对 → logo；PDB → 3D 模型（点选后 canvas 被绘制，拖拽触发重绘）；
    扩展名分类、排序、base64 解码、非法输入的错误路径。
 5. **数据通路（文献库）**：`readWorkspaceText` 的三种结果（有文本 / 文件不存在 / 读取失败）
    分别对应"有库 / 空库 / 报错"；`parseLibrary` 与工具侧契约一致（`{papers: [...]}`）且
@@ -256,6 +257,11 @@ shadow（无冲突），面板的 `remote`/`slot` 服务不受影响。
   后续可考虑把同样的卡片给 `molbio_dotplot` 等新画图工具。**任何新卡片上线前先跑
   `test/client.mjs` 的抢座位顺序那一层**：0.7.1 的卡片因为裸 `register()` 抢座位而让 GUI
   起不来（0.7.2 修复，见 §4 第一条）；`contract` 会从产物里的 key 表反推投影数。
+- **结构预览**：✅ 已落地（0.25.0）。Molbio tab 直接读 PDB/mmCIF/SDF-MOL V2000，
+  用 canvas 画可旋转的 3D **ball-and-stick / space-filling** 模型（软件光栅化 + z-buffer +
+  Phong 光照）；明确的边界是 12,000 重原子、5 MB、无 V3000、无分子表面/静电势、
+  “preview, not for measurements”。没有走 `ctx.documentPreviews`：现有 tab 已有文件列表、
+  canvas 与错误态，新增 keyed 容器换不来新的用户能力。
 - **文献库写回**（可选）：若要面板内编辑笔记/标签，需要先定义与 `molbio_paper_*` 工具
   一致的并发契约（乐观版本号或串行化队列），或让工具走同一条 RPC。
 - **上游提案（路径 B）**：preset 渠道挂 client 仍是真实生态需求，可以在社区反馈时

package/docs/history.md

@@ -16,6 +16,7 @@
 
 | 包版本 | preset 版本 | 内容 | 工具数 |
 | --- | --- | --- | --- |
+| 0.25.0 | — | **浏览器内真实 3D 结构预览**：Molbio 面板读 PDB/mmCIF/SDF-MOL V2000，软件光栅化 ball-and-stick / space-filling，拖拽旋转、滚轮缩放；工具数不变 | 64 |
 | 0.24.1 | — | **输入边界与数据安全加固**：BibTeX 不再覆盖文献库、相对读取按会话工作区、批量/glob/并发声明修复、20 万行输入不再 `RangeError`；工具数不变 | 64 |
 | 0.24.0 | — | **数据卫生版**：新增 `molbio_contamination_screen`（内置载体/接头短签名，双链、0–2 错配）与 `molbio_fastq_trim`（质量/接头/引物/poly/N/长度，写 FASTQ/FASTA）；修 FASTQ QC 接头表 Small RNA 5' 的 RNA→DNA 静默错 | 62 → 64 |
 | 0.23.0 | — | **2.0 遗留修复 + 2.9a 调用卡 + 两个候选池工具**：跨内含子引物报告真实反向分子（F 在 R 上游）、logo/gRNA 调用卡、`molbio_protein_charge`、`molbio_dotplot`；同版完成 **DSH 0.2.2-rc.1 适配**（删掉上游已移除的 `list-agents` 子路径行、subagent 模型选择改用新键、守卫补上 specifier 解析） | 60 → 62 |
@@ -50,6 +51,35 @@
 
 ---
 
+## v0.25.0（2026-11-10，包 0.25.0）
+
+**三条教训，关于“看得见”“同一份源码”和“产物真的能跑”。**
+
+**(1) 2D PCA 不是文献里的结构图。** 第一版把 3D 坐标投到两个主轴，画一张静态 SVG；
+它保留了相对位置，却丢掉深度、遮挡和空间关系，蛋白质像线稿、核酸像折线。学术界常见的
+配图是立体的 ball-and-stick、space-filling 或 surface，而不是单张投影。0.25.0 在发布前
+改为**真实原子模型**：透视、z-buffer、Phong 光照、深度雾化；球和键按元素着色，支持
+ball-and-stick 与 space-filling 两种表示。没有采用卡通 ribbon：它需要二级结构、朝向和
+带宽的额外几何，且不是这一版要解决的问题。
+
+**(2) 软件光栅化让“浏览器里看到的”和“测试里验证的”是同一套像素。** 不引入 WebGL 或
+Three.js；`structure-render.mjs` 返回 RGB 缓冲，面板只把它 `putImageData` 到 canvas。
+Node 测试能直接检查中心原子、非背景像素、两种表示和 PNG 编码；否则 canvas 行为只能靠
+肉眼或第二个渲染器验证，二者必分叉。代价是 CPU 渲染：拖动时 1× 采样，松开后 2×，
+12,000 个重原子封顶。
+
+**(3) 产物能生成，不等于产物能运行。** 加结构预览时发现 bundler 在生成 re-export 时
+丢掉了 imported name，所有 `browser-api.mjs` 再导出在产物里都是
+`require(target).undefined`；格式/模块存在性检查全绿，但真实浏览器半拿到 undefined。
+现在保留 imported name，并在 `test/client.mjs` 加一条“产物不得含
+`require(...).undefined`”的结构断言。这也是为什么“同一份源码”必须配合**执行**产物的
+守卫，而不只是文本对比。
+
+**顺带记录**：只改浏览器半也会改变根包产物，所以根包 `0.24.1 → 0.25.0`、面板包
+`0.1.10 → 0.1.11` 同时升版本。工具数保持 64，benchmark 保持 65 题。结构解析与渲染在
+`structure-preview.mjs` / `structure-render.mjs`，面板用 canvas 承载，不再使用
+`ctx.documentPreviews`（现有 tab 已有文件列表、错误态与画布）。
+
 ## v0.24.1（2026-11-08，包 0.24.1）
 
 **三条教训，都是“合法输入 + 默认路径”才会暴露的错。**

package/docs/maintainer.md

@@ -32,7 +32,7 @@
 
 - **包**：`dsh-molbio-tools`，零依赖 DSH 插件包，**64 个 `molbio_*` 工具**（其中
   `molbio_plot` 一个工具承载 8 种图表）。
-- **基线**：DSH **0.2.2-rc.1**；`package.json` 版本 0.24.1（DSH 桌面版内嵌 Node 24.21.0）。
+- **基线**：DSH **0.2.2-rc.1**；`package.json` 版本 0.25.0（DSH 桌面版内嵌 Node 24.21.0）。
 - **两条分发渠道**：根包（工具 + 面板）与 `packages/molbio-panel`（只面板），
   **两个独立的 npm 条目、两条独立的版本线**，必须分别发布。
 - **工具只在专属模式里出现**（设计如此）：bundle 的 `cordis.patch.yml` 只插一行**惰性宿主锚点**

package/docs/roadmap.md

@@ -10,7 +10,7 @@ L = 需要新机制或外部资源）。
 
 ---
 
-## 1. 当前状态（0.24.1）
+## 1. 当前状态（0.25.0）
 
 - 64 个 `molbio_*` 工具，零依赖，随 preset 分发（见 [README](../README.md)）。
 - 离线测试金字塔 + 组合漂移守卫全绿；`benchmark/` 提供**模型使用**维度的评估
@@ -45,6 +45,11 @@ L = 需要新机制或外部资源）。
   的 key 解析顺序变为 **`api_key` 参数 → DSH 凭据库 → 环境变量**（环境变量会被 agent 自己的 shell
   子进程继承，凭据库不会）；同时插件详情页出现 **PubMed API key** 表单，用户不必改 YAML。
   没有凭据库的组合行为与 0.22.0 相同。
+- **0.25.0 交付 2.9c 真实 3D 结构预览（工具数不变）**：Molbio 面板新增 PDB/mmCIF/SDF-MOL
+  V2000 的 **ball-and-stick / space-filling** 软件光栅化（透视、z-buffer、Phong 光照、
+  深度雾化、CPK 配色），支持拖拽旋转、滚轮缩放与表示切换；12,000 重原子封顶，
+  明确拒绝 V3000，并标注"preview, not for measurements"。根包 `0.24.1 → 0.25.0`、
+  面板包 `0.1.10 → 0.1.11`。同版修掉客户端 bundler 丢掉 re-export imported name 的缺陷。
 - **0.24.1 是输入边界与数据安全加固版（工具数不变）**：修掉 BibTeX 导出覆盖文献库、
   相对路径按 provider cwd 解析、四个默认写 SVG 的工具被误标并发安全、批量 glob /
   `max_files` / 坏路径、文献与协议库坏条目，以及 20 万行表格 / 13 万条 reads 触发的
@@ -170,9 +175,10 @@ v16 的 CRISPR 已有订购 CSV 先例，可直接复用格式。
   （`molbio-figure` 投影 + `FIGURE_TOOL_KEYS`；logo 画图，gRNA 画图谱并列出前 5 条 guide）。
   `test/map-card.mjs` 现在同时跑两种卡片，`contract` 从产物里的两张 key 表反推投影数。
 - 文献库**写回**需先定并发契约（当前只读）；
-- 结构文件的浏览器内预览（`.pdb/.cif/.sdf/.mol`）：`ctx.documentPreviews.register` +
-  keyed 座位是**容器**，不是现成的 3D 查看器——要么只做 2D 投影（Cα 轨迹/二级结构条带），
-  要么单独估工。
+- ✅ **已做（0.25.0）**：结构文件的浏览器内预览（`.pdb/.ent/.cif/.mmcif/.sdf/.mol`）
+  接在现有 Molbio tab 里，做**真实 3D 原子模型**（ball-and-stick / space-filling，
+  透视 + z-buffer + Phong 光照）；拖拽旋转、滚轮缩放。没有走 `ctx.documentPreviews`，
+  也没有做卡通 ribbon、分子表面或静电势。边界与测试见 [history.md](history.md) 的 v0.25.0 段。
 
 ### 2.10 ✅ 图表八种全部落地（0.17.0 第一批 3 种，0.18.0 第二批 3 种 + 色带）