← Back to devlog

2026-07-04 — v23 primer design + Tm + in-silico PCR

July 4, 2026

Work unit 4: the Primer panel lets you enter a forward and a reverse primer, instantly see Tm / GC% / hairpin risk / self-dimer scores computed with the SantaLucia 1998 nearest-neighbor parameters, search the loaded sequence for binding sites (mismatch-tolerant, strict 3′ end), and predict PCR amplicons — all in-browser, nothing uploaded. This closes the Sanger-review → primer-design → PCR-validation loop without a context switch to another tool.

What changed

• Nearest-neighbor Tm library (src/primers/tm.ts). Implements the SantaLucia 1998 unified parameter set (all 16 dinucleotide ΔH°/ΔS° values, terminal initiation penalties, R × ln(c_T/4) entropy correction, and a Marmur–Schildkraut salt correction: Tm += 16.6 × log₁₀([Na⁺])). Default conditions: 250 nM primer, 50 mM NaCl. Also exports computeGC (IUPAC-aware), computeHairpinTm (stem-loop scan, ≥ 3 bp stem / ≥ 3 bp loop), computeSelfDimerScore (max contiguous complement run in anti-parallel alignment), and computePrimerFlags (length, GC%, Tm, hairpin, self-dimer, 3′ homopolymer, 3′ G/C clamp).
• Binding-site search (src/primers/binding.ts). findPrimerBindingSites slides the primer (and its reverse-complement for reverse-strand search) across the template, counting mismatches with a full IUPAC compatibility table. The last THREE_END_STRICT = 3 bases of the primer must match perfectly (any 3′ mismatch immediately rejects the site). Returns 1-based coordinates to match the VCF / lab convention used by the rest of the app.
• In-silico PCR engine (src/primers/pcr.ts). predictAmplicons pairs every forward site with every reverse site, emitting a linear amplicon when the reverse site is downstream of the forward site, or a circular wrap-around amplicon when circular = true and the primer positions cross the origin. Results are sorted by ascending size then ascending total mismatches. ampliconToFasta serialises the top amplicon to standard FASTA (80-char line wrap, header includes both primer names, size, coordinates, and [circular wrap] tag when applicable).
• Shared types (src/types/primer.ts). Defines PrimerEntry, PrimerBindingSite, PredictedAmplicon, and PrimerPairResult — the data contracts that flow between the math layer, the search engine, and the DOM component.
• Primer panel UI (src/components/PrimerPanel.ts). Two primer input rows (name + sequence), each with a live stat card (Tm, GC%, hairpin Tm, self-dimer score, length, quality flags) that updates on every keystroke without a Run click. "Run in-silico PCR" fires the binding search and amplicon prediction. Results are split into a "Binding Sites" table (primer name, strand, 1-based start/end, mismatch count) and a "Predicted Amplicons" table (rank, size, coordinates, total mismatches). "Export FASTA" downloads the top amplicon with a complete FASTA header. All computation happens in the parent (TraceViewer) — the panel dispatches a run-pcr custom event and receives rendered results back via renderPrimerResults.
• TraceViewer wiring (src/components/TraceViewer.ts). Imports PrimerPanel, findPrimerBindingSites, and predictAmplicons. The run-pcr event handler extracts the current display-trace sequence (strand-corrected + edited), runs binding search on both strands, predicts amplicons, and calls renderPrimerResults. The panel is cleared by syncContigPanel (which fires on every workspace change) so stale results never persist across trace loads.
• Full light + dark theme (src/style.css). --color-primer-* design tokens (14 light, 14 dark), covering panel background, border, title, forward/reverse pill labels, stat text, quality-flag chips (amber warning, green OK), table header, and table border. The primer panel uses a purple accent distinct from the reference panel (sky-blue) and the contig panel (deep-blue).

Spec grounding

• docs/specs/09-primer-design-and-tm.md
• docs/specs/10-in-silico-pcr.md

Tests

Design decisions

• No new npm dependencies. The entire Tm calculator, binding search, and PCR engine are pure TypeScript — no bioinformatics library needed. The SantaLucia 1998 parameter table is embedded as a 16-entry constant (≈ 50 lines).
• 3′ strict-end rule. The last three bases of every primer must match perfectly — any 3′ mismatch immediately rejects the site. This mimics the biological reality that DNA polymerase extension requires a matched 3′ terminus, and prevents spurious partial matches from polluting the results.
• Live stats without clicking Run. Tm / GC% / hairpin / self-dimer update on every keystroke using the same pure-TS functions as the test suite. This makes the panel feel interactive rather than batch-oriented.
• Amplicon results not encoded in permalink. A predicted amplicon sequence (up to 5 000 bp) would far exceed the 1 800-character URL-hash guardrail. Users re-run PCR from the panel after re-loading the trace — the primer sequences themselves are short enough to encode in a future permalink extension.
• Privacy preserved. All primer sequences, binding searches, and amplicon predictions happen locally. The hint text in the panel reads "all in-browser, nothing uploaded" — matching the privacy language used across the reference-alignment and contig-assembly panels.