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

package/esm/util/colorScale.js

@@ -0,0 +1,243 @@
+/**
+ * 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 const COLOR_SCALES = [
+    '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 const IDENTITY_SCALE = 'identity';
+const CATEGORICAL_PRESET = { scale: 'categorical' };
+/**
+ * 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 const UNIVERSAL_FIELD_PRESETS = {
+    strand: {
+        scale: 'categorical',
+        missing: '0',
+        domain: ['1', '-1', '0'],
+        range: ['tomato', 'cornflowerblue', 'goldenrod'],
+        labels: ['Forward strand', 'Reverse strand', 'No strand'],
+    },
+    svType: {
+        scale: 'categorical',
+        domain: ['DEL', 'DUP', 'INS', 'INV', 'CNV', 'TR', 'BND', 'CPX', 'OTHER'],
+        range: [
+            '#e41a1c',
+            '#377eb8',
+            '#800080',
+            '#ff7f00',
+            '#7e6148',
+            '#e7298a',
+            '#17becf',
+            '#66a61e',
+            '#000000',
+        ],
+        labels: [
+            'Deletion',
+            'Duplication',
+            'Insertion',
+            'Inversion',
+            'Copy-number variable',
+            'Tandem repeat',
+            'Breakend / translocation',
+            'Complex',
+            'Other / mixed',
+        ],
+        title: 'SV type',
+    },
+};
+/** The universal preset of `field`, if it has one. */
+export function universalPresetOf(field) {
+    return Object.hasOwn(UNIVERSAL_FIELD_PRESETS, field)
+        ? UNIVERSAL_FIELD_PRESETS[field]
+        : undefined;
+}
+/** Every field categorical while `scale` is unset, with nothing preset. */
+export const CATEGORICAL_FIELD_PRESETS = {
+    '*': CATEGORICAL_PRESET,
+};
+/**
+ * What a feature's field paints through while `scale` is unset: `score` a
+ * ramp, any other field categories.
+ */
+export const FEATURE_FIELD_PRESETS = {
+    score: { scale: 'linear' },
+    '*': CATEGORICAL_PRESET,
+};
+/**
+ * A field's preset under `presets`: its own, else a universal one, else
+ * `*`'s, else categorical.
+ */
+export function presetOf(presets, field) {
+    return ((Object.hasOwn(presets, field)
+        ? presets[field]
+        : (universalPresetOf(field) ?? presets['*'])) ?? CATEGORICAL_PRESET);
+}
+/** What a field paints through under `presets` while `scale` is unset. */
+export function fieldScaleOf(presets, field) {
+    return presetOf(presets, field).scale;
+}
+function unwritten(value) {
+    return value === undefined || (Array.isArray(value) && value.length === 0);
+}
+/**
+ * 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 function withPreset(color, presets) {
+    const field = color.field ?? '';
+    const preset = presetOf(presets, field);
+    if (!field || (color.scale ?? preset.scale) !== preset.scale) {
+        return color;
+    }
+    const written = new Map(Object.entries(color));
+    const ordered = preset.scale !== 'categorical' ||
+        !preset.domain ||
+        unwritten(written.get('domain'));
+    const filled = Object.entries(preset).filter(([key]) => key !== 'scale' &&
+        key !== 'missing' &&
+        (ordered || (key !== 'range' && key !== 'labels')) &&
+        unwritten(written.get(key)));
+    return filled.length > 0 ? { ...color, ...Object.fromEntries(filled) } : color;
+}
+/**
+ * The scale a colour object paints through: `none` while no `field` is
+ * named, else its own `scale`, or `fieldScale` where that is unset.
+ */
+export function paintedScale({ scale, field }, fieldScale) {
+    return field ? (scale ?? fieldScale) : 'none';
+}
+/**
+ * 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 function scaleEndProblems({ domainMin, domainMax, domainQuantile }, { reverse = false } = {}) {
+    return [
+        ...(domainMin !== undefined &&
+            domainMax !== undefined &&
+            domainMin > domainMax
+            ? [
+                {
+                    rule: 'domain-ends',
+                    slot: 'domainMax',
+                    message: `domainMax is below domainMin: the scale spans the two in order either way${reverse ? ', and reverse is what turns it round' : ''}`,
+                },
+            ]
+            : []),
+        ...(domainQuantile !== undefined &&
+            !(domainQuantile >= 0.5 && domainQuantile <= 1)
+            ? [
+                {
+                    rule: 'domain-quantile',
+                    slot: 'domainQuantile',
+                    message: 'domainQuantile is a fraction from 0.5 to 1, not a percent: 1 follows the extremes and 0.99 clips the outermost 1% at each end; above 1 reads as 1 and below 0.5 as 0.5',
+                },
+            ]
+            : []),
+    ];
+}
+/** Problems as the lines a display's corner notice lists, under the setting that holds the scale. */
+export function noticeLines(setting, problems) {
+    return problems.map(({ slot, message }) => `${setting}.${slot}: ${message}`);
+}
+function pinned(entry) {
+    return entry !== '' && Number.isFinite(Number(entry));
+}
+/**
+ * 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 function colorProblems(written, presets) {
+    const color = withPreset(written, presets);
+    const { domain = [] } = color;
+    const { range = [] } = written;
+    const scale = color.scale === IDENTITY_SCALE
+        ? IDENTITY_SCALE
+        : paintedScale({ scale: color.scale, field: color.field ?? '' }, fieldScaleOf(presets, color.field ?? ''));
+    const problems = [];
+    if (scale === 'threshold') {
+        if (domain.some((cut, i) => !pinned(cut) || Number(cut) <= Number(domain[i - 1]))) {
+            problems.push({
+                rule: 'threshold-cuts',
+                slot: 'domain',
+                message: 'threshold cuts are distinct numbers, read in ascending order, with the range running from the lowest interval; a repeated cut leaves an interval no value falls in',
+            });
+        }
+        if (domain.length > 0 &&
+            range.length > 0 &&
+            range.length !== domain.length + 1) {
+            problems.push({
+                rule: 'threshold-range',
+                slot: 'range',
+                message: `${domain.length} threshold ${domain.length === 1 ? 'cut makes' : 'cuts make'} ${domain.length + 1} intervals, one colour each, and range lists ${range.length}: a missing colour comes from the default palette and an extra one is never read`,
+            });
+        }
+    }
+    if (scale === 'linear' || scale === 'log') {
+        if (domain.length > 0) {
+            problems.push({
+                rule: 'ramp-domain',
+                slot: 'domain',
+                message: "a linear or log scale reads no domain, which is a categorical scale's order and a threshold scale's cuts; a ramp's ends are domainMin and domainMax where the colour has them",
+            });
+        }
+        problems.push(...scaleEndProblems(color, { reverse: true }));
+    }
+    const { labels = [] } = color;
+    const named = scale === 'categorical' || scale === IDENTITY_SCALE
+        ? domain.length
+        : scale === 'threshold'
+            ? domain.length + 1
+            : undefined;
+    const cutsFromData = scale === 'threshold' && domain.length === 0;
+    if (labels.length > 0 &&
+        !cutsFromData &&
+        (named === undefined || labels.length > named)) {
+        const what = scale === 'categorical'
+            ? 'value'
+            : scale === IDENTITY_SCALE
+                ? 'colour'
+                : 'interval';
+        problems.push({
+            rule: 'labels-domain',
+            slot: 'labels',
+            message: named === undefined
+                ? "labels names a categorical scale's values, a threshold scale's intervals or an identity scale's colours, and this colour paints none of them"
+                : `labels names one ${what} each, and ${labels.length} ${labels.length === 1 ? 'label names' : 'labels name'} ${named} ${named === 1 ? what : `${what}s`}: a label past them names nothing`,
+        });
+    }
+    return problems;
+}
+/** `colorProblems` as the lines a display's corner notice lists, under `color`. */
+export function colorNotices(color, presets) {
+    return noticeLines('color', colorProblems(color, presets));
+}

