dsh-molbio-tools 0.22.2 → 0.24.0

package/benchmark/tasks/06-analysis.json

@@ -1,6 +1,7 @@
 {
   "$comment": [
-    "Protein analysis, bench analysis and plotting.",
+    "Protein analysis, bench analysis and plotting, plus the embedded-signature",
+    "contamination screen (short signatures, both strands, negative != clean).",
     "",
     "`reading-frames` is the one task whose point is a TOOL CHOICE rather than a",
     "value: the model must call the translator in all-frames mode with an ORF floor,",
@@ -164,6 +165,115 @@
         }
       ]
     },
+    {
+      "id": "protein-charge",
+      "category": "protein",
+      "tier": "full",
+      "covers": [
+        "molbio_protein_charge"
+      ],
+      "instruction": "I need to know how this peptide's charge changes with pH. Plot the net charge from pH 0 to 14, report the isoelectric point and the net charge at pH 7.4, and tell me which pK set the numbers come from. Write the figure to charge.svg.\n\nMKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ",
+      "timeout_ms": 240000,
+      "expect_tools": [
+        "molbio_protein_charge"
+      ],
+      "assertions": [
+        {
+          "where": "tool",
+          "pattern": "33 aa · Bjellqvist 1993 pK set · pI 10\\.63 · charge at pH 7\\.4 2\\.9835 e \\(net positive\\)"
+        },
+        {
+          "where": "tool",
+          "pattern": "Curve over pH 0-14 \\(29 points; range -4\\.9682 \\.\\. 7\\.9996 e\\)"
+        },
+        {
+          "where": "answer",
+          "pattern": "10\\.6"
+        },
+        {
+          "where": "answer",
+          "pattern": "2\\.98|3\\.0|net positive"
+        },
+        {
+          "where": "answer",
+          "pattern": "Bjellqvist|pK"
+        }
+      ]
+    },
+    {
+      "id": "dotplot",
+      "category": "bench-analysis",
+      "tier": "full",
+      "covers": [
+        "molbio_dotplot"
+      ],
+      "instruction": "I want to see the repeat structure of this 46 bp sequence. Draw a self dotplot with a 5-mer word, covering both direct and inverted repeats, and tell me how many direct and how many inverted matches it finds. Write the figure to dot.svg.\n\nTTAGGCACGTAGCTAGGCTAACGTTAGGCACGTAGCTAGGCTAACG",
+      "timeout_ms": 240000,
+      "expect_tools": [
+        "molbio_dotplot"
+      ],
+      "assertions": [
+        {
+          "where": "tool",
+          "pattern": "46 bp · word 5 · 88 direct / 18 inverted match\\(es\\); 88 \\+ 18 occupied cell\\(s\\)"
+        },
+        {
+          "where": "tool",
+          "pattern": "Exact k-mer view \\(black = direct, red = inverted\\)"
+        },
+        {
+          "where": "answer",
+          "pattern": "88"
+        },
+        {
+          "where": "answer",
+          "pattern": "18"
+        },
+        {
+          "where": "answer",
+          "pattern": "direct|inverted|repeat"
+        }
+      ]
+    },
+    {
+      "id": "contamination-screen",
+      "category": "bench-analysis",
+      "tier": "full",
+      "covers": [
+        "molbio_contamination_screen"
+      ],
+      "instruction": "I have this 122 bp sequence from a miniprep and I am worried it is contaminated with vector backbone or Illumina/Nextera adapter. Screen it against common vector and adapter signatures, tell me which signatures hit and their positions, and say whether this is proof of contamination.\n\n{seq:contamination}",
+      "timeout_ms": 240000,
+      "expect_tools": [
+        "molbio_contamination_screen"
+      ],
+      "assertions": [
+        {
+          "where": "tool",
+          "pattern": "sequence input: 1 of 1 entry, 122 bp; 2 signature\\(s\\) hit, 1 entry with a hit\\."
+        },
+        {
+          "where": "tool",
+          "pattern": "Illumina Universal \\[adapter/adapter\\] 1/1 \\(100%\\), best 0 mismatch\\(es\\); e\\.g\\. input 111-122 \\(\\+\\)"
+        },
+        {
+          "where": "tool",
+          "pattern": "pUC/pBR322 origin \\[vector/origin\\] 1/1 \\(100%\\), best 0 mismatch\\(es\\); e\\.g\\. input 1-30 \\(\\+\\)"
+        },
+        {
+          "where": "answer",
+          "pattern": "pUC|pBR322|vector"
+        },
+        {
+          "where": "answer",
+          "pattern": "Illumina|adapter"
+        },
+        {
+          "where": "answer",
+          "pattern": "not proof|short signature|does not prove|suggest|consistent"
+        }
+      ]
+    },
     {
       "id": "codon-optimize",
       "category": "bench-analysis",

package/benchmark/tasks/09-formats.json

@@ -1,6 +1,10 @@
 {
   "$comment": [
-    "Codon usage, phylogeny, and the two file-parsing tools.",
+    "Codon usage, phylogeny, FASTQ trimming, and the two file-parsing tools.",
+    "",
+    "`fastq-trim` belongs here rather than under visualisation: it reads a FASTQ,",
+    "transforms every record, and writes a FASTQ/FASTA back. The task pins the",
+    "before/after counts and the per-stage trim reasons, not just 'it ran'.",
     "",
     "The parsing tools appear here as a CHAIN rather than alone: a model that",
     "answers a question about a GenBank record without parsing it is doing",
@@ -128,6 +132,45 @@
         }
       ]
     },
