@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/installFetch.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveFetch, StatusReporter } from './createStopTokenRotation.ts';
+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';
@@ -23,12 +23,17 @@ export interface FetchLifecycle {
     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
+     * 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?: (active: ActiveFetch) => void;
+    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
@@ -50,7 +55,7 @@ export interface FetchLifecycle {
  * 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
+ * `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
@@ -80,7 +85,7 @@ export interface FetchSkeletonHost extends IStateTreeNode {
     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.
+     * retry contract check. A decline there is not a dead Retry.
      */
     fetchInert: boolean;
     /**
@@ -97,19 +102,11 @@ export interface FetchSkeletonHost extends IStateTreeNode {
      */
     fetchCanceled?: boolean;
 }
-export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs, TResult, FetchContext>, FetchLifecycle {
+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;
-    /**
-     * 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
@@ -129,7 +126,7 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
      * 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
+     * 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
@@ -145,13 +142,17 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
      *
      * 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) => string;
+    fetchKey?: (args: TArgs) => unknown;
     /**
-     * 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.
+     * 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
@@ -159,9 +160,23 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
      * 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;
+    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 dev-only display-contract checks under this name. Omitted
+     * 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
@@ -169,26 +184,51 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
      */
     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 — 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.
+ * 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`).
- *
- * 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;
+export declare function installFetch<TArgs, TResult>(self: FetchSkeletonHost, opts: InstallFetchOptions<TArgs, TResult>): void;
+export {};

package/esm/util/installFetch.js

@@ -2,7 +2,7 @@ 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 { createAbortRotation } from './createAbortRotation.js';
 import { makeFetchContext } from './fetchContext.js';
 import { isDataCurrent } from './isDataCurrent.js';
 import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
@@ -18,7 +18,7 @@ import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
  * 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
+ * `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
@@ -30,13 +30,13 @@ import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
  * 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;
+    const { signal, isCurrent, statusCallback, end } = active;
     // synchronous, so it lands while this run is by construction the current one
     setError(undefined);
-    onBegin?.(active);
+    onBegin?.(signal);
     try {
         const result = await run(args, makeFetchContext(self, {
-            stopToken,
+            signal,
             isStale: () => !isCurrent(),
             statusCallback,
         }));
@@ -52,20 +52,18 @@ export async function runFetchOnce(self, active, args, { run, commit, 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
+        // 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, and unconditional
-        // because a superseded run's status slot goes on voting for a phase that
-        // is over until it is retired
+        // last, because it closes the guard `onEnd` reads
         end();
     }
 }
 /**
- * The two dev-only checks every fetch installer owes, together because they are
+ * 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.
  */
@@ -73,38 +71,63 @@ 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 — 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.
+ * 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`).
- *
- * 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, }) {
+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 rotation = createStopTokenRotation(self, report);
+    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;
-    const stamp = committedKey ? undefined : observable.box();
-    const heldKey = committedKey ?? (() => stamp.get());
+    // 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(() => {
@@ -113,9 +136,6 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
             });
         }
         : commit;
-    addDisposer(self, () => {
-        rotation.dispose();
-    });
     leadingEdgeAutorun(self, 
     // #region voidTracking
     () => {
@@ -128,13 +148,23 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
         // 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;
         }
-        // Teardown mutates observables `prepare` reads before the disposers run,
-        // and getContainingView on a detached node warns then throws.
-        const args = isAlive(self) ? prepare() : undefined;
+        const args = prepare();
         if (args === undefined) {
             noteFetchAutorunRun?.('declined');
             return false;
@@ -145,9 +175,7 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
         // 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) {
+        if (held !== undefined && held(args) && reloadEpoch === issuedEpoch) {
             noteFetchAutorunRun?.('declined');
             return false;
         }
@@ -174,5 +202,4 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
     }, 
     // #endregion
     { name, delay });
-    return rotation.cancel;
 }

package/esm/util/installInitAutorun.d.ts

