dsh-molbio-tools 0.22.2 → 0.24.0

package/index.mjs

@@ -2,9 +2,9 @@
  * dsh-molbio-tools/index.mjs
  *
  * DeepSeek Harness Cordis plugin: molecular-biology computation tools for the
- * model. Zero runtime dependencies — the only import is the sibling lib.mjs —
- * so the package is a pair of files that travel with an agent preset and can
- * be referenced by a relative plugin row (see README.md).
+ * model. Zero runtime dependencies — every import is a sibling module of this
+ * package — so the toolset travels with an agent preset and can be referenced
+ * by a package-name row (see README.md and rules.md rule 1).
  *
  * Every tool is pure computation: deterministic, no network, no filesystem.
  * The plugin publishes no service, so the preset row needs no isolate realm.
@@ -50,6 +50,8 @@ import {
 } from './cloning.mjs';
 import { readTraceFromBytes, verifySanger } from './sanger.mjs';
 import { CODON_HOSTS, codonOptimize, peptideDigest, proteinProperties } from './protein.mjs';
+import { chargeCurve, renderChargeCurve } from './protein-charge.mjs';
+import { dotplot, renderDotplot } from './dotplot.mjs';
 import { linearFit, renderBarChart, renderGel, renderScatterChart } from './plot.mjs';
 import {
   SERIES_COLORS,
@@ -65,7 +67,7 @@ import {
   renderVolcanoPlot,
   resolveTable,
 } from './charts.mjs';
-import { entryStats, parseFasta, parseFastq, toFasta } from './seqio.mjs';
+import { entryStats, parseFasta, parseFastq, toFasta, toFastq } from './seqio.mjs';
 import { addExperiment, addProtocol, loadRecords, recordPath, saveRecords, updateProtocol } from './records.mjs';
 import { toBibtex } from './papers.mjs';
 import { parseXml } from './snapgene.mjs';
@@ -123,6 +125,8 @@ import {
 import { openDefaultViewer } from './view.mjs';
 import { renderSvgToPng } from './svgpng.mjs';
 import { fastqQcReport, renderFastqQcReport } from './fastq-qc.mjs';
+import { screenContamination } from './contamination.mjs';
+import { trimFastq } from './fastq-trim.mjs';
 import { CODON_FREQUENCIES, codonUsageAnalysis } from './codon.mjs';
 import {
   DISTANCE_MODELS,
@@ -2140,7 +2144,7 @@ const plasmidMapTool = (ctx) => define({
   },
   // The map card in the transcript/panel reads this meta (see mapCardMeta).
   presentationMeta(_args, value) {
-    return mapCardMeta(value, rememberedMapSvg(value.svg_path));
+    return mapCardMeta(value, cardSvgFor(value.svg_path));
   },
   async execute(args, exec) {
     const sequence = normalizeSequence(args.sequence, 'plasmid sequence');
@@ -2182,7 +2186,7 @@ const plasmidMapTool = (ctx) => define({
       gc_skew: args.gc_skew === true,
     });
     const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, name);
-    rememberMapSvg(file, svg);
+    rememberCardSvg(file, svg);
     return mergeAttachedImage({
       svg_path: file,
       name,
@@ -2334,7 +2338,7 @@ const plasmidMapFileTool = (ctx) => define({
   },
   // The map card in the transcript/panel reads this meta (see mapCardMeta).
   presentationMeta(_args, value) {
-    return mapCardMeta(value, rememberedMapSvg(value.svg_path));
+    return mapCardMeta(value, cardSvgFor(value.svg_path));
   },
   async execute(args, exec) {
     const lower = args.path.toLowerCase();
@@ -2374,7 +2378,7 @@ const plasmidMapFileTool = (ctx) => define({
       gc_skew: args.gc_skew === true,
     });
     const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, name);
-    rememberMapSvg(file, svg);
+    rememberCardSvg(file, svg);
     return mergeAttachedImage({
       svg_path: file,
       name,
@@ -2423,22 +2427,40 @@ function mapCardMeta(value, svg) {
 }
 
 /**
- * Markup of the most recent maps, keyed by written path, so the card's
+ * Build the meta a figure card reads (sequence logo, gRNA map). Shared by both
+ * tools so the browser half has one shape to validate: `summary` is the header
+ * line, `extra` carries bounded presentation rows, and the markup travels only
+ * when it fits `CARD_SVG_MAX_BYTES`.
+ */
+function figureCardMeta({ figure, summary, svgPath, extra = {} }, svg) {
+  return {
+    kind: 'molbio-figure',
+    figure,
+    summary,
+    svg_path: svgPath,
+    svg_bytes: svg.length,
+    ...extra,
+    ...svg.length === 0 ? { svg_missing: true } : svg.length <= CARD_SVG_MAX_BYTES ? { svg } : { svg_omitted: true },
+  };
+}
+
+/**
+ * Markup of the most recent written figures, keyed by path, so a card's
  * projection never has to read a file back. Bounded on both axes — a handful of
- * maps, each at most `CARD_SVG_MAX_BYTES` — because this is a module-level
+ * figures, each at most `CARD_SVG_MAX_BYTES` — because this is a module-level
  * cache in a long-lived host process, not a store.
  */
-const recentMapSvg = new Map();
+const recentCardSvg = new Map();
 
-function rememberMapSvg(svgPath, svg) {
-  if (recentMapSvg.has(svgPath)) recentMapSvg.delete(svgPath);
-  recentMapSvg.set(svgPath, svg.length <= CARD_SVG_MAX_BYTES ? svg : '');
-  while (recentMapSvg.size > 8) recentMapSvg.delete(recentMapSvg.keys().next().value);
+function rememberCardSvg(svgPath, svg) {
+  if (recentCardSvg.has(svgPath)) recentCardSvg.delete(svgPath);
+  recentCardSvg.set(svgPath, svg.length <= CARD_SVG_MAX_BYTES ? svg : '');
+  while (recentCardSvg.size > 8) recentCardSvg.delete(recentCardSvg.keys().next().value);
 }
 
 /** The markup remembered for one written map ('' when it was too large or is gone). */
-function rememberedMapSvg(svgPath) {
-  return recentMapSvg.get(svgPath) ?? '';
+function cardSvgFor(svgPath) {
+  return recentCardSvg.get(svgPath) ?? '';
 }
 
 // ── cross-intron primer design ──────────────────────────────────────────────
@@ -2449,7 +2471,7 @@ const INTRON_MISMATCH_SCHEMA = {
   required: ['position', 'template_base', 'primer_base', 'spliced_position', 'genomic_position', 'distance_from_3prime'],
   properties: {
     position: { type: 'integer', description: '1-based position of the mismatch in the primer (5\'→3\').' },
-    template_base: { type: 'string', description: 'The base a perfectly matching primer would carry at this position on the spliced transcript.' },
+    template_base: { type: 'string', description: 'The base a perfectly matching primer would carry at this position: the spliced-transcript base for the forward primer, its complement for the reverse primer (which is reported as the molecule to order).' },
     primer_base: { type: 'string', description: 'The base the reported primer actually carries (primer_base !== template_base marks a real mismatch).' },
     spliced_position: { type: 'integer', description: '1-based position on the spliced transcript.' },
     genomic_position: { type: 'integer', description: '1-based position on the genomic sequence.' },
@@ -2501,7 +2523,7 @@ const INTRON_PRIMER_SCHEMA = {
 
 const intronPrimersTool = (ctx) => define({
   name: 'molbio_design_intron_primers',
-  description: 'Design qPCR primer pairs where the forward primer spans an exon-exon junction (>= min_junction_bases on each side) so genomic DNA cannot be amplified, and the reverse primer sits in a different exon. Provide the genomic sequence and the exon spans (1-based, inclusive). min_genomic_span enforces a minimal genomic distance between the primers (making gDNA amplification impossible or easily detectable). Coordinates come back both on the spliced transcript and on the genomic sequence. v12: Primer3-style structural filters (self-complementarity alignment scores, hairpin/dimer folding Tm at 47 °C defaults, end stability/end GC, GC clamp levels); pass max_mismatches > 0 to allow mismatched primers (never on the 3\'-terminal base) with spliced+genomic mismatch reports; pass check_mispriming: true to reject/penalize non-specific 3\'-tail annealing on the transcript.',
+  description: 'Design qPCR primer pairs where ONE primer spans an exon-exon junction (>= min_junction_bases on each side) so genomic DNA cannot be amplified. In the returned pair the junction is carried by the REVERSE primer (the assay sits 5\' of the junction): the forward primer is upstream inside a single exon, and the reverse sequence is the molecule to order (the reverse complement of its spliced site), so F is upstream of R and the pair amplifies as printed. Provide the genomic sequence and the exon spans (1-based, inclusive). min_genomic_span enforces a minimal genomic distance between the primers (making gDNA amplification impossible or easily detectable). Coordinates come back both on the spliced transcript and on the genomic sequence. v12: Primer3-style structural filters (self-complementarity alignment scores, hairpin/dimer folding Tm at 47 °C defaults, end stability/end GC, GC clamp levels); pass max_mismatches > 0 to allow mismatched primers (never on the 3\'-terminal base) with spliced+genomic mismatch reports; pass check_mispriming: true to reject/penalize non-specific 3\'-tail annealing on the transcript.',
   parameters: {
     type: 'object',
     required: ['exons'],
@@ -2621,7 +2643,7 @@ const intronPrimersTool = (ctx) => define({
     }
     const lines = [
       `Tm model conditions: ${value.conditions.na_mm} mM Na+ / ${value.conditions.mg_mm} mM Mg2+ / ${value.conditions.dntp_mm} mM dNTP / ${value.conditions.primer_nm} nM primer (SantaLucia 1998 NN — an estimate).`,
-      `${value.pairs.length} candidate pair(s); the forward primer spans an exon-exon junction (genomic DNA will not amplify):`,
+      `${value.pairs.length} candidate pair(s); the REVERSE primer spans an exon-exon junction, so genomic DNA will not amplify (forward is upstream of it):`,
     ];
     const mismatchLine = (label, primer) => {
       if (primer.mismatch_count > 0) {
@@ -2641,8 +2663,8 @@ const intronPrimersTool = (ctx) => define({
     };
     for (const [index, pair] of value.pairs.entries()) {
       lines.push(`#${index + 1} spliced amplicon ${pair.spliced_amplicon.start}-${pair.spliced_amplicon.end} (${pair.spliced_amplicon.length} bp), genomic span ${pair.genomic_amplicon_length} bp${pair.target_distance !== undefined ? `, nearer 3' end ${pair.target_distance} spliced bp from target_position` : ''}, penalty ${pair.penalty}`);
-      lines.push(`  F ${pair.forward.sequence}  (spliced ${pair.forward.spliced_start}-${pair.forward.spliced_end}; genomic ${pair.forward.genomic_start}-${pair.forward.genomic_end}; exons ${pair.forward.exons.join('/')}, junction ${pair.forward.junction_left}+${pair.forward.junction_right} bp; Tm ${pair.forward.tm} °C, self ${pair.forward.self_any}/${pair.forward.self_end}, hairpin ${pair.forward.hairpin_tm} °C)`);
-      lines.push(`  R ${pair.reverse.sequence}  (spliced ${pair.reverse.spliced_start}-${pair.reverse.spliced_end}; genomic ${pair.reverse.genomic_start}-${pair.reverse.genomic_end}; exon ${pair.reverse.exon}; Tm ${pair.reverse.tm} °C, self ${pair.reverse.self_any}/${pair.reverse.self_end}, hairpin ${pair.reverse.hairpin_tm} °C)`);
+      lines.push(`  F ${pair.forward.sequence}  (spliced ${pair.forward.spliced_start}-${pair.forward.spliced_end}; genomic ${pair.forward.genomic_start}-${pair.forward.genomic_end}; exon ${pair.forward.exon}; Tm ${pair.forward.tm} °C, self ${pair.forward.self_any}/${pair.forward.self_end}, hairpin ${pair.forward.hairpin_tm} °C)`);
+      lines.push(`  R ${pair.reverse.sequence}  (spliced ${pair.reverse.spliced_start}-${pair.reverse.spliced_end}; genomic ${pair.reverse.genomic_start}-${pair.reverse.genomic_end}; exons ${pair.reverse.exons.join('/')}, junction ${pair.reverse.junction_left}+${pair.reverse.junction_right} bp; Tm ${pair.reverse.tm} °C, self ${pair.reverse.self_any}/${pair.reverse.self_end}, hairpin ${pair.reverse.hairpin_tm} °C)`);
       mismatchLine('F', pair.forward);
       mismatchLine('R', pair.reverse);
       misprimingLine('F', pair.forward);
@@ -3524,6 +3546,141 @@ const proteinPropsTool = define({
   },
 });
 
+const proteinChargeTool = (ctx) => define({
+  name: 'molbio_protein_charge',
+  description: 'Plot a protein\'s net charge across a pH range and report the isoelectric point on the same curve (Henderson-Hasselbalch summation over the terminal groups, K/R/H positive and D/E/C/Y negative). pka_set selects the pK table: bjellqvist (the set molbio_protein_props uses, so the pI matches) or emboss (the Epk.dat values). The SVG is written to the workspace and opened with the OS default viewer (auto_view, default true); the sampled curve and the charge at pH 7.4 are returned too. pI is an estimate and is only meaningful together with the named pK set.',
+  parameters: {
+    type: 'object',
+    required: ['sequence'],
+    properties: {
+      sequence: requiredString('Protein sequence (one-letter amino acid codes).'),
+      pka_set: { type: 'string', enum: ['bjellqvist', 'emboss'], description: 'pK table: bjellqvist (default, matches molbio_protein_props) or emboss (Epk.dat).' },
+      ph_min: { type: 'number', description: 'Lowest pH sampled (0-14, default 0).' },
+      ph_max: { type: 'number', description: 'Highest pH sampled (0-14, default 14).' },
+      steps: { type: 'integer', description: 'Number of sampled points including both ends (2-141, default 29 = 0.5 pH).' },
+      title: { type: 'string', description: 'Title drawn on the SVG (default "Net charge vs pH").' },
+      output_path: { type: 'string', description: 'Optional SVG file path; default protein-charge.svg in the session workspace.' },
+      auto_view: { type: 'boolean', description: 'Open the SVG automatically with the OS default application (default true).' },
+      ...ATTACH_IMAGE_PARAM,
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['length', 'pka_set', 'pka_label', 'pI', 'charge_at_7_4', 'charge_min', 'charge_max', 'ph_min', 'ph_max', 'steps', 'points', 'svg_path', 'auto_viewed'],
+    properties: {
+      length: { type: 'integer' },
+      pka_set: { type: 'string', enum: ['bjellqvist', 'emboss'] },
+      pka_label: { type: 'string' },
+      pI: { type: 'number', description: 'Isoelectric point on the sampled pK set.' },
+      charge_at_7_4: { type: 'number', description: 'Net charge at pH 7.4 (e).' },
+      charge_min: { type: 'number' },
+      charge_max: { type: 'number' },
+      ph_min: { type: 'number' },
+      ph_max: { type: 'number' },
+      steps: { type: 'integer' },
+      points: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['ph', 'charge'],
+          properties: {
+            ph: { type: 'number' },
+            charge: { type: 'number' },
+          },
+        },
+      },
+      svg_path: { type: 'string' },
+      auto_viewed: { type: 'boolean' },
+      image: ATTACHED_IMAGE_SCHEMA,
+      image_note: { type: 'string' },
+    },
+  },
+  render(value) {
+    const direction = value.charge_at_7_4 > 0 ? 'net positive' : value.charge_at_7_4 < 0 ? 'net negative' : 'neutral';
+    return [
+      value.length + ' aa · ' + value.pka_label + ' pK set · pI ' + value.pI + ' · charge at pH 7.4 ' + value.charge_at_7_4 + ' e (' + direction + ')',
+      'Curve over pH ' + value.ph_min + '-' + value.ph_max + ' (' + value.steps + ' points; range ' + value.charge_min + ' .. ' + value.charge_max + ' e), SVG written to ' + value.svg_path + (value.auto_viewed === true ? ' and opened automatically' : '') + '.',
+      'Henderson-Hasselbalch estimate: the pI belongs to the named pK set and is not interchangeable with another calculator.',
+      imageNote(value).trim(),
+    ].filter((line) => line !== '').join('\n');
+  },
+  async execute(args, exec) {
+    const curve = chargeCurve(args.sequence, {
+      pkaSet: args.pka_set ?? 'bjellqvist',
+      phMin: args.ph_min,
+      phMax: args.ph_max,
+      steps: args.steps,
+    });
+    const svg = renderChargeCurve(curve, { title: args.title });
+    const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, 'protein-charge.svg');
+    return mergeAttachedImage({ ...curve, svg_path: file, auto_viewed: viewed }, attached);
+  },
+});
+
+const dotplotTool = (ctx) => define({
+  name: 'molbio_dotplot',
+  description: 'Compute and draw a self-comparison dotplot of a DNA sequence by exact word matching: a black cell at (i,j) means the k-mer at i equals the k-mer at j (direct repeat); a red cell means it equals the REVERSE COMPLEMENT of the k-mer at j (inverted repeat). word defaults to 8 (4-12); lower words find shorter repeats and produce more dots. The plot is binned to a fixed grid so a repetitive sequence cannot produce an enormous file; direct/inverted match counts and any scan/plot caps are reported. The SVG is written and opened with the OS default viewer (auto_view, default true). Exact k-mer view — not a windowed identity/scoring dotplot.',
+  parameters: {
+    type: 'object',
+    required: ['sequence'],
+    properties: {
+      sequence: requiredString('DNA sequence (IUPAC; ambiguous k-mers are skipped and counted).'),
+      word: { type: 'integer', description: 'Word (k-mer) length, 4-12 (default 8).' },
+      mode: { type: 'string', enum: ['both', 'direct', 'inverted'], description: 'Which repeats to plot: both (default), direct only, or inverted only.' },
+      title: { type: 'string', description: 'Title drawn on the SVG (default "Sequence dotplot").' },
+      output_path: { type: 'string', description: 'Optional SVG file path; default dotplot.svg in the session workspace.' },
+      auto_view: { type: 'boolean', description: 'Open the SVG automatically with the OS default application (default true).' },
+      ...ATTACH_IMAGE_PARAM,
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['length', 'word', 'mode', 'direct_matches', 'inverted_matches', 'direct_cells', 'inverted_cells', 'ambiguous_bases', 'truncated', 'plot_truncated', 'svg_path', 'auto_viewed'],
+    properties: {
+      length: { type: 'integer' },
+      word: { type: 'integer' },
+      mode: { type: 'string', enum: ['both', 'direct', 'inverted'] },
+      direct_matches: { type: 'integer' },
+      inverted_matches: { type: 'integer' },
+      direct_cells: { type: 'integer', description: 'Occupied grid cells for direct repeats (the plotted count, not the match count).' },
+      inverted_cells: { type: 'integer' },
+      ambiguous_bases: { type: 'integer', description: 'Ambiguous k-mers skipped (IUPAC bases other than A/C/G/T).' },
+      truncated: { type: 'boolean', description: 'The match scan hit the work cap; counts are lower bounds.' },
+      plot_truncated: { type: 'boolean', description: 'The grid hit the cell cap; some dots are not drawn.' },
+      grid: { type: 'integer', description: 'Grid resolution used for binning the plot (cells per axis).' },
+      svg_path: { type: 'string' },
+      auto_viewed: { type: 'boolean' },
+      image: ATTACHED_IMAGE_SCHEMA,
+      image_note: { type: 'string' },
+    },
+  },
+  render(value) {
+    const lines = [
+      value.length + ' bp · word ' + value.word + ' · ' + value.direct_matches + ' direct / ' + value.inverted_matches + ' inverted match(es); ' + value.direct_cells + ' + ' + value.inverted_cells + ' occupied cell(s)',
+      'SVG written to ' + value.svg_path + (value.auto_viewed === true ? ' and opened automatically' : '') + '.',
+    ];
+    if (value.ambiguous_bases > 0) lines.push(value.ambiguous_bases + ' ambiguous k-mer(s) skipped (IUPAC bases other than A/C/G/T).');
+    if (value.truncated) lines.push('The match scan hit its work cap: the counts are lower bounds. Raise word to focus on longer, rarer repeats.');
+    if (value.plot_truncated) lines.push('The plotted grid hit its cell cap: some dots are not drawn.');
+    lines.push('Exact k-mer view (black = direct, red = inverted); the diagonal is the sequence against itself.');
+    if (imageNote(value) !== '') lines.push(imageNote(value).trim());
+    return lines.join('\n');
+  },
+  async execute(args, exec) {
+    const data = dotplot(args.sequence, {
+      word: args.word ?? 8,
+      mode: args.mode ?? 'both',
+    });
+    const svg = renderDotplot(data, { title: args.title });
+    const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, 'dotplot.svg');
+    const { directGrid, invertedGrid, ...stats } = data;
+    return mergeAttachedImage({ ...stats, svg_path: file, auto_viewed: viewed }, attached);
+  },
+});
+
 const peptideDigestTool = define({
   name: 'molbio_peptide_digest',
   description: 'In silico protease digestion for mass spectrometry: trypsin, chymotrypsin, LysC or GluC cleavage rules (no cleavage before proline where applicable), optional missed cleavages (0-3), monoisotopic or average [M+H]+ peptide masses, and optional mass-range filtering.',
@@ -4907,6 +5064,7 @@ const sequenceLogoTool = (ctx) => define({
       smallSample: args.small_sample !== false,
     });
     const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, 'logo.svg');
+    rememberCardSvg(file, svg);
     const total = compositions.reduce((sum, column) => sum + column.bits, 0);
     const best = compositions.reduce((top, column) => (column.bits > top.bits ? column : top), compositions[0]);
     const round2 = (x) => Math.round(x * 100) / 100;
@@ -4924,6 +5082,17 @@ const sequenceLogoTool = (ctx) => define({
       auto_viewed: viewed,
     }, attached);
   },
+  // The transcript card draws the logo instead of asking the reader to open the
+  // file. The meta is a projection: cheap, total, and bounded (the markup is
+  // dropped when it exceeds CARD_SVG_MAX_BYTES).
+  presentationMeta(args, value) {
+    return figureCardMeta({
+      figure: 'logo',
+      summary: `Sequence logo · ${value.sequence_count} sequences × ${value.columns} columns · ${value.total_bits} bits (${value.score_type})`,
+      svgPath: value.svg_path,
+      extra: { title: args?.title ?? 'Sequence logo' },
+    }, cardSvgFor(value.svg_path));
+  },
 });
 
 /**
@@ -5199,6 +5368,7 @@ const grnaDesignTool = (ctx) => define({
       mapPath = written.file;
       viewed = written.viewed;
       attached = written.attached;
+      rememberCardSvg(written.file, svg);
     }
     return mergeAttachedImage({
       target_name: name,
@@ -5224,6 +5394,36 @@ const grnaDesignTool = (ctx) => define({
       auto_viewed: viewed,
     }, attached);
   },
+  // The transcript card shows the ranked guides (top five) and, when the caller
+  // asked for map_path, the map itself. The summary is built here so the card
+  // stays a pure function of this projection.
+  presentationMeta(_args, value) {
+    const guides = value.guides.slice(0, 5).map((guide) => ({
+      rank: guide.rank,
+      sequence: guide.sequence,
+      pam: guide.pam,
+      strand: guide.strand,
+      start: guide.start,
+      end: guide.end,
+      score: guide.score,
+      off_target_count: guide.off_target_count ?? 0,
+    }));
+    const recognition = value.pam === '' ? 'no PAM (Cas13)' : value.pam + ' PAM';
+    return figureCardMeta({
+      figure: 'grna',
+      summary: `${value.cas_label} · ${value.guides.length} of ${value.candidate_count} guide(s) · ${recognition} · ${value.target_name} (${value.target_length} bp)`,
+      svgPath: value.map_path,
+      extra: {
+        guides,
+        guide_count: value.guides.length,
+        candidate_count: value.candidate_count,
+        csv_path: value.saved_to,
+        map_path: value.map_path,
+        cas_family: value.cas_family,
+        pam: value.pam,
+      },
+    }, value.map_path === '' ? '' : cardSvgFor(value.map_path));
+  },
 });
 
 /** CSV of the returned guides, for pasting into an ordering sheet. */
@@ -6481,6 +6681,248 @@ const fastqQcTool = (ctx) => define({
   },
 });
 
+
+const contaminationScreenTool = (ctx) => define({
+  name: 'molbio_contamination_screen',
+  description: 'Screen a DNA sequence, or every entry in a FASTA/FASTQ file, for common vector-backbone/promoter/origin and Illumina/Nextera adapter signatures. The signature table is SHORT and embedded (no reference database, no network): a hit is evidence worth following up, and a negative result does NOT prove the sample is clean. Matching is both-strand and substitution-only (no gaps); max_mismatches adds a seed-and-verify search (0-2). Reports per-signature read counts, the best example position/strand, and the criteria that produced them. Use it for "is this assembly contaminated with vector backbone or adapter" — not as a BLAST replacement.',
+  parameters: {
+    type: 'object',
+    properties: {
+      sequence: { type: 'string', description: 'Inline DNA sequence to screen. Provide exactly one of sequence or path.' },
+      path: { type: 'string', description: 'Path to a FASTA/FASTQ file, or a plain sequence file. Provide exactly one of sequence or path.' },
+      max_mismatches: { type: 'integer', description: 'Substitutions allowed per signature (0-2, default 0). A hit still needs one exact seed chunk.' },
+      max_reads: { type: 'integer', description: 'Scan at most this many entries (default 0 = all, capped at 200000).' },
+      kinds: { type: 'string', enum: ['both', 'adapter', 'vector'], description: 'Restrict the table to adapters, vectors, or both (default both).' },
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['input_type', 'total_entries', 'scanned_entries', 'bases', 'ambiguous_bases', 'hits', 'hit_count', 'reads_with_hit', 'truncated', 'criteria'],
+    properties: {
+      input_type: { type: 'string', enum: ['sequence', 'fasta', 'fastq'] },
+      total_entries: { type: 'integer' },
+      scanned_entries: { type: 'integer' },
+      bases: { type: 'integer' },
+      ambiguous_bases: { type: 'integer' },
+      hits: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['name', 'kind', 'category', 'signature', 'reads', 'percent', 'best_mismatches', 'example'],
+          properties: {
+            name: { type: 'string' },
+            kind: { type: 'string', enum: ['adapter', 'vector'] },
+            category: { type: 'string' },
+            signature: { type: 'string' },
+            reads: { type: 'integer' },
+            percent: { type: 'number' },
+            best_mismatches: { type: 'integer' },
+            example: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['id', 'start', 'end', 'strand', 'mismatches'],
+              properties: {
+                id: { type: 'string' },
+                start: { type: 'integer' },
+                end: { type: 'integer' },
+                strand: { type: 'string', enum: ['+', '-'] },
+                mismatches: { type: 'integer' },
+              },
+            },
+          },
+        },
+      },
+      hit_count: { type: 'integer' },
+      reads_with_hit: { type: 'integer' },
+      truncated: { type: 'boolean' },
+      criteria: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['max_mismatches', 'kinds', 'signature_count', 'max_reads', 'match_basis'],
+        properties: {
+          max_mismatches: { type: 'integer' },
+          kinds: { type: 'string', enum: ['both', 'adapter', 'vector'] },
+          signature_count: { type: 'integer' },
+          max_reads: { type: 'integer' },
+          match_basis: { type: 'string' },
+        },
+      },
+    },
+  },
+  render(value) {
+    const lines = [
+      value.input_type + ' input: ' + value.scanned_entries + ' of ' + value.total_entries + ' entr' + (value.total_entries === 1 ? 'y' : 'ies') + ', ' + value.bases + ' bp; ' + value.hit_count + ' signature(s) hit, ' + value.reads_with_hit + ' entr' + (value.total_entries === 1 ? 'y' : 'ies') + ' with a hit.',
+    ];
+    if (value.hits.length === 0) {
+      lines.push('No embedded vector/adapter signature matched.');
+    } else {
+      for (const hit of value.hits) {
+        lines.push('  ' + hit.name + ' [' + hit.kind + '/' + hit.category + '] ' + hit.reads + '/' + value.scanned_entries + ' (' + hit.percent + '%), best ' + hit.best_mismatches + ' mismatch(es); e.g. ' + hit.example.id + ' ' + hit.example.start + '-' + hit.example.end + ' (' + hit.example.strand + ')');
+      }
+    }
+    if (value.ambiguous_bases > 0) lines.push(value.ambiguous_bases + ' ambiguous base(s) were scanned literally (they can only match a signature at an unambiguous position).');
+    if (value.truncated) lines.push('Only the first ' + value.scanned_entries + ' entr' + (value.scanned_entries === 1 ? 'y was' : 'ies were') + ' scanned; max_reads capped the input.');
+    lines.push('Short embedded signatures, both strands, substitutions only (no gaps). A negative result does not prove the sample is clean.');
+    return lines.join('\n');
+  },
+  async execute(args, exec) {
+    const hasSequence = typeof args.sequence === 'string' && args.sequence !== '';
+    const hasPath = typeof args.path === 'string' && args.path !== '';
+    if (hasSequence === hasPath) throw new MolbioInputError('provide exactly one of sequence or path');
+    let entries;
+    let inputType;
+    if (hasSequence) {
+      entries = [{ id: 'input', sequence: normalizeSequence(args.sequence, 'sequence') }];
+      inputType = 'sequence';
+    } else {
+      const bytes = await readFileBytes(ctx, exec, args.path);
+      const text = new TextDecoder().decode(bytes).replace(/^\uFEFF/, '');
+      const first = text.trimStart();
+      if (first.startsWith('@')) {
+        entries = parseFastq(text);
+        inputType = 'fastq';
+      } else if (first.startsWith('>')) {
+        entries = parseFasta(text);
+        inputType = 'fasta';
+      } else {
+        entries = [{ id: 'input', sequence: normalizeSequence(text, 'sequence') }];
+        inputType = 'sequence';
+      }
+    }
+    const result = screenContamination(entries, {
+      maxMismatches: args.max_mismatches,
+      maxReads: args.max_reads,
+      kinds: args.kinds,
+    });
+    return { input_type: inputType, ...result };
+  },
+});
+
+const FASTQ_TRIM_TOOL_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['reads_in', 'total_reads', 'reads_out', 'bases_in', 'bases_out', 'trimmed_reads', 'dropped_reads', 'trim_counts', 'drop_counts', 'truncated', 'criteria', 'saved_to', 'output_format'],
+  properties: {
+    reads_in: { type: 'integer' },
+    total_reads: { type: 'integer' },
+    reads_out: { type: 'integer' },
+    bases_in: { type: 'integer' },
+    bases_out: { type: 'integer' },
+    trimmed_reads: { type: 'integer' },
+    dropped_reads: { type: 'integer' },
+    trim_counts: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['quality', 'adapter', 'poly_g', 'poly_a', 'primer'],
+      properties: {
+        quality: { type: 'integer' },
+        adapter: { type: 'integer' },
+        poly_g: { type: 'integer' },
+        poly_a: { type: 'integer' },
+        primer: { type: 'integer' },
+      },
+    },
+    drop_counts: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['length', 'n'],
+      properties: {
+        length: { type: 'integer' },
+        n: { type: 'integer' },
+      },
+    },
+    truncated: { type: 'boolean' },
+    criteria: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['min_quality', 'quality_window', 'poly_min', 'min_length', 'max_n_percent', 'phred', 'max_reads', 'adapter', 'primer', 'poly_g', 'poly_a'],
+      properties: {
+        min_quality: { type: 'integer' },
+        quality_window: { type: 'integer' },
+        poly_min: { type: 'integer' },
+        min_length: { type: 'integer' },
+        max_n_percent: { type: 'number' },
+        phred: { type: 'integer', enum: [33, 64] },
+        max_reads: { type: 'integer' },
+        adapter: { type: 'string' },
+        primer: { type: 'string' },
+        poly_g: { type: 'boolean' },
+        poly_a: { type: 'boolean' },
+      },
+    },
+    saved_to: { type: 'string' },
+    output_format: { type: 'string', enum: ['fastq', 'fasta'] },
+  },
+};
+
+const fastqTrimTool = (ctx) => define({
+  safe: false,
+  name: 'molbio_fastq_trim',
+  description: 'Trim and filter a FASTQ file, then WRITE the surviving reads as FASTQ or FASTA. Supported operations, applied in this order: remove an exact 5\' primer, remove an exact 3\' adapter and everything after it, trim a low-quality 3\' tail with a sliding mean-quality window, trim a trailing poly-G or poly-A run, then drop reads below min_length or above max_n_percent. Phred+33 and Phred+64 are supported (quality characters are preserved). This is not a paired-end merger, not a semiglobal adapter aligner, and not a UMI pipeline; those are deliberately out of scope. Returns before/after counts, per-stage trim counts, and the written path.',
+  parameters: {
+    type: 'object',
+    required: ['path', 'output_path'],
+    properties: {
+      path: { type: 'string', description: 'Path to the input .fastq/.fq file.' },
+      output_path: { type: 'string', description: 'Path to write the trimmed reads (FASTQ or FASTA, per output_format).' },
+      output_format: { type: 'string', enum: ['fastq', 'fasta'], description: 'Output format (default fastq).' },
+      min_quality: { type: 'integer', description: 'Minimum mean Phred in the sliding window (0-60, default 20). Set 0 to disable quality trimming.' },
+      quality_window: { type: 'integer', description: 'Sliding-window width in bases (1-100, default 4).' },
+      poly_g: { type: 'boolean', description: 'Trim a trailing poly-G run (default false; useful for NovaSeq/NextSeq).' },
+      poly_a: { type: 'boolean', description: 'Trim a trailing poly-A run (default false).' },
+      poly_min: { type: 'integer', description: 'Minimum trailing run length to trim (2-100, default 8).' },
+      adapter: { type: 'string', description: 'Exact 3\' adapter sequence; it and everything after it are removed. Empty = no adapter trim.' },
+      primer: { type: 'string', description: 'Exact 5\' primer sequence; it is removed when the read starts with it. Empty = no primer trim.' },
+      min_length: { type: 'integer', description: 'Drop reads shorter than this after trimming (default 0).' },
+      max_n_percent: { type: 'number', description: 'Drop reads whose trimmed sequence has more than this percent of non-ACGT bases (0-100, default 100 = no filter).' },
+      phred: { type: 'integer', enum: [33, 64], description: 'Quality encoding of the input (33 = Sanger/Illumina 1.8+, 64 = old Illumina). Output keeps the same encoding.' },
+      max_reads: { type: 'integer', description: 'Process at most this many reads (default 0 = all, capped at 200000).' },
+    },
+  },
+  outputSchema: FASTQ_TRIM_TOOL_SCHEMA,
+  render(value) {
+    const counts = value.trim_counts;
+    const lines = [
+      'FASTQ trim: ' + value.reads_in + ' of ' + value.total_reads + ' read(s) scanned (' + value.bases_in + ' bases) -> ' + value.reads_out + ' read(s) (' + value.bases_out + ' bases); ' + value.trimmed_reads + ' trimmed, ' + value.dropped_reads + ' dropped.',
+      '  quality ' + counts.quality + ' · adapter ' + counts.adapter + ' · poly-G ' + counts.poly_g + ' · poly-A ' + counts.poly_a + ' · primer ' + counts.primer + '; dropped by length ' + value.drop_counts.length + ', by N ' + value.drop_counts.n,
+      'Saved ' + value.output_format.toUpperCase() + ' to ' + value.saved_to + '.',
+    ];
+    if (value.truncated) lines.push('Only the first ' + value.reads_in + ' read(s) were processed; max_reads capped the input.');
+    lines.push('Settings: Phred+' + value.criteria.phred + ', min Q' + value.criteria.min_quality + ' over ' + value.criteria.quality_window + ' base(s), poly >= ' + value.criteria.poly_min + ', min length ' + value.criteria.min_length + ', max N ' + value.criteria.max_n_percent + '%.');
+    if (value.criteria.adapter !== '') lines.push('Adapter: ' + value.criteria.adapter + '.');
+    if (value.criteria.primer !== '') lines.push('Primer: ' + value.criteria.primer + '.');
+    return lines.join('\n');
+  },
+  async execute(args, exec) {
+    const bytes = await readFileBytes(ctx, exec, args.path);
+    const text = new TextDecoder().decode(bytes).replace(/^\uFEFF/, '');
+    if (text.trimStart().startsWith('>')) throw new MolbioInputError('this looks like FASTA, not FASTQ: molbio_fastq_trim needs per-base quality strings');
+    const entries = parseFastq(text);
+    const trimmed = trimFastq(entries, {
+      minQuality: args.min_quality,
+      qualityWindow: args.quality_window,
+      polyG: args.poly_g,
+      polyA: args.poly_a,
+      polyMin: args.poly_min,
+      adapter: args.adapter,
+      primer: args.primer,
+      minLength: args.min_length,
+      maxNPercent: args.max_n_percent,
+      phred: args.phred,
+      maxReads: args.max_reads,
+    });
+    const outputFormat = args.output_format ?? 'fastq';
+    const fs = fsService(ctx);
+    const sandboxPolicyService = ctx.get('sandboxPolicy');
+    const policy = sandboxPolicyService?.resolve({ ...exec?.agent !== undefined ? { session: exec.agent.session } : {} });
+    const file = workspaceFilePath(args.output_path, exec, policy?.workspaceRoot);
+    await writeWorkspaceFile(fs, file, outputFormat === 'fasta' ? toFasta(trimmed.entries) : toFastq(trimmed.entries), policy);
+    return { ...trimmed.stats, saved_to: file, output_format: outputFormat };
+  },
+});
+
 const RARE_CODON_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -7602,11 +8044,11 @@ const PROMPT_SECTION = `Molecular-biology tools (dsh-molbio-tools) are available
 - Proteins: molbio_protein_props (MW/pI/A280/GRAVY — estimates), molbio_peptide_digest (trypsin etc. for MS), molbio_codon_optimize (E. coli/yeast/human, can avoid restriction sites), molbio_helical_wheel (Schiffer-Edmundson wheel + Eisenberg hydrophobic moment, written as an SVG), molbio_hydropathy_plot (Kyte-Doolittle sliding-window profile with the 1.6 threshold peaks, written as an SVG).
 - Quantitation: molbio_qpcr_efficiency (standard curve + plot), molbio_plot (experiment-data charts written to files), molbio_virtual_gel (expected band pattern as an SVG gel image with a size ladder).
 - molbio_plot kinds: bar (labelled values + optional SD error bars) and scatter (x/y + optional least-squares line) take their arrays directly in the call; the table kinds read a workspace CSV/TSV — pass data_path plus columns naming which column plays which role, or pass data with the table text inline. Use a table kind whenever the numbers are already in a file: do NOT retype a column into the call. line = one series per group_column; histogram = distribution of one column (bins default to Freedman-Diaconis unless you pass bins); box = Q1-Q3 box, median, 1.5xIQR whiskers, outliers as dots; violin = the same samples as a kernel-density silhouette with the box summary inside (use it when the SHAPE matters, not just the five numbers); volcano = effect size against significance from a log2-fold-change column and a p column, with dashed thresholds — it computes no statistics of its own, so the p-values must already be in the table; heatmap = a row x column matrix, one cell per value plus a colour bar, accepting either a wide table (first column = row labels, the rest = samples) or the long form (columns.row/column/value), with scale row_zscore|log2 as an explicitly-reported DISPLAY transform. The result carries the computed statistics (medians, quartiles, outliers, bin counts, axis ranges, significance counts, matrix extent), so quote THOSE instead of estimating values off the picture.
-- Sequences & files: molbio_align (local alignment with a readable match line), molbio_msa_align (progressive multiple sequence alignment — pass an array of sequences or a workspace FASTA), molbio_conservation (consensus + per-column identity/conservation + variable positions; accepts aligned rows or raw sequences it aligns first), molbio_sequence_logo (draws the same alignment as a sequence logo SVG — pass the molbio_msa_align output rows as the alignment argument; letters are sized by per-position information content), molbio_fasta_fastq (FASTA/FASTQ stats/extract/convert/QC on workspace files), molbio_batch_analyze (run one summary/ORF/enzyme analysis over every matching FASTA/FASTQ/GenBank/.dna file in a directory and write one CSV/TSV table), molbio_extract_region (pull a CDS/promoter/region from a plasmid file by feature label or coordinates).
+- Sequences & files: molbio_align (local alignment with a readable match line), molbio_msa_align (progressive multiple sequence alignment — pass an array of sequences or a workspace FASTA), molbio_conservation (consensus + per-column identity/conservation + variable positions; accepts aligned rows or raw sequences it aligns first), molbio_sequence_logo (draws the same alignment as a sequence logo SVG — pass the molbio_msa_align output rows as the alignment argument; letters are sized by per-position information content), molbio_fasta_fastq (FASTA/FASTQ stats/extract/convert/QC on workspace files), molbio_contamination_screen (embedded short vector/adapter signatures, both strands, exact or 0-2 mismatches — a short-signature screen, not BLAST), molbio_batch_analyze (run one summary/ORF/enzyme analysis over every matching FASTA/FASTQ/GenBank/.dna file in a directory and write one CSV/TSV table), molbio_extract_region (pull a CDS/promoter/region from a plasmid file by feature label or coordinates).
 - CRISPR: molbio_grna_design (family-aware guide RNAs over a sequence or plasmid file: cas_family spcas9/sacas9/cas12a/cas13a/cas13b/cas13d selects the PAM side, crRNA length, seed and target type — Cas12a uses a 5' TTTV PAM and 23 nt crRNA; Cas13 targets RNA and reports a PFS preference rather than a PAM. Both strands are scanned for DNA families, the sense strand by default for Cas13; guides are filtered on GC/poly-T/self-complementarity and ranked, with a mismatch-tolerant off-target search over the same sequence — reaching a whole genome simply means passing it as the target). Pass the top candidates on for ordering with save_path (CSV) or map_path (SVG map); the ranking is a heuristic and says so, so present it as candidate ranking, never as a validated efficiency prediction.
 - Map extras: pass gc_skew: true for the GC skew ring, show_unique_cutters: true to mark single-cutting enzymes on the map.
 - Literature & records: molbio_pubmed_abstract (fetch abstracts by PMID — needs web fetch; an NCBI key comes from the api_key argument, the credential store's NCBI_API_KEY, or the environment), molbio_paper_export_bibtex (papers.json → .bib), molbio_protocol_add / molbio_protocol_list / molbio_protocol_update (protocols.json), molbio_experiment_log / molbio_experiment_list (experiments.json).
-- Bench analysis (v19): molbio_fastq_qc (read-level QC for a FASTQ file: per-base quality with quartiles, per-read quality, base content, GC distribution, length, exact duplication, over-represented sequences, adapter screen, plus a report SVG — use it for "is this run good"), molbio_codon_usage (CAI/RSCU/Nc/GC3, rare-codon list and CDS CpG against E. coli/yeast/human — use it for "will this gene express"; it explains, molbio_codon_optimize rewrites), molbio_phylogenetic_tree (distance method: p-distance/JC/K2P/Tamura-Nei, UPGMA or neighbour-joining, bootstrap support, consensus, Newick file and an SVG tree — it is NOT a maximum-likelihood or Bayesian analysis, and bootstrap percentages are not p-values), molbio_pcr_simulate (where a primer pair amplifies: product sizes and coordinates on both strands, mismatch detail, the 3'-end exact-match requirement, circular templates, screening other templates, and an expected gel — use it for "what band will I see"), molbio_gc_composition (sliding-window GC, CpG islands under the Gardiner-Garden or Takai criteria, GC/AT skew with the cumulative-skew origin/terminus indication, dinucleotide obs/exp, entropy, complexity, N50/L50, plus a figure — use it for "is this a promoter or an origin").
+- Bench analysis (v19): molbio_fastq_qc (read-level QC for a FASTQ file: per-base quality with quartiles, per-read quality, base content, GC distribution, length, exact duplication, over-represented sequences, adapter screen, plus a report SVG — use it for "is this run good"), molbio_codon_usage (CAI/RSCU/Nc/GC3, rare-codon list and CDS CpG against E. coli/yeast/human — use it for "will this gene express"; it explains, molbio_codon_optimize rewrites), molbio_phylogenetic_tree (distance method: p-distance/JC/K2P/Tamura-Nei, UPGMA or neighbour-joining, bootstrap support, consensus, Newick file and an SVG tree — it is NOT a maximum-likelihood or Bayesian analysis, and bootstrap percentages are not p-values), molbio_pcr_simulate (where a primer pair amplifies: product sizes and coordinates on both strands, mismatch detail, the 3'-end exact-match requirement, circular templates, screening other templates, and an expected gel — use it for "what band will I see"), molbio_gc_composition (sliding-window GC, CpG islands under the Gardiner-Garden or Takai criteria, GC/AT skew with the cumulative-skew origin/terminus indication, dinucleotide obs/exp, entropy, complexity, N50/L50, plus a figure — use it for "is this a promoter or an origin"), molbio_fastq_trim (trim low-quality 3' tails, exact adapters/primers, poly-G/poly-A, then filter by length/N and write FASTQ/FASTA — not a paired-end merger).
 - Literature: molbio_pubmed_search — with an NCBI API key (api_key argument, the credential store under NCBI_API_KEY / MOLBIO_NCBI_API_KEY, or the environment) it uses the official PubMed E-utilities API and returns PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web search. The reading library is molbio_paper_add / molbio_paper_list / molbio_paper_update / molbio_paper_remove (papers.json in the workspace).
 
 Cloning workflow rules (follow them to avoid slow re-derivation):
@@ -7650,6 +8092,7 @@ export function apply(ctx) {
     silentSiteTool,
     verifySangerTool(ctx),
     proteinPropsTool,
+    proteinChargeTool(ctx),
     peptideDigestTool,
     codonOptimizeTool,
     helicalWheelTool(ctx),
@@ -7666,10 +8109,13 @@ export function apply(ctx) {
     fastaFastqTool(ctx),
     batchAnalyzeTool(ctx),
     fastqQcTool(ctx),
+    contaminationScreenTool(ctx),
+    fastqTrimTool(ctx),
     codonUsageTool,
     phylogeneticTreeTool(ctx),
     pcrSimulateTool(ctx),
     gcCompositionTool(ctx),
+    dotplotTool(ctx),
     extractRegionTool(ctx),
     pubmedAbstractTool(ctx),
     bibtexTool(ctx),