@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/diagonalizeRegions.js

@@ -0,0 +1,192 @@
+import { cmpStr } from './cmpStr.js';
+import { createProgressReporter } from './progress.js';
+import { checkStopToken } from './stopToken.js';
+// A strand vote at least this lopsided (80% of aligned bases agreeing) decides
+// the reversal by itself. Below that the vote is unreliable: a chromosome
+// carrying many inversions splits it near 50/50, and MCScan `strand` is the
+// product of two gene strands rather than a block orientation. The ref-vs-query
+// position covariance then decides instead, which is the question reversal is
+// actually trying to answer (does the panel read monotonically along the
+// reference).
+const decisiveStrandFraction = 0.6;
+// Position along the anchor reference chromosome, and whether the query
+// chromosome should be displayed reversed.
+//
+// Summing in a fixed intra-pair order is what makes the result deterministic:
+// the synteny worker emits alignments in nondeterministic order (features from
+// concurrently-resolved blocks are concatenated by arrival, not position) and
+// float addition is non-associative, so a varying order would perturb these sums
+// in their low bits and could flip the query-chromosome ordering on a near-tie.
+// Only intra-pair order matters, since every sum here is over one pair.
+function anchorStats({ alignments, bases, strandWeightedSum }) {
+    alignments.sort((a, b) => a.refStart - b.refStart ||
+        a.queryStart - b.queryStart ||
+        a.refEnd - b.refEnd ||
+        a.queryEnd - b.queryEnd);
+    // x-axis (reference) length weights everything: consistent weighting for
+    // x-axis position and base count, matching the original jmonlong R
+    // implementation
+    let refPosSum = 0;
+    let queryPosSum = 0;
+    for (const aln of alignments) {
+        const alnLength = aln.refEnd - aln.refStart;
+        refPosSum += ((aln.refStart + aln.refEnd) / 2) * alnLength;
+        queryPosSum += ((aln.queryStart + aln.queryEnd) / 2) * alnLength;
+    }
+    const refMean = refPosSum / bases;
+    const queryMean = queryPosSum / bases;
+    // length-weighted covariance of the two axes' positions, centered on the means
+    // so it stays precise at genomic magnitudes. Negative means the query runs
+    // antiparallel to the reference.
+    let covariance = 0;
+    for (const aln of alignments) {
+        covariance +=
+            (aln.refEnd - aln.refStart) *
+                ((aln.refStart + aln.refEnd) / 2 - refMean) *
+                ((aln.queryStart + aln.queryEnd) / 2 - queryMean);
+    }
+    const strandFraction = strandWeightedSum / bases;
+    return {
+        bestRefPos: refMean,
+        shouldReverse: Math.abs(strandFraction) > decisiveStrandFraction || covariance === 0
+            ? strandFraction < 0
+            : covariance < 0,
+    };
+}
+// Groups alignments by vertical-axis (query) chromosome, accumulates total
+// aligned bases and strand per (query, reference) pair. Selects the reference
+// chromosome with the most aligned bases as the anchor, then sorts query
+// chromosomes to follow that reference's order, reversing a query chromosome
+// that runs antiparallel to its anchor.
+//
+// - refRefName:   horizontal-axis (reference) chromosome
+// - queryRefName: vertical-axis (query) chromosome
+export async function diagonalizeRegions(alignments, referenceRegions, currentRegions, { stopToken, statusCallback, } = {}) {
+    // Both passes below are long enough to notice on a whole-genome alignment —
+    // the grouping walks every alignment, and the ordering pass sorts each query
+    // chromosome's group. They used to share a single cancel check between them,
+    // so the whole grouping pass ran after a cancel and the bar sat on the
+    // fetch's last message throughout. Two reporters because the phases count
+    // different things (alignments, then chromosomes), so one auto-incrementing
+    // counter across both would report a meaningless fraction.
+    const reportGrouping = createProgressReporter({
+        label: 'Grouping alignments',
+        total: alignments.length,
+        statusCallback,
+        stopToken,
+    });
+    // first appearance wins: a refName can appear in more than one reference
+    // region, and the ordering key is where that chromosome starts on the axis
+    const refOrder = new Map();
+    for (const [i, region] of referenceRegions.entries()) {
+        if (!refOrder.has(region.refName)) {
+            refOrder.set(region.refName, i);
+        }
+    }
+    // outer key: vertical chrom; inner key: horizontal chrom. Alignments to a
+    // reference chromosome the axis does not display are skipped: they can supply
+    // neither an ordering index nor a comparable position.
+    const queryGroups = new Map();
+    for (const aln of alignments) {
+        reportGrouping();
+        const refIndex = refOrder.get(aln.refRefName);
+        if (refIndex !== undefined) {
+            let group = queryGroups.get(aln.queryRefName);
+            if (!group) {
+                group = new Map();
+                queryGroups.set(aln.queryRefName, group);
+            }
+            let data = group.get(aln.refRefName);
+            if (!data) {
+                data = {
+                    refName: aln.refRefName,
+                    refIndex,
+                    bases: 0,
+                    strandWeightedSum: 0,
+                    alignments: [],
+                };
+                group.set(aln.refRefName, data);
+            }
+            const alnLength = aln.refEnd - aln.refStart;
+            data.bases += alnLength;
+            data.strandWeightedSum += (aln.strand >= 0 ? 1 : -1) * alnLength;
+            data.alignments.push(aln);
+        }
+    }
+    const queryOrdering = [];
+    const reportOrdering = createProgressReporter({
+        label: 'Ordering chromosomes',
+        total: queryGroups.size,
+        statusCallback,
+        stopToken,
+    });
+    for (const [verticalChrom, group] of queryGroups) {
+        reportOrdering();
+        let best;
+        for (const data of group.values()) {
+            // the refName tiebreak is explicit because Map iteration follows insertion
+            // order, which follows the order alignments arrived in
+            if (!best ||
+                data.bases > best.bases ||
+                (data.bases === best.bases && cmpStr(data.refName, best.refName) < 0)) {
+                best = data;
+            }
+        }
+        // bases === 0 means every alignment was zero-length, leaving no position to
+        // order by, so such a chromosome joins the unaligned tail below
+        if (best !== undefined && best.bases > 0) {
+            queryOrdering.push({
+                refName: verticalChrom,
+                bestRefIndex: best.refIndex,
+                ...anchorStats(best),
+            });
+        }
+    }
+    checkStopToken(stopToken);
+    queryOrdering.sort((a, b) => a.bestRefIndex - b.bestRefIndex ||
+        a.bestRefPos - b.bestRefPos ||
+        cmpStr(a.refName, b.refName));
+    // group by refName: a refName can appear in more than one region (e.g. a
+    // chromosome displayed in multiple regions), and all of them move together
+    const regionsByName = new Map();
+    for (const region of currentRegions) {
+        let group = regionsByName.get(region.refName);
+        if (!group) {
+            group = [];
+            regionsByName.set(region.refName, group);
+        }
+        group.push(region);
+    }
+    const orderedNames = new Set(queryOrdering.map(q => q.refName));
+    const newQueryRegions = [];
+    let regionsReversed = 0;
+    for (const { refName, shouldReverse } of queryOrdering) {
+        for (const region of regionsByName.get(refName) ?? []) {
+            newQueryRegions.push({ ...region, reversed: shouldReverse });
+            if (shouldReverse !== (region.reversed ?? false)) {
+                regionsReversed++;
+            }
+        }
+    }
+    // Regions with no alignments are appended after the ordered ones
+    const regionsWithoutAlignments = currentRegions.filter(r => !orderedNames.has(r.refName));
+    // Count how many regions ended up at a different position than they started
+    // (within the subset that participated in the ordering — unaligned regions
+    // keep their tail position and aren't counted as moves).
+    const previousOrder = currentRegions
+        .map(r => r.refName)
+        .filter(name => orderedNames.has(name));
+    let regionsReordered = 0;
+    for (let i = 0; i < newQueryRegions.length; i++) {
+        if (newQueryRegions[i].refName !== previousOrder[i]) {
+            regionsReordered++;
+        }
+    }
+    return {
+        newRegions: [...newQueryRegions, ...regionsWithoutAlignments],
+        stats: {
+            regionsReordered,
+            regionsReversed,
+        },
+    };
+}

