@jbrowse/core 4.3.0 → 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

@@ -0,0 +1,18 @@
+export declare function stripAlpha(str: string): string;
+export declare function getStrokeProps(str: string): {
+    [x: string]: string | number;
+};
+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

@@ -0,0 +1,55 @@
+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
+// path per render on overlay tracks, and each colord() allocates an object
+// carrying nine closures — two of them, since .alpha(1) builds another. formatHEX
+// ignores the alpha byte, so stripping alpha before formatting was a no-op.
+export function stripAlpha(str) {
+    return formatHEX(parseCssColorOr(str, FALLBACK));
+}
+function svgColorProps(str, colorKey, opacityKey) {
+    if (str) {
+        const c = parseCssColorOr(str, FALLBACK);
+        return {
+            [opacityKey]: getAlpha(c) / 255,
+            [colorKey]: formatHEX(c),
+        };
+    }
+    else {
+        return {};
+    }
+}
+export function getStrokeProps(str) {
+    return svgColorProps(str, 'stroke', 'strokeOpacity');
+}
+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

@@ -0,0 +1,125 @@
+import type { StatusCallback } from './progress.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
+ * survives redispatch and panning, and start/end/type feed the redispatch
+ * calculation (see {@link calculateRedispatchRange}) that runs before any line
+ * is parsed.
+ *
+ * `start`/`end` are interbase, not the raw column values: @gmod/tabix applies
+ * the index's coordinate offset (-1 for a 1-based-closed preset such as GFF)
+ * before it calls back.
+ */
+export interface TabixLine {
+    line: string;
+    offset: number;
+    start: number;
+    end: number;
+    type: string;
+}
+/**
+ * Minimal structural view of `@gmod/tabix`'s `TabixIndexedFile.getLines`, so
+ * core needn't depend on `@gmod/tabix`.
+ */
+interface TabixLineSource {
+    getLines(refName: string, start: number | undefined, end: number | undefined, opts: {
+        lineCallback: (line: string, offset: number, start: number, end: number) => void;
+        onProgress?: (bytesDownloaded: number, totalBytes?: number) => void;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/**
+ * Fetch the tabix lines for a region under a "Downloading features" progress
+ * 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 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, 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. `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
+ * to collect a gene's tail. At the window sizes a GFF3 track is browsed at that
+ * is most of the work done twice, and it is the reason the download bar halved:
+ * the expansion arrived as a second phase whose total was the whole region
+ * again, so a region that had just reported 100% dropped to 50% and climbed back
+ * (measured: two `65536/65536` phases for one query). Reading only what is
+ * missing leaves the second phase the size of the overhang.
+ *
+ * The line sequence is unchanged by that. Tabix returns the lines *overlapping*
+ * a range, so the three ranges' lines are the union range's lines, with the ones
+ * straddling a boundary appearing twice; `offset` is a line's position in the
+ * file, so deduplicating and sorting on it reconstructs file order — which for
+ * an indexed file is coordinate order — exactly.
+ *
+ * The two flanks are read concurrently and so need a status slot each, or they
+ * take turns overwriting one label. Exactly one expansion happens: a flank's own
+ * overhang is not chased, which bounds the work at three reads per query and
+ * usually two.
+ *
+ * Shared by the GFF3 and GTF tabix adapters, which differ only in how they
+ * parse the returned lines.
+ */
+export declare function readTabixLinesRedispatched(file: TabixLineSource, query: {
+    refName: string;
+    start: number;
+    end: number;
+}, expands: (line: TabixLine) => boolean, opts?: {
+    statusCallback?: StatusCallback;
+    signal?: AbortSignal;
+}): Promise<TabixLine[]>;
+/**
+ * Minimal structural view of the `@gmod/tabix` call a header read needs, kept
+ * structural for the same reason as {@link TabixLineSource}.
+ */
+interface TabixHeaderSource {
+    getHeaderLines(): Promise<string[]>;
+}
+/**
+ * The header lines of a tabix-indexed file, however that file kept them.
+ *
+ * `getHeader()` alone is not that: it returns only lines beginning with the
+ * index's meta character (`#`). A header that is a plain row — which is what
+ * `tabix -S N` exists for, and what PLINK `.ld`, bedGraph and BED deflines
+ * routinely are — comes back as the empty string, even though the index records
+ * N in `skipLines`.
+ *
+ * Reading both is not backwards compatibility, and does not become unnecessary
+ * once our own files are written with commented headers. A bare header is the
+ * shape the data's publisher chose: Pan-UKB's TSVs and PLINK's `.ld` are
+ * distributed that way, and `-S N` is the only way to index one without
+ * rewriting a file the user did not write. Advice about how to generate a file
+ * reaches the files we generate; this reaches the rest.
+ *
+ * An adapter that stops at `getHeader()` therefore cannot tell "this file has
+ * no header" from "this file's header is not commented", and quietly falls back
+ * to an assumed column layout. That has cost real information more than once: a
+ * PLINK LD file lost its D' column, so `ldMetric: 'dprime'` silently served r²,
+ * and a bedGraph loses the names of its value columns. Nothing errors, because
+ * the assumed layout parses.
+ *
+ * That policy now lives in @gmod/tabix 3.5.4 as getHeaderLines, next to the
+ * index metadata that decides it, so this is a delegate. Deciding it there also
+ * costs one read of the file's leading blocks rather than two: asking for the
+ * commented block and then the counted rows used to fetch and decompress the
+ * same bytes twice, which every bare-header file did on every call.
+ */
+export declare function readTabixHeaderLines(file: TabixHeaderSource): Promise<string[]>;
+export {};