dsh-molbio-tools 0.22.2 → 0.24.0

package/test/map-card.mjs

@@ -344,6 +344,144 @@ assert.ok(unparseableText.includes('could not be parsed as SVG'), 'unparseable m
 assert.ok(unparseableText.includes('pCARD · 206 bp'), 'and the header is still there, above the explanation');
 unparseable.unmount();
 
+// ── figure cards: sequence logo and gRNA design ─────────────────────────────
+
+/** Deterministic pseudo-random DNA for the gRNA fixture. */
+function dnaFixture(n, seed) {
+  let s = seed;
+  const bases = 'ACGT';
+  let out = '';
+  for (let i = 0; i < n; i++) {
+    s = (s * 1103515245 + 12345) % 2147483648;
+    out += bases[(s >> 16) % 4];
+  }
+  return out;
+}
+
+const logoTool = registered.find((entry) => entry.name === 'molbio_sequence_logo');
+const grnaTool = registered.find((entry) => entry.name === 'molbio_grna_design');
+assert.ok(logoTool !== undefined && grnaTool !== undefined, 'both figure tools register');
+
+const logoArgs = { sequences: ['ACGTACGTACGTACGT', 'ACGTACGTACGTACGA', 'ACGTACGTTCGTACGT'] };
+const logoValue = await logoTool.execute(logoArgs, exec);
+const logoMeta = logoTool.output.presentationMeta(logoArgs, logoValue);
+assert.equal(logoMeta.kind, 'molbio-figure');
+assert.equal(logoMeta.figure, 'logo');
+assert.equal(logoMeta.svg_path, logoValue.svg_path);
+assert.ok(typeof logoMeta.svg === 'string' && logoMeta.svg.startsWith('<svg'), 'the logo card meta carries the markup');
+assert.equal(logoMeta.svg_bytes, logoMeta.svg.length);
+assert.match(logoMeta.summary, /3 sequences × 16 columns/, 'the summary states the alignment size');
+
+const logoView = panelCore.figureCardView(logoMeta);
+assert.equal(logoView.kind, 'figure', 'the card resolves the logo projection');
+assert.equal(logoView.svg, logoMeta.svg);
+assert.equal(logoView.svgPath, logoValue.svg_path);
+assert.equal(panelCore.figureCardSummary(logoView), logoMeta.summary);
+
+const grnaArgs = {
+  sequence: dnaFixture(320, 7),
+  map_path: at('grna-map.svg'),
+  save_path: at('grna-order.csv'),
+  max_guides: 5,
+};
+const grnaValue = await grnaTool.execute(grnaArgs, exec);
+assert.ok(grnaValue.guides.length > 0, 'the gRNA fixture yields at least one guide');
+const grnaMeta = grnaTool.output.presentationMeta(grnaArgs, grnaValue);
+assert.equal(grnaMeta.kind, 'molbio-figure');
+assert.equal(grnaMeta.figure, 'grna');
+assert.equal(grnaMeta.svg_path, grnaValue.map_path);
+assert.ok(typeof grnaMeta.svg === 'string' && grnaMeta.svg.startsWith('<svg'), 'the gRNA card carries the map markup');
+assert.ok(grnaMeta.guides.length >= 1 && grnaMeta.guides.length <= 5, 'the card carries at most five guide rows');
+assert.equal(grnaMeta.guides[0].sequence, grnaValue.guides[0].sequence);
+assert.equal(grnaMeta.csv_path, grnaValue.saved_to);
+assert.match(grnaMeta.summary, /SpCas9/, 'the summary names the Cas family');
+
+const grnaView = panelCore.figureCardView(grnaMeta);
+assert.equal(grnaView.kind, 'figure');
+assert.equal(grnaView.guides.length, grnaMeta.guides.length);
+assert.equal(grnaView.guides[0].offTargets, grnaValue.guides[0].off_target_count ?? 0);
+
+// A gRNA call WITHOUT a map still gets the ranked-guide table, with an
+// explanation for the absent picture rather than a blank card.
+const plainGrnaValue = await grnaTool.execute({ sequence: dnaFixture(320, 7), max_guides: 5 }, exec);
+const plainMeta = grnaTool.output.presentationMeta({ sequence: dnaFixture(320, 7) }, plainGrnaValue);
+assert.equal(plainMeta.svg_missing, true);
+const plainView = panelCore.figureCardView(plainMeta);
+assert.equal(plainView.kind, 'notice');
+assert.match(plainView.message, /No picture was requested/i);
+assert.ok(plainView.guides.length > 0, 'the table survives the missing picture');
+
+// ── figure-card fallbacks: never throw inside a transcript ──────────────────
+
+assert.equal(panelCore.figureCardView({ kind: 'molbio-map' }).kind, 'notice', 'a map meta is not a figure');
+assert.equal(panelCore.figureCardView(undefined).kind, 'notice');
+assert.equal(panelCore.figureCardView(null).kind, 'notice');
+assert.equal(panelCore.figureCardView('nonsense').kind, 'notice');
+assert.equal(panelCore.figureCardView([]).kind, 'notice');
+assert.equal(panelCore.figureCardView({ kind: 'molbio-figure', figure: 'unknown' }).kind, 'notice');
+const oversizedFigure = panelCore.figureCardView({
+  kind: 'molbio-figure',
+  figure: 'logo',
+  summary: 'Sequence logo',
+  svg_omitted: true,
+  svg_bytes: 900_000,
+  svg_path: at('big-logo.svg'),
+});
+assert.equal(oversizedFigure.kind, 'notice');
+assert.match(oversizedFigure.message, /too large/i);
+assert.equal(oversizedFigure.svgPath, at('big-logo.svg'));
+assert.equal(panelCore.figureCardView({ kind: 'molbio-figure', figure: 'logo', svg: '<div>hi</div>' }).kind, 'notice');
+const sanitized = panelCore.figureCardView({
+  kind: 'molbio-figure',
+  figure: 'grna',
+  summary: 's',
+  svg_missing: true,
+  guides: [null, 7, { sequence: 42 }, { sequence: 'ACGT', rank: 'x', start: 1.5 }, { sequence: 'ACGT', rank: 1 }, { sequence: 'ACGT', rank: 2 }, { sequence: 'ACGT', rank: 3 }, { sequence: 'ACGT', rank: 4 }],
+});
+assert.equal(sanitized.guides.length, 5, 'malformed rows are dropped and the list is capped at five');
+assert.equal(sanitized.guides[0].rank, 0, 'a non-integer rank degrades to 0 rather than being trusted');
+
+// ── the figure component: logo and gRNA render through the same card ────────
+
+const FigureCard = slots.registrations.find(
+  (entry) => entry.registration.name === 'tool.call.toolview' && entry.registration.key === 'molbio_sequence_logo',
+).component;
+assert.equal(typeof FigureCard, 'function', 'the figure card is registered for molbio_sequence_logo');
+
+globalThis.__molbioTestHooks = mount(FigureCard);
+const logoCard = globalThis.__molbioTestHooks;
+logoCard.setProps({ block: { kind: 'tool-result', callId: 'l1', isError: false, meta: logoMeta, content: [{ type: 'text', text: 'logo saved' }] }, inspect: undefined });
+await logoCard.render();
+const logoText = texts(logoCard.tree).join('\n');
+assert.ok(logoText.includes('Sequence logo · 3 sequences × 16 columns'), 'the logo card header summarises the alignment');
+assert.ok(logoText.includes(logoValue.svg_path), 'the logo card names the written file');
+const logoHosts = (function find(node, out = []) {
+  if (Array.isArray(node)) {
+    for (const child of node) find(child, out);
+    return out;
+  }
+  if (node !== null && typeof node === 'object' && node.props !== undefined) {
+    if (node.props.ref !== undefined && node.props.ref !== null) out.push(node);
+    find(node.props.children, out);
+  }
+  return out;
+})(logoCard.tree);
+assert.equal(logoHosts.length, 1, 'the logo card mounts one SVG host');
+assert.equal(logoHosts[0].props.ref.current.children.length, 1, 'and appended the parsed logo into it');
+logoCard.unmount();
+
+globalThis.__molbioTestHooks = mount(FigureCard);
+const grnaCard = globalThis.__molbioTestHooks;
+grnaCard.setProps({ block: { kind: 'tool-result', callId: 'g1', isError: false, meta: grnaMeta, content: [{ type: 'text', text: 'guides designed' }] }, inspect: undefined });
+await grnaCard.render();
+const grnaText = texts(grnaCard.tree).join('\n');
+assert.ok(grnaText.includes('SpCas9'), 'the gRNA card header names the family');
+assert.ok(grnaText.includes(grnaValue.guides[0].sequence), 'the gRNA card lists the top guide');
+assert.ok(grnaText.includes('Off-targets'), 'the gRNA card shows the guide table header');
+assert.ok(grnaText.includes(grnaValue.map_path), 'and the written map path');
+assert.ok(grnaText.includes(grnaValue.saved_to), 'and the ordering CSV path');
+grnaCard.unmount();
+
 await rm(shimPath, { force: true });
 await rm(entryPath, { force: true });
-console.log('map card checks passed (host projection -> card view -> rendered SVG)');
+console.log('tool card checks passed (map + logo/gRNA: host projection -> card view -> rendered SVG)');

package/test/preset-health.mjs

@@ -36,6 +36,7 @@
  */
 import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 // Re-exported for test/drift-probe.mjs, which drives the same reader against
@@ -101,6 +102,34 @@ function flattenRows(rows, at = '') {
   return found;
 }
 
+/**
+ * Resolve a row's specifier the way the Loader does, or say why it cannot.
+ *
+ * The Loader imports a package row BY SPECIFIER (`import.meta.resolve` anchored
+ * in the config project's scope, see `cordis-plugin-loader`), and Node enforces
+ * the target package's `exports` map on that specifier. `packageInstalled` only
+ * proves that a directory exists, so a row naming a SUBPATH the harness dropped
+ * used to pass this suite and then fail at preset mount — that is exactly how
+ * `@deepseek-ai/dsh-tool-subagent-control/list-agents` (removed in 0.2.2-rc.1,
+ * where `list_agents` moved into the control plugin itself) survived until a
+ * manual run against the new harness.
+ *
+ * Exported so `test/drift-probe.mjs` can drive it against a mutated specifier:
+ * a guard nobody has seen fail is not a guard (rules.md rule 9).
+ *
+ * @param {string} name the row's `name`.
+ * @param {string} harnessRoot the installed harness.
+ * @returns {string|undefined} a diagnostic, or undefined when it resolves.
+ */
+export function specifierProblem(name, harnessRoot) {
+  try {
+    createRequire(join(harnessRoot, 'package.json')).resolve(name);
+    return undefined;
+  } catch (error) {
+    return `specifier does not resolve: ${error?.code ?? error?.message ?? error}`;
+  }
+}
+
 /** Validate one row against its package's own `Config` schema. */
 async function checkRow(row, packages, harnessRoot, presetBase) {
   const id = typeof row.id === 'string' ? row.id : row.name;
@@ -118,6 +147,16 @@ async function checkRow(row, packages, harnessRoot, presetBase) {
       : { ...result, status: 'unresolvable', detail: `preset-relative module not found: ${target}` };
   }
 
+  // A bare package row is imported by SPECIFIER, so its `exports` map decides
+  // whether it mounts. Check that before looking for the package directory:
+  // `packageInstalled` walks up from the harness root and would happily report a
+  // package whose named subpath no longer exists. `cordis:*` rows name Loader
+  // builtins, not modules, so they are skipped here too.
+  if (!row.name.includes(':') && row.name !== selfName) {
+    const problem = specifierProblem(row.name, harnessRoot);
+    if (problem !== undefined) return { ...result, status: 'unresolvable', detail: problem };
+  }
+
   const pkgDir = row.name === selfName
     // The row names THIS package. `packageInstalled` walks up from the harness
     // root, where this package is not installed — but in the preset it is

package/test/smoke.mjs

@@ -1587,8 +1587,8 @@ function makeTemplate(n, seed = 42) {
 
 {
   // cross-intron primer design (fixture seeds chosen to pass the v12
-  // Primer3-style structural defaults)
-  const e1 = makeTemplate(120, 10);
+  // Primer3-style structural defaults under the corrected orientation)
+  const e1 = makeTemplate(120, 49);
   const e2 = makeTemplate(120, 14);
   const e3 = makeTemplate(120, 34);
   const genomic = e1 + makeTemplate(800, 29) + e2 + makeTemplate(800, 31) + e3;
@@ -1603,15 +1603,26 @@ function makeTemplate(n, seed = 42) {
   });
   assert.ok(out.pairs.length > 0, 'should find junction-spanning pairs');
   const pair = out.pairs[0];
-  assert.ok(pair.forward.junction_left >= 6 && pair.forward.junction_right >= 6);
-  assert.equal(pair.forward.exons.length, 2);
-  assert.equal(Math.abs(Number(pair.forward.exons[1]) - Number(pair.forward.exons[0])), 1);
+  // 0.23.0: the junction is carried by the REVERSE primer (the assay sits 5' of
+  // the junction); forward is upstream and inside one exon. The reverse sequence
+  // is the molecule to order, i.e. the reverse complement of its spliced site.
+  assert.ok(pair.reverse.junction_left >= 6 && pair.reverse.junction_right >= 6);
+  assert.equal(pair.reverse.exons.length, 2);
+  assert.equal(Math.abs(Number(pair.reverse.exons[1]) - Number(pair.reverse.exons[0])), 1);
   assert.ok(pair.genomic_amplicon_length >= 900);
   assert.ok(pair.spliced_amplicon.length >= 80 && pair.spliced_amplicon.length <= 200);
-  assert.ok(pair.reverse.exon !== Number(pair.forward.exons[1]));
+  assert.ok(pair.forward.exon >= 1 && pair.forward.exon < Number(pair.reverse.exons[1]), 'forward sits in an earlier exon than the reverse primer\'s downstream exon');
+  assert.ok(pair.forward.spliced_start < pair.reverse.spliced_start, 'F is upstream of R');
+  assert.equal(pair.forward.spliced_start, pair.spliced_amplicon.start, 'amplicon opens at the forward 5\' end');
+  assert.equal(pair.reverse.spliced_end, pair.spliced_amplicon.end, 'amplicon closes at the reverse 5\' end');
   const spliced = e1 + e2 + e3;
   assert.ok(spliced.includes(pair.forward.sequence), 'forward primer is a spliced-sequence substring');
-  assert.ok(spliced.includes(pair.reverse.sequence), 'reverse primer is a spliced-sequence substring');
+  assert.equal(
+    pair.reverse.sequence,
+    lib.reverseComplement(spliced.slice(pair.reverse.spliced_start - 1, pair.reverse.spliced_end)),
+    'reverse primer is the reverse complement of its spliced site (the molecule to order)',
+  );
+  assert.ok(pair.reverse.spliced_start <= 120 && pair.reverse.spliced_end > 120, 'the reverse primer straddles the exon 1/2 junction');
 }
 
 // ── v12: mismatch tolerance in primer design ────────────────────────────────
@@ -1782,10 +1793,24 @@ function makeTemplate(n, seed = 42) {
     assert.equal(primer.mismatch_count, primer.mismatches.length);
     for (const m of primer.mismatches) {
       assert.equal(m.primer_base, primer.sequence[m.position - 1]);
-      assert.equal(m.template_base, spliced[m.spliced_position - 1], 'spliced position maps to the transcript base');
+      // The perfect-match base is the transcript base for the forward primer and
+      // its COMPLEMENT for the reverse primer (which is reported as the molecule
+      // to order, i.e. the reverse complement of its spliced site).
+      const transcriptBase = spliced[m.spliced_position - 1];
+      assert.equal(m.template_base, isForward ? transcriptBase : lib.complement(transcriptBase), 'template_base is the perfect-match base on this strand');
       assert.equal(m.genomic_position, splicedToGenomic(m.spliced_position, exons), 'genomic position maps consistently');
       assert.ok(m.distance_from_3prime >= 1, 'no terminal-base mismatch in intron mode');
     }
+    // The reported molecule must equal its spliced site (forward) or that
+    // site's reverse complement (reverse) outside the reported mismatches.
+    const expected = isForward
+      ? spliced.slice(primer.spliced_start - 1, primer.spliced_end)
+      : lib.reverseComplement(spliced.slice(primer.spliced_start - 1, primer.spliced_end));
+    const positions = new Set(primer.mismatches.map((m) => m.position));
+    for (let i = 0; i < expected.length; i++) {
+      if (positions.has(i + 1)) continue;
+      assert.equal(primer.sequence[i], expected[i], 'reported primer equals its site outside the reported mismatches');
+    }
   }
 }
 
@@ -2133,8 +2158,10 @@ if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_
   assert.equal(plain.pairs[0].target_distance, undefined, 'no target_distance without target_position');
   await assert.rejects(() => run('molbio_design_primers', { template, target_position: 601 }), /outside the template/);
   await assert.rejects(() => run('molbio_design_primers', { template, target_penalty: -1 }), /target_penalty/);
-  // cross-intron design reports spliced-coordinate target distances too
-  const e1 = makeTemplate(120, 10);
+  // cross-intron design reports spliced-coordinate target distances too, and
+  // (0.23.0) measures each one from the primer's actual 3' end: the forward's
+  // highest coordinate and the reverse's LOWEST coordinate.
+  const e1 = makeTemplate(120, 49);
   const e2 = makeTemplate(120, 14);
   const e3 = makeTemplate(120, 34);
   const genomic = e1 + makeTemplate(800, 29) + e2 + makeTemplate(800, 31) + e3;
@@ -2143,6 +2170,8 @@ if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_
   assert.ok(intron.pairs.length > 0);
   for (const pair of intron.pairs) {
     assert.equal(pair.target_distance, Math.min(pair.forward.target_distance, pair.reverse.target_distance));
+    assert.equal(pair.forward.target_distance, Math.abs(pair.forward.spliced_end - 150), 'forward distance is from its 3\' end');
+    assert.equal(pair.reverse.target_distance, Math.abs(pair.reverse.spliced_start - 150), 'reverse distance is from its 3\' end');
     assert.ok(pair.forward.target_distance <= 359);
   }
 }
