@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/data_adapters/dataAdapterCache.js

@@ -1,16 +1,31 @@
-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);
+}
+// 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 = {};
+/** 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) {
     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);
+    const getSubAdapter = conf => getAdapter(pluginManager, sessionId, conf);
     const CLASS = await dataAdapterType.getAdapterClass();
     const dataAdapter = new CLASS(adapterConfig, getSubAdapter, pluginManager);
     return {
@@ -18,34 +33,59 @@ async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
         sessionIds: new Set([sessionId]),
     };
 }
-export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot) {
+/** look up the cached entry for a config, creating and storing it if absent */
+function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot) {
     const cacheKey = adapterConfigCacheKey(adapterConfigSnapshot);
-    adapterCache[cacheKey] ??= getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot);
-    const ret = await adapterCache[cacheKey];
+    return (adapterCache[cacheKey] ??
+        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot)));
+}
+/** instantiate a data adapter, or return a cached one with the same config */
+export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot) {
+    const ret = await getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot);
     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,22 @@
+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 and prime its reference-sequence adapter
+ * config in one step — the single resolution path for every RPC that reads
+ * features. 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 and prime its reference-sequence adapter
+ * config in one step — the single resolution path for every RPC that reads
+ * features. 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);
+    const featureAdapter = isFeatureAdapter(dataAdapter) ? dataAdapter : undefined;
+    featureAdapter?.setSequenceAdapterConfig(sequenceAdapter);
+    return featureAdapter;
+}
+/**
+ * {@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,21 @@
+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.** `getFeatureAdapter` and `CoreGetRefNames` prime every feature
+ * adapter's `sequenceAdapterConfig` from the assembly the track is displayed
+ * against, 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. Deliberately NOT in `BaseAdapter/index.ts`: that barrel is a
+ * `@jbrowse/core/*` re-export, and a name published there is load-bearing ABI —
+ * `abi.test.ts`/`abiBaseline.json` fails a removal from it.
+ *
+ * `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,44 @@
+/**
+ * Resolves the reference sequence an adapter reads from.
+ *
+ * **The assembly is the source, and a hand-written `sequenceAdapter` slot is an
+ * anti-pattern.** `getFeatureAdapter` and `CoreGetRefNames` prime every feature
+ * adapter's `sequenceAdapterConfig` from the assembly the track is displayed
+ * against, 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. Deliberately NOT in `BaseAdapter/index.ts`: that barrel is a
+ * `@jbrowse/core/*` re-export, and a name published there is load-bearing ABI —
+ * `abi.test.ts`/`abiBaseline.json` fails a removal from it.
+ *
+ * `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('No sequence adapter available: either set the `sequenceAdapter` slot or display this track against an assembly that has one');
+    }
+    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

@@ -5,21 +5,71 @@ 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;
 }
+/** 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 extends PluggableElementBase {
     getAdapterClass: () => Promise<AnyAdapter>;
     configSchema: AnyConfigurationSchemaType;
     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`,
+     * `AllVsAllPAFAdapter`, `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;
         displayName?: string;
         adapterCapabilities?: string[];
         adapterMetadata?: AdapterMetadata;
+        normalizeSnapshot?: NormalizeSnapshot;
+        locationKey?: string;
     } & ({
-        AdapterClass: AnyAdapter;
-    } | {
         getAdapterClass: () => Promise<AnyAdapter>;
+    } | {
+        AdapterClass: AnyAdapter;
     }));
 }

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`,
+     * `AllVsAllPAFAdapter`, `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

@@ -3,28 +3,37 @@ 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;
+    private loadedStateModel?;
+    get stateModel(): IAnyModelType;
+    stateModelLoader?: () => Promise<IAnyModelType>;
+    private stateModelPromise?;
+    private pendingStateModelExtensions;
     configSchema: AnyConfigurationSchemaType;
     ReactComponent: AnyReactComponentType;
+    /**
+     * The track type the display is associated with
+     */
     trackType: string;
-    subDisplay?: {
-        type: string;
-        [key: string]: unknown;
-    };
+    /**
+     * The view type the display is associated with
+     */
     viewType: string;
+    /**
+     * Help text describing the display type
+     */
     helpText?: string;
     constructor(stuff: {
         name: string;
-        stateModel: IAnyModelType;
+        stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
         trackType: string;
         viewType: string;
         displayName?: string;
-        subDisplay?: {
-            type: string;
-            [key: string]: unknown;
-        };
         configSchema: AnyConfigurationSchemaType;
         ReactComponent: AnyReactComponentType;
         helpText?: string;
+        aliases?: string[];
     });
