Rebuild variant detail, allele grouping, and clinical controls on the allele-centric API

.github/instructions/state-management.instructions.md

@@ -84,12 +84,19 @@ const {downloadFile, downloadMultipleData, customDialogVisible, dataTypeOptions}
 
 ## Variant Coordinates (`src/composables/use-variant-coordinates.ts`)
 
-Stateless utilities for resolving variant HGVS coordinates based on display mode (raw vs mapped). Shared between ScoreSetView (variant search, labels, sequence type detection) and ScoreSetHeatmap.
+Stateless resolution of a lean variant's HGVS coordinate across two orthogonal axes: sequence
+**level** (`dna` ↔ `protein`) and **frame** (`raw` = submitted/target numbering ↔ `mapped` =
+reference numbering). `coordinateFor` is the single source of truth — every derivation (heatmap
+x/y, axis availability, labels, tooltips) resolves through it, so the (level, frame) → coordinate
+mapping lives in one place. The frame axis is load-bearing: `raw` and `mapped` are genuinely
+different coordinate systems, so flipping frame reprojects the grid, it does not merely relabel it.
+Shared between ScoreSetView (search, labels, level options) and ScoreSetHeatmap (plotting).
 
 ```ts
-const {getHgvsNt, getHgvsPro, labelForVariant, sequenceTypeOptions} = useVariantCoordinates()
-const nt = getHgvsNt(variant, useMapped) // resolved NT coordinate
-const options = sequenceTypeOptions(variants, useMapped) // [{title: 'DNA', value: 'dna'}, ...]
+const {coordinateFor, sequenceTypeOptions, resolveLevel, labelForVariant} = useVariantCoordinates()
+coordinateFor(variant, 'dna', 'mapped') // → HgvsField | null (null for protein assays — no mapped coding, mavedb-api#784)
+sequenceTypeOptions(variants, 'mapped') // → [{title: 'DNA', value: 'dna'}, ...] available for that frame
+resolveLevel(variants, 'protein', 'mapped') // → the level to display, falling back when the desired one is stranded
 ```
 
 ## Entity Cache (`src/composables/entity-cache.ts`)

docs/content/finding-data/downloading.md

