@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/installInitAutorun.d.ts

@@ -0,0 +1,62 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+interface InitAutorunHost<T> extends IStateTreeNode {
+    pendingLaunch?: T;
+    setLaunch: (launch?: T) => void;
+    setError: (error: unknown) => void;
+}
+export interface InitApplyContext {
+    /**
+     * True once this init can no longer be the one being applied: the node is
+     * gone, or a newer `setLaunch` has replaced it. Any mid-apply wait that can
+     * park indefinitely must fold this into its condition — an unbounded wait on
+     * state that never arrives holds the drain open, and the newer init that
+     * would have superseded it is exactly what gets stranded. This is the causal
+     * form of the wait ceiling; a fixed timeout bounds the same hazard only by
+     * guessing, and pays for it by expiring on slow-but-healthy loads.
+     */
+    superseded: () => boolean;
+}
+interface InitAutorunOptions<T> {
+    /** autorun name, for the MobX devtools/spy stream */
+    name: string;
+    /**
+     * Read synchronously at the top of the autorun, so whatever it touches is
+     * the dependency set that re-fires this. Typically the measured width plus
+     * whatever the view needs before `apply` can run.
+     */
+    ready: () => boolean;
+    /**
+     * Whether the view has materialized — the same line each view's
+     * postProcessSnapshot draws for persistence (dotplot: assemblyNames set;
+     * synteny: rows built). Decides the failure policy, see below.
+     */
+    materialized: () => boolean;
+    /** Apply one init blob. Owns the ordered steps; never clears `init`. */
+    apply: (init: T, ctx: InitApplyContext) => Promise<void>;
+}
+/**
+ * The launch state machine shared by the views that take a declarative launch
+ * blob (LinearGenomeView, DotplotView, LinearSyntenyView): the re-entry guard,
+ * the readiness gate, the serialized drain, the identity-checked clear, the
+ * isAlive guards, and one failure policy.
+ *
+ * The failure policy keys off `materialized`, the same line each view's
+ * postProcessSnapshot already draws for persistence:
+ *
+ * - Not materialized — nothing is on screen and `launch` is still persisted, so
+ *   keep it for a reload retry and `setError`. That flips the view onto its
+ *   import form, which renders the error in its own banner; a snackbar would
+ *   state the same failure twice and the banner is the one that persists.
+ * - Materialized — the view works, so a later failure is one sub-step's
+ *   problem and must not take the view down with it. `setError` would, since
+ *   showImportForm keys off `error` alone and would discard rows that loaded
+ *   fine, so report it as a snackbar instead. Clearing `launch` is also what
+ *   disarms the re-fire: `ready` usually folds in the measured width, so
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
+ *
+ * `apply` therefore never clears `launch` and never catches for reporting — it
+ * catches only the failures it wants to keep going through (a bad locstring in
+ * one row), and everything it lets escape is fatal-as-of-that-point.
+ */
+export declare function installInitAutorun<T>(self: InitAutorunHost<T>, opts: InitAutorunOptions<T>): void;
+export {};

package/esm/util/installInitAutorun.js

