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

package/esm/util/fetchPhases.d.ts

@@ -4,10 +4,10 @@
  * remembered.
  *
  * The shared `installFetch` skeleton takes this shape, and so does the LGV
- * global family (`installGlobalFetchAutorun`, over `FetchMixin.runFetch`). It
- * was the same contract declared twice, with the same three rules explained
- * twice, which is a drift axis over rules whose whole value is being the same
- * everywhere.
+ * global family (`installGlobalFetchAutorun`, a declaration over that same
+ * skeleton). It was the same contract declared twice, with the same three rules
+ * explained twice, which is a drift axis over rules whose whole value is being
+ * the same everywhere.
  *
  * `TCtx` is what a family hands its `run`: a `FetchContext` for most of them, a
  * `ComparativeFetchContext` (that plus adapter config and refName rename) for
@@ -56,11 +56,11 @@ export interface FetchPhases<TArgs, TResult, TCtx> {
      * **Nothing it reads is tracked**, so the payload it assembles cannot widen
      * the autorun's dependency set the way calling `rpcProps()` in the body would.
      * Being async is not what buys that — `run` is *called* synchronously, so its
-     * own prefix down to its first `await` runs wherever the caller was. Each
-     * family arranges it: the global one reaches `run` through
-     * `FetchMixin.runFetch`, an MST flow and so an action, which MobX runs
-     * untracked; the comparative one calls its lifecycle inside `untracked`
-     * because it has no action to hide behind.
+     * own prefix down to its first `await` runs wherever the caller was. The
+     * `installFetch` skeleton calls it inside `untracked`, which covers the
+     * global and comparative families with it; the per-region family reaches its
+     * work through `FetchMixin.runFetch`, an MST flow and so an action, which
+     * MobX runs untracked.
      */
     run: (args: TArgs, ctx: TCtx) => Promise<TResult | undefined>;
     /**

package/esm/util/hooks.d.ts

@@ -20,6 +20,14 @@ export declare function useWidthSetter(view: {
  * "avoiding recreating the ref contents" pattern.
  */
 export declare function useCreateOnce<T>(create: () => T): T;
+/**
+ * `useCreateOnce` for an asynchronous factory: returns undefined until
+ * `create` resolves, and rethrows a rejection from render. The value can
+ * resolve after the component is gone — a caller whose value is expensive to
+ * leak should use product-core's `useAsyncEngineLifecycle`, which discards
+ * that late arrival.
+ */
+export declare function useCreateOnceAsync<T>(create: () => Promise<T>): T | undefined;
 /**
  * Run `cleanup` when the component *really* unmounts.
  *

package/esm/util/hooks.js

@@ -112,6 +112,33 @@ export function useCreateOnce(create) {
     ref.current ??= { value: create() };
     return ref.current.value;
 }
+/**
+ * `useCreateOnce` for an asynchronous factory: returns undefined until
+ * `create` resolves, and rethrows a rejection from render. The value can
+ * resolve after the component is gone — a caller whose value is expensive to
+ * leak should use product-core's `useAsyncEngineLifecycle`, which discards
+ * that late arrival.
+ */
+export function useCreateOnceAsync(create) {
+    const started = useRef(false);
+    const [state, setState] = useState();
+    useEffect(() => {
+        if (!started.current) {
+            started.current = true;
+            create().then(value => {
+                setState({ value });
+            }, (error) => {
+                setState({ error });
+            });
+        }
+        // create is read on the first effect only, as in useCreateOnce
+        // eslint-disable-next-line @eslint-react/exhaustive-deps
+    }, []);
+    if (state && 'error' in state) {
+        throw state.error;
+    }
+    return state?.value;
+}
 /**
  * Run `cleanup` when the component *really* unmounts.
  *

package/esm/util/index.d.ts

@@ -3,7 +3,7 @@ export { capitalizeFirst, pluralize, shorten, shorten2, truncateMiddle, } from '
 export { formatBytes } from './formatBytes.ts';
 export { getFillProps, getStrokeProps, stripAlpha } from './svgColorProps.ts';
 export { fetchAndMaybeUnzip, fetchAndMaybeUnzipText, isGzip, } from './fetchAndMaybeUnzip.ts';
-export { type AbstractDisplayModel, type AbstractMenuManager, type AbstractRootModel, type AbstractSessionModel, type AbstractTrackModel, type AbstractViewContainer, type AbstractViewModel, type AnimationMode, type AnyReactComponentType, type AppRootModel, type AssemblyHost, type AssemblyManager, type AugmentedRegion, AuthNeededError, type BasePlugin, type BlobLocation, type ClassReturnedBy, type ConnectionInstance, type DialogComponentType, type DialogHost, type DrawerPosition, type FileHandleLocation, type FileLocation, type InstanceTypeRestrictive, type JBrowsePlugin, type JBrowsePluginVersion, type LocalPathLocation, type NoAssemblyRegion, type NotificationLevel, type NotificationSink, type PaletteHost, type PreBlobLocation, type PreFileHandleLocation, type PreFileLocation, type PreLocalPathLocation, type PreUriLocation, type Region, type RenderingServices, type RpcCaller, type RpcHost, type RootModelWithInternetAccounts, type SelectionContainer, type SessionServices, type SessionWithAddAssembly, type SessionWithAddSessionTrack, type SessionWithPublishTrackConf, type SessionWithConfigEditing, type SessionWithConnectionEditing, type SessionWithConnections, type SessionWithDeleteTrackConf, type SessionWithDrawerWidgets, type SessionWithFocusedViewAndDrawerWidgets, type SessionWithPermanentPlugins, type SessionWithSessionPlugins, type SessionWithShareURL, type SessionWithViewReplacement, type SessionWithWidgets, type SnackAction, type TrackActionView, type TrackCatalog, type TrackContainer, type TrackViewModel, type TypeTestedByPredicate, type UriLocation, type Widget, type WidgetMap, 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.ts';
+export { type AbstractDisplayModel, type AbstractMenuManager, type AbstractRootModel, type AbstractSessionModel, type AbstractTrackModel, type AbstractViewContainer, type AbstractViewModel, type AnimationMode, type AnyReactComponentType, type AppRootModel, type AssemblyHost, type AssemblyManager, type AugmentedRegion, AuthNeededError, type BasePlugin, type BlobLocation, type ClassReturnedBy, type ConnectionInstance, type DialogComponentType, type DialogHost, type DrawerPosition, type FileHandleLocation, type FileLocation, type InstanceTypeRestrictive, type JBrowsePlugin, type JBrowsePluginVersion, type LocalPathLocation, type NoAssemblyRegion, type NotificationLevel, type NotificationSink, type PaletteHost, type PreBlobLocation, type PreFileHandleLocation, type PreFileLocation, type PreLocalPathLocation, type PreUriLocation, type Region, type RenderingServices, type RpcCaller, type RpcHost, type RootModelWithInternetAccounts, type SelectionContainer, type SessionServices, type SessionWithAddAssembly, type SessionWithAddSessionTrack, type SessionWithPublishTrackConf, type SessionWithConfigEditing, type SessionWithConnectionEditing, type SessionWithConnections, type SessionWithDeleteTrackConf, type SessionWithDrawerWidgets, type SessionWithFocusedViewAndDrawerWidgets, type SessionWithPermanentPlugins, type SessionWithSessionPlugins, type SessionWithShareURL, type SessionWithViewReplacement, type SessionWithWidgets, type SnackAction, type TrackActionView, type TrackCatalog, type TrackContainer, type TrackViewModel, type TypeTestedByPredicate, type UriLocation, type Widget, type WidgetMap, 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.ts';
 export { type PluginUpdate, type ResolvedPlugin, type StorePluginFailure, type StorePluginResolution, getPluginUpdate, installablePlugins, installedVersionFromUrl, isPluginInstalled, resolvePlugin, resolveStorePluginRefs, resolveStoreRefs, } from './pluginStore.ts';
 export { type PhaseFailure, type ProgressReporter, type RpcStatus, type StatusCallback, type StatusPhase, type StatusStream, type StatusWindow, type StatusWithProgress, createProgressReporter, createStatusFanOut, createStatusWindow, downloadStatus, progressLabel, statusFraction, statusMessageText, statusProgressLabel, statusReading, statusSource, throttleStatusEmits, updateStatus, withProgress, } from './progress.ts';
 export { calculateRedispatchRange, doesIntersect2, intersection2, } from './range.ts';
@@ -46,7 +46,7 @@ export { isRpcResult } from './rpc.ts';
 export { aesDecrypt, aesEncrypt, sha256, sha256Base64, sha256Base64Url, toBase64, toBase64Url, } from './crypto.ts';
 export { type FeatureWidgetTypeRef, notifyFeatureDetailsMiss, openFeatureWidget, } from './openFeatureWidget.ts';
 export { withFeatureDetails } from './withFeatureDetails.ts';
-export { canonicalizeViewRefName, findParentThat, findParentThatIs, getAssemblyHost, getContainingDisplay, getContainingTrack, getContainingView, getEnv, getRenderingServices, getSession, hashCode, objectHash, } from './mstUtils.ts';
+export { canonicalizeViewRefName, findParentThat, findParentThatIs, getAssemblyHost, getContainingDisplay, getContainingTrack, getContainingView, getEnv, getRenderingServices, launchOrReplaceView, getSession, hashCode, objectHash, } from './mstUtils.ts';
 export { getDialogHost, getNotificationSink, getPaletteHost, getRpcHost, getSessionServices, } from './sessionServices.ts';
 /**
  * Convert a browser File (from a drop zone or file input) into a FileLocation:
@@ -56,7 +56,6 @@ export declare function fileToLocation(file: File): FileLocation;
 export { type Frame, complement, complementTable, defaultStarts, getFrame, revcom, reverse, stitch, } from './seqUtils.ts';
 export { revlist } from './revlist.ts';
 export { useCreateOnce, useDebounce, useFinalUnmount, useLocalStorage, useWidthSetter, } from './hooks.ts';
-export { renderToStaticMarkup } from './renderToStaticMarkup.ts';
 export { codonTable, defaultCodonTable, generateCodonTable, } from './geneticCodes.ts';
 export { IUPAC_MOTIF_REGEX, isPalindromic, iupacToRegex, reverseComplementIupac, } from './iupac.ts';
 export { type MotifListParse, type MotifParseError, type ParsedMotif, parseMotifList, } from './parseMotifList.ts';

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';
@@ -53,7 +53,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 +91,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';

package/esm/util/installFetch.d.ts

@@ -1,6 +1,7 @@
-import type { ActiveFetch, StatusReporter } from './createStopTokenRotation.ts';
+import type { ActiveFetch, StatusReporter, StopTokenRotation } from './createStopTokenRotation.ts';
 import type { FetchContext } from './fetchContext.ts';
 import type { FetchPhases } from './fetchPhases.ts';
+import type { StopToken } from './stopToken.ts';
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 /**
  * The bookkeeping a family hangs off one fetch, beside the phases. Each of the
@@ -27,8 +28,13 @@ export interface FetchLifecycle {
      * the comparative family's `fetching`), and anything a display blanks
      * because it has no freshness signature to keep stale data honest with
      * (chord's refName map).
+     *
+     * Takes the token 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?: (stopToken: StopToken) => 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
@@ -80,7 +86,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 +103,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
@@ -161,7 +159,7 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
      */
     committedKey?: () => string | undefined;
     /**
-     * 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,19 +167,46 @@ 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: StopTokenRotation;
+    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 LGV global family
+ * (`installGlobalFetchAutorun`, which lends `FetchMixin`'s rotation through the
+ * `rotation` option so `cancelFetch` reaches the fetch it installs), 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 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
@@ -191,4 +216,5 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
  * 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

@@ -33,7 +33,7 @@ export async function runFetchOnce(self, active, args, { run, commit, setError,
     const { stopToken, isCurrent, statusCallback, end } = active;
     // synchronous, so it lands while this run is by construction the current one
     setError(undefined);
-    onBegin?.(active);
+    onBegin?.(stopToken);
     try {
         const result = await run(args, makeFetchContext(self, {
             stopToken,
@@ -65,7 +65,7 @@ export async function runFetchOnce(self, active, args, { run, commit, setError,
     }
 }
 /**
- * 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,19 +73,33 @@ 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 = createStopTokenRotation(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 LGV global family
+ * (`installGlobalFetchAutorun`, which lends `FetchMixin`'s rotation through the
+ * `rotation` option so `cancelFetch` reaches the fetch it installs), 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 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
@@ -95,16 +109,23 @@ function installContractChecks(self, contract) {
  * 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, committedKey, 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.
+    const stamp = committedKey === undefined && fetchKey !== undefined
+        ? observable.box()
+        : undefined;
+    const heldKey = committedKey ?? (() => stamp?.get());
     const commitAndStamp = stamp
         ? (result, args) => {
             runInAction(() => {
@@ -113,9 +134,6 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
             });
         }
         : commit;
-    addDisposer(self, () => {
-        rotation.dispose();
-    });
     leadingEdgeAutorun(self, 
     // #region voidTracking
     () => {
@@ -128,13 +146,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;

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
@@ -35,7 +35,7 @@ interface InitAutorunOptions<T> {
     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.
@@ -43,18 +43,18 @@ interface InitAutorunOptions<T> {
  * The failure policy keys off `materialized`, the same line each view's
  * postProcessSnapshot already draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - 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,13 +47,13 @@ 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.
@@ -61,18 +61,18 @@ async function drainInit(self, opts) {
  * The failure policy keys off `materialized`, the same line each view's
  * postProcessSnapshot already draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - 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/lazyAfterAttach.d.ts

@@ -0,0 +1,13 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export declare function runLazyAfterAttach<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>): void;

package/esm/util/lazyAfterAttach.js

@@ -0,0 +1,31 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export function runLazyAfterAttach(self, load) {
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    ;
+    (async () => {
+        try {
+            const install = await load();
+            if (isAlive(self)) {
+                install(self);
+            }
+        }
+        catch (e) {
+            if (isAlive(self)) {
+                console.error(e);
+                getNotificationSink(self).notifyError(`${e}`, e);
+            }
+        }
+    })();
+}

package/esm/util/legendCandidates.d.ts

@@ -0,0 +1,50 @@
+export interface LegendCandidate {
+    rowIndex: number;
+    label: string;
+    color: number;
+}
+export interface LegendEntry {
+    label: string;
+    color: number;
+}
+export declare const MAX_LEGEND_ENTRIES = 30;
+export declare const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, name, color) combinations a packer walks
+ * past, in first-seen order and bounded — the small list `unionLegendCandidates`
+ * derives a key from, so the main thread never re-walks the features. Fed scalar
+ * by scalar, from the loop that already holds the three values.
+ *
+ * Deduped on the whole triple rather than on (row, color): the union takes the
+ * first NAME it sees for a color, so where that name is already spoken for, the
+ * second name on that color has to still be in the list to carry it.
+ *
+ * A nameless feature contributes nothing, which is the union's rule too — so a
+ * track whose features have no names ships an empty list rather than one entry
+ * per feature.
+ */
+export declare function createLegendCandidateCollector(maxCandidates?: number): {
+    candidates: LegendCandidate[];
+    add(rowIndex: number, label: string, color: number): void;
+};
+export interface LegendCandidateSource {
+    candidates: readonly LegendCandidate[];
+    rowPaintsCandidateColor: (rowIndex: number) => boolean;
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color, labeled by the first name seen in that color, in first-seen
+ * order.
+ *
+ * Keyed by color rather than by name, so each key row is 1:1 with a color — a
+ * row is normally a toggle and hiding a category hides features BY color, so two
+ * names sharing one color must collapse to a single row. A name reused across
+ * two colors keeps its first-seen color.
+ *
+ * `[]` when the data carries no categorical signal: nothing named, or more than
+ * `maxEntries` distinct colors.
+ *
+ * `regions` is consumed lazily, so a caller able to answer without reading any
+ * of them can pass a generator and have none of them touched.
+ */
+export declare function unionLegendCandidates<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, maxEntries?: number): LegendEntry[];