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

package/esm/data_adapters/dataAdapterCache.js

@@ -3,6 +3,25 @@ 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
@@ -16,7 +35,7 @@ function storeWithEvict(key, p) {
     adapterCache[key] = p;
     return p;
 }
-async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
+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)}`);
@@ -25,23 +44,38 @@ async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
     // instantiate the data adapter's config schema so it gets its defaults,
     // callbacks, etc
     const adapterConfig = dataAdapterType.configSchema.create(adapterConfigSnapshot, { pluginManager });
-    const getSubAdapter = conf => getAdapter(pluginManager, sessionId, conf);
+    // 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]),
     };
 }
-/** look up the cached entry for a config, creating and storing it if absent */
-function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot) {
-    const cacheKey = adapterConfigCacheKey(adapterConfigSnapshot);
+/**
+ * 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)));
+        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence)));
 }
-/** 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);
+/**
+ * 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;
 }

package/esm/data_adapters/getFeatureAdapter.d.ts

@@ -7,10 +7,12 @@ export interface GetFeatureAdapterArgs {
     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
+ * 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>;

package/esm/data_adapters/getFeatureAdapter.js

@@ -1,17 +1,17 @@
 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
+ * 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);
-    const featureAdapter = isFeatureAdapter(dataAdapter) ? dataAdapter : undefined;
-    featureAdapter?.setSequenceAdapterConfig(sequenceAdapter);
-    return featureAdapter;
+    const { dataAdapter } = await getAdapter(pluginManager, sessionId, adapterConfig, sequenceAdapter);
+    return isFeatureAdapter(dataAdapter) ? dataAdapter : undefined;
 }
 /**
  * {@link getFeatureAdapter} for the common case where the RPC cannot proceed

package/esm/data_adapters/getSequenceSubAdapter.d.ts

@@ -3,17 +3,15 @@ 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.
+ * 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. 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.
+ * `BaseAdapter`'s.
  *
  * `configured` is passed in rather than read here so each adapter reads its own
  * slot through its own config type.

package/esm/data_adapters/getSequenceSubAdapter.js

@@ -2,17 +2,15 @@
  * 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.
+ * 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. 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.
+ * `BaseAdapter`'s.
  *
  * `configured` is passed in rather than read here so each adapter reads its own
  * slot through its own config type.
@@ -20,7 +18,7 @@
 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');
+        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) {

package/esm/pluggableElementTypes/AdapterType.d.ts

@@ -1,6 +1,6 @@
 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;
@@ -25,9 +25,9 @@ export interface AdapterMetadata {
 }
 /** 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;
+export default class AdapterType<SCHEMA extends AnyConfigurationSchemaType = any> extends PluggableElementBase {
+    getAdapterClass: () => Promise<AdapterClassFor<SCHEMA>>;
+    configSchema: SCHEMA;
     adapterCapabilities: string[];
     adapterMetadata?: AdapterMetadata;
     private declaredNormalizeSnapshot?;
@@ -42,7 +42,7 @@ export default class AdapterType extends PluggableElementBase {
      * 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,
+     * `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
@@ -61,15 +61,15 @@ export default class AdapterType extends PluggableElementBase {
     locationKey?: string;
     constructor(stuff: {
         name: string;
-        configSchema: AnyConfigurationSchemaType;
+        configSchema: SCHEMA;
         displayName?: string;
         adapterCapabilities?: string[];
         adapterMetadata?: AdapterMetadata;
         normalizeSnapshot?: NormalizeSnapshot;
         locationKey?: string;
     } & ({
-        getAdapterClass: () => Promise<AnyAdapter>;
+        getAdapterClass: () => Promise<AdapterClassFor<SCHEMA>>;
     } | {
-        AdapterClass: AnyAdapter;
+        AdapterClass: AdapterClassFor<SCHEMA>;
     }));
 }

package/esm/pluggableElementTypes/AdapterType.js