@@ -0,0 +1,107 @@
+import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
+import { autorun } from 'mobx';
+import { getNotificationSink } from './sessionServices.js';
+// Clear only when the pending blob is still the exact object we applied. A
+// setLaunch that lands while `apply` is awaiting (React StrictMode remounts, a
+// programmatic re-launch) swaps in a new object; clearing unconditionally would
+// silently drop it. Leaving it lets the drain loop apply it next.
+function clearIfUnchanged(self, init) {
+    if (isAlive(self) && self.pendingLaunch === init) {
+        self.setLaunch(undefined);
+    }
+}
+async function applyInitOnce(self, init, { apply, materialized }) {
+    try {
+        await apply(init, {
+            superseded: () => !isAlive(self) || self.pendingLaunch !== init,
+        });
+        clearIfUnchanged(self, init);
+    }
+    catch (e) {
+        // the autorun body is async, so anything escaping here becomes an
+        // unhandled rejection: no report at all, and the drain stops with the view
+        // half-initialized
+        console.error(e);
+        if (isAlive(self)) {
+            if (materialized()) {
+                clearIfUnchanged(self, init);
+                getNotificationSink(self).notifyError(`${e}`, e);
+            }
+            else {
+                self.setError(e);
+            }
+        }
+    }
+}
+function currentInit(self, { ready }) {
+    return isAlive(self) && ready() ? self.pendingLaunch : undefined;
+}
+// Apply pending inits one at a time until none remain. Serializing (rather
+// than letting the autorun run `apply` concurrently) is what keeps re-entrant
+// width churn safe: overlapping applies duplicate whatever the init appends
+// (LGV's highlights did exactly this) and, where `apply` rebuilds sub-views,
+// the second run detaches the models the first is still awaiting. Looping also
+// guarantees an init set mid-apply is eventually applied instead of stranded.
+async function drainInit(self, opts) {
+    let pending = currentInit(self, opts);
+    while (pending !== undefined) {
+        await applyInitOnce(self, pending, opts);
+        const next = currentInit(self, opts);
+        // a fatal failure keeps `launch` for a reload retry; the same object still
+        // sitting there means it was not consumed, so stop rather than spin on it
+        pending = next === pending ? undefined : next;
+    }
+}
+/**
+ * The launch state machine shared by the views that take a declarative launch
+ * blob (LinearGenomeView, DotplotView, LinearSyntenyView): the re-entry guard,
+ * the readiness gate, the serialized drain, the identity-checked clear, the
+ * isAlive guards, and one failure policy.
+ *
+ * The failure policy keys off `materialized`, the same line each view's
+ * postProcessSnapshot already draws for persistence:
+ *
+ * - Not materialized — nothing is on screen and `launch` is still persisted, so
+ *   keep it for a reload retry and `setError`. That flips the view onto its
+ *   import form, which renders the error in its own banner; a snackbar would
+ *   state the same failure twice and the banner is the one that persists.
+ * - Materialized — the view works, so a later failure is one sub-step's
+ *   problem and must not take the view down with it. `setError` would, since
+ *   showImportForm keys off `error` alone and would discard rows that loaded
+ *   fine, so report it as a snackbar instead. Clearing `launch` is also what
+ *   disarms the re-fire: `ready` usually folds in the measured width, so
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
+ *
+ * `apply` therefore never clears `launch` and never catches for reporting — it
+ * catches only the failures it wants to keep going through (a bad locstring in
+ * one row), and everything it lets escape is fatal-as-of-that-point.
+ */
+export function installInitAutorun(self, opts) {
+    // `draining` is a plain closure flag, intentionally NOT observable so it
+    // stays out of the dependency graph. The autorun observes init + whatever
+    // `ready` reads, so it re-fires when either changes, but a re-entrant pass
+    // while a drain is in flight is a no-op — drainInit already consumes
+    // whatever init is current. The flag is load-bearing, not incidental:
+    // `ready` flips true→false→true when the measured width resets (StrictMode
+    // remount, a workspace tab being shown again), which re-fires this whether it
+    // is an autorun or a reaction.
+    let draining = false;
+    addDisposer(self, autorun(async function initAutorun() {
+        // read both unconditionally: they are the dependency set, and a run
+        // that bails still has to be woken by the thing it bailed on. Teardown
+        // mutates observables `ready` reads before the disposers run, and
+        // reading a detached node throws — here into an unawaited promise.
+        const alive = isAlive(self);
+        const isReady = alive && opts.ready();
+        const init = alive ? self.pendingLaunch : undefined;
+        if (isReady && init !== undefined && !draining) {
+            draining = true;
+            try {
+                await drainInit(self, opts);
+            }
+            finally {
+                draining = false;
+            }
+        }
+    }, { name: opts.name }));
+}

package/esm/util/intervals.d.ts

@@ -0,0 +1,20 @@
+export interface BasicFeature {
+    end: number;
+    start: number;
+    refName: string;
+}
+/**
+ * Merge intervals that overlap once each is grown by `padding` on both sides.
+ * `padding` is per side, so the merge window between two intervals is `2 *
+ * padding` — the default merges anything within 10kb of its neighbour, not 5kb.
+ * Callers that have already baked their padding into start/end pass 0.
+ */
+export declare function mergeIntervals<T extends {
+    start: number;
+    end: number;
+}>(intervals: T[], padding?: number): T[];
+/**
+ * {@link mergeIntervals} per refName: returns a new array of non-overlapping
+ * features. `padding` carries the same per-side meaning.
+ */
+export declare function gatherOverlaps<T extends BasicFeature>(regions: T[], padding?: number): T[];

