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/utils/hgConfCatalog/hgConfCatalog.py src/hg/utils/hgConfCatalog/hgConfCatalog.py
index d92b27dfde7..4e5ee5f5e49 100755
--- src/hg/utils/hgConfCatalog/hgConfCatalog.py
+++ src/hg/utils/hgConfCatalog/hgConfCatalog.py
@@ -222,30 +222,44 @@
 }
 
 
 # ---------------------------------------------------------------------------
 # release gates: boolean flags that exist to hold a feature back
 # ---------------------------------------------------------------------------
 # These are the reason this catalog has a sunset mode.  Each was added so a
 # user-visible change could sit on master without shipping.  Ordered by age so
 # the backlog is visible at a glance.
 
 RELEASE_GATES = {
     "what": "Boolean flags introduced to ship a feature dark during a release. "
             "Temporary by intent: each should be deleted once the feature it "
             "guards is public and mirrors have had a cycle to object.",
     "vars": [
+        h("showTxCodonNumbers", "flag", "hg/hgTracks/cds.c", default="FALSE",
+          role="gate", verified=True, ticket="38298",
+          note="A second codon number in the gene-track codon mouseover, counted in the "
+               "transcript's own coordinates, for a transcript that aligns with bases the "
+               "assembly does not have.  The number the browser has always shown is counted "
+               "along the genome, so for those transcripts it disagrees with the number NCBI "
+               "reports, by one codon per three missing bases.  It affects 58 coding "
+               "transcripts on hg38's primary chromosomes but 656 on canFam3, and gets worse "
+               "the poorer the assembly.  With the gate on, such codons also draw in the "
+               "browser's existing query-insertion orange with a \"!\" after the codon "
+               "number.  Read once in txCodonNumbersEnabled(); with it off no alignment is "
+               "looked up, no codon carries a transcript number, and the rendering and the "
+               "mouseover are byte-identical to before.  Off during QA; flip to TRUE once "
+               "released."),
         h("collectionHubCopyOnWrite", "flag", "hg/lib/cart.c", default="FALSE",
           role="gate", verified=True, ticket="38273",
           note="Copy a track collection's generated hub file when the program that writes "
                "it (only hgCollection) asks for a copy, instead of on every session load.  "
                "With it off, loading any session that carries a collection copies the hub to "
                "a new trash file and registers that copy in hgcentral.hubStatus, which is "
                "where 81% of the RR's 3.1M hubStatus rows came from.  Read in "
                "cartCollectionHubCopyOnWrite() and branched on at four places in three "
                "files: cart.c makes the copy when cartRequestLocalHubCopy() was called, and "
                "skips a hub the cart already owns in copyLocalHubs(); "
                "cartCopyLocalHubsOnSessionLoad() does nothing (that one is the old behavior, "
                "and it plus its five callers in cart.c and hgSession.c go away with the "
                "gate); sessionData.c's saveTrackFile splits a hub that came from another "
                "session.  Off during QA; flip to TRUE once released."),
         h("bigNet", "flag", "hg/lib/trackHub.c", default="FALSE",