@@ -3323,6 +3352,7 @@ if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_
     'molbio_grna_design', 'molbio_qpcr_efficiency', 'molbio_plot', 'molbio_virtual_gel',
     'molbio_sequence_logo', 'molbio_helical_wheel', 'molbio_hydropathy_plot',
     'molbio_fastq_qc', 'molbio_phylogenetic_tree', 'molbio_pcr_simulate', 'molbio_gc_composition',
+    'molbio_protein_charge', 'molbio_dotplot',
   ];
   for (const toolName of pictureTools) {
     const tool = toolByName(toolName);
@@ -3330,7 +3360,7 @@ if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_
     assert.ok(Object.hasOwn(tool.output.schema.properties, 'image'), `${toolName} can report the attached image`);
     assert.ok(Object.hasOwn(tool.output.schema.properties, 'image_note'), `${toolName} can explain a missing image`);
   }
-  assert.equal(registered.filter((tool) => Object.hasOwn(tool.parameters.properties, 'attach_image')).length, 15, 'exactly the 15 picture tools — the report-only analysis tools are untouched');
+  assert.equal(registered.filter((tool) => Object.hasOwn(tool.parameters.properties, 'attach_image')).length, 17, 'exactly the 17 picture tools — the report-only analysis tools are untouched');
 
   // 9. Rendering text alone still works (the attachment must not break render).
   const logo = await runWith('molbio_sequence_logo', { alignment: ['ACGTACGT', 'ACGTTCGT'], attach_image: true }, routedExec);