+    {
+      "id": "fastq-trim",
+      "category": "sequence-io",
+      "tier": "full",
+      "covers": [
+        "molbio_fastq_trim"
+      ],
+      "instruction": "These four reads are from an old Illumina run: r1 has a low-quality 3' tail, r2 carries the Illumina Universal adapter, r3 has a poly-G tail, and r4 is very short. Trim the low-quality tail with a 3-base window at mean Q30, remove the adapter and everything after it, trim poly-G runs of 8 or more, drop reads shorter than 20 bp, and write the survivors to trimmed.fq. Tell me how many reads and bases went in and out, how many were trimmed or dropped, and why.\n",
+      "timeout_ms": 240000,
+      "expect_tools": [
+        "molbio_fastq_trim"
+      ],
+      "assertions": [
+        {
+          "where": "tool",
+          "pattern": "FASTQ trim: 4 of 4 read\\(s\\) scanned \\(127 bases\\) -> 3 read\\(s\\) \\(80 bases\\); 3 trimmed, 1 dropped\\."
+        },
+        {
+          "where": "tool",
+          "pattern": "quality 1 · adapter 1 · poly-G 1 · poly-A 0 · primer 0; dropped by length 1, by N 0"
+        },
+        {
+          "where": "tool",
+          "pattern": "Saved FASTQ to .*trimmed\\.fq\\."
+        },
+        {
+          "where": "answer",
+          "pattern": "3 .{0,20}(read|kept|surviv)|(kept|surviv).{0,20}3"
+        },
+        {
+          "where": "answer",
+          "pattern": "80"
+        },
+        {
+          "where": "answer",
+          "pattern": "adapter|poly-G|quality|drop"
+        }
+      ]
+    },
     {
       "id": "batch-analysis",
       "category": "formats",

package/benchmark/verifications.mjs

@@ -74,6 +74,7 @@ const FILE_SETUPS = {
   'chart-volcano': { 'de.csv': FIXTURES.DE_CSV },
   'chart-heatmap': { 'expression.tsv': FIXTURES.HEATMAP_TSV },
   'batch-analysis': { 'pUC118.gb': GENBANK_TEXT },
+  'fastq-trim': { 'reads.fq': FIXTURES.TRIM_FASTQ_TEXT },
 };
 
 /**
@@ -252,6 +253,18 @@ export function invocationsFor(task) {
     'peptide-digest': () => [{ tool: 'molbio_peptide_digest', args: { sequence: FIXTURES.DIGEST_PEPTIDE, enzyme: 'trypsin', missed: 0 } }],
     'helical-wheel': () => [{ tool: 'molbio_helical_wheel', args: { sequence: FIXTURES.AMPHIPATHIC_PEPTIDE, title: 'amphipathic test' } }],
     hydropathy: () => [{ tool: 'molbio_hydropathy_plot', args: { sequence: FIXTURES.DIGEST_PEPTIDE } }],
+    'protein-charge': () => [
+      { tool: 'molbio_protein_charge', args: { sequence: FIXTURES.DIGEST_PEPTIDE, output_path: at('charge.svg') } },
+    ],
+    dotplot: () => [
+      { tool: 'molbio_dotplot', args: { sequence: FIXTURES.DOTPLOT_SEQUENCE, word: 5, output_path: at('dot.svg') } },
+    ],
+    'contamination-screen': () => [
+      { tool: 'molbio_contamination_screen', args: { sequence: FIXTURES.CONTAMINATION_SEQUENCE } },
+    ],
+    'fastq-trim': () => [
+      { tool: 'molbio_fastq_trim', args: { path: at('reads.fq'), output_path: at('trimmed.fq'), min_quality: 30, quality_window: 3, poly_g: true, adapter: 'AGATCGGAAGAG', min_length: 20 } },
+    ],
 
     // bench analysis
     'codon-optimize': () => [{ tool: 'molbio_codon_optimize', args: { sequence: FIXTURES.CDS, host: 'e_coli' } }],

package/build/client-entry.mjs

@@ -36,6 +36,8 @@ import {
   childPath,
   classifyEntry,
   credentialInfo,
+  figureCardSummary,
+  figureCardView,
   isMolbioDetailSubject,
   remoteFailure,
   decodeWorkspaceBytes,
@@ -294,8 +296,10 @@ function papersTitle() {
   return 'Papers';
 }
 
-/** The tool names whose transcript card this package draws. */
+/** The tool names whose transcript card this package draws (plasmid maps). */
 const MAP_TOOL_KEYS = ['molbio_plasmid_map', 'molbio_plasmid_map_file'];
+/** Figure tools: a drawn logo / gRNA map plus (for gRNA) the ranked list. */
+const FIGURE_TOOL_KEYS = ['molbio_sequence_logo', 'molbio_grna_design'];
 
 /**
  * The transcript card for the map tools (`tool.call.toolview`, keyed by tool
@@ -364,6 +368,72 @@ function MolbioMapCard({ block, inspect }) {
   return h('div', { style: styles.card }, ...content);
 }
 
+/**
+ * The transcript card for the sequence-logo and gRNA tools. The logo card draws
+ * the logo; the gRNA card draws the map when `map_path` was requested AND lists
+ * the top-ranked guides (a gRNA call without a map still gets the table). Like
+ * the map card it is a pure function of the block, and everything it reads is
+ * validated and bounded by `figureCardView`.
+ */
+function MolbioFigureCard({ block, inspect }) {
+  const settled = block !== null && typeof block === 'object' && block.kind === 'tool-result';
+  const view = figureCardView(settled ? block.meta : undefined);
+  const host = useRef(null);
+  const svg = view.kind === 'figure' ? view.svg : '';
+  const [drawError, setDrawError] = useState(null);
+
+  useEffect(() => {
+    const node = host.current;
+    if (node === null) return;
+    node.replaceChildren();
+    if (svg === '') return;
+    const parsed = new DOMParser().parseFromString(svg, 'image/svg+xml');
+    if (parsed.querySelector('parsererror') !== null) {
+      setDrawError('the figure markup could not be parsed as SVG');
+      return;
+    }
+    setDrawError(null);
+    const element = parsed.documentElement;
+    element.setAttribute('style', 'width:100%;height:auto;max-width:640px');
+    node.append(document.importNode(element, true));
+  }, [svg]);
+
+  const content = [h('div', { key: 'head', style: styles.cardHead }, settled ? figureCardSummary(view) : 'Drawing the figure…')];
+  if (view.kind === 'figure') {
+    if (drawError !== null) content.push(h('div', { key: 'drawerr', style: styles.cardNote }, drawError));
+    content.push(h('div', { key: 'svg', ref: host, style: styles.cardSvg }));
+  } else {
+    content.push(h('div', { key: 'note', style: styles.cardNote }, view.message));
+  }
+  if (view.guides.length > 0) {
+    const head = ['#', 'Guide', 'PAM', 'Position', 'Score', 'Off-targets'];
+    const rows = view.guides.map((guide) => h('tr', { key: guide.rank },
+      h('td', { style: styles.td }, String(guide.rank)),
+      h('td', { style: styles.td }, guide.sequence),
+      h('td', { style: styles.td }, guide.pam === '' ? '—' : guide.pam),
+      h('td', { style: styles.td }, `${guide.strand === 'reverse' ? '−' : '+'}${guide.start}-${guide.end}`),
+      h('td', { style: styles.td }, String(guide.score)),
+      h('td', { style: styles.td }, String(guide.offTargets)),
+    ));
+    content.push(h('table', { key: 'guides', style: styles.table },
+      h('thead', null, h('tr', null, ...head.map((label) => h('th', { key: label, style: styles.th }, label)))),
+      h('tbody', null, ...rows)));
+  }
+  if (view.svgPath !== '') content.push(h('div', { key: 'path', style: styles.cardPath }, view.svgPath));
+  if (view.csvPath !== '') content.push(h('div', { key: 'csv', style: styles.cardPath }, view.csvPath));
+  if (settled && block.isError === true) {
+    const text = (Array.isArray(block.content) ? block.content : [])
+      .map((item) => (item !== null && typeof item === 'object' && item.type === 'text' ? String(item.text ?? '') : ''))
+      .join('\n')
+      .trim();
+    content.push(h('div', { key: 'err', style: styles.error }, text === '' ? 'The call failed.' : text));
+    if (typeof inspect === 'function') {
+      content.push(h('button', { key: 'inspect', style: styles.cardButton, onClick: () => inspect() }, 'Inspect'));
+    }
+  }
+  return h('div', { style: styles.card }, ...content);
+}
+
 /**
  * The literature panel: the workspace `papers.json` the molbio_paper_* tools
  * maintain, rendered as a searchable reading list with a detail pane.
@@ -712,6 +782,15 @@ function apply(ctx) {
       key: toolName,
     }, MolbioMapCard)), `molbio panel: ${toolName} card`);
   }
+  // Figure cards: the sequence-logo and gRNA tools declare a `molbio-figure`
+  // projection; the same component draws a logo or a gRNA map and, for gRNA,
+  // lists the top-ranked guides even when no map was requested.
+  for (const toolName of FIGURE_TOOL_KEYS) {
+    ctx.effect(() => ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
+      name: 'tool.call.toolview',
+      key: toolName,
+    }, MolbioFigureCard)), `molbio panel: ${toolName} card`);
+  }
   // Plugins -> the installed plugin's detail page: the one place a user can
   // store the NCBI key without editing a YAML file or exporting a variable.
   //

package/build/panel-core.mjs

@@ -268,6 +268,91 @@ export function mapCardSummary(view) {
   return parts.join(' · ');
 }
 
+// ── figure cards (the same `tool.call.toolview` seat) ───────────────────────
+
+/** The meta kind the sequence-logo and gRNA tools attach to their results. */
+export const FIGURE_CARD_KIND = 'molbio-figure';
+
+const CARD_SUMMARY_MAX = 300;
+const CARD_PATH_MAX = 500;
+const CARD_GUIDES_MAX = 5;
+
+/** A bounded string, or '' when the value is not a string. */
+function cardText(value, max) {
+  return typeof value === 'string' ? value.slice(0, max) : '';
+}
+
+/** One guide row, validated field by field; malformed rows are dropped. */
+function cardGuide(row) {
+  if (row === null || typeof row !== 'object' || Array.isArray(row)) return undefined;
+  const sequence = cardText(row.sequence, 60);
+  if (sequence === '') return undefined;
+  return {
+    rank: Number.isInteger(row.rank) ? row.rank : 0,
+    sequence,
+    pam: cardText(row.pam, 12),
+    strand: row.strand === 'reverse' ? 'reverse' : 'forward',
+    start: Number.isInteger(row.start) ? row.start : 0,
+    end: Number.isInteger(row.end) ? row.end : 0,
+    score: typeof row.score === 'number' && Number.isFinite(row.score) ? row.score : 0,
+    offTargets: Number.isInteger(row.off_target_count) ? row.off_target_count : 0,
+  };
+}
+
+/**
+ * Read a tool-result block's meta into what the figure card draws.
+ *
+ * Like `mapCardView`, the value is a projection this package produced itself,
+ * but the card renders inside the conversation, so every field is checked and
+ * bounded rather than trusted: a block from an older version, another tool, a
+ * running call or a failed run must degrade to a notice, never throw.
+ *
+ * @param {unknown} meta the block's meta, as the client received it.
+ * @returns {{kind: 'notice', message: string, ...} | {kind: 'figure', figure:
+ *   'logo'|'grna', summary: string, svg: string, svgPath: string,
+ *   csvPath: string, mapPath: string, guides: Array}}
+ */
+export function figureCardView(meta) {
+  if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) {
+    return { kind: 'notice', message: 'No figure data was attached to this call.' };
+  }
+  if (meta.kind !== FIGURE_CARD_KIND) {
+    return { kind: 'notice', message: 'This call carries no figure.' };
+  }
+  const figure = meta.figure === 'grna' ? 'grna' : meta.figure === 'logo' ? 'logo' : '';
+  if (figure === '') {
+    return { kind: 'notice', message: 'This call carries an unknown figure type.' };
+  }
+  const base = {
+    figure,
+    summary: cardText(meta.summary, CARD_SUMMARY_MAX),
+    svgPath: cardText(meta.svg_path, CARD_PATH_MAX),
+    csvPath: cardText(meta.csv_path, CARD_PATH_MAX),
+    mapPath: cardText(meta.map_path, CARD_PATH_MAX),
+    guides: Array.isArray(meta.guides)
+      // Bound the work before validating, then keep at most five VALID rows:
+      // malformed entries must not consume the budget and hide good ones.
+      ? meta.guides.slice(0, 50).map(cardGuide).filter((guide) => guide !== undefined).slice(0, CARD_GUIDES_MAX)
+      : [],
+    svg: '',
+  };
+  if (!isSvgMarkup(meta.svg)) {
+    const message = meta.svg_missing === true
+      ? 'No picture was requested for this call; the numbers are in the tool result.'
+      : meta.svg_omitted === true
+        ? `The figure is too large to draw inline (${Math.round((Number.isInteger(meta.svg_bytes) ? meta.svg_bytes : 0) / 1024)} KB); the written file is named below.`
+        : 'The figure markup did not travel with this call.';
+    return { kind: 'notice', message, ...base };
+  }
+  return { kind: 'figure', ...base, svg: meta.svg };
+}
+
+/** The header line for a figure card, with a stable fallback. */
+export function figureCardSummary(view) {
+  if (view.summary !== '') return view.summary;
+  return view.figure === 'logo' ? 'Sequence logo' : 'gRNA design';
+}
+
 // ── literature library (papers.json) ────────────────────────────────────────
 
 /** The library file the molbio_paper_* tools write, relative to the workspace. */

