@jbrowse/core 5.0.0-beta.13 → 5.0.0-beta.14

package/esm/data_adapters/BaseAdapter/rowSources.d.ts

@@ -2,7 +2,7 @@ import type { BaseOptions } from './types.ts';
 /**
  * #api
  * One row an adapter lists: `name` is a value of the listing's field, and
- * `label` and `color` are what the adapter names and colours that row with.
+ * `label` and `color` are what the adapter names and colors that row with.
  */
 export interface ListedRowSource {
     name: string;
@@ -13,7 +13,7 @@ export interface ListedRowSource {
  * #api
  * Every row an adapter has, in its own order, whatever the loaded regions hold,
  * so a row display gives a row with nothing in view its place, label and
- * colour.
+ * color.
  */
 export interface RowSourceListing {
     /** The feature field the listed names are values of: `source` on a multi-BigWig, `alignments` on a MAF, whose per-species record is keyed by them. */

package/esm/data_adapters/BaseAdapter/types.d.ts

@@ -7,6 +7,7 @@ export interface BaseOptions {
     sessionId?: string;
     statusCallback?: StatusCallback;
     notices?: string[];
+    facts?: Record<string, unknown>;
     headers?: Record<string, string>;
     assemblyName?: string;
     lodMode?: LodTier;

package/esm/data_adapters/CytobandAdapter/configSchema.d.ts

@@ -1,5 +1,7 @@
 /**
  * #config CytobandAdapter
+ * Reads an assembly's cytoband file, which the linear genome view draws as
+ * ideogram banding in its overview bar.
  *
  * #example
  * Goes on an ASSEMBLY, under `cytobands` — not on a track. It draws the

package/esm/data_adapters/CytobandAdapter/configSchema.js

@@ -1,6 +1,8 @@
 import { ConfigurationSchema, expandUriShorthand, } from '../../configuration/index.js';
 /**
  * #config CytobandAdapter
+ * Reads an assembly's cytoband file, which the linear genome view draws as
+ * ideogram banding in its overview bar.
  *
  * #example
  * Goes on an ASSEMBLY, under `cytobands` — not on a track. It draws the
@@ -37,6 +39,9 @@ const configSchema = ConfigurationSchema('CytobandAdapter', {
     },
 }, {
     explicitlyTyped: true,
+    closed: true,
+    // desktop's open-sequence dialog wrote the plural through v4.3
+    retired: { cytobandsLocation: cytobandLocation => ({ cytobandLocation }) },
     /**
      * #preProcessSnapshot
      *

package/esm/data_adapters/dataAdapterCache.d.ts

@@ -38,20 +38,19 @@ export type getSubAdapterType = (adapterConfigSnap: ConfigSnap) => ReturnType<ty
  * other session still claims. Reached from the CoreFreeResources RPC when the
  * last track using an adapter config closes.
  *
- * Deleting the key is the whole reclamation: the cache is the only strong
- * reference to an adapter, so once it goes the instance and everything it holds
- * — a whole parsed GFF3, a BAM chunk cache — become unreachable and are
- * collected normally. There is nothing to free by hand.
+ * Deleting the key makes the instance unreachable from here, and for most
+ * adapters that is the whole reclamation: a parsed GFF3 goes with it.
  *
- * "Collected normally" is not the same as "collected now", and for the indexed
- * adapters it is not even soon. @gmod/bam, @gmod/cram and @gmod/tabix each hold
- * their parsed chunks in a SharedReadCache that sweeps itself on a setInterval,
- * and a pending timer is a GC root — so the instance stays reachable through its
- * own sweep timer until that sweep empties the cache and stops itself, three
- * minutes later. Measured: closing a panned alignments track reclaims nothing at
- * the time it happens, and the worker falls from 296 MB to 7 MB four minutes on.
- * Deleting the key is still the only thing to do here; just don't read a heap
- * immediately after a close and conclude this did nothing.
+ * The indexed adapters are the exception, which is why an evicted adapter is
+ * also told so (`freeResources`). @gmod/bam, @gmod/cram and @gmod/tabix each
+ * hold their parsed chunks in a SharedReadCache charged to the shared budget,
+ * and the budget credits a dropped cache back only once the collector has
+ * taken it. A run that opens and closes a track per image has no GC to wait
+ * for. `jb2export batch` drew a callset from CRAM slices of long reads at
+ * about a record every two seconds, and before @gmod/shared-read-cache 2.1 two
+ * of its four processes reached the 4 GB heap limit 135 s in, with the budget
+ * at 3,100 MB against its 1,024 MB limit: the budget left each of 54 caches
+ * its last entry. 2.1 keeps one entry per budget instead.
  *
  * The refcount is what makes this safe to call on any track close: an adapter
  * pulled in as a sub-adapter carries its parent's sessionId (getSubAdapter
@@ -61,5 +60,18 @@ export type getSubAdapterType = (adapterConfigSnap: ConfigSnap) => ReturnType<ty
 export declare function freeAdapterResources(args: {
     sessionId?: string;
 }): Promise<void>;
+/** How many adapter requests the cache has answered. */
+export declare function adapterRequests(): number;
+/**
+ * Evict every cached adapter `keep` declines, each told to free what it holds,
+ * whatever sessions claim it. `keep` sees the settled adapters most recently
+ * requested first, each with the {@link adapterRequests} count at its latest
+ * request. For a host with no tracks to close, such as `@jbrowse/tables`,
+ * which would otherwise keep an adapter, its parsed index and its share of the
+ * decoded-bytes budget for every file it ever read.
+ */
+export declare function keepAdapters(keep: (dataAdapter: AnyDataAdapter, lastRequest: number) => boolean): Promise<void>;
+/** How many adapters the cache holds, failed and pending ones included. */
+export declare function cachedAdapterCount(): number;
 export declare function clearAdapterCache(): void;
 export {};

package/esm/data_adapters/dataAdapterCache.js

@@ -24,15 +24,21 @@ function readsReference(pluginManager, adapterConfig) {
 }
 // Pruned by storeWithEvict (rejections) and by freeAdapterResources, which the
 // CoreFreeResources RPC reaches when the last track holding an adapter config is
-// closed (releaseAdapterSession). There is still no size bound: an adapter
-// whose track stays open lives as long as its worker, by design.
-let adapterCache = {};
+// closed (releaseAdapterSession). The browser sets no size bound: an adapter
+// whose track stays open lives as long as its worker, by design. A host with no
+// tracks to close bounds it with keepAdapters. Ordered least recently
+// requested first.
+let adapterCache = new Map();
+let requests = 0;
+const lastRequests = new WeakMap();
 /** stores a promise in the cache and auto-evicts if it rejects */
 function storeWithEvict(key, p) {
     p.catch(() => {
-        delete adapterCache[key];
+        if (adapterCache.get(key) === p) {
+            adapterCache.delete(key);
+        }
     });
-    adapterCache[key] = p;
+    adapterCache.set(key, p);
     return p;
 }
 async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence) {
@@ -65,8 +71,13 @@ function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, seque
     const cacheKey = keyedSequence
         ? `${configKey}|${adapterConfigCacheKey(keyedSequence)}`
         : configKey;
-    return (adapterCache[cacheKey] ??
-        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence)));
+    const cached = adapterCache.get(cacheKey);
+    if (cached) {
+        adapterCache.delete(cacheKey);
+        adapterCache.set(cacheKey, cached);
+        return cached;
+    }
+    return storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence));
 }
 /**
  * instantiate a data adapter, or return a cached one with the same config.
@@ -77,6 +88,7 @@ function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, seque
 export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter) {
     const ret = await getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter);
     ret.sessionIds.add(sessionId);
+    lastRequests.set(ret, ++requests);
     return ret;
 }
 /**
@@ -84,20 +96,19 @@ export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot
  * other session still claims. Reached from the CoreFreeResources RPC when the
  * last track using an adapter config closes.
  *
- * Deleting the key is the whole reclamation: the cache is the only strong
- * reference to an adapter, so once it goes the instance and everything it holds
- * — a whole parsed GFF3, a BAM chunk cache — become unreachable and are
- * collected normally. There is nothing to free by hand.
+ * Deleting the key makes the instance unreachable from here, and for most
+ * adapters that is the whole reclamation: a parsed GFF3 goes with it.
  *
- * "Collected normally" is not the same as "collected now", and for the indexed
- * adapters it is not even soon. @gmod/bam, @gmod/cram and @gmod/tabix each hold
- * their parsed chunks in a SharedReadCache that sweeps itself on a setInterval,
- * and a pending timer is a GC root — so the instance stays reachable through its
- * own sweep timer until that sweep empties the cache and stops itself, three
- * minutes later. Measured: closing a panned alignments track reclaims nothing at
- * the time it happens, and the worker falls from 296 MB to 7 MB four minutes on.
- * Deleting the key is still the only thing to do here; just don't read a heap
- * immediately after a close and conclude this did nothing.
+ * The indexed adapters are the exception, which is why an evicted adapter is
+ * also told so (`freeResources`). @gmod/bam, @gmod/cram and @gmod/tabix each
+ * hold their parsed chunks in a SharedReadCache charged to the shared budget,
+ * and the budget credits a dropped cache back only once the collector has
+ * taken it. A run that opens and closes a track per image has no GC to wait
+ * for. `jb2export batch` drew a callset from CRAM slices of long reads at
+ * about a record every two seconds, and before @gmod/shared-read-cache 2.1 two
+ * of its four processes reached the 4 GB heap limit 135 s in, with the budget
+ * at 3,100 MB against its 1,024 MB limit: the budget left each of 54 caches
+ * its last entry. 2.1 keeps one entry per budget instead.
  *
  * The refcount is what makes this safe to call on any track close: an adapter
  * pulled in as a sub-adapter carries its parent's sessionId (getSubAdapter
@@ -109,20 +120,53 @@ export async function freeAdapterResources(args) {
     if (!sessionId) {
         return;
     }
-    for (const [cacheKey, cacheEntryP] of Object.entries(adapterCache)) {
+    for (const [cacheKey, cacheEntryP] of [...adapterCache]) {
         try {
             const cacheEntry = await cacheEntryP;
             cacheEntry.sessionIds.delete(sessionId);
             if (cacheEntry.sessionIds.size === 0) {
-                delete adapterCache[cacheKey];
+                evict(cacheKey, cacheEntryP);
+                cacheEntry.dataAdapter.freeResources();
             }
         }
         catch (e) {
             console.error(`dataAdapterCache: evicting failed adapter "${cacheKey}"`, e);
-            delete adapterCache[cacheKey];
+            evict(cacheKey, cacheEntryP);
         }
     }
 }
+function evict(cacheKey, entry) {
+    if (adapterCache.get(cacheKey) === entry) {
+        adapterCache.delete(cacheKey);
+    }
+}
+/** How many adapter requests the cache has answered. */
+export function adapterRequests() {
+    return requests;
+}
+/**
+ * Evict every cached adapter `keep` declines, each told to free what it holds,
+ * whatever sessions claim it. `keep` sees the settled adapters most recently
+ * requested first, each with the {@link adapterRequests} count at its latest
+ * request. For a host with no tracks to close, such as `@jbrowse/tables`,
+ * which would otherwise keep an adapter, its parsed index and its share of the
+ * decoded-bytes budget for every file it ever read.
+ */
+export async function keepAdapters(keep) {
+    const cached = [...adapterCache].reverse();
+    const settled = await Promise.all(cached.map(([, entry]) => entry.catch(() => undefined)));
+    cached.forEach(([cacheKey, entry], i) => {
+        const adapter = settled[i];
+        if (adapter && !keep(adapter.dataAdapter, lastRequests.get(adapter) ?? 0)) {
+            evict(cacheKey, entry);
+            adapter.dataAdapter.freeResources();
+        }
+    });
+}
+/** How many adapters the cache holds, failed and pending ones included. */
+export function cachedAdapterCount() {
+    return adapterCache.size;
+}
 export function clearAdapterCache() {
-    adapterCache = {};
+    adapterCache = new Map();
 }

