Release 2026.3.0

.github/instructions/code-style.instructions.md

@@ -2,7 +2,7 @@
 
 ## Formatting (Prettier)
 
-The project uses Prettier for code formatting, configured in `.prettierrc.ts`:
+The project uses Prettier for code formatting, configured in `.prettierrc.json`:
 
 | Setting                 | Value    |
 | ----------------------- | -------- |

.github/instructions/copilot-instructions.md

@@ -10,7 +10,7 @@ MaveDB UI is the frontend for [MaveDB](https://mavedb.org), a database for Multi
 | ------------------ | ------------------------------------------------------- |
 | Framework          | Vue 3 (Composition API via `defineComponent` + `setup`) |
 | Language           | TypeScript (strict mode) with some legacy `.js` files   |
-| Build tool         | Vite 5                                                  |
+| Build tool         | Vite 7                                                  |
 | Package manager    | npm                                                     |
 | Component library  | PrimeVue 4 (Aura theme)                                 |
 | CSS                | Tailwind CSS 4                                          |

.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`)

.github/instructions/styling.instructions.md

@@ -15,8 +15,9 @@ Key tokens:
 
 | Token | Value | Usage |
 |-------|-------|-------|
-| `--color-sage` | `#78b793` | Primary brand color (PrimeVue: `sagePalette`) |
-| `--color-sage-dark` | `#5a9375` | Hover state for sage |
+| `--color-sage` | `#78b793` | Primary brand color for fills, borders and icons; fails WCAG AA as text (PrimeVue: `sagePalette`) |
+| `--color-sage-dark` | `#5a9375` | Hover fills; as text only at 20px bold or larger |
+| `--color-sage-strong` | `#3a654e` | Sage-colored text and links (passes AA on white and sage tints) |
 | `--color-mint` | `#a1d8c8` | Accent backgrounds |
 | `--color-orange-cta` | `#f8971d` | Warn/CTA actions (PrimeVue: `orangePalette`) |
 | `--color-danger` | `#D05353` | Destructive actions (PrimeVue: `dangerPalette`) |
@@ -56,7 +57,7 @@ Located in `src/assets/`:
 
 ## Fonts
 
-- **Body**: Raleway (`@fontsource/raleway`)
+- **Body**: Raleway (`@fontsource/raleway`, weights 400/500/600/700 and 400 italic). Import each weight file explicitly in `MvLayout.vue`: the package index ships only 400, and any missing weight is browser-synthesized. Body text sets `font-feature-settings: 'lnum'` because Raleway defaults to old-style figures; use `tabular-nums` where digits align in columns.
 - **Display/Headings**: Exo 2 (`@fontsource/exo-2`, weights 700/800/900)
 
 ## Layout Patterns

.github/instructions/vue-components.instructions.md

@@ -138,6 +138,7 @@ Key composables:
 - `use-calibration-editor.ts` — draft calibration state, dirty tracking, validation, and save logic
 - `use-calibration-dialog.ts` — calibration editor dialog open/close state
 - `use-json-file-field.ts` — JSON file upload field with parsing and validation
+- `use-unsaved-changes-guard.ts` — confirms before a route change, reload or reset discards form input (creators and editors). An exception to the no-lifecycle-coupling rule: it registers a route-leave guard and a `beforeunload` listener
 - `entity-cache.ts` — shared reactive cache for entity lookups (score sets, experiments) with TTL and deduplication
 - `scoped-id.ts` — generates unique IDs for form accessibility
 

.prettierignore

@@ -1,5 +1,6 @@
 # Derived files
 /dist/
+/src/schema/openapi.d.ts
 
 # MkDocs documentation (Prettier breaks admonitions and collapsible syntax)
 /docs/

.prettierrc.json

@@ -0,0 +1,13 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": false,
+  "endOfLine": "lf",
+  "printWidth": 120,
+  "quoteProps": "as-needed",
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "useTabs": false,
+  "vueIndentScriptAndStyle": false
+}

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/external-integrations.md