package/build/release-preflight.mjs

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

package/contamination.mjs

@@ -0,0 +1,229 @@
+/**
+ * dsh-molbio-tools/contamination.mjs
+ *
+ * A small, EMBEDDED set of common vector-backbone/promoter/origin and
+ * Illumina/Nextera adapter signatures, plus a bounded both-strand screen.
+ *
+ * This is deliberately a short-signature screen, not a database search:
+ * a hit is evidence worth following up, and a miss is NOT evidence that a
+ * sample is clean. The table lives in code because the package has no external
+ * data files; every entry names the feature it represents so a report can be
+ * read without guessing which 20-mer matched.
+ *
+ * The adapters are shared with the FASTQ QC adapter-content panel. They are DNA
+ * here: the Small RNA 5' entry is publicly documented as RNA (GUUCAG...), but a
+ * FASTQ read is cDNA, so keeping the U in the table made the forward molecule
+ * unmatchable. Normalizing U→T at the source fixes the screen for both the
+ * standalone tool and fastq-qc's adapter panel.
+ */
+import { MolbioInputError, normalizeSequence, reverseComplement } from './lib.mjs';
+
+/** One signature in the embedded table. */
+export const ADAPTERS = [
+  { name: 'Illumina Universal', kind: 'adapter', category: 'adapter', sequence: 'AGATCGGAAGAG' },
+  { name: "Illumina Small RNA 3'", kind: 'adapter', category: 'adapter', sequence: 'TGGAATTCTCGG' },
+  { name: "Illumina Small RNA 5'", kind: 'adapter', category: 'adapter', sequence: 'GTTCAGAGTTCTACAGTCCGACGATC' },
+  { name: 'Nextera Transposase', kind: 'adapter', category: 'adapter', sequence: 'CTGTCTCTTATA' },
+  { name: 'PolyA', kind: 'adapter', category: 'homopolymer', sequence: 'AAAAAAAAAAAA' },
+  { name: 'PolyG', kind: 'adapter', category: 'homopolymer', sequence: 'GGGGGGGGGGGG' },
+];
+
+/**
+ * Common vector signatures. These are SHORT, deliberately: a 20-35 bp signature
+ * is enough to flag a backbone/promoter/origin in an assembly or read set, while
+ * a full vector sequence would turn this table into a reference database (and
+ * raise licensing questions). Names say which element matched.
+ */
+export const VECTORS = [
+  { name: 'pUC/pBR322 origin', kind: 'vector', category: 'origin', sequence: 'GTTTGCCGGATCAAGAGCTACCAACTCTTT' },
+  { name: 'pUC19 lacZ/M13 region', kind: 'vector', category: 'backbone', sequence: 'GTTTTCCCAGTCACGACGTTGTAAAACGACGGCCAGT' },
+  { name: 'pUC/pBR322 bla (AmpR) start', kind: 'vector', category: 'selection', sequence: 'ATGAGTATTCAACATTTCCGTGTCGCCCTT' },
+  { name: 'pET T7 promoter', kind: 'vector', category: 'promoter', sequence: 'TAATACGACTCACTATAGGG' },
+  { name: 'pET T7 terminator', kind: 'vector', category: 'terminator', sequence: 'GCTAGTTATTGCTCAGCGG' },
+  { name: 'pcDNA CMV promoter', kind: 'vector', category: 'promoter', sequence: 'CGCAAATGGGCGGTAGGCGTG' },
+  { name: 'pcDNA BGH polyA', kind: 'vector', category: 'terminator', sequence: 'CTAGAAGGCACAGTCGAGG' },
+  { name: 'Gateway attB1', kind: 'vector', category: 'recombination', sequence: 'ACAAGTTTGTACAAAAAAGCAGGCT' },
+  { name: 'Gateway attB2', kind: 'vector', category: 'recombination', sequence: 'ACCCAGCTTTCTTGTACAAAGTGGT' },
+];
+
+/** Every embedded signature, adapters first (the table order is stable). */
+export const SIGNATURES = [...ADAPTERS, ...VECTORS];
+
+/** Defaults and hard bounds shared by the tool, tests and docs. */
+export const CONTAMINATION_DEFAULTS = {
+  maxMismatches: 0,
+  maxMismatchesHard: 2,
+  maxReads: 0,
+  maxReadsHard: 200000,
+  maxHits: 100,
+};
+
+const round = (value, digits = 1) => Math.round(value * 10 ** digits) / 10 ** digits;
+
+/** Hamming distance over equal-length strings (non-ACGT positions count as mismatches). */
+function hamming(a, b) {
+  let distance = 0;
+  for (let index = 0; index < a.length; index++) {
+    if (a[index] !== b[index]) distance++;
+  }
+  return distance;
+}
+
+/** The seed chunks used by the mismatch path; one chunk when maxMismatches is 0. */
+function seedChunks(signature, maxMismatches) {
+  const count = maxMismatches + 1;
+  const base = Math.floor(signature.length / count);
+  const chunks = [];
+  let offset = 0;
+  for (let index = 0; index < count; index++) {
+    const length = index === count - 1 ? signature.length - offset : base;
+    chunks.push({ needle: signature.slice(offset, offset + length), offset });
+    offset += length;
+  }
+  return chunks;
+}
+
+/**
+ * Best occurrence of one needle on one strand, or undefined.
+ *
+ * Exact mode is a plain indexOf. The mismatch path uses maxMismatches+1 seed
+ * chunks: at most maxMismatches chunks can be altered, so at least one chunk
+ * must occur verbatim; every seed occurrence is verified with a Hamming count.
+ * This keeps a 30-mer search linear in the number of seed hits instead of
+ * scanning every window of every read.
+ */
+function bestOnStrand(sequence, needle, maxMismatches, strand) {
+  let best;
+  const consider = (start, mismatches) => {
+    if (start < 0 || start + needle.length > sequence.length) return;
+    if (best === undefined
+      || mismatches < best.mismatches
+      || (mismatches === best.mismatches && start < best.start)) {
+      best = { start, end: start + needle.length, strand, mismatches };
+    }
+  };
+  if (maxMismatches === 0) {
+    let from = 0;
+    while (from <= sequence.length - needle.length) {
+      const at = sequence.indexOf(needle, from);
+      if (at === -1) break;
+      consider(at, 0);
+      from = at + 1;
+    }
+    return best;
+  }
+  for (const chunk of seedChunks(needle, maxMismatches)) {
+    if (chunk.needle.length === 0) continue;
+    let from = 0;
+    while (from <= sequence.length - chunk.needle.length) {
+      const at = sequence.indexOf(chunk.needle, from);
+      if (at === -1) break;
+      const start = at - chunk.offset;
+      if (start >= 0 && start + needle.length <= sequence.length) {
+        const mismatches = hamming(sequence.slice(start, start + needle.length), needle);
+        if (mismatches <= maxMismatches) consider(start, mismatches);
+      }
+      from = at + 1;
+    }
+  }
+  return best;
+}
+
+/** Best hit of a signature against a sequence on either strand. */
+export function findSignatureHit(sequence, signature, maxMismatches = 0) {
+  const forward = bestOnStrand(sequence, signature, maxMismatches, '+');
+  const reverse = bestOnStrand(sequence, reverseComplement(signature), maxMismatches, '-');
+  if (forward === undefined) return reverse;
+  if (reverse === undefined) return forward;
+  if (reverse.mismatches < forward.mismatches) return reverse;
+  if (reverse.mismatches === forward.mismatches && reverse.start < forward.start) return reverse;
+  return forward;
+}
+
+/**
+ * Screen one or more sequences against the embedded signatures.
+ *
+ * @param {Array<{id: string, sequence: string}>} entries
+ * @param {{maxMismatches?: number, kinds?: 'both'|'adapter'|'vector', maxReads?: number}} [options]
+ * @returns {object} aggregate hits plus the criteria that produced them.
+ */
+export function screenContamination(entries, options = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) throw new MolbioInputError('contamination screening needs at least one sequence');
+  const maxMismatches = options.maxMismatches ?? CONTAMINATION_DEFAULTS.maxMismatches;
+  if (!Number.isInteger(maxMismatches) || maxMismatches < 0 || maxMismatches > CONTAMINATION_DEFAULTS.maxMismatchesHard) {
+    throw new MolbioInputError('max_mismatches must be an integer between 0 and ' + CONTAMINATION_DEFAULTS.maxMismatchesHard);
+  }
+  const kinds = options.kinds ?? 'both';
+  if (!['both', 'adapter', 'vector'].includes(kinds)) throw new MolbioInputError('kinds must be "both", "adapter" or "vector"');
+  const maxReads = options.maxReads ?? CONTAMINATION_DEFAULTS.maxReads;
+  if (!Number.isInteger(maxReads) || maxReads < 0 || maxReads > CONTAMINATION_DEFAULTS.maxReadsHard) {
+    throw new MolbioInputError('max_reads must be an integer between 0 and ' + CONTAMINATION_DEFAULTS.maxReadsHard);
+  }
+  const limit = maxReads === 0 ? CONTAMINATION_DEFAULTS.maxReadsHard : maxReads;
+  const normalized = entries.map((entry, index) => ({
+    id: typeof entry?.id === 'string' && entry.id !== '' ? entry.id : 'entry' + (index + 1),
+    sequence: normalizeSequence(entry?.sequence ?? '', 'sequence'),
+  }));
+  const scanned = normalized.slice(0, limit);
+  const truncated = normalized.length > scanned.length;
+  const signatures = SIGNATURES.filter((signature) => kinds === 'both' || signature.kind === kinds);
+  let ambiguousBases = 0;
+  let bases = 0;
+  for (const entry of scanned) {
+    bases += entry.sequence.length;
+    for (const base of entry.sequence) if (!'ACGT'.includes(base)) ambiguousBases++;
+  }
+  const hits = [];
+  const withHit = new Set();
+  for (const signature of signatures) {
+    let reads = 0;
+    let best;
+    for (let index = 0; index < scanned.length; index++) {
+      const entry = scanned[index];
+      const hit = findSignatureHit(entry.sequence, signature.sequence, maxMismatches);
+      if (hit === undefined) continue;
+      reads++;
+      withHit.add(index);
+      if (best === undefined
+        || hit.mismatches < best.mismatches
+        || (hit.mismatches === best.mismatches && hit.start < best.start)) {
+        best = { ...hit, id: entry.id };
+      }
+    }
+    if (reads === 0) continue;
+    hits.push({
+      name: signature.name,
+      kind: signature.kind,
+      category: signature.category,
+      signature: signature.sequence,
+      reads,
+      percent: round((reads / scanned.length) * 100),
+      best_mismatches: best.mismatches,
+      example: {
+        id: best.id,
+        start: best.start + 1,
+        end: best.end,
+        strand: best.strand,
+        mismatches: best.mismatches,
+      },
+    });
+  }
+  hits.sort((a, b) => b.reads - a.reads || a.name.localeCompare(b.name));
+  return {
+    total_entries: normalized.length,
+    scanned_entries: scanned.length,
+    bases,
+    ambiguous_bases: ambiguousBases,
+    hits: hits.slice(0, CONTAMINATION_DEFAULTS.maxHits),
+    hit_count: Math.min(hits.length, CONTAMINATION_DEFAULTS.maxHits),
+    reads_with_hit: withHit.size,
+    truncated,
+    criteria: {
+      max_mismatches: maxMismatches,
+      kinds,
+      signature_count: signatures.length,
+      max_reads: maxReads,
+      match_basis: 'embedded short signatures, both strands, substitutions only (no gaps); a negative result does not prove the sample is clean',
+    },
+  };
+}