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

package/esm/util/colorBits.js

@@ -1,5 +1,7 @@
+import { abgrToCssRgba } from '@jbrowse/render-core/marks/colorFill';
 import { getAlpha, getBlue, getGreen, getRed, newColor, parse, } from './color-bits/index.js';
 import { namedColorToHex } from './color/cssColorsLevel4.js';
+export { abgrToCssRgba };
 export { alpha, blend, darken, formatHEX, formatHEXA, formatRGBA, getAlpha, getBlue, getGreen, getLuminance, getRed, lighten, newColor, parse, toHSLA, toRGBA, } from './color-bits/index.js';
 // Magenta sentinel for invalid input. User-written jexl color callbacks can
 // legitimately return undefined (e.g. when a feature lacks the field they
@@ -143,7 +145,6 @@ export function normalizedRgbToCss(c) {
 export function normalizedRgbToCssRgba(c, alpha) {
     return `rgba(${Math.round(c[0] * 255)},${Math.round(c[1] * 255)},${Math.round(c[2] * 255)},${alpha})`;
 }
-// Set fillStyle from an ABGR-packed u32.
 export function setAbgrFill(ctx, c) {
     ctx.fillStyle = abgrToCssRgba(c);
 }
@@ -165,10 +166,6 @@ export function abgrBlue(c) {
 export function abgrAlpha(c) {
     return (c >>> 24) & 0xff;
 }
-// Format an ABGR-packed u32 as a CSS rgba() string.
-export function abgrToCssRgba(c) {
-    return `rgba(${abgrRed(c)},${abgrGreen(c)},${abgrBlue(c)},${abgrAlpha(c) / 255})`;
-}
 export function cssColorToNormalizedRgba(color) {
     const c = parseCssColor(color);
     return [

package/esm/util/createStopTokenRotation.d.ts

@@ -13,19 +13,20 @@ import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
  */
 export type StatusReporter = {
     /**
-     * The host's own window, present on any display composing the LGV fetch
-     * mixins. The rotation reports through it rather than opening a SECOND on
-     * the same status field — which is what one-window-per-owner exists to
+     * The host's own window, present on any display composing `FetchMixin`.
+     * The rotation reports through it rather than opening a SECOND on the
+     * same status field — which is what one-window-per-owner exists to
      * prevent.
      */
     statusWindow: StatusWindow;
     setStatusMessage?: never;
 } | {
     /**
-     * The sink for the window the rotation opens for itself. This is the mode
-     * the displays this helper was written for are in (dotplot, synteny),
-     * which compose no fetch mixin, along with every
-     * {@link createStatusChannel} holder.
+     * The sink for the window the rotation opens for itself: the mode of a
+     * fetch on a host with no window of its own — the prerequisite reads,
+     * chord, the breakpoint overlay — along with every
+     * {@link createStatusChannel} holder. The comparative displays this
+     * helper was written for lend a window now (ADR-105).
      */
     setStatusMessage: (status?: RpcStatus) => void;
     statusWindow?: never;

package/esm/util/featureTypes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Classification of a feature from its `type` string alone, for the plugins
+ * that decide something about a feature they did not parse. A type is the only
+ * thing a display, a menu or a widget can ask about a feature without knowing
+ * which adapter produced it, so these live in core rather than beside any one
+ * of their callers.
+ */
+/**
+ * Whether the type names a unit of transcription — a gene, a transcript, or an
+ * RNA, including the pseudogene and V(D)J segment spellings. This is the
+ * question "does this feature have exons", not "can this feature be spliced":
+ * an alignment splices too and is deliberately not gene-like, because a caller
+ * that means to launch a protein view or read a CDS would be wrong about it.
+ */
+export declare function isGeneLikeType(type: string | undefined): boolean;
+/**
+ * Whether the type names a sequence alignment — SO `match` and its subtypes
+ * (`cDNA_match`, `EST_match`, `nucleotide_match`, `protein_match`,
+ * `translated_nucleotide_match`), whose `match_part` children are the aligned
+ * blocks and whose gaps between them are introns when the aligned sequence was
+ * a transcript. Separate from `isGeneLikeType` on purpose: an EST alignment is
+ * evidence for a gene, not one.
+ */
+export declare function isSequenceMatchType(type: string | undefined): boolean;

package/esm/util/featureTypes.js

@@ -0,0 +1,35 @@
+/**
+ * Classification of a feature from its `type` string alone, for the plugins
+ * that decide something about a feature they did not parse. A type is the only
+ * thing a display, a menu or a widget can ask about a feature without knowing
+ * which adapter produced it, so these live in core rather than beside any one
+ * of their callers.
+ */
+// Anchored at the end for gene and RNA so 'intergenic_region' is not a gene and
+// 'rnapol_binding_site' is not an RNA. Unanchored for transcript, which SO
+// spells both ways ('transcript', 'pseudogenic_transcript', 'transcript_region').
+const GENE_LIKE_TYPE = /gene(_segment)?$|rna$|transcript/;
+/**
+ * Whether the type names a unit of transcription — a gene, a transcript, or an
+ * RNA, including the pseudogene and V(D)J segment spellings. This is the
+ * question "does this feature have exons", not "can this feature be spliced":
+ * an alignment splices too and is deliberately not gene-like, because a caller
+ * that means to launch a protein view or read a CDS would be wrong about it.
+ */
+export function isGeneLikeType(type) {
+    return type !== undefined && GENE_LIKE_TYPE.test(type.toLowerCase());
+}
+// SO `match` and every subtype of it is spelled `<something>_match`, so the
+// suffix is the family. `match_part`, the child, is excluded by the anchor.
+const SEQUENCE_MATCH_TYPE = /(^|_)match$/;
+/**
+ * Whether the type names a sequence alignment — SO `match` and its subtypes
+ * (`cDNA_match`, `EST_match`, `nucleotide_match`, `protein_match`,
+ * `translated_nucleotide_match`), whose `match_part` children are the aligned
+ * blocks and whose gaps between them are introns when the aligned sequence was
+ * a transcript. Separate from `isGeneLikeType` on purpose: an EST alignment is
+ * evidence for a gene, not one.
+ */
+export function isSequenceMatchType(type) {
+    return type !== undefined && SEQUENCE_MATCH_TYPE.test(type.toLowerCase());
+}

package/esm/util/fetchPhases.d.ts

@@ -43,7 +43,7 @@ export interface FetchPhases<TArgs, TResult, TCtx> {
      * gets a dead Retry button — see there.
      *
      * What it must **not** do is move a trigger read of its own under a bail-out.
-     * See ARCHITECTURE.md §"The global-fetch trigger list must be read
+     * See reference/FETCH_SKELETON.md §"The global-fetch trigger list must be read
      * unconditionally".
      */
     prepare: () => TArgs | undefined;

package/esm/util/index.d.ts

@@ -22,7 +22,7 @@ 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.ts';
 export { type MinimalRegion, bpSpanPx, bpToPx, bytesForRegions, featureSpanPx, getBpDisplayStr, getTickDisplayStr, parseBpString, } from './bpUtils.ts';
 export { type BasicFeature, gatherOverlaps, mergeIntervals, } from './intervals.ts';
-export { clampToContig } from './clampToContig.ts';
+export { clampToContig, clampToListedContig } from './clampToContig.ts';
 export { animationAllowed } from './animationAllowed.ts';
 export { springAnimate } from './springAnimate.ts';
 export { localStorageAvailable, localStorageGetBoolean, localStorageGetItem, localStorageGetJSON, localStorageGetNumber, localStorageGetStringArray, localStorageRemoveItem, localStorageSetBoolean, localStorageSetItem, localStorageSetJSON, localStorageSetNumber, notifyLocalStorageKey, subscribeToLocalStorageKey, } from './localStorage.ts';
@@ -44,7 +44,7 @@ export { downloadPhase, getLocationUri, resolveUri } from './getLocationUri.ts';
 export { measureGridWidth, resolveSelectedIds } from './dataGridUtils.ts';
 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 { type FeatureWidgetTypeRef, type ParentFeatureSummary, notifyFeatureDetailsMiss, openFeatureWidget, } from './openFeatureWidget.ts';
 export { withFeatureDetails } from './withFeatureDetails.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';
@@ -68,9 +68,11 @@ export { saveAs } from './FileSaver/index.ts';
 export { type SaveSvgAsImageOptions, saveSvgAsImage, svgHtmlToPngBlob, } from '../svg/saveSvgAsImage.ts';
 export { type ActiveFetch, type StatusChannel, type StatusReporter, createStatusChannel, createStopTokenRotation, } from './createStopTokenRotation.ts';
 export { createSharedSetup } from './cachedSetup.ts';
+export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.ts';
 export { isDataCurrent } from './isDataCurrent.ts';
 export { handleFetchError, isAbortException, makeAbortError, } from './aborting.ts';
 export { linkify } from './linkify.ts';
+export { isGeneLikeType, isSequenceMatchType } from './featureTypes.ts';
 export { locStringsToRegions } from './locStringsToRegions.ts';
 export type { RefNameSource } from './locStringsToRegions.ts';
 export { type ParsedLocString, UnknownRefNameError, assembleLocString, assembleLocStringRaw, assembleLocStrings, compareLocStrings, compareLocs, parseLocString, parseLocStringOneBased, stringify, } from './locString.ts';

package/esm/util/index.js

@@ -29,7 +29,7 @@ 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 { clampToContig, clampToListedContig } from './clampToContig.js';
 export { animationAllowed } 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';
@@ -141,9 +141,11 @@ export { createStatusChannel, createStopTokenRotation, } from './createStopToken
 // 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';

package/esm/util/installFetch.d.ts

@@ -25,7 +25,7 @@ export interface FetchLifecycle {
     /**
      * 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
+     * through `fetchMixinLifecycle`), and anything a display blanks
      * because it has no freshness signature to keep stale data honest with
      * (chord's refName map).
      *
@@ -127,7 +127,7 @@ interface InstallFetchOptionsBase<TArgs, TResult> extends FetchPhases<TArgs, TRe
      * 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
@@ -146,10 +146,10 @@ interface InstallFetchOptionsBase<TArgs, TResult> extends FetchPhases<TArgs, TRe
      */
     fetchKey?: (args: TArgs) => string;
     /**
-     * The key of the data already committed, when the host keeps one — the
-     * comparative displays stamp `loadedFetchKey`, which their `dataCurrent`
-     * flag reads too, so a second stamp would be one more thing to disagree with
-     * it. Omitted, the skeleton stamps its own at commit.
+     * 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
@@ -157,7 +157,21 @@ interface InstallFetchOptionsBase<TArgs, TResult> extends FetchPhases<TArgs, TRe
      * 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?: () => string | undefined;
+    /**
+     * The predicate form of the freshness gate, for a fetch whose "I have exactly
+     * this already" is not string equality: the density tier holds bins over a
+     * buffered read and answers a viewport those bins *contain*, which no key can
+     * spell. Same rules as `fetchKey` — declined runs report `declined`, and a
+     * `reloadCounter` advanced since the last issued fetch overrides it — so the
+     * comparison lives here and not in `prepare`, where a reload could not reach
+     * it. Runs inside the autorun, so what it reads is tracked: read the
+     * committed state off an observable, and the commit that changes the answer
+     * wakes the declined run.
+     *
+     * Either this or `fetchKey`, not both.
+     */
+    heldAnswers?: (args: TArgs) => boolean;
     /**
      * Install the two display-contract checks under this name. Omitted
      * by a **secondary** fetch on a host whose primary foundation already
@@ -197,12 +211,13 @@ export type InstallFetchOptions<TArgs, TResult> = InstallFetchOptionsBase<TArgs,
  * unconditional trigger reads, the gates, and {@link runFetchOnce} under them.
  *
  * Every fetch in the tree is this shape except one family — the prerequisite
- * reads (HiC's header, the multi-sample sample list), the 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
+ * 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
@@ -211,10 +226,6 @@ export type InstallFetchOptions<TArgs, TResult> = InstallFetchOptionsBase<TArgs,
  * 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, opts: InstallFetchOptions<TArgs, TResult>): () => void;
+export declare function installFetch<TArgs, TResult>(self: FetchSkeletonHost, opts: InstallFetchOptions<TArgs, TResult>): void;
 export {};

package/esm/util/installFetch.js

@@ -90,12 +90,13 @@ function ownRotation(self, report) {
  * unconditional trigger reads, the gates, and {@link runFetchOnce} under them.
  *
  * Every fetch in the tree is this shape except one family — the prerequisite
- * reads (HiC's header, the multi-sample sample list), the 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
+ * 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
@@ -104,13 +105,9 @@ function ownRotation(self, report) {
  * 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, opts) {
-    const { name, delay, gate, contract, fetchKey, committedKey, prepare, run, commit, setError, onBegin, onEnd, } = opts;
+    const { name, delay, gate, contract, fetchKey, loadedKey, heldAnswers, prepare, run, commit, setError, onBegin, onEnd, } = opts;
     const noteFetchAutorunRun = contract === undefined ? undefined : installContractChecks(self, contract);
     const lent = opts.rotation;
     const rotation = lent === undefined ? ownRotation(self, opts.report) : lent;
@@ -122,10 +119,16 @@ export function installFetch(self, opts) {
     // 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
+    const stamp = loadedKey === undefined && fetchKey !== undefined
         ? observable.box()
         : undefined;
-    const heldKey = committedKey ?? (() => stamp?.get());
+    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(() => {
@@ -173,9 +176,7 @@ export function installFetch(self, opts) {
         // 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;
         }
@@ -202,5 +203,4 @@ export function installFetch(self, opts) {
     }, 
     // #endregion
     { name, delay });
-    return rotation.cancel;
 }

package/esm/util/installInitAutorun.d.ts

@@ -26,9 +26,10 @@ 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`. */
@@ -40,8 +41,8 @@ interface InitAutorunOptions<T> {
  * 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 `launch` is still persisted, so
  *   keep it for a reload retry and `setError`. That flips the view onto its

package/esm/util/installInitAutorun.js

@@ -58,8 +58,8 @@ async function drainInit(self, opts) {
  * 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 `launch` is still persisted, so
  *   keep it for a reload retry and `setError`. That flips the view onto its

package/esm/util/installPrerequisiteFetch.d.ts

@@ -0,0 +1,86 @@
+import type { StatusReporter } from './createStopTokenRotation.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**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Three in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; and the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for —
+ * 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.
+ * - **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 stop token 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 token 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: (result: TResult) => void;
+    setError: (error?: unknown) => void;
+}): void;

package/esm/util/installPrerequisiteFetch.js

@@ -0,0 +1,73 @@
+import { adapterConfigKey } from './adapterConfigKey.js';
+import { installFetch } from './installFetch.js';
+/**
+ * A **prerequisite read**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Three in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; and the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for —
+ * 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.
+ * - **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 stop token 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 token 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 function installPrerequisiteFetch(self, { name, delay, report, gate = () => true, run, commit, setError, }) {
+    installFetch(self, {
+        name,
+        delay,
+        report,
+        gate: () => !self.isMinimized && gate(),
+        prepare: () => ({ adapterConfig: self.adapterConfig }),
+        fetchKey: ({ adapterConfig }) => adapterConfigKey(adapterConfig),
+        run: ({ adapterConfig }, ctx) => run(adapterConfig, ctx),
+        commit,
+        setError,
+    });
+}

package/esm/util/openFeatureWidget.d.ts

@@ -5,10 +5,15 @@ export interface FeatureWidgetTypeRef {
     type: string;
     id: string;
 }
+export interface ParentFeatureSummary {
+    name: string;
+    type?: string;
+}
 export declare function openFeatureWidget(node: IAnyStateTreeNode, featureData: SimpleFeatureSerialized, opts?: {
     widget?: FeatureWidgetTypeRef;
     extra?: Record<string, unknown>;
     feature?: Feature;
+    parentFeature?: ParentFeatureSummary;
 }): Widget | undefined;
 /**
  * The other half of the flow above: the details lookup came back with nothing,

package/esm/util/openFeatureWidget.js

@@ -32,6 +32,7 @@ export function openFeatureWidget(node, featureData, opts = {}) {
     const { type, id } = opts.widget ?? DEFAULT_FEATURE_WIDGET;
     const widget = session.addWidget(type, id, {
         featureData,
+        parentFeature: opts.parentFeature,
         view: getContainingView(node),
         track: getContainingTrack(node),
         ...opts.extra,

package/esm/util/openViews.d.ts

@@ -0,0 +1,16 @@
+import type { AbstractSessionModel, AbstractTrackModel, AbstractViewModel } from './types/index.ts';
+/**
+ * "What is open" — the reduction four consumers wanted and each used to walk
+ * for itself (AppReadyMarker, jbApi, and capture's session gate and busy
+ * check), on different and drifting spellings of the view nesting.
+ *
+ * The recursion lives here, once. What each view contributes lives on the view,
+ * once, as `ownViews`/`ownTracks`. Neither half guesses at the other: the
+ * census is declared intent, not a shape that can be discovered, because the
+ * two things that look enumerable are not — the dotplot's `views` prop holds
+ * view-shaped axis models the user never opened, and react-msaview's `tracks`
+ * getter holds annotation rows that are not tracks.
+ */
+export declare function openViews(session: AbstractSessionModel): AbstractViewModel[];
+/** Every track on every open view. */
+export declare function openTracks(session: AbstractSessionModel): AbstractTrackModel[];

package/esm/util/openViews.js

@@ -0,0 +1,22 @@
+/**
+ * "What is open" — the reduction four consumers wanted and each used to walk
+ * for itself (AppReadyMarker, jbApi, and capture's session gate and busy
+ * check), on different and drifting spellings of the view nesting.
+ *
+ * The recursion lives here, once. What each view contributes lives on the view,
+ * once, as `ownViews`/`ownTracks`. Neither half guesses at the other: the
+ * census is declared intent, not a shape that can be discovered, because the
+ * two things that look enumerable are not — the dotplot's `views` prop holds
+ * view-shaped axis models the user never opened, and react-msaview's `tracks`
+ * getter holds annotation rows that are not tracks.
+ */
+export function openViews(session) {
+    return session.views.flatMap(withNested);
+}
+/** Every track on every open view. */
+export function openTracks(session) {
+    return openViews(session).flatMap(v => v.ownTracks ?? []);
+}
+function withNested(view) {
+    return [view, ...(view.ownViews ?? []).flatMap(withNested)];
+}

package/esm/util/parentWalk.d.ts

@@ -14,7 +14,7 @@ export declare function findParentThatIs<T extends (a: IAnyStateTreeNode) => boo
  * Keying on the node is safe because nothing re-parents one — both `detach`
  * call sites hand the node straight to `scheduleDetachedDestroy` (ADR-069), so
  * a cached ancestor can only go stale by dying, which the `isAlive` check
- * catches. That is the difference from the three memos REJECTED_IDEAS records
+ * catches. That is the difference from the three memos agent-docs/architecture-decision-records/ records
  * removing: each keyed on something its caller had just allocated.
  */
 export declare function cachedParent<T>(cache: WeakMap<IAnyStateTreeNode, T>, node: IAnyStateTreeNode, finder: () => T, errorMsg: string): T;

package/esm/util/parentWalk.js

@@ -39,7 +39,7 @@ export function findParentThatIs(node, predicate) {
  * Keying on the node is safe because nothing re-parents one — both `detach`
  * call sites hand the node straight to `scheduleDetachedDestroy` (ADR-069), so
  * a cached ancestor can only go stale by dying, which the `isAlive` check
- * catches. That is the difference from the three memos REJECTED_IDEAS records
+ * catches. That is the difference from the three memos agent-docs/architecture-decision-records/ records
  * removing: each keyed on something its caller had just allocated.
  */
 export function cachedParent(cache, node, finder, errorMsg) {