package/esm/util/environment.d.ts

@@ -0,0 +1,4 @@
+export declare const isElectron: boolean;
+export declare const isNode: boolean;
+export declare function indexedDBAvailable(): boolean;
+export declare const rIC: ((cb: () => void) => void) | (((callback: IdleRequestCallback, options?: IdleRequestOptions) => number) & typeof requestIdleCallback);

package/esm/util/environment.js

@@ -0,0 +1,43 @@
+// Which JS environment we are running in, plus the idle-callback shim that
+// depends on it. Deliberately dependency-free and separate from the `util`
+// barrel: `util/io` needs `isElectron`/`isNode`, and importing them from the
+// barrel dragged the whole of `@jbrowse/core/util` — MST, the configuration
+// system, MUI — into anything that opened a file.
+export const isElectron = /electron/i.test(typeof navigator !== 'undefined' ? navigator.userAgent : '');
+// equivalent to the `detect-node` package: true only inside a real Node.js
+// process, not in browsers where `process` may be polyfilled by the bundler
+// (the toString brand is '[object process]' only for the genuine global).
+// `process` isn't in core's browser-targeted build lib, so read it off
+// globalThis rather than referencing the bare global
+export const isNode = Object.prototype.toString.call(globalThis.process) === '[object process]';
+// Whether there is an IndexedDB to open. The two callers gate on it rather than
+// catching, so the absence stays silent: opening it anyway throws a
+// ReferenceError that reads like a real failure, and that is the reason every
+// test run had to filter "indexedDB" out of console.error wholesale.
+//
+// Guarded like the Web Storage globals (see util/webStorage.ts): a bare
+// `typeof indexedDB` invokes the same getter, which throws rather than answering
+// in a cross-origin iframe with third-party storage blocked. So the probe that
+// exists to avoid a throw was itself the throw, in the one environment where it
+// matters — an embedded product on someone else's page.
+export function indexedDBAvailable() {
+    try {
+        return typeof indexedDB !== 'undefined';
+    }
+    catch {
+        return false;
+    }
+}
+// the real idle callback where the realm has one, otherwise a short timeout.
+// jsdom has neither, so tests install a synchronous shim
+// (config/jest/requestIdleCallback.js) rather than this branching on the
+// environment
+export const rIC = 
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+typeof window !== 'undefined' && window.requestIdleCallback
+    ? window.requestIdleCallback
+    : (cb) => {
+        setTimeout(() => {
+            cb();
+        }, 1);
+    };

