@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/calculateStaticBlocks.js

@@ -1,103 +1,80 @@
-import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { BlockSet, ContentBlock, ElidedBlock, InterRegionPaddingBlock, } from "./blockTypes.js";
-import { assembleLocStringFast } from "./index.js";
-export default function calculateStaticBlocks(model, padding = true, elision = true, extra = 0, width = 800) {
-    const { offsetPx, displayedRegions, bpPerPx, minimumBlockWidth, interRegionPaddingWidth, width: modelWidth, } = model;
+import { BlockSet } from './blockTypes.js';
+const blockSizeCssPx = 800;
+export default function calculateStaticBlocks(model, padding = true, elision = true) {
+    const { offsetPx, displayedRegions, bpPerPx, minimumBlockWidth, width: modelWidth, } = model;
     const windowLeftBp = offsetPx * bpPerPx;
     const windowRightBp = (offsetPx + modelWidth) * bpPerPx;
-    const blockSizePx = width;
-    const blockSizeBp = Math.ceil(blockSizePx * bpPerPx);
+    const blockSizeBp = Math.ceil(blockSizeCssPx * bpPerPx);
     const invBpPerPx = 1 / bpPerPx;
     const invBlockSizeBp = 1 / blockSizeBp;
     let regionBpOffset = 0;
     const blocks = new BlockSet();
-    for (let regionNumber = 0; regionNumber < displayedRegions.length; regionNumber++) {
-        const region = displayedRegions[regionNumber];
-        const { assemblyName, refName, start: regionStart, end: regionEnd, reversed, } = region;
-        const regionBlockCount = Math.ceil((regionEnd - regionStart) * invBlockSizeBp);
-        const parentRegion = isStateTreeNode(region) ? getSnapshot(region) : region;
-        let windowRightBlockNum = Math.floor((windowRightBp - regionBpOffset) * invBlockSizeBp) + extra;
-        if (windowRightBlockNum >= regionBlockCount) {
-            windowRightBlockNum = regionBlockCount - 1;
-        }
-        let windowLeftBlockNum = Math.floor((windowLeftBp - regionBpOffset) * invBlockSizeBp) - extra;
-        if (windowLeftBlockNum < 0) {
-            windowLeftBlockNum = 0;
+    for (let displayedRegionIndex = 0; displayedRegionIndex < displayedRegions.length; displayedRegionIndex++) {
+        // Regions are laid out left to right, so once the cursor passes the window's
+        // right edge nothing further can contribute a block — and the trailing
+        // padding block needs the last region to be in view anyway. A whole-genome
+        // view holds one region per refName, so without this the loop (and its five
+        // MST observable reads per region) runs thousands of times per zoom frame to
+        // emit a handful of blocks.
+        if (regionBpOffset > windowRightBp) {
+            break;
         }
+        const { assemblyName, refName, start: regionStart, end: regionEnd, reversed, } = displayedRegions[displayedRegionIndex];
+        const regionBlockCount = Math.ceil((regionEnd - regionStart) * invBlockSizeBp);
+        const windowRightBlockNum = Math.min(Math.floor((windowRightBp - regionBpOffset) * invBlockSizeBp), regionBlockCount - 1);
+        const windowLeftBlockNum = Math.max(Math.floor((windowLeftBp - regionBpOffset) * invBlockSizeBp), 0);
         const regionWidthPx = (regionEnd - regionStart) * invBpPerPx;
-        for (let blockNum = windowLeftBlockNum; blockNum <= windowRightBlockNum; blockNum += 1) {
+        for (let blockNum = windowLeftBlockNum; blockNum <= windowRightBlockNum; blockNum++) {
+            const isLeftEndOfDisplayedRegion = blockNum === 0;
+            const isRightEndOfDisplayedRegion = blockNum === regionBlockCount - 1;
             let start;
             let end;
-            let isLeftEndOfDisplayedRegion;
-            let isRightEndOfDisplayedRegion;
             if (reversed) {
                 start = Math.max(regionStart, regionEnd - (blockNum + 1) * blockSizeBp);
                 end = regionEnd - blockNum * blockSizeBp;
-                isLeftEndOfDisplayedRegion = end === regionEnd;
-                isRightEndOfDisplayedRegion = start === regionStart;
             }
             else {
                 start = regionStart + blockNum * blockSizeBp;
                 end = Math.min(regionEnd, regionStart + (blockNum + 1) * blockSizeBp);
-                isLeftEndOfDisplayedRegion = start === regionStart;
-                isRightEndOfDisplayedRegion = end === regionEnd;
             }
             const widthPx = (end - start) * invBpPerPx;
-            const blockData = {
+            const blockOffsetPx = (regionBpOffset + blockNum * blockSizeBp) * invBpPerPx;
+            const key = `${assemblyName}:${refName}:${start}:${end}:${displayedRegionIndex}${reversed ? ':rev' : ''}`;
+            if (padding && displayedRegionIndex === 0 && blockNum === 0) {
+                blocks.push({
+                    type: 'InterRegionPaddingBlock',
+                    key: `${key}-beforeFirstRegion`,
+                    widthPx: blockSizeCssPx,
+                    offsetPx: blockOffsetPx - blockSizeCssPx,
+                    variant: 'boundary',
+                });
+            }
+            const data = {
                 assemblyName,
                 refName,
                 start,
                 end,
                 reversed,
-                offsetPx: (regionBpOffset + blockNum * blockSizeBp) * invBpPerPx,
-                parentRegion,
-                regionNumber,
+                offsetPx: blockOffsetPx,
+                displayedRegionIndex,
                 widthPx,
                 isLeftEndOfDisplayedRegion,
                 isRightEndOfDisplayedRegion,
-                key: `${assembleLocStringFast({
-                    assemblyName,
-                    refName,
-                    start,
-                    end,
-                    reversed,
-                })}-${regionNumber}${reversed ? '-reversed' : ''}`,
+                key,
             };
-            if (padding && regionNumber === 0 && blockNum === 0) {
-                blocks.push(new InterRegionPaddingBlock({
-                    key: `${blockData.key}-beforeFirstRegion`,
-                    widthPx: width,
-                    offsetPx: blockData.offsetPx - width,
+            blocks.push(elision && regionWidthPx < minimumBlockWidth
+                ? { ...data, type: 'ElidedBlock' }
+                : { ...data, type: 'ContentBlock' });
+            if (padding &&
+                displayedRegionIndex === displayedRegions.length - 1 &&
+                isRightEndOfDisplayedRegion) {
+                blocks.push({
+                    type: 'InterRegionPaddingBlock',
+                    key: `${key}-afterLastRegion`,
+                    widthPx: blockSizeCssPx,
+                    offsetPx: blockOffsetPx + widthPx,
                     variant: 'boundary',
-                }));
-            }
-            if (elision && regionWidthPx < minimumBlockWidth) {
-                blocks.push(new ElidedBlock(blockData));
-            }
-            else {
-                blocks.push(new ContentBlock(blockData));
-            }
-            if (padding) {
-                if (regionWidthPx >= minimumBlockWidth &&
-                    blockData.isRightEndOfDisplayedRegion &&
-                    regionNumber < displayedRegions.length - 1) {
-                    regionBpOffset += interRegionPaddingWidth * bpPerPx;
-                    blocks.push(new InterRegionPaddingBlock({
-                        key: `${blockData.key}-rightpad`,
-                        widthPx: interRegionPaddingWidth,
-                        offsetPx: blockData.offsetPx + blockData.widthPx,
-                    }));
-                }
-                if (regionNumber === displayedRegions.length - 1 &&
-                    blockData.isRightEndOfDisplayedRegion) {
-                    regionBpOffset += interRegionPaddingWidth * bpPerPx;
-                    blocks.push(new InterRegionPaddingBlock({
-                        key: `${blockData.key}-afterLastRegion`,
-                        widthPx: width,
-                        offsetPx: blockData.offsetPx + blockData.widthPx,
-                        variant: 'boundary',
-                    }));
-                }
+                });
             }
         }
         regionBpOffset += regionEnd - regionStart;

package/esm/util/chooseGridPitch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Given a scale ( bp/px ) and minimum distances (px) between major and minor
+ * gridlines, return an object like `{ majorPitch: bp, minorPitch: bp }` giving
+ * the gridline pitches to use.
+ */
+export declare function chooseGridPitch(scale: number, minMajorPitchPx: number, minMinorPitchPx: number): {
+    majorPitch: number;
+    minorPitch: number;
+};

package/esm/util/chooseGridPitch.js

@@ -0,0 +1,31 @@
+/**
+ * Given a scale ( bp/px ) and minimum distances (px) between major and minor
+ * gridlines, return an object like `{ majorPitch: bp, minorPitch: bp }` giving
+ * the gridline pitches to use.
+ */
+export function chooseGridPitch(scale, minMajorPitchPx, minMinorPitchPx) {
+    scale = Math.abs(scale);
+    const minMajorPitchBp = minMajorPitchPx * scale;
+    const majorMagnitude = +minMajorPitchBp.toExponential().split(/e/i, 2)[1];
+    let majorPitch = 10 ** majorMagnitude;
+    while (majorPitch < minMajorPitchBp) {
+        majorPitch *= 2;
+        if (majorPitch >= minMajorPitchBp) {
+            break;
+        }
+        majorPitch *= 2.5;
+    }
+    majorPitch = Math.max(majorPitch, 5);
+    const majorPitchPx = majorPitch / scale;
+    let minorPitch = 0;
+    if (!(majorPitch % 10) && majorPitchPx / 10 >= minMinorPitchPx) {
+        minorPitch = majorPitch / 10;
+    }
+    else if (!(majorPitch % 5) && majorPitchPx / 5 >= minMinorPitchPx) {
+        minorPitch = majorPitch / 5;
+    }
+    else if (!(majorPitch % 2) && majorPitchPx / 2 >= minMinorPitchPx) {
+        minorPitch = majorPitch / 2;
+    }
+    return { majorPitch, minorPitch };
+}

package/esm/util/clampToContig.d.ts

@@ -0,0 +1,26 @@
+import type { Assembly } from '../assemblyManager/assembly.ts';
+import type { Region } from './types/data.ts';
+/**
+ * Clamp a span to the extents of the contig it names, resolving the refName to
+ * canonical on the way. Returns undefined when the clamp leaves nothing — the
+ * span lies wholly off the end of the contig.
+ *
+ * **The undefined is the point.** A one-sided clamp is the shape this keeps
+ * getting written as, and it inverts: a span past the contig end comes back with
+ * its end below its start, which every consumer that SUMS region lengths then
+ * subtracts. That is silent, and it happens for real, on a GFF3 or a BAM
+ * annotated against a longer assembly than the FASTA in use — which JBrowse
+ * otherwise just draws past the end of. Two callers wrote the one-sided version
+ * and only one of them ever guarded it.
+ *
+ * `start` is floored at 0 even when the contig extents are unknown (`regions`
+ * still loading, or a refName this assembly doesn't have), because interbase has
+ * no coordinate below 0 whatever the contig turns out to be. Only the high end
+ * needs a length to clamp against, so without one it is left alone — and with no
+ * high bound there is nothing to invert, so such a span always comes back.
+ */
+export declare function clampToContig(assembly: Assembly, region: {
+    refName: string;
+    start: number;
+    end: number;
+}): Region | undefined;

package/esm/util/clampToContig.js

@@ -0,0 +1,28 @@
+/**
+ * Clamp a span to the extents of the contig it names, resolving the refName to
+ * canonical on the way. Returns undefined when the clamp leaves nothing — the
+ * span lies wholly off the end of the contig.
+ *
+ * **The undefined is the point.** A one-sided clamp is the shape this keeps
+ * getting written as, and it inverts: a span past the contig end comes back with
+ * its end below its start, which every consumer that SUMS region lengths then
+ * subtracts. That is silent, and it happens for real, on a GFF3 or a BAM
+ * annotated against a longer assembly than the FASTA in use — which JBrowse
+ * otherwise just draws past the end of. Two callers wrote the one-sided version
+ * and only one of them ever guarded it.
+ *
+ * `start` is floored at 0 even when the contig extents are unknown (`regions`
+ * still loading, or a refName this assembly doesn't have), because interbase has
+ * no coordinate below 0 whatever the contig turns out to be. Only the high end
+ * needs a length to clamp against, so without one it is left alone — and with no
+ * high bound there is nothing to invert, so such a span always comes back.
+ */
+export function clampToContig(assembly, region) {
+    const refName = assembly.getCanonicalRefName2(region.refName);
+    const bounds = assembly.getRegionForRefName(refName);
+    const start = Math.max(bounds?.start ?? 0, region.start);
+    const end = bounds ? Math.min(bounds.end, region.end) : region.end;
+    return end > start
+        ? { ...region, assemblyName: assembly.name, refName, start, end }
+        : undefined;
+}

package/esm/util/cmpStr.d.ts

@@ -0,0 +1 @@
+export declare function cmpStr(a: string, b: string): number;

package/esm/util/cmpStr.js

@@ -0,0 +1,7 @@
+// Deterministic, locale-independent string ordering. Returns 0 when equal so
+// it chains with `||` in multi-key comparators. Prefer this over
+// `localeCompare` wherever the order must be reproducible across environments
+// (e.g. sort keys feeding deterministic worker output or screenshot renders).
+export function cmpStr(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/esm/util/coarseStripHTML.js

@@ -1,17 +1,5 @@
+// not a sanitizer, this just removes html tags for use in measureText-based
+// element width calculations
 export function coarseStripHTML(s) {
-    let result = '';
-    let inTag = false;
-    for (let i = 0, l = s.length; i < l; i++) {
-        const char = s[i];
-        if (char === '<') {
-            inTag = true;
-        }
-        else if (char === '>') {
-            inTag = false;
-        }
-        else if (!inTag) {
-            result += char;
-        }
-    }
-    return result;
+    return s.replaceAll(/<[^<>]*>/g, '');
 }

package/esm/util/color/cssColorsLevel4.js

@@ -1,3 +1,4 @@
+// from https://www.w3.org/TR/css-color-4/#named-colors
 const colors = {
     aliceblue: '#F0F8FF',
     antiquewhite: '#FAEBD7',
@@ -148,9 +149,12 @@ const colors = {
     yellow: '#FFFF00',
     yellowgreen: '#9ACD32',
 };
+// Object.hasOwn rather than a bare index: the table is a plain object, so
+// `colors.constructor` and `colors.toString` come back as functions typed
+// `string`, and isNamedColor('toString') was true.
 export function namedColorToHex(name) {
-    return colors[name];
+    return Object.hasOwn(colors, name) ? colors[name] : undefined;
 }
 export function isNamedColor(name) {
-    return !!colors[name];
+    return Object.hasOwn(colors, name);
 }

package/esm/util/color/index.d.ts

@@ -1,5 +1,84 @@
-export declare function contrastingTextColor(color: string): string;
+/**
+ * Darken or lighten a color, depending on its luminance.
+ * Light colors are darkened, dark colors are lightened.
+ *
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(),
+ * hsl(), hsla(), or named color
+ * @param coefficient - multiplier in the range 0 - 1, defaults to 0.15
+ * @returns A CSS color string. Hex input values are returned as rgb
+ */
 export declare function emphasize(color: string, coefficient?: number): string;
+/**
+ * Push `foreground` away from `background` until it clears `minContrastRatio`,
+ * returning the closest it got when that ratio is unreachable.
+ *
+ * `minContrastRatio` genuinely cannot be met against a mid-luminance
+ * background: lighten/darken clamp their coefficient at 1, so the candidate
+ * pins at white/black, and against a `#b0b0b0` paper the best ratio any color
+ * reaches is about 2.2. This used to be a `while (ratio < min)` loop with an
+ * unbounded coefficient, which froze the render thread outright for 38 of the 40
+ * default refName colors.
+ */
 export declare function makeContrasting(foreground: string, background?: string, minContrastRatio?: number): string;
 export { isNamedColor, namedColorToHex } from './cssColorsLevel4.ts';
-export declare function randomColor(str: string): string;
+/**
+ * #api
+ * Move a color's OKLCH lightness by `lightnessShift` and scale its chroma,
+ * holding its hue.
+ *
+ * For extending a categorical palette past its length. Cycling a nine-color
+ * list over a 24-chromosome karyotype repeats the color outright; cycling it
+ * with a lightness shift per lap gives the hue back as a variant still told
+ * apart from the original — tab20's construction, which pairs a light and a
+ * dark of each hue.
+ *
+ * SHIFT rather than a fixed lightness, and SCALE rather than a fixed chroma,
+ * because a categorical palette is uneven on purpose: category10's brown and
+ * its red are 5 degrees apart in hue and are told apart by chroma alone, so
+ * re-lighting both to one (lightness, chroma) makes them the same color.
+ * Keeping each color's own relative chroma keeps brown reading as brown.
+ *
+ * In OKLCH rather than through `lighten`/`darken`, which work in sRGB, where
+ * the same coefficient moves a yellow and a blue by visibly different amounts:
+ * a lap has to read as one tone across the whole palette or it reads as noise.
+ *
+ * @param color - CSS color to transform
+ * @param lightnessShift - added to its OKLCH lightness (which is 0 - 1)
+ * @param chromaScale - multiplies its OKLCH chroma; the result is reduced at
+ *  constant hue if that lands out of gamut
+ * @returns A CSS hex color string
+ */
+export declare function relight(color: string, lightnessShift: number, chromaScale?: number): string;
+/**
+ * Generate a consistent random color for a given string.
+ * The same string will always generate the same color, with no shared palette
+ * state — so the same value (e.g. a gene symbol used as an ortholog id) gets the
+ * same color across independent tracks/panels.
+ *
+ * Statelessness is why this hashes into a color space rather than indexing a
+ * fixed palette of N: with no allocator there is no "next unused color", so an
+ * N-color palette collides by the birthday problem — six values into a
+ * twenty-color palette collide more often than not — while a hue circle does
+ * not repeat until 360 values. What a curated palette actually buys is
+ * perceptual evenness, and that comes from the space, not the list: hues are
+ * placed in OKLCH at a fixed lightness and chroma, so every value is equally
+ * light and equally colorful. HSL, which this used to use, is neither — its
+ * hue wheel spends a quarter of itself on greens that look identical and a
+ * sliver on yellow, and at one lightness its yellows glare while its blues go
+ * murky. That unevenness is what reads as "random RGB".
+ *
+ * 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
+ * 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
+ * strong color: a large fake category, drawn over the real ones. Grey says the
+ * only true thing about a feature with no value for the attribute you asked to
+ * colour by.
+ *
+ * @param str - The string to generate a color from
+ * @returns A CSS hex color string
+ */
+export declare function randomColor(str: string | undefined | null): string;

package/esm/util/color/index.js

@@ -1,39 +1,208 @@
-import { darken, emphasize as muiEmphasize, getContrastRatio, getLuminance as muiGetLuminance, lighten, } from '@mui/material/styles';
-import { namedColorToHex } from "./cssColorsLevel4.js";
-export function contrastingTextColor(color) {
-    const luminance = getLuminance(color);
-    return luminance > 0.5 ? 'black' : 'white';
-}
+// The color math is `ui/palette.ts`'s, not Material UI's. Same values —
+// `palette.test.ts` asserts them against a real MUI theme, and `emphasize` is
+// checked against MUI's directly below — but this module is reached from a
+// plugin's eagerly-evaluated code, and the MUI import made it one of the
+// first-party edges keeping `@mui/material/styles` in every host's first paint.
+// See agent-docs/reference/EAGER_BUNDLE.md.
+import { darken, getContrastRatio, lighten, getLuminance as luminanceOf, } from '../../ui/palette.js';
+import * as convert from '../color-bits/convert.js';
+import { cssColorToNormalizedRgb } from '../colorBits.js';
+import { namedColorToHex } from './cssColorsLevel4.js';
+/**
+ * The relative brightness of any point in a color space,
+ * normalized to 0 for darkest black and 1 for lightest white,
+ * with support for named colors on top.
+ *
+ * Formula: https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
+ *
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(),
+ *  hsl(), hsla(), or named color
+ * @returns The relative brightness of the color in the range 0 - 1
+ */
 function getLuminance(color) {
     const convertedColor = namedColorToHex(color);
-    return muiGetLuminance(convertedColor || color);
+    return luminanceOf(convertedColor || color);
 }
+/**
+ * Darken or lighten a color, depending on its luminance.
+ * Light colors are darkened, dark colors are lightened.
+ *
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(),
+ * hsl(), hsla(), or named color
+ * @param coefficient - multiplier in the range 0 - 1, defaults to 0.15
+ * @returns A CSS color string. Hex input values are returned as rgb
+ */
 export function emphasize(color, coefficient = 0.15) {
-    const convertedColor = namedColorToHex(color);
-    return muiEmphasize(convertedColor || color, coefficient);
+    const convertedColor = namedColorToHex(color) || color;
+    return getLuminance(convertedColor) > 0.5
+        ? darken(convertedColor, coefficient)
+        : lighten(convertedColor, coefficient);
 }
+const CONTRAST_STEPS = 20;
+/**
+ * Push `foreground` away from `background` until it clears `minContrastRatio`,
+ * returning the closest it got when that ratio is unreachable.
+ *
+ * `minContrastRatio` genuinely cannot be met against a mid-luminance
+ * background: lighten/darken clamp their coefficient at 1, so the candidate
+ * pins at white/black, and against a `#b0b0b0` paper the best ratio any color
+ * reaches is about 2.2. This used to be a `while (ratio < min)` loop with an
+ * unbounded coefficient, which froze the render thread outright for 38 of the 40
+ * default refName colors.
+ */
 export function makeContrasting(foreground, background = 'white', minContrastRatio = 3) {
-    let convertedForeground = namedColorToHex(foreground) || foreground;
+    const originalColor = namedColorToHex(foreground) || foreground;
     const convertedBackground = namedColorToHex(background) || background;
     const backgroundLuminance = getLuminance(convertedBackground);
-    let contrastRatio = getContrastRatio(convertedForeground, convertedBackground);
-    const originalColor = convertedForeground;
-    let coefficient = 0.05;
-    while (contrastRatio < minContrastRatio) {
-        convertedForeground =
-            backgroundLuminance > 0.5
-                ? darken(originalColor, coefficient)
-                : lighten(originalColor, coefficient);
-        coefficient += 0.05;
-        contrastRatio = getContrastRatio(convertedForeground, convertedBackground);
+    let best = originalColor;
+    let bestRatio = getContrastRatio(originalColor, convertedBackground);
+    // an integer step keeps the last coefficient exactly 1, where the clamp bites
+    for (let step = 1; step <= CONTRAST_STEPS && bestRatio < minContrastRatio; step++) {
+        const coefficient = step / CONTRAST_STEPS;
+        const candidate = backgroundLuminance > 0.5
+            ? darken(originalColor, coefficient)
+            : lighten(originalColor, coefficient);
+        const ratio = getContrastRatio(candidate, convertedBackground);
+        // lightening a dark color against a mid-grey background dips before it
+        // climbs, so track the max rather than taking the last candidate
+        if (ratio > bestRatio) {
+            best = candidate;
+            bestRatio = ratio;
+        }
+    }
+    return best;
+}
+export { 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
+// white/black. The three differ enough to separate two neighbouring hues, and
+// little enough that no tier reads as "the faded ones".
+// 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';
+const RANDOM_COLOR_TIERS = [
+    { lightness: 0.66, chroma: 0.15 },
+    { lightness: 0.56, chroma: 0.14 },
+    { lightness: 0.75, chroma: 0.12 },
+];
+// sRGB has room for very different amounts of chroma at different hues (a
+// vivid yellow exists, an equally vivid blue does not), so a requested chroma
+// is often outside the gamut. Bisect down to the most saturated in-gamut
+// version of the SAME hue and lightness, rather than letting the channel clamp
+// do it — clamping a channel shifts the hue, which is the one thing this must
+// hold constant.
+const GAMUT_BISECTION_STEPS = 8;
+const GAMUT_EPSILON = 1 / 512;
+function oklchToSrgb(lightness, chroma, hue) {
+    return convert.xyzd50ToSrgb(...convert.oklchToXyzd50(lightness, chroma, hue));
+}
+function inGamut(rgb) {
+    return rgb.every(v => v >= -GAMUT_EPSILON && v <= 1 + GAMUT_EPSILON);
+}
+function oklchToHex(lightness, chroma, hue) {
+    let rgb = oklchToSrgb(lightness, chroma, hue);
+    if (!inGamut(rgb)) {
+        let lo = 0;
+        let hi = chroma;
+        for (let i = 0; i < GAMUT_BISECTION_STEPS; i++) {
+            const mid = (lo + hi) / 2;
+            const candidate = oklchToSrgb(lightness, mid, hue);
+            if (inGamut(candidate)) {
+                lo = mid;
+                rgb = candidate;
+            }
+            else {
+                hi = mid;
+            }
+        }
     }
-    return convertedForeground;
+    return `#${rgb
+        .map(v => Math.max(0, Math.min(255, Math.round(v * 255)))
+        .toString(16)
+        .padStart(2, '0'))
+        .join('')}`;
 }
-export { isNamedColor, namedColorToHex } from "./cssColorsLevel4.js";
+/**
+ * #api
+ * Move a color's OKLCH lightness by `lightnessShift` and scale its chroma,
+ * holding its hue.
+ *
+ * For extending a categorical palette past its length. Cycling a nine-color
+ * list over a 24-chromosome karyotype repeats the color outright; cycling it
+ * with a lightness shift per lap gives the hue back as a variant still told
+ * apart from the original — tab20's construction, which pairs a light and a
+ * dark of each hue.
+ *
+ * SHIFT rather than a fixed lightness, and SCALE rather than a fixed chroma,
+ * because a categorical palette is uneven on purpose: category10's brown and
+ * its red are 5 degrees apart in hue and are told apart by chroma alone, so
+ * re-lighting both to one (lightness, chroma) makes them the same color.
+ * Keeping each color's own relative chroma keeps brown reading as brown.
+ *
+ * In OKLCH rather than through `lighten`/`darken`, which work in sRGB, where
+ * the same coefficient moves a yellow and a blue by visibly different amounts:
+ * a lap has to read as one tone across the whole palette or it reads as noise.
+ *
+ * @param color - CSS color to transform
+ * @param lightnessShift - added to its OKLCH lightness (which is 0 - 1)
+ * @param chromaScale - multiplies its OKLCH chroma; the result is reduced at
+ *  constant hue if that lands out of gamut
+ * @returns A CSS hex color string
+ */
+export function relight(color, lightnessShift, chromaScale = 1) {
+    const [lightness, chroma, hue] = convert.xyzd50ToOklch(...convert.srgbToXyzd50(...cssColorToNormalizedRgb(color)));
+    return oklchToHex(Math.max(0, Math.min(1, lightness + lightnessShift)), chroma * chromaScale, hue);
+}
+/**
+ * Generate a consistent random color for a given string.
+ * The same string will always generate the same color, with no shared palette
+ * state — so the same value (e.g. a gene symbol used as an ortholog id) gets the
+ * same color across independent tracks/panels.
+ *
+ * Statelessness is why this hashes into a color space rather than indexing a
+ * fixed palette of N: with no allocator there is no "next unused color", so an
+ * N-color palette collides by the birthday problem — six values into a
+ * twenty-color palette collide more often than not — while a hue circle does
+ * not repeat until 360 values. What a curated palette actually buys is
+ * perceptual evenness, and that comes from the space, not the list: hues are
+ * placed in OKLCH at a fixed lightness and chroma, so every value is equally
+ * light and equally colorful. HSL, which this used to use, is neither — its
+ * hue wheel spends a quarter of itself on greens that look identical and a
+ * sliver on yellow, and at one lightness its yellows glare while its blues go
+ * murky. That unevenness is what reads as "random RGB".
+ *
+ * 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
+ * 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
+ * strong color: a large fake category, drawn over the real ones. Grey says the
+ * only true thing about a feature with no value for the attribute you asked to
+ * colour by.
+ *
+ * @param str - The string to generate a color from
+ * @returns A CSS hex color string
+ */
 export function randomColor(str) {
-    let sum = 0;
+    if (!str) {
+        return NO_CATEGORY_COLOR;
+    }
+    // djb2 hash — much better distribution than a char-code sum (anagrams and
+    // similar strings get well-separated hues).
+    let hash = 5381;
     for (let i = 0; i < str.length; i++) {
-        sum += str.charCodeAt(i);
+        hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
     }
-    return `hsl(${sum * 10}, 50%, 50%)`;
+    const h = hash >>> 0;
+    const hue = h % 360;
+    // The tier is picked by a separately mixed hash (xorshift + Math.imul for a
+    // real 32-bit multiply — a plain `*` overflows float precision and drops the
+    // low bits) so it varies independently of the hue rather than tracking it.
+    const mix = Math.imul(h ^ (h >>> 15), 2246822519) >>> 0;
+    const tier = RANDOM_COLOR_TIERS[mix % RANDOM_COLOR_TIERS.length];
+    return oklchToHex(tier.lightness, tier.chroma, hue);
 }

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

@@ -0,0 +1,4 @@
+export declare function cast(n: number): number;
+export declare function get(n: number, offset: number): number;
+export declare function set(n: number, offset: number, byte: number): number;
+export declare function clampByte(n: number): number;