@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/data_adapters/dataAdapterCache.js

@@ -1,51 +1,125 @@
-import { adapterConfigCacheKey } from "./util.js";
+import idMaker from '../util/idMaker.js';
+export function adapterConfigCacheKey(conf = {}) {
+    const { adapterId } = conf;
+    return typeof adapterId === 'string' && adapterId ? adapterId : idMaker(conf);
+}
+/**
+ * #api
+ * The `adapterCapabilities` entry of an adapter that reads the reference
+ * sequence of the assembly it is displayed against: BAM and SAM for mismatches
+ * without an MD tag, CRAM to rebuild bases, GC content and the reference scans
+ * for everything they answer. Such an adapter is built with that reference and
+ * keyed on it as well as on its config, so one config shown on two genomes is
+ * two instances, each reading its own, and an instance never changes reference
+ * for its life. Every other adapter keys on its config alone: a synteny adapter
+ * is fetched from each of its assemblies and reads no reference.
+ */
+export const READS_REFERENCE = 'readsReference';
+function readsReference(pluginManager, adapterConfig) {
+    const type = adapterConfig?.type;
+    return (typeof type === 'string' &&
+        pluginManager
+            .getAdapterType(type)
+            .adapterCapabilities.includes(READS_REFERENCE));
+}
+// 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 = {};
-async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
+/** stores a promise in the cache and auto-evicts if it rejects */
+function storeWithEvict(key, p) {
+    p.catch(() => {
+        delete adapterCache[key];
+    });
+    adapterCache[key] = p;
+    return p;
+}
+async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence) {
     const adapterType = adapterConfigSnapshot?.type;
     if (!adapterType) {
         throw new Error(`could not determine adapter type from adapter config snapshot ${JSON.stringify(adapterConfigSnapshot)}`);
     }
     const dataAdapterType = pluginManager.getAdapterType(adapterType);
-    if (!dataAdapterType) {
-        throw new Error(`unknown data adapter type ${adapterType}`);
-    }
+    // instantiate the data adapter's config schema so it gets its defaults,
+    // callbacks, etc
     const adapterConfig = dataAdapterType.configSchema.create(adapterConfigSnapshot, { pluginManager });
-    const getSubAdapter = getAdapter.bind(null, pluginManager, sessionId);
+    // a sub-adapter reads the reference its parent was built with
+    const getSubAdapter = conf => getAdapter(pluginManager, sessionId, conf, keyedSequence);
     const CLASS = await dataAdapterType.getAdapterClass();
-    const dataAdapter = new CLASS(adapterConfig, getSubAdapter, pluginManager);
+    const dataAdapter = new CLASS(adapterConfig, getSubAdapter, pluginManager, keyedSequence);
     return {
         dataAdapter,
         sessionIds: new Set([sessionId]),
     };
 }
-export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot) {
-    const cacheKey = adapterConfigCacheKey(adapterConfigSnapshot);
-    adapterCache[cacheKey] ??= getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot);
-    const ret = await adapterCache[cacheKey];
+/**
+ * look up the cached entry for a config, creating and storing it if absent.
+ * Keyed synchronously, so concurrent callers share one pending entry
+ */
+function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter) {
+    const keyedSequence = sequenceAdapter && readsReference(pluginManager, adapterConfigSnapshot)
+        ? sequenceAdapter
+        : undefined;
+    const configKey = adapterConfigCacheKey(adapterConfigSnapshot);
+    const cacheKey = keyedSequence
+        ? `${configKey}|${adapterConfigCacheKey(keyedSequence)}`
+        : configKey;
+    return (adapterCache[cacheKey] ??
+        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence)));
+}
+/**
+ * instantiate a data adapter, or return a cached one with the same config.
+ * `sequenceAdapter` is the reference of the genome the request names; a
+ * {@link READS_REFERENCE} type is keyed on it and built with it, any other
+ * type ignores it
+ */
+export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter) {
+    const ret = await getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter);
     ret.sessionIds.add(sessionId);
     return ret;
 }
