@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/indexCandidates.d.ts

@@ -0,0 +1,20 @@
+import type { FileLocation } from './types/data.ts';
+export { indexCandidateNames, indexSpellings } from '@jbrowse/add-track-core';
+/**
+ * `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,43 @@
+import { indexCandidateNames } from '@jbrowse/add-track-core';
+import { getFileName } from './getFileName.js';
+// defined in `@jbrowse/add-track-core`, which is framework-free so `jbrowse-cli`
+// reads the same list; re-exported because this subpath serves them to plugins
+export { indexCandidateNames, indexSpellings } from '@jbrowse/add-track-core';
+/**
+ * `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,234 @@
+import type { ActiveFetch, StatusReporter, AbortRotation } from './createAbortRotation.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 `activeSignal`,
+     * through `fetchMixinLifecycle`), and anything a display blanks
+     * because it has no freshness signature to keep stale data honest with
+     * (chord's refName map).
+     *
+     * Takes the signal rather than the whole {@link ActiveFetch}: publishing it is
+     * the only thing any implementation does with the fetch, and the guard and
+     * the status slot are the skeleton's to hand out — through `ctx`, where a
+     * `run` gets them pre-wired.
+     */
+    onBegin?: (signal: AbortSignal) => 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 createAbortRotation} `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
+     * retry contract 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;
+}
+interface InstallFetchOptionsBase<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;
+    /**
+     * 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 `loadedFetchKey` 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.
+     *
+     * A value, compared by `isDataCurrent`: the settings a fetch was issued
+     * under go in as the object the worker receives, never as a serialized
+     * spelling of it.
+     */
+    fetchKey?: (args: TArgs) => unknown;
+    /**
+     * The key of the data already committed, when the host keeps one —
+     * `KeyedFetchMixin` stamps `loadedFetchKey`, which its `dataCurrent` 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.
+     */
+    loadedKey?: () => unknown;
+    /**
+     * The predicate form of the freshness gate, for a fetch whose "I have exactly
+     * this already" is not key equality: the density tier holds bins over a
+     * buffered read and answers a viewport those bins *contain*, which no key can
+     * spell. Same rules as `fetchKey` — declined runs report `declined`, and a
+     * `reloadCounter` advanced since the last issued fetch overrides it — so the
+     * comparison lives here and not in `prepare`, where a reload could not reach
+     * it. Runs inside the autorun, so what it reads is tracked: read the
+     * committed state off an observable, and the commit that changes the answer
+     * wakes the declined run.
+     *
+     * Either this or `fetchKey`, not both.
+     */
+    heldAnswers?: (args: TArgs) => boolean;
+    /**
+     * Install the two 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;
+}
+/**
+ * The rotation half is either/or: `report` says where a rotation this installer
+ * creates for itself reports, and `rotation` lends the host's own instead — a
+ * display composing `FetchMixin` passes its `fetchRotation`, so `cancelFetch`
+ * and `cancelFetchByUser` reach the fetch this installs rather than a second
+ * rotation they cannot see. A lent rotation already carries its status window,
+ * so `report` would be dead beside it — the same either/or `StatusReporter`
+ * itself is a union for.
+ */
+export type InstallFetchOptions<TArgs, TResult> = InstallFetchOptionsBase<TArgs, TResult> & ({
+    /**
+     * 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;
+    rotation?: never;
+} | {
+    /** the host's own latest-wins rotation, lent whole — see above */
+    rotation: AbortRotation;
+    report?: never;
+});
+/**
+ * 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 family — the prerequisite
+ * reads (HiC's header, the multi-sample sample list), the two keyed families
+ * (`installGlobalFetchAutorun` and `installComparativeFetchAutorun`, which lend
+ * `FetchMixin`'s rotation through the `rotation` option so `cancelFetch` and
+ * the Cancel button reach the fetch they install), 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 the per-region family's `FetchMixin.runFetch`: its trigger is
+ * `planRegionFetch`'s autorun and its commits stream per region through
+ * `ctx.commitRegion`, 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`).
+ */
+export declare function installFetch<TArgs, TResult>(self: FetchSkeletonHost, opts: InstallFetchOptions<TArgs, TResult>): void;
+export {};

