@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/blockTypes.js

@@ -1,32 +1,77 @@
+/**
+ * A content block as a region that addresses whole bases.
+ *
+ * `calculateDynamicBlocks` says in its own docstring that start/end may be
+ * FRACTIONAL — a block is a span of screen, and the view is only at a whole
+ * base when the pan and the zoom both happen to land there. Anything naming
+ * bases rather than pixels needs this: a sequence fetch, a bookmark, and above
+ * all a locString, since `BP_QUANTITY_SOURCE` rejects a bare fractional
+ * coordinate on purpose ("a bare '1.5' as a coordinate is a mistake").
+ *
+ * `reversed` is dropped with the pixels. It orients a projection, and a region
+ * that has left the screen is not being projected; carrying it only reached
+ * `assembleLocString`, which spells it `[rev]` in a field the user is about to
+ * read.
+ */
+export function wholeBaseRegion(block) {
+    return {
+        assemblyName: block.assemblyName,
+        refName: block.refName,
+        start: Math.floor(block.start),
+        end: Math.ceil(block.end),
+    };
+}
+export function wholeBaseRegions(blocks) {
+    return blocks.map(wholeBaseRegion);
+}
+// A merged elided run can span several displayed regions, so its per-region
+// identity is meaningless: refName/start/end are cleared and only widthPx stays
+// valid. The leftover key, assemblyName, displayedRegionIndex,
+// isRightEndOfDisplayedRegion belong to the FIRST sub-block — don't key off them
+// for an ElidedBlock.
+function mergeElided(run, widthPx) {
+    run.refName = '';
+    run.start = 0;
+    run.end = 0;
+    run.widthPx += widthPx;
+}
 export class BlockSet {
     blocks;
     constructor(blocks = []) {
         this.blocks = blocks;
     }
-    *[Symbol.iterator]() {
-        yield* this.blocks;
-    }
     push(block) {
-        if (block.type === 'ElidedBlock' && this.blocks.length > 0) {
-            const lastBlock = this.blocks.at(-1);
-            if (lastBlock?.type === 'ElidedBlock') {
-                ;
-                lastBlock.push(block);
-                return;
-            }
+        const last = this.blocks.at(-1);
+        if (block.type === 'ElidedBlock' && last?.type === 'ElidedBlock') {
+            mergeElided(last, block.widthPx);
+        }
+        else {
+            this.blocks.push(block);
         }
-        this.blocks.push(block);
-    }
-    getBlocks() {
-        return this.blocks;
     }
-    getRegions() {
-        return this.blocks.map(block => block.toRegion());
+    /**
+     * Widen a trailing elided run by widthPx, reporting whether there was one to
+     * widen. `push` keeps nothing but the width off an ElidedBlock it merges, so
+     * a caller holding the width can skip building the block that would have
+     * carried it — which at whole-genome zoom is nearly every region, see
+     * calculateDynamicBlocks.
+     */
+    growElidedRun(widthPx) {
+        const last = this.blocks.at(-1);
+        if (last?.type !== 'ElidedBlock') {
+            return false;
+        }
+        mergeElided(last, widthPx);
+        return true;
     }
     map(func, thisarg) {
+        // deliberately mirrors Array#map's (callback, thisArg) signature
+        // eslint-disable-next-line unicorn/no-array-method-this-argument
         return this.blocks.map(func, thisarg);
     }
     forEach(func, thisarg) {
+        // deliberately mirrors Array#forEach's (callback, thisArg) signature
+        // eslint-disable-next-line unicorn/no-array-method-this-argument
         this.blocks.forEach(func, thisarg);
     }
     get length() {
@@ -52,68 +97,16 @@ export class BlockSet {
         return this.blocks.length > 0 ? this.blocks[0].offsetPx : 0;
     }
     get contentBlocks() {
-        return this.blocks.filter(block => block.type === 'ContentBlock');
+        return this.blocks.filter((block) => block.type === 'ContentBlock');
     }
     get totalBp() {
         let total = 0;
-        for (let i = 0, l = this.contentBlocks.length; i < l; i++) {
-            const b = this.contentBlocks[i];
-            total += b.end - b.start;
+        for (let i = 0, l = this.blocks.length; i < l; i++) {
+            const b = this.blocks[i];
+            if (b.type === 'ContentBlock') {
+                total += b.end - b.start;
+            }
         }
         return total;
     }
 }
-export class BaseBlock {
-    type = 'BaseBlock';
-    regionNumber;
-    reversed;
-    refName;
-    start;
-    end;
-    assemblyName;
-    key;
-    offsetPx;
-    widthPx = 0;
-    variant;
-    isLeftEndOfDisplayedRegion;
-    constructor(data) {
-        Object.assign(this, data);
-        this.assemblyName = data.assemblyName;
-        this.refName = data.refName;
-        this.start = data.start;
-        this.end = data.end;
-        this.key = data.key;
-        this.offsetPx = data.offsetPx;
-    }
-    toRegion() {
-        return {
-            refName: this.refName,
-            start: this.start,
-            end: this.end,
-            assemblyName: this.assemblyName,
-            reversed: this.reversed,
-        };
-    }
-}
-export class ContentBlock extends BaseBlock {
-    type = 'ContentBlock';
-}
-export class ElidedBlock extends BaseBlock {
-    type = 'ElidedBlock';
-    widthPx;
-    elidedBlockCount = 0;
-    constructor(data) {
-        super(data);
-        this.widthPx = data.widthPx;
-    }
-    push(otherBlock) {
-        this.elidedBlockCount += 1;
-        this.refName = '';
-        this.start = 0;
-        this.end = 0;
-        this.widthPx += otherBlock.widthPx;
-    }
-}
-export class InterRegionPaddingBlock extends BaseBlock {
-    type = 'InterRegionPaddingBlock';
-}

package/esm/util/bpUtils.d.ts

@@ -0,0 +1,81 @@
+import type { Region } from './types/data.ts';
+export interface MinimalRegion {
+    start: number;
+    end: number;
+    reversed?: boolean;
+}
+export declare function bpToPx(bp: number, { reversed, end, start, }: {
+    start?: number;
+    end?: number;
+    reversed?: boolean;
+}, bpPerPx: number): number;
+export declare function bpSpanPx(leftBp: number, rightBp: number, region: MinimalRegion, bpPerPx: number): readonly [number, number];
+export declare function featureSpanPx(feature: {
+    get: (key: string) => number;
+}, region: MinimalRegion, bpPerPx: number): readonly [number, number];
+export declare function getBpDisplayStr(total: number): string;
+/**
+ * The grammar of a single base-pair quantity, as a regex source fragment so
+ * that callers matching it in a larger pattern (a locString coordinate range,
+ * say) stay in step with {@link parseBpString}. Match case-insensitively.
+ *
+ * A decimal point is allowed only on the unit-suffixed alternative. That is
+ * deliberate: "1.5Mb" is a number a user means, whereas a bare "1.5" as a
+ * coordinate is a mistake, and it should stay an error rather than silently
+ * yielding a fractional coordinate.
+ */
+export declare const BP_QUANTITY_SOURCE: string;
+/**
+ * Parse a base-pair count written the way people type one: plain digits, with
+ * optional thousand separators, and with an optional metric unit suffix. So
+ * "150", "1,500", "1.5kb", "1.5k", "34Mb" and "2G" are all accepted.
+ *
+ * The unit's tail is loose because both "kb" and "k" are in common use, and
+ * because everything {@link getBpDisplayStr} prints has to come back in. The
+ * app shows a window size as "1.5Mbp" in the zoom slider tooltip and over a
+ * rubberband selection, so a user who reads one off the screen and types it
+ * into a bp field has typed a string this must accept.
+ *
+ * Returns undefined, rather than NaN or a throw, when the string is not a bp
+ * quantity, so that callers validating a text field can test it directly.
+ */
+export declare function parseBpString(str: string): number | undefined;
+export declare function getTickDisplayStr(totalBp: number, bpPerPx: number): string;
+interface VirtualOffset {
+    blockPosition: number;
+    dataPosition?: number;
+}
+interface Block {
+    minv: VirtualOffset;
+    maxv: VirtualOffset;
+    /**
+     * Bytes this block's fetch actually reads. @gmod/tabix and @gmod/bam compute
+     * it from an `endPosition` that `clampChunkEnds` has tightened down to the
+     * next known BGZF block boundary, so it is materially smaller than the
+     * full-block padding the fallback below has to assume.
+     */
+    fetchedSize?: () => number;
+}
+/**
+ * Index-only estimate of the bytes a fetch of these regions would download.
+ *
+ * Prefers each block's own `fetchedSize()`. The fallback —
+ * `maxv + 65535 - minv` — has to pad by a whole maximum-size BGZF block,
+ * because the compressed length of the block at `maxv` is not recorded in the
+ * index; it is what this did for every block before the parsers exposed a
+ * tightened figure, and it over-estimates.
+ *
+ * Blocks are also de-duplicated across regions. Two adjacent regions routinely
+ * resolve to the same chunk, and it is downloaded once, so counting it twice
+ * inflated the estimate for exactly the multi-region queries this gates.
+ *
+ * Note @gmod/tabix's own `TabixIndexedFile.bytesForRegions` is strictly better
+ * still — it runs the chunk merger over the combined set, so it also collapses
+ * *overlapping* blocks rather than only identical ones — and every tabix
+ * adapter in this repo calls that instead. This remains for other index shapes
+ * and for plugins outside the repo, which reach it through `@jbrowse/core/util`.
+ */
+export declare function bytesForRegions(regions: Region[], index: {
+    blocksForRange: (ref: string, start: number, end: number) => Promise<Block[]>;
+}): Promise<number>;
+export {};

package/esm/util/bpUtils.js

@@ -0,0 +1,103 @@
+import { reducePrecision, sum, toLocale, toPrecision } from './numericUtils.js';
+function roundToNearestPointOne(num) {
+    return Math.round(num * 10) / 10;
+}
+export function bpToPx(bp, { reversed, end = 0, start = 0, }, bpPerPx) {
+    return roundToNearestPointOne((reversed ? end - bp : bp - start) / bpPerPx);
+}
+export function bpSpanPx(leftBp, rightBp, region, bpPerPx) {
+    const start = bpToPx(leftBp, region, bpPerPx);
+    const end = bpToPx(rightBp, region, bpPerPx);
+    return region.reversed ? [end, start] : [start, end];
+}
+export function featureSpanPx(feature, region, bpPerPx) {
+    return bpSpanPx(feature.get('start'), feature.get('end'), region, bpPerPx);
+}
+export function getBpDisplayStr(total) {
+    // the unit comes from the rounded value, not the raw one: 3-significant-digit
+    // rounding of 999,500bp reaches 1000, which reads as "1Mbp" not "1,000Kbp"
+    const mb = toPrecision(total / 1_000_000);
+    return mb >= 1
+        ? `${toLocale(mb)}Mbp`
+        : total >= 1000
+            ? `${reducePrecision(total / 1_000)}Kbp`
+            : `${Math.floor(total)}bp`;
+}
+const BP_UNITS = {
+    k: 1_000,
+    m: 1_000_000,
+    g: 1_000_000_000,
+};
+/**
+ * The grammar of a single base-pair quantity, as a regex source fragment so
+ * that callers matching it in a larger pattern (a locString coordinate range,
+ * say) stay in step with {@link parseBpString}. Match case-insensitively.
+ *
+ * A decimal point is allowed only on the unit-suffixed alternative. That is
+ * deliberate: "1.5Mb" is a number a user means, whereas a bare "1.5" as a
+ * coordinate is a mistake, and it should stay an error rather than silently
+ * yielding a fractional coordinate.
+ */
+export const BP_QUANTITY_SOURCE = String.raw `(?:-?\d+(?:\.\d+)?[kmg](?:bp?)?|-?\d+(?:bp)?)`;
+const BP_QUANTITY_REGEX = new RegExp(String.raw `^(?:(-?\d+(?:\.\d+)?)([kmg])(?:bp?)?|(-?\d+)(?:bp)?)$`, 'i');
+/**
+ * Parse a base-pair count written the way people type one: plain digits, with
+ * optional thousand separators, and with an optional metric unit suffix. So
+ * "150", "1,500", "1.5kb", "1.5k", "34Mb" and "2G" are all accepted.
+ *
+ * The unit's tail is loose because both "kb" and "k" are in common use, and
+ * because everything {@link getBpDisplayStr} prints has to come back in. The
+ * app shows a window size as "1.5Mbp" in the zoom slider tooltip and over a
+ * rubberband selection, so a user who reads one off the screen and types it
+ * into a bp field has typed a string this must accept.
+ *
+ * Returns undefined, rather than NaN or a throw, when the string is not a bp
+ * quantity, so that callers validating a text field can test it directly.
+ */
+export function parseBpString(str) {
+    const match = BP_QUANTITY_REGEX.exec(str.replaceAll(',', ''));
+    if (!match) {
+        return undefined;
+    }
+    const [, scaled, unit, plain] = match;
+    return plain === undefined
+        ? // rounded because the scaled value can land off an integer ("1.0000001M"),
+            // and a coordinate is a whole number of bases
+            Math.round(+scaled * BP_UNITS[unit.toLowerCase()])
+        : +plain;
+}
+export function getTickDisplayStr(totalBp, bpPerPx) {
+    return Math.floor(bpPerPx / 1_000) > 0
+        ? `${toLocale(Number.parseFloat((totalBp / 1_000_000).toFixed(2)))}M`
+        : toLocale(Math.floor(totalBp));
+}
+/**
+ * Index-only estimate of the bytes a fetch of these regions would download.
+ *
+ * Prefers each block's own `fetchedSize()`. The fallback —
+ * `maxv + 65535 - minv` — has to pad by a whole maximum-size BGZF block,
+ * because the compressed length of the block at `maxv` is not recorded in the
+ * index; it is what this did for every block before the parsers exposed a
+ * tightened figure, and it over-estimates.
+ *
+ * Blocks are also de-duplicated across regions. Two adjacent regions routinely
+ * resolve to the same chunk, and it is downloaded once, so counting it twice
+ * inflated the estimate for exactly the multi-region queries this gates.
+ *
+ * Note @gmod/tabix's own `TabixIndexedFile.bytesForRegions` is strictly better
+ * still — it runs the chunk merger over the combined set, so it also collapses
+ * *overlapping* blocks rather than only identical ones — and every tabix
+ * adapter in this repo calls that instead. This remains for other index shapes
+ * and for plugins outside the repo, which reach it through `@jbrowse/core/util`.
+ */
+export async function bytesForRegions(regions, index) {
+    const blockResults = await Promise.all(regions.map(r => index.blocksForRange(r.refName, r.start, r.end)));
+    const seen = new Map();
+    for (const block of blockResults.flat()) {
+        const { minv, maxv } = block;
+        seen.set(`${minv.blockPosition}:${minv.dataPosition ?? 0}-${maxv.blockPosition}:${maxv.dataPosition ?? 0}`, block);
+    }
+    return sum([...seen.values()].map(block => block.fetchedSize
+        ? block.fetchedSize()
+        : block.maxv.blockPosition + 65535 - block.minv.blockPosition));
+}

package/esm/util/cacheBudgets.d.ts

@@ -0,0 +1,52 @@
+import { SharedBudget } from '@gmod/shared-read-cache';
+/**
+ * Ceilings on what the indexed-format libraries retain, shared by every adapter
+ * in this JS context — so one per RPC worker, plus one on the main thread,
+ * which is the scope that actually runs out of memory.
+ *
+ * ## Why these are not per file
+ *
+ * `@gmod/bam`, `@gmod/tabix` and `@gmod/cram` each take a per-file budget,
+ * sized so that a single track panning never falls off the cliff where a cache
+ * smaller than one query's working set stops caching entirely (`@gmod/bam` ADR
+ * 0014). But `dataAdapterCache` holds one adapter — and so one `BamFile`, one
+ * `TabixIndexedFile`, one `IndexedCramFile` — per open track for the life of
+ * that track, so a per-file ceiling is multiplied by the track count and
+ * nothing bounds the sum.
+ *
+ * Measured in `@gmod/bam` ADR 0018: three moderately deep alignments tracks
+ * browsing eight windows retained 1109 MB at 1665 MB RSS, still climbing, with
+ * **every cache well under its own 1 GB ceiling** — so the ceiling was not what
+ * held the line, and nothing else was either. Six tracks reached 1442 MB. The
+ * idle timeouts cannot help here by construction: they reclaim what has gone
+ * quiet, and nothing is quiet while the reader is browsing.
+ *
+ * Dividing each library's ceiling by the track count is the obvious fix and it
+ * is worse than doing nothing: at 128 MB per file — eight tracks under a
+ * gigabyte — the same workload cost 101 refills on the revisit against 98 for
+ * the cold pass. A shared budget has no such failure, because a member yields
+ * only what is globally least-recently-used: tracks the reader is not looking
+ * at hand their space to the one being panned, so the active track keeps a
+ * whole working set however many are open.
+ *
+ * ## The numbers are not new
+ *
+ * Both are the libraries' own per-file defaults, moved from per-file to
+ * per-context. That makes this a strict tightening — retention can only fall —
+ * and avoids inventing a number that would need its own justification. The
+ * budget still has to clear one query's working set or the cliff returns, and
+ * on that workload 512 MB shared across three tracks already cost 43 refills
+ * where 1 GB cost 4.
+ *
+ * ## Two budgets, because units cannot mix
+ *
+ * `SharedBudget.total` is a sum over its members, so they must all weigh in the
+ * same unit. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes;
+ * `@gmod/cram` weighs decoded records, because a decoded record has no cheap
+ * size. A single budget spanning them would add records to bytes and bound
+ * neither. `sizeOf` is opaque, so nothing can catch that at runtime — hence two
+ * budgets named for their units.
+ */
+export declare const decompressedBytesBudget: SharedBudget;
+/** See {@link decompressedBytesBudget}. Records, not bytes — CRAM only. */
+export declare const decodedRecordsBudget: SharedBudget;

package/esm/util/cacheBudgets.js

@@ -0,0 +1,52 @@
+import { SharedBudget } from '@gmod/shared-read-cache';
+/**
+ * Ceilings on what the indexed-format libraries retain, shared by every adapter
+ * in this JS context — so one per RPC worker, plus one on the main thread,
+ * which is the scope that actually runs out of memory.
+ *
+ * ## Why these are not per file
+ *
+ * `@gmod/bam`, `@gmod/tabix` and `@gmod/cram` each take a per-file budget,
+ * sized so that a single track panning never falls off the cliff where a cache
+ * smaller than one query's working set stops caching entirely (`@gmod/bam` ADR
+ * 0014). But `dataAdapterCache` holds one adapter — and so one `BamFile`, one
+ * `TabixIndexedFile`, one `IndexedCramFile` — per open track for the life of
+ * that track, so a per-file ceiling is multiplied by the track count and
+ * nothing bounds the sum.
+ *
+ * Measured in `@gmod/bam` ADR 0018: three moderately deep alignments tracks
+ * browsing eight windows retained 1109 MB at 1665 MB RSS, still climbing, with
+ * **every cache well under its own 1 GB ceiling** — so the ceiling was not what
+ * held the line, and nothing else was either. Six tracks reached 1442 MB. The
+ * idle timeouts cannot help here by construction: they reclaim what has gone
+ * quiet, and nothing is quiet while the reader is browsing.
+ *
+ * Dividing each library's ceiling by the track count is the obvious fix and it
+ * is worse than doing nothing: at 128 MB per file — eight tracks under a
+ * gigabyte — the same workload cost 101 refills on the revisit against 98 for
+ * the cold pass. A shared budget has no such failure, because a member yields
+ * only what is globally least-recently-used: tracks the reader is not looking
+ * at hand their space to the one being panned, so the active track keeps a
+ * whole working set however many are open.
+ *
+ * ## The numbers are not new
+ *
+ * Both are the libraries' own per-file defaults, moved from per-file to
+ * per-context. That makes this a strict tightening — retention can only fall —
+ * and avoids inventing a number that would need its own justification. The
+ * budget still has to clear one query's working set or the cliff returns, and
+ * on that workload 512 MB shared across three tracks already cost 43 refills
+ * where 1 GB cost 4.
+ *
+ * ## Two budgets, because units cannot mix
+ *
+ * `SharedBudget.total` is a sum over its members, so they must all weigh in the
+ * same unit. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes;
+ * `@gmod/cram` weighs decoded records, because a decoded record has no cheap
+ * size. A single budget spanning them would add records to bytes and bound
+ * neither. `sizeOf` is opaque, so nothing can catch that at runtime — hence two
+ * budgets named for their units.
+ */
+export const decompressedBytesBudget = new SharedBudget(1024 * 2 ** 20);
+/** See {@link decompressedBytesBudget}. Records, not bytes — CRAM only. */
+export const decodedRecordsBudget = new SharedBudget(1_000_000);

package/esm/util/cachedSetup.d.ts

@@ -0,0 +1,51 @@
+import type { BaseOptions } from '../data_adapters/BaseAdapter/types.ts';
+/** byte-granularity progress reporter to hand an index reader's `onProgress` */
+type OnProgress = (current: number, total?: number) => void;
+/**
+ * Memoize an adapter's one-time setup (open the file, read the header, build a
+ * parser, download and parse a whole file) into a loader every method can
+ * await.
+ *
+ * Four behaviors, each of which a hand-rolled `p ??= f().catch(...)` gets wrong
+ * in a way that is invisible until it isn't:
+ *
+ * - **A rejected setup clears the memo**, so the next call retries instead of
+ *   replaying the same rejection for the life of the adapter.
+ * - **Progress fans out to every live waiter.** The setup body reports to
+ *   whoever is *currently* awaiting it, not to whoever happened to start it. A
+ *   memo that captured the first caller's `statusCallback` went silent the
+ *   moment that fetch was superseded — the display's latest-wins guard gates the
+ *   old callback off — so the fetch replacing it awaited a multi-GB parse behind
+ *   a blank loading overlay.
+ * - **`stopToken` is withheld from the shared work.** Honoring one caller's
+ *   cancel would abort a parse the caller replacing it is already waiting on,
+ *   and reject them both. A superseded fetch just stops listening. Cancellation
+ *   stays with the per-call work (indexed range queries), which no one else is
+ *   waiting on.
+ * - **`label` is shown only while the *first* attempt is in flight.** Re-entry
+ *   on pan/zoom (every getFeatures and byte estimate awaits the loader) would
+ *   otherwise re-flash "Downloading index" over an index that is already
+ *   resident.
+ *
+ * Pass `label` when the setup is an index read that narrates nothing itself, so
+ * the label is the whole story. Omit it when the setup reports from the inside —
+ * a whole-file fetch driving its own download bar — since two labels for one
+ * download is worse than one, and phases nest (see `openPhase` in progress.ts).
+ * `onProgress` is for handing to an index reader that can upgrade the label to a
+ * determinate bar.
+ */
+export declare function cachedSetup<T>({ setup, label, }: {
+    setup: (opts: BaseOptions, onProgress?: OnProgress) => Promise<T>;
+    label?: string;
+}): (opts?: BaseOptions) => Promise<T>;
+/**
+ * {@link cachedSetup} taking a bare function instead of an options object.
+ *
+ * Kept because it is a published `@jbrowse/core/util` export and so pinned ABI
+ * (see reference/PLUGIN_ABI_STABILITY.md); nothing in this repo calls it. It
+ * used to be a second implementation, which is the thing worth not having: two
+ * memos with the same shape and different answers about whose `statusCallback`
+ * the shared work reports to, and no one place saying which to reach for.
+ */
+export declare function createSharedSetup<T>(run: (opts: BaseOptions) => Promise<T>): (opts?: BaseOptions) => Promise<T>;
+export {};

package/esm/util/cachedSetup.js

@@ -0,0 +1,87 @@
+import { downloadStatus } from './progress.js';
+/**
+ * Memoize an adapter's one-time setup (open the file, read the header, build a
+ * parser, download and parse a whole file) into a loader every method can
+ * await.
+ *
+ * Four behaviors, each of which a hand-rolled `p ??= f().catch(...)` gets wrong
+ * in a way that is invisible until it isn't:
+ *
+ * - **A rejected setup clears the memo**, so the next call retries instead of
+ *   replaying the same rejection for the life of the adapter.
+ * - **Progress fans out to every live waiter.** The setup body reports to
+ *   whoever is *currently* awaiting it, not to whoever happened to start it. A
+ *   memo that captured the first caller's `statusCallback` went silent the
+ *   moment that fetch was superseded — the display's latest-wins guard gates the
+ *   old callback off — so the fetch replacing it awaited a multi-GB parse behind
+ *   a blank loading overlay.
+ * - **`stopToken` is withheld from the shared work.** Honoring one caller's
+ *   cancel would abort a parse the caller replacing it is already waiting on,
+ *   and reject them both. A superseded fetch just stops listening. Cancellation
+ *   stays with the per-call work (indexed range queries), which no one else is
+ *   waiting on.
+ * - **`label` is shown only while the *first* attempt is in flight.** Re-entry
+ *   on pan/zoom (every getFeatures and byte estimate awaits the loader) would
+ *   otherwise re-flash "Downloading index" over an index that is already
+ *   resident.
+ *
+ * Pass `label` when the setup is an index read that narrates nothing itself, so
+ * the label is the whole story. Omit it when the setup reports from the inside —
+ * a whole-file fetch driving its own download bar — since two labels for one
+ * download is worse than one, and phases nest (see `openPhase` in progress.ts).
+ * `onProgress` is for handing to an index reader that can upgrade the label to a
+ * determinate bar.
+ */
+export function cachedSetup({ setup, label, }) {
+    const waiting = new Set();
+    let cached;
+    let ready = false;
+    const run = (opts, onProgress) => {
+        cached ??= setup({
+            ...opts,
+            stopToken: undefined,
+            statusCallback: status => {
+                for (const cb of waiting) {
+                    cb(status);
+                }
+            },
+        }, onProgress)
+            .then(result => {
+            ready = true;
+            return result;
+        })
+            .catch((e) => {
+            cached = undefined;
+            throw e;
+        });
+        return cached;
+    };
+    return async (opts = {}) => {
+        const { statusCallback } = opts;
+        if (statusCallback) {
+            waiting.add(statusCallback);
+        }
+        try {
+            return await (label === undefined || ready
+                ? run(opts)
+                : downloadStatus(label, statusCallback, onProgress => run(opts, onProgress)));
+        }
+        finally {
+            if (statusCallback) {
+                waiting.delete(statusCallback);
+            }
+        }
+    };
+}
+/**
+ * {@link cachedSetup} taking a bare function instead of an options object.
+ *
+ * Kept because it is a published `@jbrowse/core/util` export and so pinned ABI
+ * (see reference/PLUGIN_ABI_STABILITY.md); nothing in this repo calls it. It
+ * used to be a second implementation, which is the thing worth not having: two
+ * memos with the same shape and different answers about whose `statusCallback`
+ * the shared work reports to, and no one place saying which to reach for.
+ */
+export function createSharedSetup(run) {
+    return cachedSetup({ setup: run });
+}

package/esm/util/calculateDynamicBlocks.d.ts

@@ -1,3 +1,8 @@
 import { BlockSet } from './blockTypes.ts';
 import type { Base1DViewModel } from './calculateStaticBlocks.ts';
+/**
+ * Returns a BlockSet covering only the regions currently visible in the view.
+ * Used by tracks where static blocks are not feasible. start/end/offsetPx may
+ * be fractional.
+ */
 export default function calculateDynamicBlocks(model: Base1DViewModel, padding?: boolean, elision?: boolean): BlockSet;