package/esm/util/intervals.js

@@ -0,0 +1,37 @@
+/**
+ * Merge intervals that overlap once each is grown by `padding` on both sides.
+ * `padding` is per side, so the merge window between two intervals is `2 *
+ * padding` — the default merges anything within 10kb of its neighbour, not 5kb.
+ * Callers that have already baked their padding into start/end pass 0.
+ */
+export function mergeIntervals(intervals, padding = 5000) {
+    if (intervals.length <= 1) {
+        return intervals;
+    }
+    // clone so neither the input array order nor its elements are mutated
+    const sorted = [...intervals].sort((a, b) => a.start - b.start);
+    const stack = [{ ...sorted[0] }];
+    for (let i = 1; i < sorted.length; i++) {
+        const top = stack.at(-1);
+        const next = sorted[i];
+        if (top.end + padding < next.start - padding) {
+            stack.push({ ...next });
+        }
+        else if (top.end < next.end) {
+            top.end = next.end;
+        }
+    }
+    return stack;
+}
+/**
+ * {@link mergeIntervals} per refName: returns a new array of non-overlapping
+ * features. `padding` carries the same per-side meaning.
+ */
+export function gatherOverlaps(regions, padding = 5000) {
+    const memo = {};
+    for (const x of regions) {
+        memo[x.refName] ??= [];
+        memo[x.refName].push(x);
+    }
+    return Object.values(memo).flatMap(group => mergeIntervals(group, padding));
+}

package/esm/util/io/RemoteFileWithRangeCache.d.ts

@@ -1,11 +1,10 @@
-import { RemoteFile } from 'generic-filehandle2';
-export declare function clearCache(): void;
-export declare class RemoteFileWithRangeCache extends RemoteFile {
-    private cachedStat?;
-    stat(): Promise<{
-        size: number;
-    }>;
-    private fetchRange;
-    private getCachedRange;
-    fetch(url: string | RequestInfo, init?: RequestInit): Promise<Response>;
-}
+/**
+ * The chunk cache now lives in `@gmod/range-cache-filehandle`, extracted from
+ * this file so the @gmod parsers can use it without depending on
+ * `@jbrowse/core`, react and mobx-state-tree.
+ *
+ * Kept as a re-export rather than deleted: `products/jbrowse-web/src/tests`
+ * imports `clearCache` from this path directly, and `@jbrowse/core/util/io`
+ * re-exports the two classes from here.
+ */
+export { CachedFilehandle, RemoteFileWithRangeCache, clearCache, sweepIdleCache, } from '@gmod/range-cache-filehandle';

package/esm/util/io/RemoteFileWithRangeCache.js

