@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/color-bits/index.js

@@ -0,0 +1,4 @@
+export { OFFSET_A, OFFSET_B, OFFSET_G, OFFSET_R, from, getAlpha, getBlue, getGreen, getRed, newColor, setAlpha, setBlue, setGreen, setRed, toNumber, } from './core.js';
+export { parse, parseColor, parseHex } from './parse.js';
+export { format, formatHEX, formatHEXA, formatHSLA, formatRGBA, toGLrgb, toHSLA, toRGBA, } from './format.js';
+export { alpha, blend, darken, getLuminance, lighten } from './functions.js';

package/esm/util/color-bits/parse.d.ts

@@ -0,0 +1,17 @@
+import type { Color } from './core.ts';
+/**
+ * Parse CSS color
+ * @param color CSS color string: #xxx, #xxxxxx, #xxxxxxxx, rgb(), rgba(), hsl(), hsla(), color()
+ */
+export declare function parse(color: string): Color;
+/**
+ * Parse hexadecimal CSS color
+ * @param color Hex color string: #xxx, #xxxx, #xxxxxx, #xxxxxxxx
+ */
+export declare function parseHex(color: string): Color;
+/**
+ * Parse CSS color
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+ * @param color CSS color string: rgb(), rgba(), hsl(), hsla(), color()
+ */
+export declare function parseColor(color: string): Color;

package/esm/util/color-bits/parse.js