package/esm/util/installFetch.js

@@ -0,0 +1,205 @@
+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 { createAbortRotation } from './createAbortRotation.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 createAbortRotation} `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 { signal, isCurrent, statusCallback, end } = active;
+    // synchronous, so it lands while this run is by construction the current one
+    setError(undefined);
+    onBegin?.(signal);
+    try {
+        const result = await run(args, makeFetchContext(self, {
+            signal,
+            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 aborted the
+        // signal, 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
+        end();
+    }
+}
+/**
+ * The two contract 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);
+}
+/**
+ * The rotation for an installation that was lent none: created here, so
+ * disposed here — a lent one is the host's, and resetting its status window
+ * would drop a write the host's other operations are still owed.
+ */
+function ownRotation(self, report) {
+    const rotation = createAbortRotation(self, report);
+    addDisposer(self, () => {
+        rotation.dispose();
+    });
+    return rotation;
+}
+/**
+ * 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 family — the prerequisite
+ * reads (HiC's header, the multi-sample sample list), the two keyed families
+ * (`installGlobalFetchAutorun` and `installComparativeFetchAutorun`, which lend
+ * `FetchMixin`'s rotation through the `rotation` option so `cancelFetch` and
+ * the Cancel button reach the fetch they install), 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 the per-region family's `FetchMixin.runFetch`: its trigger is
+ * `planRegionFetch`'s autorun and its commits stream per region through
+ * `ctx.commitRegion`, 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`).
+ */
+export function installFetch(self, opts) {
+    const { name, delay, gate, contract, fetchKey, loadedKey, heldAnswers, prepare, run, commit, setError, onBegin, onEnd, } = opts;
+    const noteFetchAutorunRun = contract === undefined ? undefined : installContractChecks(self, contract);
+    const lent = opts.rotation;
+    const rotation = lent === undefined ? ownRotation(self, opts.report) : lent;
+    // 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;
+    // The skeleton's own stamp exists only where there is a key to stamp — a
+    // fetch with no `fetchKey` never reads it, so allocating one would only feed
+    // it `undefined` on every commit. Shallow, because the deep enhancer would
+    // swap a stamped key object for an observable copy of it.
+    const stamp = loadedKey === undefined && fetchKey !== undefined
+        ? observable.box(undefined, { deep: false })
+        : undefined;
+    const heldKey = loadedKey ?? (() => stamp?.get());
+    // the freshness gate in whichever form the caller declared it
+    const held = heldAnswers !== undefined
+        ? heldAnswers
+        : fetchKey !== undefined
+            ? (args) => isDataCurrent(heldKey(), fetchKey(args))
+            : undefined;
+    const commitAndStamp = stamp
+        ? (result, args) => {
+            runInAction(() => {
+                commit(result, args);
+                stamp.set(fetchKey?.(args));
+            });
+        }
+        : commit;
+    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;
+        // Above the gate, not only above `prepare`: teardown mutates the
+        // observables this body reads before the disposers run, and every `gate`
+        // but the breakpoint view's reaches the containing view or track through a
+        // parent walk (`host.initialized`, `isMinimized`, `getContainingView`),
+        // which throws once the node has left the tree. This catches the destroyed
+        // node; the detached-and-still-alive window (ADR-069) is covered only by
+        // the walk's own cache. Nothing is reported for a dead node — there is no
+        // Retry button left to be dead, and the check would read three more
+        // members of a corpse to decide it.
+        if (!isAlive(self)) {
+            return false;
+        }
+        if (canceled || gate?.() === false) {
+            noteFetchAutorunRun?.('gated');
+            return false;
+        }
+        const args = prepare();
+        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 (held !== undefined && held(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 });
+}

package/esm/util/installInitAutorun.d.ts

@@ -0,0 +1,63 @@
+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 line `withLaunchInput`'s
+     * `materialized` draws for persistence, read from the live node (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 `withLaunchInput`
+ * 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 {};