@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/palette.js

@@ -0,0 +1,785 @@
+/**
+ * JBrowse's colors, as plain data.
+ *
+ * This module is the single place a color is decided. It imports no UI toolkit,
+ * so it loads in an RPC worker, in a GPU renderer, and in an embedding app that
+ * has never heard of Material UI. `theme.ts` is a *consumer*: it takes what
+ * `resolvePalette` produces and splices it into an MUI theme, so JBrowse's own
+ * Material UI chrome and JBrowse's renderers cannot disagree about what
+ * `highlight` means.
+ *
+ * The color math below reproduces MUI's `augmentColor` exactly, because the
+ * config `theme` slot is public API shaped as MUI `ThemeOptions` and a user who
+ * writes `primary: { main: '#0D233F' }` has to keep getting the same light,
+ * dark and contrastText shades they got before. `palette.test.ts` asserts that
+ * value by value against a real MUI theme, so a drift shows up as a test
+ * failure rather than as a slightly different browser.
+ *
+ * The neutral tokens (text, background, divider, action) are JBrowse's own,
+ * declared here rather than read off MUI. They start at the values MUI happens
+ * to use, which is why the parity test passes, but they are ours: a renderer
+ * asking for "the color text is drawn in" should not have to reach into a
+ * component library to find out.
+ */
+import { colord } from '../util/colord.js';
+// ---------------------------------------------------------------------------
+// MUI-compatible color math
+//
+// Reimplemented rather than imported so this module stays toolkit-free. The
+// constants and the truncation behavior are MUI's, deliberately: see the module
+// comment and the parity test.
+// ---------------------------------------------------------------------------
+const TONAL_OFFSET = 0.2;
+const CONTRAST_THRESHOLD = 3;
+// MUI picks contrast text between the two defaults below, not between the
+// active mode's text colors, so this stays mode-independent
+const CONTRAST_DARK_TEXT = '#fff';
+const CONTRAST_LIGHT_TEXT = 'rgba(0, 0, 0, 0.87)';
+/**
+ * MUI recomposes a channel with `parseInt`, which truncates toward zero rather
+ * than rounding. Matching that is the difference between `rgb(61, 79, 101)` and
+ * `rgb(61, 79, 102)` for the default primary, so it is not a detail.
+ */
+function recompose(r, g, b, a) {
+    const [rr, gg, bb] = [r, g, b].map(Math.trunc);
+    return a < 1 ? `rgba(${rr}, ${gg}, ${bb}, ${a})` : `rgb(${rr}, ${gg}, ${bb})`;
+}
+function shiftChannels(color, fn) {
+    const { r, g, b, a } = colord(color).toRgb();
+    return recompose(fn(r), fn(g), fn(b), a);
+}
+export function lighten(color, coefficient) {
+    return shiftChannels(color, v => v + (255 - v) * coefficient);
+}
+export function darken(color, coefficient) {
+    return shiftChannels(color, v => v * (1 - coefficient));
+}
+/** Restate a color at a given opacity, as `rgba(r, g, b, a)`. */
+export function alpha(color, value) {
+    const { r, g, b } = colord(color).toRgb();
+    const a = Math.min(Math.max(value, 0), 1);
+    return `rgba(${Math.trunc(r)}, ${Math.trunc(g)}, ${Math.trunc(b)}, ${a})`;
+}
+/** WCAG relative luminance, truncated to three digits the way MUI does. */
+export function getLuminance(color) {
+    const { r, g, b } = colord(color).toRgb();
+    const [rr, gg, bb] = [r, g, b].map(channel => {
+        const v = channel / 255;
+        return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+    });
+    return Number((0.2126 * rr + 0.7152 * gg + 0.0722 * bb).toFixed(3));
+}
+export function getContrastRatio(foreground, background) {
+    const a = getLuminance(foreground);
+    const b = getLuminance(background);
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+export function getContrastText(background) {
+    return getContrastRatio(background, CONTRAST_DARK_TEXT) >= CONTRAST_THRESHOLD
+        ? CONTRAST_DARK_TEXT
+        : CONTRAST_LIGHT_TEXT;
+}
+/**
+ * Expand a color into its four shades. A shade map supplies `light`/`dark`
+ * directly from its 300/700 entries, anything else derives them by tonal
+ * offset, and `contrastText` is chosen by contrast ratio against `main`.
+ */
+export function augmentColor(input) {
+    const entry = typeof input === 'string' ? { main: input } : input;
+    const main = entry.main ?? entry[500];
+    if (!main) {
+        throw new Error(`palette color needs a \`main\` or a \`500\` shade, got ${JSON.stringify(input)}`);
+    }
+    return {
+        main,
+        light: entry.light ?? entry[300] ?? lighten(main, TONAL_OFFSET),
+        dark: entry.dark ?? entry[700] ?? darken(main, TONAL_OFFSET * 1.5),
+        contrastText: entry.contrastText ?? getContrastText(main),
+    };
+}
+// ---------------------------------------------------------------------------
+// Palette shade maps
+//
+// The handful of MUI shade values JBrowse's defaults are built from, inlined so
+// this module owns them. They are the standard Material palette stops.
+// ---------------------------------------------------------------------------
+const green = {
+    300: '#81c784',
+    400: '#66bb6a',
+    500: '#4caf50',
+    700: '#388e3c',
+    800: '#2e7d32',
+    900: '#1b5e20',
+};
+const blue = { 300: '#64b5f6', 500: '#2196f3', 700: '#1976d2' };
+const orange = {
+    300: '#ffb74d',
+    400: '#ffa726',
+    500: '#ff9800',
+    700: '#f57c00',
+    900: '#e65100',
+};
+const red = {
+    300: '#e57373',
+    400: '#ef5350',
+    500: '#f44336',
+    700: '#d32f2f',
+    800: '#c62828',
+};
+const lightBlue = {
+    300: '#4fc3f7',
+    400: '#29b6f6',
+    500: '#03a9f4',
+    700: '#0288d1',
+    900: '#01579b',
+};
+const brown = { 300: '#a1887f', 500: '#795548', 700: '#5d4037' };
+export const grey = {
+    50: '#fafafa',
+    100: '#f5f5f5',
+    200: '#eeeeee',
+    300: '#e0e0e0',
+    400: '#bdbdbd',
+    500: '#9e9e9e',
+    600: '#757575',
+    700: '#616161',
+    800: '#424242',
+    900: '#212121',
+};
+// Material's own semantic stops, one set per mode. Stated with explicit
+// light/dark shades because MUI states them that way: `warning.main` in light
+// mode is not orange[800] but the nearest value that passes 3:1 against white.
+const lightSemantics = {
+    error: { main: red[700], light: red[400], dark: red[800] },
+    warning: { main: '#ed6c02', light: orange[500], dark: orange[900] },
+    info: { main: lightBlue[700], light: lightBlue[500], dark: lightBlue[900] },
+    success: { main: green[800], light: green[500], dark: green[900] },
+};
+const darkSemantics = {
+    error: { main: red[500], light: red[300], dark: red[700] },
+    warning: { main: orange[400], light: orange[300], dark: orange[700] },
+    info: { main: lightBlue[400], light: lightBlue[300], dark: lightBlue[700] },
+    success: { main: green[400], light: green[300], dark: green[700] },
+};
+// A theme that declares no primary/secondary at all (a config `extraThemes`
+// entry, in practice) falls back to the stock Material defaults rather than to
+// JBrowse's brand colors, which is what it did when MUI owned this resolution.
+const lightBrandFallback = {
+    primary: { main: '#1976d2', light: '#42a5f5', dark: '#1565c0' },
+    secondary: { main: '#9c27b0', light: '#ba68c8', dark: '#7b1fa2' },
+};
+const darkBrandFallback = {
+    primary: { main: '#90caf9', light: '#e3f2fd', dark: '#42a5f5' },
+    secondary: { main: '#ce93d8', light: '#f3e5f5', dark: '#ab47bc' },
+};
+const lightNeutrals = {
+    text: {
+        primary: 'rgba(0, 0, 0, 0.87)',
+        secondary: 'rgba(0, 0, 0, 0.6)',
+        disabled: 'rgba(0, 0, 0, 0.38)',
+    },
+    background: { paper: '#fff', default: '#fff' },
+    divider: 'rgba(0, 0, 0, 0.12)',
+    common: { black: '#000', white: '#fff' },
+    grey,
+    action: {
+        active: 'rgba(0, 0, 0, 0.54)',
+        hover: 'rgba(0, 0, 0, 0.04)',
+        hoverOpacity: 0.04,
+        selected: 'rgba(0, 0, 0, 0.08)',
+        selectedOpacity: 0.08,
+        disabled: 'rgba(0, 0, 0, 0.26)',
+        disabledBackground: 'rgba(0, 0, 0, 0.12)',
+        disabledOpacity: 0.38,
+        focus: 'rgba(0, 0, 0, 0.12)',
+        focusOpacity: 0.12,
+        activatedOpacity: 0.12,
+    },
+};
+const darkNeutrals = {
+    text: {
+        primary: '#fff',
+        secondary: 'rgba(255, 255, 255, 0.7)',
+        disabled: 'rgba(255, 255, 255, 0.5)',
+    },
+    background: { paper: '#121212', default: '#121212' },
+    divider: 'rgba(255, 255, 255, 0.12)',
+    common: { black: '#000', white: '#fff' },
+    grey,
+    action: {
+        active: '#fff',
+        hover: 'rgba(255, 255, 255, 0.08)',
+        hoverOpacity: 0.08,
+        selected: 'rgba(255, 255, 255, 0.16)',
+        selectedOpacity: 0.16,
+        disabled: 'rgba(255, 255, 255, 0.3)',
+        disabledBackground: 'rgba(255, 255, 255, 0.12)',
+        disabledOpacity: 0.38,
+        focus: 'rgba(255, 255, 255, 0.12)',
+        focusOpacity: 0.12,
+        activatedOpacity: 0.24,
+    },
+};
+// ---------------------------------------------------------------------------
+// Static domain colors
+//
+// Colors that do not vary with the theme. Already plain strings, already
+// imported directly by worker code, kept here so every color in the system has
+// one home. `theme.ts` re-exports them, so existing imports are unaffected.
+// ---------------------------------------------------------------------------
+/** #color alignments-strand | Forward strand | Read maps to the forward strand */
+export const colorFwdStrand = '#EC8B8B';
+/** #color alignments-strand | Reverse strand | Read maps to the reverse strand */
+export const colorRevStrand = '#8F8FD8';
+/** #color alignments-pair-orientation | LR (→ ←) | Normal proper pair */
+export const colorPairLR = '#d3d3d3';
+// Below #d3d3d3, which glares on a dark track, and light enough that
+// insertions, soft clips and deletions stay darker than the read, the order the
+// light theme draws them in.
+export const colorPairLRDark = '#b0b0b0';
+/** #color alignments-pair-orientation | RL (← →) | Mates point away from each other */
+export const colorPairRL = '#0099bb';
+/** #color alignments-pair-orientation | LL (→ →) | Both mates on the forward strand */
+export const colorPairLL = '#4d9a4d';
+/** #color alignments-pair-orientation | RR (← ←) | Both mates on the reverse strand */
+export const colorPairRR = '#5555bb';
+/**
+ * #color alignments-pair-orientation | Inter-chromosomal | Mate on another chromosome
+ * #color alignments-insert-size | Inter-chromosomal | Mate on another chromosome
+ */
+// THIS SLOT AND `colorUnmappedMate` WERE CHOSEN TOGETHER, and reading either one
+// alone is how the previous pair got stuck. Both are warm, both belong to all
+// three mate-aware schemes, and at #6e4b3a / #b05a20 they sat 4.5 degrees apart
+// in hue — which left this one nowhere to go in any direction, because every
+// direction was that one:
+//
+//   more chroma at the same L*   -> dE 38.0 to unmappedMate becomes 20.7
+//   lighter                      -> dE 11.8 to it, then the greys past that
+//   darker                       -> the complaint, worse
+//   another hue                  -> the two schemes hold nine, and the widest
+//                                   gap is 91 degrees between pairLL and pairRL,
+//                                   whose midpoint reads as a second green-blue
+//
+// So it was the darkest slot in either scheme (L* 35.3 against 41.2 next) AND
+// the dullest (C* 20.4 against 34.6), which together is what "reads as a smudge"
+// means. Reported on `cancer_sv/k562_bcr_abl_split`: "the arcs for the
+// interchromosomal reads are very dark". The tell is a 2 px stroke — at that
+// weight it was the only colour in either scheme that disappeared, while as a
+// large flat read fill it was merely dull. This slot has to survive both.
+//
+// The fix is that unmappedMate left the warm family (see its own note), which
+// opens the band this now takes: L* 44.9, C* 60.1, and dE 42.2 to its nearest
+// neighbour — the pale supplementary tan — where it used to be 30.1 to a grey.
+// Contrast 5.39 on paper and 3.48 on #121212 puts it mid-pack on both grounds
+// rather than worst on either; it was 2.44 on dark, the worst in the palette.
+//
+// Hue 51.7 keeps it clear of `colorLongInsert` at 40, which is the one warm
+// neighbour that must not be confusable: red means "insert too long", and a
+// second red would read as a second statement about insert size.
+export const colorInterchrom = '#af4d19';
+/** #color alignments-insert-size | Insert larger than expected | Deletion between the mates */
+export const colorLongInsert = '#ff0000';
+/** #color alignments-insert-size | Insert smaller than expected | Insertion between the mates */
+// This slot has TWO neighbours it must stay clear of, and every past value has
+// solved one by walking into the other. They sit at opposite ends of the
+// lightness axis, which is what makes it a balance rather than a direction:
+//
+//   colorLongInsert  #ff0000   L* 53.2   C* 104.6   h  40   <- must not read as
+//   colorPairLR      #d3d3d3   L* 84.6   C*   0.0          <- must not vanish on
+//
+// 31 L* apart, so no pink can be more than about 16 from each. The history is
+// four attempts at spending that budget:
+//
+//   #ffc0cb   L* 83.6  C* 24.4  h   8   pale: red's own hue washed out, read as
+//                                       "washed-out red" beside it
+//   #ff3a8c   L* 58.2  C* 76.9  h   1   saturated: 5 L* from red, same warm end
+//                                       of the wheel, so chroma could not part
+//                                       them (review, twice)
+//   #ffbcd8   L* 83.0  C* 28.6  h 351   light: 30 L* from red -- and 1.5 L* from
+//                                       the grey baseline, separated from it by
+//                                       chroma alone
+//   #f582c0   L* 68.9  C* 52.7  h 346   this
+//
+// The third is the one to understand, because it looks like the fix and is the
+// reason this comment is long. It maximised the distance from red by spending
+// the entire budget, so it arrived at the grey. Measured against that grey it
+// is dE 28.6, the closest any categorized slot comes -- and the margin is pure
+// chroma, which is the weakest channel there is on a 1px arc stroke. It is also
+// contrast 1.56 against paper, against grey's own 1.50: a short-insert arc was
+// very nearly as faint as the concordant ones it had to be picked out from.
+// Reported as "i cant see pink short insert on grey very well", which is
+// exactly what those two numbers say.
+//
+//                        dE vs red   dE vs grey   contrast on paper
+//   #ffbcd8 (was)             93.4         28.6   1.56
+//   #f582c0 (this)            86.2         54.9   2.38
+//
+// So: 15.7 L* from red -- three times the gap the rejected saturated value had,
+// on the axis that review was about -- while nearly doubling the separation
+// from grey and half again the contrast against the page. Hue 346 keeps it on
+// the magenta side of red rather than #ffc0cb's hue 8, so what lightness cannot
+// finish, hue does.
+//
+// Both neighbours have to be re-checked together if this is touched again. It
+// is also a READ FILL, not only an arc stroke, so a value has to survive being
+// a large flat area as well as a hairline; C* 52.7 puts it in the same band as
+// colorPairLL (52.0) and colorSupplementary (42.1) rather than shouting past
+// them.
+export const colorShortInsert = '#f582c0';
+/**
+ * #color alignments-pair-orientation | Mate unmapped | Mate aligned nowhere
+ * #color alignments-insert-size | Mate unmapped | Mate aligned nowhere
+ */
+// A NON-COLOUR, at the dark end of the neutral scale on BOTH themes. It takes
+// the first half of the `readOverlap` pattern and not the second, and that split
+// is the thing to understand here.
+//
+// The half it takes is the reason that note gives for being a neutral at all:
+// "no read color is the honest answer there, which is the whole reason the span
+// is marked". An unmapped mate is the same kind of fact — nothing about the
+// pair's geometry is answerable, so a hue would claim a category where there is
+// an absence. This slot briefly took a teal in the last free hue region, which
+// worked on every number and was the wrong answer: rendered against a pileup a
+// hue reads as one more findable category beside the green LL and blue RR bars,
+// where a neutral reads as a mark that is deliberately not one of them.
+//
+// The half it does NOT take is the inversion, and the difference is EXTENT.
+// Overlap marks a SPAN INSIDE a read, so a charcoal span on a dark track is a
+// gap in a mark that should be continuous — the read looks cut, which is a claim
+// about the data. This fills a WHOLE read, which has its own boundary and the
+// rows above and below it, so a dark grey reads as a dim read and not as a hole.
+//
+// So the statement is the same on both themes and only the room differs:
+//
+//   on #ffffff  #000000  contrast 21.0. The extreme is free, because dE 36.1
+//                        from `readOverlap` #555555 is the only other dark
+//                        neutral a read fill sits beside. Near-black is not
+//                        free: #2e2e2e is dE 17.2 from that charcoal and
+//                        #3d3d3d is 10.4, so on this ground it is the extreme
+//                        or nothing.
+//   on #121212  #4a4a4a  contrast 2.11. Here the extreme collides with the
+//                        GROUND — black is 1.12 against it and so is #1e1e1e,
+//                        i.e. everything from black up to #1e1e1e sits inside
+//                        the ground's own noise and paints a hole. So the value
+//                        walks up the same axis exactly as far as it takes to be
+//                        a block and stops, at L* 31.5, still the darkest fill
+//                        in either scheme by 9.7 L* (`colorPairRR` is next).
+//
+// Judged as a swatch #3a3a3a also clears the ground, at 1.65. Rendered as a
+// pileup it does not: at a 4 px row height it carries the same weight as the
+// gaps between rows and cannot be found. A few px of row is what a value here
+// has to survive, not a 40 px square.
+//
+// White was the previous dark value, and it reads as the loudest thing in a dark
+// pileup — louder than the coloured categories it is meant to be quieter than —
+// which is the "glaring near-white blocks" failure `colorPairLRDark` already
+// exists to avoid. Going dark also drops the one real cost white carried, dE 9.4
+// to `readOverlap`'s dark #e4e4e4 — which the note that shipped it called dE 7,
+// wrongly: #e4e4e4 is L* 90.5 and white is L* 100, on a pair separated by
+// lightness alone.
+//
+// The dark end is affordable at all because this slot has the loosest
+// requirements in the palette: it is a READ FILL ONLY, in neither
+// `ARC_SLOT_CATEGORY` nor `LINKED_READ_SLOT_CATEGORY`, so it never has to
+// survive a hairline stroke.
+//
+// IGV goes further than any of this: `setPairOrientation` requires
+// `mate.isMapped()`, so an unmapped mate falls through every branch and takes
+// the default read colour. Going that far loses the one thing the category is
+// for — under insert size, tlen is 0 and would otherwise paint
+// `colorShortInsert`, a false claim — so it keeps a mark, and makes the mark a
+// non-colour.
+export const colorUnmappedMate = '#000000';
+// See colorUnmappedMate: the same dark neutral, lifted off the #121212 ground by
+// the least that still reads as a read rather than as a hole.
+export const colorUnmappedMateDark = '#4a4a4a';
+export const colorLongreadInv = '#7755bb';
+/** #color alignments-pair-orientation | Split read (inverted) | Supplementary segment on the opposite strand to its primary */
+export const colorSplitReadInversion = '#9b30b0';
+export const colorSupplementary = '#f0b878';
+// Qualitative palette for coloring reads by an arbitrary tag value (e.g. the HP
+// haplotype tag). Pale "tol_light" scheme:
+// https://cran.r-project.org/web/packages/khroma/vignettes/tol.html
+export const tagColorPalette = [
+    '#BBCCEE',
+    'pink',
+    '#CCDDAA',
+    '#EEEEBB',
+    '#FFCCCC',
+    'lightblue',
+    'lightgreen',
+    'tan',
+    '#CCEEFF',
+    'lightsalmon',
+];
+/**
+ * #color theme-colors | Feature (default) | A feature with no color of its own — no `color` slot, no BED itemRgb
+ *
+ * What an uncolored feature is painted. Lives here rather than in the display
+ * that draws most of them because it is not one display's default: the
+ * single-feature variant display resolves it through `plugins/canvas`, and the
+ * multi-sample variant display's lane bakes it into the color array its worker
+ * ships. Two copies of a color two displays are supposed to agree on is exactly
+ * the "never a fallback copy" this module exists to prevent.
+ */
+export const featureDefaultColor = 'goldenrod';
+/**
+ * #color theme-colors | UTR (default) | The untranslated ends of a gene glyph when no `utrColor` slot is set
+ *
+ * Same reasoning as featureDefaultColor: the canvas gene track and the
+ * multi-way synteny lanes both draw UTRs, and the two must be the same blue or
+ * a lane's gene models read as a different annotation from the gene track
+ * above them.
+ */
+export const utrDefaultColor = '#357089';
+/** #color theme-methylation | methylated5mC | 5-methylcytosine, methylated */
+export const methylated5mC = '#ff0000';
+/** #color theme-methylation | unmethylated5mC | 5-methylcytosine, unmethylated */
+export const unmethylated5mC = '#0000ff';
+/** #color theme-methylation | methylated5hmC | 5-hydroxymethylcytosine, methylated */
+export const methylated5hmC = '#ffc0cb';
+/** #color theme-colors | Stop codon | Stop codon in gene/CDS tracks */
+const stopCodon = '#e22';
+/** #color theme-colors | Start codon | Start codon in gene/CDS tracks */
+const startCodon = '#3e3';
+/** #color maf | Nonsynonymous codon | MAF codon view: the species' amino acid differs from the reference (nonsynonymous) */
+const codonNonsynonymous = '#e8930c';
+/** #color maf | Synonymous codon | MAF codon view: the codon differs from the reference but the amino acid is unchanged (silent) */
+const codonSynonymous = '#3a7bd5';
+/** #color maf | Stop gained | MAF codon view: a stop the reference codon is not */
+const codonStop = '#cc2222';
+/** #color alignments-indicators | Insertion | Reads carry an insertion relative to the reference */
+const insertion = '#800080';
+/** #color theme-colors | Deletion | Deletion markers in alignments */
+const deletion = '#808080';
+/** #color alignments-indicators | Soft clip | Reads are soft-clipped (clipped bases retained in the read) */
+const softclip = '#00f';
+/** #color alignments-indicators | Hard clip | Reads are hard-clipped (clipped bases removed from the read) */
+const hardclip = '#f00';
+/** #color theme-colors | Skip (intron) | Skipped regions such as introns in RNA-seq reads */
+const skip = '#009a8a';
+/**
+ * #color alignments-indicators | Overlapping segments of one molecule | Both reads of a pair, or both arms of a split read, align here — so the junction between them is this span rather than a point
+ *
+ * Deliberately NOT a hue, and deliberately outside the categorical greys.
+ * Without a mark the two segments paint over each other and the display shows a
+ * clean junction at whichever coordinate the later one starts, which is a
+ * precise claim about a breakpoint that the data does not make. Painting the
+ * span as a darker version of either segment's color says "more of that one",
+ * which is the same lie louder — on a foldback the arms are opposite-strand
+ * red and blue, and darkening whichever drew last reads as extra-inverted.
+ *
+ * So the value has one job: read as NEITHER segment. The alignments vocabulary's
+ * one neutral grey is light (`colorPairLR` #d3d3d3, and `colorPairLRDark`
+ * #b0b0b0 on the dark theme), so this sits past
+ * the dark end of them in light mode and past the light end in dark mode,
+ * which is also why it inverts rather than dimming: on a dark track background
+ * a charcoal span is the background showing through, i.e. a gap where the mark
+ * should be.
+ */
+const readOverlap = '#555555';
+/** #color theme-colors | Base modification (fwd) | Base modifications on the forward strand */
+const modificationFwd = '#c8c8c8';
+/** #color theme-colors | Base modification (rev) | Base modifications on the reverse strand */
+const modificationRev = '#c8dcc8';
+/** #color theme-colors | Muted SNP base | SNP bases muted when show-modifications coloring is on */
+const mutedSnpBase = '#888';
+// MAF bridged-row fill where the species has no alignment (à la UCSC)
+const missingData = '#ffffcc';
+const lightStringColors = {
+    stopCodon,
+    startCodon,
+    codonNonsynonymous,
+    codonSynonymous,
+    codonStop,
+    coverage: grey[400],
+    insertion,
+    deletion,
+    mafGap: deletion,
+    readOverlap,
+    softclip,
+    hardclip,
+    skip,
+    modificationFwd,
+    modificationRev,
+    mutedSnpBase,
+    missingData,
+    // vertical gridlines behind the genome
+    gridlineMinor: 'rgba(0,0,0,0.12)',
+    gridlineMajor: 'rgba(0,0,0,0.26)',
+    // a plot area's own coordinate grid, and the region boundary that has to read
+    // as a landmark through it — three steps apart on purpose, so the boundary is
+    // never mistaken for a major and the grid stays under the data
+    plotGridlineMinor: 'rgba(0,0,0,0.06)',
+    plotGridlineMajor: 'rgba(0,0,0,0.13)',
+    regionBoundary: 'rgba(0,0,0,0.42)',
+    regionSeparator: grey[600],
+    tableBorder: grey[300],
+    // hover shading over a feature
+    featureHover: 'rgba(0,0,0,0.15)',
+    // stronger shade for a hovered group (e.g. a linked-read chain), so the group
+    // reads more prominently than a single-feature hover
+    featureHoverStrong: 'rgba(0,0,0,0.4)',
+    // border accent around the click-selected feature
+    featureSelected: 'rgba(0,100,255,0.8)',
+    // blue accent for feature description labels (e.g. gene descriptions)
+    featureDescription: 'blue',
+    featureConnector: 'rgba(0, 0, 0, 0.6)',
+};
+// Dark overrides. White-on-dark reads far stronger than dark-on-white at the
+// same alpha, so the gridlines and hover shades are gentler and inverted rather
+// than reused, and the colors that would otherwise vanish are lightened.
+const darkStringColors = {
+    // above the L* 55-72 band the base colors occupy, so the SNP ticks drawn on
+    // it keep a lightness step; a mid grey inside that band hides them
+    coverage: '#cccccc',
+    gridlineMinor: 'rgba(255,255,255,0.06)',
+    gridlineMajor: 'rgba(255,255,255,0.15)',
+    plotGridlineMinor: 'rgba(255,255,255,0.05)',
+    plotGridlineMajor: 'rgba(255,255,255,0.1)',
+    regionBoundary: 'rgba(255,255,255,0.3)',
+    regionSeparator: grey[500],
+    tableBorder: '#515151',
+    featureHover: 'rgba(255,255,255,0.25)',
+    featureHoverStrong: 'rgba(255,255,255,0.4)',
+    featureSelected: 'rgba(120,180,255,0.9)',
+    // plain CSS 'blue' reads as near-black against a dark track
+    featureDescription: blue[300],
+    // a 1px light line on a dark ground reads thinner than the same line dark on
+    // white, so this runs at more ink than the light value's 0.6
+    featureConnector: 'rgba(255, 255, 255, 0.9)',
+    // drawn over a read, so it keeps the light theme's step below the read fill:
+    // #d3d3d3 to #808080 is 31 L*, #b0b0b0 to this is 33
+    deletion: '#5c5c5c',
+    // MAF gap cells sit beside match cells painted `action.disabledBackground`,
+    // which is dark here, so the gap is the lighter of the two
+    mafGap: '#c8c8c8',
+    // inverted rather than dimmed, for the reason on the light value: the mark
+    // has to be the one neutral no read category paints, and on a dark track that
+    // is the light end, clear of `colorPairLRDark` #b0b0b0
+    readOverlap: '#e4e4e4',
+};
+const lightAlignmentFill = {
+    pairLR: colorPairLR,
+    pairRL: colorPairRL,
+    pairLL: colorPairLL,
+    pairRR: colorPairRR,
+    unmappedMate: colorUnmappedMate,
+};
+// pairLR because the light #d3d3d3 reads as glaring near-white blocks;
+// unmappedMate because its black is inside the #121212 ground's own noise and
+// paints a hole (see its own note)
+const darkAlignmentFill = {
+    ...lightAlignmentFill,
+    pairLR: colorPairLRDark,
+    unmappedMate: colorUnmappedMateDark,
+};
+// ---------------------------------------------------------------------------
+// Brand colors
+// ---------------------------------------------------------------------------
+const midnight = '#0D233F';
+const grape = '#721E63';
+const forest = '#135560';
+const mandarin = '#FFB11D';
+const textHighlightYellow = '#ffe066';
+const lightgrey = '#aaa';
+const defaultBases = {
+    A: green,
+    C: blue,
+    G: orange,
+    T: red,
+    // N / ambiguous bases: muted brown, a distinct hue so it never blends into
+    // the grey coverage histogram the way mutedSnpBase does
+    N: brown,
+};
+const defaultFramesCDS = [
+    null,
+    { main: '#FF8080' },
+    { main: '#80FF80' },
+    { main: '#8080FF' },
+    { main: '#8080FF' },
+    { main: '#80FF80' },
+    { main: '#FF8080' },
+];
+const defaultFrames = [
+    null,
+    { main: '#8f8f8f' },
+    { main: '#adadad' },
+    { main: '#d8d8d8' },
+    { main: '#d8d8d8' },
+    { main: '#adadad' },
+    { main: '#8f8f8f' },
+];
+// The same order as the light greys, with the outer frames nearest the ground
+const defaultFramesDark = [
+    null,
+    { main: '#6e6e6e' },
+    { main: '#525252' },
+    { main: '#303030' },
+    { main: '#303030' },
+    { main: '#525252' },
+    { main: '#6e6e6e' },
+];
+/**
+ * The palette half of the built-in themes. `theme.ts` composes these with the
+ * display names and MUI component overrides that make up `defaultThemes`, so
+ * the preset colors are stated once.
+ */
+// The JBrowse-branded colors every built-in preset starts from. Deliberately
+// does NOT carry the string colors, alignmentFill or frames: those have light and dark
+// variants that `resolvePalette` picks off `mode`, and baking the light ones in
+// here would shadow the dark set for any theme built on top.
+const brandDefaults = {
+    primary: { main: midnight },
+    secondary: { main: grape },
+    tertiary: { main: forest },
+    quaternary: { main: mandarin },
+    highlight: { main: mandarin },
+    textHighlight: { main: textHighlightYellow },
+    bases: defaultBases,
+    framesCDS: defaultFramesCDS,
+};
+// Each palette states its colors once and, where a brand cannot survive the
+// flip, the `dark` delta. Stock needs none: measured, its dark half is the
+// light one with `mode: 'dark'` and nothing else, because the neutrals,
+// semantics and string colors already follow the mode. Minimal needs one
+// shade, grey[900] being too near the dark background to read as chrome.
+export const palettePresets = {
+    default: { ...brandDefaults },
+    stock: { ...brandDefaults },
+    minimal: {
+        ...brandDefaults,
+        primary: { main: grey[900] },
+        secondary: { main: grey[800] },
+        tertiary: { main: grey[900] },
+        dark: { primary: { main: grey[700] } },
+    },
+};
+/**
+ * The theme names from before light and dark were an axis, as the palette and
+ * mode each one meant. A stored selection, a share link, an admin's
+ * `configuration.theme`, `jbrowse-img --theme` and a saved figure spec all
+ * carry these, so they keep resolving rather than falling back to the default.
+ */
+export const legacyThemeNames = {
+    lightStock: { themeName: 'stock', mode: 'light' },
+    darkStock: { themeName: 'stock', mode: 'dark' },
+    lightMinimal: { themeName: 'minimal', mode: 'light' },
+    darkMinimal: { themeName: 'minimal', mode: 'dark' },
+};
+// indexed through hasOwn so the miss is a value rather than a lie the key cast
+// tells the checker
+function legacyEntry(name) {
+    return name !== undefined && Object.hasOwn(legacyThemeNames, name)
+        ? legacyThemeNames[name]
+        : undefined;
+}
+/**
+ * What a name and a mode mean together, with a name that predates the axis
+ * resolved to the pair it stood for. An explicit `mode` still wins — a user
+ * picking Dark over a stored `lightStock` gets dark stock, not light.
+ *
+ * `themes` is whatever map the caller looks names up in, so an admin's
+ * `extraThemes` entry taking one of the retired names wins over the alias it
+ * would otherwise shadow.
+ */
+export function resolveThemeSelection(themeName, mode, themes) {
+    if (themeName !== undefined && themes?.[themeName]) {
+        return { themeName, mode };
+    }
+    const legacy = legacyEntry(themeName);
+    return legacy
+        ? { themeName: legacy.themeName, mode: mode ?? legacy.mode }
+        : { themeName: themeName ?? 'default', mode };
+}
+/**
+ * Resolve a frame tuple. A theme's tuple replaces the default wholesale rather
+ * than splicing entry by entry onto stale shades, so slots it leaves out are
+ * filled from the default here. Consumers index by frame number and assume
+ * every slot resolves.
+ */
+function resolveFrames(entry, fallback) {
+    const source = entry ?? fallback;
+    return [
+        null,
+        ...[1, 2, 3, 4, 5, 6].map(i => {
+            const value = source[i] ?? fallback[i];
+            return value === undefined ? undefined : augmentColor(value);
+        }),
+    ];
+}
+/**
+ * Build the palette for a set of theme arguments.
+ *
+ * Only the `default` theme draws from `configTheme`. Every other named theme is
+ * a fixed preset and intentionally ignores it, which is what the picker entry
+ * "Default (from config)" means. Do not "fix" that.
+ */
+export function resolvePalette(args = {}) {
+    const { configTheme, extraThemes } = args;
+    const presets = {
+        ...palettePresets,
+        ...Object.fromEntries(Object.entries(extraThemes ?? {}).map(([k, v]) => [k, v.palette ?? {}])),
+    };
+    const selection = resolveThemeSelection(args.themeName, args.mode, presets);
+    const themeName = selection.themeName;
+    const preset = presets[themeName] ?? presets.default ?? {};
+    const declared = themeName === 'default' ? { ...preset, ...configTheme?.palette } : preset;
+    // A palette that declares a `mode` is pinned to it: an admin who registers a
+    // dark `extraThemes` entry picked its colours for dark, and the light half
+    // they never wrote is not JBrowse's to invent. A `mode` in the config `theme`
+    // slot is the opposite — the site's starting point for the one palette that
+    // merges it — so a reader's own pick wins over that.
+    const mode = preset.mode ?? selection.mode ?? configTheme?.palette?.mode ?? 'light';
+    const isDark = mode === 'dark';
+    // the palette's own dark half, over the light one it is a delta against
+    const input = isDark
+        ? { ...declared, ...declared.dark }
+        : declared;
+    const neutrals = isDark ? darkNeutrals : lightNeutrals;
+    const brandFallback = isDark ? darkBrandFallback : lightBrandFallback;
+    const semantics = isDark ? darkSemantics : lightSemantics;
+    const strings = {
+        ...lightStringColors,
+        ...(isDark ? darkStringColors : {}),
+    };
+    for (const key of Object.keys(strings)) {
+        const override = input[key];
+        if (override !== undefined) {
+            strings[key] = override;
+        }
+    }
+    const text = { ...neutrals.text, ...input.text };
+    const primary = augmentColor(input.primary ?? brandFallback.primary);
+    return {
+        ...strings,
+        mode,
+        text,
+        background: { ...neutrals.background, ...input.background },
+        divider: input.divider ?? neutrals.divider,
+        common: { ...neutrals.common, ...input.common },
+        grey: { ...neutrals.grey, ...input.grey },
+        action: { ...neutrals.action, ...input.action },
+        primary,
+        accent: input.accent ?? (isDark ? text.secondary : primary.main),
+        secondary: augmentColor(input.secondary ?? brandFallback.secondary),
+        error: augmentColor(input.error ?? semantics.error),
+        warning: augmentColor(input.warning ?? semantics.warning),
+        info: augmentColor(input.info ?? semantics.info),
+        success: augmentColor(input.success ?? semantics.success),
+        tertiary: augmentColor(input.tertiary ?? lightgrey),
+        quaternary: augmentColor(input.quaternary ?? lightgrey),
+        highlight: augmentColor(input.highlight ?? { main: mandarin }),
+        textHighlight: augmentColor(input.textHighlight ?? { main: textHighlightYellow }),
+        bases: Object.fromEntries(['A', 'C', 'G', 'T', 'N'].map(key => [
+            key,
+            augmentColor(input.bases?.[key] ?? defaultBases[key]),
+        ])),
+        frames: resolveFrames(input.frames, isDark ? defaultFramesDark : defaultFrames),
+        framesCDS: resolveFrames(input.framesCDS, defaultFramesCDS),
+        alignmentFill: {
+            ...(isDark ? darkAlignmentFill : lightAlignmentFill),
+            ...input.alignmentFill,
+        },
+    };
+}