@@ -3447,6 +3477,22 @@ if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_
   assert.equal(adapterUncapped.adapter.per_base_percent[23], 12.5, 'through its last base at position 24');
   assert.equal(adapterUncapped.adapter.per_base_percent[24], 0, 'and stops there');
 
+  // 6b. The Small RNA 5' entry is documented as RNA; the table is DNA-normalized
+  // so BOTH the forward molecule and its reverse complement are detectable in
+  // cDNA reads. Before the fix only one of these two reads matched.
+  const smallRna = 'GTTCAGAGTTCTACAGTCCGACGATC';
+  const smallRnaFastq = [
+    '@rna_f', 'ACGT' + smallRna + 'ACGT', '+', 'I'.repeat(8 + smallRna.length),
+    '@rna_r', 'ACGT' + reverseComplementOf(smallRna) + 'ACGT', '+', 'I'.repeat(8 + smallRna.length),
+    '',
+  ].join('\n');
+  const qcRna = await run('molbio_fastq_qc', { fastq: smallRnaFastq, adapter_scan_reads: 10, max_plot_bases: 100 });
+  assert.deepEqual(
+    qcRna.adapter.hits.map((hit) => [hit.name, hit.reads, hit.percent]),
+    [["Illumina Small RNA 5'", 2, 100]],
+    'the DNA-normalized Small RNA adapter matches the forward and reverse-complement reads',
+  );
+
   // 7. Over-representation names the threshold that produced it — and on a
   //    sample this small that threshold legitimately yields nothing, because
   //    the bar is max(20 reads, 0.1% of the sample).