@@ -37,6 +37,8 @@ Mapped variants in MaveDB are cross-referenced with the [gnomAD database](https:
 
 A variant's frequency is displayed on its [variant page](../mavemd/variant-page.md), and is available in bulk through the `gnomad` namespace of the variant data download. Each frequency is matched by ClinGen allele ID, so it is a direct assertion about that variant rather than an aggregate over related variants. Variants absent from gnomAD show no frequency.
 
+A protein change has no gnomAD record of its own. For a protein-level measurement, the score set's variant panel shows the record of the nucleotide variant encoding that change with the highest FAF95, the frequency ACMG BA1/BS1 thresholds apply to. The record is labelled with that variant, and every encoding variant's record is listed alongside it. Frequencies are shown exactly as gnomAD records them and are never summed.
+
 ## Ensembl VEP
 
 MaveDB uses the [Ensembl Variant Effect Predictor (VEP)](https://www.ensembl.org/info/docs/tools/vep/index.html) to annotate mapped variants with predicted functional consequences, including effects on protein coding sequences, splicing, and regulatory regions. These VEP annotations are displayed alongside variant effect scores on score set pages, providing additional context for interpreting the functional impact of each variant.

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/finding-data/searching.md

@@ -8,28 +8,30 @@ MaveDB provides a search interface to help users find relevant datasets. You can
 ## Search interface
 
 <figure markdown="span">
-  ![MaveDB search interface showing target filters and keyword search](../images/search_interface.png)
-  <figcaption>The MaveDB search interface with target filters and keyword search. Results are grouped by experiment, with matching score sets listed underneath.</figcaption>
+  ![MaveDB search interface showing the filter sidebar and keyword search](../images/search_interface.png)
+  <figcaption>The MaveDB search interface with target, publication, and keyword filters. Results are grouped by experiment, with matching score sets listed underneath.</figcaption>
 </figure>
 
-The search interface allows users to filter datasets based on various criteria.
+The search interface presents a filter sidebar on the left (a slide-out drawer on smaller screens) alongside the results. Each filter is a collapsible section; the **Gene** and **Organism** sections are expanded by default, and the rest can be opened as needed.
 
-In the **Target** tab, users can filter datasets by the following fields drawn from user-submitted [target](../submitting-data/targets.md) metadata:
+The following sections filter datasets by user-submitted [target](../submitting-data/targets.md) metadata:
 
-- **Target name** -- The name of the target associated with the dataset (usually a gene or protein).
-- **Target type** -- The type of target (e.g., protein-coding gene, non-coding RNA, regulatory element).
+- **Gene** -- The name of the target associated with the dataset (usually a gene or protein).
 - **Organism** -- The organism from which the target is derived.
+- **Target type** -- The type of target (e.g., protein-coding gene, non-coding RNA, regulatory element).
 - **Target accession** -- The accession number or identifier for the target (e.g., Ensembl ID, RefSeq ID).
 
-In the **Publication** tab, users can filter datasets by the following publication-related fields:
+These sections filter by publication metadata:
 
 - **Author** -- The author of any publication associated with a dataset.
-- **Database** -- The database of any publication associated with a dataset (e.g., PubMed, CrossRef).
 - **Journal** -- The journal in which any publication associated with a dataset was published.
+- **Publication database** -- The database that indexes an associated publication (e.g., PubMed, CrossRef).
+
+The **Keywords** section filters by [controlled-vocabulary keywords](../reference/controlled-vocabulary.md), grouped by category, that describe how an assay was performed.
 
-Users may also enter keywords into the search bar to perform a full-text search across all dataset metadata fields, including target metadata, publication metadata, [assay facts](../reference/assay-facts.md), and score set metadata. Note that search filters are additive: datasets must meet **all** specified criteria to appear in the results.
+Separately, the **search bar** at the top of the page runs a full-text search across all dataset metadata fields, including target metadata, publication metadata, [assay facts](../reference/assay-facts.md), and score set metadata. Filters and the search term are additive: datasets must meet **all** specified criteria to appear in the results, and any filters you have applied appear as removable chips beneath the search bar.
 
-Results are grouped by [experiment](../getting-started/key-concepts.md#experiments), with all matching [score sets](../getting-started/key-concepts.md#score-sets) listed under each experiment.
+Results are grouped by [experiment](../getting-started/key-concepts.md#experiments), with all matching [score sets](../getting-started/key-concepts.md#score-sets) listed under each experiment. Use the **Sort by** control above the results to order them by most recent, most variants, or title (A--Z).
 
 !!! note
     Search results update in real time as you modify your criteria, but they are limited to the first 100 results for performance reasons. If your search returns more than 100 results, try refining your criteria further.

docs/content/finding-data/visualizations.md

@@ -62,7 +62,7 @@ The custom view gives users full control over the histogram. Available options i
 
 The heatmap provides a two-dimensional view of variant effect scores across the target sequence, with positions along the horizontal axis and substitutions along the vertical axis. This visualization is particularly useful for identifying positional patterns in variant effects.
 
-When variants are provided at the nucleotide level, users can toggle between nucleotide and amino acid views using the controls below the heatmap. In amino acid view, residues are ordered by hydrophobicity using the [Kyte-Doolittle scale](http://www.sciencedirect.com/science/article/pii/0022283682905150) and grouped by chemical class based on values from [Enrich2](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-017-1272-5/figures/1).
+The **Coordinate system** control in the heatmap's header switches between nucleotide and amino acid positions. The **Submitted variants / Reference variants** toggle at the top of the page chooses between the coordinates the researchers submitted, numbered against the assay's own target sequence, and the same variants mapped onto standard reference sequences; with reference variants shown, the heatmap can be drawn in cDNA, genomic, or amino acid coordinates. In amino acid view, residues are ordered by hydrophobicity using the [Kyte-Doolittle scale](http://www.sciencedirect.com/science/article/pii/0022283682905150) and grouped by chemical class based on values from [Enrich2](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-017-1272-5/figures/1).
 
 Each cell represents a specific variant at a given position. Color intensity indicates the variant effect score, and wild-type variants are shown in yellow. Hovering over a cell reveals the variant's score, classification (if applicable), and [HGVS](../submitting-data/data-formats.md) notation. For long target sequences, you can scroll horizontally to explore the full heatmap.
 
@@ -75,7 +75,7 @@ When a baseline score is available from a [score calibration](../reference/score
 
 ## Protein structure viewer
 
-The protein structure viewer provides an interactive 3D view of variant effect scores mapped onto a protein structure using [Mol\*](https://molstar.org/). This visualization is available when the score set's target can be linked to a UniProt accession — either because the target was defined with a UniProt identifier, or because MaveDB was able to match the target sequence to a UniProt entry during [variant mapping](../reference/variant-mapping.md). If you don't see the structure viewer for your score set, the target may not have a matching UniProt record.
+The protein structure viewer provides an interactive 3D view of variant effect scores mapped onto a protein structure using [Mol\*](https://molstar.org/). This visualization is available when the score set's target can be linked to a UniProt accession — either because the target was defined with a UniProt identifier, or because MaveDB was able to match the target sequence to a UniProt entry during [variant mapping](../reference/variant-mapping.md). Open it with **View on protein structure** below the heatmap. If you don't see that link for your score set, the target may not have a matching UniProt record.
 
 The viewer displays a side-by-side heatmap and 3D structure sourced from the [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/), with a color gradient applied based on the mean variant effect score at each position. Users can: