dsh-molbio-panel 0.1.2 → 0.1.4

package/lib/client.js

@@ -1813,13 +1813,29 @@ window.__ModuleLoader__.load({
 			const { MolbioInputError } = __molbio_require("lib.mjs");
 			// ── minimal XML scanner ─────────────────────────────────────────────────────
 
+			/**
+			 * Whether a numeric entity names a character this decoder may emit.
+			 *
+			 * `String.fromCodePoint` THROWS a RangeError above U+10FFFF, and a RangeError
+			 * raised from inside a `replace` callback escapes the whole parser as an error
+			 * type no caller handles — a crafted `�` in a SnapGene feature
+			 * qualifier (or in a PubMed response) turned `molbio_parse_snapgene` into a
+			 * crash instead of a MolbioInputError. Surrogates are rejected too: they are not
+			 * characters, and emitting a lone one would corrupt the value rather than
+			 * reject the reference. An unreadable entity is left as literal text, which is
+			 * what the named-entity branch already does.
+			 */
+			function isXmlCodePoint(code) {
+			  return Number.isInteger(code) && code >= 0 && code <= 0x10ffff && (code < 0xd800 || code > 0xdfff);
+			}
+
 			function decodeEntities(value) {
 			  return value.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, entity) => {
 			    if (entity[0] === '#') {
 			      const code = entity[1] === 'x' || entity[1] === 'X'
 			        ? parseInt(entity.slice(2), 16)
 			        : parseInt(entity.slice(1), 10);
-			      return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+			      return isXmlCodePoint(code) ? String.fromCodePoint(code) : match;
 			    }
 			    const named = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'", nbsp: ' ' };
 			    return named[entity] ?? match;
@@ -3985,6 +4001,138 @@ window.__ModuleLoader__.load({
 			/** Default SpCas9 PAM. */
 			const DEFAULT_PAM = 'NGG';
 
+			/**
+			 * Cas-family geometry, in ONE table.
+			 *
+			 * The original design hard-coded SpCas9's shape everywhere: a 3' PAM, a 20 nt
+			 * protospacer, and a seed at the guide's 3' end. That is correct for SpCas9 and
+			 * SaCas9, but it is wrong for Cas12a (5' TTTV PAM, 23 nt crRNA, PAM-proximal 5'
+			 * seed) and meaningless for Cas13 (an RNA target with a PFS preference, not a
+			 * PAM). The table below is the fact each family is scored against; the geometry
+			 * and scoring code read it instead of assuming SpCas9.
+			 *
+			 * Sources: SpCas9 NGG / 20 nt; SaCas9 NNGRRT / 21 nt; Cas12a (LbCpf1, AsCpf1)
+			 * 5'-TTTV / 23 nt; LwaCas13a 3' H PFS / 28 nt; PspCas13b 5' D + 3' NAN PFS /
+			 * 30 nt; RfxCas13d no PFS / 22 nt. PFS preferences are NOT hard PAMs: a guide
+			 * without the preferred PFS can still work, so it is penalised and reported
+			 * rather than silently discarded unless the caller sets require_pfs.
+			 */
+			const CAS_FAMILIES = {
+			  spcas9: {
+			    id: 'spcas9',
+			    label: 'SpCas9',
+			    pam: 'NGG',
+			    pamSide: '3prime',
+			    guideLength: 20,
+			    guideLengthMin: 15,
+			    guideLengthMax: 30,
+			    seedSide: '3prime',
+			    seedLength: 12,
+			    seedMismatchWindow: 2,
+			    target: 'DNA',
+			    tmModel: 'dna',
+			    positionBonus: { index: 20, base: 'G', points: 4 },
+			    gcClampNote: true,
+			    pfs: null,
+			  },
+			  sacas9: {
+			    id: 'sacas9',
+			    label: 'SaCas9',
+			    pam: 'NNGRRT',
+			    pamSide: '3prime',
+			    guideLength: 21,
+			    guideLengthMin: 15,
+			    guideLengthMax: 30,
+			    seedSide: '3prime',
+			    seedLength: 12,
+			    seedMismatchWindow: 2,
+			    target: 'DNA',
+			    tmModel: 'dna',
+			    positionBonus: null,
+			    gcClampNote: true,
+			    pfs: null,
+			  },
+			  cas12a: {
+			    id: 'cas12a',
+			    label: 'Cas12a (Cpf1)',
+			    pam: 'TTTV',
+			    pamSide: '5prime',
+			    guideLength: 23,
+			    guideLengthMin: 15,
+			    guideLengthMax: 30,
+			    seedSide: '5prime',
+			    seedLength: 8,
+			    seedMismatchWindow: 2,
+			    target: 'DNA',
+			    tmModel: 'dna',
+			    positionBonus: null,
+			    gcClampNote: false,
+			    pfs: null,
+			  },
+			  cas13a: {
+			    id: 'cas13a',
+			    label: 'Cas13a (LwaCas13a)',
+			    pam: null,
+			    pamSide: 'none',
+			    guideLength: 28,
+			    guideLengthMin: 15,
+			    guideLengthMax: 30,
+			    seedSide: null,
+			    seedLength: 0,
+			    seedMismatchWindow: 0,
+			    target: 'RNA',
+			    tmModel: 'none',
+			    positionBonus: null,
+			    gcClampNote: false,
+			    pfs: { fivePrime: null, threePrime: 'H', label: "3' H (A/C/U) — a preference, not a PAM" },
+			  },
+			  cas13b: {
+			    id: 'cas13b',
+			    label: 'Cas13b (PspCas13b)',
+			    pam: null,
+			    pamSide: 'none',
+			    guideLength: 30,
+			    guideLengthMin: 15,
+			    guideLengthMax: 30,
+			    seedSide: null,
+			    seedLength: 0,
+			    seedMismatchWindow: 0,
+			    target: 'RNA',
+			    tmModel: 'none',
+			    positionBonus: null,
+			    gcClampNote: false,
+			    pfs: { fivePrime: 'D', threePrime: 'NAN', label: "5' D (A/G/U) and 3' NAN — preferences, not a PAM" },
+			  },
+			  cas13d: {
+			    id: 'cas13d',
+			    label: 'Cas13d (RfxCas13d)',
+			    pam: null,
+			    pamSide: 'none',
+			    guideLength: 22,
+			    guideLengthMin: 15,
+			    guideLengthMax: 30,
+			    seedSide: null,
+			    seedLength: 0,
+			    seedMismatchWindow: 0,
+			    target: 'RNA',
+			    tmModel: 'none',
+			    positionBonus: null,
+			    gcClampNote: false,
+			    pfs: null,
+			  },
+			};
+
+			const CAS_FAMILY_NAMES = Object.keys(CAS_FAMILIES);
+
+			/** Look up a family, with a useful error instead of a silent SpCas9 fallback. */
+			function resolveCasFamily(raw = 'spcas9') {
+			  const family = CAS_FAMILIES[raw];
+			  if (family === undefined) {
+			    throw new MolbioInputError(`unknown cas_family ${JSON.stringify(raw)}; known: ${CAS_FAMILY_NAMES.join(', ')}`);
+			  }
+			  return family;
+			}
+
 			/** Hard caps, so one call cannot enumerate an unbounded search space. */
 			const CRISPR_LIMITS = {
 			  maxSequenceLength: 200_000,
@@ -3992,37 +4140,116 @@ window.__ModuleLoader__.load({
 			  maxMismatches: 4,
 			  maxVariantsPerGuide: 400_000,
 			  maxReportedSites: 20,
+			  // A Cas13 scan has no PAM to thin the candidate set: every window of the
+			  // guide length is a candidate. 200 kb would be ~200,000 windows and each
+			  // evaluation computes two folding scores, so cap it and ask for a region.
+			  maxCas13Candidates: 50_000,
 			};
 
+			/** Whether one IUPAC symbol stands for more than one base. */
+			function isDegenerateSymbol(symbol) {
+			  const mask = IUPAC_MASKS[symbol];
+			  if (mask === undefined) return false;
+			  let count = 0;
+			  for (let bits = mask; bits !== 0; bits &= bits - 1) count++;
+			  return count > 1;
+			}
+
 			/**
-			 * Validate a PAM pattern: IUPAC DNA, 2-6 nt, with the 5'-most position
-			 * degenerate (`N`) — the invariant that makes a PAM a PAM rather than a fixed
-			 * site, and the reason a protospacer can always be found upstream of a hit.
+			 * Validate a PAM pattern: IUPAC DNA, 2-6 nt, with the PAM position ADJACENT to
+			 * the protospacer degenerate.
+			 *
+			 * For a 3' PAM (SpCas9 NGG, SaCas9 NNGRRT) that is the 5'-most position, as
+			 * before. For a 5' PAM (Cas12a TTTV) it is the 3'-most position: the V is the
+			 * base next to the protospacer. Requiring "N first" for Cas12a would reject the
+			 * real PAM, so the side is an explicit argument rather than an assumption.
 			 */
-			function assertPamPattern(raw) {
+			function assertPamPattern(raw, side = '3prime') {
 			  if (typeof raw !== 'string') throw new MolbioInputError('pam must be a string');
 			  const pam = normalizeSequence(raw, 'pam');
 			  if (pam.length < 2 || pam.length > 6) {
 			    throw new MolbioInputError(`pam must be 2-6 nt (got ${pam.length})`);
 			  }
-			  if (pam[0] !== 'N') {
+			  if (side === '5prime') {
+			    const anchor = pam[pam.length - 1];
+			    if (!isDegenerateSymbol(anchor)) {
+			      throw new MolbioInputError(`a 5' PAM must end with a degenerate position (got ${JSON.stringify(pam)}) — the base next to the protospacer cannot be fixed`);
+			    }
+			    return pam;
+			  }
+			  if (!isDegenerateSymbol(pam[0])) {
 			    throw new MolbioInputError(`pam must start with the degenerate position N (got ${JSON.stringify(pam)}) — a fixed first position cannot anchor a protospacer`);
 			  }
 			  return pam;
 			}
 
 			/**
-			 * Every PAM-anchored protospacer in `seq`, both strands.
+			 * The PFS observed around one top-strand protospacer window, as read on the
+			 * guide's own strand.
+			 *
+			 * Cas13 PFS elements are preferences, not PAMs, and PspCas13b has one on each
+			 * side. The flanks are therefore part of the candidate object (reported and
+			 * optionally filtered), not a reason to drop a window before the caller sees it.
+			 */
+			function observedPfs(seq, start, guideLength, strand, pfs) {
+			  if (pfs === null) return { five: '', three: '', sequence: '', ok: true };
+			  // For the reverse strand the guide is the reverse complement of the top
+			  // strand, so its 5' flank is the top-strand base AFTER the protospacer and its
+			  // 3' flank is the top-strand base BEFORE it. Reading both through the same
+			  // reverse-complement helper is what keeps the two ends from being swapped.
+			  const fiveTop = strand === 'forward' ? start - 1 : start + guideLength;
+			  const threeTop = strand === 'forward' ? start + guideLength : start - 1;
+			  const read = (from, length) => {
+			    if (from < 0 || from + length > seq.length) return undefined;
+			    const top = seq.slice(from, from + length);
+			    return strand === 'forward' ? top : reverseComplement(top);
+			  };
+			  const five = pfs.fivePrime === null ? '' : read(fiveTop, pfs.fivePrime.length) ?? '';
+			  const three = pfs.threePrime === null ? '' : read(threeTop, pfs.threePrime.length) ?? '';
+			  const okFive = pfs.fivePrime === null || (five !== '' && pamMatches(five, pfs.fivePrime));
+			  const okThree = pfs.threePrime === null || (three !== '' && pamMatches(three, pfs.threePrime));
+			  return { five, three, sequence: [five, three].filter((value) => value !== '').join('/'), ok: okFive && okThree };
+			}
+
+			/**
+			 * Every PAM-anchored (or, for Cas13, PFS-flanked) protospacer in `seq`.
+			 *
 			 * @param {string} seq normalized (ACGT-only) sequence.
-			 * @param {{pam?: string, guideLength?: number}} [options]
+			 * @param {{pam?: string, pamSide?: '3prime'|'5prime'|'none', guideLength?: number,
+			 *   family?: object, targetStrand?: 'forward'|'reverse'|'both'}} [options]
 			 * @returns {Array<{strand: 'forward'|'reverse', start: number, end: number,
-			 *   sequence: string, pam: string, pam_start: number}>} `start`/`end` are
-			 *   1-based inclusive top-strand positions; `pam_start` is 1-based too.
-			 *   Ordered by top-strand position, forward before reverse at a tie.
+			 *   sequence: string, pam: string, pam_start: number, pfs?: string, pfs_ok?: boolean}>}
+			 *   `start`/`end` are 1-based inclusive top-strand positions; `pam_start` is
+			 *   1-based too. Ordered by top-strand position, forward before reverse at a tie.
 			 */
 			function findProtospacers(seq, options = {}) {
-			  const pam = assertPamPattern(options.pam ?? DEFAULT_PAM);
-			  const guideLength = options.guideLength ?? 20;
+			  const pamSide = options.pamSide ?? '3prime';
+			  const guideLength = options.guideLength ?? options.family?.guideLength ?? 20;
+			  if (pamSide === 'none') {
+			    const family = options.family ?? CAS_FAMILIES.cas13a;
+			    const targetStrand = options.targetStrand ?? 'forward';
+			    const strands = targetStrand === 'both' ? ['forward', 'reverse'] : [targetStrand];
+			    const hits = [];
+			    for (const strand of strands) {
+			      for (let start = 0; start + guideLength <= seq.length; start++) {
+			        const pfs = observedPfs(seq, start, guideLength, strand, family.pfs);
+			        hits.push({
+			          strand,
+			          start: start + 1,
+			          end: start + guideLength,
+			          sequence: strand === 'forward' ? seq.slice(start, start + guideLength) : reverseComplement(seq.slice(start, start + guideLength)),
+			          pam: '',
+			          pam_start: 0,
+			          pfs: pfs.sequence,
+			          pfs_ok: pfs.ok,
+			        });
+			      }
+			    }
+			    hits.sort((a, b) => a.start - b.start || a.end - b.end || a.strand.localeCompare(b.strand));
+			    return hits;
+			  }
+			  const pam = assertPamPattern(options.pam ?? options.family?.pam ?? DEFAULT_PAM, pamSide);
+			  const pamLength = pam.length;
 			  const rcPam = reverseComplement(pam);
 			  const hits = [];
 			  const scan = (pattern, strand) => {
@@ -4038,39 +4265,51 @@ window.__ModuleLoader__.load({
 			        }
 			      }
 			      if (!matched) continue;
+			      const pamStart = start; // 0-based top-strand PAM start, both strands
+			      let protospacerStart;
+			      let protospacerEnd; // 0-based inclusive
+			      let pamTop;
 			      if (strand === 'forward') {
-			        const protospacerStart = start - guideLength;
-			        if (protospacerStart < 0) continue; // PAM too close to the 5' end
-			        hits.push({
-			          strand: 'forward',
-			          start: protospacerStart + 1,
-			          end: start,
-			          sequence: seq.slice(protospacerStart, start),
-			          pam: seq.slice(start, start + pattern.length),
-			          pam_start: start + 1,
-			        });
+			        pamTop = seq.slice(pamStart, pamStart + pamLength);
+			        if (pamSide === '3prime') {
+			          // PAM is downstream of the protospacer on the top strand.
+			          protospacerStart = pamStart - guideLength;
+			          protospacerEnd = pamStart - 1;
+			        } else {
+			          // Cas12a: PAM is upstream of the protospacer on the top strand.
+			          protospacerStart = pamStart + pamLength;
+			          protospacerEnd = protospacerStart + guideLength - 1;
+			        }
 			      } else {
-			        // Reverse strand: the PAM triple occupies `start` .. `start + L - 1`
-			        // on the TOP strand, and the protospacer is the guideLength bases
-			        // DOWNSTREAM of it — NOT including the PAM itself. (Slicing PAM +
-			        // guideLength and reverse-complementing the lot was the first version
-			        // of this function and produced 23 nt "guides".)
-			        const pamEnd = start + pattern.length;
-			        const protospacerEnd = pamEnd + guideLength;
-			        if (protospacerEnd > seq.length) continue; // PAM too close to the 3' end
-			        hits.push({
-			          strand: 'reverse',
-			          start: pamEnd + 1,
-			          end: protospacerEnd,
-			          sequence: reverseComplement(seq.slice(pamEnd, protospacerEnd)),
-			          pam: reverseComplement(seq.slice(start, pamEnd)),
-			          pam_start: start + 1,
-			        });
+			        pamTop = reverseComplement(seq.slice(pamStart, pamStart + pamLength));
+			        if (pamSide === '3prime') {
+			          // On the reverse strand the top-strand PAM is UPSTREAM of the
+			          // top-strand protospacer.
+			          protospacerStart = pamStart + pamLength;
+			          protospacerEnd = protospacerStart + guideLength - 1;
+			        } else {
+			          // Cas12a on the reverse strand: the top-strand PAM is DOWNSTREAM.
+			          protospacerEnd = pamStart - 1;
+			          protospacerStart = protospacerEnd - guideLength + 1;
+			        }
 			      }
+			      if (protospacerStart < 0 || protospacerEnd >= seq.length) continue;
+			      const topProto = seq.slice(protospacerStart, protospacerEnd + 1);
+			      hits.push({
+			        strand,
+			        start: protospacerStart + 1,
+			        end: protospacerEnd + 1,
+			        sequence: strand === 'forward' ? topProto : reverseComplement(topProto),
+			        pam: pamTop,
+			        pam_start: pamStart + 1,
+			      });
 			    }
 			  };
 			  scan(pam, 'forward');
-			  if (rcPam !== pam) scan(rcPam, 'reverse');
+			  // Palindromic PAM patterns are legitimate (e.g. an NNNN test pattern), and
+			  // the reverse-strand geometry is a different site even when the text matches,
+			  // so both scans run unconditionally.
+			  scan(rcPam, 'reverse');
 			  hits.sort((a, b) => a.start - b.start || a.end - b.end || a.strand.localeCompare(b.strand));
 			  return hits;
 			}
@@ -4104,25 +4343,32 @@ window.__ModuleLoader__.load({
 			 *   reject_reasons: string[]}}
 			 */
 			function evaluateGuide(guide, options = {}) {
+			  const family = options.family ?? CAS_FAMILIES.spcas9;
 			  const notes = [];
 			  const rejectReasons = [];
 			  const gc = gcFraction(guide);
 			  const gcPercent = Math.round(gc * 1000) / 10;
 			  let tm = null;
-			  try {
-			    tm = primerTm(guide, {
-			      naMm: options.naMm ?? 50,
-			      mgMm: options.mgMm ?? 1.5,
-			      dntpMm: options.dntpMm ?? 0.8,
-			      primerNm: options.primerNm ?? 200,
-			    }).tm_celsius;
-			  } catch {
-			    tm = null; // outside the physical regime of the NN model
-			    notes.push('Tm could not be estimated with the NN model for this sequence');
+			  if (family.tmModel === 'dna') {
+			    try {
+			      tm = primerTm(guide, {
+			        naMm: options.naMm ?? 50,
+			        mgMm: options.mgMm ?? 1.5,
+			        dntpMm: options.dntpMm ?? 0.8,
+			        primerNm: options.primerNm ?? 200,
+			      }).tm_celsius;
+			    } catch {
+			      tm = null; // outside the physical regime of the NN model
+			      notes.push('Tm could not be estimated with the NN model for this sequence');
+			    }
+			  } else {
+			    notes.push('Cas13 targets RNA; the DNA nearest-neighbour Tm is not reported for this guide (it would be a different molecule)');
 			  }
 			  const selfAny = round2(selfAnyScore(guide));
 			  const selfEnd = round2(selfEndScoreSafe(guide));
-			  const seedAny = round2(selfAnyScore(guide.slice(-12)));
+			  const seedAny = family.seedSide === null
+			    ? 0
+			    : round2(selfAnyScore(family.seedSide === '5prime' ? guide.slice(0, family.seedLength) : guide.slice(-family.seedLength)));
 			  let hairpinTm = null;
 			  try {
 			    const hairpins = hairpinThermo(guide);
@@ -4144,11 +4390,17 @@ window.__ModuleLoader__.load({
 			  if (gcPercent < gcMin) rejectReasons.push(`GC ${gcPercent}% below the minimum ${gcMin}%`);
 			  if (gcPercent > gcMax) rejectReasons.push(`GC ${gcPercent}% above the maximum ${gcMax}%`);
 			  if (tRun > (options.maxTRun ?? 4)) rejectReasons.push(`poly-T run of ${tRun} (limit ${options.maxTRun ?? 4}) — a U6 terminator signal`);
-			  if (options.avoidGcClamp !== false && (guide[guide.length - 1] === 'G' || guide[guide.length - 1] === 'C') && (guide[guide.length - 2] === 'G' || guide[guide.length - 2] === 'C')) {
+			  if (family.gcClampNote && options.avoidGcClamp !== false && (guide[guide.length - 1] === 'G' || guide[guide.length - 1] === 'C') && (guide[guide.length - 2] === 'G' || guide[guide.length - 2] === 'C')) {
 			    notes.push('3\' end is a GG/GC/CC/CG clamp, which can favour seed-independent extension');
 			  }
 			  if (selfEnd >= (options.maxSelfEnd ?? 3)) rejectReasons.push(`3' self-complementarity score ${selfEnd} at or above ${options.maxSelfEnd ?? 3}`);
 			  if (options.avoidGcRun !== false && /G{4,}|C{4,}/.test(guide)) rejectReasons.push('homopolymer run of 4+ G/C');
+			  const pfsOk = options.pfsOk ?? true;
+			  if (family.pfs !== null && options.requirePfs === true && !pfsOk) {
+			    rejectReasons.push(`the preferred ${family.pfs.label} PFS is absent; a PFS is a preference, so set require_pfs=false to keep this guide`);
+			  } else if (family.pfs !== null && options.requirePfs !== true && !pfsOk) {
+			    notes.push(`the preferred ${family.pfs.label} PFS is absent (a preference, not a PAM; it costs ranking points)`);
+			  }
 
 			  const scored = scoreGuide({
 			    gcPercent,
@@ -4157,8 +4409,10 @@ window.__ModuleLoader__.load({
 			    longestHomopolymer,
 			    selfAny,
 			    selfEnd,
+			    seedAny,
 			    hairpinTm,
 			    guide,
+			    pfsOk,
 			    offTargetCount: options.offTargetCount ?? 0,
 			  }, options);
 			  return {
@@ -4206,28 +4460,37 @@ window.__ModuleLoader__.load({
 			 * NOT fitted parameters.
 			 */
 			function scoreGuide(metrics, options) {
+			  const family = options.family ?? CAS_FAMILIES.spcas9;
 			  const cap = (value, max) => Math.min(value, max);
-			  const penalties = { gc: 0, tm: 0, poly_t: 0, homopolymer: 0, self: 0, seed: 0, hairpin: 0, off_target: 0 };
+			  const penalties = { gc: 0, tm: 0, poly_t: 0, homopolymer: 0, self: 0, seed: 0, hairpin: 0, pfs: 0, off_target: 0 };
 			  const gcMin = options.gcMin ?? 40;
 			  const gcMax = options.gcMax ?? 70;
 			  const tmMin = options.tmMin ?? 50;
 			  const tmMax = options.tmMax ?? 70;
 			  if (metrics.gcPercent < gcMin) penalties.gc = cap((gcMin - metrics.gcPercent) * 1.0, 20);
 			  if (metrics.gcPercent > gcMax) penalties.gc = cap((metrics.gcPercent - gcMax) * 1.0, 20);
-			  if (metrics.tm === null) penalties.tm = 12;
-			  else if (metrics.tm < tmMin) penalties.tm = cap((tmMin - metrics.tm) * 0.5, 20);
-			  else if (metrics.tm > tmMax) penalties.tm = cap((metrics.tm - tmMax) * 0.5, 20);
+			  if (family.tmModel === 'dna') {
+			    if (metrics.tm === null) penalties.tm = 12;
+			    else if (metrics.tm < tmMin) penalties.tm = cap((tmMin - metrics.tm) * 0.5, 20);
+			    else if (metrics.tm > tmMax) penalties.tm = cap((metrics.tm - tmMax) * 0.5, 20);
+			  }
 			  if (metrics.tRun > 3) penalties.poly_t = cap((metrics.tRun - 3) * 4, 12);
 			  if (metrics.longestHomopolymer > 4) penalties.homopolymer = cap((metrics.longestHomopolymer - 4) * 4, 12);
 			  penalties.self = cap(2 * Math.max(0, metrics.selfAny - 8) + 4 * metrics.selfEnd, 16);
-			  const seedAny = selfAnyScore(metrics.guide.slice(-12));
-			  if (seedAny >= 6) penalties.seed = cap(4 + 0.5 * (seedAny - 6), 12);
+			  const seedAny = metrics.seedAny ?? 0;
+			  if (family.seedSide !== null && seedAny >= 6) penalties.seed = cap(4 + 0.5 * (seedAny - 6), 12);
 			  if (metrics.hairpinTm !== null && metrics.hairpinTm >= (options.maxHairpinTm ?? 47)) {
 			    penalties.hairpin = cap(2 + (metrics.hairpinTm - (options.maxHairpinTm ?? 47)) * 0.5, 12);
 			  }
+			  // A missing preferred PFS is a ranking penalty, never a hard rejection unless
+			  // require_pfs was set. 10 points puts it near the other strong sequence
+			  // signals but below an actual off-target site.
+			  if (family.pfs !== null && metrics.pfsOk === false) penalties.pfs = 10;
 			  penalties.off_target = 8 * (metrics.offTargetCount ?? 0);
 			  const total = Object.values(penalties).reduce((sum, value) => sum + value, 0);
-			  const bonus = metrics.guide[metrics.guide.length - 1] === 'G' ? 4 : 0;
+			  const bonus = family.positionBonus !== null && metrics.guide[family.positionBonus.index - 1] === family.positionBonus.base
+			    ? family.positionBonus.points
+			    : 0;
 			  const score = Math.round(Math.max(0, Math.min(100, 100 - total + bonus)) * 10) / 10;
 			  return { score, penalties };
 			}
@@ -4284,12 +4547,21 @@ window.__ModuleLoader__.load({
 			 */
 			function offTargetSites(guide, index, options = {}) {
 			  const maxMismatches = options.maxMismatches ?? 2;
-			  const requirePam = options.requirePam !== false;
+			  const pamSide = options.pamSide ?? '3prime';
+			  const requirePam = pamSide !== 'none' && options.requirePam !== false;
+			  const seedSide = options.seedSide ?? (pamSide === 'none' ? null : '3prime');
+			  const seedWindow = options.seedMismatchWindow ?? (pamSide === 'none' ? 0 : 2);
 			  const kmers = mismatchVariants(guide, maxMismatches);
 			  const seen = new Map();
 			  for (const [key, distance] of kmers) {
-			    // Seed constraint: positions length-2 and length-1 must match exactly.
-			    if (key.slice(-2) !== guide.slice(-2)) continue;
+			    // The seed is the PAM-proximal end. SpCas9/SaCas9 protect the last two
+			    // bases; Cas12a protects the first two; Cas13 has no PAM and therefore no
+			    // hard seed window in this model.
+			    if (seedWindow > 0 && seedSide !== null) {
+			      const seed = seedSide === '5prime' ? guide.slice(0, seedWindow) : guide.slice(-seedWindow);
+			      const candidate = seedSide === '5prime' ? key.slice(0, seedWindow) : key.slice(-seedWindow);
+			      if (candidate !== seed) continue;
+			    }
 			    for (const [table, strand] of [[index.forward, 'forward'], [index.reverse, 'reverse']]) {
 			      const positions = table.get(key);
 			      if (positions === undefined) continue;
@@ -4306,22 +4578,43 @@ window.__ModuleLoader__.load({
 			function finalizeSites(entries, options, requirePam, guideSequence) {
 			  const reference = options.reference;
 			  const guideLength = options.guideLength ?? 20;
+			  const pamSide = options.pamSide ?? '3prime';
+			  const pam = options.pam ?? DEFAULT_PAM;
+			  const pamLength = pamSide === 'none' ? 0 : pam.length;
 			  const ownStart = options.ownStart;
 			  const ownStrand = options.ownStrand;
 			  const sites = [];
 			  let droppedPam = 0;
 			  let intended = 0;
 			  for (const entry of entries) {
-			    // Protospacer top-strand window: 0-based [start, start+20).
-			    const start = entry.strand === 'forward' ? entry.position : entry.position - (guideLength - 1);
+			    // The index stores every k-mer at its TOP-STRAND start, for both the
+			    // forward and the reverse table. The old reverse formula subtracted
+			    // guideLength-1 here, which shifted every reverse-strand off-target by
+			    // 19 nt and dropped most of them as out of bounds — a silent
+			    // under-count that the forward-only smoke fixture never exposed.
+			    const start = entry.position;
 			    if (start < 0 || start + guideLength > reference.length) continue;
-			    const topSlice = reference.slice(start + guideLength - 1, start + guideLength + 2);
-			    if (topSlice.length < 3) continue;
-			    const pamTop = entry.strand === 'forward' ? reference.slice(start + guideLength, start + guideLength + 3) : reverseComplement(topSlice);
-			    const pamIntact = pamMatches(pamTop, options.pam ?? DEFAULT_PAM);
-			    if (requirePam && !pamIntact) {
-			      droppedPam++;
-			      continue;
+			    let pamTop = '';
+			    let pamIntact = true;
+			    if (pamSide !== 'none') {
+			      // The PAM as read on the GUIDE's strand, and its top-strand window.
+			      // 3' PAM: forward -> downstream; reverse -> upstream.
+			      // 5' PAM (Cas12a): forward -> upstream; reverse -> downstream.
+			      const topPamStart = entry.strand === 'forward'
+			        ? (pamSide === '3prime' ? start + guideLength : start - pamLength)
+			        : (pamSide === '3prime' ? start - pamLength : start + guideLength);
+			      const topPamEnd = topPamStart + pamLength;
+			      if (topPamStart < 0 || topPamEnd > reference.length) {
+			        droppedPam++;
+			        continue;
+			      }
+			      const topPam = reference.slice(topPamStart, topPamEnd);
+			      pamTop = entry.strand === 'forward' ? topPam : reverseComplement(topPam);
+			      pamIntact = pamMatches(pamTop, pam);
+			      if (requirePam && !pamIntact) {
+			        droppedPam++;
+			        continue;
+			      }
 			    }
 			    // The guide's own intended site: same top-strand window and strand, and an
 			    // exact match. Counted (not listed) so the caller can subtract it.
@@ -4330,7 +4623,7 @@ window.__ModuleLoader__.load({
 			      intended++;
 			      continue;
 			    }
-			    sites.push({
+			    const site = {
 			      strand: entry.strand,
 			      start: start + 1,
 			      end: start + guideLength,
@@ -4341,7 +4634,13 @@ window.__ModuleLoader__.load({
 			        entry.strand === 'forward' ? reference.slice(start, start + guideLength) : reverseComplement(reference.slice(start, start + guideLength)),
 			        guideSequence ?? '',
 			      ),
-			    });
+			    };
+			    if (options.pfsSpec !== undefined && options.pfsSpec !== null) {
+			      const pfs = observedPfs(reference, start, guideLength, entry.strand, options.pfsSpec);
+			      site.pfs = pfs.sequence;
+			      site.pfs_ok = pfs.ok;
+			    }
+			    sites.push(site);
 			  }
 			  sites.sort((a, b) => a.mismatches - b.mismatches || a.start - b.start || a.strand.localeCompare(b.strand));
 			  return {
@@ -4372,20 +4671,37 @@ window.__ModuleLoader__.load({
 			 *   off-target penalty is already part of every scanned guide's score.
 			 */
 			function designGrnas(sequence, options = {}) {
-			  const pam = assertPamPattern(options.pam ?? DEFAULT_PAM);
-			  const guideLength = options.guideLength ?? 20;
-			  const candidates = findProtospacers(sequence, { pam, guideLength });
+			  const family = resolveCasFamily(options.casFamily ?? 'spcas9');
+			  const pam = family.pam === null ? '' : assertPamPattern(options.pam ?? family.pam, family.pamSide);
+			  const guideLength = options.guideLength ?? family.guideLength;
+			  if (guideLength < family.guideLengthMin || guideLength > family.guideLengthMax) {
+			    throw new MolbioInputError(`guide_length for ${family.id} must be between ${family.guideLengthMin} and ${family.guideLengthMax} nt (got ${guideLength})`);
+			  }
+			  const targetStrand = options.targetStrand ?? (family.target === 'RNA' ? 'forward' : 'both');
+			  const candidates = findProtospacers(sequence, {
+			    ...family.pam === null ? {} : { pam },
+			    pamSide: family.pamSide,
+			    guideLength,
+			    family,
+			    targetStrand,
+			  });
 			  const regionStart = options.regionStart ?? 1;
 			  const regionEnd = options.regionEnd ?? sequence.length;
 			  const inRegion = candidates.filter((hit) => hit.start >= regionStart && hit.end <= regionEnd);
+			  if (family.pamSide === 'none' && inRegion.length > CRISPR_LIMITS.maxCas13Candidates) {
+			    throw new MolbioInputError(`the Cas13 scan found ${inRegion.length} candidate windows in the requested region (limit ${CRISPR_LIMITS.maxCas13Candidates}); tighten region_start/region_end`);
+			  }
+			  const requirePfs = options.requirePfs === true;
 			  const evaluated = inRegion.map((hit) => {
-			    const metrics = evaluateGuide(hit.sequence, options);
+			    const metrics = evaluateGuide(hit.sequence, { ...options, family, pfsOk: hit.pfs_ok ?? true, requirePfs });
 			    return {
 			      sequence: hit.sequence,
 			      pam: hit.pam,
 			      strand: hit.strand,
 			      start: hit.start,
 			      end: hit.end,
+			      ...family.target === 'RNA' ? { rna_sequence: hit.sequence.replaceAll('T', 'U') } : {},
+			      ...hit.pfs === undefined || hit.pfs === '' ? {} : { pfs: hit.pfs.replaceAll('T', 'U'), pfs_ok: hit.pfs_ok ?? true },
 			      gc_percent: metrics.gc_percent,
 			      tm_celsius: metrics.tm_celsius,
 			      self_any: metrics.self_any,
@@ -4418,6 +4734,10 @@ window.__ModuleLoader__.load({
 			        reference: sequence,
 			        guideLength,
 			        pam,
+			        pamSide: family.pamSide,
+			        seedSide: family.seedSide,
+			        seedMismatchWindow: family.seedMismatchWindow,
+			        pfsSpec: family.pfs,
 			        guideSequence: guide.sequence,
 			        ownStart: guide.start,
 			        ownStrand: guide.strand,
@@ -4429,7 +4749,8 @@ window.__ModuleLoader__.load({
 			      guide.off_target_sites = result.sites;
 			      guide.pam_disrupted_sites = result.dropped_pam_disrupted;
 			      if (guide.off_target_count > 0) {
-			        guide.notes.push(`${guide.off_target_count} off-target site(s) with <= ${options.maxMismatches ?? 2} mismatch(es) and an intact PAM in the supplied reference`);
+			        const requirement = family.pamSide === 'none' ? 'with no PAM requirement (Cas13)' : 'and an intact PAM';
+			        guide.notes.push(`${guide.off_target_count} off-target site(s) with <= ${options.maxMismatches ?? 2} mismatch(es) ${requirement} in the supplied reference`);
 			      }
 			      // Re-score with the off-target penalty included (the only penalty that
 			      // depends on the search, and the one weighted above all the others).
@@ -4440,10 +4761,12 @@ window.__ModuleLoader__.load({
 			        longestHomopolymer: longestRun(guide.sequence),
 			        selfAny: guide.self_any,
 			        selfEnd: guide.self_end,
+			        seedAny: guide.seed_self_any,
 			        hairpinTm: guide.hairpin_tm,
 			        guide: guide.sequence,
+			        pfsOk: guide.pfs_ok ?? true,
 			        offTargetCount: guide.off_target_count,
-			      }, options);
+			      }, { ...options, family });
 			      guide.score = rescored.score;
 			      guide.penalties = rescored.penalties;
 			    }
@@ -4458,7 +4781,14 @@ window.__ModuleLoader__.load({
 			    rejected_count: evaluated.length - accepted.length,
 			    accepted_count: accepted.length,
 			    off_target_scanned: scanned,
+			    cas_family: family.id,
+			    cas_label: family.label,
 			    pam,
+			    pam_side: family.pamSide,
+			    pfs: family.pfs === null ? '' : family.pfs.label,
+			    target: family.target,
+			    target_strand: targetStrand,
+			    require_pfs: requirePfs,
 			    guide_length: guideLength,
 			  };
 			}
@@ -4531,6 +4861,9 @@ window.__ModuleLoader__.load({
 			}
 
 			exports.DEFAULT_PAM = DEFAULT_PAM;
+			exports.CAS_FAMILIES = CAS_FAMILIES;
+			exports.CAS_FAMILY_NAMES = CAS_FAMILY_NAMES;
+			exports.resolveCasFamily = resolveCasFamily;
 			exports.CRISPR_LIMITS = CRISPR_LIMITS;
 			exports.assertPamPattern = assertPamPattern;
 			exports.findProtospacers = findProtospacers;
@@ -5686,6 +6019,40 @@ window.__ModuleLoader__.load({
 			  maxAmplicons: 5,
 			};
 
+			/**
+			 * Probe chemistries the designer knows about.
+			 *
+			 * A standard TaqMan probe is dual-labelled (5' reporter, 3' quencher) and is
+			 * designed at 18-27 nt with a Tm 5 °C above the primers. An MGB probe carries a
+			 * minor-groove binder that raises the Tm substantially, so the SAME unmodified
+			 * NN estimate must be compared with a lower window and the shorter length
+			 * window. The modification's Tm contribution is NOT modelled: the reported Tm
+			 * is the unmodified DNA estimate, and the result says so. Claiming a modified
+			 * Tm from the NN model would be a fabricated number.
+			 */
+			const PROBE_CHEMISTRY = {
+			  taqman: {
+			    label: 'TaqMan (standard dual-labelled)',
+			    probeLenMin: 18,
+			    probeLenMax: 27,
+			    probeTmMin: 58,
+			    probeTmMax: 72,
+			    minTmDelta: 5,
+			    defaultQuencher: 'BHQ1',
+			    tmModel: 'unmodified DNA nearest-neighbour estimate',
+			  },
+			  mgb: {
+			    label: 'TaqMan MGB (minor-groove binder)',
+			    probeLenMin: 13,
+			    probeLenMax: 20,
+			    probeTmMin: 48,
+			    probeTmMax: 60,
+			    minTmDelta: 0,
+			    defaultQuencher: 'NFQ-MGB',
+			    tmModel: 'unmodified DNA nearest-neighbour estimate; the MGB modification raises Tm by an amount this model does not predict — verify with the supplier',
+			  },
+			};
+
 			const round2 = (value) => Math.round(value * 100) / 100;
 
 			function pairTm(pair) {
@@ -5739,7 +6106,8 @@ window.__ModuleLoader__.load({
 			 * Evaluate one probe candidate: thermodynamics, structure, and the heuristic
 			 * flags a designer must know before ordering it.
 			 */
-			function evaluateProbe(seq, { tmOpts, ctMolar, primerTmMax, maxRun, maxSelfAny }) {
+			function evaluateProbe(seq, { tmOpts, ctMolar, primerTmMax, maxRun, maxSelfAny, chemistry = 'taqman' }) {
+			  const chemistrySpec = PROBE_CHEMISTRY[chemistry] ?? PROBE_CHEMISTRY.taqman;
 			  const lower = seq.toUpperCase();
 			  const tm = primerTm(lower, tmOpts).tm_celsius;
 			  const gc = gcPercent(lower);
@@ -5749,6 +6117,7 @@ window.__ModuleLoader__.load({
 			  const selfAny = safeSelfAny(lower);
 			  const selfEnd = safeSelfEnd(lower);
 			  const notes = [];
+			  if (chemistry === 'mgb') notes.push(`MGB probe: Tm ${round2(tm)} °C is the unmodified DNA NN estimate; the MGB modification raises it, so verify the modified Tm with the supplier`);
 			  if (lower[0] === 'G') notes.push('5\' terminal G: the guanine quenches the reporter even before cleavage — move the probe or pick the reverse strand');
 			  if (lower[lower.length - 1] === 'G') notes.push('3\' terminal G: a short probe is extended by the polymerase without cleavage — prefer a different 3\' base');
 			  if (runs.length > 0) notes.push(`mononucleotide run >= ${maxRun + 1} bases (${runs.map((run) => `${run.base}${run.count}`).join(', ')})`);
@@ -5770,9 +6139,12 @@ window.__ModuleLoader__.load({
 			  return {
 			    sequence: lower,
 			    length: lower.length,
+			    chemistry,
+			    chemistry_label: chemistrySpec.label,
+			    tm_model: chemistrySpec.tmModel,
 			    tm: round2(tm),
 			    gc_percent: gc,
-			    tm_delta_vs_primer: tmDelta,
+			    ...tmDelta === undefined ? {} : { tm_delta_vs_primer: tmDelta },
 			    hairpin_tm: round2(hairpin),
 			    self_any: selfAny,
 			    self_end: selfEnd,
@@ -5830,6 +6202,11 @@ window.__ModuleLoader__.load({
 			  // outward from, and the 3' end the reported distance is measured against.
 			  const stem = forwardUpstream ? forwardInterval : reverseInterval;
 			  const work = reverse ? reverseComplement(template) : template;
+			  // An MGB probe's unmodified Tm is lower than its primers' by design; the
+			  // minor-groove binder supplies the missing stability. Comparing the raw NN Tm
+			  // with the primer Tm would penalise every MGB candidate, so the margin is not
+			  // applied to that chemistry (the MGB Tm window is the constraint instead).
+			  const tmReference = opts.chemistry === 'mgb' ? undefined : primerTmMax;
 			  // On `work`, a top-strand interval [s, e] corresponds to [n-1-e, n-1-s].
 			  const windowStart = reverse ? n - 1 - gap[1] : gap[0] + minGap;
 			  const windowEnd = reverse ? n - 1 - gap[0] - minGap : gap[1] - minGap;
@@ -5840,9 +6217,10 @@ window.__ModuleLoader__.load({
 			      const evaluated = evaluateProbe(sequence, {
 			        tmOpts: opts.tmOpts,
 			        ctMolar: opts.ctMolar,
-			        primerTmMax,
+			        primerTmMax: tmReference,
 			        maxRun: opts.maxRun,
 			        maxSelfAny: opts.maxSelfAny,
+			        chemistry: opts.chemistry,
 			      });
 			      if (evaluated.gc_percent < opts.probeGcMin || evaluated.gc_percent > opts.probeGcMax) continue;
 			      if (evaluated.tm < opts.probeTmMin || evaluated.tm > opts.probeTmMax) continue;
@@ -5892,9 +6270,22 @@ window.__ModuleLoader__.load({
 			 */
 			function designTaqmanProbes(rawTemplate, rawOptions = {}) {
 			  const template = normalizeSequence(rawTemplate);
-			  const opts = { ...PROBE_DEFAULTS };
+			  const chemistry = rawOptions.probeChemistry ?? 'taqman';
+			  const chemistrySpec = PROBE_CHEMISTRY[chemistry];
+			  if (chemistrySpec === undefined) {
+			    throw new MolbioInputError(`unknown probe_chemistry ${JSON.stringify(chemistry)}; known: ${Object.keys(PROBE_CHEMISTRY).join(', ')}`);
+			  }
+			  const opts = {
+			    ...PROBE_DEFAULTS,
+			    probeLenMin: chemistrySpec.probeLenMin,
+			    probeLenMax: chemistrySpec.probeLenMax,
+			    probeTmMin: chemistrySpec.probeTmMin,
+			    probeTmMax: chemistrySpec.probeTmMax,
+			    minTmDelta: chemistrySpec.minTmDelta,
+			    chemistry,
+			  };
 			  for (const [key, value] of Object.entries(rawOptions)) {
-			    if (value !== undefined && value !== null) opts[key] = value;
+			    if (value !== undefined && value !== null && key !== 'probeChemistry') opts[key] = value;
 			  }
 			  // A hydrolysis-probe assay is deliberately short (the amplicon is the stretch
 			  // the polymerase must traverse before it reaches and cleaves the probe), so
@@ -6000,7 +6391,11 @@ window.__ModuleLoader__.load({
 			      tm: [primerOpts.tmMin, primerOpts.tmMax],
 			      gc: [primerOpts.gcMin, primerOpts.gcMax],
 			    },
+			    probe_chemistry: chemistry,
 			    probe_options: {
+			      chemistry,
+			      chemistry_label: chemistrySpec.label,
+			      tm_model: chemistrySpec.tmModel,
 			      length: [opts.probeLenMin, opts.probeLenMax],
 			      tm: [opts.probeTmMin, opts.probeTmMax],
 			      gc: [opts.probeGcMin, opts.probeGcMax],
@@ -6075,9 +6470,22 @@ window.__ModuleLoader__.load({
 			 * that will run them.
 			 */
 			function resolveProbeOptions(raw = {}) {
-			  const opts = { ...PROBE_DEFAULTS };
+			  const chemistry = raw.probeChemistry ?? 'taqman';
+			  const chemistrySpec = PROBE_CHEMISTRY[chemistry];
+			  if (chemistrySpec === undefined) {
+			    throw new MolbioInputError(`unknown probe_chemistry ${JSON.stringify(chemistry)}; known: ${Object.keys(PROBE_CHEMISTRY).join(', ')}`);
+			  }
+			  const opts = {
+			    ...PROBE_DEFAULTS,
+			    probeLenMin: chemistrySpec.probeLenMin,
+			    probeLenMax: chemistrySpec.probeLenMax,
+			    probeTmMin: chemistrySpec.probeTmMin,
+			    probeTmMax: chemistrySpec.probeTmMax,
+			    minTmDelta: chemistrySpec.minTmDelta,
+			    chemistry,
+			  };
 			  for (const [key, value] of Object.entries(raw)) {
-			    if (value !== undefined && value !== null && key !== 'primer_options') opts[key] = value;
+			    if (value !== undefined && value !== null && key !== 'primer_options' && key !== 'probeChemistry') opts[key] = value;
 			  }
 			  if (!Number.isInteger(opts.probeLenMin) || opts.probeLenMin < 12) throw new MolbioInputError('probe_len_min must be an integer >= 12');
 			  if (!Number.isInteger(opts.probeLenMax) || opts.probeLenMax > 40 || opts.probeLenMax < opts.probeLenMin) throw new MolbioInputError('probe_len_max must be an integer between probe_len_min and 40');
@@ -6094,12 +6502,96 @@ window.__ModuleLoader__.load({
 			  return opts;
 			}
 
+			/** Quote one CSV field; ordering sheets contain commas in probe notes. */
+			function csvField(value) {
+			  const text = value === undefined || value === null ? '' : String(value);
+			  return /[",\n\r]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+			}
+
+			/**
+			 * Build the oligo rows a synthesis order needs: one row per primer and probe.
+			 *
+			 * The modification column is deliberately explicit rather than implied by the
+			 * chemistry name: a lab ordering sheet has separate 5' and 3' modification
+			 * fields, and an MGB probe without an NFQ-MGB quencher is a different molecule.
+			 */
+			function taqmanOrderRows(assays, options = {}) {
+			  const chemistry = options.chemistry ?? 'taqman';
+			  const spec = PROBE_CHEMISTRY[chemistry] ?? PROBE_CHEMISTRY.taqman;
+			  const reporter = options.reporter ?? 'FAM';
+			  const quencher = options.quencher ?? spec.defaultQuencher;
+			  const primerScale = options.primerScale ?? '25nm';
+			  const probeScale = options.probeScale ?? '25nm';
+			  const primerPurification = options.primerPurification ?? 'standard';
+			  const probePurification = options.probePurification ?? 'hplc';
+			  const rows = [];
+			  for (const [index, assay] of assays.entries()) {
+			    const id = `assay${index + 1}`;
+			    for (const [role, primer] of [['forward', assay.forward], ['reverse', assay.reverse]]) {
+			      rows.push({
+			        assay: index + 1,
+			        role,
+			        name: `${id}_${role === 'forward' ? 'F' : 'R'}`,
+			        sequence: primer.sequence,
+			        length: primer.length,
+			        tm_celsius: primer.tm,
+			        gc_percent: primer.gc_percent,
+			        modification: '',
+			        scale: primerScale,
+			        purification: primerPurification,
+			        notes: '',
+			      });
+			    }
+			    const probe = assay.probe;
+			    const noteParts = [spec.label, probe.tm_model, ...(probe.notes ?? [])];
+			    if (chemistry === 'mgb' && quencher !== 'NFQ-MGB') {
+			      noteParts.push('an MGB probe is normally ordered with an NFQ-MGB quencher; a different quencher is a different molecule');
+			    }
+			    rows.push({
+			      assay: index + 1,
+			      role: 'probe',
+			      name: `${id}_P`,
+			      sequence: probe.sequence,
+			      length: probe.length,
+			      tm_celsius: probe.tm,
+			      gc_percent: probe.gc_percent,
+			      modification: `5' ${reporter} / 3' ${quencher}`,
+			      scale: probeScale,
+			      purification: probePurification,
+			      notes: noteParts.filter((part) => part !== undefined && part !== '').join('; '),
+			    });
+			  }
+			  return rows;
+			}
+
+			/** Render the ordering rows as CSV text. */
+			function taqmanOrderCsv(rows) {
+			  const header = 'assay,role,name,sequence,length,tm_celsius,gc_percent,modification,scale,purification,notes';
+			  const lines = rows.map((row) => [
+			    row.assay,
+			    row.role,
+			    row.name,
+			    row.sequence,
+			    row.length,
+			    row.tm_celsius,
+			    row.gc_percent,
+			    row.modification,
+			    row.scale,
+			    row.purification,
+			    row.notes,
+			  ].map(csvField).join(','));
+			  return `${[header, ...lines].join('\n')}\n`;
+			}
+
 			exports.PROBE_DEFAULTS = PROBE_DEFAULTS;
+			exports.PROBE_CHEMISTRY = PROBE_CHEMISTRY;
 			exports.evaluateProbe = evaluateProbe;
 			exports.probeCandidates = probeCandidates;
 			exports.designTaqmanProbes = designTaqmanProbes;
 			exports.primerEngineOptions = primerEngineOptions;
 			exports.resolveProbeOptions = resolveProbeOptions;
+			exports.taqmanOrderRows = taqmanOrderRows;
+			exports.taqmanOrderCsv = taqmanOrderCsv;
 			return exports;
 		};
 		__molbio_modules["multiplex.mjs"] = () => {
@@ -6139,6 +6631,14 @@ window.__ModuleLoader__.load({
 			  maxSitesReported: 6,
 			  /** Concentration used for folding Tm (nM primer -> molar). */
 			  primerNm: 200,
+			  /** Annealing-temperature recommendation: lowest primer Tm minus this offset. */
+			  annealingOffsetC: 3,
+			  /** Half-width of the recommended annealing window, °C. */
+			  annealingWindowC: 1,
+			  /** A primer-Tm spread above this makes one annealing temperature a compromise. */
+			  tmSpreadWarnC: 5,
+			  /** Starting primer concentration for every target, nM. */
+			  primerConcentrationNm: 200,
 			};
 
 			const round2 = (value) => Math.round(value * 100) / 100;
@@ -6271,6 +6771,18 @@ window.__ModuleLoader__.load({
 			  if (rawTargets.length > opts.maxTargets) throw new MolbioInputError(`targets has ${rawTargets.length} entries; the limit is ${opts.maxTargets} per call`);
 			  if (!(opts.dimerTmThreshold > 0)) throw new MolbioInputError('dimer_tm_threshold must be a positive temperature in °C');
 			  if (!Number.isInteger(opts.minSizeSeparationBp) || opts.minSizeSeparationBp < 0) throw new MolbioInputError('min_size_separation_bp must be a non-negative integer');
+			  if (!(typeof opts.annealingOffsetC === 'number' && Number.isFinite(opts.annealingOffsetC) && opts.annealingOffsetC >= 0 && opts.annealingOffsetC <= 15)) {
+			    throw new MolbioInputError('annealing_offset_c must be a number between 0 and 15 (°C below the lowest primer Tm)');
+			  }
+			  if (!(typeof opts.annealingWindowC === 'number' && Number.isFinite(opts.annealingWindowC) && opts.annealingWindowC >= 0 && opts.annealingWindowC <= 5)) {
+			    throw new MolbioInputError('annealing_window_c must be a number between 0 and 5 (°C on each side of the recommendation)');
+			  }
+			  if (!(typeof opts.tmSpreadWarnC === 'number' && Number.isFinite(opts.tmSpreadWarnC) && opts.tmSpreadWarnC >= 0 && opts.tmSpreadWarnC <= 20)) {
+			    throw new MolbioInputError('tm_spread_warn_c must be a number between 0 and 20');
+			  }
+			  if (!(typeof opts.primerConcentrationNm === 'number' && Number.isFinite(opts.primerConcentrationNm) && opts.primerConcentrationNm >= 20 && opts.primerConcentrationNm <= 1000)) {
+			    throw new MolbioInputError('primer_concentration_nm must be a number between 20 and 1000');
+			  }
 
 			  const ctMolar = opts.primerNm * 1e-9;
 			  const targets = rawTargets.map((target, index) => {
@@ -6318,6 +6830,31 @@ window.__ModuleLoader__.load({
 			    }
 			  }
 
+			  // Annealing temperature: one tube, one temperature. The defensible starting
+			  // point is the LOWEST primer Tm minus a small offset, because a primer that
+			  // melts below the set temperature is the one that drops out first. This is a
+			  // rule of thumb, not a thermal-cycling optimisation — the note says so.
+			  const annealing = primers.length === 0 ? null : (() => {
+			    const tms = primers.map((primer) => primer.tm);
+			    const minTm = Math.min(...tms);
+			    const maxTm = Math.max(...tms);
+			    const spread = round2(maxTm - minTm);
+			    const limiting = primers.reduce((best, primer) => (primer.tm < best.tm ? primer : best));
+			    const recommended = round2(minTm - opts.annealingOffsetC);
+			    return {
+			      min_primer_tm: round2(minTm),
+			      max_primer_tm: round2(maxTm),
+			      spread_c: spread,
+			      recommended_c: recommended,
+			      range_c: [round2(recommended - opts.annealingWindowC), round2(recommended + opts.annealingWindowC)],
+			      limiting_primer: `${limiting.target}/${limiting.role}`,
+			      offset_c: opts.annealingOffsetC,
+			      window_c: opts.annealingWindowC,
+			      tm_spread_ok: spread <= opts.tmSpreadWarnC,
+			      note: 'Starting point: the lowest primer Tm minus the configured offset; optimise on the bench with a temperature gradient.',
+			    };
+			  })();
+
 			  // Cross interactions: every primer pair that is not the same primer. Within a
 			  // target, forward+reverse is the intended pair (its dimer was already checked
 			  // by the designer), so the conflicts are the CROSS-target ones plus each
@@ -6435,6 +6972,36 @@ window.__ModuleLoader__.load({
 			  }
 			  sizeConflicts.sort((x, y) => x.difference_bp - y.difference_bp);
 
+			  // Primer concentrations: a multiplex is a competition, and a much shorter
+			  // amplicon can out-compete a longer one. The plan is deliberately conservative
+			  // — it starts every pair at the same concentration and only shifts the
+			  // extremes when the size ratio is at least 2x. It is a starting point, not a
+			  // measured optimum; the rationale field says which case each target is in.
+			  const knownSizes = sizes.filter((entry) => entry.length !== undefined).map((entry) => entry.length);
+			  const minSize = knownSizes.length === 0 ? undefined : Math.min(...knownSizes);
+			  const maxSize = knownSizes.length === 0 ? undefined : Math.max(...knownSizes);
+			  const sizeRatio = minSize === undefined || minSize === 0 || maxSize === undefined ? 1 : maxSize / minSize;
+			  const primerConcentrations = targets.map((target) => {
+			    const size = sizes.find((entry) => entry.name === target.name)?.length;
+			    let recommended = opts.primerConcentrationNm;
+			    let rationale = 'panel default; no size-based adjustment applies';
+			    if (knownSizes.length >= 2 && sizeRatio >= 2 && size !== undefined) {
+			      if (size === minSize) {
+			        recommended = Math.round(opts.primerConcentrationNm * 0.75);
+			        rationale = 'shortest amplicon in the panel; a lower share limits its competitive advantage';
+			      } else if (size === maxSize) {
+			        recommended = Math.round(opts.primerConcentrationNm * 1.5);
+			        rationale = 'longest amplicon in the panel; a higher share compensates for lower amplification efficiency';
+			      } else {
+			        rationale = 'panel default; between the shortest and longest amplicon';
+			      }
+			    }
+			    return { target: target.name, recommended_nm: recommended, rationale };
+			  });
+			  const concentrationNote = knownSizes.length >= 2 && sizeRatio >= 2
+			    ? `amplicon sizes span ${minSize}-${maxSize} bp (${round2(sizeRatio)}x); the plan lowers the shortest and raises the longest pair — a starting point, not a measured optimum`
+			    : '';
+
 			  const blockingInteractions = interactions.filter((entry) => entry.conflict && entry.cross_target);
 			  const blockingMispriming = mispriming.filter((entry) => entry.scope === 'other_templates');
 			  const blockingSizes = sizeConflicts.filter((entry) => entry.severity === 'indistinguishable');
@@ -6450,6 +7017,13 @@ window.__ModuleLoader__.load({
 			  for (const entry of blockingSizes.slice(0, 5)) {
 			    advice.push(`${entry.a} (${entry.a_length} bp) and ${entry.b} (${entry.b_length} bp) differ by only ${entry.difference_bp} bp — not resolvable on a standard gel`);
 			  }
+			  if (annealing !== null) {
+			    advice.push(`set the annealing temperature around ${annealing.recommended_c} °C (range ${annealing.range_c[0]}-${annealing.range_c[1]} °C): the lowest-Tm primer is ${annealing.limiting_primer} at ${annealing.min_primer_tm} °C`);
+			    if (!annealing.tm_spread_ok) {
+			      advice.push(`primer Tm spread is ${annealing.spread_c} °C (${annealing.min_primer_tm}-${annealing.max_primer_tm} °C) — one annealing temperature cannot be optimal for all; redesign the outlier primer(s) or use a two-step protocol`);
+			    }
+			  }
+			  if (concentrationNote !== '') advice.push(concentrationNote);
 
 			  return {
 			    compatible: blockingInteractions.length === 0 && blockingMispriming.length === 0 && blockingSizes.length === 0,
@@ -6466,10 +7040,15 @@ window.__ModuleLoader__.load({
 			    cross_template_mispriming: blockingMispriming.length,
 			    amplicons: sizes,
 			    size_conflicts: sizeConflicts,
+			    annealing,
+			    primer_concentrations: primerConcentrations,
+			    concentration_note: concentrationNote,
 			    advice,
 			    notes: [
 			      'Dimer/hairpin Tms are the same SantaLucia-1998 nearest-neighbour estimates the primer designer uses; they rank risk, they do not predict a multiplex outcome.',
 			      'Cross-template annealing is searched with a perfect 3\' tail only; own-template mispriming allows the configured mismatch tolerance.',
+			      'The annealing temperature is a rule of thumb (lowest primer Tm minus the configured offset), not a thermal-cycling optimisation; run a gradient.',
+			      'Primer concentrations are starting points chosen from amplicon-size balance, not measured optima; rebalance empirically.',
 			      'A panel that passes this check can still fail on the bench: template competition, unequal primer efficiencies and amplicon secondary structure are not modelled here.',
 			    ],
 			  };

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "dsh-molbio-panel",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Browser panel for the DeepSeek Harness Web GUI: a Molbio tab in the right sidebar that draws plasmid maps and sequence logos from workspace sequence files, using the same computation modules as the dsh-molbio-tools plugin.",
   "type": "module",
   "main": "index.mjs",
+  "engines": {
+    "node": ">=26",
+    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
+  },
   "exports": {
     ".": "./index.mjs",
     "./client": {
@@ -17,6 +21,13 @@
     "README.md"
   ],
   "dsh": {
+    "compatibility": {
+      "dshReleases": {
+        "0.2.1-rc.1": "unknown",
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "unknown"
+      }
+    },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },