dsh-molbio-panel 0.1.10 → 0.1.11

package/README.md

@@ -1,10 +1,14 @@
 # dsh-molbio-panel
 
-DSH Web GUI 的**浏览器内 Molbio 面板**：右侧栏的一个 tab，列出当前会话工作区的序列文件，
-选中当场画出来——`.dna` / `.gb` / `.gbk` 出质粒图谱，`.fa` / `.fasta` 出序列标识图。
+DSH Web GUI 的**浏览器内 Molbio 面板**：右侧栏的一个 tab，列出当前会话工作区的序列与结构文件，
+选中当场画出来——`.dna` / `.gb` / `.gbk` 出质粒图谱，`.fa` / `.fasta` 出序列标识图，
+`.pdb` / `.ent` / `.cif` / `.mmcif` / `.sdf` / `.mol` 出可旋转的 3D
+ball-and-stick / space-filling 原子模型。
 
 解析与渲染在浏览器里跑的是 [`dsh-molbio-tools`](https://github.com/lovy2004/dsh-molbio-tools)
-的**同一份源码**（`lib/genbank/snapgene/plasmid/msa/logo`）——不落盘 SVG、不弹系统查看器、
+的**同一份源码**（`lib/genbank/snapgene/plasmid/msa/logo` 与 `structure-preview` /
+`structure-render`）——
+不落盘 SVG、不弹系统查看器、
 不经过工具调用。
 
 ## 为什么是单独的包
@@ -37,7 +41,10 @@ dsh plugin --profile <profile> add D:\path\to\packages\molbio-panel   # 本地
 1. 打开右侧栏（会话头部角落的按钮），从引导页选 **Molbio**。
 2. 左栏列出工作区里可打开的文件（质粒文件排在前面）。
 3. 点一个 `.dna` / `.gb` → 右侧出图谱 + 特征表（Feature / Type / Start / End / Strand）；
-   点一个 `.fasta`（≥2 条序列）→ 出序列标识图（信息量 bits，小样本校正默认开）。
+   点一个 `.fasta`（≥2 条序列）→ 出序列标识图（信息量 bits，小样本校正默认开）；
+   点一个 `.pdb` / `.cif` / `.sdf` / `.mol` → 出可旋转的 3D 模型（ball-and-stick 或
+   space-filling；拖拽旋转、滚轮缩放、双击复位）。它是真实原子模型的预览，
+   不含分子表面/静电势，也不做测量；V3000 不支持。
 
 ## 限制
 

package/lib/client.js

@@ -7908,6 +7908,825 @@ window.__ModuleLoader__.load({
 			exports.renderHydropathyPlot = renderHydropathyPlot;
 			return exports;
 		};
+		__molbio_modules["structure-preview.mjs"] = () => {
+			const exports = {};
+			/**
+			 * dsh-molbio-tools/structure-preview.mjs
+			 *
+			 * Pure parsing for structure files shown in the browser panel: PDB, mmCIF and
+			 * MDL SDF/MOL V2000. Rendering lives in structure-render.mjs, which turns this
+			 * record into a realistic ball-and-stick or space-filling RGB frame.
+			 *
+			 * WHAT THIS IS
+			 * ------------
+			 * A compact, dependency-free reader for the coordinates, elements, chains and
+			 * bonds a preview needs. It does not interpret secondary structure, surfaces,
+			 * symmetry or multiple models; a failed/unsupported file throws a
+			 * MolbioInputError naming the file kind, and the panel turns that into a notice.
+			 *
+			 * The module is browser-safe on purpose: it imports only MolbioInputError from
+			 * lib.mjs. It must not import node:fs, node:path or node:zlib.
+			 */
+			const { MolbioInputError } = __molbio_require("lib.mjs");
+			/** Extension to parser kind. The keys are lowercase. */
+			const STRUCTURE_EXTENSIONS = {
+			  pdb: 'pdb',
+			  ent: 'pdb',
+			  cif: 'mmcif',
+			  mmcif: 'mmcif',
+			  sdf: 'sdf',
+			  mol: 'sdf',
+			};
+
+			/** Upper bound on atoms read from one file. */
+			const MAX_STRUCTURE_ATOMS = 20000;
+
+			/** Upper bound on bonds read from one file. */
+			const MAX_STRUCTURE_BONDS = 40000;
+
+			/** The format label for a filename, or undefined when it is not a structure. */
+			function structureFormatOf(name) {
+			  const match = /\.([A-Za-z0-9]+)$/.exec(String(name));
+			  if (match === null) return undefined;
+			  return STRUCTURE_EXTENSIONS[match[1].toLowerCase()];
+			}
+
+			/**
+			 * Parse one structure file.
+			 * @param {string} format 'pdb' | 'mmcif' | 'sdf'
+			 * @param {string} text file content (UTF-8 decoded).
+			 * @param {string} [name] display name, used for the title fallback.
+			 * @returns {object} the parsed record consumed by structure-render.mjs.
+			 */
+			function parseStructureText(format, text, name = 'structure') {
+			  const kind = String(format).toLowerCase();
+			  if (kind === 'pdb') return withSummary(parsePdb(text, name));
+			  if (kind === 'mmcif') return withSummary(parseMmcif(text, name));
+			  if (kind === 'sdf') return withSummary(parseSdf(text, name));
+			  throw new MolbioInputError('the structure parser accepts pdb, mmcif or sdf/mol files');
+			}
+
+			// ── shared atom helpers ─────────────────────────────────────────────────────
+
+			const ELEMENTS = new Set(['H', 'C', 'N', 'O', 'S', 'P', 'F', 'CL', 'BR', 'I', 'B', 'SI', 'SE', 'FE', 'ZN', 'MG', 'CA', 'NA', 'K']);
+
+			/** Element symbol from an atom name, when the file does not carry one. */
+			function guessElement(atomName) {
+			  const cleaned = String(atomName ?? '').toUpperCase().replace(/[^A-Z]/g, '');
+			  if (cleaned === '') return 'C';
+			  const two = cleaned.slice(0, 2);
+			  if (ELEMENTS.has(two)) return two;
+			  return cleaned.slice(0, 1);
+			}
+
+			/** Element symbol, normalised to upper case and at most two characters. */
+			function normalizeElement(value, fallbackName) {
+			  const element = String(value ?? '').trim().toUpperCase();
+			  if (element !== '' && element !== '?' && element !== '.') return element.slice(0, 2);
+			  return guessElement(fallbackName);
+			}
+
+			/** One atom record; all coordinates are finite numbers. */
+			function atomRecord({ serial, name, element, residue, chain, residueNumber, x, y, z, hetatm }) {
+			  return {
+			    serial,
+			    name: String(name ?? '').trim(),
+			    element: normalizeElement(element, name),
+			    residue: String(residue ?? '').trim(),
+			    chain: String(chain ?? '').trim(),
+			    residue_number: String(residueNumber ?? '').trim(),
+			    x,
+			    y,
+			    z,
+			    hetatm: hetatm === true,
+			  };
+			}
+
+			/** Reject a file that produced no usable coordinates. */
+			function requireAtoms(atoms, format) {
+			  if (atoms.length === 0) {
+			    throw new MolbioInputError(`the ${format} file contains no usable atom coordinates`);
+			  }
+			  if (atoms.length > MAX_STRUCTURE_ATOMS) {
+			    throw new MolbioInputError(`the file has ${atoms.length} atoms; the panel reads at most ${MAX_STRUCTURE_ATOMS}`);
+			  }
+			}
+
+			/** Attach the derived facts the panel shows, without copying the arrays. */
+			function withSummary(record) {
+			  const chains = [...new Set(record.atoms.map((atom) => atom.chain).filter((chain) => chain !== ''))];
+			  const residues = new Set(record.atoms.map((atom) => `${atom.chain}:${atom.residue_number}:${atom.residue}`));
+			  return {
+			    ...record,
+			    chains,
+			    chain_count: chains.length,
+			    residue_count: residues.size,
+			    hetatm_count: record.atoms.filter((atom) => atom.hetatm).length,
+			  };
+			}
+
+			// ── PDB ─────────────────────────────────────────────────────────────────────
+
+			/** Parse PDB ATOM/HETATM records from the first model. */
+			function parsePdb(text, name = 'structure') {
+			  const atoms = [];
+			  const serials = new Map();
+			  const conect = [];
+			  const titleParts = [];
+			  let model = 0;
+			  let sawModel = false;
+
+			  for (const rawLine of String(text).split(/\r?\n/)) {
+			    const lineText = rawLine.padEnd(80, ' ');
+			    const recordName = lineText.slice(0, 6).trim().toUpperCase();
+			    if (recordName === 'TITLE') {
+			      titleParts.push(lineText.slice(10).trim());
+			      continue;
+			    }
+			    if (recordName === 'MODEL') {
+			      sawModel = true;
+			      model += 1;
+			      continue;
+			    }
+			    if (recordName === 'ENDMDL') {
+			      if (atoms.length > 0) break;
+			      continue;
+			    }
+			    if (recordName !== 'ATOM' && recordName !== 'HETATM') {
+			      if (recordName === 'CONECT') {
+			        const numbers = lineText.slice(6).trim().split(/\s+/).map((value) => Number(value)).filter((value) => Number.isInteger(value));
+			        if (numbers.length > 1) conect.push(numbers);
+			      }
+			      continue;
+			    }
+			    if (sawModel && model > 1) continue;
+			    const altLocation = lineText.slice(16, 17);
+			    if (altLocation !== ' ' && altLocation !== 'A') continue;
+			    const x = Number(lineText.slice(30, 38));
+			    const y = Number(lineText.slice(38, 46));
+			    const z = Number(lineText.slice(46, 54));
+			    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) continue;
+			    const serial = Number(lineText.slice(6, 11).trim());
+			    const atom = atomRecord({
+			      serial: Number.isInteger(serial) ? serial : atoms.length + 1,
+			      name: lineText.slice(12, 16),
+			      element: lineText.slice(76, 78),
+			      residue: lineText.slice(17, 20),
+			      chain: lineText.slice(21, 22),
+			      residueNumber: lineText.slice(22, 26),
+			      x,
+			      y,
+			      z,
+			      hetatm: recordName === 'HETATM',
+			    });
+			    if (Number.isInteger(atom.serial)) serials.set(atom.serial, atoms.length);
+			    atoms.push(atom);
+			  }
+
+			  requireAtoms(atoms, 'PDB');
+			  const bonds = [];
+			  for (const numbers of conect) {
+			    const from = serials.get(numbers[0]);
+			    if (from === undefined) continue;
+			    for (const target of numbers.slice(1)) {
+			      const to = serials.get(target);
+			      if (to !== undefined) bonds.push({ a: from, b: to, order: 1 });
+			    }
+			  }
+			  return {
+			    kind: 'structure',
+			    format: 'pdb',
+			    name,
+			    title: titleParts.join(' ').replace(/\s+/g, ' ').trim(),
+			    atoms,
+			    bonds: bonds.slice(0, MAX_STRUCTURE_BONDS),
+			  };
+			}
+
+			// ── mmCIF ───────────────────────────────────────────────────────────────────
+
+			/** Split a CIF document into tokens, honouring quotes and ; text blocks. */
+			function cifTokens(text) {
+			  const tokens = [];
+			  const lines = String(text).split(/\r?\n/);
+			  let index = 0;
+			  while (index < lines.length) {
+			    const lineText = lines[index];
+			    if (lineText.startsWith(';')) {
+			      const parts = [];
+			      index += 1;
+			      while (index < lines.length && !lines[index].startsWith(';')) {
+			        parts.push(lines[index]);
+			        index += 1;
+			      }
+			      index += 1;
+			      tokens.push(parts.join('\n'));
+			      continue;
+			    }
+			    let position = 0;
+			    while (position < lineText.length) {
+			      while (position < lineText.length && /\s/.test(lineText[position])) position += 1;
+			      if (position >= lineText.length) break;
+			      if (lineText[position] === '#') break;
+			      const quote = lineText[position];
+			      if (quote === "'" || quote === '"') {
+			        position += 1;
+			        const start = position;
+			        while (position < lineText.length && lineText[position] !== quote) position += 1;
+			        tokens.push(lineText.slice(start, position));
+			        if (position < lineText.length) position += 1;
+			        continue;
+			      }
+			      const start = position;
+			      while (position < lineText.length && !/\s/.test(lineText[position])) position += 1;
+			      tokens.push(lineText.slice(start, position));
+			    }
+			    index += 1;
+			  }
+			  return tokens;
+			}
+
+			/** Index of the first tag matching one of the candidate names. */
+			function firstTagIndex(tags, candidates) {
+			  for (const candidate of candidates) {
+			    const index = tags.indexOf(candidate);
+			    if (index !== -1) return index;
+			  }
+			  return -1;
+			}
+
+			/** Parse the _atom_site loop of an mmCIF document. */
+			function parseMmcif(text, name = 'structure') {
+			  const tokens = cifTokens(text);
+			  let atoms = [];
+			  for (let index = 0; index < tokens.length; index++) {
+			    if (tokens[index].toLowerCase() !== 'loop_') continue;
+			    const tags = [];
+			    let cursor = index + 1;
+			    while (cursor < tokens.length && tokens[cursor].startsWith('_')) {
+			      tags.push(tokens[cursor]);
+			      cursor += 1;
+			    }
+			    if (!tags.some((tag) => tag.startsWith('_atom_site.'))) {
+			      index = cursor - 1;
+			      continue;
+			    }
+			    const values = [];
+			    while (cursor < tokens.length) {
+			      const token = tokens[cursor];
+			      if (token.startsWith('_') || token.toLowerCase() === 'loop_' || token.toLowerCase() === 'stop_' || token.toLowerCase().startsWith('data_')) break;
+			      values.push(token);
+			      cursor += 1;
+			    }
+			    const rowWidth = tags.length;
+			    if (rowWidth === 0) continue;
+			    const column = (candidates) => firstTagIndex(tags, candidates);
+			    const groupColumn = column(['_atom_site.group_PDB']);
+			    const atomColumn = column(['_atom_site.label_atom_id', '_atom_site.auth_atom_id']);
+			    const residueColumn = column(['_atom_site.label_comp_id', '_atom_site.auth_comp_id']);
+			    const chainColumn = column(['_atom_site.auth_asym_id', '_atom_site.label_asym_id']);
+			    const residueNumberColumn = column(['_atom_site.auth_seq_id', '_atom_site.label_seq_id']);
+			    const xColumn = column(['_atom_site.Cartn_x']);
+			    const yColumn = column(['_atom_site.Cartn_y']);
+			    const zColumn = column(['_atom_site.Cartn_z']);
+			    const elementColumn = column(['_atom_site.type_symbol']);
+			    const modelColumn = column(['_atom_site.pdbx_PDB_model_num']);
+			    const altColumn = column(['_atom_site.label_alt_id']);
+			    if (xColumn === -1 || yColumn === -1 || zColumn === -1) continue;
+			    const rows = [];
+			    for (let start = 0; start + rowWidth <= values.length; start += rowWidth) {
+			      rows.push(values.slice(start, start + rowWidth));
+			    }
+			    let firstModel;
+			    const parsed = [];
+			    for (const row of rows) {
+			      const cell = (position) => (position === -1 ? '' : row[position]);
+			      const modelValue = cell(modelColumn);
+			      if (firstModel === undefined && modelValue !== '' && modelValue !== '.' && modelValue !== '?') firstModel = modelValue;
+			      if (firstModel !== undefined && modelValue !== '' && modelValue !== '.' && modelValue !== '?' && modelValue !== firstModel) continue;
+			      const alt = cell(altColumn);
+			      if (alt !== '' && alt !== '.' && alt !== '?' && alt !== 'A') continue;
+			      const x = Number(cell(xColumn));
+			      const y = Number(cell(yColumn));
+			      const z = Number(cell(zColumn));
+			      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) continue;
+			      const group = cell(groupColumn).toUpperCase();
+			      parsed.push(atomRecord({
+			        serial: parsed.length + 1,
+			        name: cell(atomColumn),
+			        element: cell(elementColumn),
+			        residue: cell(residueColumn),
+			        chain: cell(chainColumn),
+			        residueNumber: cell(residueNumberColumn),
+			        x,
+			        y,
+			        z,
+			        hetatm: group === 'HETATM',
+			      }));
+			    }
+			    atoms = parsed;
+			    break;
+			  }
+
+			  requireAtoms(atoms, 'mmCIF');
+			  return {
+			    kind: 'structure',
+			    format: 'mmcif',
+			    name,
+			    title: '',
+			    atoms,
+			    bonds: [],
+			  };
+			}
+
+			// ── SDF / MOL V2000 ─────────────────────────────────────────────────────────
+
+			/** Parse the first molecule of an SDF/MOL V2000 file. */
+			function parseSdf(text, name = 'structure') {
+			  // The first record ends at $$$$; later records are deliberately ignored.
+			  const first = String(text).split(/^\$\$\$\$/m)[0];
+			  const lines = first.split(/\r?\n/);
+			  const title = (lines[0] ?? '').trim();
+			  let countsIndex = -1;
+			  for (let index = 0; index < Math.min(lines.length, 8); index++) {
+			    if (/V2000|V3000/.test(lines[index])) {
+			      countsIndex = index;
+			      break;
+			    }
+			  }
+			  if (countsIndex === -1) throw new MolbioInputError('the SDF/MOL file has no V2000 counts line');
+			  if (/V3000/.test(lines[countsIndex])) {
+			    throw new MolbioInputError('MDL V3000 is not supported; export the molecule as V2000 SDF or MOL');
+			  }
+			  const counts = lines[countsIndex] ?? '';
+			  const atomCount = Number.parseInt(counts.slice(0, 3), 10);
+			  const bondCount = Number.parseInt(counts.slice(3, 6), 10);
+			  if (!Number.isInteger(atomCount) || atomCount <= 0) throw new MolbioInputError('the SDF/MOL counts line declares no atoms');
+			  if (atomCount > MAX_STRUCTURE_ATOMS) throw new MolbioInputError(`the file has ${atomCount} atoms; the panel reads at most ${MAX_STRUCTURE_ATOMS}`);
+			  const atoms = [];
+			  for (let offset = 0; offset < atomCount; offset++) {
+			    const lineText = lines[countsIndex + 1 + offset] ?? '';
+			    const x = Number(lineText.slice(0, 10));
+			    const y = Number(lineText.slice(10, 20));
+			    const z = Number(lineText.slice(20, 30));
+			    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) continue;
+			    const symbol = lineText.slice(31, 34).trim() || lineText.trim().split(/\s+/)[3] || 'C';
+			    atoms.push(atomRecord({
+			      serial: offset + 1,
+			      name: symbol,
+			      element: symbol,
+			      residue: '',
+			      chain: '',
+			      residueNumber: '',
+			      x,
+			      y,
+			      z,
+			      hetatm: false,
+			    }));
+			  }
+			  requireAtoms(atoms, 'SDF/MOL');
+			  const bonds = [];
+			  const bondStart = countsIndex + 1 + atomCount;
+			  for (let offset = 0; offset < bondCount; offset++) {
+			    const lineText = lines[bondStart + offset] ?? '';
+			    const from = Number.parseInt(lineText.slice(0, 3), 10) - 1;
+			    const to = Number.parseInt(lineText.slice(3, 6), 10) - 1;
+			    const order = Number.parseInt(lineText.slice(6, 9), 10);
+			    if (from < 0 || to < 0 || from >= atoms.length || to >= atoms.length) continue;
+			    bonds.push({ a: from, b: to, order: Number.isInteger(order) && order > 0 ? order : 1 });
+			  }
+			  return {
+			    kind: 'structure',
+			    format: 'sdf',
+			    name,
+			    title,
+			    atoms,
+			    bonds: bonds.slice(0, MAX_STRUCTURE_BONDS),
+			  };
+			}
+
+			exports.STRUCTURE_EXTENSIONS = STRUCTURE_EXTENSIONS;
+			exports.MAX_STRUCTURE_ATOMS = MAX_STRUCTURE_ATOMS;
+			exports.MAX_STRUCTURE_BONDS = MAX_STRUCTURE_BONDS;
+			exports.structureFormatOf = structureFormatOf;
+			exports.parseStructureText = parseStructureText;
+			exports.parsePdb = parsePdb;
+			exports.parseMmcif = parseMmcif;
+			exports.parseSdf = parseSdf;
+			return exports;
+		};
+		__molbio_modules["structure-render.mjs"] = () => {
+			const exports = {};
+			/**
+			 * dsh-molbio-tools/structure-render.mjs
+			 *
+			 * A small, dependency-free software renderer for the realistic 3D structure
+			 * preview: ball-and-stick and space-filling models with perspective, a z-buffer
+			 * and simple Phong lighting.
+			 *
+			 * WHY A SOFTWARE RENDERER
+			 * -----------------------
+			 * The DSH Web client is a browser, but this package ships zero runtime
+			 * dependencies and must keep the browser half Node-free. Canvas 2D is available
+			 * everywhere, yet gradients/shadow support differs between engines and is hard
+			 * to test in Node. Rendering an RGB buffer here gives:
+			 *
+			 *   - one implementation shared by the panel and the tests;
+			 *   - a PNG the tests can encode and inspect without a browser;
+			 *   - deterministic pixels for a given record and view;
+			 *   - no WebGL context, shader compilation or asset download.
+			 *
+			 * The tradeoff is CPU rasterization. The panel renders at reduced supersampling
+			 * while a pointer drag is active and at full quality when it settles; the
+			 * atom cap keeps a single frame bounded.
+			 *
+			 * WHAT THIS IS NOT
+			 * ----------------
+			 * No molecular surface, no electrostatics, no ambient occlusion, no secondary
+			 * structure ribbons. It is a realistic atom/bond model, not an analysis tool.
+			 */
+			const { MolbioInputError } = __molbio_require("lib.mjs");
+			/** The representations the panel offers, in display order. */
+			const STRUCTURE_REPRESENTATIONS = ['ball-and-stick', 'space-filling'];
+
+			/** CPK-like colours, exported so the panel legend and renderer cannot drift. */
+			const STRUCTURE_ELEMENT_COLORS = Object.freeze({
+			  H: '#e8ebef',
+			  C: '#6b7480',
+			  N: '#2f6fdb',
+			  O: '#d64545',
+			  S: '#d0a02a',
+			  P: '#e07a2f',
+			  F: '#3aa76d',
+			  CL: '#3aa76d',
+			  BR: '#a6512c',
+			  I: '#7b4bb7',
+			  FE: '#c26a2e',
+			  ZN: '#7b8794',
+			  MG: '#3aa76d',
+			  CA: '#3aa76d',
+			  NA: '#3aa76d',
+			  K: '#3aa76d',
+			});
+
+			/** The initial camera the panel uses when a structure is selected. */
+			const DEFAULT_STRUCTURE_VIEW = Object.freeze({
+			  yaw: 0.55,
+			  pitch: 0.18,
+			  zoom: 1,
+			  representation: 'ball-and-stick',
+			});
+
+			/** A single frame above this atom count is refused rather than freezing the tab. */
+			const MAX_RENDER_ATOMS = 12000;
+
+			const VDW = { H: 1.20, C: 1.70, N: 1.55, O: 1.52, P: 1.80, S: 1.80, F: 1.47, CL: 1.75, BR: 1.85, I: 1.98, FE: 1.80, ZN: 1.39, MG: 1.73, CA: 1.95, NA: 2.27, K: 2.75 };
+			const COVALENT = { H: 0.31, C: 0.76, N: 0.71, O: 0.66, P: 1.07, S: 1.05, F: 0.57, CL: 1.02, BR: 1.20, I: 1.39, FE: 1.24, ZN: 1.22, MG: 1.41, CA: 1.76, NA: 1.66, K: 2.03 };
+			const BG = [247, 249, 251];
+			const EMPTY = new Uint8Array(0);
+
+			/** Is this atom a crystallographic water that should not clutter the preview? */
+			function isWater(atom) {
+			  const residue = String(atom.residue ?? '').toUpperCase();
+			  return residue === 'HOH' || residue === 'WAT' || residue === 'DOD';
+			}
+
+			/** Rounded element colour, with a neutral fallback for metals and unknowns. */
+			function elementColor(element) {
+			  return STRUCTURE_ELEMENT_COLORS[String(element ?? '').toUpperCase()] ?? '#5b9b74';
+			}
+
+			/** Hex colour to [r,g,b]. */
+			function rgbOf(hex) {
+			  return [parseInt(hex.slice(1, 3), 16), parseInt(hex.slice(3, 5), 16), parseInt(hex.slice(5, 7), 16)];
+			}
+
+			/** Spatial hash of atom indices on a cubic grid. */
+			function gridIndex(atoms, cell) {
+			  const grid = new Map();
+			  for (let index = 0; index < atoms.length; index++) {
+			    const atom = atoms[index];
+			    const key = `${Math.floor(atom.x / cell)},${Math.floor(atom.y / cell)},${Math.floor(atom.z / cell)}`;
+			    const bucket = grid.get(key);
+			    if (bucket === undefined) grid.set(key, [index]);
+			    else bucket.push(index);
+			  }
+			  return grid;
+			}
+
+			/**
+			 * Infer a covalent bond graph from 3D coordinates.
+			 *
+			 * Covalent radii (not van der Waals radii) are the right scale for a bond: a
+			 * vdW-sum threshold would connect every atom pair in a tightly packed helix.
+			 * The 0.45 Å tolerance absorbs coordinate precision without reaching the next
+			 * bonded neighbour in the common C-C/N-C/O-C cases.
+			 * @param {Array} atoms
+			 * @returns {Array<[number, number]>} index pairs into `atoms`.
+			 */
+			function inferStructureBonds(atoms) {
+			  const bonds = [];
+			  if (!Array.isArray(atoms) || atoms.length < 2 || atoms.length > MAX_RENDER_ATOMS) return bonds;
+			  const cell = 2.4;
+			  const grid = gridIndex(atoms, cell);
+			  for (let i = 0; i < atoms.length; i++) {
+			    const a = atoms[i];
+			    if (a.element === 'H') continue;
+			    const gx = Math.floor(a.x / cell);
+			    const gy = Math.floor(a.y / cell);
+			    const gz = Math.floor(a.z / cell);
+			    for (let dx = -1; dx <= 1; dx++) {
+			      for (let dy = -1; dy <= 1; dy++) {
+			        for (let dz = -1; dz <= 1; dz++) {
+			          const bucket = grid.get(`${gx + dx},${gy + dy},${gz + dz}`);
+			          if (bucket === undefined) continue;
+			          for (const j of bucket) {
+			            if (j <= i) continue;
+			            const b = atoms[j];
+			            if (b.element === 'H') continue;
+			            const distance = Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+			            const limit = (COVALENT[a.element] ?? 0.8) + (COVALENT[b.element] ?? 0.8) + 0.45;
+			            if (distance > 0.35 && distance <= limit) bonds.push([i, j]);
+			          }
+			        }
+			      }
+			    }
+			  }
+			  return bonds;
+			}
+
+			/** Filter atoms the preview does not draw, keeping a serial -> index map. */
+			function preparedAtoms(record) {
+			  const atoms = [];
+			  const bySerial = new Map();
+			  for (const atom of record.atoms) {
+			    if (atom.element === 'H' || isWater(atom)) continue;
+			    if (!Number.isFinite(atom.x) || !Number.isFinite(atom.y) || !Number.isFinite(atom.z)) continue;
+			    bySerial.set(atom.serial, atoms.length);
+			    atoms.push(atom);
+			  }
+			  return { atoms, bySerial };
+			}
+
+			/** Explicit bonds from the parser, mapped onto the filtered atom array. */
+			function explicitBonds(record, bySerial) {
+			  const bonds = [];
+			  const seen = new Set();
+			  for (const bond of record.bonds ?? []) {
+			    const fromAtom = record.atoms[bond.a];
+			    const toAtom = record.atoms[bond.b];
+			    if (fromAtom === undefined || toAtom === undefined) continue;
+			    const a = bySerial.get(fromAtom.serial);
+			    const b = bySerial.get(toAtom.serial);
+			    if (a === undefined || b === undefined || a === b) continue;
+			    const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+			    if (seen.has(key)) continue;
+			    seen.add(key);
+			    bonds.push([a, b]);
+			  }
+			  return bonds;
+			}
+
+			/** The bond list used by the renderer for one representation. */
+			function bondList(record, atoms, bySerial, representation) {
+			  if (representation === 'space-filling') return [];
+			  if (record.format === 'sdf') return explicitBonds(record, bySerial);
+			  const inferred = inferStructureBonds(atoms);
+			  const explicit = explicitBonds(record, bySerial);
+			  if (explicit.length === 0) return inferred;
+			  const seen = new Set(inferred.map(([a, b]) => (a < b ? `${a}:${b}` : `${b}:${a}`)));
+			  const merged = [...inferred];
+			  for (const [a, b] of explicit) {
+			    const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+			    if (seen.has(key)) continue;
+			    seen.add(key);
+			    merged.push([a, b]);
+			  }
+			  return merged;
+			}
+
+			/** Clamp a finite number, or use the fallback. */
+			function numberOr(value, fallback, min, max) {
+			  const numeric = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+			  return Math.max(min, Math.min(max, numeric));
+			}
+
+			/**
+			 * Render one structure frame to an RGB buffer.
+			 *
+			 * @param {object} record a parseStructureText record.
+			 * @param {object} [options]
+			 * @param {number} [options.width=640]
+			 * @param {number} [options.height=480]
+			 * @param {1|2} [options.supersample=2] 1 is the interaction-quality setting.
+			 * @param {number} [options.yaw=0.55]
+			 * @param {number} [options.pitch=0.18]
+			 * @param {number} [options.zoom=1]
+			 * @param {'ball-and-stick'|'space-filling'} [options.representation='ball-and-stick']
+			 * @returns {{width:number,height:number,rgb:Uint8Array,atoms:number,bonds:number,representation:string}}
+			 */
+			function renderStructureImage(record, options = {}) {
+			  if (record === null || typeof record !== 'object' || !Array.isArray(record.atoms)) {
+			    throw new MolbioInputError('renderStructureImage needs a parsed structure record');
+			  }
+			  const representation = options.representation ?? 'ball-and-stick';
+			  if (!STRUCTURE_REPRESENTATIONS.includes(representation)) {
+			    throw new MolbioInputError(`unknown structure representation ${JSON.stringify(representation)}; use ${STRUCTURE_REPRESENTATIONS.join(' or ')}`);
+			  }
+			  const width = Math.round(numberOr(options.width, 640, 64, 1600));
+			  const height = Math.round(numberOr(options.height, 480, 64, 1200));
+			  const supersample = Math.round(numberOr(options.supersample, 2, 1, 2));
+			  const yaw = numberOr(options.yaw, DEFAULT_STRUCTURE_VIEW.yaw, -Math.PI * 8, Math.PI * 8);
+			  const pitch = numberOr(options.pitch, DEFAULT_STRUCTURE_VIEW.pitch, -1.45, 1.45);
+			  const zoom = numberOr(options.zoom, 1, 0.35, 5);
+			  const { atoms, bySerial } = preparedAtoms(record);
+			  if (atoms.length === 0) throw new MolbioInputError('the structure has no heavy atoms to draw');
+			  if (atoms.length > MAX_RENDER_ATOMS) {
+			    throw new MolbioInputError(`the structure has ${atoms.length} heavy atoms; the preview renders at most ${MAX_RENDER_ATOMS}`);
+			  }
+			  const bonds = bondList(record, atoms, bySerial, representation);
+			  const W = width * supersample;
+			  const H = height * supersample;
+
+			  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity, minZ = Infinity, maxZ = -Infinity;
+			  for (const atom of atoms) {
+			    if (atom.x < minX) minX = atom.x;
+			    if (atom.x > maxX) maxX = atom.x;
+			    if (atom.y < minY) minY = atom.y;
+			    if (atom.y > maxY) maxY = atom.y;
+			    if (atom.z < minZ) minZ = atom.z;
+			    if (atom.z > maxZ) maxZ = atom.z;
+			  }
+			  const cx = (minX + maxX) / 2;
+			  const cy = (minY + maxY) / 2;
+			  const cz = (minZ + maxZ) / 2;
+			  let radius = 6;
+			  for (const atom of atoms) radius = Math.max(radius, Math.hypot(atom.x - cx, atom.y - cy, atom.z - cz));
+			  const camera = (radius * 2.0) / zoom;
+			  const focal = Math.min(W, H) * 1.15;
+			  const cyaw = Math.cos(yaw), syaw = Math.sin(yaw);
+			  const cp = Math.cos(pitch), sp = Math.sin(pitch);
+
+			  const project = (atom) => {
+			    const x = atom.x - cx;
+			    const y = atom.y - cy;
+			    const z = atom.z - cz;
+			    const x1 = x * cyaw + z * syaw;
+			    const z1 = -x * syaw + z * cyaw;
+			    const y1 = y * cp - z1 * sp;
+			    const z2 = y * sp + z1 * cp;
+			    const depth = camera - z2;
+			    const scale = focal / Math.max(1, depth);
+			    return { x: W / 2 + x1 * scale, y: H / 2 - y1 * scale, depth, scale };
+			  };
+			  const projected = atoms.map(project);
+
+			  const rgb = new Uint8Array(W * H * 3);
+			  for (let y = 0; y < H; y++) {
+			    const t = y / Math.max(1, H - 1);
+			    const r = Math.round(248 - 5 * t);
+			    const g = Math.round(250 - 5 * t);
+			    const b = Math.round(252 - 4 * t);
+			    for (let x = 0; x < W; x++) {
+			      const offset = (y * W + x) * 3;
+			      rgb[offset] = r;
+			      rgb[offset + 1] = g;
+			      rgb[offset + 2] = b;
+			    }
+			  }
+			  const depthBuffer = new Float32Array(W * H).fill(Infinity);
+			  const light = [0.35, 0.45, 0.82];
+			  const lightLength = Math.hypot(light[0], light[1], light[2]);
+			  const L = [light[0] / lightLength, light[1] / lightLength, light[2] / lightLength];
+
+			  const shade = (base, nx, ny, nz, depth) => {
+			    const diffuse = Math.max(0, nx * L[0] + ny * L[1] + nz * L[2]);
+			    const hx = L[0], hy = L[1], hz = L[2] + 1;
+			    const hLength = Math.hypot(hx, hy, hz);
+			    const specular = Math.pow(Math.max(0, (nx * hx + ny * hy + nz * hz) / hLength), 42) * 0.35;
+			    const ambient = 0.30;
+			    const fog = Math.max(0, Math.min(0.28, (depth - camera * 0.45) / (camera * 1.8)));
+			    const lightLevel = ambient + diffuse * 0.68;
+			    return [
+			      Math.round((base[0] * lightLevel + 255 * specular) * (1 - fog) + BG[0] * fog),
+			      Math.round((base[1] * lightLevel + 255 * specular) * (1 - fog) + BG[1] * fog),
+			      Math.round((base[2] * lightLevel + 255 * specular) * (1 - fog) + BG[2] * fog),
+			    ];
+			  };
+
+			  // Bonds are rasterized as shaded capsules. The z-buffer makes draw order
+			  // irrelevant for overlaps, so no global primitive sort is needed.
+			  if (representation !== 'space-filling') {
+			    for (const [i, j] of bonds) {
+			      const a = projected[i];
+			      const b = projected[j];
+			      const bondRadius = 0.18 * ((a.scale + b.scale) / 2);
+			      const dx = b.x - a.x;
+			      const dy = b.y - a.y;
+			      const length2 = dx * dx + dy * dy;
+			      if (length2 < 1e-6 || bondRadius < 0.25) continue;
+			      const padding = bondRadius + 2;
+			      const minPX = Math.max(0, Math.floor(Math.min(a.x, b.x) - padding));
+			      const maxPX = Math.min(W - 1, Math.ceil(Math.max(a.x, b.x) + padding));
+			      const minPY = Math.max(0, Math.floor(Math.min(a.y, b.y) - padding));
+			      const maxPY = Math.min(H - 1, Math.ceil(Math.max(a.y, b.y) + padding));
+			      const base = [116, 126, 141];
+			      for (let py = minPY; py <= maxPY; py++) {
+			        for (let px = minPX; px <= maxPX; px++) {
+			          const t = Math.max(0, Math.min(1, ((px - a.x) * dx + (py - a.y) * dy) / length2));
+			          const qx = a.x + dx * t;
+			          const qy = a.y + dy * t;
+			          const vx = px - qx;
+			          const vy = py - qy;
+			          const distance = Math.hypot(vx, vy);
+			          if (distance > bondRadius) continue;
+			          const front = Math.sqrt(Math.max(0, bondRadius * bondRadius - distance * distance)) / Math.max(1e-6, (a.scale + b.scale) / 2);
+			          const depth = a.depth + (b.depth - a.depth) * t - front;
+			          const index = py * W + px;
+			          if (depth >= depthBuffer[index]) continue;
+			          const nx = vx / Math.max(1e-6, bondRadius);
+			          const ny = -vy / Math.max(1e-6, bondRadius);
+			          const nz = Math.sqrt(Math.max(0, 1 - nx * nx - ny * ny));
+			          const colour = shade(base, nx, ny, nz, depth);
+			          const offset = index * 3;
+			          rgb[offset] = colour[0];
+			          rgb[offset + 1] = colour[1];
+			          rgb[offset + 2] = colour[2];
+			          depthBuffer[index] = depth;
+			        }
+			      }
+			    }
+			  }
+
+			  // Front-to-back atom order reduces z-buffer writes, but correctness comes
+			  // from the depth test, not the order.
+			  const order = atoms.map((_, index) => index).sort((left, right) => projected[left].depth - projected[right].depth);
+			  for (const index of order) {
+			    const atom = atoms[index];
+			    const point = projected[index];
+			    const baseRadius = (VDW[atom.element] ?? 1.5) * (representation === 'space-filling' ? 1.0 : 0.28);
+			    const screenRadius = baseRadius * point.scale;
+			    if (screenRadius < 0.4) continue;
+			    const base = rgbOf(elementColor(atom.element));
+			    const minPX = Math.max(0, Math.floor(point.x - screenRadius - 1));
+			    const maxPX = Math.min(W - 1, Math.ceil(point.x + screenRadius + 1));
+			    const minPY = Math.max(0, Math.floor(point.y - screenRadius - 1));
+			    const maxPY = Math.min(H - 1, Math.ceil(point.y + screenRadius + 1));
+			    const radius2 = screenRadius * screenRadius;
+			    for (let py = minPY; py <= maxPY; py++) {
+			      const dy = py - point.y;
+			      for (let px = minPX; px <= maxPX; px++) {
+			        const dx = px - point.x;
+			        const distance2 = dx * dx + dy * dy;
+			        if (distance2 > radius2) continue;
+			        const dz = Math.sqrt(Math.max(0, radius2 - distance2));
+			        const depth = point.depth - dz / point.scale;
+			        const bufferIndex = py * W + px;
+			        if (depth >= depthBuffer[bufferIndex]) continue;
+			        const nx = dx / screenRadius;
+			        const ny = -dy / screenRadius;
+			        const nz = dz / screenRadius;
+			        const colour = shade(base, nx, ny, nz, depth);
+			        const offset = bufferIndex * 3;
+			        rgb[offset] = colour[0];
+			        rgb[offset + 1] = colour[1];
+			        rgb[offset + 2] = colour[2];
+			        depthBuffer[bufferIndex] = depth;
+			      }
+			    }
+			  }
+
+			  // Box-filter the supersampled image back to the requested size.
+			  const out = new Uint8Array(width * height * 3);
+			  const samples = supersample * supersample;
+			  for (let y = 0; y < height; y++) {
+			    for (let x = 0; x < width; x++) {
+			      let r = 0, g = 0, b = 0;
+			      for (let sy = 0; sy < supersample; sy++) {
+			        for (let sx = 0; sx < supersample; sx++) {
+			          const offset = ((y * supersample + sy) * W + (x * supersample + sx)) * 3;
+			          r += rgb[offset];
+			          g += rgb[offset + 1];
+			          b += rgb[offset + 2];
+			        }
+			      }
+			      const offset = (y * width + x) * 3;
+			      out[offset] = Math.round(r / samples);
+			      out[offset + 1] = Math.round(g / samples);
+			      out[offset + 2] = Math.round(b / samples);
+			    }
+			  }
+			  return { width, height, rgb: out, atoms: atoms.length, bonds: bonds.length, representation };
+			}
+
+			exports.STRUCTURE_REPRESENTATIONS = STRUCTURE_REPRESENTATIONS;
+			exports.STRUCTURE_ELEMENT_COLORS = STRUCTURE_ELEMENT_COLORS;
+			exports.DEFAULT_STRUCTURE_VIEW = DEFAULT_STRUCTURE_VIEW;
+			exports.MAX_RENDER_ATOMS = MAX_RENDER_ATOMS;
+			exports.inferStructureBonds = inferStructureBonds;
+			exports.renderStructureImage = renderStructureImage;
+			return exports;
+		};
 		__molbio_modules["methylation.mjs"] = () => {
 			const exports = {};
 			/**
@@ -8157,12 +8976,13 @@ window.__ModuleLoader__.load({
 			 * 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.
 			 */
 
 
@@ -8182,55 +9002,66 @@ window.__ModuleLoader__.load({
 
 
 
-			exports.DNA_BASES = __molbio_require("lib.mjs").undefined;
-			exports.ENZYME_NAMES = __molbio_require("lib.mjs").undefined;
-			exports.MolbioInputError = __molbio_require("lib.mjs").undefined;
-			exports.baseCounts = __molbio_require("lib.mjs").undefined;
-			exports.complement = __molbio_require("lib.mjs").undefined;
-			exports.enzymeCatalog = __molbio_require("lib.mjs").undefined;
-			exports.enzymeCuts = __molbio_require("lib.mjs").undefined;
-			exports.enzymePattern = __molbio_require("lib.mjs").undefined;
-			exports.findRuns = __molbio_require("lib.mjs").undefined;
-			exports.hairpinThermo = __molbio_require("lib.mjs").undefined;
-			exports.isIisEnzyme = __molbio_require("lib.mjs").undefined;
-			exports.normalizeSequence = __molbio_require("lib.mjs").undefined;
-			exports.primerTm = __molbio_require("lib.mjs").undefined;
-			exports.reverseComplement = __molbio_require("lib.mjs").undefined;
-			exports.selfAnyScore = __molbio_require("lib.mjs").undefined;
-			exports.selfEndScore = __molbio_require("lib.mjs").undefined;
-			exports.parseGenBank = __molbio_require("genbank.mjs").undefined;
-			exports.parseSnapGeneBytes = __molbio_require("snapgene.mjs").undefined;
-			exports.parseXml = __molbio_require("snapgene.mjs").undefined;
-			exports.renderPlasmidMap = __molbio_require("plasmid.mjs").undefined;
-			exports.normalizeAlignedRow = __molbio_require("msa.mjs").undefined;
-			exports.progressiveAlign = __molbio_require("msa.mjs").undefined;
-			exports.conservationAnalysis = __molbio_require("msa.mjs").undefined;
-			exports.pairwiseIdentities = __molbio_require("msa.mjs").undefined;
-			exports.columnComposition = __molbio_require("logo.mjs").undefined;
-			exports.renderSequenceLogo = __molbio_require("logo.mjs").undefined;
-			exports.designGrnas = __molbio_require("crispr.mjs").undefined;
-			exports.findProtospacers = __molbio_require("crispr.mjs").undefined;
-			exports.evaluateGuide = __molbio_require("crispr.mjs").undefined;
-			exports.entryStats = __molbio_require("seqio.mjs").undefined;
-			exports.parseFasta = __molbio_require("seqio.mjs").undefined;
-			exports.digest = __molbio_require("lib.mjs").undefined;
-			exports.BUFFERS = __molbio_require("lib.mjs").undefined;
-			exports.METHYLATION_SENSITIVITY = __molbio_require("lib.mjs").undefined;
-			exports.METHYLATION_SITES = __molbio_require("lib.mjs").undefined;
-			exports.methylationImpact = __molbio_require("lib.mjs").undefined;
-			exports.methylationSites = __molbio_require("lib.mjs").undefined;
-			exports.sharedBuffers = __molbio_require("lib.mjs").undefined;
-			exports.designTaqmanProbes = __molbio_require("taqman.mjs").undefined;
-			exports.evaluateProbe = __molbio_require("taqman.mjs").undefined;
-			exports.probeCandidates = __molbio_require("taqman.mjs").undefined;
-			exports.checkMultiplex = __molbio_require("multiplex.mjs").undefined;
-			exports.helicalWheel = __molbio_require("protein-structure.mjs").undefined;
-			exports.hydropathyProfile = __molbio_require("protein-structure.mjs").undefined;
-			exports.renderHelicalWheel = __molbio_require("protein-structure.mjs").undefined;
-			exports.renderHydropathyPlot = __molbio_require("protein-structure.mjs").undefined;
-			exports.analyzeMethylation = __molbio_require("methylation.mjs").undefined;
-			exports.bufferReport = __molbio_require("methylation.mjs").undefined;
-			exports.planDoubleDigest = __molbio_require("methylation.mjs").undefined;
+
+
+			exports.DNA_BASES = __molbio_require("lib.mjs").DNA_BASES;
+			exports.ENZYME_NAMES = __molbio_require("lib.mjs").ENZYME_NAMES;
+			exports.MolbioInputError = __molbio_require("lib.mjs").MolbioInputError;
+			exports.baseCounts = __molbio_require("lib.mjs").baseCounts;
+			exports.complement = __molbio_require("lib.mjs").complement;
+			exports.enzymeCatalog = __molbio_require("lib.mjs").enzymeCatalog;
+			exports.enzymeCuts = __molbio_require("lib.mjs").enzymeCuts;
+			exports.enzymePattern = __molbio_require("lib.mjs").enzymePattern;
+			exports.findRuns = __molbio_require("lib.mjs").findRuns;
+			exports.hairpinThermo = __molbio_require("lib.mjs").hairpinThermo;
+			exports.isIisEnzyme = __molbio_require("lib.mjs").isIisEnzyme;
+			exports.normalizeSequence = __molbio_require("lib.mjs").normalizeSequence;
+			exports.primerTm = __molbio_require("lib.mjs").primerTm;
+			exports.reverseComplement = __molbio_require("lib.mjs").reverseComplement;
+			exports.selfAnyScore = __molbio_require("lib.mjs").selfAnyScore;
+			exports.selfEndScore = __molbio_require("lib.mjs").selfEndScore;
+			exports.parseGenBank = __molbio_require("genbank.mjs").parseGenBank;
+			exports.parseSnapGeneBytes = __molbio_require("snapgene.mjs").parseSnapGeneBytes;
+			exports.parseXml = __molbio_require("snapgene.mjs").parseXml;
+			exports.renderPlasmidMap = __molbio_require("plasmid.mjs").renderPlasmidMap;
+			exports.normalizeAlignedRow = __molbio_require("msa.mjs").normalizeAlignedRow;
+			exports.progressiveAlign = __molbio_require("msa.mjs").progressiveAlign;
+			exports.conservationAnalysis = __molbio_require("msa.mjs").conservationAnalysis;
+			exports.pairwiseIdentities = __molbio_require("msa.mjs").pairwiseIdentities;
+			exports.columnComposition = __molbio_require("logo.mjs").columnComposition;
+			exports.renderSequenceLogo = __molbio_require("logo.mjs").renderSequenceLogo;
+			exports.designGrnas = __molbio_require("crispr.mjs").designGrnas;
+			exports.findProtospacers = __molbio_require("crispr.mjs").findProtospacers;
+			exports.evaluateGuide = __molbio_require("crispr.mjs").evaluateGuide;
+			exports.entryStats = __molbio_require("seqio.mjs").entryStats;
+			exports.parseFasta = __molbio_require("seqio.mjs").parseFasta;
+			exports.digest = __molbio_require("lib.mjs").digest;
+			exports.BUFFERS = __molbio_require("lib.mjs").BUFFERS;
+			exports.METHYLATION_SENSITIVITY = __molbio_require("lib.mjs").METHYLATION_SENSITIVITY;
+			exports.METHYLATION_SITES = __molbio_require("lib.mjs").METHYLATION_SITES;
+			exports.methylationImpact = __molbio_require("lib.mjs").methylationImpact;
+			exports.methylationSites = __molbio_require("lib.mjs").methylationSites;
+			exports.sharedBuffers = __molbio_require("lib.mjs").sharedBuffers;
+			exports.designTaqmanProbes = __molbio_require("taqman.mjs").designTaqmanProbes;
+			exports.evaluateProbe = __molbio_require("taqman.mjs").evaluateProbe;
+			exports.probeCandidates = __molbio_require("taqman.mjs").probeCandidates;
+			exports.checkMultiplex = __molbio_require("multiplex.mjs").checkMultiplex;
+			exports.helicalWheel = __molbio_require("protein-structure.mjs").helicalWheel;
+			exports.hydropathyProfile = __molbio_require("protein-structure.mjs").hydropathyProfile;
+			exports.renderHelicalWheel = __molbio_require("protein-structure.mjs").renderHelicalWheel;
+			exports.renderHydropathyPlot = __molbio_require("protein-structure.mjs").renderHydropathyPlot;
+			exports.STRUCTURE_EXTENSIONS = __molbio_require("structure-preview.mjs").STRUCTURE_EXTENSIONS;
+			exports.parseStructureText = __molbio_require("structure-preview.mjs").parseStructureText;
+			exports.structureFormatOf = __molbio_require("structure-preview.mjs").structureFormatOf;
+			exports.DEFAULT_STRUCTURE_VIEW = __molbio_require("structure-render.mjs").DEFAULT_STRUCTURE_VIEW;
+			exports.MAX_RENDER_ATOMS = __molbio_require("structure-render.mjs").MAX_RENDER_ATOMS;
+			exports.STRUCTURE_ELEMENT_COLORS = __molbio_require("structure-render.mjs").STRUCTURE_ELEMENT_COLORS;
+			exports.STRUCTURE_REPRESENTATIONS = __molbio_require("structure-render.mjs").STRUCTURE_REPRESENTATIONS;
+			exports.inferStructureBonds = __molbio_require("structure-render.mjs").inferStructureBonds;
+			exports.renderStructureImage = __molbio_require("structure-render.mjs").renderStructureImage;
+			exports.analyzeMethylation = __molbio_require("methylation.mjs").analyzeMethylation;
+			exports.bufferReport = __molbio_require("methylation.mjs").bufferReport;
+			exports.planDoubleDigest = __molbio_require("methylation.mjs").planDoubleDigest;
 			return exports;
 		};
 		__molbio_modules["build/panel-core.mjs"] = () => {
@@ -8247,7 +9078,7 @@ window.__ModuleLoader__.load({
 			 * All parsing and rendering is the SAME code the Node tools run: this module
 			 * re-exports through browser-api.mjs, which points at the root .mjs sources.
 			 */
-			const { MolbioInputError, parseGenBank, parseSnapGeneBytes, renderPlasmidMap, columnComposition, renderSequenceLogo, progressiveAlign } = __molbio_require("build/browser-api.mjs");
+			const { MolbioInputError, parseGenBank, parseSnapGeneBytes, renderPlasmidMap, columnComposition, renderSequenceLogo, progressiveAlign, parseStructureText, renderStructureImage, DEFAULT_STRUCTURE_VIEW, STRUCTURE_ELEMENT_COLORS, STRUCTURE_EXTENSIONS, STRUCTURE_REPRESENTATIONS } = __molbio_require("build/browser-api.mjs");
 			/** Extensions the panel can open, mapped to the parser that handles them. */
 			const PLASMID_EXTENSIONS = {
 			  dna: 'snapgene',
@@ -8264,6 +9095,8 @@ window.__ModuleLoader__.load({
 			  fas: 'fasta',
 			};
 
+			/** Structure formats the panel opens, mapped to the parser kind. */
+
 			/** Lowercase extension without the dot, or '' when there is none. */
 			function extensionOf(name) {
 			  const match = /\.([A-Za-z0-9]+)$/.exec(String(name));
@@ -8273,7 +9106,7 @@ window.__ModuleLoader__.load({
 			/**
 			 * 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'}
 			 */
 			function classifyEntry(entry) {
 			  if (entry === null || typeof entry !== 'object') return 'other';
@@ -8282,18 +9115,19 @@ window.__ModuleLoader__.load({
 			  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. */
 			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. */
 			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;
@@ -8392,6 +9226,44 @@ window.__ModuleLoader__.load({
 			  });
 			}
 
+			/**
+			 * 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.
+			 */
+			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}}
+			 */
+			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.
@@ -8753,6 +9625,8 @@ window.__ModuleLoader__.load({
 			exports.MAX_PANEL_FILE_BYTES = MAX_PANEL_FILE_BYTES;
 			exports.parsePlasmidFile = parsePlasmidFile;
 			exports.plasmidSvg = plasmidSvg;
+			exports.parseStructureFile = parseStructureFile;
+			exports.structureImage = structureImage;
 			exports.parseAlignmentFile = parseAlignmentFile;
 			exports.logoSvg = logoSvg;
 			exports.MAP_CARD_KIND = MAP_CARD_KIND;
@@ -8773,6 +9647,10 @@ window.__ModuleLoader__.load({
 			exports.isMolbioDetailSubject = isMolbioDetailSubject;
 			exports.remoteFailure = remoteFailure;
 			exports.credentialInfo = credentialInfo;
+			exports.DEFAULT_STRUCTURE_VIEW = DEFAULT_STRUCTURE_VIEW;
+			exports.STRUCTURE_ELEMENT_COLORS = STRUCTURE_ELEMENT_COLORS;
+			exports.STRUCTURE_EXTENSIONS = STRUCTURE_EXTENSIONS;
+			exports.STRUCTURE_REPRESENTATIONS = STRUCTURE_REPRESENTATIONS;
 			return exports;
 		};
 		__molbio_modules["build/client-entry.mjs"] = () => {
@@ -8809,7 +9687,7 @@ window.__ModuleLoader__.load({
 			 * inside the factory would also have to be torn down by hand on unload.
 			 */
 			const { createElement: h, useEffect, useMemo, useRef, useState } = __ext0;
-			const { LIBRARY_FILE, NCBI_KEY_REF, childPath, classifyEntry, credentialInfo, figureCardSummary, figureCardView, isMolbioDetailSubject, remoteFailure, decodeWorkspaceBytes, filterPapers, isOpenable, libraryTags, logoSvg, mapCardSummary, mapCardView, paperFields, paperLink, paperSummary, parseAlignmentFile, parseLibrary, parsePlasmidFile, plasmidSvg, readWorkspaceText, sortEntries } = __molbio_require("build/panel-core.mjs");
+			const { LIBRARY_FILE, NCBI_KEY_REF, childPath, classifyEntry, credentialInfo, figureCardSummary, figureCardView, isMolbioDetailSubject, remoteFailure, decodeWorkspaceBytes, filterPapers, isOpenable, libraryTags, logoSvg, mapCardSummary, mapCardView, paperFields, paperLink, paperSummary, parseAlignmentFile, parseLibrary, parsePlasmidFile, parseStructureFile, plasmidSvg, readWorkspaceText, sortEntries, structureImage, DEFAULT_STRUCTURE_VIEW, STRUCTURE_ELEMENT_COLORS, STRUCTURE_REPRESENTATIONS } = __molbio_require("build/panel-core.mjs");
 			/** This implementation's identity, and the key its body/title register under. */
 			const PANEL_ID = 'dsh-molbio-tools';
 			/** Type discriminator the tab is opened by. */
@@ -8887,6 +9765,20 @@ window.__ModuleLoader__.load({
 			  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)' },
@@ -8899,7 +9791,11 @@ window.__ModuleLoader__.load({
 			  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(() => {
@@ -8929,8 +9825,13 @@ window.__ModuleLoader__.load({
 			        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) => {
@@ -8950,7 +9851,7 @@ window.__ModuleLoader__.load({
 			    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.
@@ -8971,15 +9872,90 @@ window.__ModuleLoader__.load({
 			    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(
@@ -9034,6 +10010,40 @@ window.__ModuleLoader__.load({
 			      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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-molbio-panel",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Browser panel for the DeepSeek Harness Web GUI: a Molbio tab in the right sidebar that draws plasmid maps and sequence logos from workspace sequence files, using the same computation modules as the dsh-molbio-tools plugin.",
   "type": "module",
   "main": "index.mjs",