package/esm/util/colorSchemes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * #api
+ * The named ramps a continuous colour scale's `scheme` takes, each one a stop
+ * table in `colorRamp.ts` that every ramp baker reads, so no display can name
+ * a scheme nothing bakes. `viridis`, `magma`, `inferno` and `cividis` are
+ * matplotlib's perceptual ramps, dark at the low end; `juicebox` fades from
+ * transparent to red, as Juicebox paints contacts; `fall` runs white through
+ * yellow and red to black, as HiGlass does; `reds` and `blues` are
+ * ColorBrewer's, from white; `redblue` and `purpleorange` diverge through
+ * white, ColorBrewer's RdBu and PuOr.
+ */
+export declare const COLOR_SCHEMES: readonly ['viridis', 'magma', 'inferno', 'cividis', 'juicebox', 'fall', 'reds', 'blues', 'redblue', 'purpleorange'];
+/** #api */
+export type ColorSchemeName = (typeof COLOR_SCHEMES)[number];
+/**
+ * #api
+ * The ramp a continuous scale samples while it names no `range` and no
+ * `scheme`, so a declaration spelling it out and one leaving it unset resolve
+ * alike.
+ */
+export declare const DEFAULT_COLOR_SCHEME: ColorSchemeName;

package/esm/util/colorSchemes.js

