@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/indexCandidates.d.ts

@@ -0,0 +1,50 @@
+import type { FileLocation } from './types/data.ts';
+/**
+ * Every conventional spelling of an index file, for the docs that describe this
+ * behavior. Kept beside {@link indexCandidateNames}, which is the list actually
+ * probed, so the two are edited together.
+ */
+export declare const indexSpellings: {
+    name: string;
+    writtenBy: string;
+}[];
+/**
+ * The index filenames worth looking for beside `fileName`, best guess first.
+ *
+ * One data file has several names its index might carry, and picking only the
+ * first left everyone else with a missing-file error naming a path they never
+ * wrote:
+ *
+ * - `<file>.bai` / `.crai` / `.tbi` is what samtools and tabix write
+ * - `<file>.csi` is what htslib writes for a reference over 512 Mb, and on
+ *   request at any size
+ * - `reads.bai` beside `reads.bam` is what Picard and GATK write, in place of
+ *   samtools' `reads.bam.bai`
+ *
+ * Empty for a file type that carries no sibling index (BigWig, BigBed, hic),
+ * which is how a caller knows not to go looking.
+ *
+ * `jbrowse-cli` answers the same question in `siblingSidecar`
+ * (`commands/add-track-utils/adapter-utils.ts`) rather than calling this: it
+ * carries no `@jbrowse/core` dependency, so `npm i -g @jbrowse/cli` stays a CLI
+ * rather than a copy of the app. Change one, change the other.
+ */
+export declare function indexCandidateNames(fileName: string): string[];
+/**
+ * `location` with its filename replaced, i.e. the sibling of a data file.
+ *
+ * Only a URI and a local path have a sibling at all. A Blob or a FileHandle is
+ * whatever the user picked out of a file dialog and there is no directory
+ * around it to look in, so those get `undefined` — the honest answer, and the
+ * reason index detection cannot work from a browser file picker.
+ */
+export declare function siblingLocation(location: FileLocation, fileName: string): FileLocation | undefined;
+/**
+ * The index sitting beside `location`, or undefined when none of the
+ * conventional spellings is there.
+ *
+ * `exists` is injected rather than reached for, because what "exists" costs is
+ * the caller's business and differs by host: a local path is a stat, a URL is a
+ * request, and a Blob cannot be asked at all.
+ */
+export declare function detectIndexLocation(location: FileLocation, exists: (location: FileLocation) => Promise<boolean>): Promise<FileLocation | undefined>;

package/esm/util/indexCandidates.js

