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

package/esm/util/svAlt.js

@@ -0,0 +1,364 @@
+import { parseBreakend } from '@gmod/vcf';
+export const SV_SYMBOLIC_ALLELES = [
+    '<TRA',
+    '<DEL',
+    '<INV',
+    '<INS',
+    '<DUP',
+    '<CNV',
+];
+/**
+ * #api
+ * parseBreakend, honoring its `Breakend | undefined` signature. ALT strings are
+ * user data and malformed breakends do occur; @gmod/vcf <=7.0.10 throws on them
+ * instead of returning undefined, which would otherwise fail a whole render or
+ * feature-parse pass over one bad allele. Use this everywhere rather than
+ * importing parseBreakend directly; it can become a plain re-export once the
+ * upstream fix ships.
+ */
+export function safeParseBreakend(alt) {
+    try {
+        return parseBreakend(alt);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * #api
+ * The mate locString ("chr2:100") of a parsed breakend, or undefined when it
+ * names no navigable position. Two ALT forms reach here without one: a single
+ * breakend (`.A` / `G.`) has no mate at all, and the symbolic-mate forms
+ * (`G<DEL>`, `<DEL>G`) get a placeholder `<DEL>:1` from parseBreakend, which
+ * puts a symbolic allele id where a contig name belongs. Callers that navigate
+ * or split-view a mate must drop both rather than treat `<DEL>` as a refName.
+ */
+export function getBreakendMateLocString(breakend) {
+    const matePosition = breakend?.MatePosition;
+    return matePosition === undefined || matePosition.startsWith('<')
+        ? undefined
+        : matePosition;
+}
+// VCF 4.5 computes END rather than storing it: a DEL, DUP, INV or CNV allele
+// ends |SVLEN| bases past POS, SVLEN one value per ALT (one for all in files
+// older than 4.4)
+function spannedEnd(feature, alt, svlen, alleleIndex) {
+    if (!/^<(DEL|DUP|INV|CNV)[:>]/.test(alt) || !Array.isArray(svlen)) {
+        return undefined;
+    }
+    const len = Math.abs(Number(svlen.length === 1 ? svlen[0] : svlen[alleleIndex]));
+    return len > 0 ? feature.get('start') + 1 + len : undefined;
+}
+/**
+ * #api
+ * Parse raw (non-assembly-resolved) mate coordinates from a VCF SV feature+alt.
+ * Returns undefined when no mate coordinate info is found. `alleleIndex` is
+ * the alt's place in `ALT`, which a record repeating one symbolic allele with
+ * several lengths needs; it defaults to the first place `alt` appears.
+ */
+export function parseSvAlt(feature, alt, alleleIndex = Math.max(0, feature.get('ALT')?.indexOf(alt ?? '') ?? 0)) {
+    const bnd = alt !== undefined ? safeParseBreakend(alt) : undefined;
+    const mateLocString = getBreakendMateLocString(bnd);
+    const refName = feature.get('refName');
+    if (alt !== undefined && SV_SYMBOLIC_ALLELES.some(a => alt.startsWith(a))) {
+        // An insertion has one end: its END, where a caller writes one, is POS.
+        if (alt.startsWith('<INS')) {
+            return undefined;
+        }
+        const info = feature.get('INFO');
+        const matePos = info?.END?.[0] ??
+            spannedEnd(feature, alt, info?.SVLEN, alleleIndex);
+        if (matePos === undefined) {
+            return undefined;
+        }
+        return {
+            mateRefName: info?.CHR2?.[0] ?? refName,
+            matePos,
+        };
+    }
+    else if (bnd !== undefined && mateLocString !== undefined) {
+        // Split at the LAST colon, the same rule `parseLocString` applies and for
+        // the same reason: a refName may contain one. GRCh38's full analysis set
+        // names its HLA contigs `HLA-A*01:01:01:01`, so a mate on one arrives here
+        // as `HLA-A*01:01:01:01:1000` and splitting at the first colon read the
+        // chromosome as `HLA-A*01` and the position as 1.
+        const colon = mateLocString.lastIndexOf(':');
+        const mateRefName = mateLocString.slice(0, colon);
+        const matePosStr = mateLocString.slice(colon + 1);
+        const matePos = Number(matePosStr);
+        // A position that is not a 1-based coordinate is not a location. Returning
+        // one anyway put it through `svMateLocus` into a fetch region and a panel's
+        // `centerAt`, neither of which reports anything. `Number` alone is too
+        // generous to screen on: it reads `''` as 0 and `'0x10'` as 16.
+        if (colon <= 0 || !/^\d+$/.test(matePosStr) || matePos < 1) {
+            return undefined;
+        }
+        return { mateRefName, matePos, ...breakendKeepsDirections(bnd) };
+    }
+    return undefined;
+}
+/**
+ * #api
+ * Which way the sequence each end of a breakend KEEPS runs from its breakpoint,
+ * as `+1 = right` / `-1 = left` — the convention `StarFusionAdapter`'s
+ * `tickDirection` states and the one every producer in the tree emits.
+ *
+ * The two halves read their strings with OPPOSITE polarity, which is the whole
+ * reason to state them together. `Join: 'right'` says the mate piece is joined
+ * to the RIGHT of the ref base, so this end keeps the sequence to its left:
+ * negated. `MateDirection: 'right'` says the mate's own piece extends to the
+ * right of the mate position, which is already the direction it keeps: taken as
+ * read. So `N[chr2:2000[` is `{ joinDirection: -1, mateDirection: 1 }`, and that
+ * is the same pair `StarFusionAdapter` emits for the fusion it describes — the
+ * donor keeps the sequence below its breakpoint (-1) and the acceptor the
+ * sequence above its own (+1).
+ *
+ * Split out of `parseSvAlt` because a consumer holding an already-parsed
+ * `Breakend` was re-deriving it by hand, in two adjacent ternaries of opposite
+ * polarity — the shape that produced 78bb7b84f9.
+ */
+export function breakendKeepsDirections(bnd) {
+    return {
+        mateDirection: bnd.MateDirection === 'left' ? -1 : 1,
+        joinDirection: bnd.Join === 'left' ? 1 : -1,
+    };
+}
+/**
+ * #api
+ * Breakend notation, without parsing it: bracket forms (`G[chr2:100[`), single
+ * breakends (`.A` / `G.`), and the symbolic-mate form (`G<DEL>`, an angle
+ * bracket past position 0; a leading `<` is a plain symbolic allele).
+ */
+export function isBreakend(alt) {
+    return (alt.includes('[') ||
+        alt.includes(']') ||
+        alt.startsWith('.') ||
+        alt.endsWith('.') ||
+        alt.lastIndexOf('<') > 0);
+}
+/**
+ * #api
+ * The conventional size floor for calling a sequence indel structural.
+ */
+export const SV_MIN_LENGTH = 50;
+const CLASS_OF_TOKEN = {
+    DEL: 'DEL',
+    DUP: 'DUP',
+    INS: 'INS',
+    INV: 'INV',
+    CNV: 'CNV',
+    TR: 'TR',
+    VNTR: 'TR',
+    BND: 'BND',
+    TRA: 'BND',
+    CTX: 'BND',
+    CPX: 'CPX',
+    INVDUP: 'CPX',
+    CHROMOTHRIPSIS: 'CPX',
+    CHROMOPLEXY: 'CPX',
+    BFB: 'CPX',
+    DOUBLEMINUTE: 'CPX',
+};
+// gVCF's `<NON_REF>` and bcftools mpileup's `<*>` stand for whatever allele
+// the caller did not name, not for a structure.
+const ANY_OTHER_ALLELE = new Set(['<NON_REF>', '<*>']);
+/**
+ * #api
+ * The class a symbolic allele id, `SVTYPE` or `EVENTTYPE` names. A subtype folds
+ * into its first level (`DEL:ME:ALU` is DEL, `DUP:TANDEM` DUP), except the
+ * tandem repeats VCF 4.4 spells `CNV:TR` and ExpansionHunter `STRn`, and the
+ * inverted duplication `INV:DUP`. 1000 Genomes' `CNn` counts one haplotype's
+ * copies, so none is a deletion and two or more a duplication. `''` for an
+ * empty or missing token.
+ */
+export function svClassOfToken(raw) {
+    const token = raw.trim().toUpperCase();
+    if (token === '' || token === '.') {
+        return '';
+    }
+    if (token === 'CNV:TR') {
+        return 'TR';
+    }
+    if (token === 'INV:DUP') {
+        return 'CPX';
+    }
+    const first = token.split(':')[0];
+    const copies = /^CN(\d+)$/.exec(first);
+    if (copies) {
+        const n = Number(copies[1]);
+        return n === 0 ? 'DEL' : n === 1 ? 'CNV' : 'DUP';
+    }
+    return /^STR\d*$/.test(first) ? 'TR' : (CLASS_OF_TOKEN[first] ?? 'OTHER');
+}
+// an INFO token one allele states: its own entry of a Number=A field, or the
+// one entry a record-wide field has
+function alleleToken(info, key, alleleIndex) {
+    const value = info?.[key];
+    const list = Array.isArray(value) ? value : [value];
+    const token = list.length === 1 ? list[0] : list[alleleIndex];
+    return typeof token === 'string' ? token : '';
+}
+/**
+ * #api
+ * The structural-variant class one ALT allele states, `''` for one that is not
+ * structural. A symbolic allele's own id wins. Otherwise VCF 4.4's `EVENTTYPE`
+ * does; then a breakend is the class its `SVTYPE` declares where that says more
+ * than BND, and a sequence allele is an insertion or deletion by its length
+ * against REF, else its `SVTYPE`'s class.
+ */
+export function svClassOfAlt(alt, { ref, info, alleleIndex = 0, } = {}) {
+    if (ANY_OTHER_ALLELE.has(alt)) {
+        return '';
+    }
+    if (alt.startsWith('<') && alt.endsWith('>')) {
+        return svClassOfToken(alt.slice(1, -1));
+    }
+    const event = svClassOfToken(alleleToken(info, 'EVENTTYPE', alleleIndex));
+    if (event) {
+        return event;
+    }
+    const declared = svClassOfToken(alleleToken(info, 'SVTYPE', alleleIndex));
+    if (isBreakend(alt)) {
+        return declared && declared !== 'BND' && declared !== 'OTHER'
+            ? declared
+            : 'BND';
+    }
+    const diff = alt.length - (ref?.length ?? alt.length);
+    return diff >= SV_MIN_LENGTH
+        ? 'INS'
+        : diff <= -SV_MIN_LENGTH
+            ? 'DEL'
+            : declared;
+}
+/**
+ * #api
+ * The structural-variant class of a VCF record as a whole: the one class its
+ * alleles state, CNV where they are losses and gains of one segment, OTHER
+ * where they otherwise disagree, and `''` for a record with no structural
+ * allele.
+ */
+export function svClassOf(feature) {
+    const alts = feature.get('ALT');
+    const ref = feature.get('REF');
+    const info = feature.get('INFO');
+    if (!alts?.length) {
+        return svClassOfToken(alleleToken(info, 'SVTYPE', 0));
+    }
+    const classes = new Set();
+    for (const [alleleIndex, alt] of alts.entries()) {
+        const found = svClassOfAlt(alt, { ref, info, alleleIndex });
+        if (found) {
+            classes.add(found);
+        }
+    }
+    const [only, ...rest] = classes;
+    return rest.length === 0
+        ? (only ?? '')
+        : [...classes].every(c => c === 'DEL' || c === 'DUP' || c === 'CNV')
+            ? 'CNV'
+            : 'OTHER';
+}
+// Read the mate destination from a VCF translocation INFO record. CHR2/END
+// give the mate ref+position; STRANDS[0] is a two-char code (e.g. "+-") where
+// the first char is this side's strand and the second is the mate's. Returns
+// undefined when CHR2/END aren't both present.
+export function readTranslocationMate(info) {
+    const chr = info.CHR2?.[0];
+    const pos = info.END?.[0];
+    if (chr === undefined || pos === undefined) {
+        return undefined;
+    }
+    const [myDir, mateDir] = info.STRANDS?.[0]?.split('') ?? ['.', '.'];
+    // A STRANDS char names the strand the record is ON, and an end on `+` keeps
+    // the sequence to its LEFT — so the keeps-direction (`breakendKeepsDirections`,
+    // +1 = right) is its negation. Resolved here so the one consumer that draws
+    // these as ticks does not have to know that, which is how the two conventions
+    // came to sit a negation apart in the first place.
+    const sign = (s) => (s === '+' ? -1 : s === '-' ? 1 : 0);
+    return {
+        chr,
+        pos,
+        myDir: myDir ?? '.',
+        mateDir: mateDir ?? '.',
+        myKeepsDir: sign(myDir ?? '.'),
+        mateKeepsDir: sign(mateDir ?? '.'),
+    };
+}
+// A BEDPE strand names the side of the block the junction is on: `+` its end,
+// so the block keeps the sequence to its left.
+function keepsOf(mateDirection, strand) {
+    if (typeof mateDirection === 'number') {
+        return mateDirection;
+    }
+    return strand === 1 ? -1 : strand === -1 ? 1 : 0;
+}
+function joinBase(self, other) {
+    const keeps = self.keeps || (self.start + self.end <= other.start + other.end ? -1 : 1);
+    return keeps === -1 ? self.end - 1 : self.start;
+}
+function symbolicKeeps(feature, alt) {
+    if (alt.startsWith('<DEL')) {
+        return [-1, 1];
+    }
+    if (alt.startsWith('<DUP')) {
+        return [1, -1];
+    }
+    const tra = readTranslocationMate(feature.get('INFO') ?? {});
+    return [tra?.myKeepsDir ?? 0, tra?.mateKeepsDir ?? 0];
+}
+/**
+ * #api
+ * Where a paired record's junction is at each of its two ends, and which side
+ * of it each end keeps — the one answer every launcher, the row menu and the
+ * chain walk take, whether the record is a VCF breakend, a symbolic SV or a
+ * paired adapter's row (BEDPE, STAR-Fusion). Refnames are as the record spells
+ * them. `undefined` for a record naming no other end. A VCF record is read
+ * through `alt`, its first ALT unless the caller names another.
+ *
+ * A VCF end is its own position. A paired adapter's end is a block, and the
+ * junction is the block's edge on the side the end keeps: stated by
+ * `mateDirection` where the adapter knows it, read off the strands where the
+ * record states one for each end as BEDPE does, and with neither the two
+ * blocks face each other. A PAF row's strand is the query's orientation and
+ * states none for the target, so it names no side.
+ */
+export function junctionEnds(feature, alt = feature.get('ALT')?.[0], alleleIndex) {
+    const refName = feature.get('refName');
+    const mate = feature.get('mate');
+    if (mate?.refName !== undefined && mate.start !== undefined) {
+        const sided = mate.strand !== undefined;
+        const self = {
+            start: feature.get('start'),
+            end: feature.get('end'),
+            keeps: keepsOf(feature.get('mateDirection'), sided ? feature.get('strand') : undefined),
+        };
+        const far = {
+            start: mate.start,
+            end: mate.end ?? mate.start + 1,
+            keeps: keepsOf(mate.mateDirection, mate.strand),
+        };
+        return {
+            own: { refName, pos: joinBase(self, far), keeps: self.keeps },
+            mate: {
+                refName: mate.refName,
+                pos: joinBase(far, self),
+                keeps: far.keeps,
+            },
+        };
+    }
+    const parsed = parseSvAlt(feature, alt, alleleIndex);
+    if (!parsed || alt === undefined) {
+        return undefined;
+    }
+    const [ownKeeps, mateKeeps] = parsed.joinDirection === undefined
+        ? symbolicKeeps(feature, alt)
+        : [parsed.joinDirection, parsed.mateDirection ?? 0];
+    return {
+        own: { refName, pos: feature.get('start'), keeps: ownKeeps },
+        mate: {
+            refName: parsed.mateRefName,
+            pos: parsed.matePos - 1,
+            keeps: mateKeeps,
+        },
+    };
+}

package/esm/util/svgColorProps.d.ts

@@ -5,3 +5,14 @@ export declare function getStrokeProps(str: string): {
 export declare function getFillProps(str: string): {
     [x: string]: string | number;
 };
+/**
+ * A paint value split into the `rgb()` an SVG 1.1 `<color>` can carry and the
+ * alpha it cannot, for a separate `*-opacity`. Illustrator and older Inkscape
+ * drop an element whose fill they cannot parse, so `rgba()`, `hsl()`, `#rgba`
+ * and `transparent` have to be split before they reach a file. Undefined for a
+ * value that is already an SVG color, `none` or a `url()`.
+ */
+export declare function splitPaintAlpha(value: string): {
+    color: string;
+    opacity: number;
+} | undefined;

package/esm/util/svgColorProps.js

@@ -1,4 +1,4 @@
-import { formatHEX, getAlpha, newColor, parseCssColorOr } from './colorBits.js';
+import { formatHEX, getAlpha, getBlue, getGreen, getRed, newColor, parseCssColorOr, } from './colorBits.js';
 // Matches colord()'s fallback for unparsable input.
 const FALLBACK = newColor(0, 0, 0, 255);
 // Works on the packed Color directly rather than via colord(): these run per
@@ -26,3 +26,30 @@ export function getStrokeProps(str) {
 export function getFillProps(str) {
     return svgColorProps(str, 'fill', 'fillOpacity');
 }
+// four channels, comma- or slash-separated, so a three-channel `rgb(4,5,6)`
+// never reads its blue as an alpha
+const FUNCTIONAL_ALPHA = /^(?:rgb|hsl)a?\((?:[^,/)]+,){3}\s*([\d.]+)(%?)\s*\)$|^(?:rgb|hsl)a?\([^,/)]+\/\s*([\d.]+)(%?)\s*\)$/i;
+const HEX_ALPHA = /^#(?:[\da-f]{4}|[\da-f]{8})$/i;
+const NOT_SVG_COLOR = /^(?:rgba|hsla?)\(|^transparent$/i;
+/**
+ * A paint value split into the `rgb()` an SVG 1.1 `<color>` can carry and the
+ * alpha it cannot, for a separate `*-opacity`. Illustrator and older Inkscape
+ * drop an element whose fill they cannot parse, so `rgba()`, `hsl()`, `#rgba`
+ * and `transparent` have to be split before they reach a file. Undefined for a
+ * value that is already an SVG color, `none` or a `url()`.
+ */
+export function splitPaintAlpha(value) {
+    const m = FUNCTIONAL_ALPHA.exec(value);
+    if (!m && !HEX_ALPHA.test(value) && !NOT_SVG_COLOR.test(value)) {
+        return undefined;
+    }
+    const c = parseCssColorOr(value, FALLBACK);
+    const digits = m?.[1] ?? m?.[3];
+    const percent = (m?.[2] ?? m?.[4]) === '%';
+    return {
+        color: `rgb(${getRed(c)},${getGreen(c)},${getBlue(c)})`,
+        opacity: digits === undefined
+            ? getAlpha(c) / 255
+            : Math.min(1, Number(digits) / (percent ? 100 : 1)),
+    };
+}

package/esm/util/systemColorScheme.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether the OS asks for a dark UI. False wherever `matchMedia` is missing — a
+ * worker, jsdom, node — which is the light theme JBrowse has always started in.
+ */
+export declare function prefersDarkColorScheme(): boolean;
+/**
+ * Call `listener` whenever the OS preference flips, and return the unsubscribe.
+ * Both halves live here rather than beside either caller because the session's
+ * `system` theme and the embedding hook `useSessionPalette` are two readers of
+ * one preference, and a second spelling of the query is a second answer.
+ */
+export declare function onColorSchemeChange(listener: () => void): () => void;

package/esm/util/systemColorScheme.js

@@ -0,0 +1,27 @@
+const DARK_SCHEME = '(prefers-color-scheme: dark)';
+function darkSchemeQuery() {
+    return typeof window !== 'undefined' &&
+        typeof window.matchMedia === 'function'
+        ? window.matchMedia(DARK_SCHEME)
+        : undefined;
+}
+/**
+ * Whether the OS asks for a dark UI. False wherever `matchMedia` is missing — a
+ * worker, jsdom, node — which is the light theme JBrowse has always started in.
+ */
+export function prefersDarkColorScheme() {
+    return darkSchemeQuery()?.matches ?? false;
+}
+/**
+ * Call `listener` whenever the OS preference flips, and return the unsubscribe.
+ * Both halves live here rather than beside either caller because the session's
+ * `system` theme and the embedding hook `useSessionPalette` are two readers of
+ * one preference, and a second spelling of the query is a second answer.
+ */
+export function onColorSchemeChange(listener) {
+    const media = darkSchemeQuery();
+    media?.addEventListener('change', listener);
+    return () => {
+        media?.removeEventListener('change', listener);
+    };
+}

package/esm/util/tabix.d.ts

@@ -1,5 +1,4 @@
 import type { StatusCallback } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 /**
  * A raw tabix line paired with the metadata the GFF3/GTF adapters need before
  * parsing: `offset` (the tabix byte offset) mints a stable per-feature id that
@@ -34,20 +33,26 @@ interface TabixLineSource {
  * label, capturing each line's byte offset, indexed start/end, and feature type
  * into a {@link TabixLine}. Shared by the GFF3 and GTF tabix adapters.
  *
- * The stop token becomes the read's `AbortSignal`, so a cancelled fetch drops
+ * The signal becomes the read's `AbortSignal`, so a cancelled fetch drops
  * its block reads at the socket instead of downloading them and discarding the
  * lines. @gmod/tabix aborts a block shared between callers only once every
  * joined caller has aborted (`AggregateAbortController`), so this can't cancel a
  * chunk another region still needs.
  */
-export declare function readTabixLines(gff: TabixLineSource, refName: string, start: number, end: number, statusCallback?: StatusCallback, stopToken?: StopToken): Promise<TabixLine[]>;
+export declare function readTabixLines(gff: TabixLineSource, refName: string, start: number, end: number, statusCallback?: StatusCallback, signal?: AbortSignal): Promise<TabixLine[]>;
 /**
  * Read a region's tabix lines, then — if any feature found there extends past
  * the query — read the overhang on either side, so a parent line's children (a
  * gene's exons, a transcript's CDS) outside the original window are pulled in
- * and the parent/child tree resolves fully. Types in `dontRedispatchSet` are
- * excluded from the bounds, so one chromosome-spanning record can't force a
- * whole-chromosome refetch.
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
  *
  * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
  * everything the first read already had — a second full read of the query range
@@ -76,9 +81,9 @@ export declare function readTabixLinesRedispatched(file: TabixLineSource, query:
     refName: string;
     start: number;
     end: number;
-}, dontRedispatchSet: Set<string>, opts?: {
+}, expands: (line: TabixLine) => boolean, opts?: {
     statusCallback?: StatusCallback;
-    stopToken?: StopToken;
+    signal?: AbortSignal;
 }): Promise<TabixLine[]>;
 /**
  * Minimal structural view of the `@gmod/tabix` call a header read needs, kept

package/esm/util/tabix.js

@@ -1,6 +1,5 @@
 import { createStatusFanOut, downloadStatus } from './progress.js';
 import { calculateRedispatchRange } from './range.js';
-import { withStopTokenSignal } from './stopToken.js';
 /**
  * Read the feature type (column 3) from a raw GFF3/GTF line without a full
  * split. Used only to classify a line for redispatch.
@@ -18,15 +17,15 @@ function extractType(line) {
  * label, capturing each line's byte offset, indexed start/end, and feature type
  * into a {@link TabixLine}. Shared by the GFF3 and GTF tabix adapters.
  *
- * The stop token becomes the read's `AbortSignal`, so a cancelled fetch drops
+ * The signal becomes the read's `AbortSignal`, so a cancelled fetch drops
  * its block reads at the socket instead of downloading them and discarding the
  * lines. @gmod/tabix aborts a block shared between callers only once every
  * joined caller has aborted (`AggregateAbortController`), so this can't cancel a
  * chunk another region still needs.
  */
-export function readTabixLines(gff, refName, start, end, statusCallback, stopToken) {
+export function readTabixLines(gff, refName, start, end, statusCallback, signal) {
     const lines = [];
-    return withStopTokenSignal(stopToken, signal => downloadStatus('Downloading features', statusCallback, onProgress => gff.getLines(refName, start, end, {
+    return downloadStatus('Downloading features', statusCallback, onProgress => gff.getLines(refName, start, end, {
         lineCallback: (line, offset, s, e) => {
             lines.push({
                 line,
@@ -38,15 +37,21 @@ export function readTabixLines(gff, refName, start, end, statusCallback, stopTok
         },
         onProgress,
         signal,
-    }))).then(() => lines);
+    })).then(() => lines);
 }
 /**
  * Read a region's tabix lines, then — if any feature found there extends past
  * the query — read the overhang on either side, so a parent line's children (a
  * gene's exons, a transcript's CDS) outside the original window are pulled in
- * and the parent/child tree resolves fully. Types in `dontRedispatchSet` are
- * excluded from the bounds, so one chromosome-spanning record can't force a
- * whole-chromosome refetch.
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
  *
  * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
  * everything the first read already had — a second full read of the query range
@@ -74,13 +79,13 @@ export function readTabixLines(gff, refName, start, end, statusCallback, stopTok
 export async function readTabixLinesRedispatched(file, 
 // the region's locus only — kept structural, like TabixLineSource above, so
 // this module stays free of the `types` barrel and its MST models
-query, dontRedispatchSet, opts = {}) {
-    const { statusCallback, stopToken } = opts;
+query, expands, opts = {}) {
+    const { statusCallback, signal } = opts;
     // `cb` is not optional: each read decides where it reports, and the flanks
     // report somewhere the first read does not
-    const read = (start, end, cb) => readTabixLines(file, query.refName, start, end, cb, stopToken);
+    const read = (start, end, cb) => readTabixLines(file, query.refName, start, end, cb, signal);
     const lines = await read(query.start, query.end, statusCallback);
-    const redispatch = calculateRedispatchRange(lines, dontRedispatchSet, query.start, query.end);
+    const redispatch = calculateRedispatchRange(lines, expands, query.start, query.end);
     if (redispatch) {
         const slot = createStatusFanOut(statusCallback);
         const flanks = await Promise.all([

package/esm/util/thresholdScale.d.ts

@@ -0,0 +1,91 @@
+import type { CategoricalScale } from '../ui/colorScale.ts';
+import type { CategoricalField } from './categoricalField.ts';
+/**
+ * #api
+ * A domain written as strings — the shared `domain` slot is a `stringArray` —
+ * read back as the numbers it names. A member that is not a number reads NaN,
+ * which every comparison against it declines.
+ */
+export declare function numericDomain(domain: readonly (string | number)[]): number[];
+/**
+ * #api
+ * A threshold scale's cut points as {@link thresholdIndex} walks them: the
+ * numbers the domain names, ascending. Cuts written high to low, as p-value
+ * thresholds often are, left the middle interval unreachable, the walk stopping
+ * at the first cut a value is under.
+ */
+export declare function thresholdCuts(domain: readonly (string | number)[]): number[];
+/**
+ * #api
+ * The bin a value falls in: how many of the ascending cut points it is at or
+ * past, so a palette with one more entry than the domain paints it as
+ * `palette[thresholdIndex(value, domain)]`. A value that is not a number is
+ * in no bin and answers -1; an infinite one takes the end bin on its side, as
+ * d3's threshold scale places it, so a `-log10` of a zero p-value lands in
+ * the top bin.
+ */
+export declare function thresholdIndex(value: unknown, domain: readonly number[]): number;
+/**
+ * #api
+ * The colour of each interval, in order: the declared palette, and the
+ * default categorical palette where it runs out.
+ */
+export declare function thresholdPalette(bins: number, palette?: readonly string[]): string[];
+/**
+ * #api
+ * What a threshold scale's bins are called in a key, one label per palette
+ * entry: `< a` below the first cut, `a – b` between two, `≥ b` past the last.
+ */
+export declare function thresholdLabels(domain: readonly number[]): string[];
+/**
+ * #api
+ * The key a value holding text that is no number files under on a threshold
+ * scale, painted the misconfiguration grey rather than passing for a missing
+ * value.
+ */
+export declare const NOT_A_NUMBER_LABEL = "(not a number)";
+/**
+ * #api
+ * A threshold key's rows: every interval, painted or not, since the bins are
+ * the whole domain, then the not-a-number and no-value rows where a feature
+ * took one, in the order `thresholdField` sorts them.
+ */
+export declare function thresholdKeyEntries(cuts: readonly number[], range: readonly string[] | undefined, met: {
+    missing?: boolean;
+    notNumber?: boolean;
+}, names?: readonly string[]): {
+    value: string;
+    label: string;
+    color: string;
+    missing?: true;
+}[];
+/**
+ * #api
+ * The rows a ramp's key lists beside its bar once a feature painted one: the
+ * not-a-number and no-value rows a threshold's key ends with. Empty while
+ * neither painted.
+ */
+export declare function rampGapScales(id: string, met: {
+    missing?: boolean;
+    notNumber?: boolean;
+}): CategoricalScale[];
+/**
+ * #api
+ * Whether a field holds no value at all, as against text that fails to parse:
+ * absent, empty, or a VCF's `AF=.`, which arrives as `[undefined]`.
+ */
+export declare function isMissing(value: unknown): boolean;
+/**
+ * #api
+ * A threshold scale read the way every categorical channel reads its field: a
+ * value files under the label of the bin it falls in, a feature with no value
+ * under `''`, and text that is no number under {@link NOT_A_NUMBER_LABEL}.
+ * The bins are the whole domain, so a key lists each one. `labels` names the
+ * bins in a key, one each from the lowest, where a config spells them for a
+ * reader; a bin's key stays its interval.
+ */
+export declare function thresholdField(field: string, { domain, range, labels: names, }?: {
+    domain?: readonly string[];
+    range?: readonly string[];
+    labels?: readonly string[];
+}): CategoricalField;