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

package/esm/util/index.js

@@ -12,7 +12,7 @@ export { capitalizeFirst, pluralize, shorten, shorten2, truncateMiddle, } from '
 export { formatBytes } from './formatBytes.js';
 export { getFillProps, getStrokeProps, stripAlpha } from './svgColorProps.js';
 export { fetchAndMaybeUnzip, fetchAndMaybeUnzipText, isGzip, } from './fetchAndMaybeUnzip.js';
-export { AuthNeededError, addOrReplaceView, canReplaceView, isAbstractMenuManager, isAppRootModel, isAuthNeededException, isBlobLocation, isDisplayModel, isFileHandleLocation, isLocalPathLocation, isRootModelWithInternetAccounts, isSelectionContainer, isSessionModel, isSessionServices, isSessionModelWithConfigEditing, isSessionModelWithConnectionEditing, isSessionModelWithConnections, isSessionModelWithWidgets, isSessionWithAddAssembly, isSessionWithAddSessionTrack, isSessionWithAddTracks, isSessionWithPublishTrackConf, isSessionWithDeleteTrackConf, isSessionWithPermanentPlugins, isSessionWithSessionPlugins, isSessionWithSessionTracks, isSessionWithShareURL, isSessionWithViewReplacement, isTrackModel, isTrackViewModel, isUriLocation, isViewContainer, isViewModel, } from './types/index.js';
+export { AuthNeededError, addOrReplaceView, canReplaceView, isAbstractMenuManager, isAppRootModel, isAuthNeededException, isBlobLocation, isDisplayModel, isFileHandleLocation, isLocalPathLocation, isRootModelWithInternetAccounts, isSelectionContainer, isSessionModel, isSessionServices, isSessionModelWithConfigEditing, isSessionModelWithConnectionEditing, isSessionModelWithConnections, isSessionModelWithWidgets, isSessionWithAddAssembly, isSessionWithAddSessionTrack, isSessionWithAddTracks, isSessionWithPublishTrackConf, isSessionWithDeleteTrackConf, isSessionWithMultipleViews, isSessionWithPermanentPlugins, isSessionWithSessionPlugins, isSessionWithSessionTracks, isSessionWithShareURL, isSessionWithViewReplacement, isTrackModel, isTrackViewModel, isUriLocation, isViewContainer, isViewModel, } from './types/index.js';
 export { getPluginUpdate, installablePlugins, installedVersionFromUrl, isPluginInstalled, resolvePlugin, resolveStorePluginRefs, resolveStoreRefs, } from './pluginStore.js';
 export { createProgressReporter, createStatusFanOut, createStatusWindow, downloadStatus, progressLabel, statusFraction, statusMessageText, statusProgressLabel, statusReading, statusSource, throttleStatusEmits, updateStatus, withProgress, } from './progress.js';
 export { calculateRedispatchRange, doesIntersect2, intersection2, } from './range.js';