package/esm/util/eventPoint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A mouse event's position in the coordinate space of the element the handler
+ * is bound to.
+ *
+ * Off `currentTarget`, so there is no ref to thread and no way to measure
+ * against an element other than the one that received the event — which is the
+ * mistake this replaces. Five display handlers spelled the same three lines out,
+ * in three spellings, and each was one edit from measuring against a box the
+ * pointer was not in.
+ *
+ * **Read it during the handler.** React clears `currentTarget` once the handler
+ * returns, so a deferred read (an rAF, a promise) measures `null`.
+ *
+ * Two neighbours do a deliberately different thing, and neither is a candidate
+ * for this:
+ *
+ * - `getRelativeX` measures against an element passed in, because a rubberband
+ *   drag tracks the pointer across the whole document and the box it projects
+ *   through is not whatever is under the cursor.
+ * - A display whose canvas is a borderless leaf element (the pileup) reads
+ *   `offsetX`/`offsetY` off the native event, which is already this and costs no
+ *   layout read. That only holds while nothing is drawn inside the element, so
+ *   it is a fact about that canvas rather than a style to copy.
+ */
+export declare function eventPoint(event: {
+    clientX: number;
+    clientY: number;
+    currentTarget: Element;
+}): {
+    x: number;
+    y: number;
+};

