@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/color/index.js

@@ -72,7 +72,7 @@ export function makeContrasting(foreground, background = 'white', minContrastRat
     }
     return best;
 }
-export { isNamedColor, namedColorToHex } from './cssColorsLevel4.js';
+export { CSS_COLOR_NAMES, isNamedColor, namedColorToHex, } from './cssColorsLevel4.js';
 // The (lightness, chroma) tiers randomColor picks between, in OKLCH. Values are
 // in the band a hand-built categorical palette occupies — bright enough to tell
 // apart, dark enough that black text over one still reads, and never near
@@ -81,7 +81,10 @@ export { isNamedColor, namedColorToHex } from './cssColorsLevel4.js';
 // What a value-less feature is painted. Neutral and unsaturated on purpose: it
 // has to read as "not in a category" beside a palette whose every member is
 // equally light and equally colorful, so it cannot be one more hue.
-const NO_CATEGORY_COLOR = '#afafaf';
+export const NO_CATEGORY_COLOR = '#afafaf';
+// What a colour declaration paints where it reads nothing it can colour, so a
+// misconfiguration surfaces rather than passing for the no-category grey.
+export const MISCONFIGURED_COLOR = '#808080';
 const RANDOM_COLOR_TIERS = [
     { lightness: 0.66, chroma: 0.15 },
     { lightness: 0.56, chroma: 0.14 },
@@ -175,8 +178,8 @@ export function relight(color, lightnessShift, chromaScale = 1) {
  *
  * A value that is absent gets NO_CATEGORY_COLOR rather than a hue, and that is
  * the difference between this being usable on real data and not. The everyday
- * caller is the Color-by-attribute dialog, which writes
- * `jexl:randomColor(get(feature,'<attr>'))` over a whole track — and most files
+ * caller is a `jexl:randomColor(get(feature,'<attr>'))` color slot over a
+ * whole track — and most files
  * have the attribute on some features and not others, so most of the time this
  * is handed `undefined`. It used to throw on that (`str.length` of undefined),
  * once per feature, and what a reader saw was every unlabelled feature in one

package/esm/util/colorBits.d.ts

@@ -1,5 +1,7 @@
-import type { Color } from './color-bits/index.ts';
+import { abgrToCssRgba } from '@jbrowse/render-core/marks/colorFill';
 import type { Feature } from './simpleFeature.ts';
+export { abgrToCssRgba };
+export { isCssColor, parseCssColorOr } from './cssColorParse.ts';
 export { alpha, blend, darken, formatHEX, formatHEXA, formatRGBA, getAlpha, getBlue, getGreen, getLuminance, getRed, lighten, newColor, parse, toHSLA, toRGBA, } from './color-bits/index.ts';
 export type { Color } from './color-bits/index.ts';
 /**
@@ -17,7 +19,6 @@ export declare function featureItemRgb(raw: unknown): string | undefined;
  * undefined if it declares none.
  */
 export declare function featureBedColor(feature: Feature): string | undefined;
-export declare function parseCssColorOr(color: string, fallback: Color): Color;
 export declare function parseCssColor(color: string | undefined | null): number;
 export declare function cssColorToNormalizedRgb(color: string): [number, number, number];
 export declare function cssColorToRgb(color: string): [number, number, number];
@@ -35,5 +36,4 @@ export declare function abgrRed(c: number): number;
 export declare function abgrGreen(c: number): number;
 export declare function abgrBlue(c: number): number;
 export declare function abgrAlpha(c: number): number;
-export declare function abgrToCssRgba(c: number): string;
 export declare function cssColorToNormalizedRgba(color: string): [number, number, number, number];

package/esm/util/colorBits.js

@@ -1,5 +1,8 @@
-import { getAlpha, getBlue, getGreen, getRed, newColor, parse, } from './color-bits/index.js';
-import { namedColorToHex } from './color/cssColorsLevel4.js';
+import { abgrToCssRgba } from '@jbrowse/render-core/marks/colorFill';
+import { getAlpha, getBlue, getGreen, getRed, newColor, } from './color-bits/index.js';
+import { bedTriple, parseCssColorOr } from './cssColorParse.js';
+export { abgrToCssRgba };
+export { isCssColor, parseCssColorOr } from './cssColorParse.js';
 export { alpha, blend, darken, formatHEX, formatHEXA, formatRGBA, getAlpha, getBlue, getGreen, getLuminance, getRed, lighten, newColor, parse, toHSLA, toRGBA, } from './color-bits/index.js';
 // Magenta sentinel for invalid input. User-written jexl color callbacks can
 // legitimately return undefined (e.g. when a feature lacks the field they
@@ -7,10 +10,6 @@ export { alpha, blend, darken, formatHEX, formatHEXA, formatRGBA, getAlpha, getB
 // Returning magenta makes the bad slot visually obvious without breaking the
 // rest of the render.
 const INVALID_COLOR = newColor(255, 0, 255, 255);
-// A bare BED color triple ("255,0,0"), which is not a CSS color but is what
-// BED-family adapters put on the feature verbatim. The spec has no spaces, but
-// tolerate them rather than silently ignoring an otherwise-usable color.
-const BED_TRIPLE = /^(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})$/;
 // UCSC's convention is that a color of "0" means "no color specified", and plain
 // BED12 files fill the column with that placeholder (often spelled as the
 // all-zero triple) rather than omitting it — every itemRgb in our own
@@ -18,17 +17,6 @@ const BED_TRIPLE = /^(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})$/;
 // ordinary BED12 track solid black, so read them as absent. A file that really
 // wants black can say so with an explicit `color` slot.
 const BED_TRIPLE_UNSET = /^0(,0,0)?$/;
-/**
- * Normalize a bare BED color triple to canonical "r,g,b", or undefined if the
- * string isn't one. Each component must be in range: the underlying parser
- * masks to 8 bits, so a bogus "999,0,0" would otherwise *wrap* to 231 and paint
- * a plausible-looking but wrong color rather than being caught.
- */
-function bedTriple(str) {
-    const m = BED_TRIPLE.exec(str.trim());
-    const rgb = m?.slice(1, 4).map(Number);
-    return rgb?.every(n => n <= 255) ? rgb.join(',') : undefined;
-}
 /**
  * One raw attribute value as a usable BED color, or undefined when it isn't
  * one. Deliberately strict: this feeds an *automatic* coloring path, so a value
@@ -73,27 +61,6 @@ export function featureBedColor(feature) {
     }
     return found;
 }
-// Resolve a CSS color string to a Color: honors named colors, `transparent`,
-// and bare BED color triples, and returns `fallback` on malformed-but-nonempty
-// input. `parse` throws on e.g. an empty "rgb()"; callers pass a fallback so one
-// bad per-feature color can't crash a whole render/RPC. An out-of-range triple
-// is left to throw into `fallback` (magenta) rather than wrapping to a wrong
-// color — the same rule featureItemRgb applies, so a jexl callback reading an
-// itemRgb column and the automatic path agree on what counts as a color.
-export function parseCssColorOr(color, fallback) {
-    const str = color.trim().toLowerCase();
-    if (str === 'transparent') {
-        return newColor(0, 0, 0, 0);
-    }
-    try {
-        const hex = namedColorToHex(str);
-        const triple = bedTriple(str);
-        return parse(hex ? hex : triple ? `rgb(${triple})` : str);
-    }
-    catch {
-        return fallback;
-    }
-}
 export function parseCssColor(color) {
     if (typeof color !== 'string' || color.length === 0) {
         return INVALID_COLOR;
@@ -118,9 +85,22 @@ export function cssColorToRgba(color) {
 export function packAbgr(r, g, b, a) {
     return ((a << 24) | (b << 16) | (g << 8) | r) >>> 0;
 }
+// A packer resolves the same few strings once per primitive, so the parse is
+// cached by string. Capped, because BED itemRgb triples are unbounded.
+const ABGR_CACHE_LIMIT = 4096;
+const abgrByCss = new Map();
 export function cssColorToABGR(color) {
+    const cached = abgrByCss.get(color);
+    if (cached !== undefined) {
+        return cached;
+    }
     const c = parseCssColor(color);
-    return packAbgr(getRed(c), getGreen(c), getBlue(c), getAlpha(c));
+    const packed = packAbgr(getRed(c), getGreen(c), getBlue(c), getAlpha(c));
+    if (abgrByCss.size >= ABGR_CACHE_LIMIT) {
+        abgrByCss.clear();
+    }
+    abgrByCss.set(color, packed);
+    return packed;
 }
 // Replace the alpha byte of an ABGR-packed u32, keeping its RGB. RGB already
 // occupies the low 24 bits (b<<16 | g<<8 | r), so this is a mask + or — no
@@ -143,7 +123,6 @@ export function normalizedRgbToCss(c) {
 export function normalizedRgbToCssRgba(c, alpha) {
     return `rgba(${Math.round(c[0] * 255)},${Math.round(c[1] * 255)},${Math.round(c[2] * 255)},${alpha})`;
 }
-// Set fillStyle from an ABGR-packed u32.
 export function setAbgrFill(ctx, c) {
     ctx.fillStyle = abgrToCssRgba(c);
 }
@@ -165,10 +144,6 @@ export function abgrBlue(c) {
 export function abgrAlpha(c) {
     return (c >>> 24) & 0xff;
 }
-// Format an ABGR-packed u32 as a CSS rgba() string.
-export function abgrToCssRgba(c) {
-    return `rgba(${abgrRed(c)},${abgrGreen(c)},${abgrBlue(c)},${abgrAlpha(c) / 255})`;
-}
 export function cssColorToNormalizedRgba(color) {
     const c = parseCssColor(color);
     return [

package/esm/util/colorRamp.d.ts

@@ -1,4 +1,5 @@
-import type { GradientStop } from '../ui/SvgGradientLegend.tsx';
+import type { RampStop } from '../ui/colorScale.ts';
+import type { ColorSchemeName } from './colorSchemes.ts';
 /** One evenly-spaced ramp stop: 8-bit red, green, blue, alpha. */
 export type ColorRampStop = readonly [number, number, number, number];
 /**
@@ -8,6 +9,27 @@ export type ColorRampStop = readonly [number, number, number, number];
  * stops.
  */
 export declare const VIRIDIS_STOPS: readonly ColorRampStop[];
+/**
+ * #api
+ * Whether a named ramp runs dark at its low end, drawn over white: viridis
+ * and its siblings do, juicebox, fall, reds and blues do not.
+ */
+export declare function darkAtLowEnd(scheme: ColorSchemeName): boolean;
+/**
+ * #api
+ * The domain a continuous colour scale spans: each end `min` or `max` pins,
+ * else the extent's, ascending, since a span has no direction and `reverse`
+ * is the ramp's. An open end stops at a pinned one rather than crossing it,
+ * and an extent holding no value (`[Infinity, -Infinity]`) spans [0, 1].
+ */
+export declare function rampDomain(min: number | undefined, max: number | undefined, extent: readonly [number, number]): [number, number];
+/**
+ * #api
+ * The stops a continuous colour scale samples: `range`'s CSS colours where it
+ * lists any, else the named `scheme`, viridis while that is unset, turned
+ * round under `reverse`.
+ */
+export declare function colorRampStops({ range, scheme, reverse, }: RampDeclaration): readonly ColorRampStop[];
 /**
  * #api
  * The color at `t` in `[0, 1]` across a list of EVENLY SPACED stops, linearly
@@ -22,16 +44,38 @@ export declare function sampleColorRamp(stops: readonly ColorRampStop[], t: numb
  * texture both GPU backends upload and the Canvas2D twins index — entry `i` is
  * the color at `t = i / (N - 1)`. N comes off the shader that samples it, so
  * the table and `rampColor`'s texel mapping cannot disagree.
+ *
+ * The table is always straight. A diverging ramp whose middle belongs at a
+ * value off the centre of the domain reads it through `rampMidT`, the shader's
+ * rule and its generated twin, so the middle follows a moving domain without a
+ * new table.
  */
 export declare function buildColorRampLut(stops: readonly ColorRampStop[]): Uint8Array<ArrayBuffer>;
+/**
+ * #api
+ * A continuous colour scale's ramp as a config declares it.
+ */
+export interface RampDeclaration {
+    range?: readonly string[];
+    scheme?: ColorSchemeName;
+    reverse?: boolean;
+}
+/**
+ * #api
+ * The {@link buildColorRampLut} table a ramp declaration asks for, the same
+ * `Uint8Array` for the same declaration, since a GPU backend re-uploads its
+ * ramp texture when the identity changes and a render state is rebuilt far
+ * more often than its ramp.
+ */
+export declare function rampLutOf(ramp: RampDeclaration): Uint8Array;
 /**
  * #api
  * `n` evenly spaced legend stops read straight out of a
  * {@link buildColorRampLut} byte table — the same 256×1 RGBA array
  * `uploadColorRampLut` hands the GPU and the Canvas2D fillStyle LUTs index —
- * formatted for `SvgGradientLegend`. It holds one claim by construction: the
- * swatch at bar fraction `t` is byte-identical to the ramp entry at `t` on
- * both backends. Alpha rides `opacity` (the juicebox fade), never baked into
+ * as the stops of a `RampScale`. It holds one claim by construction: the
+ * swatch at bar fraction `t` is byte-identical to the ramp entry both backends
+ * read at `t`, through the ramp's middle stop at `midNorm` (`rampMidT`). Alpha rides `opacity` (the juicebox fade), never baked into
  * the color string.
  */
-export declare function stopsFromRampLut(lut: Uint8Array, n: number): GradientStop[];
+export declare function stopsFromRampLut(lut: Uint8Array, n: number, midNorm?: number): RampStop[];

package/esm/util/colorRamp.js

@@ -1,18 +1,15 @@
 import { COLOR_RAMP_LUT_ENTRIES } from '@jbrowse/render-core/colorRampLut';
-// Viridis full 256-color hex spec, kept whole so a LUT built from these stops
-// carries the smooth perceptually-uniform gradient rather than an
-// interpolation over a subset. Lived in the hic plugin until wiggle density
-// gained the same named ramp; both build their 256×1 GPU/Canvas2D LUTs from
-// this one table.
+import { rampMidT } from '@jbrowse/render-core/shaders/colorRampLut';
+import { cssColorToRgba } from './colorBits.js';
+import { DEFAULT_COLOR_SCHEME } from './colorSchemes.js';
 const VIRIDIS_HEX_SPEC = '44015444025645045745055946075a46085c460a5d460b5e470d60470e6147106347116447136548146748166848176948186a481a6c481b6d481c6e481d6f481f70482071482173482374482475482576482677482878482979472a7a472c7a472d7b472e7c472f7d46307e46327e46337f463480453581453781453882443983443a83443b84433d84433e85423f854240864241864142874144874045884046883f47883f48893e49893e4a893e4c8a3d4d8a3d4e8a3c4f8a3c508b3b518b3b528b3a538b3a548c39558c39568c38588c38598c375a8c375b8d365c8d365d8d355e8d355f8d34608d34618d33628d33638d32648e32658e31668e31678e31688e30698e306a8e2f6b8e2f6c8e2e6d8e2e6e8e2e6f8e2d708e2d718e2c718e2c728e2c738e2b748e2b758e2a768e2a778e2a788e29798e297a8e297b8e287c8e287d8e277e8e277f8e27808e26818e26828e26828e25838e25848e25858e24868e24878e23888e23898e238a8d228b8d228c8d228d8d218e8d218f8d21908d21918c20928c20928c20938c1f948c1f958b1f968b1f978b1f988b1f998a1f9a8a1e9b8a1e9c891e9d891f9e891f9f881fa0881fa1881fa1871fa28720a38620a48621a58521a68522a78522a88423a98324aa8325ab8225ac8226ad8127ad8128ae8029af7f2ab07f2cb17e2db27d2eb37c2fb47c31b57b32b67a34b67935b77937b87838b9773aba763bbb753dbc743fbc7340bd7242be7144bf7046c06f48c16e4ac16d4cc26c4ec36b50c46a52c56954c56856c66758c7655ac8645cc8635ec96260ca6063cb5f65cb5e67cc5c69cd5b6ccd5a6ece5870cf5773d05675d05477d1537ad1517cd2507fd34e81d34d84d44b86d54989d5488bd6468ed64590d74393d74195d84098d83e9bd93c9dd93ba0da39a2da37a5db36a8db34aadc32addc30b0dd2fb2dd2db5de2bb8de29bade28bddf26c0df25c2df23c5e021c8e020cae11fcde11dd0e11cd2e21bd5e21ad8e219dae319dde318dfe318e2e418e5e419e7e419eae51aece51befe51cf1e51df4e61ef6e620f8e621fbe723fde725';
-function viridisStopsFromHex() {
+function stopsFromHex(spec) {
     const out = [];
-    for (let i = 0; i < 256; i++) {
-        const hex = VIRIDIS_HEX_SPEC.slice(i * 6, i * 6 + 6);
+    for (let i = 0; i < spec.length; i += 6) {
         out.push([
-            Number.parseInt(hex.slice(0, 2), 16),
-            Number.parseInt(hex.slice(2, 4), 16),
-            Number.parseInt(hex.slice(4, 6), 16),
+            Number.parseInt(spec.slice(i, i + 2), 16),
+            Number.parseInt(spec.slice(i + 2, i + 4), 16),
+            Number.parseInt(spec.slice(i + 4, i + 6), 16),
             255,
         ]);
     }
@@ -24,7 +21,133 @@ function viridisStopsFromHex() {
  * for the texture/fillStyle form, or to {@link sampleColorRamp} for legend
  * stops.
  */
-export const VIRIDIS_STOPS = viridisStopsFromHex();
+export const VIRIDIS_STOPS = stopsFromHex(VIRIDIS_HEX_SPEC);
+const MAGMA_HEX_SPEC = '00000401000501010601010802010902020b02020d03030f03031204041405041606051806051a07061c08071e0907200a08220b09240c09260d0a290e0b2b100b2d110c2f120d31130d34140e36150e38160f3b180f3d19103f1a10421c10441d11471e114920114b21114e22115024125325125527125829115a2a115c2c115f2d11612f116331116533106734106936106b38106c390f6e3b0f703d0f713f0f72400f74420f75440f764510774710784910784a10794c117a4e117b4f127b51127c52137c54137d56147d57157e59157e5a167e5c167f5d177f5f187f601880621980641a80651a80671b80681c816a1c816b1d816d1d816e1e81701f81721f817320817521817621817822817922827b23827c23827e24828025828125818326818426818627818827818928818b29818c29818e2a81902a81912b81932b80942c80962c80982d80992d809b2e7f9c2e7f9e2f7fa02f7fa1307ea3307ea5317ea6317da8327daa337dab337cad347cae347bb0357bb2357bb3367ab5367ab73779b83779ba3878bc3978bd3977bf3a77c03a76c23b75c43c75c53c74c73d73c83e73ca3e72cc3f71cd4071cf4070d0416fd2426fd3436ed5446dd6456cd8456cd9466bdb476adc4869de4968df4a68e04c67e24d66e34e65e44f64e55064e75263e85362e95462ea5661eb5760ec5860ed5a5fee5b5eef5d5ef05f5ef1605df2625df2645cf3655cf4675cf4695cf56b5cf66c5cf66e5cf7705cf7725cf8745cf8765cf9785df9795df97b5dfa7d5efa7f5efa815ffb835ffb8560fb8761fc8961fc8a62fc8c63fc8e64fc9065fd9266fd9467fd9668fd9869fd9a6afd9b6bfe9d6cfe9f6dfea16efea36ffea571fea772fea973feaa74feac76feae77feb078feb27afeb47bfeb67cfeb77efeb97ffebb81febd82febf84fec185fec287fec488fec68afec88cfeca8dfecc8ffecd90fecf92fed194fed395fed597fed799fed89afdda9cfddc9efddea0fde0a1fde2a3fde3a5fde5a7fde7a9fde9aafdebacfcecaefceeb0fcf0b2fcf2b4fcf4b6fcf6b8fcf7b9fcf9bbfcfbbdfcfdbf';
+const INFERNO_HEX_SPEC = '00000401000501010601010802010a02020c02020e03021004031204031405041706041907051b08051d09061f0a07220b07240c08260d08290e092b10092d110a30120a32140b34150b37160b39180c3c190c3e1b0c411c0c431e0c451f0c48210c4a230c4c240c4f260c51280b53290b552b0b572d0b592f0a5b310a5c320a5e340a5f3609613809623909633b09643d09653e0966400a67420a68440a68450a69470b6a490b6a4a0c6b4c0c6b4d0d6c4f0d6c510e6c520e6d540f6d550f6d57106e59106e5a116e5c126e5d126e5f136e61136e62146e64156e65156e67166e69166e6a176e6c186e6d186e6f196e71196e721a6e741a6e751b6e771c6d781c6d7a1d6d7c1d6d7d1e6d7f1e6c801f6c82206c84206b85216b87216b88226a8a226a8c23698d23698f24699025689225689326679526679727669827669a28659b29649d29649f2a63a02a63a22b62a32c61a52c60a62d60a82e5fa92e5eab2f5ead305dae305cb0315bb1325ab3325ab43359b63458b73557b93556ba3655bc3754bd3853bf3952c03a51c13a50c33b4fc43c4ec63d4dc73e4cc83f4bca404acb4149cc4248ce4347cf4446d04545d24644d34743d44842d54a41d74b3fd84c3ed94d3dda4e3cdb503bdd513ade5238df5337e05536e15635e25734e35933e45a31e55c30e65d2fe75e2ee8602de9612bea632aeb6429eb6628ec6726ed6925ee6a24ef6c23ef6e21f06f20f1711ff1731df2741cf3761bf37819f47918f57b17f57d15f67e14f68013f78212f78410f8850ff8870ef8890cf98b0bf98c0af98e09fa9008fa9207fa9407fb9606fb9706fb9906fb9b06fb9d07fc9f07fca108fca309fca50afca60cfca80dfcaa0ffcac11fcae12fcb014fcb216fcb418fbb61afbb81dfbba1ffbbc21fbbe23fac026fac228fac42afac62df9c72ff9c932f9cb35f8cd37f8cf3af7d13df7d340f6d543f6d746f5d949f5db4cf4dd4ff4df53f4e156f3e35af3e55df2e661f2e865f2ea69f1ec6df1ed71f1ef75f1f179f2f27df2f482f3f586f3f68af4f88ef5f992f6fa96f8fb9af9fc9dfafda1fcffa4';
+const CIVIDIS_HEX_SPEC = '00224e00234f00245100255300255400265600275800285900285b00295d002a5f002a61002b62002c64002c66002d68002e6a002e6c002f6d00306f0030700031700031710132710533710833700c34700f357012357014367016377018376f1a386f1c396f1e3a6f203a6f213b6e233c6e243c6e263d6e273e6e293f6e2a3f6d2b406d2d416d2e416d2f426d31436d32436d33446d34456c35456c36466c38476c39486c3a486c3b496c3c4a6c3d4a6c3e4b6c3f4c6c404c6c414d6c424e6c434e6c444f6c45506c46516c47516c48526c49536c4a536c4b546c4c556c4d556c4e566c4f576c50576c51586d52596d535a6d545a6d555b6d555c6d565c6d575d6d585e6d595e6e5a5f6e5b606e5c616e5d616e5e626e5e636f5f636f60646f61656f62656f636670646770656870656870666970676a71686a71696b716a6c716b6d726c6d726c6e726d6f726e6f736f70737071737172747272747273747374757474757575757676767777767777777878777979777a7a787b7a787c7b787d7c787e7c787e7d787f7e78807f78817f788280798381798482798582798683798784788885788985788a86788b87788c88788d88788e89788f8a78908b78918b78928c78928d78938e78948e77958f779690779791779892779992779a93769b94769c95769d95769e96769f9775a09875a19975a29975a39a74a49b74a59c74a69c74a79d73a89e73a99f73aaa073aba072aca172ada272aea371afa471b0a571b1a570b3a670b4a76fb5a86fb6a96fb7a96eb8aa6eb9ab6dbaac6dbbad6dbcae6cbdae6cbeaf6bbfb06bc0b16ac1b26ac2b369c3b369c4b468c5b568c6b667c7b767c8b866c9b965cbb965ccba64cdbb63cebc63cfbd62d0be62d1bf61d2c060d3c05fd4c15fd5c25ed6c35dd7c45cd9c55cdac65bdbc75adcc859ddc858dec958dfca57e0cb56e1cc55e2cd54e4ce53e5cf52e6d051e7d150e8d24fe9d34eead34cebd44bedd54aeed649efd748f0d846f1d945f2da44f3db42f5dc41f6dd3ff7de3ef8df3cf9e03afbe138fce236fde334fee434fee535fee636fee838';
+const FALL_STOPS = [
+    [255, 255, 255, 255],
+    [255, 255, 204, 255],
+    [255, 237, 160, 255],
+    [254, 217, 118, 255],
+    [254, 178, 76, 255],
+    [253, 141, 60, 255],
+    [252, 78, 42, 255],
+    [227, 26, 28, 255],
+    [189, 0, 38, 255],
+    [128, 0, 38, 255],
+    [0, 0, 0, 255],
+];
+const JUICEBOX_STOPS = [
+    [255, 0, 0, 0],
+    [255, 0, 0, 255],
+];
+const REDS_STOPS = [
+    [255, 245, 240, 255],
+    [254, 224, 210, 255],
+    [252, 187, 161, 255],
+    [252, 146, 114, 255],
+    [251, 106, 74, 255],
+    [239, 59, 44, 255],
+    [203, 24, 29, 255],
+    [165, 15, 21, 255],
+    [103, 0, 13, 255],
+];
+const BLUES_STOPS = [
+    [247, 251, 255, 255],
+    [222, 235, 247, 255],
+    [198, 219, 239, 255],
+    [158, 202, 225, 255],
+    [107, 174, 214, 255],
+    [66, 146, 198, 255],
+    [33, 113, 181, 255],
+    [8, 81, 156, 255],
+    [8, 48, 107, 255],
+];
+const REDBLUE_STOPS = [
+    [103, 0, 31, 255],
+    [178, 24, 43, 255],
+    [214, 96, 77, 255],
+    [244, 165, 130, 255],
+    [253, 219, 199, 255],
+    [247, 247, 247, 255],
+    [209, 229, 240, 255],
+    [146, 197, 222, 255],
+    [67, 147, 195, 255],
+    [33, 102, 172, 255],
+    [5, 48, 97, 255],
+];
+const PURPLEORANGE_STOPS = [
+    [45, 0, 75, 255],
+    [84, 39, 136, 255],
+    [128, 115, 172, 255],
+    [178, 171, 210, 255],
+    [216, 218, 235, 255],
+    [247, 247, 247, 255],
+    [254, 224, 182, 255],
+    [253, 184, 99, 255],
+    [224, 130, 20, 255],
+    [179, 88, 6, 255],
+    [127, 59, 8, 255],
+];
+const SCHEME_STOPS = {
+    viridis: VIRIDIS_STOPS,
+    juicebox: JUICEBOX_STOPS,
+    fall: FALL_STOPS,
+    reds: REDS_STOPS,
+    blues: BLUES_STOPS,
+    magma: stopsFromHex(MAGMA_HEX_SPEC),
+    inferno: stopsFromHex(INFERNO_HEX_SPEC),
+    cividis: stopsFromHex(CIVIDIS_HEX_SPEC),
+    redblue: REDBLUE_STOPS,
+    purpleorange: PURPLEORANGE_STOPS,
+};
+function luminanceOverWhite([r, g, b, a]) {
+    const over = (c) => 255 + (c - 255) * (a / 255);
+    return 0.2126 * over(r) + 0.7152 * over(g) + 0.0722 * over(b);
+}
+/**
+ * #api
+ * Whether a named ramp runs dark at its low end, drawn over white: viridis
+ * and its siblings do, juicebox, fall, reds and blues do not.
+ */
+export function darkAtLowEnd(scheme) {
+    const stops = SCHEME_STOPS[scheme];
+    return luminanceOverWhite(stops[0]) < luminanceOverWhite(stops.at(-1));
+}
+const EMPTY_EXTENT_DOMAIN = [0, 1];
+/**
+ * #api
+ * The domain a continuous colour scale spans: each end `min` or `max` pins,
+ * else the extent's, ascending, since a span has no direction and `reverse`
+ * is the ramp's. An open end stops at a pinned one rather than crossing it,
+ * and an extent holding no value (`[Infinity, -Infinity]`) spans [0, 1].
+ */
+export function rampDomain(min, max, extent) {
+    const [lo, hi] = extent[0] <= extent[1] ? extent : EMPTY_EXTENT_DOMAIN;
+    if (min !== undefined && max !== undefined) {
+        return min <= max ? [min, max] : [max, min];
+    }
+    if (min !== undefined) {
+        return [min, Math.max(min, hi)];
+    }
+    if (max !== undefined) {
+        return [Math.min(lo, max), max];
+    }
+    return [lo, hi];
+}
+/**
+ * #api
+ * The stops a continuous colour scale samples: `range`'s CSS colours where it
+ * lists any, else the named `scheme`, viridis while that is unset, turned
+ * round under `reverse`.
+ */
+export function colorRampStops({ range, scheme, reverse, }) {
+    const stops = range?.length
+        ? range.map(c => cssColorToRgba(c))
+        : SCHEME_STOPS[scheme ?? DEFAULT_COLOR_SCHEME];
+    return reverse ? stops.toReversed() : stops;
+}
 function lerp8(a, b, t) {
     return Math.round(a * (1 - t) + b * t);
 }
@@ -54,6 +177,11 @@ export function sampleColorRamp(stops, t) {
  * texture both GPU backends upload and the Canvas2D twins index — entry `i` is
  * the color at `t = i / (N - 1)`. N comes off the shader that samples it, so
  * the table and `rampColor`'s texel mapping cannot disagree.
+ *
+ * The table is always straight. A diverging ramp whose middle belongs at a
+ * value off the centre of the domain reads it through `rampMidT`, the shader's
+ * rule and its generated twin, so the middle follows a moving domain without a
+ * new table.
  */
 export function buildColorRampLut(stops) {
     const last = COLOR_RAMP_LUT_ENTRIES - 1;
@@ -67,24 +195,47 @@ export function buildColorRampLut(stops) {
     }
     return data;
 }
+const MAX_RAMP_LUTS = 32;
+const luts = new Map();
+/**
+ * #api
+ * The {@link buildColorRampLut} table a ramp declaration asks for, the same
+ * `Uint8Array` for the same declaration, since a GPU backend re-uploads its
+ * ramp texture when the identity changes and a render state is rebuilt far
+ * more often than its ramp.
+ */
+export function rampLutOf(ramp) {
+    const key = [ramp.scheme ?? '', ramp.range?.join(' ') ?? '', !!ramp.reverse]
+        .map(String)
+        .join('|');
+    let lut = luts.get(key);
+    if (!lut) {
+        if (luts.size >= MAX_RAMP_LUTS) {
+            luts.delete(luts.keys().next().value);
+        }
+        lut = buildColorRampLut(colorRampStops(ramp));
+        luts.set(key, lut);
+    }
+    return lut;
+}
 /**
  * #api
  * `n` evenly spaced legend stops read straight out of a
  * {@link buildColorRampLut} byte table — the same 256×1 RGBA array
  * `uploadColorRampLut` hands the GPU and the Canvas2D fillStyle LUTs index —
- * formatted for `SvgGradientLegend`. It holds one claim by construction: the
- * swatch at bar fraction `t` is byte-identical to the ramp entry at `t` on
- * both backends. Alpha rides `opacity` (the juicebox fade), never baked into
+ * as the stops of a `RampScale`. It holds one claim by construction: the
+ * swatch at bar fraction `t` is byte-identical to the ramp entry both backends
+ * read at `t`, through the ramp's middle stop at `midNorm` (`rampMidT`). Alpha rides `opacity` (the juicebox fade), never baked into
  * the color string.
  */
-export function stopsFromRampLut(lut, n) {
+export function stopsFromRampLut(lut, n, midNorm = 0.5) {
     const lastEntry = lut.length / 4 - 1;
     const out = [];
     for (let i = 0; i < n; i++) {
         const t = n === 1 ? 0 : i / (n - 1);
-        const o = Math.round(t * lastEntry) * 4;
+        const o = Math.round(rampMidT(t, midNorm) * lastEntry) * 4;
         out.push({
-            offset: `${+(t * 100).toFixed(2)}%`,
+            offset: t,
             color: `rgb(${lut[o]},${lut[o + 1]},${lut[o + 2]})`,
             opacity: lut[o + 3] / 255,
         });

package/esm/util/colorScale.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The scales a colour object paints through, in a module that imports
+ * nothing: `jbrowse validate` carries a copy of it, so the validator and the
+ * displays read one statement.
+ */
+/** How a colour object maps its `field`; `none` paints `value`. */
+export declare const COLOR_SCALES: readonly ['none', 'categorical', 'linear', 'log', 'threshold'];
+/**
+ * The scale that maps no field: each feature paints the colour it carries, and
+ * the key names the colours `domain` lists. Only a display whose features
+ * carry colours of their own declares it.
+ */
+export declare const IDENTITY_SCALE = "identity";
+export type ColorScaleName = (typeof COLOR_SCALES)[number] | typeof IDENTITY_SCALE;
+/**
+ * A field's defaults on a display: the scale it paints through while `scale`
+ * is unset, and the members that scale reads while the config leaves them
+ * unwritten, so a field with a vocabulary or ramp of its own is the colour
+ * object's defaults rather than a painter beside it.
+ */
+export interface FieldPreset<S extends string = ColorScaleName> {
+    scale: S;
+    /** The key a feature carrying no value files under. */
+    missing?: string;
+    domain?: readonly string[];
+    range?: readonly string[];
+    labels?: readonly string[];
+    title?: string;
+    domainMin?: number;
+    domainMax?: number;
+    domainMid?: number;
+    scheme?: string;
+    reverse?: boolean;
+}
+/** Each field's preset, `*` for any other field. */
+export type FieldPresets<S extends string = ColorScaleName> = Readonly<Record<string, FieldPreset<S>>>;
+/**
+ * The fields whose values have names, an order and colours of their own on
+ * every display, beneath each display's own presets. Red forward and blue
+ * reverse is what the synteny ribbons paint too. The SV classes are
+ * `svClassOf`'s, deletion red and duplication blue as dbVar and gnomAD-SV
+ * paint them, insertion the pileup's purple, and the rest kept apart under
+ * deuteranopia and protanopia. A record with no class files under `''`, so
+ * each display keeps its own no-value colour for it.
+ */
+export declare const UNIVERSAL_FIELD_PRESETS: {
+    readonly strand: {
+        readonly scale: 'categorical';
+        readonly missing: '0';
+        readonly domain: readonly ["1", "-1", "0"];
+        readonly range: readonly ["tomato", "cornflowerblue", "goldenrod"];
+        readonly labels: readonly ["Forward strand", "Reverse strand", "No strand"];
+    };
+    readonly svType: {
+        readonly scale: 'categorical';
+        readonly domain: readonly ["DEL", "DUP", "INS", "INV", "CNV", "TR", "BND", "CPX", "OTHER"];
+        readonly range: readonly ["#e41a1c", "#377eb8", "#800080", "#ff7f00", "#7e6148", "#e7298a", "#17becf", "#66a61e", "#000000"];
+        readonly labels: readonly ["Deletion", "Duplication", "Insertion", "Inversion", "Copy-number variable", "Tandem repeat", "Breakend / translocation", "Complex", "Other / mixed"];
+        readonly title: 'SV type';
+    };
+};
+/** The universal preset of `field`, if it has one. */
+export declare function universalPresetOf(field: string): FieldPreset<'categorical'> | undefined;
+/** Every field categorical while `scale` is unset, with nothing preset. */
+export declare const CATEGORICAL_FIELD_PRESETS: {
+    readonly '*': FieldPreset<"categorical">;
+};
+/**
+ * What a feature's field paints through while `scale` is unset: `score` a
+ * ramp, any other field categories.
+ */
+export declare const FEATURE_FIELD_PRESETS: {
+    readonly score: {
+        readonly scale: 'linear';
+    };
+    readonly '*': FieldPreset<"categorical">;
+};
+/**
+ * A field's preset under `presets`: its own, else a universal one, else
+ * `*`'s, else categorical.
+ */
+export declare function presetOf<S extends string>(presets: FieldPresets<S>, field: string): FieldPreset<S | 'categorical'>;
+/** What a field paints through under `presets` while `scale` is unset. */
+export declare function fieldScaleOf<S extends string>(presets: FieldPresets<S>, field: string): S | 'categorical';
+/**
+ * A colour object with its field's preset under it: each member the preset
+ * names and the config leaves unwritten, an empty list counting as unwritten.
+ * Only while the colour paints through the preset's own scale, so the cuts of
+ * a threshold preset never reach a field read through a ramp. A categorical
+ * preset's `range` and `labels` name its `domain`'s values in order, so they
+ * fill only while `domain` does too: a written order keeps each value's own
+ * colour and name.
+ */
+export declare function withPreset<C extends {
+    field?: string;
+    scale?: string;
+}>(color: C, presets: FieldPresets<string>): C;
+/**
+ * The scale a colour object paints through: `none` while no `field` is
+ * named, else its own `scale`, or `fieldScale` where that is unset.
+ */
+export declare function paintedScale<S extends string, F extends string>({ scale, field }: {
+    scale: S | undefined;
+    field: string;
+}, fieldScale: F): S | F | 'none';
+/** A combination of a scale's slots the display cannot draw as written. */
+export interface ScaleProblem {
+    rule: 'threshold-cuts' | 'threshold-range' | 'ramp-domain' | 'domain-ends' | 'domain-quantile' | 'labels-domain';
+    /** the slot to look at, relative to the scale's own object */
+    slot: string;
+    message: string;
+}
+/**
+ * The members a quantitative scale's ends are read by, as a colour ramp,
+ * `scales.y` and a mark's width spell them alike.
+ */
+export interface ScaleEnds {
+    domainMin?: number;
+    domainMax?: number;
+    domainQuantile?: number;
+}
+/**
+ * What a quantitative scale's ends say together that neither can refuse
+ * alone: a `domainMax` below its `domainMin`, which every such scale draws in
+ * order either way, and a `domainQuantile` outside 0.5 to 1, where the quantile
+ * an open end follows is clamped. `reverse` is whether the scale turns round by
+ * a member of its own, which is then the spelling to point at.
+ */
+export declare function scaleEndProblems({ domainMin, domainMax, domainQuantile }: ScaleEnds, { reverse }?: {
+    reverse?: boolean;
+}): ScaleProblem[];
+/** Problems as the lines a display's corner notice lists, under the setting that holds the scale. */
+export declare function noticeLines(setting: string, problems: readonly ScaleProblem[]): string[];
+/** The slots `colorProblems` reads, as a snapshot or a resolved setting holds them. */
+export interface ColorSlots {
+    value?: string;
+    field?: string;
+    scale?: string;
+    domain?: readonly unknown[];
+    range?: readonly unknown[];
+    domainMin?: number;
+    domainMax?: number;
+    domainQuantile?: number;
+    labels?: readonly unknown[];
+}
+/**
+ * What a colour object's slots say together that no single slot can refuse,
+ * since the config editor writes one slot at a time (ADR-133), read with its
+ * field's preset under it. A display shows these as a notice and draws what
+ * it can. A threshold naming no cuts leaves its intervals to the display —
+ * the alignments insert-size band samples its cuts, the wiggle plot cuts at
+ * its origin — so its `labels` go uncounted.
+ */
+export declare function colorProblems(written: ColorSlots, presets: FieldPresets<string>): ScaleProblem[];
+/** `colorProblems` as the lines a display's corner notice lists, under `color`. */
+export declare function colorNotices(color: ColorSlots, presets: FieldPresets<string>): string[];