68b9911e4c156cd1346fde5c957434b1a8780d1c
max
  Wed Sep 9 08:49:07 2026 -0700
Show the transcript's own codon number where it differs from the genomic one

The gene tracks count codons along the genome.  A RefSeq transcript is a
sequence in its own right, so where it has an insertion or a deletion relative
to the assembly, every codon 3' of that point gets a different number here than
the sequence provider gives it, one codon per three bases.  DNM1 on canFam3 is
the reported case: the transcript carries 21 bases canFam3 does not, so our
p.249 is NCBI's p.256.  Neither number is wrong, but HGVS c./p. is defined on
the transcript, so the number people quote is the one we were not showing.

The genomic number and amino acid are unchanged.  Codons whose two numbers
disagree now draw in the existing CDS_QUERY_INSERTION orange with a "!" after
the codon number, and their mouseover adds the transcript number plus a link to
a new FAQ entry.  Both directions of indel are covered, and so is the case
where the alignment does not reach the start of the CDS (801 transcripts on
hg38), which needs the transcript's own CDS annotation as the anchor rather
than the alignment.

Numbers come from the transcript alignment, ncbiRefSeqPsl or refSeqAli, which
is the same source hgvsMapToGenome already uses, so the browser now agrees with
its own position search.  Two queries per table per window, on the bin index,
and only at zoomedToCdsColorLevel, where the mouseover carrying the numbers is
drawn: on and off are within noise at every zoom.

Gated by showTxCodonNumbers in hg.conf, default off, catalogued as a release
gate.  With it off nothing is looked up and the rendering and mouseover are
byte-identical to before.

refs #38298

diff --git src/hg/makeDb/trackDb/human/refSeqComposite.html src/hg/makeDb/trackDb/human/refSeqComposite.html
index f485bd60d9e..1459a745807 100644
--- src/hg/makeDb/trackDb/human/refSeqComposite.html
+++ src/hg/makeDb/trackDb/human/refSeqComposite.html
@@ -135,31 +135,36 @@
 <p>
 The item labels and codon display properties for features within this track can be configured 
 through the check-box controls at the top of the track description page. To adjust the settings 
 for an individual subtrack, click the wrench icon next to the track name in the subtrack list.</p>
 <ul>   
   <li>
   <strong>Label:</strong> By default, items are labeled by gene name. Click the appropriate Label 
   option to display the accession name or OMIM identifier instead of the gene name, show all or a 
   subset of these labels including the gene name, OMIM identifier and accession names, or turn off 
   the label completely.</li>
   <li>
   <strong>Codon coloring:</strong> This track has an optional codon coloring feature that 
   allows users to quickly validate and compare gene predictions. To display codon colors, select the
   <em>genomic codons</em> option from the <em>Color track by codons</em> pull-down menu. For more 
   information about this feature, go to the <a href="../goldenPath/help/hgCodonColoring.html" 
-  target="_blank">Coloring Gene Predictions and Annotations by Codon</a> page.</li>
+  target="_blank">Coloring Gene Predictions and Annotations by Codon</a> page.
+  Codons are counted along the genome, so where a RefSeq transcript's own sequence differs from
+  the assembly by an insertion or a deletion, the codon number shown here differs from the one
+  NCBI reports for that transcript. Those codons are drawn in orange with a "!" after the codon
+  number, and their mouseover gives both numbers; the RefSeq Alignments and RefSeq Diffs
+  subtracks show the underlying difference.</li>
 </ul>
 
 <p>The <em>RefSeq Diffs</em> track contains five different types of inconsistency between the
 reference genome sequence and the RefSeq transcript sequences. The five types of differences are
 as follows:
 <ul>
   <li>
    <em>mismatch</em> &ndash; aligned but mismatching bases, plus HGVS g. 
        to show the genomic change required to match the transcript and HGVS c./n. 
        to show the transcript change required to match the genome.</li>
   <li>
    <em>short gap</em> &ndash; genomic gaps that are too small to be introns (arbitrary cutoff of
 	 &lt; 45 bp), most likely insertions/deletion variants or errors, with HGVS g. and c./n. 
 	showing differences.</li>
   <li>