@@ -17,7 +17,7 @@ export default class AdapterType extends PluggableElementBase {
      * 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,
+     * `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

package/esm/pluggableElementTypes/DisplayType.d.ts

@@ -1,19 +1,42 @@
-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;
     /**
-     * The track type the display is associated with
+     * 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;
-    subDisplay?: {
-        type: string;
-        [key: string]: unknown;
-    };
+    trackType: string | string[];
     /**
      * The view type the display is associated with
      */
@@ -22,19 +45,26 @@ export default class DisplayType extends PluggableElementBase {
      * 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;
-        aliases?: string[];
+        adapterCapabilities?: readonly string[];
+        retiredTypes?: readonly RetiredDisplayType[];
+        retiredState?: RetiredDisplayState;
     });
 }

package/esm/pluggableElementTypes/DisplayType.js

@@ -1,17 +1,14 @@
-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 is associated with
+     * 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;
-    /*
-     * Indicates that this display type can be a "sub-display" of another type of
-     * display, e.g. in AlignmentsDisplay, has Pileup and SNPCoverage subDisplays
-     */
-    subDisplay;
     /**
      * The view type the display is associated with
      */
@@ -20,14 +17,27 @@ export default class DisplayType extends PluggableElementBase {
      * 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/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;
+}

package/esm/pluggableElementTypes/LazyStateModelElement.js

@@ -0,0 +1,77 @@
+import { preloadComponent } from '../util/preloadComponent.js';
+import PluggableElementBase from './PluggableElementBase.js';
+/**
+ * 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 class LazyStateModelElement extends PluggableElementBase {
+    loadedStateModel;
+    stateModelPromise;
+    pendingStateModelExtensions = [];
+    // named `stateModel` + `Loader` because pluggableMstType probes
+    // `${fieldName}Loader` generically
+    stateModelLoader;
+    // set by PluginManager.addElementType: runs Core-extendPluggableElement once
+    // the loader resolves, so a callback reading `stateModel` sees a model
+    onStateModelLoaded;
+    constructor(stuff) {
+        super(stuff);
+        if (typeof stuff.stateModel === 'function') {
+            this.stateModelLoader = stuff.stateModel;
+        }
+        else {
+            this.loadedStateModel = stuff.stateModel;
+        }
+    }
+    // Throws before the loader resolves, so a plugin composing an unloaded
+    // model fails here rather than as an opaque MST error.
+    get stateModel() {
+        this.assertStateModelLoaded();
+        return this.loadedStateModel;
+    }
+    set stateModel(stateModel) {
+        this.loadedStateModel = stateModel;
+    }
+    get isStateModelLoaded() {
+        return this.loadedStateModel !== undefined;
+    }
+    assertStateModelLoaded() {
+        if (this.loadedStateModel === undefined) {
+            const getter = this.group === 'view' ? 'getViewType' : 'getDisplayType';
+            throw new Error(`state model for ${this.group} type ${this.name} is not loaded yet — await ${getter}('${this.name}').loadStateModel() first`);
+        }
+    }
+    /**
+     * Also starts the component's download, which rendering would otherwise
+     * request only after the model exists and the element mounts.
+     */
+    loadStateModel() {
+        preloadComponent(this.ReactComponent);
+        if (this.loadedStateModel !== undefined) {
+            return Promise.resolve(this.loadedStateModel);
+        }
+        if (!this.stateModelLoader) {
+            throw new Error(`${this.group} 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;
+            this.onStateModelLoaded?.();
+            return this.stateModel;
+        });
+        return this.stateModelPromise;
+    }
+    extendStateModel(extend) {
+        if (this.loadedStateModel !== undefined) {
+            this.loadedStateModel = extend(this.loadedStateModel);
+        }
+        else {
+            this.pendingStateModelExtensions.push(extend);
+        }
+    }
+}

package/esm/pluggableElementTypes/PluggableElementBase.d.ts