@@ -0,0 +1,382 @@
+import * as convert from './convert.js';
+import { newColor } from './core.js';
+const HASH = '#'.charCodeAt(0);
+const PERCENT = '%'.charCodeAt(0);
+const G = 'g'.charCodeAt(0);
+const N = 'n'.charCodeAt(0);
+const D = 'd'.charCodeAt(0);
+const E = 'e'.charCodeAt(0);
+/**
+ * Approximative CSS colorspace string pattern, e.g. rgb(), color()
+ *
+ * **Anchored**, because the whole string has to be a colour for this to be one.
+ * Unanchored it matched a colour sitting anywhere inside anything, so
+ * `parseCssColor('foo rgb(1,2,3) bar')` answered `[1,2,3]` — and a config slot
+ * holding prose, a jexl expression that did not evaluate, or two colours by
+ * mistake read as a plausible colour instead of reaching the invalid-colour
+ * sentinel. That sentinel is a contract (`colorBits.test.ts`: a broken config
+ * reads as magenta, never as a plausible wrong colour), and it was unreachable
+ * for every such string. Surrounding whitespace is still tolerated: a slot with
+ * a trailing space is a formatting slip, not a different colour.
+ */
+const PATTERN = (() => {
+    const NAME = String.raw `(\w+)`;
+    const SEPARATOR = String.raw `[\s,\/]`;
+    const VALUE = String.raw `([^\s,\/]+)`;
+    const SEPARATOR_THEN_VALUE = `(?:${SEPARATOR}+${VALUE})`;
+    return new RegExp(String.raw `^\s*
+      ${NAME}\(
+      ${SEPARATOR}*
+      ${VALUE}
+      ${SEPARATOR_THEN_VALUE}
+      ${SEPARATOR_THEN_VALUE}
+      ${SEPARATOR_THEN_VALUE}?
+      ${SEPARATOR_THEN_VALUE}?
+      ${SEPARATOR}*
+    \)\s*$`.replaceAll(/\s/g, ''));
+})();
+/**
+ * Parse CSS color
+ * @param color CSS color string: #xxx, #xxxxxx, #xxxxxxxx, rgb(), rgba(), hsl(), hsla(), color()
+ */
+export function parse(color) {
+    return color.charCodeAt(0) === HASH ? parseHex(color) : parseColor(color);
+}
+// The four legal hex forms. Validated up front rather than trusted, because
+// hexValue() maps any character to a number: '#zzzzzz' produced a plausible dark
+// grey and '#ff' opaque black, so parseCssColor's invalid-color sentinel was
+// unreachable for anything starting with '#'. Nibbles above 0xf also overflow
+// into the neighbouring channel once packed.
+const HEX = /^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i;
+/**
+ * Parse hexadecimal CSS color
+ * @param color Hex color string: #xxx, #xxxx, #xxxxxx, #xxxxxxxx
+ */
+export function parseHex(color) {
+    if (!HEX.test(color)) {
+        throw new Error(`Color.parse(): invalid CSS color: "${color}"`);
+    }
+    let r = 0x00;
+    let g = 0x00;
+    let b = 0x00;
+    let a = 0xff;
+    switch (color.length) {
+        // #59f
+        case 4: {
+            r = (hexValue(color.charCodeAt(1)) << 4) + hexValue(color.charCodeAt(1));
+            g = (hexValue(color.charCodeAt(2)) << 4) + hexValue(color.charCodeAt(2));
+            b = (hexValue(color.charCodeAt(3)) << 4) + hexValue(color.charCodeAt(3));
+            break;
+        }
+        // #59fa
+        case 5: {
+            r = (hexValue(color.charCodeAt(1)) << 4) + hexValue(color.charCodeAt(1));
+            g = (hexValue(color.charCodeAt(2)) << 4) + hexValue(color.charCodeAt(2));
+            b = (hexValue(color.charCodeAt(3)) << 4) + hexValue(color.charCodeAt(3));
+            a = (hexValue(color.charCodeAt(4)) << 4) + hexValue(color.charCodeAt(4));
+            break;
+        }
+        // #5599ff
+        case 7: {
+            r = (hexValue(color.charCodeAt(1)) << 4) + hexValue(color.charCodeAt(2));
+            g = (hexValue(color.charCodeAt(3)) << 4) + hexValue(color.charCodeAt(4));
+            b = (hexValue(color.charCodeAt(5)) << 4) + hexValue(color.charCodeAt(6));
+            break;
+        }
+        // #5599ff88
+        case 9: {
+            r = (hexValue(color.charCodeAt(1)) << 4) + hexValue(color.charCodeAt(2));
+            g = (hexValue(color.charCodeAt(3)) << 4) + hexValue(color.charCodeAt(4));
+            b = (hexValue(color.charCodeAt(5)) << 4) + hexValue(color.charCodeAt(6));
+            a = (hexValue(color.charCodeAt(7)) << 4) + hexValue(color.charCodeAt(8));
+            break;
+        }
+        default: {
+            break;
+        }
+    }
+    return newColor(r, g, b, a);
+}
+// https://lemire.me/blog/2019/04/17/parsing-short-hexadecimal-strings-efficiently/
+function hexValue(c) {
+    return (c & 0xf) + 9 * (c >> 6);
+}
+/**
+ * Parse CSS color
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+ * @param color CSS color string: rgb(), rgba(), hsl(), hsla(), color()
+ */
+export function parseColor(color) {
+    const match = PATTERN.exec(color);
+    if (match === null) {
+        throw new Error(`Color.parse(): invalid CSS color: "${color}"`);
+    }
+    const fmt = match[1];
+    const p1 = match[2];
+    const p2 = match[3];
+    const p3 = match[4];
+    const p4 = match[5];
+    const p5 = match[6];
+    switch (fmt) {
+        case 'rgb':
+        case 'rgba': {
+            const r = parseColorChannel(p1);
+            const g = parseColorChannel(p2);
+            const b = parseColorChannel(p3);
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            return newColor(r, g, b, a);
+        }
+        case 'hsl':
+        case 'hsla': {
+            const h = parseAngle(p1);
+            const s = parsePercentage(p2);
+            const l = parsePercentage(p3);
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            // https://stackoverflow.com/a/9493060/3112706
+            let r;
+            let g;
+            let b;
+            if (s === 0) {
+                r = g = b = Math.round(l * 255); // achromatic
+            }
+            else {
+                const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+                const p = 2 * l - q;
+                r = Math.round(hueToRGB(p, q, h + 1 / 3) * 255);
+                g = Math.round(hueToRGB(p, q, h) * 255);
+                b = Math.round(hueToRGB(p, q, h - 1 / 3) * 255);
+            }
+            return newColor(r, g, b, a);
+        }
+        case 'hwb': {
+            const h = parseAngle(p1);
+            const w = parsePercentage(p2);
+            const bl = parsePercentage(p3);
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            /* https://drafts.csswg.org/css-color/#hwb-to-rgb */
+            const s = 1;
+            const l = 0.5;
+            // Same as HSL to RGB
+            const q = l + s - l * s;
+            const p = 2 * l - q;
+            let r = Math.round(hueToRGB(p, q, h + 1 / 3) * 255);
+            let g = Math.round(hueToRGB(p, q, h) * 255);
+            let b = Math.round(hueToRGB(p, q, h - 1 / 3) * 255);
+            // Then HWB
+            r = hwbApply(r, w, bl);
+            g = hwbApply(g, w, bl);
+            b = hwbApply(b, w, bl);
+            return newColor(r, g, b, a);
+        }
+        case 'lab': {
+            const l = parsePercentageFor(p1, 100);
+            const aa = parsePercentageFor(p2, 125);
+            const b = parsePercentageFor(p3, 125);
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.labToXyzd50(l, aa, b)));
+        }
+        case 'lch': {
+            const l = parsePercentageFor(p1, 100);
+            const c = parsePercentageFor(p2, 150);
+            const h = parseAngle(p3) * 360;
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.labToXyzd50(...convert.lchToLab(l, c, h))));
+        }
+        case 'oklab': {
+            const l = parsePercentageFor(p1, 1);
+            const aa = parsePercentageFor(p2, 0.4);
+            const b = parsePercentageFor(p3, 0.4);
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.xyzd65ToD50(...convert.oklabToXyzd65(l, aa, b))));
+        }
+        case 'oklch': {
+            const l = parsePercentageOrValue(p1);
+            const c = parsePercentageOrValue(p2);
+            const h = parsePercentageOrValue(p3);
+            const a = p4 ? parseAlphaChannel(p4) : 255;
+            return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.oklchToXyzd50(l, c, h)));
+        }
+        case 'color': {
+            // https://drafts.csswg.org/css-color-4/#color-function
+            const colorspace = p1;
+            const c1 = parsePercentageOrValue(p2);
+            const c2 = parsePercentageOrValue(p3);
+            const c3 = parsePercentageOrValue(p4);
+            const a = p5 ? parseAlphaChannel(p5) : 255;
+            switch (colorspace) {
+                // RGB color spaces
+                case 'srgb': {
+                    return newColorFromArray(a, [c1, c2, c3]);
+                }
+                case 'srgb-linear': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.srgbLinearToXyzd50(c1, c2, c3)));
+                }
+                case 'display-p3': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.displayP3ToXyzd50(c1, c2, c3)));
+                }
+                case 'a98-rgb': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.adobeRGBToXyzd50(c1, c2, c3)));
+                }
+                case 'prophoto-rgb': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.proPhotoToXyzd50(c1, c2, c3)));
+                }
+                case 'rec2020': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.rec2020ToXyzd50(c1, c2, c3)));
+                }
+                // XYZ color spaces
+                case 'xyz':
+                case 'xyz-d65': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(...convert.xyzd65ToD50(c1, c2, c3)));
+                }
+                case 'xyz-d50': {
+                    return newColorFromArray(a, convert.xyzd50ToSrgb(c1, c2, c3));
+                }
+                default:
+            }
+            break;
+        }
+        default:
+    }
+    throw new Error(`Color.parse(): invalid CSS color: "${color}"`);
+}
+/**
+ * Accepts: "50%", "128"
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb#values
+ * @returns a value in the 0 to 255 range
+ */
+function parseColorChannel(channel) {
+    if (channel.charCodeAt(channel.length - 1) === PERCENT) {
+        return Math.round((Number.parseFloat(channel) / 100) * 255);
+    }
+    return Math.round(Number.parseFloat(channel));
+}
+/**
+ * Accepts: "50%", ".5", "0.5"
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/alpha-value
+ * @returns a value in the [0, 255] range
+ */
+function parseAlphaChannel(channel) {
+    return Math.round(parseAlphaValue(channel) * 255);
+}
+/**
+ * Accepts: "50%", ".5", "0.5"
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/alpha-value
+ * @returns a value in the [0, 1] range
+ */
+function parseAlphaValue(channel) {
+    if (channel.charCodeAt(0) === N) {
+        return 0;
+    }
+    if (channel.charCodeAt(channel.length - 1) === PERCENT) {
+        return Number.parseFloat(channel) / 100;
+    }
+    return Number.parseFloat(channel);
+}
+/**
+ * Accepts: "360", "360deg", "400grad", "6.28rad", "1turn", "none"
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/angle
+ * @returns a value in the 0.0 to 1.0 range
+ */
+function parseAngle(angle) {
+    let factor;
+    switch (angle.charCodeAt(angle.length - 1)) {
+        case E: {
+            // 'none'
+            return 0;
+        }
+        case D: {
+            // 'rad', 'grad'
+            factor =
+                angle.charCodeAt(Math.max(0, angle.length - 4)) === G
+                    ? 400
+                    : 2 * Math.PI; // TAU
+            break;
+        }
+        case N: {
+            // 'turn'
+            factor = 1;
+            break;
+        }
+        // case G: // 'deg', but no need to check as it's also the default
+        default: {
+            factor = 360;
+        }
+    }
+    const turns = Number.parseFloat(angle) / factor;
+    // Hue is periodic, and every caller of this is a hue. `hueToRGB` corrects its
+    // argument by at most one turn, so it reads `hsl(-720deg)` as a hue two turns
+    // below the wheel rather than as red — folding here is what makes the three
+    // hue syntaxes agree with a browser past ±1 turn.
+    return turns - Math.floor(turns);
+}
+/**
+ * Accepts: "100%", "none"
+ * @returns a value in the 0.0 to 1.0 range
+ */
+function parsePercentage(value) {
+    if (value.charCodeAt(0) === N) {
+        return 0;
+    }
+    return Number.parseFloat(value) / 100;
+}
+/**
+ * Accepts: "1.0", "100%", "none"
+ * @returns a value in the 0.0 to 1.0 range
+ */
+function parsePercentageOrValue(value) {
+    if (value.charCodeAt(0) === N) {
+        return 0;
+    }
+    if (value.charCodeAt(value.length - 1) === PERCENT) {
+        return Number.parseFloat(value) / 100;
+    }
+    return Number.parseFloat(value);
+}
+/**
+ * Accepts: "100", "100%", "none"
+ * @returns a value in the -@range to @range range
+ */
+function parsePercentageFor(value, range) {
+    if (value.charCodeAt(0) === N) {
+        return 0;
+    }
+    if (value.charCodeAt(value.length - 1) === PERCENT) {
+        return (Number.parseFloat(value) / 100) * range;
+    }
+    return Number.parseFloat(value);
+}
+// HSL functions
+function hueToRGB(p, q, t) {
+    if (t < 0) {
+        t += 1;
+    }
+    if (t > 1) {
+        t -= 1;
+    }
+    if (t < 1 / 6) {
+        return p + (q - p) * 6 * t;
+    }
+    if (t < 1 / 2) {
+        return q;
+    }
+    if (t < 2 / 3) {
+        return p + (q - p) * (2 / 3 - t) * 6;
+    }
+    return p;
+}
+// HWB functions
+function hwbApply(channel, w, b) {
+    let result = channel / 255;
+    result *= 1 - w - b;
+    result += w;
+    return Math.round(result * 255);
+}
+function clamp(value) {
+    return Math.max(0, Math.min(255, value));
+}
+function newColorFromArray(a, rgb) {
+    const r = clamp(Math.round(rgb[0] * 255));
+    const g = clamp(Math.round(rgb[1] * 255));
+    const b = clamp(Math.round(rgb[2] * 255));
+    return newColor(r, g, b, a);
+}