@@ -0,0 +1,30 @@
+/**
+ * #api
+ * The named ramps a continuous colour scale's `scheme` takes, each one a stop
+ * table in `colorRamp.ts` that every ramp baker reads, so no display can name
+ * a scheme nothing bakes. `viridis`, `magma`, `inferno` and `cividis` are
+ * matplotlib's perceptual ramps, dark at the low end; `juicebox` fades from
+ * transparent to red, as Juicebox paints contacts; `fall` runs white through
+ * yellow and red to black, as HiGlass does; `reds` and `blues` are
+ * ColorBrewer's, from white; `redblue` and `purpleorange` diverge through
+ * white, ColorBrewer's RdBu and PuOr.
+ */
+export const COLOR_SCHEMES = [
+    'viridis',
+    'magma',
+    'inferno',
+    'cividis',
+    'juicebox',
+    'fall',
+    'reds',
+    'blues',
+    'redblue',
+    'purpleorange',
+];
+/**
+ * #api
+ * The ramp a continuous scale samples while it names no `range` and no
+ * `scheme`, so a declaration spelling it out and one leaving it unset resolve
+ * alike.
+ */
+export const DEFAULT_COLOR_SCHEME = 'viridis';

package/esm/util/copyToClipboard.js

@@ -7,7 +7,14 @@ export default async function copyToClipboard(text, options = {}) {
     // navigator.clipboard is only present in secure contexts; isSecureContext is
     // the real gate, so insecure http:// falls through to execCommand below
     if (format === 'text/plain' && window.isSecureContext) {
-        await navigator.clipboard.writeText(text);
+        try {
+            await navigator.clipboard.writeText(text);
+        }
+        catch (e) {
+            if (!execCommandCopy(text, format)) {
+                throw e;
+            }
+        }
     }
     else if (!execCommandCopy(text, format)) {
         throw new Error('the browser rejected the clipboard write');

package/esm/util/{createStopTokenRotation.d.ts → createAbortRotation.d.ts}

@@ -1,5 +1,4 @@
 import type { RpcStatus, StatusWindow } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 /**
  * Where a rotation reports, in the one of two modes the host is actually in.
@@ -13,19 +12,20 @@ import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
  */
 export type StatusReporter = {
     /**
-     * The host's own window, present on any display composing the LGV fetch
-     * mixins. The rotation reports through it rather than opening a SECOND on
-     * the same status field — which is what one-window-per-owner exists to
+     * The host's own window, present on any display composing `FetchMixin`.
+     * The rotation reports through it rather than opening a SECOND on the
+     * same status field — which is what one-window-per-owner exists to
      * prevent.
      */
     statusWindow: StatusWindow;
     setStatusMessage?: never;
 } | {
     /**
-     * The sink for the window the rotation opens for itself. This is the mode
-     * the displays this helper was written for are in (dotplot, synteny),
-     * which compose no fetch mixin, along with every
-     * {@link createStatusChannel} holder.
+     * The sink for the window the rotation opens for itself: the mode of a
+     * fetch on a host with no window of its own — the prerequisite reads,
+     * chord, the breakpoint overlay — along with every
+     * {@link createStatusChannel} holder. The comparative displays this
+     * helper was written for lend a window now (ADR-105).
      */
     setStatusMessage: (status?: RpcStatus) => void;
     statusWindow?: never;
@@ -50,8 +50,7 @@ export interface StatusChannel {
 }
 export declare function createStatusChannel(): StatusChannel;
 export interface ActiveFetch {
-    /** stop token to forward to the RPC call */
-    stopToken: StopToken;
+    signal: AbortSignal;
     /**
      * True only while this is still the most recent fetch AND `self` is alive.
      * Gate every post-await write — result commit, error set — on it so a
@@ -72,31 +71,29 @@ export interface ActiveFetch {
      * other operation on the host is still reporting.
      *
      * Both together, because a caller doing it by hand gets a subset.
-     * `isCurrent` is `token === current && isAlive`, and a run that *completes*
-     * never rotates its own token — so without this the guard stays open past the
+     * `isCurrent` is `signal === current && isAlive`, and a run that *completes*
+     * never rotates its own signal — so without this the guard stays open past the
      * work and a trailing write lands on top of a hand-written
      * `setStatusMessage(undefined)` up to a window later.
      *
-     * A **superseded** run calls it too, and must: its slot goes on voting for a
-     * phase that is over until it does. The run that replaced it has already
-     * opened its own slot by then, so the label the user is looking at survives.
+     * A superseded run's slot is already retired by the `begin()` that replaced
+     * it, so its `end()` only closes the guard.
      */
     end: () => void;
 }
 /**
- * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
+ * Latest-wins abort rotation for a fetch that runs in a bare `autorun`
  * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
  * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
- * `begin()` aborts the prior fetch's token and returns a fresh one plus an
- * `isCurrent()` guard that captures this run's token — gate every post-await
- * write on it and a superseded or torn-down fetch can never clobber fresher
- * data. The guard is the return value, so a caller can't forget to compare a
- * token by hand.
+ * `begin()` aborts the prior fetch and returns a fresh signal plus an
+ * `isCurrent()` guard that captures this run — gate every post-await write on
+ * it and a superseded or torn-down fetch can never clobber fresher data. The
+ * guard is the return value, so a caller can't forget to compare by hand.
  *
  * `end()` in the run's `finally` is the other half, and for the same reason —
  * see {@link ActiveFetch.end} for the two things it does together.
  *
- * Owns the token mechanics and the status channel; the caller keeps its own
+ * Owns the controller and the status channel; the caller keeps its own
  * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
  * (so `cancelFetch` can reach it), `installFetch` one per installation (every
  * other fetch in the tree runs on that skeleton), and the synteny diagonalize
@@ -110,7 +107,8 @@ export interface ActiveFetch {
  * passes a {@link createStatusChannel}, which is one volatile instead of two
  * fields and an action.
  */
-export declare function createStopTokenRotation(self: IStateTreeNode, report: StatusReporter): {
+export type AbortRotation = ReturnType<typeof createAbortRotation>;
+export declare function createAbortRotation(self: IStateTreeNode, report: StatusReporter): {
     begin(): ActiveFetch;
     cancel: () => void;
     dispose(): void;

package/esm/util/{createStopTokenRotation.js → createAbortRotation.js}

@@ -1,7 +1,6 @@
 import { isAlive } from '@jbrowse/mobx-state-tree';
 import { observable, runInAction } from 'mobx';
 import { createStatusWindow, statusFraction, statusMessageText, } from './progress.js';
-import { createStopToken, stopStopToken } from './stopToken.js';
 export function createStatusChannel() {
     // MobX rather than MST, so this is a value a model can hold rather than a
     // node it has to parent. A volatile is `observable.ref`, so the fields have
@@ -28,35 +27,8 @@ export function createStatusChannel() {
         },
     };
 }
-/**
- * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
- * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
- * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
- * `begin()` aborts the prior fetch's token and returns a fresh one plus an
- * `isCurrent()` guard that captures this run's token — gate every post-await
- * write on it and a superseded or torn-down fetch can never clobber fresher
- * data. The guard is the return value, so a caller can't forget to compare a
- * token by hand.
- *
- * `end()` in the run's `finally` is the other half, and for the same reason —
- * see {@link ActiveFetch.end} for the two things it does together.
- *
- * Owns the token mechanics and the status channel; the caller keeps its own
- * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
- * (so `cancelFetch` can reach it), `installFetch` one per installation (every
- * other fetch in the tree runs on that skeleton), and the synteny diagonalize
- * progress wrapper (`withDiagonalizeProgress`) directly.
- *
- * `report` is passed rather than read off `self`, so where the status lands is
- * the caller's decision and not a shape this imposes. A display passes itself —
- * its status fields are part of its own API, and one composing `FetchMixin`
- * passes the model-wide window along with them (see `StatusReporter`).
- * Anything with one operation to narrate and no status vocabulary of its own
- * passes a {@link createStatusChannel}, which is one volatile instead of two
- * fields and an action.
- */
-export function createStopTokenRotation(self, report) {
-    let currentStopToken;
+export function createAbortRotation(self, report) {
+    let current;
     // The host's window when it has one, so a display composing `FetchMixin` has
     // one window rather than two writing one field; our own otherwise. Lent means
     // this fetch is one slot beside the host's others rather than a second writer
@@ -76,8 +48,8 @@ export function createStopTokenRotation(self, report) {
     /**
      * Stop the in-flight fetch without starting one, and retire its slot.
      *
-     * Dropping `currentStopToken` rather than only stopping it is what closes
-     * every outstanding guard: `isCurrent` compares against this field, so one
+     * Dropping `current` rather than only aborting it is what closes every
+     * outstanding guard: `isCurrent` compares against this field, so one
      * assignment makes a fetch already past its await stale, whether it is the one
      * being cancelled or a superseded predecessor still unwinding.
      *
@@ -88,10 +60,8 @@ export function createStopTokenRotation(self, report) {
      * works: `addDisposer(self, rotation.dispose)` is a shape callers reach for.
      */
     const cancel = () => {
-        if (currentStopToken) {
-            stopStopToken(currentStopToken);
-            currentStopToken = undefined;
-        }
+        current?.abort();
+        current = undefined;
         // a fetch in flight when this is called never reaches its `finally`, and a
         // slot nobody retires goes on voting
         openStream?.clear();
@@ -99,27 +69,26 @@ export function createStopTokenRotation(self, report) {
     };
     return {
         begin() {
-            if (currentStopToken) {
-                stopStopToken(currentStopToken);
-            }
-            const stopToken = createStopToken();
-            currentStopToken = stopToken;
+            current?.abort();
+            const controller = new AbortController();
+            current = controller;
             // `ended` is the term a completed fetch has no other way to express: the
-            // token comparison catches a SUPERSEDED one, but a fetch that simply
-            // finished still holds the current token. The stream reads it as well as
+            // controller comparison catches a SUPERSEDED one, but a fetch that simply
+            // finished still holds the current one. The stream reads it as well as
             // the caller's commit guard, which is why both go through this closure.
             let ended = false;
-            const isCurrent = () => !ended && stopToken === currentStopToken && isAlive(self);
-            // Opened BEFORE the superseded run reaches its `finally`, which is what
-            // keeps the label the user is looking at from blanking between the two:
-            // the run being replaced is suspended at an await and resumes a microtask
-            // from now, by which point this slot is already voting. A fetch being
-            // SUPERSEDED is the one case where the display does not stop loading, so
-            // a gap there reads as the overlay's `'Loading'` fallback (ADR-080).
+            const isCurrent = () => !ended && controller === current && isAlive(self);
+            // Opened before the superseded slot retires, so the window is never idle
+            // across the handover and the label on screen survives it (ADR-080).
+            // Retired here rather than left to the superseded run's `finally`, which
+            // comes only when its work settles — and a CRAM record read, or a shared
+            // `cachedSetup` parse the replacement rejoins, runs on past the abort,
+            // its last reading summed into this fetch's bar the whole time.
             const stream = statusWindow.open({ isCurrent });
+            openStream?.clear();
             openStream = stream;
             return {
-                stopToken,
+                signal: controller.signal,
                 isCurrent,
                 statusCallback: stream.statusCallback,
                 end() {
@@ -134,7 +103,7 @@ export function createStopTokenRotation(self, report) {
         cancel,
         dispose() {
             cancel();
-            // the window outlives the token: a trailing write is queued on a timer,
+            // the window outlives the fetch: a trailing write is queued on a timer,
             // and while the sink's `isCurrent` makes it a no-op rather than a write to
             // a dead node, the timer itself still stands for up to a window past
             // teardown. Only ours — resetting a lent one drops a write the host's

package/esm/util/createSvgRasterCanvas.d.ts

@@ -1,5 +1,15 @@
 export interface SvgRasterCanvasOpts {
+    /**
+     * headless canvas factory for `rasterizeLayers` (jbrowse-img passes one);
+     * without it the raster path needs a DOM canvas
+     */
     createCanvas?: (width: number, height: number) => HTMLCanvasElement;
+    /**
+     * decodes SVG markup into an image a `createCanvas` canvas can draw, where
+     * the environment's `Image` cannot (node, jsdom). A headless decoder draws
+     * vectors only, so markup headed for it carries no rasterized layers.
+     */
+    decodeSvg?: (markup: string) => Promise<CanvasImageSource>;
 }
 export declare function createSvgRasterCanvas(width: number, height: number, opts: SvgRasterCanvasOpts | undefined): {
     canvas: HTMLCanvasElement;

package/esm/util/cssColorParse.d.ts

@@ -0,0 +1,15 @@
+import type { Color } from './color-bits/core.ts';
+/**
+ * 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.
+ */
+export declare function bedTriple(str: string): string | undefined;
+export declare function parseCssColorOr(color: string, fallback: Color): Color;
+/**
+ * Whether the painters read `color` as a color — a CSS name, hex, functional
+ * form, `transparent` or a BED triple — rather than as the invalid sentinel.
+ * What a `color` config slot admits.
+ */
+export declare function isCssColor(color: string): boolean;

package/esm/util/cssColorParse.js

@@ -0,0 +1,53 @@
+import { newColor } from './color-bits/core.js';
+import { parse } from './color-bits/parse.js';
+import { namedColorToHex } from './color/cssColorsLevel4.js';
+// Split out of colorBits.ts so a config slot can ask "is this a color?" without
+// taking that module's re-export of render-core's packers: the closure ceiling
+// in scripts/moduleClosure.test.ts is what says so.
+// 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})$/;
+/**
+ * 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.
+ */
+export 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;
+}
+function tryParseCssColor(color) {
+    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 undefined;
+    }
+}
+// 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) {
+    return tryParseCssColor(color) ?? fallback;
+}
+/**
+ * Whether the painters read `color` as a color — a CSS name, hex, functional
+ * form, `transparent` or a BED triple — rather than as the invalid sentinel.
+ * What a `color` config slot admits.
+ */
+export function isCssColor(color) {
+    return tryParseCssColor(color) !== undefined;
+}

package/esm/util/diagonalizeRegions.d.ts

@@ -1,5 +1,4 @@
 import type { StatusCallback } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 import type { Region } from './types/data.ts';
 export interface AlignmentData {
     refRefName: string;
@@ -17,7 +16,7 @@ export interface DiagonalizationResult {
         regionsReversed: number;
     };
 }
-export declare function diagonalizeRegions(alignments: AlignmentData[], referenceRegions: Region[], currentRegions: Region[], { stopToken, statusCallback, }?: {
-    stopToken?: StopToken;
+export declare function diagonalizeRegions(alignments: AlignmentData[], referenceRegions: Region[], currentRegions: Region[], { signal, statusCallback, }?: {
+    signal?: AbortSignal;
     statusCallback?: StatusCallback;
 }): Promise<DiagonalizationResult>;