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

package/esm/util/clampToContig.js

@@ -26,3 +26,22 @@ export function clampToContig(assembly, region) {
         ? { ...region, assemblyName: assembly.name, refName, start, end }
         : undefined;
 }
+/**
+ * `clampToContig` for a refName that may not be on the assembly at all, which
+ * is the shape a location nobody requested arrives in — a BAM's `nextRef`, an
+ * SA record's contig (REFNAME_NAMESPACES.md). `clampToContig` alone passes an
+ * unknown name through with nothing to clamp against, so it cannot tell "past
+ * the end of a contig we have" from "a contig we do not have", and both callers
+ * need that apart to say which happened.
+ */
+export function clampToListedContig(assembly, region) {
+    const refName = assembly.getCanonicalRefName2(region.refName);
+    const onAssembly = assembly.getRegionForRefName(refName) !== undefined;
+    return {
+        refName,
+        onAssembly,
+        region: onAssembly
+            ? clampToContig(assembly, { ...region, refName })
+            : undefined,
+    };
+}

package/esm/util/colorBits.d.ts

@@ -1,5 +1,7 @@
+import { abgrToCssRgba } from '@jbrowse/render-core/marks/colorFill';
 import type { Color } from './color-bits/index.ts';
 import type { Feature } from './simpleFeature.ts';
+export { abgrToCssRgba };
 export { alpha, blend, darken, formatHEX, formatHEXA, formatRGBA, getAlpha, getBlue, getGreen, getLuminance, getRed, lighten, newColor, parse, toHSLA, toRGBA, } from './color-bits/index.ts';
 export type { Color } from './color-bits/index.ts';
 /**
@@ -35,5 +37,4 @@ export declare function abgrRed(c: number): number;
 export declare function abgrGreen(c: number): number;
 export declare function abgrBlue(c: number): number;
 export declare function abgrAlpha(c: number): number;
-export declare function abgrToCssRgba(c: number): string;
 export declare function cssColorToNormalizedRgba(color: string): [number, number, number, number];

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;
@@ -110,6 +111,7 @@ export interface ActiveFetch {
  * passes a {@link createStatusChannel}, which is one volatile instead of two
  * fields and an action.
  */
+export type StopTokenRotation = ReturnType<typeof createStopTokenRotation>;
 export declare function createStopTokenRotation(self: IStateTreeNode, report: StatusReporter): {
     begin(): ActiveFetch;
     cancel: () => void;

package/esm/util/createStopTokenRotation.js

@@ -28,33 +28,6 @@ export function createStatusChannel() {
         },
     };
 }
-/**
- * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
- * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
- * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
- * `begin()` aborts the prior fetch's token and returns a fresh one plus an
- * `isCurrent()` guard that captures this run's token — gate every post-await
- * write on it and a superseded or torn-down fetch can never clobber fresher
- * data. The guard is the return value, so a caller can't forget to compare a
- * token by hand.
- *
- * `end()` in the run's `finally` is the other half, and for the same reason —
- * see {@link ActiveFetch.end} for the two things it does together.
- *
- * Owns the token mechanics and the status channel; the caller keeps its own
- * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
- * (so `cancelFetch` can reach it), `installFetch` one per installation (every
- * other fetch in the tree runs on that skeleton), and the synteny diagonalize
- * progress wrapper (`withDiagonalizeProgress`) directly.
- *
- * `report` is passed rather than read off `self`, so where the status lands is
- * the caller's decision and not a shape this imposes. A display passes itself —
- * its status fields are part of its own API, and one composing `FetchMixin`
- * passes the model-wide window along with them (see `StatusReporter`).
- * Anything with one operation to narrate and no status vocabulary of its own
- * passes a {@link createStatusChannel}, which is one volatile instead of two
- * fields and an action.
- */
 export function createStopTokenRotation(self, report) {
     let currentStopToken;
     // The host's window when it has one, so a display composing `FetchMixin` has
@@ -124,6 +97,13 @@ export function createStopTokenRotation(self, report) {
                 statusCallback: stream.statusCallback,
                 end() {
                     ended = true;
+                    // A completed fetch's token is released here, not only on supersede
+                    // or cancel — otherwise it pins its AbortSignal controllers (and blob
+                    // URL) until the next `begin()`, forever for a one-shot fetch that
+                    // succeeds and never reruns. `stopStopToken` is guarded, so the
+                    // superseded and cancelled runs that arrive here already-stopped cost
+                    // nothing.
+                    stopStopToken(stopToken);
                     if (openStream === stream) {
                         openStream = undefined;
                     }

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/fetchContext.d.ts

@@ -39,8 +39,8 @@ export interface FetchContext {
 }
 /**
  * Build a {@link FetchContext} over a live fetch's primitives. One
- * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
- * carries the same `callRpc` envelope.
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
  *
  * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
  * means a track or something under it.** `rpcSessionId` is declared by

package/esm/util/fetchContext.js

@@ -3,8 +3,8 @@ import { createStatusFanOut } from './progress.js';
 import { getRpcHost } from './sessionServices.js';
 /**
  * Build a {@link FetchContext} over a live fetch's primitives. One
- * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
- * carries the same `callRpc` envelope.
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
  *
  * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
  * means a track or something under it.** `rpcSessionId` is declared by

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
@@ -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;
@@ -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';
@@ -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,9 +44,9 @@ 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, 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';
@@ -69,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

@@ -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,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';
@@ -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';
@@ -142,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

@@ -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
@@ -24,11 +25,16 @@ 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).
+     *
+     * 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
@@ -129,7 +127,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
@@ -148,10 +146,10 @@ export interface InstallFetchOptions<TArgs, TResult> extends FetchPhases<TArgs,
      */
     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
@@ -159,9 +157,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?: () => 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 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 +181,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: 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 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 {};