package/esm/util/colorBits.d.ts

@@ -0,0 +1,39 @@
+import type { Color } from './color-bits/index.ts';
+import type { Feature } from './simpleFeature.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';
+/**
+ * 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
+ * is only claimed when it is unambiguously an in-range BED triple. Anything
+ * else — a hex string, a `reserved` column holding something that isn't a color
+ * at all — reads as absent and leaves the configured default alone, rather than
+ * rendering as the magenta invalid-color sentinel. Takes the raw value so it
+ * stays dependency-free and directly testable.
+ */
+export declare function featureItemRgb(raw: unknown): string | undefined;
+/**
+ * The BED color a feature declares for itself, under either column name, or
+ * 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];
+export declare function cssColorToRgba(color: string): [number, number, number, number];
+export declare function packAbgr(r: number, g: number, b: number, a: number): number;
+export declare function cssColorToABGR(color: string): number;
+export declare function withAbgrAlpha(c: number, a: number): number;
+export declare function normalizedRgbToABGR(r: number, g: number, b: number): number;
+export declare function normalizedRgbToCss(c: readonly [number, number, number]): string;
+export declare function normalizedRgbToCssRgba(c: readonly [number, number, number], alpha: number): string;
+export declare function setAbgrFill(ctx: {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+}, c: number): void;
+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

@@ -0,0 +1,180 @@
+import { getAlpha, getBlue, getGreen, getRed, newColor, parse, } from './color-bits/index.js';
+import { namedColorToHex } from './color/cssColorsLevel4.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
+// reference); crashing the worker on `undefined.trim()` was the failure mode.
+// 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
+// volvox-bed12 fixture is "0,0,0". Honoring those literally would paint an
+// 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
+ * is only claimed when it is unambiguously an in-range BED triple. Anything
+ * else — a hex string, a `reserved` column holding something that isn't a color
+ * at all — reads as absent and leaves the configured default alone, rather than
+ * rendering as the magenta invalid-color sentinel. Takes the raw value so it
+ * stays dependency-free and directly testable.
+ */
+export function featureItemRgb(raw) {
+    const triple = typeof raw === 'string' ? bedTriple(raw) : undefined;
+    return triple !== undefined && !BED_TRIPLE_UNSET.test(triple)
+        ? triple
+        : undefined;
+}
+// The names the BED color column goes by, most specific first.
+//
+// - `itemRgb` — the BED spec's name. What the parser emits for a full BED12.
+// - `reserved` — what UCSC's canonical autoSql calls it ("uint reserved; Used
+//   as itemRgb as of 2004-11-22"). bigBed/bigGenePred embed that autoSql and
+//   BigBedAdapter takes its field names from it, so bigBed features carry this.
+// - `field8` — the parser only applies the *named* BED schema at exactly 12
+//   columns; a BED9/10/11 falls back to positional auto-naming, so the color
+//   lands in `field8` (column index 8, which the spec fixes as itemRgb). That
+//   makes plain BED9 — the classic "I just want colored features" file — the
+//   case this whole thing exists for. Reading the positional name is safe
+//   *because* featureItemRgb is strict: a 9th column holding something that
+//   isn't an in-range triple is simply not claimed.
+//
+// Nothing is renamed on the feature, deliberately: a config already reading
+// `jexl:get(feature,'field8')` (the workaround this issue's users were told to
+// write) keeps working, and can now just be deleted.
+const BED_COLOR_FIELDS = ['itemRgb', 'reserved', 'field8'];
+/**
+ * The BED color a feature declares for itself, under either column name, or
+ * undefined if it declares none.
+ */
+export function featureBedColor(feature) {
+    let found;
+    for (const field of BED_COLOR_FIELDS) {
+        found ??= featureItemRgb(feature.get(field));
+    }
+    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;
+    }
+    return parseCssColorOr(color, INVALID_COLOR);
+}
+export function cssColorToNormalizedRgb(color) {
+    const c = parseCssColor(color);
+    return [getRed(c) / 255, getGreen(c) / 255, getBlue(c) / 255];
+}
+export function cssColorToRgb(color) {
+    const c = parseCssColor(color);
+    return [getRed(c), getGreen(c), getBlue(c)];
+}
+export function cssColorToRgba(color) {
+    const c = parseCssColor(color);
+    return [getRed(c), getGreen(c), getBlue(c), getAlpha(c)];
+}
+// Pack 0..255 RGBA channel bytes into an ABGR u32 (R at byte 0, A at byte 3).
+// >>> 0 keeps the result an unsigned 32-bit — bit 31 (alpha's top bit) would
+// otherwise make opaque colors negative in JS.
+export function packAbgr(r, g, b, a) {
+    return ((a << 24) | (b << 16) | (g << 8) | r) >>> 0;
+}
+export function cssColorToABGR(color) {
+    const c = parseCssColor(color);
+    return packAbgr(getRed(c), getGreen(c), getBlue(c), getAlpha(c));
+}
+// 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
+// per-channel unpack/repack. >>> 0 keeps the result unsigned (see packAbgr).
+export function withAbgrAlpha(c, a) {
+    return ((c & 0x00ffffff) | (a << 24)) >>> 0;
+}
+// Pack a 0..1 normalized RGB triple into an ABGR u32 (opaque alpha). Inverse
+// of cssColorToNormalizedRgb at the GPU write boundary — the shader side
+// unpacks with unpackRGBA() (see packages/render-core/src/shaders/colorPack.slang).
+export function normalizedRgbToABGR(r, g, b) {
+    return packAbgr(Math.round(r * 255), Math.round(g * 255), Math.round(b * 255), 255);
+}
+// Format a 0..1 normalized RGB triple as a CSS `rgb(r,g,b)` string.
+export function normalizedRgbToCss(c) {
+    return `rgb(${Math.round(c[0] * 255)},${Math.round(c[1] * 255)},${Math.round(c[2] * 255)})`;
+}
+// Format a 0..1 normalized RGB triple + alpha as a CSS `rgba(r,g,b,a)` string.
+// Preferred over `ctx.globalAlpha = a; fillStyle = rgb(...)` bracketing.
+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);
+}
+// Channel accessors for the ABGR packed layout (R at byte 0, A at byte 3 —
+// the layout produced by cssColorToABGR and consumed by GPU shaders that
+// unpack via bit shifts from a u32 vertex attribute). Mirror of the
+// color-bits getRed/Green/Blue/Alpha, which operate on the canonical
+// 0xRRGGBBAA layout and therefore give wrong results if called on an ABGR
+// value.
+export function abgrRed(c) {
+    return c & 0xff;
+}
+export function abgrGreen(c) {
+    return (c >>> 8) & 0xff;
+}
+export function abgrBlue(c) {
+    return (c >>> 16) & 0xff;
+}
+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 [
+        getRed(c) / 255,
+        getGreen(c) / 255,
+        getBlue(c) / 255,
+        getAlpha(c) / 255,
+    ];
+}