@@ -29,11 +29,11 @@ export { MAX_ZOOM_RATE_PER_MS, SCROLL_ZOOM_FACTOR_DIVISOR, ZOOM_ACTIVE_WINDOW_MS
 export { avg, clamp, getDisplayStr, getNumberGrouping, max, maxFinite, min, minmax, polarToCartesian, radToDeg, reducePrecision, setNumberGrouping, sum, toLocale, } from './numericUtils.js';
 export { bpSpanPx, bpToPx, bytesForRegions, featureSpanPx, getBpDisplayStr, getTickDisplayStr, parseBpString, } from './bpUtils.js';
 export { gatherOverlaps, mergeIntervals, } from './intervals.js';
-export { clampToContig } from './clampToContig.js';
-export { animationAllowed } from './animationAllowed.js';
+export { clampToContig, clampToListedContig } from './clampToContig.js';
+export { MORPH_DURATION_MS, animationAllowed, easeInOutCubic, morphClockMs, } from './animationAllowed.js';
 export { springAnimate } from './springAnimate.js';
 export { localStorageAvailable, localStorageGetBoolean, localStorageGetItem, localStorageGetJSON, localStorageGetNumber, localStorageGetStringArray, localStorageRemoveItem, localStorageSetBoolean, localStorageSetItem, localStorageSetJSON, localStorageSetNumber, notifyLocalStorageKey, subscribeToLocalStorageKey, } from './localStorage.js';
-export { renameRegionIfNeeded, renameRegionsIfNeeded } from './renameRegions.js';
+export { renameComparativeRegions, renameRegionIfNeeded, renameRegionsIfNeeded, } from './renameRegions.js';
 export { addAndShowTrack } from './addAndShowTrack.js';
 export { addTrackFromWidget, containerDisplaysAssembly, finishAddTrack, } from './addTrackFromWidget.js';
 export { namesTemporaryAssembly } from './temporaryAssembly.js';
@@ -44,7 +44,6 @@ export { indexedDBAvailable, isElectron, isNode, rIC } from './environment.js';
 export { isWebWorker } from './isWebWorker.js';
 export { sessionStorageAvailable, sessionStorageGetItem, sessionStorageRemoveItem, sessionStorageSetItem, } from './sessionStorage.js';
 export { isObject } from './objectUtils.js';
-export { openPromotableDisplays } from './openDisplays.js';
 export { applyOrderWithin, reorder, reorderWithin, } from './reorder.js';
 export { getStr } from './getStr.js';
 export { downloadPhase, getLocationUri, resolveUri } from './getLocationUri.js';
@@ -53,7 +52,7 @@ export { isRpcResult } from './rpc.js';
 export { aesDecrypt, aesEncrypt, sha256, sha256Base64, sha256Base64Url, toBase64, toBase64Url, } from './crypto.js';
 export { notifyFeatureDetailsMiss, openFeatureWidget, } from './openFeatureWidget.js';
 export { withFeatureDetails } from './withFeatureDetails.js';
-export { canonicalizeViewRefName, findParentThat, findParentThatIs, getAssemblyHost, getContainingDisplay, getContainingTrack, getContainingView, getEnv, getRenderingServices, getSession, hashCode, objectHash, } from './mstUtils.js';
+export { canonicalizeViewRefName, findParentThat, findParentThatIs, getAssemblyHost, getContainingDisplay, getContainingTrack, getContainingView, getEnv, getRenderingServices, launchOrReplaceView, getSession, hashCode, objectHash, } from './mstUtils.js';
 export { getDialogHost, getNotificationSink, getPaletteHost, getRpcHost, getSessionServices, } from './sessionServices.js';
 // this is recommended in a later comment in
 // https://github.com/electron/electron/issues/2288 for detecting electron in a
@@ -91,7 +90,6 @@ export { revlist } from './revlist.js';
 // without it that is `(0, PR.useLocalStorage) is not a function` when the panel
 // renders. The implementations never went anywhere -- only these lines did.
 export { useCreateOnce, useDebounce, useFinalUnmount, useLocalStorage, useWidthSetter, } from './hooks.js';
-export { renderToStaticMarkup } from './renderToStaticMarkup.js';
 export { codonTable, defaultCodonTable, generateCodonTable, } from './geneticCodes.js';
 export { IUPAC_MOTIF_REGEX, isPalindromic, iupacToRegex, reverseComplementIupac, } from './iupac.js';
 export { parseMotifList, } from './parseMotifList.js';
@@ -121,6 +119,7 @@ export function isSupportedIndexingAdapter(type = '') {
 // needing insertion order builds its own Map (see tree-sidebar's CLAUDE.md).
 export function groupBy(array, predicate) {
     const result = Object.create(null);
+    // eslint-disable-next-line unicorn/prefer-group-by -- Object.groupBy types its result Partial, which would widen every caller's Object.values to `T[] | undefined`
     for (const value of array) {
         const t = predicate(value);
         result[t] ??= [];
@@ -137,17 +136,19 @@ export function testAdapter(fileName, regex, adapterHint, expected) {
 export { default as SimpleFeature, isFeature, } from './simpleFeature.js';
 export { saveAs } from './FileSaver/index.js';
 export { saveSvgAsImage, svgHtmlToPngBlob, } from '../svg/saveSvgAsImage.js';
-export { createStatusChannel, createStopTokenRotation, } from './createStopTokenRotation.js';
+export { createStatusChannel, createAbortRotation, } from './createAbortRotation.js';
 // `installFetch` is deliberately NOT re-exported here: it reaches `getSession`
 // through `fetchContext.ts`, which imports this barrel, so exporting it makes
 // the barrel initialize itself. Import it from `@jbrowse/core/util/installFetch`.
 export { createSharedSetup } from './cachedSetup.js';
+export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.js';
 export { isDataCurrent } from './isDataCurrent.js';
 export { handleFetchError, isAbortException, makeAbortError, } from './aborting.js';
 export { linkify } from './linkify.js';
+export { isGeneLikeType, isSequenceMatchType } from './featureTypes.js';
 export { locStringsToRegions } from './locStringsToRegions.js';
 export { UnknownRefNameError, assembleLocString, assembleLocStringRaw, assembleLocStrings, compareLocStrings, compareLocs, parseLocString, parseLocStringOneBased, stringify, } from './locString.js';
-export { checkStopToken, checkStopTokenThrottled, createStopToken, createStopTokenChecker, hasSharedArrayBuffer, isStopToken, isStopped, markStopTokenStopped, registerStopTokenBroadcaster, stopStopToken, stopTokenSignal, withStopTokenCheck, withStopTokenSignal, } from './stopToken.js';
+export { checkAbortSignal, createAbortBreakpoint, withAbortCheck, } from './aborting.js';
 export { adapterNeedsAddTrackComponent, addAddTrackComponent, } from './addTrackComponent.js';
 export { adapterConfigFromSpec } from './formatGuessers.js';
 export { UNKNOWN, UNSUPPORTED, addAdapterGuesser, addTrackTypeGuesser, clearFileFromCache, ensureFileHandleReady, expandLooseTrackConfig, findFileHandleIds, generateUnknownTrackConf, generateUnsupportedTrackConf, getBlob, getBlobMap, getConfAssemblyNames, getFileFromCache, getFileName, getRpcSessionId, getTrackAssemblyNames, getTrackName, guessAdapter, guessTrackConf, guessTrackType, hasFileHandlesInCache, hideTrackGeneric, isLooseTrackConfig, makeIndex, makeIndexType, restoreFileHandles, restoreFileHandlesFromSnapshot, setBlobMap, setFileInCache, showTrackGeneric, storeBlobLocation, storeFileHandleLocation, stripFileExtension, stripTrackIds, toggleTrackGeneric, } from './tracks.js';
@@ -155,5 +156,5 @@ export { getFileHandle, isFileSystemAccessSupported, storeFileHandle, verifyPerm
 export { IntervalTree } from './IntervalTree.js';
 export { cmpStr } from './cmpStr.js';
 export { diffTrackConfig, flattenTrackConfigDelta, mergeTrackConfig, } from './trackConfigDelta.js';
-export { BEZIER_CONNECTOR_MAX_REACH_PX, bezierConnectorPath, } from './bezierConnector.js';
+export { BEZIER_CONNECTOR_MAX_REACH_PX, CUBIC_APEX_RATIO, bezierConnectorPath, } from './bezierConnector.js';
 export { diagonalizeRegions, } from './diagonalizeRegions.js';

package/esm/util/indexCandidates.d.ts

@@ -1,35 +1,5 @@
 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[];
+export { indexCandidateNames, indexSpellings } from '@jbrowse/add-track-core';
 /**
  * `location` with its filename replaced, i.e. the sibling of a data file.
  *

package/esm/util/indexCandidates.js

@@ -1,66 +1,8 @@
+import { indexCandidateNames } from '@jbrowse/add-track-core';
 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 [];
-}
+// 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.
  *
@@ -73,7 +15,7 @@ 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);
+    path.replace(/[^/\\]*$/, () => fileName);
     if (location.locationType === 'UriLocation') {
         return { ...location, uri: replaceLast(location.uri) };
     }

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;
 }