+    get isStateModelLoaded(): boolean;
+    loadStateModel(): Promise<IAnyModelType>;
+    extendStateModel(extend: (stateModel: IAnyModelType) => IAnyModelType): void;
 }

package/esm/pluggableElementTypes/DisplayType.js

@@ -1,20 +1,68 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class DisplayType extends PluggableElementBase {
-    stateModel;
+    loadedStateModel;
+    // same contract as ViewType.stateModel
+    get stateModel() {
+        return this.loadedStateModel;
+    }
+    stateModelLoader;
+    stateModelPromise;
+    pendingStateModelExtensions = [];
     configSchema;
     ReactComponent;
+    /**
+     * The track type the display is associated with
+     */
     trackType;
-    subDisplay;
+    /**
+     * The view type the display is associated with
+     */
     viewType;
+    /**
+     * Help text describing the display type
+     */
     helpText;
     constructor(stuff) {
         super(stuff);
-        this.stateModel = stuff.stateModel;
-        this.subDisplay = stuff.subDisplay;
+        if (typeof stuff.stateModel === 'function') {
+            this.stateModelLoader = stuff.stateModel;
+        }
+        else {
+            this.loadedStateModel = stuff.stateModel;
+        }
         this.configSchema = stuff.configSchema;
         this.ReactComponent = stuff.ReactComponent;
         this.trackType = stuff.trackType;
         this.viewType = stuff.viewType;
         this.helpText = stuff.helpText;
     }
+    get isStateModelLoaded() {
+        return this.loadedStateModel !== undefined;
+    }
+    loadStateModel() {
+        if (this.loadedStateModel !== undefined) {
+            return Promise.resolve(this.loadedStateModel);
+        }
+        if (!this.stateModelLoader) {
+            throw new Error(`display type ${this.name} has neither a state model nor a loader`);
+        }
+        this.stateModelPromise ??= this.stateModelLoader().then(loaded => {
+            let stateModel = loaded;
+            for (const extend of this.pendingStateModelExtensions) {
+                stateModel = extend(stateModel);
+            }
+            this.pendingStateModelExtensions = [];
+            this.loadedStateModel = stateModel;
+            return stateModel;
+        });
+        return this.stateModelPromise;
+    }
+    extendStateModel(extend) {
+        if (this.loadedStateModel !== undefined) {
+            this.loadedStateModel = extend(this.loadedStateModel);
+        }
+        else {
+            this.pendingStateModelExtensions.push(extend);
+        }
+    }
 }

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

@@ -1,9 +1,22 @@
 export default abstract class PluggableElementBase {
     name: string;
     maybeDisplayName?: string;
+    /**
+     * Older names for this element that should be remapped to it when a session
+     * or config names one. Each entry is a legacy `type` value previously used.
+     *
+     * Lets an element own its renames instead of a central migration file, so a
+     * plugin can be renamed out of tree. A per-element `preProcessSnapshot` hook
+     * then handles any property migrations within the renamed type; for a
+     * migration that rewrites the value of an existing constrained slot (an enum
+     * rename, a type narrow) use `addDisplayConfigMigration` instead — see that
+     * helper for why.
+     */
+    aliases?: string[];
     constructor(args?: {
         name?: string;
         displayName?: string;
+        aliases?: string[];
     });
     get displayName(): string;
 }

package/esm/pluggableElementTypes/PluggableElementBase.js

@@ -1,9 +1,22 @@
 export default class PluggableElementBase {
     name;
     maybeDisplayName;
+    /**
+     * Older names for this element that should be remapped to it when a session
+     * or config names one. Each entry is a legacy `type` value previously used.
+     *
+     * Lets an element own its renames instead of a central migration file, so a
+     * plugin can be renamed out of tree. A per-element `preProcessSnapshot` hook
+     * then handles any property migrations within the renamed type; for a
+     * migration that rewrites the value of an existing constrained slot (an enum
+     * rename, a type narrow) use `addDisplayConfigMigration` instead — see that
+     * helper for why.
+     */
+    aliases;
     constructor(args) {
         this.name = args?.name || 'UNKNOWN';
         this.maybeDisplayName = args?.displayName;
+        this.aliases = args?.aliases;
     }
     get displayName() {
         return this.maybeDisplayName || this.name;