package/esm/util/eventPoint.js

@@ -0,0 +1,28 @@
+/**
+ * A mouse event's position in the coordinate space of the element the handler
+ * is bound to.
+ *
+ * Off `currentTarget`, so there is no ref to thread and no way to measure
+ * against an element other than the one that received the event — which is the
+ * mistake this replaces. Five display handlers spelled the same three lines out,
+ * in three spellings, and each was one edit from measuring against a box the
+ * pointer was not in.
+ *
+ * **Read it during the handler.** React clears `currentTarget` once the handler
+ * returns, so a deferred read (an rAF, a promise) measures `null`.
+ *
+ * Two neighbours do a deliberately different thing, and neither is a candidate
+ * for this:
+ *
+ * - `getRelativeX` measures against an element passed in, because a rubberband
+ *   drag tracks the pointer across the whole document and the box it projects
+ *   through is not whatever is under the cursor.
+ * - A display whose canvas is a borderless leaf element (the pileup) reads
+ *   `offsetX`/`offsetY` off the native event, which is already this and costs no
+ *   layout read. That only holds while nothing is drawn inside the element, so
+ *   it is a fact about that canvas rather than a style to copy.
+ */
+export function eventPoint(event) {
+    const rect = event.currentTarget.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+}

package/esm/util/fetchAndMaybeUnzip.d.ts

@@ -0,0 +1,6 @@
+import type { BaseOptions } from '../data_adapters/BaseAdapter/index.ts';
+import type { StatusPhase } from './progress.ts';
+import type { GenericFilehandle } from 'generic-filehandle2';
+export declare function isGzip(buf: Uint8Array): boolean;
+export declare function fetchAndMaybeUnzip(loc: GenericFilehandle, opts?: BaseOptions, label?: string | StatusPhase): Promise<Uint8Array<ArrayBufferLike>>;
+export declare function fetchAndMaybeUnzipText(loc: GenericFilehandle, opts?: BaseOptions, label?: string | StatusPhase): Promise<string>;

package/esm/util/fetchAndMaybeUnzip.js