@@ -6,11 +6,9 @@ export default abstract class PluggableElementBase {
      * 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.
+     * plugin can be renamed out of tree. A display declares its renames as
+     * `retiredTypes`, which also say what the old type's entries become, and
+     * answers these from them.
      */
     aliases?: string[];
     constructor(args?: {

package/esm/pluggableElementTypes/PluggableElementBase.js

@@ -6,11 +6,9 @@ export default class PluggableElementBase {
      * 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.
+     * plugin can be renamed out of tree. A display declares its renames as
+     * `retiredTypes`, which also say what the old type's entries become, and
+     * answers these from them.
      */
     aliases;
     constructor(args) {

package/esm/pluggableElementTypes/RpcMethodType.d.ts

@@ -71,6 +71,16 @@ export default abstract class RpcMethodType<MethodName extends string = string>
     pluginManager: PluginManager;
     constructor(pluginManager: PluginManager);
     serializeArguments(args: object): Promise<Record<string, unknown>>;
+    /**
+     * The reference sequence of the genome a call names in `assemblyName`, as a
+     * sibling of `adapterConfig`. The worker keys and builds a reference-reading
+     * adapter with it (dataAdapterCache), and this is the one place it comes
+     * from: a per-genome renaming method's regions have already become its
+     * `assemblyName` by the time super is reached, a header call names its own,
+     * and a comparative method names none. Ahead of the location walk, which
+     * converts and authorizes what the worker opens.
+     */
+    private attachReference;
     protected renameRegions<T extends RenameRegionsArgs>(args: T): Promise<T>;
     /**
      * The root model to resolve internet accounts against, but only while it is
@@ -109,7 +119,7 @@ export default abstract class RpcMethodType<MethodName extends string = string>
      * is not cosmetic, because the two handles every method receives are the two
      * an author who did not write them down never forwards.
      *
-     * `CoreGetExportData` is the worked example: the stop token and status
+     * `CoreGetExportData` is the worked example: the signal and status
      * callback arrived on every call and its `execute` destructured neither, so
      * the Save-track-data dialog's cancel did nothing and its progress never moved
      * on the adapter-export branch. Nothing was mistyped — the fields simply were

package/esm/pluggableElementTypes/RpcMethodType.js

@@ -1,4 +1,6 @@
 import { isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { untracked } from 'mobx';
+import { getSequenceAdapterConfigByName } from '../assemblyManager/getSequenceAdapterConfig.js';
 import { renameRegionsIfNeeded } from '../util/index.js';
 import { resolveUriLocation } from '../util/io/index.js';
 import { unwrapRpcResult } from '../util/rpc.js';
@@ -64,17 +66,12 @@ function isCloneable(thing) {
 }
 // Values that structuredClone handles natively and that must pass through
 // ownArgs unchanged: `Object.entries` on them yields `[]`, so naive cloning
-// would collapse them to plain `{}` (e.g. a SharedArrayBuffer-backed stop token
-// would silently stop working, a typed array would lose its data).
+// would collapse them to plain `{}` (a typed array would lose its data).
 function isStructuredClonePassthrough(thing) {
     return (thing instanceof File ||
         thing instanceof Blob ||
         thing instanceof ArrayBuffer ||
-        // SharedArrayBuffer is not an ArrayBuffer subclass; without this it
-        // collapses to {} and SAB-based stop tokens silently stop working. Nothing
-        // we ship mints one (see `stopToken.ts`, "Which path runs where"), so this
-        // arm is correctness for an isolated embedding host and nothing else —
-        // keep it, but it is not a hot path and never was.
+        // not an ArrayBuffer subclass
         (typeof SharedArrayBuffer !== 'undefined' &&
             thing instanceof SharedArrayBuffer) ||
         ArrayBuffer.isView(thing) ||
@@ -96,7 +93,7 @@ function isStructuredClonePassthrough(thing) {
 // DataCloneError on every call a display makes.
 //
 // So: non-cloneable leaves (functions, Errors) and structured-clone natives
-// (typed arrays, Blobs, the SAB stop token...) pass through by reference
+// (typed arrays, Blobs...) pass through by reference
 // unchanged. A genuinely non-cloneable value that leaked in by mistake is still
 // caught — at the worker postMessage boundary, which is a real structuredClone.
 function ownArgs(thing, seen = new WeakMap()) {
@@ -171,12 +168,31 @@ export default class RpcMethodType extends PluggableElementBase {
         this.pluginManager = pluginManager;
     }
     async serializeArguments(args) {
-        const augmented = await this.augmentLocationObjects(args);
+        const augmented = await this.augmentLocationObjects(this.attachReference(args));
         return {
             ...augmented,
             blobMap: getBlobMap(),
         };
     }
+    /**
+     * The reference sequence of the genome a call names in `assemblyName`, as a
+     * sibling of `adapterConfig`. The worker keys and builds a reference-reading
+     * adapter with it (dataAdapterCache), and this is the one place it comes
+     * from: a per-genome renaming method's regions have already become its
+     * `assemblyName` by the time super is reached, a header call names its own,
+     * and a comparative method names none. Ahead of the location walk, which
+     * converts and authorizes what the worker opens.
+     */
+    attachReference(args) {
+        const { assemblyName } = args;
+        const assemblyManager = this.pluginManager.rootModel?.session?.assemblyManager;
+        if (!assemblyName || !assemblyManager) {
+            return args;
+        }
+        // eslint-disable-next-line no-restricted-syntax -- EFFECT INPUT: the reference only rides along on the RPC this call sends; the autorun that reached here (the synteny swap check) branches on the call's result, not on this read
+        const sequenceAdapter = untracked(() => getSequenceAdapterConfigByName(assemblyManager, assemblyName));
+        return sequenceAdapter ? { ...args, sequenceAdapter } : args;
+    }
     async renameRegions(args) {
         const { rootModel } = this.pluginManager;
         return renameRegionsIfNeeded(rootModel.session.assemblyManager, args);