package/esm/data_adapters/getFeatureAdapter.d.ts

@@ -22,3 +22,12 @@ export declare function getFeatureAdapter({ pluginManager, sessionId, adapterCon
  * undefined, so callers get a definite type and no cast.
  */
 export declare function getFeatureAdapterOrThrow(args: GetFeatureAdapterArgs): Promise<BaseFeatureDataAdapter>;
+/**
+ * The cached adapter a `@jbrowse/tables` read uses, which every tables
+ * lookup goes through. A `READS_REFERENCE` adapter is keyed on its
+ * config and `sequenceAdapter`, so a lookup without the one the read uses
+ * builds a second instance with its own index.
+ */
+export declare function tablesAdapter(pluginManager: PluginManager, adapterConfig: Record<string, unknown>, sequenceAdapter: Record<string, unknown> | undefined): Promise<import("./BaseAdapter/util.ts").AnyDataAdapter>;
+/** {@link tablesAdapter}, refusing an adapter that serves no features. */
+export declare function tablesFeatureAdapter(pluginManager: PluginManager, adapterConfig: Record<string, unknown>, sequenceAdapter: Record<string, unknown> | undefined): Promise<BaseFeatureDataAdapter<import("../configuration/types.ts").AnyConfigurationModel> | BaseFeatureDataAdapter<import("../configuration/types.ts").AnyConfigurationModel> | import("./BaseAdapter/BaseSequenceAdapter.ts").BaseSequenceAdapter<import("../configuration/types.ts").AnyConfigurationModel>>;

package/esm/data_adapters/getFeatureAdapter.js

@@ -25,3 +25,20 @@ export async function getFeatureAdapterOrThrow(args) {
     }
     return dataAdapter;
 }
+/**
+ * The cached adapter a `@jbrowse/tables` read uses, which every tables
+ * lookup goes through. A `READS_REFERENCE` adapter is keyed on its
+ * config and `sequenceAdapter`, so a lookup without the one the read uses
+ * builds a second instance with its own index.
+ */
+export async function tablesAdapter(pluginManager, adapterConfig, sequenceAdapter) {
+    return (await getAdapter(pluginManager, 'tables', adapterConfig, sequenceAdapter)).dataAdapter;
+}
+/** {@link tablesAdapter}, refusing an adapter that serves no features. */
+export async function tablesFeatureAdapter(pluginManager, adapterConfig, sequenceAdapter) {
+    const adapter = await tablesAdapter(pluginManager, adapterConfig, sequenceAdapter);
+    if (!isFeatureAdapter(adapter)) {
+        throw new Error(`adapter "${adapterConfig.type}" is not a feature adapter`);
+    }
+    return adapter;
+}

package/esm/pluggableElementTypes/models/BaseConnectionModelFactory.d.ts

@@ -3,6 +3,8 @@ import type { AnyConfigurationModel } from '../../configuration/index.ts';
 type TrackConf = AnyConfigurationModel | Record<string, unknown>;
 /**
  * #stateModel BaseConnectionModel
+ * Holds the tracks a connection has loaded. Each connection type overrides
+ * `connect` to fetch them from its source.
  */
 declare function stateModelFactory(pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
     /**

package/esm/pluggableElementTypes/models/BaseConnectionModelFactory.js

@@ -3,6 +3,8 @@ import { ConfigurationReference, readConfObject, } from '../../configuration/ind
 import configSchema from './baseConnectionConfig.js';
 /**
  * #stateModel BaseConnectionModel
+ * Holds the tracks a connection has loaded. Each connection type overrides
+ * `connect` to fetch them from its source.
  */
 function stateModelFactory(pluginManager) {
     return types

package/esm/pluggableElementTypes/models/BaseDisplayModel.d.ts

@@ -655,6 +655,21 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
      * #method
      */
     trackMenuItems(): MenuItem[];
+    /**
+     * #method
+     * What a config says that cannot be drawn as written: by default the
+     * schema's rules over its color objects and `scales.y`, the ones
+     * `jbrowse validate` runs. A display with rules of its own overrides it.
+     * `plotProblems` asks it of a draft and `notices` of the live config,
+     * so Edit plot and the corner never disagree.
+     */
+    configProblemsOf(conf: AnyConfigurationModel): string[];
+    /**
+     * #getter
+     * What the loaded data says beside the config, such as a field no
+     * fetched feature carries. None unless a display overrides it.
+     */
+    readonly liveNotices: string[];
 } & {
     /**
      * #action
@@ -689,9 +704,11 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
      * were applied. Each key runs through the display config schema's
      * `preProcessSnapshot` (shorthand expansions and legacy-key migrations,
      * as `showTrackGeneric` applies to a session spec's inline track keys),
-     * then writes the matching config slot. A key naming a sub-schema
-     * (`facet`, `color`) replaces the whole object, its string shorthand
-     * lifted by that schema, and `null` clears it. Keys that are not slots
+     * then writes the matching config slot. A key naming a channel (`facet`,
+     * `color`, `rows`, any object with a one-value shorthand) replaces the
+     * whole object, its string shorthand lifted by that schema, and `null`
+     * clears it; `scales` names members inside it and leaves the rest. Keys
+     * that are not slots
      * come back in `unapplied` as `{ key, reason }`, so a caller can tell a
      * misspelling from a key that has an action instead of a slot.
      *
@@ -738,6 +755,24 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
      * checks it with `plotProblems` and hands it to `applyPlot`.
      */
     readonly plot: Plot;
+    /**
+     * #getter
+     * `configProblemsOf` the live config.
+     */
+    readonly configNotices: string[];
+    /**
+     * #getter
+     * Every line the display has to say about what it cannot draw as
+     * written, as an agent's settle report reads them: `configNotices`,
+     * then `liveNotices`.
+     */
+    readonly notices: string[];
+    /**
+     * #getter
+     * The lines the display chrome's corner chip lists: `notices`, less any
+     * a display shows in a chip of its own.
+     */
+    readonly cornerNotices: string[];
     /**
      * #getter
      * The worked examples this display type declares, which "Edit plot..."
@@ -759,9 +794,8 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
     /**
      * #method
      * What a draft would report once applied, throwing a refusal as
-     * `liftPlot` does: what its colour objects and `scales.y` say together
-     * that cannot be drawn as written. A display with a rule list over its
-     * settings overrides it; the draft still applies, and draws what it can.
+     * `liftPlot` does: `configProblemsOf` the lifted draft. The draft still
+     * applies, and draws what it can.
      */
     plotProblems(draft: Plot): string[];
     /**

package/esm/pluggableElementTypes/models/BaseDisplayModel.js

@@ -7,6 +7,9 @@ import { displaySetterName } from '../../util/unknownSnapshotKeys.js';
 /**
  * #stateModel BaseDisplay
  * #category display
+ * Holds a display's parent track, the adapter config read from that track, its
+ * load status and error, and the component that draws it. Every display
+ * composes this model.
  */
 function stateModelFactory() {
     return types
@@ -77,7 +80,7 @@ function stateModelFactory() {
             // This is a snapshot, so read a specific slot with an array path off the
             // live node (`getConf(track, ['adapter', 'x'])`) rather than off this —
             // `types.stripDefault` omits a slot at its default. See
-            // ../../configuration/CLAUDE.md.
+            // agent-docs/reference/CONFIG_PATTERN.md.
             return getConf(self.parentTrack, 'adapter');
         },
         /**
@@ -175,6 +178,25 @@ function stateModelFactory() {
         trackMenuItems() {
             return [];
         },
+        /**
+         * #method
+         * What a config says that cannot be drawn as written: by default the
+         * schema's rules over its color objects and `scales.y`, the ones
+         * `jbrowse validate` runs. A display with rules of its own overrides it.
+         * `plotProblems` asks it of a draft and `notices` of the live config,
+         * so Edit plot and the corner never disagree.
+         */
+        configProblemsOf(conf) {
+            return schemaPlotProblems(conf);
+        },
+        /**
+         * #getter
+         * What the loaded data says beside the config, such as a field no
+         * fetched feature carries. None unless a display overrides it.
+         */
+        get liveNotices() {
+            return [];
+        },
     }))
         .actions(self => ({
         /**
@@ -217,9 +239,11 @@ function stateModelFactory() {
          * were applied. Each key runs through the display config schema's
          * `preProcessSnapshot` (shorthand expansions and legacy-key migrations,
          * as `showTrackGeneric` applies to a session spec's inline track keys),
-         * then writes the matching config slot. A key naming a sub-schema
-         * (`facet`, `color`) replaces the whole object, its string shorthand
-         * lifted by that schema, and `null` clears it. Keys that are not slots
+         * then writes the matching config slot. A key naming a channel (`facet`,
+         * `color`, `rows`, any object with a one-value shorthand) replaces the
+         * whole object, its string shorthand lifted by that schema, and `null`
+         * clears it; `scales` names members inside it and leaves the rest. Keys
+         * that are not slots
          * come back in `unapplied` as `{ key, reason }`, so a caller can tell a
          * misspelling from a key that has an action instead of a slot.
          *
@@ -293,6 +317,31 @@ function stateModelFactory() {
         get plot() {
             return plotOf(self.configuration);
         },
+        /**
+         * #getter
+         * `configProblemsOf` the live config.
+         */
+        get configNotices() {
+            return self.configProblemsOf(self.configuration);
+        },
+        /**
+         * #getter
+         * Every line the display has to say about what it cannot draw as
+         * written, as an agent's settle report reads them: `configNotices`,
+         * then `liveNotices`.
+         */
+        get notices() {
+            const { configNotices } = self;
+            return [...configNotices, ...self.liveNotices];
+        },
+        /**
+         * #getter
+         * The lines the display chrome's corner chip lists: `notices`, less any
+         * a display shows in a chip of its own.
+         */
+        get cornerNotices() {
+            return self.notices;
+        },
         /**
          * #getter
          * The worked examples this display type declares, which "Edit plot..."
@@ -324,12 +373,11 @@ function stateModelFactory() {
         /**
          * #method
          * What a draft would report once applied, throwing a refusal as
-         * `liftPlot` does: what its colour objects and `scales.y` say together
-         * that cannot be drawn as written. A display with a rule list over its
-         * settings overrides it; the draft still applies, and draws what it can.
+         * `liftPlot` does: `configProblemsOf` the lifted draft. The draft still
+         * applies, and draws what it can.
          */
         plotProblems(draft) {
-            return schemaPlotProblems(liftPlotDraft(self.configuration, draft));
+            return self.configProblemsOf(liftPlotDraft(self.configuration, draft));
         },
         /**
          * #method

package/esm/pluggableElementTypes/models/BaseTrackModel.d.ts

@@ -9,9 +9,9 @@ import type { IType, Instance } from '@jbrowse/mobx-state-tree';
  * #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.
+ * Holds the UI state of a track that is *shown* in a view, with a reference to
+ * its track configuration and the displays drawing it. Only shown tracks have
+ * this model, and several shown tracks can use the same configuration.
  */
 export declare function createBaseTrackModel(pm: PluginManager, trackType: string, baseTrackConfig: AnyConfigurationSchemaType): import("@jbrowse/mobx-state-tree").IModelType<{
     /**

package/esm/pluggableElementTypes/models/BaseTrackModel.js

@@ -6,6 +6,7 @@ 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 { TRACK_MENU_PRIORITY } from '../../ui/MenuTypes.js';
 import { getContainingView, getDialogHost, getEnv, getSession, } from '../../util/index.js';
 import { getConfAssemblyNamesOrNone, viewDisplayNames, } from '../../util/tracks.js';
 import { isSessionModelWithConfigEditing } from '../../util/types/index.js';
@@ -36,9 +37,9 @@ function getDisplayConf(displays, displayId) {
  * #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.
+ * Holds the UI state of a track that is *shown* in a view, with a reference to
+ * its track configuration and the displays drawing it. Only shown tracks have
+ * this model, and several shown tracks can use the same configuration.
  */
 export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
     return types
@@ -447,9 +448,9 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
          */
         get saveTrackDataMenuItem() {
             return {
-                label: 'Save track data',
+                label: 'Save track data...',
                 icon: Save,
-                priority: 998,
+                priority: TRACK_MENU_PRIORITY.saveTrackData,
                 onClick: () => {
                     getDialogHost(self).queueDialog(handleClose => [
                         SaveTrackDataDlg,
@@ -475,7 +476,7 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
                         {
                             type: 'subMenu',
                             label: 'Display types',
-                            priority: -1000,
+                            priority: TRACK_MENU_PRIORITY.displayTypes,
                             subMenu: compatDisp.map(d => {
                                 const displayType = pm.getDisplayType(d.type);
                                 return {

package/esm/pluggableElementTypes/models/BaseViewModel.d.ts

@@ -4,6 +4,8 @@ import type { Instance } from '@jbrowse/mobx-state-tree';
 /**
  * #stateModel BaseViewModel
  * #category view
+ * Holds a view's id, the name shown in its header, its width and whether it is
+ * minimized. Every view composes this model.
  */
 declare const BaseViewModel: import("@jbrowse/mobx-state-tree").IModelType<{
     /**

package/esm/pluggableElementTypes/models/BaseViewModel.js

@@ -27,6 +27,8 @@ function bodyInDom(view) {
 /**
  * #stateModel BaseViewModel
  * #category view
+ * Holds a view's id, the name shown in its header, its width and whether it is
+ * minimized. Every view composes this model.
  */
 const BaseViewModel = types
     .model('BaseView', {

package/esm/pluggableElementTypes/models/InternetAccountModel.d.ts

@@ -5,6 +5,9 @@ import type React from 'react';
 /**
  * #stateModel BaseInternetAccountModel
  * #category internetAccount
+ * Adds a token header to each request for a file on one of the account's
+ * domains, keeping the token in `sessionStorage`. Every internet account type
+ * builds on this model.
  */
 export declare const InternetAccount: import("@jbrowse/mobx-state-tree").IModelType<{
     /**

package/esm/pluggableElementTypes/models/InternetAccountModel.js

@@ -9,6 +9,9 @@ import { uriMatchesDomains } from './uriMatchesDomains.js';
 /**
  * #stateModel BaseInternetAccountModel
  * #category internetAccount
+ * Adds a token header to each request for a file on one of the account's
+ * domains, keeping the token in `sessionStorage`. Every internet account type
+ * builds on this model.
  */
 export const InternetAccount = types
     .model('InternetAccount', {

package/esm/pluggableElementTypes/models/baseConnectionConfig.d.ts

@@ -1,6 +1,9 @@
 import type { Instance } from '@jbrowse/mobx-state-tree';
 /**
  * #config BaseConnection
+ * Holds a connection's name and the assemblies its tracks belong to. Every
+ * connection type has these slots.
+ *
  * #gotcha JBrowse fetches the hub's track list when the connection loads and
  * holds it in memory, and does **not** write it into a saved or shared session.
  * The session stores only the tracks you open (under `connectionTrackConfigs`,

package/esm/pluggableElementTypes/models/baseConnectionConfig.js

@@ -1,6 +1,9 @@
 import { ConfigurationSchema } from '../../configuration/index.js';
 /**
  * #config BaseConnection
+ * Holds a connection's name and the assemblies its tracks belong to. Every
+ * connection type has these slots.
+ *
  * #gotcha JBrowse fetches the hub's track list when the connection loads and
  * holds it in memory, and does **not** write it into a saved or shared session.
  * The session stores only the tracks you open (under `connectionTrackConfigs`,

package/esm/pluggableElementTypes/models/baseInternetAccountConfig.d.ts

@@ -1,6 +1,8 @@
 /**
  * #config BaseInternetAccount
- * the "base" internet account type
+ * Holds an internet account's name and description, the domains it handles,
+ * and the request header it sends credentials in. Every internet account type
+ * has these slots.
  */
 export declare const BaseInternetAccountConfig: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
     readonly name: {

package/esm/pluggableElementTypes/models/baseInternetAccountConfig.js

@@ -1,7 +1,9 @@
 import { ConfigurationSchema } from '../../configuration/index.js';
 /**
  * #config BaseInternetAccount
- * the "base" internet account type
+ * Holds an internet account's name and description, the domains it handles,
+ * and the request header it sends credentials in. Every internet account type
+ * has these slots.
  */
 export const BaseInternetAccountConfig = ConfigurationSchema('InternetAccount', {
     /**