@@ -1,148 +1,10 @@
-import { RemoteFile } from 'generic-filehandle2';
-const MAX_CACHE_ENTRIES = 2000;
-const CHUNK_SIZE = 256 * 1024;
-const MAX_CONCURRENT = 20;
-let cache = new Map();
-let activeCount = 0;
-const queue = [];
-function getCached(key) {
-    return cache.get(key);
-}
-function putCached(key, buffer) {
-    if (cache.size >= MAX_CACHE_ENTRIES) {
-        const firstKey = cache.keys().next().value;
-        if (firstKey !== undefined) {
-            cache.delete(firstKey);
-        }
-    }
-    cache.set(key, buffer);
-}
-export function clearCache() {
-    cache = new Map();
-}
-function runNext() {
-    if (queue.length > 0 && activeCount < MAX_CONCURRENT) {
-        activeCount++;
-        const next = queue.shift();
-        next();
-    }
-}
-function limitConcurrency(fn) {
-    return new Promise((resolve, reject) => {
-        function run() {
-            fn().then(val => {
-                activeCount--;
-                resolve(val);
-                runNext();
-            }, (err) => {
-                activeCount--;
-                reject(err instanceof Error ? err : new Error(String(err)));
-                runNext();
-            });
-        }
-        if (activeCount < MAX_CONCURRENT) {
-            activeCount++;
-            run();
-        }
-        else {
-            queue.push(run);
-        }
-    });
-}
-function cacheKey(url, chunkIndex) {
-    return `${url}:${chunkIndex}`;
-}
-export class RemoteFileWithRangeCache extends RemoteFile {
-    cachedStat;
-    async stat() {
-        if (!this.cachedStat) {
-            await this.getCachedRange(this.url, 0, 1);
-        }
-        return this.cachedStat ?? { size: 0 };
-    }
-    async fetchRange(url, start, end, signal) {
-        const res = await super.fetch(url, {
-            signal: signal ?? undefined,
-            headers: { range: `bytes=${start}-${end}` },
-        });
-        if (res.status === 416) {
-            return new Uint8Array(0);
-        }
-        if (!res.ok) {
-            const hint = ' (should be 206 for range requests)';
-            const msg = `HTTP ${res.status} fetching ${url} bytes ${start}-${end}${res.status === 200 ? hint : ''}`;
-            throw Object.assign(new Error(msg), { status: res.status });
-        }
-        if (!this.cachedStat) {
-            const contentRange = res.headers.get('content-range');
-            const match = contentRange ? /\/(\d+)$/.exec(contentRange) : null;
-            if (match) {
-                this.cachedStat = { size: parseInt(match[1], 10) };
-            }
-        }
-        return new Uint8Array(await res.arrayBuffer());
-    }
-    async getCachedRange(url, start, length, signal) {
-        const startChunk = Math.floor(start / CHUNK_SIZE);
-        const endChunk = Math.floor((start + length - 1) / CHUNK_SIZE);
-        let effectiveEndChunk = endChunk;
-        for (let i = startChunk; i < endChunk; i++) {
-            const c = getCached(cacheKey(url, i));
-            if (c !== undefined && c.length < CHUNK_SIZE) {
-                effectiveEndChunk = i;
-                break;
-            }
-        }
-        const chunkCount = effectiveEndChunk - startChunk + 1;
-        const runs = [];
-        for (let i = 0; i < chunkCount; i++) {
-            if (!getCached(cacheKey(url, startChunk + i))) {
-                const lastRun = runs[runs.length - 1];
-                if (lastRun?.end === i - 1) {
-                    lastRun.end = i;
-                }
-                else {
-                    runs.push({ start: i, end: i });
-                }
-            }
-        }
-        await Promise.all(runs.map(run => limitConcurrency(async () => {
-            const runStartChunk = startChunk + run.start;
-            const runEndChunk = startChunk + run.end;
-            const rangeStart = runStartChunk * CHUNK_SIZE;
-            const rangeEnd = (runEndChunk + 1) * CHUNK_SIZE - 1;
-            const data = await this.fetchRange(url, rangeStart, rangeEnd, signal);
-            for (let i = run.start; i <= run.end; i++) {
-                const offset = (i - run.start) * CHUNK_SIZE;
-                putCached(cacheKey(url, startChunk + i), data.subarray(offset, offset + CHUNK_SIZE));
-            }
-        })));
-        const offsetInFirstChunk = start - startChunk * CHUNK_SIZE;
-        const result = new Uint8Array(length);
-        let written = 0;
-        for (let i = 0; i < chunkCount; i++) {
-            const chunk = getCached(cacheKey(url, startChunk + i));
-            const sourceStart = i === 0 ? offsetInFirstChunk : 0;
-            const available = chunk.length - sourceStart;
-            const needed = length - written;
-            const copyLen = Math.min(available, needed);
-            result.set(chunk.subarray(sourceStart, sourceStart + copyLen), written);
-            written += copyLen;
-        }
-        return result.subarray(0, written);
-    }
-    async fetch(url, init) {
-        const range = new Headers(init?.headers).get('range');
-        if (range) {
-            const rangeParse = /bytes=(\d+)-(\d+)/.exec(range);
-            if (rangeParse) {
-                const [, startStr, endStr] = rangeParse;
-                const s = Number.parseInt(startStr, 10);
-                const e = Number.parseInt(endStr, 10);
-                const buffer = await this.getCachedRange(String(url), s, e - s + 1, init?.signal);
-                return new Response(buffer, { status: 206 });
-            }
-        }
-        return super.fetch(url, init);
-    }
-}
+/**
+ * The chunk cache now lives in `@gmod/range-cache-filehandle`, extracted from
+ * this file so the @gmod parsers can use it without depending on
+ * `@jbrowse/core`, react and mobx-state-tree.
+ *
+ * Kept as a re-export rather than deleted: `products/jbrowse-web/src/tests`
+ * imports `clearCache` from this path directly, and `@jbrowse/core/util/io`
+ * re-exports the two classes from here.
+ */
+export { CachedFilehandle, RemoteFileWithRangeCache, clearCache, sweepIdleCache, } from '@gmod/range-cache-filehandle';