@@ -0,0 +1,101 @@
+import { getFileName } from './getFileName.js';
+/**
+ * Every conventional spelling of an index file, for the docs that describe this
+ * behavior. Kept beside {@link indexCandidateNames}, which is the list actually
+ * probed, so the two are edited together.
+ */
+export const indexSpellings = [
+    {
+        name: '`<file>.tbi`, `<file>.bai`, `<file>.crai`',
+        writtenBy: 'samtools, tabix',
+    },
+    {
+        name: '`<file>.csi`',
+        writtenBy: 'htslib, for a reference over 512 Mb and on request at any size',
+    },
+    {
+        name: '`reads.bai` beside `reads.bam`',
+        writtenBy: 'Picard, GATK',
+    },
+];
+/**
+ * The index filenames worth looking for beside `fileName`, best guess first.
+ *
+ * One data file has several names its index might carry, and picking only the
+ * first left everyone else with a missing-file error naming a path they never
+ * wrote:
+ *
+ * - `<file>.bai` / `.crai` / `.tbi` is what samtools and tabix write
+ * - `<file>.csi` is what htslib writes for a reference over 512 Mb, and on
+ *   request at any size
+ * - `reads.bai` beside `reads.bam` is what Picard and GATK write, in place of
+ *   samtools' `reads.bam.bai`
+ *
+ * Empty for a file type that carries no sibling index (BigWig, BigBed, hic),
+ * which is how a caller knows not to go looking.
+ *
+ * `jbrowse-cli` answers the same question in `siblingSidecar`
+ * (`commands/add-track-utils/adapter-utils.ts`) rather than calling this: it
+ * carries no `@jbrowse/core` dependency, so `npm i -g @jbrowse/cli` stays a CLI
+ * rather than a copy of the app. Change one, change the other.
+ */
+export function indexCandidateNames(fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith('.bam')) {
+        return [
+            `${fileName}.bai`,
+            `${fileName}.csi`,
+            fileName.replace(/\.bam$/i, '.bai'),
+        ];
+    }
+    if (lower.endsWith('.cram')) {
+        return [`${fileName}.crai`, fileName.replace(/\.cram$/i, '.crai')];
+    }
+    // the tabix family is spelled by its compression, not its content: a .gz here
+    // is a bgzipped VCF/GFF/BED/SAM, all of which index the same two ways. `.bgz`
+    // is the same file under the name htslib's own tools give it, so it takes the
+    // same candidates — every format guesser accepts `\.b?gz$`, and matching only
+    // `.gz` left a `calls.vcf.bgz` with no detection at all
+    if (/\.b?gz$/.test(lower)) {
+        return [`${fileName}.tbi`, `${fileName}.csi`];
+    }
+    return [];
+}
+/**
+ * `location` with its filename replaced, i.e. the sibling of a data file.
+ *
+ * Only a URI and a local path have a sibling at all. A Blob or a FileHandle is
+ * whatever the user picked out of a file dialog and there is no directory
+ * around it to look in, so those get `undefined` — the honest answer, and the
+ * reason index detection cannot work from a browser file picker.
+ */
+export function siblingLocation(location, fileName) {
+    const replaceLast = (path) => 
+    // the separator is kept: a Windows local path uses backslashes and a URI
+    // never does, so rebuilding with '/' would corrupt one of them
+    path.replace(/[^/\\]*$/, fileName);
+    if (location.locationType === 'UriLocation') {
+        return { ...location, uri: replaceLast(location.uri) };
+    }
+    if (location.locationType === 'LocalPathLocation') {
+        return { ...location, localPath: replaceLast(location.localPath) };
+    }
+    return undefined;
+}
+/**
+ * The index sitting beside `location`, or undefined when none of the
+ * conventional spellings is there.
+ *
+ * `exists` is injected rather than reached for, because what "exists" costs is
+ * the caller's business and differs by host: a local path is a stat, a URL is a
+ * request, and a Blob cannot be asked at all.
+ */
+export async function detectIndexLocation(location, exists) {
+    for (const name of indexCandidateNames(getFileName(location))) {
+        const candidate = siblingLocation(location, name);
+        if (candidate && (await exists(candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}

package/esm/util/installClearHoverOnSurfaceMove.d.ts

@@ -0,0 +1,40 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Drop a shared surface's stored hover whenever the content moves under a
+ * stationary cursor.
+ *
+ * A stored hover is only as good as its invalidation, and the pointer handlers
+ * answer one axis of it: the pointer moving. The other axis is the content
+ * moving instead, which fires no pointer event at all — a wheel zoom, a drag
+ * pan, a locstring navigation, a plot resize. Left uncleared, the hover goes on
+ * naming the feature the cursor *used* to be over, which is exactly what the
+ * tooltip renders and the highlight outlines.
+ *
+ * `transform` is the one value carrying every number that moves the picture —
+ * synteny's `bandTransformKey`, dotplot's `plotTransform`, the breakpoint split
+ * view's `overlayTransformKey`. Watching that value instead of listing entry
+ * points is the design: the wheel was the entry point nobody had written a
+ * clear for. Each caller documents beside its transform getter what the key
+ * covers.
+ *
+ * `clear` rather than a duck-typed action name, because the three owners store
+ * three different things: a synteny pick hit, a dotplot feature index, an
+ * overlay curve id. The omission the per-display installer guards against
+ * (`installClearHoverOnViewportChange`, which a mixin installs on six displays'
+ * behalf) cannot happen here — a surface owner writes this call itself, and the
+ * clear is the line above it.
+ *
+ * A `reaction`, not an `autorun`: the effect writes the hover, and an autorun
+ * body that both read and wrote it would re-fire itself.
+ *
+ * The LGV family answers the same question through
+ * `installClearHoverOnViewportChange`, which its fetch foundation installs for
+ * every per-region display; a view that owns a canvas or an overlay spanning
+ * several of them has no such foundation, so it installs this one. A new
+ * shared-surface container owes the same call (SHARED_CANVAS_VIEWS.md).
+ */
+export declare function installClearHoverOnSurfaceMove(self: IStateTreeNode, opts: {
+    transform: () => unknown;
+    clear: () => void;
+    name: string;
+}): void;

package/esm/util/installClearHoverOnSurfaceMove.js

@@ -0,0 +1,41 @@
+import { addDisposer } from '@jbrowse/mobx-state-tree';
+import { reaction } from 'mobx';
+/**
+ * Drop a shared surface's stored hover whenever the content moves under a
+ * stationary cursor.
+ *
+ * A stored hover is only as good as its invalidation, and the pointer handlers
+ * answer one axis of it: the pointer moving. The other axis is the content
+ * moving instead, which fires no pointer event at all — a wheel zoom, a drag
+ * pan, a locstring navigation, a plot resize. Left uncleared, the hover goes on
+ * naming the feature the cursor *used* to be over, which is exactly what the
+ * tooltip renders and the highlight outlines.
+ *
+ * `transform` is the one value carrying every number that moves the picture —
+ * synteny's `bandTransformKey`, dotplot's `plotTransform`, the breakpoint split
+ * view's `overlayTransformKey`. Watching that value instead of listing entry
+ * points is the design: the wheel was the entry point nobody had written a
+ * clear for. Each caller documents beside its transform getter what the key
+ * covers.
+ *
+ * `clear` rather than a duck-typed action name, because the three owners store
+ * three different things: a synteny pick hit, a dotplot feature index, an
+ * overlay curve id. The omission the per-display installer guards against
+ * (`installClearHoverOnViewportChange`, which a mixin installs on six displays'
+ * behalf) cannot happen here — a surface owner writes this call itself, and the
+ * clear is the line above it.
+ *
+ * A `reaction`, not an `autorun`: the effect writes the hover, and an autorun
+ * body that both read and wrote it would re-fire itself.
+ *
+ * The LGV family answers the same question through
+ * `installClearHoverOnViewportChange`, which its fetch foundation installs for
+ * every per-region display; a view that owns a canvas or an overlay spanning
+ * several of them has no such foundation, so it installs this one. A new
+ * shared-surface container owes the same call (SHARED_CANVAS_VIEWS.md).
+ */
+export function installClearHoverOnSurfaceMove(self, opts) {
+    addDisposer(self, reaction(opts.transform, () => {
+        opts.clear();
+    }, { name: opts.name }));
+}

package/esm/util/installFetch.d.ts

@@ -0,0 +1,194 @@
+import type { ActiveFetch, StatusReporter } from './createStopTokenRotation.ts';
+import type { FetchContext } from './fetchContext.ts';
+import type { FetchPhases } from './fetchPhases.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * The bookkeeping a family hangs off one fetch, beside the phases. Each of the
+ * five fetches in the tree fills a different subset, and that subset is the
+ * only thing about them that genuinely differs.
+ */
+export interface FetchLifecycle {
+    /**
+     * Where the fetch's error lands, and the **clear-at-start rule** in the same
+     * parameter: it is called with `undefined` the moment a run begins, so a
+     * banner from a failed attempt cannot stand over the result a retriggered
+     * run commits — a fetch re-fires on reads that never pass through `reload()`'s
+     * own clear (an adapter edit, an un-minimize, a pan). One function rather
+     * than a clear plus an `onError`, because a caller given two can supply one.
+     *
+     * A host with no error state of its own answers only the failure (the
+     * breakpoint overlay raises a session notification), which is why the
+     * argument is optional rather than the call being conditional.
+     */
+    setError: (error?: unknown) => void;
+    /**
+     * Runs synchronously as the fetch starts, after the rotation has superseded
+     * whatever it replaced: the loading flag (`FetchMixin`'s `activeStopToken`,
+     * the comparative family's `fetching`), and anything a display blanks
+     * because it has no freshness signature to keep stale data honest with
+     * (chord's refName map).
+     */
+    onBegin?: (active: ActiveFetch) => void;
+    /**
+     * Runs in the `finally`, before the rotation's `end()`. `current` is this
+     * run's own guard, already evaluated: a **superseded** run must not clear the
+     * loading flag the run that replaced it just set, and it is the only exit
+     * that reaches here without having gone through either the commit or the
+     * error path.
+     */
+    onEnd?: (current: boolean) => void;
+}
+/**
+ * One fetch, once: **begin → clear the error → run → commit if still current →
+ * {@link handleFetchError} → end**.
+ *
+ * That sequence was written five times — `FetchMixin.runFetch`, the
+ * prerequisite skeleton, the comparative installer, the circular view's chord
+ * fetch and the breakpoint split view's overlay fetch — and each copy was
+ * missing a different rule: no rotation at all, an error publish guarded on
+ * liveness but not currency, no clear at the start, a `finally` that stranded
+ * the loading flag on an abort. The rules only pay for themselves by being the
+ * same everywhere, so they live here and the differences are parameters.
+ *
+ * `active` comes from a {@link createStopTokenRotation} `begin()` the caller
+ * already made, because who owns the rotation is one of the real differences: a
+ * display's *primary* fetch rotates through `FetchMixin`, so `cancelFetch` can
+ * reach it, while every other fetch's rotation lives in its installer's closure
+ * ({@link installFetch}).
+ *
+ * **Called synchronously by every caller**, so its own prefix down to the first
+ * `await` — and `run`'s prefix with it — executes wherever the caller was.
+ * `installFetch` puts that inside `untracked`; `FetchMixin.runFetch` is an MST
+ * flow, and so an action, which MobX runs untracked already.
+ */
+export declare function runFetchOnce<TArgs, TResult>(self: IStateTreeNode, active: ActiveFetch, args: TArgs, { run, commit, setError, onBegin, onEnd, }: Pick<FetchPhases<TArgs, TResult, FetchContext>, 'run' | 'commit'> & FetchLifecycle): Promise<void>;
+/**
+ * The host members {@link installFetch}'s autorun body reads for itself, above
+ * everything the family supplies.
+ *
+ * `IStateTreeNode`, never `IAnyStateTreeNode` — the latter resolves to `any`
+ * and silently turns off checking for every member below.
+ */
+export interface FetchSkeletonHost extends IStateTreeNode {
+    /**
+     * The pure "go again" signal, read unconditionally above every gate. After a
+     * failure every other fetch input is unchanged, so nothing but this can
+     * rewake the body — and a read placed under a gate drops out of the
+     * dependency set on the run that declines, which is a Retry button that
+     * works until the first time it is needed.
+     */
+    reloadCounter: number;
+    /**
+     * The states where this host deliberately fetches nothing, read only by the
+     * dev-only retry check. A decline there is not a dead Retry.
+     */
+    fetchInert: boolean;
+    /**
+     * A standing user cancel, and the one durability rule for all of them: **a
+     * cancel is durable — no fetch trigger un-cancels it.** Read tracked, under
+     * `reloadCounter` and above every other gate, so the gesture that reopens it
+     * (Retry, or the LGV foundations' clear-on-viewport-change) is in the
+     * dependency set of the run it closed.
+     *
+     * Optional because a host with no cancel affordance has no cancel to be
+     * durable — the circular view's chord fetch and the breakpoint overlay fetch
+     * offer no Cancel button, so they declare nothing rather than a constant
+     * `false`.
+     */
+    fetchCanceled?: boolean;
+}
+export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs, TResult, FetchContext>, FetchLifecycle {
+    /** autorun name, for the MobX devtools/spy stream */
+    name: string;
+    /** how long to coalesce reruns once the body has started work once */
+    delay: number;
+    /**
+     * Where this fetch's status lands. A display passes itself — its status
+     * fields are part of its own API, and one composing `FetchMixin` lends the
+     * model-wide window so this fetch takes a slot on the one field beside the
+     * display's other operations rather than opening a second writer over it.
+     * Anything with one operation to narrate passes a `createStatusChannel`.
+     */
+    report: StatusReporter;
+    /**
+     * An extra skip above `prepare`, reported as `gated` rather than `declined`:
+     * the skeleton decided before the family's own gate was consulted, so it is
+     * not the dead Retry the contract check hunts for. Must be a *tracked* read
+     * that flips on the transition to wake on — a minimized track, a view that
+     * is not initialized.
+     */
+    gate?: () => boolean;
+    /**
+     * The freshness signature of a run's args — the freshness gate, declared here
+     * rather than folded into `prepare` because **the skeleton owns the half of it
+     * that keeps being got wrong.**
+     *
+     * A run whose key equals the committed one declines, so a gate flip
+     * (minimize→expand, a view initializing) re-runs nothing against unchanged
+     * inputs. The law is ARCHITECTURE.md's: a gate on a freshness signal must
+     * also be invalidated by `reload()`, or Retry re-runs the body straight into
+     * the same decline and the button is dead. Every layer that has one made
+     * that pairing structural in the end — the global family after arc shipped
+     * the bug (`GlobalFetchMixin.reload` drops `loadedFetchSignature` in the same
+     * action as the bump) — and this is that move for the skeleton: a run whose
+     * `reloadCounter` has advanced since the run that last ISSUED a fetch ignores
+     * this gate, so nothing has to remember to clear anything. The multi-way
+     * synteny display's two dependent fetches shipped the same dead Retry from
+     * spelling the comparison in `prepare` with no override to match, which is
+     * what this exists to make unspellable.
+     *
+     * Separate from `prepare` because they answer different questions and only one
+     * of them can strand a display: `prepare` returning `undefined` is "nothing to
+     * fetch" (an empty viewport, no gene track configured), which is a legitimate
+     * decline forever and no amount of retrying should change it. This is "I have
+     * exactly this already", which a retry must be able to override.
+     *
+     * Omit it where the fetch holds no committed state to compare against — most
+     * of them, whose `prepare` returns args unconditionally.
+     */
+    fetchKey?: (args: TArgs) => string;
+    /**
+     * The key of the data already committed, when the host keeps one — the
+     * comparative displays stamp `loadedFetchKey`, which their `dataCurrent`
+     * flag reads too, so a second stamp would be one more thing to disagree with
+     * it. Omitted, the skeleton stamps its own at commit.
+     *
+     * **Either way the stamp is observable**, and the read is tracked. Zoom A→B
+     * issues a fetch for B; zoom back to A before B commits and the re-run
+     * declines against the still-A stamp; B then commits and stamps B, and that
+     * write is what wakes the autorun to fetch A again. A closure variable would
+     * leave data B under viewport A until the next input moved.
+     */
+    committedKey?: () => string | undefined;
+    /**
+     * Install the two dev-only display-contract checks under this name. Omitted
+     * by a **secondary** fetch on a host whose primary foundation already
+     * installed them: `assertDisplayContract` would report the second install as
+     * the double-attach it is built to catch, and a second retry check would
+     * consume the same `reloadCounter` bumps as the first.
+     */
+    contract?: string;
+}
+/**
+ * A whole fetch, installed: the rotation, the leading-edge autorun, the
+ * unconditional trigger reads, the gates, and {@link runFetchOnce} under them.
+ *
+ * Every fetch in the tree is this shape except one — the prerequisite reads
+ * (HiC's header, the multi-sample sample list), both comparative displays, the
+ * circular view's chord fetch, the breakpoint overlay fetch and the multi-way
+ * synteny display's two DEPENDENT fetches (lane genes, lane links, each gated on
+ * the key its own commit stamps) all take it. The
+ * exception is `FetchMixin.runFetch`, the viewport fetch of an LGV display: its
+ * rotation is a member rather than a closure (so `cancelFetch` can reach it)
+ * and its trigger list is the per-region or global foundation's, so it holds
+ * `runFetchOnce` directly and the autorun above it is that foundation's.
+ *
+ * What a caller supplies is exactly what differs between them: which reads wake
+ * it (`prepare`, plus `gate`), what a round trip commits, where the loading
+ * flag lives (`onBegin` / `onEnd`) and where the status goes (`report`).
+ *
+ * Returns the rotation's `cancel`, for a family whose model owns the user-facing
+ * Cancel button: the flag alone is not a cancel — nothing rotates the token, the
+ * stopped RPC stays current, and it commits over the load the user just stopped.
+ */
+export declare function installFetch<TArgs, TResult>(self: FetchSkeletonHost, { name, delay, report, gate, contract, fetchKey, committedKey, prepare, run, commit, setError, onBegin, onEnd, }: InstallFetchOptions<TArgs, TResult>): () => void;

package/esm/util/installFetch.js

@@ -0,0 +1,178 @@
+import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
+import { observable, runInAction, untracked } from 'mobx';
+import { assertDisplayContract, makeRetryContractCheck, } from '../pluggableElementTypes/models/assertDisplayContract.js';
+import { handleFetchError } from './aborting.js';
+import { createStopTokenRotation } from './createStopTokenRotation.js';
+import { makeFetchContext } from './fetchContext.js';
+import { isDataCurrent } from './isDataCurrent.js';
+import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
+/**
+ * One fetch, once: **begin → clear the error → run → commit if still current →
+ * {@link handleFetchError} → end**.
+ *
+ * That sequence was written five times — `FetchMixin.runFetch`, the
+ * prerequisite skeleton, the comparative installer, the circular view's chord
+ * fetch and the breakpoint split view's overlay fetch — and each copy was
+ * missing a different rule: no rotation at all, an error publish guarded on
+ * liveness but not currency, no clear at the start, a `finally` that stranded
+ * the loading flag on an abort. The rules only pay for themselves by being the
+ * same everywhere, so they live here and the differences are parameters.
+ *
+ * `active` comes from a {@link createStopTokenRotation} `begin()` the caller
+ * already made, because who owns the rotation is one of the real differences: a
+ * display's *primary* fetch rotates through `FetchMixin`, so `cancelFetch` can
+ * reach it, while every other fetch's rotation lives in its installer's closure
+ * ({@link installFetch}).
+ *
+ * **Called synchronously by every caller**, so its own prefix down to the first
+ * `await` — and `run`'s prefix with it — executes wherever the caller was.
+ * `installFetch` puts that inside `untracked`; `FetchMixin.runFetch` is an MST
+ * flow, and so an action, which MobX runs untracked already.
+ */
+export async function runFetchOnce(self, active, args, { run, commit, setError, onBegin, onEnd, }) {
+    const { stopToken, isCurrent, statusCallback, end } = active;
+    // synchronous, so it lands while this run is by construction the current one
+    setError(undefined);
+    onBegin?.(active);
+    try {
+        const result = await run(args, makeFetchContext(self, {
+            stopToken,
+            isStale: () => !isCurrent(),
+            statusCallback,
+        }));
+        // `undefined` is "nothing to commit" — a pre-flight that stopped this
+        // fetch — so it is not a result to record
+        if (result !== undefined && isCurrent()) {
+            commit(result, args);
+        }
+    }
+    catch (e) {
+        handleFetchError(e, isCurrent, setError);
+    }
+    finally {
+        // Both `onEnd` implementations are MST actions on `self`, and a display
+        // destroyed mid-fetch — a track closed, a display type switched out from
+        // under a load — still resumes here. `beforeDestroy` already stopped the
+        // token, so the bookkeeping is moot on a dead node; calling the action
+        // anyway only warns.
+        if (isAlive(self)) {
+            onEnd?.(isCurrent());
+        }
+        // last, because it closes the guard `onEnd` reads, and unconditional
+        // because a superseded run's status slot goes on voting for a phase that
+        // is over until it is retired
+        end();
+    }
+}
+/**
+ * The two dev-only checks every fetch installer owes, together because they are
+ * the same doctrine: one reports a foundation attached twice, the other reports
+ * a `reload()` the gate still declines — the dead Retry button.
+ */
+function installContractChecks(self, contract) {
+    assertDisplayContract(self, contract);
+    return makeRetryContractCheck(self);
+}
+/**
+ * A whole fetch, installed: the rotation, the leading-edge autorun, the
+ * unconditional trigger reads, the gates, and {@link runFetchOnce} under them.
+ *
+ * Every fetch in the tree is this shape except one — the prerequisite reads
+ * (HiC's header, the multi-sample sample list), both comparative displays, the
+ * circular view's chord fetch, the breakpoint overlay fetch and the multi-way
+ * synteny display's two DEPENDENT fetches (lane genes, lane links, each gated on
+ * the key its own commit stamps) all take it. The
+ * exception is `FetchMixin.runFetch`, the viewport fetch of an LGV display: its
+ * rotation is a member rather than a closure (so `cancelFetch` can reach it)
+ * and its trigger list is the per-region or global foundation's, so it holds
+ * `runFetchOnce` directly and the autorun above it is that foundation's.
+ *
+ * What a caller supplies is exactly what differs between them: which reads wake
+ * it (`prepare`, plus `gate`), what a round trip commits, where the loading
+ * flag lives (`onBegin` / `onEnd`) and where the status goes (`report`).
+ *
+ * Returns the rotation's `cancel`, for a family whose model owns the user-facing
+ * Cancel button: the flag alone is not a cancel — nothing rotates the token, the
+ * stopped RPC stays current, and it commits over the load the user just stopped.
+ */
+export function installFetch(self, { name, delay, report, gate, contract, fetchKey, committedKey, prepare, run, commit, setError, onBegin, onEnd, }) {
+    const noteFetchAutorunRun = contract === undefined ? undefined : installContractChecks(self, contract);
+    const rotation = createStopTokenRotation(self, report);
+    // The `reloadCounter` this installation last issued a fetch at. Per
+    // installation and per instance, so a host with several fetches gives each its
+    // own — and a closure rather than model state, because nothing outside reads
+    // it and a volatile would be one more thing a host has to declare.
+    let issuedEpoch;
+    const stamp = committedKey ? undefined : observable.box();
+    const heldKey = committedKey ?? (() => stamp.get());
+    const commitAndStamp = stamp
+        ? (result, args) => {
+            runInAction(() => {
+                commit(result, args);
+                stamp.set(fetchKey?.(args));
+            });
+        }
+        : commit;
+    addDisposer(self, () => {
+        rotation.dispose();
+    });
+    leadingEdgeAutorun(self, 
+    // #region voidTracking
+    () => {
+        // the pure "go again" signal, read unconditionally above every gate so a
+        // Retry click re-runs the body even when nothing else moved
+        const reloadEpoch = self.reloadCounter;
+        // Tracked in the same breath and for the same reason, but the mirror
+        // image: this one CLOSES the gate below, so a run that returned before
+        // the counter read would drop the one observable that can reopen it and
+        // Cancel would be a one-way door with a Retry button on it. Order, not
+        // just position: counter first, then this, then the gates.
+        const canceled = self.fetchCanceled === true;
+        if (canceled || gate?.() === false) {
+            noteFetchAutorunRun?.('gated');
+            return false;
+        }
+        // Teardown mutates observables `prepare` reads before the disposers run,
+        // and getContainingView on a detached node warns then throws.
+        const args = isAlive(self) ? prepare() : undefined;
+        if (args === undefined) {
+            noteFetchAutorunRun?.('declined');
+            return false;
+        }
+        // The freshness gate, and the reload that overrides it. The epoch is
+        // stamped at ISSUE where the key is stamped at commit: a fetch that fails
+        // leaves nothing current, so this gate is open anyway on the next run and
+        // consuming the retry here costs nothing — while a reload landing
+        // mid-flight is answered by the re-run the counter read above already
+        // guarantees.
+        if (fetchKey !== undefined &&
+            isDataCurrent(heldKey(), fetchKey(args)) &&
+            reloadEpoch === issuedEpoch) {
+            noteFetchAutorunRun?.('declined');
+            return false;
+        }
+        issuedEpoch = reloadEpoch;
+        noteFetchAutorunRun?.('fetched');
+        // `run` is called synchronously, so its prefix down to its first await
+        // executes in this derivation; `FetchPhases.run` promises those reads are
+        // untracked, and unlike the MST flow the LGV side hides behind, nothing
+        // here makes it so. Whatever the run needs tracked belongs in `prepare`.
+        // eslint-disable-next-line no-restricted-syntax -- effect input: run's prefix reads are the fetch's, prepare is the trigger list
+        untracked(() => {
+            void runFetchOnce(self, rotation.begin(), args, {
+                run,
+                commit: commitAndStamp,
+                setError,
+                onBegin,
+                onEnd,
+            });
+        });
+        // arms the debounce; the runs that bail above return false and stay on
+        // the leading edge, so the first real fetch is immediate while a
+        // zoom/pan refetch debounces
+        return true;
+    }, 
+    // #endregion
+    { name, delay });
+    return rotation.cancel;
+}

package/esm/util/installInitAutorun.d.ts

@@ -0,0 +1,62 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+interface InitAutorunHost<T> extends IStateTreeNode {
+    init?: T;
+    setInit: (init?: 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 `setInit` 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 init state machine shared by the views that take a declarative `init`
+ * 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 `init` 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 `init` 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 init.
+ *
+ * `apply` therefore never clears `init` 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 {};