@@ -4187,6 +4233,237 @@ if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_
   await assert.rejects(() => run('molbio_gc_composition', { sequence: 'ACGTACGTAC', window: 5 }), /window must be an integer of at least 10/);
 }
 
+// ── 0.23.0: protein charge vs pH ───────────────────────────────────────────
+{
+  // KKDD has two positive and two negative side chains plus the termini, so the
+  // two ends of the curve are exactly +3 and -3 (within the 1e-4 sampling
+  // rounding) and the pI is the zero crossing between them.
+  const sequence = 'KKDD';
+  const props = await run('molbio_protein_props', { sequence });
+  const out = await run('molbio_protein_charge', { sequence, output_path: at('charge.svg') });
+  assert.equal(out.length, 4);
+  assert.equal(out.pka_set, 'bjellqvist');
+  assert.equal(out.pka_label, 'Bjellqvist 1993');
+  assert.equal(out.pI, props.pi, 'the default pK set matches molbio_protein_props');
+  assert.equal(out.points.length, 29);
+  assert.equal(out.points[0].ph, 0);
+  assert.equal(out.points[28].ph, 14);
+  assert.ok(Math.abs(out.points[0].charge - 3) < 0.01, 'pH 0: N-terminus + 2 Lys = +3');
+  assert.ok(Math.abs(out.points[28].charge + 3) < 0.01, 'pH 14: C-terminus + 2 Asp = -3');
+  assert.ok(Math.abs(out.charge_at_7_4 + 0.0591) < 0.01);
+  // The pI must lie between the two sampled pH values whose charges bracket 0.
+  let bracketed = false;
+  for (let i = 1; i < out.points.length; i++) {
+    const a = out.points[i - 1];
+    const b = out.points[i];
+    if ((a.charge >= 0 && b.charge <= 0) || (a.charge <= 0 && b.charge >= 0)) {
+      assert.ok(out.pI >= a.ph && out.pI <= b.ph, 'pI is the zero crossing');
+      bracketed = true;
+      break;
+    }
+  }
+  assert.ok(bracketed, 'the sampled curve changes sign');
+  assert.ok(memFs.files.get(at('charge.svg')).includes('<svg'), 'the titration SVG is written');
+
+  // A different pK table is a different answer, and it says which one it used.
+  const emboss = await run('molbio_protein_charge', { sequence, pka_set: 'emboss', output_path: at('charge-emboss.svg') });
+  assert.equal(emboss.pka_set, 'emboss');
+  assert.equal(emboss.pka_label, 'EMBOSS Epk.dat');
+  assert.notEqual(emboss.pI, out.pI, 'the pK set changes the pI, so the set name must travel with it');
+
+  // Errors: range checks in the module, enum check by the argument schema.
+  await assert.rejects(() => run('molbio_protein_charge', { sequence, ph_min: 15 }), /ph_min/);
+  await assert.rejects(() => run('molbio_protein_charge', { sequence, ph_min: 8, ph_max: 7 }), /greater than ph_min/);
+  await assert.rejects(() => run('molbio_protein_charge', { sequence, steps: 1 }), /steps/);
+  await assert.rejects(() => run('molbio_protein_charge', { sequence, pka_set: 'nonsense' }), /must be one of/);
+  await assert.rejects(() => run('molbio_protein_charge', { sequence: 'ACGTX' }), /invalid character/);
+}
+
+// ── 0.23.0: sequence dotplot ────────────────────────────────────────────────
+{
+  // Two 12 bp copies of the same word separated by an 8 bp T stretch: with a
+  // 4-mer word every k-mer in one copy matches the same k-mer in the other.
+  const sequence = 'ACGTACGTACGT' + 'TTTTTTTT' + 'ACGTACGTACGT';
+  const out = await run('molbio_dotplot', { sequence, word: 4, output_path: at('dot.svg') });
+  assert.equal(out.length, 32);
+  assert.equal(out.word, 4);
+  assert.equal(out.mode, 'both');
+  assert.equal(out.direct_matches, 133);
+  assert.equal(out.inverted_matches, 40);
+  assert.equal(out.direct_cells, out.direct_matches, 'this small fixture is under one dot per grid cell');
+  assert.equal(out.truncated, false);
+  assert.equal(out.plot_truncated, false);
+  const dotSvg = memFs.files.get(at('dot.svg'));
+  assert.ok(dotSvg.includes('<svg'), 'the dotplot SVG is written');
+  // Layout guard: the x-axis title and the legend both live BELOW the plot but
+  // inside the panel. The first version put them on/outside the bottom border
+  // (720 px canvas, 628 px square plot); a plain "contains <svg>" check would
+  // pass while the footer was clipped, so assert the vertical budget instead.
+  const dotView = /viewBox="0 0 (\d+) (\d+)"/.exec(dotSvg);
+  assert.ok(dotView !== null, 'the dotplot declares a viewBox');
+  const dotHeight = Number(dotView[2]);
+  const dotTexts = [...dotSvg.matchAll(/<text ([^>]*)>([^<]*)<\/text>/g)]
+    .map((match) => ({ attrs: match[1], text: match[2] }));
+  const yOf = (attrs) => Number(/y="([0-9.]+)"/.exec(attrs)[1]);
+  const xTitle = dotTexts.find((node) => node.text === 'position (bp)' && !node.attrs.includes('transform='));
+  const directLegend = dotTexts.find((node) => node.text === 'direct repeat');
+  assert.ok(xTitle !== undefined, 'the x axis is titled');
+  assert.ok(directLegend !== undefined, 'the direct-repeat legend is drawn');
+  assert.ok(yOf(xTitle.attrs) <= dotHeight - 30, 'the x-axis title is not sitting on the bottom border');
+  assert.ok(yOf(directLegend.attrs) <= dotHeight - 20, 'the legend is inside the canvas');
+  assert.ok(yOf(directLegend.attrs) > yOf(xTitle.attrs), 'the legend sits below the x-axis title, not on top of it');
+
+  // Inverted-only mode does not report direct matches, and an inverted repeat of
+  // the first block shows up as 12 exact 4-mer hits.
+  const inverted = await run('molbio_dotplot', { sequence: 'AAAACCCC' + 'GGGGTTTT', word: 4, mode: 'inverted' });
+  assert.equal(inverted.direct_matches, 0);
+  assert.equal(inverted.inverted_matches, 12);
+  assert.equal(inverted.inverted_cells, 12);
+
+  // Ambiguous k-mers are skipped and counted, never silently matched.
+  const ambiguous = await run('molbio_dotplot', { sequence: 'ACGTNNNNACGTACGT', word: 4 });
+  assert.equal(ambiguous.ambiguous_bases, 7, 'every 4-mer window touching the N run is skipped');
+
+  // The work cap turns a homopolymer into a bounded, explicitly truncated result.
+  const capped = await run('molbio_dotplot', { sequence: 'A'.repeat(600), word: 4 });
+  assert.equal(capped.truncated, true, 'the scan is capped rather than hanging');
+  assert.ok(capped.direct_matches <= 200_000);
+
+  // Determinism: the same input produces the same counts.
+  const again = await run('molbio_dotplot', { sequence, word: 4 });
+  assert.deepEqual(
+    [again.direct_matches, again.inverted_matches, again.direct_cells, again.inverted_cells],
+    [out.direct_matches, out.inverted_matches, out.direct_cells, out.inverted_cells],
+  );
+
+  await assert.rejects(() => run('molbio_dotplot', { sequence, word: 3 }), /word/);
+  await assert.rejects(() => run('molbio_dotplot', { sequence, word: 13 }), /word/);
+  await assert.rejects(() => run('molbio_dotplot', { sequence: 'ACGTACGT', word: 8 }), /at least/);
+  await assert.rejects(() => run('molbio_dotplot', { sequence, mode: 'diagonal' }), /must be one of/);
+}
+
+
+// ── 0.24.0: contamination screening + FASTQ trimming ─────────────────────────
+{
+  // Two known embedded signatures: a pUC/pBR322 origin fragment at the start and
+  // the Illumina Universal adapter at the end. The middle is a neutral repeat.
+  const contaminated = 'GTTTGCCGGATCAAGAGCTACCAACTCTTT' + 'ACGT'.repeat(20) + 'AGATCGGAAGAG';
+  const screen = await run('molbio_contamination_screen', { sequence: contaminated });
+  assert.equal(screen.input_type, 'sequence');
+  assert.equal(screen.total_entries, 1);
+  assert.equal(screen.hit_count, 2);
+  assert.deepEqual(screen.hits.map((hit) => hit.name), ['Illumina Universal', 'pUC/pBR322 origin']);
+  const pucHit = screen.hits.find((hit) => hit.name === 'pUC/pBR322 origin');
+  assert.deepEqual(
+    [pucHit.kind, pucHit.category, pucHit.example.start, pucHit.example.end, pucHit.example.strand, pucHit.best_mismatches],
+    ['vector', 'origin', 1, 30, '+', 0],
+  );
+  const adapterHit = screen.hits.find((hit) => hit.name === 'Illumina Universal');
+  assert.deepEqual([adapterHit.example.start, adapterHit.example.end, adapterHit.example.strand], [111, 122, '+']);
+
+  // A reverse-strand hit is reported on the forward coordinate system.
+  const t7 = 'TAATACGACTCACTATAGGG';
+  const reverse = await run('molbio_contamination_screen', { sequence: 'ACGT'.repeat(10) + reverseComplementOf(t7) });
+  const t7Hit = reverse.hits.find((hit) => hit.name === 'pET T7 promoter');
+  assert.equal(t7Hit.example.strand, '-');
+  assert.equal(t7Hit.example.start, 41);
+
+  // One mismatch is invisible at max_mismatches 0 and found at 1. The mutated
+  // pUC signature still leaves the adapter hit in place.
+  const mutated = contaminated.replace('GTTTGCCGGATCAAGAGCTACCAACTCTTT', 'GTTTGCCGGATCAAGAGCTACCAACTCTTA');
+  const exact = await run('molbio_contamination_screen', { sequence: mutated });
+  assert.equal(exact.hits.some((hit) => hit.name === 'pUC/pBR322 origin'), false);
+  const loose = await run('molbio_contamination_screen', { sequence: mutated, max_mismatches: 1 });
+  const loosePuc = loose.hits.find((hit) => hit.name === 'pUC/pBR322 origin');
+  assert.equal(loosePuc.best_mismatches, 1);
+  assert.equal(loosePuc.example.mismatches, 1);
+
+  // FASTA/FASTQ inputs are scanned entry by entry, and max_reads caps the work.
+  memFs.files.set(at('contam.fa'), '>a\n' + contaminated + '\n');
+  const fromFasta = await run('molbio_contamination_screen', { path: at('contam.fa') });
+  assert.equal(fromFasta.input_type, 'fasta');
+  assert.equal(fromFasta.scanned_entries, 1);
+  memFs.files.set(at('contam.fq'), '@a\n' + contaminated + '\n+\n' + 'I'.repeat(contaminated.length) + '\n');
+  const fromFastq = await run('molbio_contamination_screen', { path: at('contam.fq') });
+  assert.equal(fromFastq.input_type, 'fastq');
+  assert.equal(fromFastq.hits.length, 2);
+  const capped = await run('molbio_contamination_screen', { path: at('contam.fa'), max_reads: 1 });
+  assert.equal(capped.scanned_entries, 1);
+  assert.equal(capped.truncated, false);
+
+  await assert.rejects(() => run('molbio_contamination_screen', { sequence: contaminated, path: at('contam.fa') }), /exactly one/);
+  await assert.rejects(() => run('molbio_contamination_screen', {}), /exactly one/);
+  await assert.rejects(() => run('molbio_contamination_screen', { sequence: contaminated, kinds: 'plasmid' }), /must be one of/);
+
+  // ── FASTQ trim: known per-read outcomes ─────────────────────────────────
+  const trimReadsInput = [
+    '@r1', 'ACGT'.repeat(10), '+', 'I'.repeat(30) + '!'.repeat(10),
+    '@r2', 'ACGT'.repeat(7) + 'AC' + 'AGATCGGAAGAG' + 'TTTTT', '+', 'I'.repeat(47),
+    '@r3', 'ACGT'.repeat(5) + 'G'.repeat(10), '+', 'I'.repeat(30),
+    '@r4', 'ACGT'.repeat(2) + 'AC', '+', 'I'.repeat(10),
+    '',
+  ].join('\n');
+  memFs.files.set(at('trim-in.fq'), trimReadsInput);
+  const trim = await run('molbio_fastq_trim', {
+    path: at('trim-in.fq'),
+    output_path: at('trim-out.fq'),
+    min_quality: 30,
+    quality_window: 3,
+    poly_g: true,
+    adapter: 'AGATCGGAAGAG',
+    min_length: 20,
+  });
+  assert.equal(trim.reads_in, 4);
+  assert.equal(trim.reads_out, 3);
+  assert.equal(trim.bases_in, 127);
+  assert.equal(trim.bases_out, 80);
+  assert.equal(trim.trimmed_reads, 3);
+  assert.equal(trim.dropped_reads, 1);
+  assert.deepEqual(trim.trim_counts, { quality: 1, adapter: 1, poly_g: 1, poly_a: 0, primer: 0 });
+  assert.deepEqual(trim.drop_counts, { length: 1, n: 0 });
+  assert.equal(trim.output_format, 'fastq');
+  assert.equal(trim.saved_to, at('trim-out.fq'));
+  const trimmedText = memFs.files.get(at('trim-out.fq'));
+  assert.equal(trimmedText.split('\n').filter((line) => line.startsWith('@')).length, 3);
+  const trimmedLines = trimmedText.trimEnd().split('\n');
+  assert.equal(trimmedLines.length, 12, 'three four-line FASTQ records');
+  for (let index = 0; index < trimmedLines.length; index += 4) {
+    assert.equal(trimmedLines[index + 2], '+');
+    assert.equal(trimmedLines[index + 1].length, trimmedLines[index + 3].length, 'quality length follows the trimmed sequence');
+  }
+  assert.ok(trimmedLines.includes('ACGTACGTACGTACGTACGT'), 'r3 lost exactly its 10-base poly-G tail');
+
+  const fastaTrim = await run('molbio_fastq_trim', {
+    path: at('trim-in.fq'),
+    output_path: at('trim-out.fa'),
+    output_format: 'fasta',
+    min_quality: 30,
+    quality_window: 3,
+    poly_g: true,
+    adapter: 'AGATCGGAAGAG',
+    min_length: 20,
+  });
+  assert.equal(fastaTrim.output_format, 'fasta');
+  assert.ok(memFs.files.get(at('trim-out.fa')).startsWith('>r1\n'));
+
+  // Phred+64: 'h' is Q40 under that encoding; a high-quality read survives.
+  memFs.files.set(at('trim64.fq'), '@p64\nACGTACGTACGT\n+\nhhhhhhhhhhhh\n');
+  const phred64 = await run('molbio_fastq_trim', {
+    path: at('trim64.fq'),
+    output_path: at('trim64-out.fq'),
+    phred: 64,
+    min_quality: 30,
+    quality_window: 3,
+  });
+  assert.equal(phred64.reads_out, 1);
+  assert.equal(phred64.trim_counts.quality, 0);
+
+  await assert.rejects(() => run('molbio_fastq_trim', { path: at('trim-in.fq') }), /output_path/);
+  await assert.rejects(() => run('molbio_fastq_trim', { path: at('seqs.fa'), output_path: at('x.fq') }), /FASTA/);
+  await assert.rejects(() => run('molbio_fastq_trim', { path: at('trim-in.fq'), output_path: at('x.fq'), min_quality: 61 }), /min_quality/);
+  await assert.rejects(() => run('molbio_fastq_trim', { path: at('trim-in.fq'), output_path: at('x.fq'), adapter: 'ACGTX' }), /invalid/);
+}
+
 // ── plugin surface ──────────────────────────────────────────────────────────
 
 assert.equal(plugin.name, 'dsh-molbio-tools');