package/esm/util/io/index.d.ts

@@ -1,7 +1,44 @@
 import type PluginManager from '../../PluginManager.ts';
-import type { FileLocation, UriLocation } from '../types/index.ts';
+import type { FileLocation, UriLocation } from '../types/data.ts';
 import type { Fetcher, GenericFilehandle } from 'generic-filehandle2';
+/** if a UriLocation has a baseUri, resolves its uri with respect to that base */
 export declare function resolveUriLocation(location: UriLocation): UriLocation;
 export declare function openLocation(location: FileLocation, pluginManager?: PluginManager): GenericFilehandle;
+/**
+ * Open a tabix-style index (TBI or CSI) and return it under the correct
+ * filehandle key for `new TabixIndexedFile(...)`. Centralizes the CSI-vs-TBI
+ * branch so callers can't mismatch the two — e.g. writing `=== 'CSI'` on both
+ * the csi and tbi lines, which silently yields no index at all.
+ */
+export declare function openTabixIndexFilehandle(location: FileLocation, indexType: string | undefined, pluginManager?: PluginManager): {
+    csiFilehandle: GenericFilehandle;
+    tbiFilehandle?: undefined;
+} | {
+    csiFilehandle?: undefined;
+    tbiFilehandle: GenericFilehandle;
+};
+/**
+ * A fetch that presents `location`'s credentials — and only for urls that
+ * credential covers.
+ *
+ * An account's own fetcher signs whatever url it is handed: the location it was
+ * built from decides which token to mint, not where the token may go. That is
+ * fine for a caller holding one url, which is what `openLocation` is, and wrong
+ * for one that fetches urls a *server* names. Htsget is the second kind — a
+ * ticket request answers with data-block urls that can point anywhere — and it
+ * had no way to ask whether a given url was still in scope.
+ *
+ * So ask here. Every url other than the one the fetcher was requested for goes
+ * back through the account's `handlesLocation`, which is the same
+ * `uriMatchesDomains` test that chose the account in the first place. Both
+ * directions matter: `domains` entries scope to a path as well as a host
+ * (`data.mylab.org/private`, and the origin-plus-directory form every ephemeral
+ * HTTP Basic account is minted with), and one account routinely spans several
+ * hosts (Dropbox lists seven). An origin comparison is wrong for both.
+ *
+ * Anything out of scope gets a plain fetch rather than `checkAuthNeededFetch`:
+ * a 401 from a url the config never named should not raise a credential prompt
+ * for a host the server picked.
+ */
 export declare function getFetcher(location: FileLocation, pluginManager?: PluginManager): Fetcher;
-export { RemoteFileWithRangeCache } from './RemoteFileWithRangeCache.ts';
+export { CachedFilehandle, RemoteFileWithRangeCache, } from './RemoteFileWithRangeCache.ts';

package/esm/util/io/index.js

@@ -1,9 +1,8 @@
-import isNode from 'detect-node';
 import { BlobFile, LocalFile } from 'generic-filehandle2';
-import { RemoteFileWithRangeCache } from "./RemoteFileWithRangeCache.js";
-import { isElectron } from "../index.js";
-import { getBlob, getFileFromCache } from "../tracks.js";
-import { AuthNeededError, isRootModelWithInternetAccounts, isUriLocation, } from "../types/index.js";
+import { isElectron, isNode } from '../environment.js';
+import { getBlob, getFileFromCache } from '../tracks.js';
+import { AuthNeededError, isRootModelWithInternetAccounts, isUriLocation, } from '../types/index.js';
+import { CachedFilehandle, RemoteFileWithRangeCache, } from './RemoteFileWithRangeCache.js';
 function isLocalPathLocation(location) {
     return 'localPath' in location;
 }
