@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/pluggableElementTypes/models/BaseTrackModel.js

@@ -1,22 +1,29 @@
 import { lazy } from 'react';
-import { types } from '@jbrowse/mobx-state-tree';
+import { addDisposer, getSnapshot, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import Save from '@mui/icons-material/Save';
-import { stringifyBED } from "./saveTrackFileTypes/bed.js";
-import { stringifyGBK } from "./saveTrackFileTypes/genbank.js";
-import { stringifyGFF3 } from "./saveTrackFileTypes/gff3.js";
-import { ConfigurationReference, getConf } from "../../configuration/index.js";
-import { adapterConfigCacheKey } from "../../data_adapters/util.js";
-import { getContainingView, getEnv, getSession } from "../../util/index.js";
-import { isSessionModelWithConfigEditing } from "../../util/types/index.js";
-import { ElementId } from "../../util/types/mst.js";
-const SaveTrackDataDlg = lazy(() => import("./components/SaveTrackData.js"));
-export function getCompatibleDisplays(self) {
+import { compareStructural, reaction } from 'mobx';
+import { ConfigurationReference, getConf } from '../../configuration/index.js';
+import { releaseAdapterSession, retainAdapterSession, } from '../../data_adapters/adapterSessionRefcount.js';
+import { adapterConfigCacheKey } from '../../data_adapters/dataAdapterCache.js';
+import { adapterByteLimit } from '../../rpc/byteBudget.js';
+import { getContainingView, getDialogHost, getEnv, getSession, } from '../../util/index.js';
+import { getConfAssemblyNamesOrNone, viewDisplayNames, } from '../../util/tracks.js';
+import { isSessionModelWithConfigEditing } from '../../util/types/index.js';
+import { ElementId } from '../../util/types/mst.js';
+import { displayTypesFedBy } from './baseTrackConfig.js';
+import { stringifyBED } from './saveTrackFileTypes/bed.js';
+import { stringifyGBK } from './saveTrackFileTypes/genbank.js';
+import { stringifyGFF3 } from './saveTrackFileTypes/gff3.js';
+const SaveTrackDataDlg = lazy(() => import('./components/SaveTrackData.js'));
+const DEFAULT_EXPORT_BYTE_LIMIT = 5_000_000;
+function getCompatibleDisplays(self) {
     const { pluginManager } = getEnv(self);
     const view = getContainingView(self);
-    const viewType = pluginManager.getViewType(view.type);
-    const compatTypes = new Set(viewType.displayTypes.map(d => d.name));
-    const displays = self.configuration.displays;
-    return displays.filter(d => compatTypes.has(d.type));
+    const { configuration } = self;
+    const viewDisplays = viewDisplayNames(pluginManager, view.type);
+    const fed = new Set(displayTypesFedBy(pluginManager, configuration.type, configuration.adapter));
+    const displays = configuration.displays;
+    return displays.filter(d => viewDisplays.has(d.type) && fed.has(d.type));
 }
 function getDisplayConf(displays, displayId) {
     const displayConf = displays.find(d => d.displayId === displayId);
@@ -25,102 +32,392 @@ function getDisplayConf(displays, displayId) {
     }
     return displayConf;
 }
+/**
+ * #stateModel BaseTrackModel
+ * #category track
+ *
+ * these MST models only exist for tracks that are *shown*. they should contain
+ * only UI state for the track, and have a reference to a track configuration.
+ * note that multiple displayed tracks could use the same configuration.
+ */
 export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
     return types
         .model(trackType, {
+        /**
+         * #property
+         */
         id: ElementId,
+        /**
+         * #property
+         */
         type: types.literal(trackType),
+        /**
+         * #property
+         */
         configuration: ConfigurationReference(baseTrackConfig),
-        minimized: false,
-        pinned: false,
+        /**
+         * #property
+         */
+        minimized: types.stripDefault(types.boolean, false),
+        /**
+         * #property
+         */
+        pinned: types.stripDefault(types.boolean, false),
+        /**
+         * #property
+         * The runtime plugin union (`pluggableMstType`) is typed only as
+         * `IAnyType`, erasing the element to `any`. Assert the concrete
+         * `DisplayModel` instance every registered display satisfies so reads
+         * (`activeDisplay`, `trackMenuItems`) are checked;
+         * create/snapshot stay `unknown` since the union's snapshot shape is
+         * genuinely dynamic (`replaceDisplay` writes a partial snapshot).
+         */
         displays: types.array(pm.pluggableMstType('display', 'stateModel')),
     })
+        .volatile(() => ({
+        /**
+         * Whether a height-resize gesture is in progress on this track. Set by
+         * whichever handle owns the drag — the view's track resize handle, or a
+         * handle a display draws inside itself — and read by displays that sit an
+         * expensive per-frame layer out of the gesture.
+         *
+         * On the track rather than the display because the gesture belongs to the
+         * container running it, not to whatever display happens to be active: the
+         * view can bracket a drag without knowing which display it landed on, and
+         * two handles on one track share one flag rather than racing to clear
+         * each other's.
+         */
+        resizing: false,
+    }))
         .views(self => ({
+        /**
+         * #getter
+         */
         get trackId() {
             return self.configuration.trackId;
         },
+        /**
+         * #getter
+         * determines which webworker to send the track to, currently based on trackId
+         */
         get rpcSessionId() {
-            const adapter = getConf(self, 'adapter');
-            return adapter ? adapterConfigCacheKey(adapter) : this.trackId;
+            // no `adapter ? … : this.trackId` fallback: the slot always materializes
+            // an object (see `adapterConfig` below, and
+            // adapterSlotAlwaysMaterializes.test.ts), so the trackId arm was dead and
+            // read as though a track could have no adapter.
+            //
+            // `this`, not `self` — `adapterConfig` is declared in this same `.views`
+            // block, so `self` does not carry it yet.
+            return adapterConfigCacheKey(this.adapterConfig);
         },
+        /**
+         * #getter
+         */
         get name() {
-            return getConf(self, 'name');
+            return getConf(self, 'name') || this.trackId;
         },
+        /**
+         * #getter
+         * this track's own name-search index, from the `textSearching`
+         * sub-config. `undefined` when the track has none.
+         *
+         * The path, not a bare `'textSearchAdapter'`: the slot is
+         * `textSearching.textSearchAdapter` (`baseTrackConfig.ts`), and a bare
+         * read of a name no schema declares returns `undefined` and reports
+         * nothing at any layer, so this getter answered `undefined` for every
+         * track ever configured with one. `TextSearchManager` reads the same slot
+         * by hand-walking `conf.textSearching.textSearchAdapter`, which is why
+         * nothing noticed.
+         */
         get textSearchAdapter() {
-            return getConf(self, 'textSearchAdapter');
+            return getConf(self, ['textSearching', 'textSearchAdapter']);
         },
+        /**
+         * #getter
+         */
         get adapterConfig() {
+            // Annotated, not left to infer `getConf`'s `any`, which switches off
+            // checking at every reader downstream.
+            //
+            // NOT `| undefined`, which was tried and measured. `adapter` is a bare
+            // `types.union` of the registered adapter schemas
+            // (`pluggableConfigSchemaType`) with no `maybe` and no default — which
+            // looks absent-able, but every member is an all-optional config schema,
+            // so MST creates the first one rather than leaving the slot empty. Probed
+            // both ways: omitting `adapter` entirely, and passing it explicitly as
+            // `undefined`, each read back as an object. So `| undefined` propagates a
+            // case that cannot happen to ~33 call sites.
             return getConf(self, 'adapter');
         },
-        get viewMenuActions() {
-            return self.displays.flatMap(d => d.viewMenuActions);
+        /**
+         * #getter
+         * a shown track always has at least one display
+         */
+        get activeDisplay() {
+            return self.displays[0];
         },
-        get canConfigure() {
-            const session = getSession(self);
-            const { sessionTracks, adminMode } = session;
-            return (isSessionModelWithConfigEditing(session) &&
-                (adminMode || sessionTracks?.find(t => t.trackId === this.trackId)));
+        /**
+         * #getter
+         * the configured displays the CONTAINING VIEW can draw and the track's
+         * adapter feeds, which is the set `replaceDisplay` will accept
+         *
+         * `configuration.displays` is not that set: baseTrackConfig injects one
+         * entry per display type registered for the track TYPE, across every
+         * view type, so a VariantTrack carries a ChordVariantDisplay a linear
+         * view cannot draw. The track menu's own "Display types" submenu has
+         * always filtered them; this exposes the same list to code, because the
+         * alternative is every caller re-deriving it from the plugin manager.
+         */
+        get compatibleDisplays() {
+            return getCompatibleDisplays(self);
         },
     }))
         .views(self => ({
-        get adapterType() {
-            const { adapterConfig } = self;
-            if (!adapterConfig) {
-                throw new Error(`no adapter configuration provided for ${self.type}`);
+        /**
+         * #getter
+         * Set when this track's file and one of its assemblies share no reference
+         * name at all — the `1/2/3` file loaded against a `chr1/chr2/chr3`
+         * assembly, which otherwise draws an empty track and says nothing.
+         *
+         * The verdict is reached in `loadRefNameMap`, which is the only place both
+         * name sets are in scope, and recorded on the *assembly* because nothing
+         * in the assembly manager can reach a track (the session is a sibling
+         * subtree, so `getSession` from there finds only the root). The lookup
+         * inverts that: the record is keyed by adapter cache key, which is exactly
+         * what `rpcSessionId` already is, so a track finds its own with no
+         * plumbing in between.
+         *
+         * The names come from `getConfAssemblyNamesOrNone`, not from a raw
+         * `assemblyNames` slot read: this model is shared by every track type, and
+         * `ReferenceSequenceTrack`'s schema does not declare that slot — it names
+         * its assembly by being the `sequence` of one. A raw read there returns
+         * `undefined` with no diagnostic at any layer, so the getter was inert for
+         * that one track type while looking like it worked. The `OrNone` half is
+         * what keeps this total: it runs on every render of every track label, and
+         * an unanswerable question must not become a thrown getter.
+         *
+         * Diagnostic only. It gates nothing, and a track carrying one still loads,
+         * still fetches and still draws whatever it can.
+         */
+        get refNameMismatch() {
+            const { assemblyManager } = getSession(self);
+            for (const name of getConfAssemblyNamesOrNone(self.configuration)) {
+                // screened with `has` first: `get` reports a name the session lacks
+                // to Core-handleUnrecognizedAssembly, and this getter runs on every
+                // render of every track label. A track config is free to name an
+                // assembly the session has no configuration for, and asking about it
+                // must not tell every installed plugin to go resolve it.
+                const mismatch = assemblyManager.has(name)
+                    ? assemblyManager.get(name)?.getRefNameMismatch(self.rpcSessionId)
+                    : undefined;
+                if (mismatch) {
+                    return mismatch;
+                }
             }
-            const adapterType = pm.getAdapterType(adapterConfig.type);
-            if (!adapterType) {
-                throw new Error(`unknown adapter type ${adapterConfig.type}`);
+            return undefined;
+        },
+        /**
+         * #getter
+         */
+        get adapterType() {
+            // Checks the adapter's `type`, not the adapter config's presence. The
+            // config is always an object (see `adapterConfig`), so the old
+            // `if (!adapterConfig) throw` could not fire; what genuinely can be
+            // missing is `type`, and it is a string only by convention since the slot
+            // holds an arbitrary sub-config. Unchecked it reaches
+            // `getAdapterType(undefined)`, which does throw — but as
+            // `AdapterType 'undefined' is not registered`, i.e. as a missing plugin,
+            // sending the reader after a build problem instead of at the config
+            // that names no adapter type.
+            const { type } = self.adapterConfig;
+            if (typeof type !== 'string') {
+                throw new Error(`no adapter type in the adapter configuration for ${self.type} (got ${typeof type})`);
             }
-            return adapterType;
+            return pm.getAdapterType(type);
         },
     }))
+        .actions(self => {
+        let persistTimeout;
+        // Reads the config when it fires rather than when it was scheduled, so
+        // what reaches the session is the config as it stands, whatever swapped
+        // the resolved node inside the wait.
+        function persistConfiguration() {
+            persistTimeout = undefined;
+            const session = getSession(self);
+            if (isSessionModelWithConfigEditing(session)) {
+                session.updateTrackConfiguration(getSnapshot(self.configuration));
+            }
+        }
+        return {
+            /**
+             * #action
+             * Write the config to the session now rather than after the 400 ms
+             * wait, for an edit that has to be undoable the moment it lands.
+             */
+            persistConfigurationNow() {
+                clearTimeout(persistTimeout);
+                persistConfiguration();
+            },
+            /**
+             * #action
+             */
+            setPinned(flag) {
+                self.pinned = flag;
+            },
+            /**
+             * #action
+             */
+            setMinimized(flag) {
+                self.minimized = flag;
+            },
+            /**
+             * #action
+             */
+            setResizing(flag) {
+                self.resizing = flag;
+            },
+            /**
+             * #action
+             * `applyDisplaySettings` on the display being drawn (`activeDisplay`,
+             * which a shown track always has — this is not meaningful on a bare
+             * config node) — the track-level entry for "restyle this track in
+             * place" (a session spec's inline keys, an agent's settings bag). Only
+             * that one display: settings vocabularies are per display type, so
+             * broadcasting one bag across a track's other displays would mis-route
+             * keys; address a non-active display directly if that is what you mean.
+             * See BaseDisplayModel for the routing and the `allowSetters` opt-in.
+             */
+            applyDisplaySettings(settings, options) {
+                return self.activeDisplay.applyDisplaySettings(settings, options);
+            },
+            /**
+             * #action
+             */
+            replaceDisplay(oldDisplayId, newDisplayId, initialSnapshot = {}) {
+                const idx = self.displays.findIndex(d => d.configuration.displayId === oldDisplayId);
+                if (idx === -1) {
+                    throw new Error(`could not find display id ${oldDisplayId} to replace`);
+                }
+                const displayConf = getDisplayConf(self.configuration.displays, newDisplayId);
+                // same interception showTrackGeneric makes: a registered-but-unloaded
+                // display would otherwise fail as an opaque union mismatch below
+                pm.resolveDisplayTypeRecord(displayConf.type)?.assertStateModelLoaded();
+                self.displays[idx] = {
+                    ...initialSnapshot,
+                    type: displayConf.type,
+                    configuration: newDisplayId,
+                };
+            },
+            /**
+             * #action
+             * Persist any config-schema mutation (quick track-menu edits calling
+             * `setSlot` directly, or the full Settings dialog) back to the session,
+             * debounced, mirroring ConfigurationEditorWidget's own save. Both savers
+             * intentionally coexist — this one covers direct setSlot edits on a shown
+             * track, the widget covers an unshown track edited from the selector (no
+             * BaseTrackModel). When both fire they compute an identical delta, deduped
+             * in updateTrackConfiguration; don't drop one to "simplify". `reaction`
+             * (not `autorun`) on purpose: `self.configuration` is defined
+             * immediately on attach, unlike ConfigurationEditorWidget's `target`
+             * (which starts undefined), so an autorun's guaranteed first run would
+             * otherwise schedule a spurious flush for every track ever shown, even
+             * completely untouched ones — `reaction` only fires on an actual change.
+             *
+             * `equals: compareStructural` is load-bearing, not an optimization:
+             * `self.configuration` is a re-resolving reference, and persisting a save
+             * can swap the resolved node identity (the delta path reconciles in place
+             * but still churns once, and a session without deltas replaces the frozen
+             * `jbrowse.tracks` entry, rehydrating a brand-new MST node every write).
+             * Referential comparison would treat every such swap as a fresh change
+             * and re-fire the save, an unbounded debounced loop. Structural
+             * comparison settles once the content stops changing.
+             */
+            afterAttach() {
+                addDisposer(self, reaction(() => getSnapshot(self.configuration), () => {
+                    clearTimeout(persistTimeout);
+                    persistTimeout = setTimeout(persistConfiguration, 400);
+                }, { equals: compareStructural }));
+                addDisposer(self, () => {
+                    clearTimeout(persistTimeout);
+                });
+                // Hold a claim on this track's rpcSessionId for as long as the track is
+                // open, so closing the last track using an adapter config evicts that
+                // adapter from the worker's dataAdapterCache. Without this nothing in
+                // the app ever reaches CoreFreeResources, and an adapter — with its
+                // parsed chunks, or in the unindexed case its whole parsed file — is
+                // reachable from module scope for as long as the worker lives, which no
+                // amount of garbage collection can help with.
+                //
+                // The id is tracked by reaction rather than captured once: rpcSessionId
+                // is derived from the adapter config, which a settings edit can change
+                // under a live track, and releasing an id we never retained would free
+                // an adapter another track is still using.
+                const { rpcManager } = getSession(self);
+                let retained = self.rpcSessionId;
+                retainAdapterSession(rpcManager, retained);
+                addDisposer(self, reaction(() => self.rpcSessionId, next => {
+                    if (next !== retained) {
+                        const previous = retained;
+                        retained = next;
+                        retainAdapterSession(rpcManager, next);
+                        void releaseAdapterSession(rpcManager, previous);
+                    }
+                }));
+                addDisposer(self, () => {
+                    void releaseAdapterSession(rpcManager, retained);
+                });
+            },
+        };
+    })
         .actions(self => ({
-        setPinned(flag) {
-            self.pinned = flag;
-        },
-        setMinimized(flag) {
-            self.minimized = flag;
-        },
-        showDisplay(displayId, initialSnapshot = {}) {
-            const displays = self.configuration.displays;
-            const displayConf = getDisplayConf(displays, displayId);
-            const displayType = pm.getDisplayType(displayConf.type);
-            if (!displayType) {
-                throw new Error(`unknown display type ${displayConf.type}`);
+        /**
+         * #action
+         * The awaitable sibling of `replaceDisplay`: loads the target display's
+         * state model, then swaps to it carrying whatever settings the outgoing
+         * display can hand over.
+         *
+         * `replaceDisplay` stays a plain sync action and ASSERTS the model is
+         * loaded, and every display state model in this tree is a dynamic import
+         * until something shows one — so a caller that has not already shown the
+         * target needs this. Named like `launchTrack`, which is the same problem
+         * one level up.
+         */
+        async launchDisplay(displayId) {
+            const { type } = getDisplayConf(self.configuration.displays, displayId);
+            await pm.resolveDisplayTypeRecord(type)?.loadStateModel();
+            if (isAlive(self)) {
+                self.replaceDisplay(self.activeDisplay.configuration.displayId, displayId, self.activeDisplay.getPortableSettings?.(displayId) ?? {});
             }
-            self.displays.push(displayType.stateModel.create({
-                ...initialSnapshot,
-                type: displayConf.type,
-                configuration: displayId,
-            }));
         },
-        hideDisplay(displayId) {
-            const displaysToRemove = self.displays.filter(d => d.configuration.displayId === displayId);
-            for (const display of displaysToRemove) {
-                self.displays.remove(display);
-            }
-            return displaysToRemove.length;
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * Whether this track's adapter writes an export format itself, rather
+         * than the save dialog rebuilding one out of rendered features. A claim
+         * about the adapter type, not about a given format — the fetch still
+         * falls back when the adapter declines the one that was asked for.
+         */
+        get exportsDataViaAdapter() {
+            return getEnv(self)
+                .pluginManager.getAdapterType(getConf(self, ['adapter']).type)
+                .adapterCapabilities.includes('exportData');
         },
-        replaceDisplay(oldDisplayId, newDisplayId, initialSnapshot = {}) {
-            const idx = self.displays.findIndex(d => d.configuration.displayId === oldDisplayId);
-            if (idx === -1) {
-                throw new Error(`could not find display id ${oldDisplayId} to replace`);
-            }
-            const displays = self.configuration.displays;
-            const displayConf = getDisplayConf(displays, newDisplayId);
-            const displayType = pm.getDisplayType(displayConf.type);
-            if (!displayType) {
-                throw new Error(`unknown display type ${displayConf.type}`);
-            }
-            self.displays.splice(idx, 1, {
-                ...initialSnapshot,
-                type: displayConf.type,
-                configuration: newDisplayId,
-            });
+        /**
+         * #getter
+         * The size in bytes above which "Save track data" asks for confirmation
+         * before fetching. Uses the adapter's `fetchSizeLimit` where it declares
+         * one, so a save asks at the same size at which the track's display
+         * refuses to render; otherwise a default. The default is generous
+         * because exceeding it only prompts for confirmation, and the user
+         * explicitly requested the data.
+         */
+        get exportByteLimit() {
+            return adapterByteLimit(getConf(self, ['adapter', 'fetchSizeLimit']), DEFAULT_EXPORT_BYTE_LIMIT);
         },
-    }))
-        .views(() => ({
+        /**
+         * #method
+         */
         saveTrackFileFormatOptions() {
             return {
                 gff3: {
@@ -143,27 +440,39 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
         },
     }))
         .views(self => ({
+        /**
+         * #getter
+         * the "Save track data" menu entry. Kept separate from trackMenuItems so
+         * consumers (e.g. the LGV track-label menu) can place it alongside the
+         * session's Settings/Copy/Delete track actions without fishing it back out
+         * of the general list
+         */
+        get saveTrackDataMenuItem() {
+            return {
+                label: 'Save track data',
+                icon: Save,
+                priority: 998,
+                onClick: () => {
+                    getDialogHost(self).queueDialog(handleClose => [
+                        SaveTrackDataDlg,
+                        {
+                            model: self,
+                            handleClose,
+                        },
+                    ]);
+                },
+            };
+        },
+        /**
+         * #method
+         */
         trackMenuItems() {
             const menuItems = self.displays.flatMap(d => d.trackMenuItems());
-            const shownId = self.displays[0].configuration.displayId;
-            const compatDisp = getCompatibleDisplays(self);
+            const shownId = self.activeDisplay.configuration.displayId;
+            const compatDisp = self.compatibleDisplays;
             return [
                 ...menuItems,
-                {
-                    label: 'Save track data',
-                    icon: Save,
-                    priority: 998,
-                    onClick: () => {
-                        getSession(self).queueDialog(handleClose => [
-                            SaveTrackDataDlg,
-                            {
-                                model: self,
-                                handleClose,
-                            },
-                        ]);
-                    },
-                },
-                ...(compatDisp.length > 1
+                ...(compatDisp.length > 1 && shownId
                     ? [
                         {
                             type: 'subMenu',
@@ -176,9 +485,20 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
                                     label: displayType.displayName,
                                     helpText: displayType.helpText,
                                     checked: d.displayId === shownId,
+                                    // opts out of the checkbox/radio "stay open" default:
+                                    // every row above this submenu came from the display
+                                    // being replaced, so leaving the menu up would keep a
+                                    // list of items built against a destroyed MST node
+                                    keepMenuOpen: false,
+                                    // launchDisplay, because the chosen display's state
+                                    // model may still be a dynamic import away
                                     onClick: () => {
                                         if (d.displayId !== shownId) {
-                                            self.replaceDisplay(shownId, d.displayId, self.displays[0].getPortableSettings?.() ?? {});
+                                            void self
+                                                .launchDisplay(d.displayId)
+                                                .catch((e) => {
+                                                getSession(self).notifyError(`${e}`, e);
+                                            });
                                         }
                                     },
                                 };
@@ -188,16 +508,5 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
                     : []),
             ];
         },
-    }))
-        .postProcessSnapshot(snap => {
-        if (!snap) {
-            return snap;
-        }
-        const { minimized, pinned, ...rest } = snap;
-        return {
-            ...rest,
-            ...(minimized ? { minimized } : {}),
-            ...(pinned ? { pinned } : {}),
-        };
-    });
+    }));
 }