@@ -1,13 +1,13 @@
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 interface InitAutorunHost<T> extends IStateTreeNode {
-    init?: T;
-    setInit: (init?: T) => void;
+    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 `setInit` has replaced it. Any mid-apply wait that can
+     * 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
@@ -26,35 +26,36 @@ interface InitAutorunOptions<T> {
      */
     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.
+     * 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 init state machine shared by the views that take a declarative `init`
+ * 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:
+ * The failure policy keys off `materialized`, the same line `withLaunchInput`
+ * draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - 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 `init` is also what
+ *   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 init.
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
  *
- * `apply` therefore never clears `init` and never catches for reporting — it
+ * `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.
  */

package/esm/util/installInitAutorun.js

@@ -1,19 +1,19 @@
 import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
 import { getNotificationSink } from './sessionServices.js';
-// Clear only when `init` is still the exact object we applied. A setInit that
-// lands while `apply` is awaiting (React StrictMode remounts, a programmatic
-// re-launch) swaps in a new object; clearing unconditionally would silently
-// drop that pending init. Leaving it lets the drain loop apply it next.
+// 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.init === init) {
-        self.setInit(undefined);
+    if (isAlive(self) && self.pendingLaunch === init) {
+        self.setLaunch(undefined);
     }
 }
 async function applyInitOnce(self, init, { apply, materialized }) {
     try {
         await apply(init, {
-            superseded: () => !isAlive(self) || self.init !== init,
+            superseded: () => !isAlive(self) || self.pendingLaunch !== init,
         });
         clearIfUnchanged(self, init);
     }
@@ -34,7 +34,7 @@ async function applyInitOnce(self, init, { apply, materialized }) {
     }
 }
 function currentInit(self, { ready }) {
-    return isAlive(self) && ready() ? self.init : undefined;
+    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
@@ -47,32 +47,32 @@ async function drainInit(self, opts) {
     while (pending !== undefined) {
         await applyInitOnce(self, pending, opts);
         const next = currentInit(self, opts);
-        // a fatal failure keeps `init` for a reload retry; the same object still
+        // 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 init state machine shared by the views that take a declarative `init`
+ * 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:
+ * The failure policy keys off `materialized`, the same line `withLaunchInput`
+ * draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - 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 `init` is also what
+ *   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 init.
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
  *
- * `apply` therefore never clears `init` and never catches for reporting — it
+ * `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.
  */
@@ -93,7 +93,7 @@ export function installInitAutorun(self, opts) {
         // reading a detached node throws — here into an unawaited promise.
         const alive = isAlive(self);
         const isReady = alive && opts.ready();
-        const init = alive ? self.init : undefined;
+        const init = alive ? self.pendingLaunch : undefined;
         if (isReady && init !== undefined && !draining) {
             draining = true;
             try {

package/esm/util/installPrerequisiteFetch.d.ts

@@ -0,0 +1,115 @@
+import type { StatusReporter } from './createAbortRotation.ts';
+import type { FetchContext } from './fetchContext.ts';
+import type { FetchSkeletonHost } from './installFetch.ts';
+/**
+ * What a prerequisite read needs of the display it runs on, beside the
+ * skeleton's own three. Duck-typed rather than a foundation's `Instance` type,
+ * because the hosts compose different foundations — one per fetch family, and
+ * the comparative displays compose none of them — and this is the only thing
+ * they have in common.
+ */
+export interface PrerequisiteFetchHost extends FetchSkeletonHost {
+    /**
+     * Read in `prepare`, so it is **tracked**: an adapter edited in the config
+     * editor has to re-read, and `run`'s own reads are untracked by contract.
+     */
+    adapterConfig: Record<string, unknown>;
+    isMinimized: boolean;
+}
+/**
+ * A prerequisite read's answer, stamped with the adapter config it answers.
+ * A display holds the latest one and reads it through `readFor`, so an answer
+ * never outlives its adapter config and no failure path has to clear it.
+ */
+export interface AdapterRead<T> {
+    adapterConfig: Record<string, unknown>;
+    value: T;
+}
+/**
+ * `read`'s value while it answers the adapter config `host` holds; undefined
+ * until a read of that config commits, which a failed read never does.
+ *
+ * Equal by value, as the fetch key is: an undo rebuilds the track's config,
+ * handing back an equal adapter config the fetch declines to read again.
+ */
+export declare function readFor<T>(host: {
+    adapterConfig: Record<string, unknown>;
+}, read: AdapterRead<T> | undefined): T | undefined;
+/**
+ * A **prerequisite read**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Four in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for;
+ * and the mark display's source list, which gives each listed source a row —
+ * and they sit on three different fetch foundations, which is why this sits in
+ * core beside the skeleton and not beside any of them.
+ *
+ * They had the shape below hand-copied, comment for comment, and each term is a
+ * rule rather than a preference:
+ *
+ * - **the adapter config is the whole trigger and the whole key.** Tracked in
+ *   `prepare` so a config-editor edit re-reads; keyed on the same value so an
+ *   un-minimize over the same file re-reads nothing. Getting one without the
+ *   other gives either a stale header or a walk of a `.hic` norm-vector index on
+ *   every expand.
+ * - **the answer carries the same key** (`AdapterRead`), and a display reads
+ *   it through `readFor`, so an answer to a previous adapter config is never
+ *   read as the current one, and a failed read leaves nothing to clear.
+ * - **an answer to a config the display no longer holds is dropped**, and so is
+ *   its error. An undo that brings back the config already answered makes the
+ *   skeleton decline a re-read, while the read of the abandoned config runs
+ *   on, still current; landing, it would stamp its key, force a second read of
+ *   the held one and hand the display a list for another file, on which the
+ *   variant display resets its arrangement.
+ * - **minimized is the gate**, and a display with a second condition of its own
+ *   passes `gate` — the sample-list read waits for the LGV to be measured as
+ *   well, so a full-file scan does not start ahead of the display's own first
+ *   fetch, and the tier read waits on the track declaring a tier threshold at
+ *   all.
+ * - **no `contract`.** This is the second fetch on a display whose foundation
+ *   installed both checks already: `assertDisplayContract` would report the
+ *   double-attach it exists to catch, and a second retry check would consume the
+ *   same `reloadCounter` bumps as the first.
+ * - **where the status goes is the caller's** (`report`). The two LGV reads
+ *   lend the display's own status window, so the read takes a slot beside the
+ *   primary fetch rather than opening a second writer over the one status field
+ *   (ADR-081) — and it matters more here than for most fetches: a prerequisite
+ *   runs inside the pre-first-paint window, where the scrim is up because
+ *   nothing is drawn rather than because `isLoading` is, so `statusMessage` is
+ *   the only thing that can say what is happening. The tier read narrates
+ *   nothing; a header is not a load.
+ *
+ * `createAdapterMetadataFetch` keys on the same adapter config and is
+ * deliberately NOT one of these: no trigger, no signal and no status,
+ * because it is fetched lazily when a details widget opens and the widget opens
+ * on the result. A prerequisite read is the one a display's own fetch waits on.
+ *
+ * **A declaration, not the skeleton this name used to be.** There was an
+ * `installPrerequisiteFetch` until 2026-08-23, and `3c5aa7fce2` deleted it for
+ * a good reason: it carried a `runOne` of its own — a fifth copy of begin →
+ * clear → run → commit-if-current → `handleFetchError` → end — and once
+ * `installFetch` owned that sequence, a second one was pure drift surface. This
+ * one adds no sequence, no rotation and no error rule; it is terms handed to
+ * `installFetch`, the same shape `installGlobalFetchAutorun` and
+ * `installComparativeFetchAutorun` are. Add nothing here that a family could
+ * not state as an option to the skeleton.
+ *
+ * Everything the skeleton gives it is the point of going through the skeleton:
+ * the latest-wins rotation (so a superseding read aborts the one it replaced,
+ * and only a superseding read does — a user cancel of the primary fetch cannot
+ * strand the display the way sharing its signal would), the clear at the start,
+ * the currency-guarded error rule, the unconditional `reloadCounter` read that
+ * makes the chrome's Retry re-run this, and the retired status slot that keeps a
+ * failed read from leaving a progress chip up for good.
+ */
+export declare function installPrerequisiteFetch<TResult>(self: PrerequisiteFetchHost, { name, delay, report, gate, run, commit, setError, }: {
+    name: string;
+    delay: number;
+    report: StatusReporter;
+    /** an extra term of the display's own, ANDed under `!isMinimized` */
+    gate?: () => boolean;
+    run: (adapterConfig: Record<string, unknown>, ctx: FetchContext) => Promise<TResult | undefined>;
+    commit: (read: AdapterRead<TResult>) => void;
+    setError: (error?: unknown) => void;
+}): void;