@@ -0,0 +1,64 @@
+import { redactSource } from './getLocationUri.js';
+import { downloadStatus, phaseOf, updateStatus } from './progress.js';
+import { withStopTokenSignal } from './stopToken.js';
+export function isGzip(buf) {
+    return buf[0] === 31 && buf[1] === 139 && buf[2] === 8;
+}
+export async function fetchAndMaybeUnzip(loc, opts = {}, 
+// what is being downloaded, for the loading UI. Defaulted rather than
+// required because most callers are a track's one data file, where the track
+// name is already on screen; name it wherever several files load at once
+// behind a single indicator and "Downloading file" can't say which (the four
+// parallel assembly loads, say). The URL is not the caller's to supply — see
+// below
+label = 'Downloading file') {
+    // statusCallback is passed through as-is rather than defaulted to a no-op, so
+    // that "nobody is listening" reaches the reader: downloadStatus then hands it
+    // no onProgress and generic-filehandle2 takes `res.bytes()` rather than its
+    // getReader loop.
+    //
+    // **That is not the faster path, and this comment used to say it was.** In a
+    // Chrome worker the loop is ~1.8x faster up to 10MB and only ~1.1x slower past
+    // ~25MB — agent-docs/measurements/download-read-path.json. What withholding it
+    // buys is that a caller who asked for no reporting gets none, here and in the
+    // worker alike; the read speed is a wash at best and against us at the sizes a
+    // whole-file load usually is.
+    // Where a stalled load gets the URL it names, and the reason no call site
+    // passes one: `loc` knows. Every filehandle `openLocation` builds carries the
+    // address it was constructed with (generic-filehandle2 2.4.0), so this is true
+    // of every download in the tree rather than of the handful that remembered to
+    // say so. A Blob and a FileHandle report nothing, which is right — their bytes
+    // came from the user and there is no server to go and check.
+    //
+    // Redacted here rather than at the source, because the handle's `source` is
+    // verbatim what it fetches (a presigned URL keeps its signature) and this is
+    // the layer that hands it to a display.
+    const phase = loc.source === undefined
+        ? label
+        : { message: phaseOf(label), source: redactSource(loc.source) };
+    const { statusCallback, stopToken } = opts;
+    // the stop token becomes the read's signal, so a cancelled whole-file load
+    // drops at the socket rather than downloading a multi-GB body to completion
+    const buf = await withStopTokenSignal(stopToken, signal => downloadStatus(phase, statusCallback, onProgress => loc.readFile({ ...opts, onProgress, signal })));
+    // the inflater is imported dynamically because this module is reachable from
+    // the core/util barrel, so a static import put bgzf-filehandle + pako
+    // (~180KB) on the startup path of every page load; only an actually-gzipped
+    // file needs them
+    return isGzip(buf)
+        ? await updateStatus('Unzipping', statusCallback, async () => {
+            const { unzip } = await import('@gmod/bgzf-filehandle');
+            return unzip(buf);
+        }, 
+        // a cancel landing here is otherwise discovered only by whatever parses
+        // the result, after a whole-file inflate has run to completion
+        stopToken)
+        : buf;
+}
+export async function fetchAndMaybeUnzipText(loc, opts, label) {
+    const buffer = await fetchAndMaybeUnzip(loc, opts, label);
+    // 512MB  max chrome string length is 512MB
+    if (buffer.length > 536_870_888) {
+        throw new Error('Data exceeds maximum string length (512MB)');
+    }
+    return new TextDecoder('utf8', { fatal: true }).decode(buffer);
+}

package/esm/util/fetchContext.d.ts