package/esm/util/colorRamp.d.ts

@@ -0,0 +1,37 @@
+import type { GradientStop } from '../ui/SvgGradientLegend.tsx';
+/** One evenly-spaced ramp stop: 8-bit red, green, blue, alpha. */
+export type ColorRampStop = readonly [number, number, number, number];
+/**
+ * #api
+ * The 256 viridis stops, fully opaque. Feed them to {@link buildColorRampLut}
+ * for the texture/fillStyle form, or to {@link sampleColorRamp} for legend
+ * stops.
+ */
+export declare const VIRIDIS_STOPS: readonly ColorRampStop[];
+/**
+ * #api
+ * The color at `t` in `[0, 1]` across a list of EVENLY SPACED stops, linearly
+ * interpolated per channel. `t` is clamped, so the ends are the end stops
+ * rather than an extrapolation past them, and a one-stop ramp is that stop
+ * everywhere.
+ */
+export declare function sampleColorRamp(stops: readonly ColorRampStop[], t: number): ColorRampStop;
+/**
+ * #api
+ * An RGBA lookup table over {@link sampleColorRamp}, laid out as the Nx1
+ * 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.
+ */
+export declare function buildColorRampLut(stops: readonly ColorRampStop[]): Uint8Array<ArrayBuffer>;
+/**
+ * #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
+ * the color string.
+ */
+export declare function stopsFromRampLut(lut: Uint8Array, n: number): GradientStop[];