@@ -8,21 +8,21 @@ Each [score set](../getting-started/key-concepts.md#score-sets) page in MaveDB i
 
 <figure markdown="span">
   ![Download buttons on a MaveDB score set page](../images/download_buttons.png)
-  <figcaption>Download options available on a score set page, including score/count CSV, mapped variants JSON, and annotated variant exports.</figcaption>
+  <figcaption>Download options available on a score set page, including score/count CSV, variant details, and annotated variant exports.</figcaption>
 </figure>
 
 ### Score and count data
 
 MaveDB allows users to download variant effect score data along with associated count data in **CSV** (Comma-Separated Values) format.
 
-The downloaded file contains the same data that was uploaded by the submitter, with an additional column for variant [URNs](../reference/accession-numbers.md) that uniquely identify each variant in MaveDB. Users may also choose to include other MaveDB-generated columns in this output, such as mapped variant HGVS strings and VRS identifiers, if available.
+The downloaded file contains the same data that was uploaded by the submitter, with an additional column for variant [URNs](../reference/accession-numbers.md) that uniquely identify each variant in MaveDB. Using the **Custom Data** option, users may also choose to include other MaveDB-generated columns in this output, such as mapped variant HGVS strings and VRS identifiers, and — where available — annotation columns for gnomAD allele frequency, Ensembl VEP consequence, ClinGen allele IDs, and ClinVar clinical significance.
 
 !!! warning
     Score and count columns are non-prescriptive and may vary between datasets. Columns may mean different things between datasets, so users should refer to the dataset methods section for details on the specific columns included in each download.
 
-### Mapped variants (VRS JSON)
+### Variant details (VRS JSON)
 
-MaveDB stores [mapped variants](../reference/variant-mapping.md) using the [GA4GH VRS](https://vrs.ga4gh.org/) standard for representing genetic variants. For datasets that have been mapped, users may download a JSON file containing all mapped variants associated with the score set. This provides a structured representation of each variant including genomic coordinates, alleles, and reference sequences.
+MaveDB represents [mapped variants](../reference/variant-mapping.md) using the [GA4GH VRS](https://vrs.ga4gh.org/) standard. For datasets that have been mapped, the **Variant Details** button downloads a [newline-delimited JSON](https://jsonlines.org/) (NDJSON) file — one record per mapped variant, the bulk counterpart of a single variant's detail page. Each record carries the assayed-level (pre-mapped) and measured (post-mapped) VRS objects, the full [GA4GH Cat-VRS](https://vrs.ga4gh.org/) categorical variant (the variant's equivalence class of related alleles), and its gnomAD, Ensembl VEP, and ClinVar annotations.
 
 ### Annotated variants (VA-Spec)
 

docs/content/finding-data/index.md

@@ -6,7 +6,7 @@ MaveDB provides several ways to discover, explore, and download MAVE datasets. W
 
 - **[Searching Datasets](searching.md)** -- Find MAVE datasets by gene name, target organism, publication, or keywords using the MaveDB search interface.
 - **[Visualizations](visualizations.md)** -- Explore variant effect data through interactive histograms, heatmaps, and 3D protein structure views on score set pages.
-- **[Downloading Data](downloading.md)** -- Download variant scores, counts, mapped variants, and annotated data in CSV, VRS JSON, and VA-Spec formats, or access a bulk archive via Zenodo.
+- **[Downloading Data](downloading.md)** -- Download variant scores, counts, variant details, and annotated data in CSV, VRS JSON, and VA-Spec formats, or access a bulk archive via Zenodo.
 - **[External Integrations](external-integrations.md)** -- Learn how MaveDB connects with ClinGen, ClinVar, gnomAD, Ensembl VEP, DECIPHER, and other resources.
 
 Looking for a specific variant? Use the [MaveMD variant search](../mavemd/variant-search.md) to look up individual variants by HGVS, ClinVar ID, dbSNP RSID, or ClinGen Allele ID.

docs/content/interpreting-annotated-variants.md

@@ -0,0 +1,98 @@
+# Interpreting annotated variants
+
+When you upload a variant to MaveDB, it is described relative to the experiment's own target sequence. Before that variant can be searched, compared to clinical databases, or interpreted in a clinical context, MaveDB does two things to it:
+
+1. **Maps** it onto standard human reference coordinates (GRCh38), and
+2. **Annotates** it with data from external resources — clinical significance (ClinVar), population frequency (gnomAD), and predicted consequences (Ensembl VEP).
+
+The result is an **annotated variant**: the original measurement, expressed across molecular levels and enriched with external evidence. This page explains what each element of an
+annotated variant represents and how they can be interpreted.
+
+!!! info "Rolling out"
+    These multi-level representations are still being deployed across MaveDB. Some published datasets may not yet have a full derived variant data set as described below.
+
+## One variant, several representations
+
+A variant can be described at three molecular levels:
+
+- **Genomic** (`g.`) — position on the chromosome.
+- **Coding** (`c.`) — position within a transcript's coding sequence.
+- **Protein** (`p.`) — the amino-acid change.
+
+MaveDB shows a variant at whichever of these levels apply. The important point is that **these levels are not all equally direct.** An assay measures a variant at one of these levels. We must *derive* all other levels from that measurement. How faithfully a level can be derived and interpreted depends on the underlying biology, which the labels below seek to capture.
+
+## Measured, resolved, convergent, and candidate
+
+Every representation of an annotated variant carries one of four labels describing how it relates to the variant the assay explicitly measured:
+
+| Label | What it means | How much to trust it |
+|---|---|---|
+| **Measured** | The level at which the variant was assayed. This is the observed experimental result. | Highest — this is the evidence itself. |
+| **Resolved** | The measured change expressed at another coordinate level: its exact coordinate partner across the coding and genomic levels, or the single protein consequence of a measured DNA change. Deterministic and precise. | High — one measured change maps to exactly one resolved representation, with no guesswork. |
+| **Convergent** | A *distinct*, real nucleotide change that produces the *same* protein change as the measured variant — a separate variant that converges on the same consequence, not the one assayed here. | Moderate — a precise variant, but a different one from what was measured. |
+| **Candidate** | One of *several possible* nucleotide spellings behind a protein-level measurement, when the DNA change that was actually assayed is unknown. | Interpret with care — MaveDB surfaces all of them and privileges none. |
+
+These four labels form a confidence ladder. **Measured** is the experimental result itself; **Resolved** is a faithful, one-to-one translation of it to another coordinate level. **Convergent** and **Candidate** are both *other* nucleotide changes that share the measured protein change — the difference is precision: a **convergent** variant is a distinct, real change that happens to encode the same amino acid, whereas a **candidate** is one of several possible spellings of a protein-level measurement whose true DNA change is unknown.
+
+## Why one protein change can produce several candidates
+
+Assays that measure variants at the **protein level** create ambiguity when their variants are expressed at the nucleotide level. Because the genetic code is redundant, a single amino-acid change can be spelled by more than one nucleotide change. The assay does not observe which one occurred.
+
+!!! example "A protein change fanning out to candidates"
+    Suppose an assay measured the protein change **p.Glu23Asp** (glutamate → aspartate).
+
+    Glutamate is encoded by `GAA` or `GAG`; aspartate by `GAT` or `GAC`. If the coding sequence uses `GAA` at this position (`c.67_69`), aspartate can be reached by **two different single-nucleotide changes**:
+
+    - **c.69A>T** → `GAT` (Asp)
+    - **c.69A>C** → `GAC` (Asp)
+
+    Both produce exactly the observed protein change, and nothing in a protein-level measurement tells you which one the underlying DNA carried. MaveDB therefore surfaces **both** as *candidates*.
+
+MaveDB shows the full set for a reason: most clinically relevant external databases serve annotations at the DNA level. Surfacing the complete candidate set allows us to link a protein level variant to all possible clinically relevant annotations.
+
+### Not everything can be reverse-translated
+
+Not every protein change can be reverse-translated. Simple **substitutions** (and single-residue deletions) can be; more complex edits — insertions, delins, and frameshifts — cannot, so a protein-only measurement of one of these shows **no** derived coding or genomic variants.
+
+For the mechanism behind candidate generation — codon enumeration, synonymous handling, transcript selection, and the intronic/exon-spanning flags — see [Reverse Translation & Projection](mapping/reverse-translation.md).
+
+## Where you will (and won't) see candidates
+
+*Where* you look changes *what* you see:
+
+- **Detail surfaces** — the MaveMD [variant page](mavemd/variant-page.md) and the score set detail panel — show the full set of representations, each with its Measured / Resolved / Convergent / Candidate label.
+- **Overview surfaces** — search results and the score set table — show only the primary representation. For a protein-only assay, the coding and genomic slots may simply be **empty** rather than showing a candidate. MaveDB does not fabricate a single DNA coordinate where only an ambiguous set exists.
+
+So a variant that appears to have no coding or genomic coordinate in a search result may still have a full set of candidates on its detail page.
+
+## Annotations across representations
+
+External annotations (ClinVar, gnomAD, Ensembl VEP) attach at the level where those resources describe variants — almost always DNA. Because a measured level and its derived siblings are different molecular descriptions, they can occasionally carry **different** annotations. When that happens, MaveDB shows them per-level rather than merging them.
+
+When annotations diverge, weigh the annotation on the **measured** level most heavily — it describes the variant that was actually assayed. A sibling representation's annotation is supporting context, not the primary signal.
+
+How annotations are attached, and how divergence is handled, is covered in [Annotation](mapping/annotation.md); for what each external resource provides, see [External Integrations](finding-data/external-integrations.md).
+
+## Identifiers
+
+MaveDB variants carry ClinGen Allele identifiers, which act as stable cross-references to other clinical genomics resources. The identifier tracks the **level of the representation**, not the level that was measured:
+
+- **Nucleotide** representations (genomic and coding) carry a **canonical-allele (CA)** identifier.
+- **Protein** representations carry a **protein-allele (PA)** identifier.
+
+Because every variant is projected up to its protein consequence, an annotated variant typically has a **PA identifier for its protein level and CA identifiers for its nucleotide representations — regardless of the level at which it was originally measured.** A variant measured at the nucleotide level still projects up to a protein representation with its own PA identifier; a protein-only measurement still receives a CA identifier for each of its nucleotide candidates.
+
+## In short
+
+- A variant is shown across genomic, coding, and protein levels. It can only be **measured** at one level. All other levels are derived.
+- A **resolved** representation is a faithful one-to-one derivation of the measured change. A **convergent** variant is a distinct real change that produces the same protein consequence. A **candidate** is one of several possible spellings of a protein measurement, and is never treated as canonical.
+- A protein-only assay can fan out to several DNA candidates — or, for edits that can't be reverse-translated, to none.
+- Trust in order: **measured**, then **resolved**, then **convergent**, then **candidate**.
+- Detail pages show the full picture; overview and search surfaces may be limited to only the primary representation.
+
+## See also
+
+- [Variant page](mavemd/variant-page.md) — reading these representations on the MaveMD clinical interface
+- [Variant mapping](reference/variant-mapping.md) — how variants are mapped to reference coordinates
+- [External Integrations](finding-data/external-integrations.md) — the ClinVar, gnomAD, and ClinGen resources behind annotations
+- [Data Formats](submitting-data/data-formats.md) — how variants are described on upload

docs/content/mapping/annotation.md

@@ -0,0 +1,38 @@
+# Annotation
+
+Once a variant has been [mapped](../reference/variant-mapping.md) and its other molecular levels [derived](reverse-translation.md), MaveDB annotates each representation with data from external resources. This is the final stage of the pipeline, and it is what connects a functional measurement to the wider clinical-genomics ecosystem.
+
+This page describes annotation as a **pipeline stage** — what is annotated, and at what grain. For what a given annotation *means* and how to weigh it, see [Interpreting Annotated Variants](../interpreting-annotated-variants.md). For a per-resource description of each external source, see [External Integrations](../finding-data/external-integrations.md).
+
+!!! info "Rolling out"
+    Annotation of derived (reverse-translated) representations is still being deployed across MaveDB. Some published datasets may not yet carry the full set of annotations described here.
+
+## Registration comes first
+
+Before annotation, each allele is registered with the [ClinGen Allele Registry](https://reg.clinicalgenome.org/) to obtain a stable **ClinGen Allele ID** (a CA identifier for nucleotide representations, a PA identifier for protein). These identifiers are the join keys MaveDB uses to look a variant up in external resources, so registration precedes the annotations that depend on it.
+
+## What gets annotated
+
+MaveDB attaches three kinds of annotation:
+
+- **Clinical significance** — classifications from [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/).
+- **Population frequency** — allele frequencies from [gnomAD](https://gnomad.broadinstitute.org/).
+- **Predicted consequence** — molecular consequence predictions from [Ensembl VEP](https://www.ensembl.org/info/docs/tools/vep/index.html).
+
+Each is attached at the level the resource describes variants, almost always DNA. See [External Integrations](../finding-data/external-integrations.md) for what each resource provides and how MaveDB links to it.
+
+## Annotation grain
+
+Annotations are attached **per representation**, not per variant. Every allele in a variant's set, the measured one and each derived (resolved, convergent, or candidate) representation, is annotated independently.
+
+This matters because a measured allele and its derived siblings are distinct molecular descriptions, so they can carry **different** annotations. When that happens, MaveDB keeps them per-level rather than merging them into one. Which annotation to prioritize in that situation is an interpretation question. For more details on interpreting annotations across representations, see [Interpreting Annotated Variants](../interpreting-annotated-variants.md#annotations-across-representations).
+
+## When annotation runs
+
+Annotation runs automatically after mapping and reverse translation, once a score set's alleles have been registered with ClinGen. When a score set is re-mapped, its annotations are refreshed against the new representations.
+
+## See also
+
+- [Interpreting Annotated Variants](../interpreting-annotated-variants.md) — what annotations mean and how to weigh divergence
+- [External Integrations](../finding-data/external-integrations.md) — per-resource detail for ClinVar, gnomAD, VEP, and ClinGen
+- [Reverse Translation & Projection](reverse-translation.md) — produces the representations that get annotated