@@ -0,0 +1,82 @@
+import type { RpcCallArgs, RpcCallReturn } from '../rpc/RpcRegistry.ts';
+import type { StatusCallback } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface FetchContext {
+    stopToken: StopToken;
+    isStale: () => boolean;
+    /**
+     * The RPC `statusCallback` for the work this context describes: guarded to
+     * this fetch (a superseded one cannot repaint the overlay of the fetch that
+     * replaced it) and throttled through the display-wide window. `callRpc`
+     * injects it — read it directly only for a status write of your own
+     * (`updateStatus` phase labels).
+     *
+     * The fan-out helpers hand each region a context whose callback is that
+     * region's own slot (`callEachRegion`, and `fetchEachRegion` through it), so
+     * a `ctx.callRpc` aggregates N parallel regions into one bar in the fan-out
+     * case and reports the whole fetch in the batched one. Reading it off the
+     * model instead — or reusing the *outer* ctx's inside a fan-out — is what
+     * made parallel regions clobber each other's progress, and is now the thing
+     * you would have to go out of your way to do.
+     */
+    statusCallback: StatusCallback;
+    /**
+     * The one way a fetch calls an RPC: the registry-typed
+     * `rpcManager.call(rpcSessionId, method, args)` with this context's
+     * `stopToken` and `statusCallback` injected. Both used to be hand-threaded
+     * at every fetch site, and forgetting either was silent — no cancellation
+     * for that display, or no progress — which is exactly the failure class the
+     * envelope makes inexpressible: a fetch cannot issue an RPC the cancel and
+     * the status bar don't know about.
+     *
+     * Declared with a `this` parameter so it reads the *holding* context's
+     * token and callback — the fan-out copies rebind it to their own status
+     * slot by construction — and so destructuring it off the context is a type
+     * error rather than a stale binding.
+     */
+    callRpc: <M extends string>(this: FetchContext, method: M, args: Omit<RpcCallArgs<M>, 'stopToken' | 'statusCallback'>) => Promise<RpcCallReturn<M>>;
+}
+/**
+ * Build a {@link FetchContext} over a live fetch's primitives. One
+ * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
+ * carries the same `callRpc` envelope.
+ *
+ * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
+ * means a track or something under it.** `rpcSessionId` is declared by
+ * `BaseTrackModel` and by nothing above it, so the walk throws rather than
+ * falling back — and a fetch installed on a VIEW gets a context whose `callRpc`
+ * cannot be called at all. That is not a gap to fix here: the id names the track
+ * whose adapter is being read, and a view fetching for several tracks has a
+ * different one per call. The shape is to fan out and rebuild a context per
+ * track, which is what the breakpoint split view's overlay fetch does.
+ */
+export declare function makeFetchContext(self: IStateTreeNode, base: {
+    stopToken: StopToken;
+    isStale: () => boolean;
+    statusCallback: StatusCallback;
+}): FetchContext;
+/**
+ * One context per concurrent operation, each carrying its own status slot, so
+ * the N of them aggregate into a single Σcurrent/Σtotal bar rather than
+ * last-writer-wins on the owner's one status field.
+ *
+ * A copy of the ctx rather than a separate `slot()` on it because a caller
+ * should not have to know which kind of context it holds: the field is called
+ * `statusCallback` in both, and `statusCallback: ctx.statusCallback` at the RPC
+ * call site is correct in the fan-out and in the batched case alike — as is
+ * {@link makeFetchContext}'s `callRpc`, whose `this` parameter rebinds to the
+ * copy, so the envelope injects that operation's slot and not the batch's.
+ * Callers used to reach back to the model for `makeRegionStatusCallback(index)`,
+ * and the whole hazard was that forgetting to looked exactly like remembering
+ * to.
+ *
+ * Here beside `makeFetchContext` rather than in either fetch family, because
+ * both fan out inside one run: the per-region LGV helpers over N regions
+ * (`callEachRegion`), and the shared `installFetch` skeleton over whatever a
+ * display's `run` issues concurrently — the multi-way display's N lanes.
+ *
+ * The fan-out's lifetime is this batch's: slots are never reclaimed, and the
+ * batch is the thing that ends.
+ */
+export declare function fanOutStatus<C extends FetchContext>(ctx: C, count: number): C[];

package/esm/util/fetchContext.js

@@ -0,0 +1,59 @@
+import { getRpcSessionId } from './parentWalk.js';
+import { createStatusFanOut } from './progress.js';
+import { getRpcHost } from './sessionServices.js';
+/**
+ * Build a {@link FetchContext} over a live fetch's primitives. One
+ * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
+ * carries the same `callRpc` envelope.
+ *
+ * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
+ * means a track or something under it.** `rpcSessionId` is declared by
+ * `BaseTrackModel` and by nothing above it, so the walk throws rather than
+ * falling back — and a fetch installed on a VIEW gets a context whose `callRpc`
+ * cannot be called at all. That is not a gap to fix here: the id names the track
+ * whose adapter is being read, and a view fetching for several tracks has a
+ * different one per call. The shape is to fan out and rebuild a context per
+ * track, which is what the breakpoint split view's overlay fetch does.
+ */
+export function makeFetchContext(self, base) {
+    return {
+        ...base,
+        callRpc(method, args) {
+            return getRpcHost(self).rpcManager.call(getRpcSessionId(self), method, {
+                ...args,
+                stopToken: this.stopToken,
+                statusCallback: this.statusCallback,
+            });
+        },
+    };
+}
+/**
+ * One context per concurrent operation, each carrying its own status slot, so
+ * the N of them aggregate into a single Σcurrent/Σtotal bar rather than
+ * last-writer-wins on the owner's one status field.
+ *
+ * A copy of the ctx rather than a separate `slot()` on it because a caller
+ * should not have to know which kind of context it holds: the field is called
+ * `statusCallback` in both, and `statusCallback: ctx.statusCallback` at the RPC
+ * call site is correct in the fan-out and in the batched case alike — as is
+ * {@link makeFetchContext}'s `callRpc`, whose `this` parameter rebinds to the
+ * copy, so the envelope injects that operation's slot and not the batch's.
+ * Callers used to reach back to the model for `makeRegionStatusCallback(index)`,
+ * and the whole hazard was that forgetting to looked exactly like remembering
+ * to.
+ *
+ * Here beside `makeFetchContext` rather than in either fetch family, because
+ * both fan out inside one run: the per-region LGV helpers over N regions
+ * (`callEachRegion`), and the shared `installFetch` skeleton over whatever a
+ * display's `run` issues concurrently — the multi-way display's N lanes.
+ *
+ * The fan-out's lifetime is this batch's: slots are never reclaimed, and the
+ * batch is the thing that ends.
+ */
+export function fanOutStatus(ctx, count) {
+    const slot = createStatusFanOut(ctx.statusCallback);
+    return Array.from({ length: count }, () => ({
+        ...ctx,
+        statusCallback: slot(),
+    }));
+}