+/**
+ * Drop this session's claim on every cached adapter, and evict the ones no
+ * 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.
+ *
+ * "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 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
+ * passes it straight through), so a sequence adapter shared by two alignments
+ * tracks survives either one of them closing.
+ */
 export async function freeAdapterResources(args) {
-    const specKeys = Object.keys(args);
-    if (specKeys.length === 1 && specKeys[0] === 'sessionId') {
-        const { sessionId } = args;
-        for (const [cacheKey, cacheEntryP] of Object.entries(adapterCache)) {
+    const { sessionId } = args;
+    if (!sessionId) {
+        return;
+    }
+    for (const [cacheKey, cacheEntryP] of Object.entries(adapterCache)) {
+        try {
             const cacheEntry = await cacheEntryP;
             cacheEntry.sessionIds.delete(sessionId);
             if (cacheEntry.sessionIds.size === 0) {
                 delete adapterCache[cacheKey];
             }
         }
-    }
-    else {
-        for (const cacheEntryP of Object.values(adapterCache)) {
-            const cacheEntry = await cacheEntryP;
-            const regions = args.regions || (args.region ? [args.region] : []);
-            for (const region of regions) {
-                if (region.refName !== undefined) {
-                    cacheEntry.dataAdapter.freeResources(region);
-                }
-            }
+        catch (e) {
+            console.error(`dataAdapterCache: evicting failed adapter "${cacheKey}"`, e);
+            delete adapterCache[cacheKey];
         }
     }
 }

package/esm/data_adapters/getFeatureAdapter.d.ts

@@ -0,0 +1,24 @@
+import type PluginManager from '../PluginManager.ts';
+import type { BaseFeatureDataAdapter } from './BaseAdapter/index.ts';
+export interface GetFeatureAdapterArgs {
+    pluginManager: PluginManager;
+    sessionId: string;
+    adapterConfig: Record<string, unknown>;
+    sequenceAdapter?: Record<string, unknown>;
+}
+/**
+ * Resolve a feature data adapter — the single resolution path for every RPC
+ * that reads features. An RPC passes its whole args (`{ ...args, pluginManager
+ * }`) so the `sequenceAdapter` serialization attached reaches the cache without
+ * being named, and a reference-reading type comes back built for that genome.
+ * Returns undefined when the config resolves to a non-feature adapter, so
+ * callers that can degrade (e.g. getRefNames → []) decide how; use
+ * {@link getFeatureAdapterOrThrow} when a feature adapter is required.
+ */
+export declare function getFeatureAdapter({ pluginManager, sessionId, adapterConfig, sequenceAdapter, }: GetFeatureAdapterArgs): Promise<BaseFeatureDataAdapter | undefined>;
+/**
+ * {@link getFeatureAdapter} for the common case where the RPC cannot proceed
+ * without a feature adapter: throws a clear error instead of returning
+ * undefined, so callers get a definite type and no cast.
+ */
+export declare function getFeatureAdapterOrThrow(args: GetFeatureAdapterArgs): Promise<BaseFeatureDataAdapter>;

package/esm/data_adapters/getFeatureAdapter.js

@@ -0,0 +1,27 @@
+import { isFeatureAdapter } from './BaseAdapter/index.js';
+import { getAdapter } from './dataAdapterCache.js';
+/**
+ * Resolve a feature data adapter — the single resolution path for every RPC
+ * that reads features. An RPC passes its whole args (`{ ...args, pluginManager
+ * }`) so the `sequenceAdapter` serialization attached reaches the cache without
+ * being named, and a reference-reading type comes back built for that genome.
+ * Returns undefined when the config resolves to a non-feature adapter, so
+ * callers that can degrade (e.g. getRefNames → []) decide how; use
+ * {@link getFeatureAdapterOrThrow} when a feature adapter is required.
+ */
+export async function getFeatureAdapter({ pluginManager, sessionId, adapterConfig, sequenceAdapter, }) {
+    const { dataAdapter } = await getAdapter(pluginManager, sessionId, adapterConfig, sequenceAdapter);
+    return isFeatureAdapter(dataAdapter) ? dataAdapter : undefined;
+}
+/**
+ * {@link getFeatureAdapter} for the common case where the RPC cannot proceed
+ * without a feature adapter: throws a clear error instead of returning
+ * undefined, so callers get a definite type and no cast.
+ */
+export async function getFeatureAdapterOrThrow(args) {
+    const dataAdapter = await getFeatureAdapter(args);
+    if (!dataAdapter) {
+        throw new Error(`adapter "${args.adapterConfig.type}" is not a feature adapter`);
+    }
+    return dataAdapter;
+}

package/esm/data_adapters/getSequenceSubAdapter.d.ts

@@ -0,0 +1,19 @@
+import type { BaseAdapter, BaseSequenceAdapter } from './BaseAdapter/index.ts';
+/**
+ * Resolves the reference sequence an adapter reads from.
+ *
+ * **The assembly is the source, and a hand-written `sequenceAdapter` slot is an
+ * anti-pattern.** A reference-reading adapter is built with the sequence of the
+ * assembly the request that created it named (dataAdapterCache), so no config
+ * has to copy a sequence adapter into a track. The slot survives as an escape
+ * hatch for reading some *other* sequence, and setting it pins the track to
+ * that source even when the assembly's own sequence changes — so it wins only
+ * when explicitly present, and `jbrowse validate` warns about it.
+ *
+ * In core rather than beside one of its callers because the field it reads is
+ * `BaseAdapter`'s.
+ *
+ * `configured` is passed in rather than read here so each adapter reads its own
+ * slot through its own config type.
+ */
+export declare function getSequenceSubAdapter(adapter: BaseAdapter, configured: unknown): Promise<BaseSequenceAdapter>;

package/esm/data_adapters/getSequenceSubAdapter.js

@@ -0,0 +1,42 @@
+/**
+ * Resolves the reference sequence an adapter reads from.
+ *
+ * **The assembly is the source, and a hand-written `sequenceAdapter` slot is an
+ * anti-pattern.** A reference-reading adapter is built with the sequence of the
+ * assembly the request that created it named (dataAdapterCache), so no config
+ * has to copy a sequence adapter into a track. The slot survives as an escape
+ * hatch for reading some *other* sequence, and setting it pins the track to
+ * that source even when the assembly's own sequence changes — so it wins only
+ * when explicitly present, and `jbrowse validate` warns about it.
+ *
+ * In core rather than beside one of its callers because the field it reads is
+ * `BaseAdapter`'s.
+ *
+ * `configured` is passed in rather than read here so each adapter reads its own
+ * slot through its own config type.
+ */
+export async function getSequenceSubAdapter(adapter, configured) {
+    const config = configured ?? adapter.sequenceAdapterConfig;
+    if (!config) {
+        throw new Error(`${adapter.config.type} was built with no reference: the request that created it named no assembly, and no \`sequenceAdapter\` slot is set`);
+    }
+    const result = await adapter.getSubAdapter?.(config);
+    if (!result) {
+        throw new Error('Error getting subadapter');
+    }
+    // An assembly can be backed by an adapter that carries no residues at all
+    // (ChromSizesAdapter defines refName lengths only), and auto-resolution makes
+    // that reachable without anyone having named a sequence adapter. Check for the
+    // method rather than casting blind, so this fails with the reason instead of
+    // `getSequence is not a function` deep in a scan.
+    const { dataAdapter } = result;
+    if (!isSequenceAdapter(dataAdapter)) {
+        // named from the config, not `constructor.name`, which minifies to noise
+        const { type } = config;
+        throw new Error(`Cannot scan the reference: adapter "${String(type)}" provides no sequence`);
+    }
+    return dataAdapter;
+}
+function isSequenceAdapter(adapter) {
+    return (typeof adapter.getSequence === 'function');
+}

package/esm/pluggableElementTypes/AdapterType.d.ts

@@ -1,25 +1,75 @@
 import PluggableElementBase from './PluggableElementBase.ts';
 import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
-import type { AnyAdapter } from '../data_adapters/BaseAdapter/index.ts';
+import type { AdapterClassFor } from '../data_adapters/BaseAdapter/index.ts';
 export interface AdapterMetadata {
     category?: string;
     hiddenFromGUI?: boolean;
     description?: string;
+    /**
+     * File names this adapter is a valid reading of, but which the extension
+     * guess does not hand it — either because another adapter claims the same
+     * extension (an all-vs-all PAF looks like any `.paf`) or because no guesser
+     * claims it at all.
+     *
+     * Purely an "Add track" hint: it does not enter
+     * `Core-guessAdapterForLocation`, which stays a single first-match-wins chain,
+     * so it changes nothing about what a file resolves to headlessly, from the
+     * CLI, or in an existing plugin's guesser. What it does is let the form say
+     * the alternative exists at the moment the adapter is chosen, instead of
+     * leaving it to be found in a dropdown of every adapter JBrowse has.
+     *
+     * State the fact, not a preference — every adapter naming a pattern is
+     * offered together, in registration order, with the guess still selected.
+     */
+    alsoReads?: RegExp;
 }
-export default class AdapterType extends PluggableElementBase {
-    getAdapterClass: () => Promise<AnyAdapter>;
-    configSchema: AnyConfigurationSchemaType;
+/** Expand a raw adapter config snapshot (plain JSON) to its canonical form. */
+export type NormalizeSnapshot = (snap: Record<string, unknown>) => Record<string, unknown>;
+export default class AdapterType<SCHEMA extends AnyConfigurationSchemaType = any> extends PluggableElementBase {
+    getAdapterClass: () => Promise<AdapterClassFor<SCHEMA>>;
+    configSchema: SCHEMA;
     adapterCapabilities: string[];
     adapterMetadata?: AdapterMetadata;
+    private declaredNormalizeSnapshot?;
+    /**
+     * Normalize a raw adapter config snapshot (plain JSON, before MST
+     * instantiation). Adapters that support shorthand notation (e.g. just
+     * `{type, uri}`) expand it to the canonical form so downstream code can read
+     * location keys without knowing each shorthand.
+     *
+     * **Defaults to the config schema's own `preProcessSnapshot`**, which is the
+     * function that already runs when MST builds the config, so an adapter
+     * declaring the shorthand once gets both. It used to be a second, separate
+     * registration, and five in-tree adapters had only the schema half
+     * (`MafTabixAdapter`, `BgzipMafAdapter`, `BgzipTaffyAdapter`,
+     * `MultiGenomePAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
+     * because loading such a config from a URL goes through the schema. Only
+     * `normalizeAdapterSnapshots` consults *this*, so what broke was `localFiles`
+     * in the embedded products: the shorthand stayed unexpanded, `uri` never
+     * became a location node, and the blob substitution silently found nothing to
+     * substitute.
+     *
+     * Pass one explicitly only to normalize *differently* here than at MST
+     * create, which nothing in tree needs.
+     */
+    get normalizeSnapshot(): NormalizeSnapshot | undefined;
+    /**
+     * The config key holding the adapter's primary file location (e.g.
+     * `'vcfGzLocation'`). Used by import forms to extract the file location from
+     * a track's adapter config.
+     */
+    locationKey?: string;
     constructor(stuff: {
         name: string;
-        configSchema: AnyConfigurationSchemaType;
+        configSchema: SCHEMA;
         displayName?: string;
         adapterCapabilities?: string[];
         adapterMetadata?: AdapterMetadata;
+        normalizeSnapshot?: NormalizeSnapshot;
+        locationKey?: string;
     } & ({
-        AdapterClass: AnyAdapter;
+        getAdapterClass: () => Promise<AdapterClassFor<SCHEMA>>;
     } | {
-        getAdapterClass: () => Promise<AnyAdapter>;
+        AdapterClass: AdapterClassFor<SCHEMA>;
     }));
 }

package/esm/pluggableElementTypes/AdapterType.js

@@ -1,17 +1,56 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import { getConfigurationSchemaMetadata } from '../configuration/schemaRegistry.js';
+import PluggableElementBase from './PluggableElementBase.js';
 export default class AdapterType extends PluggableElementBase {
     getAdapterClass;
     configSchema;
     adapterCapabilities;
     adapterMetadata;
+    declaredNormalizeSnapshot;
+    /**
+     * Normalize a raw adapter config snapshot (plain JSON, before MST
+     * instantiation). Adapters that support shorthand notation (e.g. just
+     * `{type, uri}`) expand it to the canonical form so downstream code can read
+     * location keys without knowing each shorthand.
+     *
+     * **Defaults to the config schema's own `preProcessSnapshot`**, which is the
+     * function that already runs when MST builds the config, so an adapter
+     * declaring the shorthand once gets both. It used to be a second, separate
+     * registration, and five in-tree adapters had only the schema half
+     * (`MafTabixAdapter`, `BgzipMafAdapter`, `BgzipTaffyAdapter`,
+     * `MultiGenomePAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
+     * because loading such a config from a URL goes through the schema. Only
+     * `normalizeAdapterSnapshots` consults *this*, so what broke was `localFiles`
+     * in the embedded products: the shorthand stayed unexpanded, `uri` never
+     * became a location node, and the blob substitution silently found nothing to
+     * substitute.
+     *
+     * Pass one explicitly only to normalize *differently* here than at MST
+     * create, which nothing in tree needs.
+     */
+    get normalizeSnapshot() {
+        return (this.declaredNormalizeSnapshot ??
+            getConfigurationSchemaMetadata(this.configSchema)?.options
+                .preProcessSnapshot);
+    }
+    /**
+     * The config key holding the adapter's primary file location (e.g.
+     * `'vcfGzLocation'`). Used by import forms to extract the file location from
+     * a track's adapter config.
+     */
+    locationKey;
+    // `AdapterClass` is retained for backward compatibility with third-party
+    // plugins that pass an eager class reference; new code should prefer
+    // `getAdapterClass` for code splitting.
     constructor(stuff) {
         super(stuff);
         this.getAdapterClass =
-            'AdapterClass' in stuff
-                ? async () => stuff.AdapterClass
-                : stuff.getAdapterClass;
+            'getAdapterClass' in stuff
+                ? stuff.getAdapterClass
+                : async () => stuff.AdapterClass;
         this.configSchema = stuff.configSchema;
-        this.adapterCapabilities = stuff.adapterCapabilities || [];
+        this.adapterCapabilities = stuff.adapterCapabilities ?? [];
         this.adapterMetadata = stuff.adapterMetadata;
+        this.declaredNormalizeSnapshot = stuff.normalizeSnapshot;
+        this.locationKey = stuff.locationKey;
     }
 }

package/esm/pluggableElementTypes/AddTrackWorkflowType.d.ts

@@ -1,15 +1,20 @@
-import type React from 'react';
 import PluggableElementBase from './PluggableElementBase.ts';
 import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
+import type React from 'react';
 type BasicComponent = React.ComponentType<{
     model: any;
+    switchWorkflow: (name: string) => void;
 }>;
 type AddTrackWorkflowComponentType = React.LazyExoticComponent<BasicComponent> | BasicComponent;
+export type AddTrackWorkflowCategory = 'general' | 'specialized';
 export default class AddTrackWorkflow extends PluggableElementBase {
     ReactComponent: AddTrackWorkflowComponentType;
+    category: AddTrackWorkflowCategory;
     stateModel: IAnyModelType;
     constructor(stuff: {
         name: string;
+        displayName?: string;
+        category?: AddTrackWorkflowCategory;
         ReactComponent: AddTrackWorkflowComponentType;
         stateModel: IAnyModelType;
     });

package/esm/pluggableElementTypes/AddTrackWorkflowType.js

@@ -1,10 +1,12 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class AddTrackWorkflow extends PluggableElementBase {
     ReactComponent;
+    category;
     stateModel;
     constructor(stuff) {
         super(stuff);
         this.ReactComponent = stuff.ReactComponent;
+        this.category = stuff.category ?? 'specialized';
         this.stateModel = stuff.stateModel;
     }
 }

package/esm/pluggableElementTypes/ConnectionType.d.ts

@@ -5,16 +5,16 @@ import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
 export default class ConnectionType extends PluggableElementBase {
     stateModel: IAnyModelType;
     configSchema: AnyConfigurationSchemaType;
-    description: string;
-    url: string;
+    description?: string;
+    url?: string;
     configEditorComponent?: AnyReactComponentType;
     constructor(stuff: {
         name: string;
         stateModel: IAnyModelType;
         configSchema: AnyConfigurationSchemaType;
-        displayName: string;
-        description: string;
+        displayName?: string;
+        description?: string;
         configEditorComponent?: AnyReactComponentType;
-        url: string;
+        url?: string;
     });
 }

package/esm/pluggableElementTypes/ConnectionType.js

@@ -1,4 +1,4 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class ConnectionType extends PluggableElementBase {
     stateModel;
     configSchema;

package/esm/pluggableElementTypes/DisplayType.d.ts

@@ -1,30 +1,70 @@
-import PluggableElementBase from './PluggableElementBase.ts';
+import LazyStateModelElement from './LazyStateModelElement.ts';
 import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
 import type { AnyReactComponentType } from '../util/index.ts';
 import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
-export default class DisplayType extends PluggableElementBase {
-    stateModel: IAnyModelType;
+export type DisplayEntry = Record<string, unknown>;
+/**
+ * A display type retired into this one. Configs and sessions naming it load
+ * as this display, the entry rewritten by `migrate` first: the settings the
+ * old type's picture needs, and its own spelling of any slot value, which
+ * `values` lists by slot so the published JSON schema and `jbrowse validate`
+ * admit it. A session track's entry keeps the retired type after its lifted
+ * settings are folded onto it, so `migrate` must leave an entry it already
+ * rewrote as it found it.
+ */
+export interface RetiredDisplayType {
+    type: string;
+    migrate?: (entry: DisplayEntry) => DisplayEntry;
+    values?: Readonly<Record<string, readonly unknown[]>>;
+}
+/**
+ * Display-instance props an old session carries that are config slots now.
+ * `lift` answers the slots they become, which the session migration writes
+ * into the track's config; `keys` lists them, so the instance sheds them and
+ * `jbrowse validate` reports them as stale rather than dead.
+ */
+export interface RetiredDisplayState {
+    keys: readonly string[];
+    lift: (instance: DisplayEntry) => DisplayEntry;
+}
+export default class DisplayType extends LazyStateModelElement {
+    protected readonly group = "display";
     configSchema: AnyConfigurationSchemaType;
     ReactComponent: AnyReactComponentType;
-    trackType: string;
-    subDisplay?: {
-        type: string;
-        [key: string]: unknown;
-    };
+    /**
+     * The track type the display attaches to, or several: a display that reads
+     * a field any feature adapter serves (the Manhattan plot's `score`) belongs
+     * to every track type whose adapters serve it.
+     */
+    trackType: string | string[];
+    /**
+     * The view type the display is associated with
+     */
     viewType: string;
+    /**
+     * Help text describing the display type
+     */
     helpText?: string;
+    /**
+     * What the track's adapter must declare it can answer for this display to
+     * be offered on the track: a graph display draws only from an adapter that
+     * cuts a subgraph (`['getSubgraph']`), so a track whose adapter cannot is
+     * not given one.
+     */
+    adapterCapabilities: readonly string[];
+    retiredTypes: readonly RetiredDisplayType[];
+    retiredState?: RetiredDisplayState;
     constructor(stuff: {
         name: string;
-        stateModel: IAnyModelType;
-        trackType: string;
+        stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
+        trackType: string | string[];
         viewType: string;
         displayName?: string;
-        subDisplay?: {
-            type: string;
-            [key: string]: unknown;
-        };
         configSchema: AnyConfigurationSchemaType;
         ReactComponent: AnyReactComponentType;
         helpText?: string;
+        adapterCapabilities?: readonly string[];
+        retiredTypes?: readonly RetiredDisplayType[];
+        retiredState?: RetiredDisplayState;
     });
 }

package/esm/pluggableElementTypes/DisplayType.js

@@ -1,20 +1,43 @@
-import PluggableElementBase from "./PluggableElementBase.js";
-export default class DisplayType extends PluggableElementBase {
-    stateModel;
+import LazyStateModelElement from './LazyStateModelElement.js';
+export default class DisplayType extends LazyStateModelElement {
+    group = 'display';
     configSchema;
     ReactComponent;
+    /**
+     * The track type the display attaches to, or several: a display that reads
+     * a field any feature adapter serves (the Manhattan plot's `score`) belongs
+     * to every track type whose adapters serve it.
+     */
     trackType;
-    subDisplay;
+    /**
+     * The view type the display is associated with
+     */
     viewType;
+    /**
+     * Help text describing the display type
+     */
     helpText;
+    /**
+     * What the track's adapter must declare it can answer for this display to
+     * be offered on the track: a graph display draws only from an adapter that
+     * cuts a subgraph (`['getSubgraph']`), so a track whose adapter cannot is
+     * not given one.
+     */
+    adapterCapabilities;
+    retiredTypes;
+    retiredState;
     constructor(stuff) {
-        super(stuff);
-        this.stateModel = stuff.stateModel;
-        this.subDisplay = stuff.subDisplay;
+        super({
+            ...stuff,
+            aliases: stuff.retiredTypes?.map(r => r.type),
+        });
         this.configSchema = stuff.configSchema;
         this.ReactComponent = stuff.ReactComponent;
         this.trackType = stuff.trackType;
         this.viewType = stuff.viewType;
         this.helpText = stuff.helpText;
+        this.adapterCapabilities = stuff.adapterCapabilities ?? [];
+        this.retiredTypes = stuff.retiredTypes ?? [];
+        this.retiredState = stuff.retiredState;
     }
 }

package/esm/pluggableElementTypes/InternetAccountType.js

@@ -1,4 +1,4 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class InternetAccountType extends PluggableElementBase {
     stateModel;
     configSchema;

package/esm/pluggableElementTypes/LazyStateModelElement.d.ts

@@ -0,0 +1,32 @@
+import PluggableElementBase from './PluggableElementBase.ts';
+import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
+/**
+ * A pluggable element whose state model may arrive through a dynamic import.
+ * Code that can run before any instance exists — session preloading, pruning,
+ * union membership — checks `isStateModelLoaded` before reading `stateModel`.
+ */
+export default abstract class LazyStateModelElement extends PluggableElementBase {
+    protected abstract readonly group: 'view' | 'display';
+    abstract ReactComponent: unknown;
+    private loadedStateModel?;
+    private stateModelPromise?;
+    private pendingStateModelExtensions;
+    stateModelLoader?: () => Promise<IAnyModelType>;
+    onStateModelLoaded?: () => void;
+    constructor(stuff: {
+        name: string;
+        displayName?: string;
+        aliases?: string[];
+        stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
+    });
+    get stateModel(): IAnyModelType;
+    set stateModel(stateModel: IAnyModelType);
+    get isStateModelLoaded(): boolean;
+    assertStateModelLoaded(): void;
+    /**
+     * Also starts the component's download, which rendering would otherwise
+     * request only after the model exists and the element mounts.
+     */
+    loadStateModel(): Promise<IAnyModelType>;
+    extendStateModel(extend: (stateModel: IAnyModelType) => IAnyModelType): void;
+}