@@ -13,71 +12,172 @@ function isBlobLocation(location) {
 function isFileHandleLocationLocal(location) {
     return 'handleId' in location;
 }
+/** if a UriLocation has a baseUri, resolves its uri with respect to that base */
 export function resolveUriLocation(location) {
     return location.baseUri
         ? { ...location, uri: new URL(location.uri, location.baseUri).href }
         : location;
 }
+/**
+ * The local path a `file:` URI names, or undefined for any other scheme. A
+ * Windows URL parses as `/C:/data/x.bam`, whose leading slash is part of the URL
+ * grammar rather than the path.
+ */
+function fileUrlToLocalPath(uri) {
+    if (!uri.startsWith('file:')) {
+        return undefined;
+    }
+    try {
+        const { pathname } = new URL(uri);
+        const decoded = decodeURIComponent(pathname);
+        return /^\/[a-z]:/i.test(decoded) ? decoded.slice(1) : decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function openLocation(location, pluginManager) {
     if (isLocalPathLocation(location)) {
         if (!location.localPath) {
             throw new Error('No local path provided');
         }
         if (isNode || isElectron) {
-            return new LocalFile(location.localPath);
+            // Same chunk cache the remote path has always had. A local read is not
+            // free — desktop re-read every byte of every pan — and the layer above
+            // does not care where the bytes came from.
+            return new CachedFilehandle(new LocalFile(location.localPath), `file://${location.localPath}`);
         }
         else {
             throw new Error("can't use local files in the browser");
         }
     }
     if (isBlobLocation(location)) {
+        // special case where blob is not directly stored on the model, use a getter
         const blob = getBlob(location.blobId);
         if (!blob) {
             throw new Error(`file ("${location.name}") was opened locally from a previous session. To restore it, go to track settings and reopen the file`);
         }
-        return new BlobFile(blob);
+        // keyed on the blobId rather than anything derived from the Blob: two
+        // handles for the same session-stored blob should share chunks, and two
+        // unrelated blobs must not
+        return new CachedFilehandle(new BlobFile(blob), `blob://${location.blobId}`);
     }
     if (isFileHandleLocationLocal(location)) {
+        // FileHandleLocation uses an in-memory cache of File objects
+        // The cache is populated asynchronously via ensureFileHandleReady
         const file = getFileFromCache(location.handleId);
         if (!file) {
             throw new Error(`file ("${location.name}") requires permission. Please reopen the file from track settings`);
         }
-        return new BlobFile(file);
+        return new CachedFilehandle(new BlobFile(file), `filehandle://${location.handleId}`);
     }
     if (isUriLocation(location)) {
+        // Check for empty string
         if (!location.uri) {
             throw new Error('No URI provided');
         }
+        // Resolve any relative URLs to absolute URLs. Before *choosing* the account
+        // and not only before opening: an account is matched on the location's host
+        // or URL prefix, which a uri relative to a baseUri does not carry yet — so
+        // a config that names its files relative to itself found no account at all
+        // and read every one of them unauthenticated.
         const absoluteLocation = resolveUriLocation(location);
+        // A file: URI names a path on this machine, not something to fetch. Desktop
+        // reaches this by way of the shorthand forms: a config.json opened from disk
+        // carries a baseUri of its own directory, so `{ type: 'BamAdapter', uri:
+        // 'reads.bam' }` resolves here as file:///dir/reads.bam — and so does every
+        // sibling the shorthand derived from it (.bai, .fai, .gzi). Reading them as
+        // localPath keeps that whole chain on the one code path that can open a
+        // local file, instead of a fetch that no range request survives.
+        const localPath = fileUrlToLocalPath(absoluteLocation.uri);
+        if (localPath !== undefined && (isNode || isElectron)) {
+            return openLocation({ localPath, locationType: 'LocalPathLocation' });
+        }
+        // If there is a plugin manager, we can try internet accounts
         if (pluginManager) {
-            const internetAccount = getInternetAccount(location, pluginManager);
+            const internetAccount = getInternetAccount(absoluteLocation, pluginManager);
+            // If an internetAccount was found, use it to open the location
             if (internetAccount) {
                 return internetAccount.openLocation(absoluteLocation);
             }
         }
+        // Otherwise fall back on usual open
         return new RemoteFileWithRangeCache(absoluteLocation.uri, {
             fetch: checkAuthNeededFetch,
         });
     }
     throw new Error('invalid fileLocation');
 }
+/**
+ * Open a tabix-style index (TBI or CSI) and return it under the correct
+ * filehandle key for `new TabixIndexedFile(...)`. Centralizes the CSI-vs-TBI
+ * branch so callers can't mismatch the two — e.g. writing `=== 'CSI'` on both
+ * the csi and tbi lines, which silently yields no index at all.
+ */
+export function openTabixIndexFilehandle(location, indexType, pluginManager) {
+    const filehandle = openLocation(location, pluginManager);
+    return indexType === 'CSI'
+        ? { csiFilehandle: filehandle }
+        : { tbiFilehandle: filehandle };
+}
+/**
+ * A fetch that presents `location`'s credentials — and only for urls that
+ * credential covers.
+ *
+ * An account's own fetcher signs whatever url it is handed: the location it was
+ * built from decides which token to mint, not where the token may go. That is
+ * fine for a caller holding one url, which is what `openLocation` is, and wrong
+ * for one that fetches urls a *server* names. Htsget is the second kind — a
+ * ticket request answers with data-block urls that can point anywhere — and it
+ * had no way to ask whether a given url was still in scope.
+ *
+ * So ask here. Every url other than the one the fetcher was requested for goes
+ * back through the account's `handlesLocation`, which is the same
+ * `uriMatchesDomains` test that chose the account in the first place. Both
+ * directions matter: `domains` entries scope to a path as well as a host
+ * (`data.mylab.org/private`, and the origin-plus-directory form every ephemeral
+ * HTTP Basic account is minted with), and one account routinely spans several
+ * hosts (Dropbox lists seven). An origin comparison is wrong for both.
+ *
+ * Anything out of scope gets a plain fetch rather than `checkAuthNeededFetch`:
+ * a 401 from a url the config never named should not raise a credential prompt
+ * for a host the server picked.
+ */
 export function getFetcher(location, pluginManager) {
     if (!isUriLocation(location)) {
         throw new Error(`Not a valid UriLocation: ${JSON.stringify(location)}`);
     }
     if (pluginManager) {
-        const internetAccount = getInternetAccount(location, pluginManager);
+        // resolved for the same reason openLocation resolves before matching
+        const absoluteLocation = resolveUriLocation(location);
+        const internetAccount = getInternetAccount(absoluteLocation, pluginManager);
         if (internetAccount) {
-            return internetAccount.getFetcher(location);
+            const authorized = internetAccount.getFetcher(absoluteLocation);
+            return (input, init) => {
+                const url = typeof input === 'string' ? input : input.url;
+                // The requested url passes on identity, so a location matched by
+                // something other than `domains` — the same-app-origin exception a
+                // relative uri needs — still authenticates the file it was resolved for
+                return url === absoluteLocation.uri ||
+                    internetAccount.handlesLocation({
+                        uri: url,
+                        locationType: 'UriLocation',
+                    })
+                    ? authorized(input, init)
+                    : fetch(input, init);
+            };
         }
     }
     return checkAuthNeededFetch;
 }
 function getInternetAccount(location, pluginManager) {
     const { rootModel } = pluginManager;
+    // If there is an appRootModel, use it to find the internetAccount
     if (rootModel && isRootModelWithInternetAccounts(rootModel)) {
         return rootModel.findAppropriateInternetAccount(location);
     }
+    // If there is no appRootModel, but there is pre-auth, create a temporary
+    // internetAccount. This is typical in a worker.
     if (location.internetAccountPreAuthorization) {
         if (!location.internetAccountPreAuthorization.authInfo.token) {
             throw new Error('Failed to obtain token from internet account. Try reloading the page');
@@ -91,6 +191,9 @@ function getInternetAccount(location, pluginManager) {
     }
     return undefined;
 }
+// This fetch throws a special error if the response is "401" and includes a
+// "WWW-Authenticate: Basic" header. This is so downstream code can retry if
+// needed with HTTP Basic authentication included
 async function checkAuthNeededFetch(url, opts) {
     const response = await fetch(url, opts);
     if (response.status === 401 &&
@@ -99,4 +202,4 @@ async function checkAuthNeededFetch(url, opts) {
     }
     return response;
 }
-export { RemoteFileWithRangeCache } from "./RemoteFileWithRangeCache.js";
+export { CachedFilehandle, RemoteFileWithRangeCache, } from './RemoteFileWithRangeCache.js';