package/esm/util/fetchHub.d.ts

@@ -0,0 +1,15 @@
+export interface HubConfig {
+    assemblies?: Record<string, unknown>[];
+    aggregateTextSearchAdapters?: Record<string, unknown>[];
+    tracks?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+export declare function hubUrl(hub: string): string;
+/**
+ * Fetch a hosted assembly config from jbrowse.org by UCSC database name (`hg38`,
+ * `mm10`, ...) or GenArk accession (`GCA_...`/`GCF_...`). Returns the full config
+ * — a self-contained assembly plus a catalog of CORS-enabled hosted tracks. Pass
+ * the name straight to `createLinearGenomeView({ assembly: 'hg38' })` for the
+ * common case; call this directly only to cherry-pick tracks from the catalog.
+ */
+export declare function fetchHub(hub: string): Promise<HubConfig>;

package/esm/util/fetchHub.js

@@ -0,0 +1,31 @@
+import { addRelativeUris } from './addRelativeUris.js';
+const HUB_HOST = 'https://jbrowse.org';
+// A UCSC database name (hg38, mm10, ...) maps to /ucsc/<db>/; a GenArk accession
+// (GCA_/GCF_...) fans its 9 digits out into a 3-level directory tree.
+export function hubUrl(hub) {
+    const genark = /^(GC[AF])_(\d{3})(\d{3})(\d{3})/.exec(hub);
+    return genark
+        ? `${HUB_HOST}/hubs/genark/${genark[1]}/${genark[2]}/${genark[3]}/${genark[4]}/${hub}/config.json`
+        : `${HUB_HOST}/ucsc/${hub}/config.json`;
+}
+/**
+ * Fetch a hosted assembly config from jbrowse.org by UCSC database name (`hg38`,
+ * `mm10`, ...) or GenArk accession (`GCA_...`/`GCF_...`). Returns the full config
+ * — a self-contained assembly plus a catalog of CORS-enabled hosted tracks. Pass
+ * the name straight to `createLinearGenomeView({ assembly: 'hg38' })` for the
+ * common case; call this directly only to cherry-pick tracks from the catalog.
+ */
+export async function fetchHub(hub) {
+    const url = hubUrl(hub);
+    const response = await fetch(url);
+    if (response.ok) {
+        const config = (await response.json());
+        // hosted configs reference their data relative to the config's own location
+        addRelativeUris(config, new URL(url));
+        return config;
+    }
+    else {
+        throw new Error(`hub "${hub}" not found (${response.status} from ${url}). ` +
+            'See https://jbrowse.org for available assemblies.');
+    }
+}

package/esm/util/fetchJson.d.ts

@@ -0,0 +1 @@
+export declare function fetchJson<T = unknown>(url: string, init?: RequestInit): Promise<T>;

package/esm/util/fetchJson.js

@@ -0,0 +1,7 @@
+export async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status} fetching ${url}: ${await res.text().catch(() => '')}`);
+    }
+    return (await res.json());
+}

package/esm/util/fetchPhases.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The three phases a single-payload fetch is written in, so the rules that
+ * strand a display when any of them is got wrong are structural rather than
+ * remembered.
+ *
+ * The shared `installFetch` skeleton takes this shape, and so does the LGV
+ * global family (`installGlobalFetchAutorun`, over `FetchMixin.runFetch`). It
+ * was the same contract declared twice, with the same three rules explained
+ * twice, which is a drift axis over rules whose whole value is being the same
+ * everywhere.
+ *
+ * `TCtx` is what a family hands its `run`: a `FetchContext` for most of them, a
+ * `ComparativeFetchContext` (that plus adapter config and refName rename) for
+ * the comparative displays, which wrap their own `run` rather than the skeleton
+ * growing an option. That is the one thing that genuinely differs, so it is the
+ * one parameter.
+ *
+ * **The per-region family is deliberately not this shape.** N regions stream and
+ * four displays decide something across them mid-fetch, so there is nowhere to
+ * put a single `commit` — it gets the same "never record what you did not
+ * receive" invariant from `RegionFetchContext.commitRegion` instead, and the
+ * note there is worth reading beside this one.
+ */
+export interface FetchPhases<TArgs, TResult, TCtx> {
+    /**
+     * Runs synchronously inside the autorun, so its reads — on top of the
+     * skeleton's own trigger list — are the dependency set. Returning `undefined`
+     * skips the run (minimized, an empty viewport, the display's own gate shut);
+     * the reads that decided that stay tracked, so the autorun rewakes. Everything
+     * the round trip has to be judged against is captured here and travels in
+     * `TArgs`: the viewport, the region set, the resolution.
+     *
+     * Prefer folding the fetch's inputs into one `currentFetchKey` computed over
+     * tracking them individually: a pan inside the buffered window then recomputes
+     * the same string and does not refire, and that same string tags the committed
+     * data so it cannot drift from what was fetched even if the view moves again
+     * mid-RPC.
+     *
+     * **Comparing that key against what is already committed does not belong
+     * here.** This gate is "is there anything to fetch", which a retry must not
+     * override; "do I already have exactly this" is `installFetch`'s `fetchKey` gate,
+     * which a retry must. Writing the second one into this one is how a display
+     * gets a dead Retry button — see there.
+     *
+     * What it must **not** do is move a trigger read of its own under a bail-out.
+     * See ARCHITECTURE.md §"The global-fetch trigger list must be read
+     * unconditionally".
+     */
+    prepare: () => TArgs | undefined;
+    /**
+     * Owns every await — the RPC, a byte-gate pre-flight, any post-RPC derivation
+     * the commit needs — and writes nothing to the model. Returns `undefined` for
+     * "nothing to commit", which is what a pre-flight that stopped this fetch
+     * says.
+     *
+     * **Nothing it reads is tracked**, so the payload it assembles cannot widen
+     * the autorun's dependency set the way calling `rpcProps()` in the body would.
+     * Being async is not what buys that — `run` is *called* synchronously, so its
+     * own prefix down to its first `await` runs wherever the caller was. Each
+     * family arranges it: the global one reaches `run` through
+     * `FetchMixin.runFetch`, an MST flow and so an action, which MobX runs
+     * untracked; the comparative one calls its lifecycle inside `untracked`
+     * because it has no action to hide behind.
+     */
+    run: (args: TArgs, ctx: TCtx) => Promise<TResult | undefined>;
+    /**
+     * Synchronous, and reached only while this is still the latest fetch, so a
+     * superseded fetch resolving late cannot clobber fresher data. Async work here
+     * would reopen exactly that window, which is why it may not await. It takes
+     * `args` back, so what it stamps onto the committed data is what the fetch was
+     * issued for and not a live re-read.
+     *
+     * **Reached only when `run` produced a result**, which is what keeps a display
+     * from ever recording data it did not receive.
+     */
+    commit: (result: TResult, args: TArgs) => void;
+}

package/esm/util/fetchPhases.js

@@ -0,0 +1 @@
+export {};