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

package/esm/util/tracks.js

@@ -8,13 +8,20 @@ export { getFileName } from './getFileName.js';
 // it. `fetchContext.ts` takes it from mstUtils instead, which is what keeps the
 // configuration schemas this file pulls in out of the fetch harness's graph.
 export { getRpcSessionId } from './parentWalk.js';
-import { getParent, getSnapshot, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+export { makeIndex } from './formatGuessers.js';
+export { isLooseTrackConfig, } from '@jbrowse/add-track-core';
+import { isLooseTrackConfig, } from '@jbrowse/add-track-core';
+import { asModelType, getParent, getSnapshot, getType, hasParent, isAlive, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import { observable, runInAction, untracked } from 'mobx';
-import { isConfigurationSlot, preProcessSlotValues, readConfObject, } from '../configuration/index.js';
+import { readConfObject } from '../configuration/index.js';
+import { adapterConfigCacheKey } from '../data_adapters/dataAdapterCache.js';
+import { displayCandidates, displayTypesFedBy, } from '../pluggableElementTypes/models/baseTrackConfig.js';
 import { getFileHandle, storeFileHandle, verifyPermission, } from './fileHandleStore.js';
+import { makeIndex } from './formatGuessers.js';
 import { getFileName } from './getFileName.js';
 import { getContainingView, getEnv, getSession, objectHash, } from './mstUtils.js';
 import { isViewModel } from './types/index.js';
+import { setterOnlyMessage, unknownKeysMessage } from './unknownSnapshotKeys.js';
 // Deliberately uncached. This used to memoize on a permanent WeakMap keyed by
 // track, but every caller reads it from inside a reactive getter or autorun: the
 // memo meant the reaction never subscribed to the config, so editing
@@ -76,12 +83,22 @@ export function isSameAssemblyName(a, b, assemblyManager) {
  * `ReferenceSequenceTrack` does not — its schema omits the slot deliberately
  * (see `createReferenceSeqTrackConfig`), because the assembly config holding it
  * IS its assembly, so the name is read off the parent instead.
+ *
+ * That makes a sequence track's assembly **positional**, so a copy of one that
+ * is not inside its assembly cannot answer at all — and a detached config is
+ * what every hydration path produces (`hydrateTrackConfig`, and the working
+ * copy a non-admin's edits would go to, ADR-032). `hasParent` is the guard:
+ * without it the walk raises MST's "Failed to find the parent" from a helper
+ * whose other two failure modes are a plain `undefined`.
  */
 function confAssemblyNames(conf) {
     const trackAssemblyNames = readConfObject(conf, 'assemblyNames');
     if (trackAssemblyNames) {
         return trackAssemblyNames;
     }
+    if (!hasParent(conf)) {
+        return undefined;
+    }
     const parent = getParent(conf);
     return 'sequence' in parent
         ? [readConfObject(parent, 'name')]
@@ -108,6 +125,15 @@ export function getConfAssemblyNames(conf) {
 export function getConfAssemblyNamesOrNone(conf) {
     return confAssemblyNames(conf) ?? [];
 }
+/**
+ * The RPC session id a track's own requests go out under, from its config:
+ * what `BaseTrackModel.rpcSessionId` computes, for a caller holding no model.
+ * A call under any other id lands on another worker, which builds a second
+ * copy of the adapter that nothing frees.
+ */
+export function getConfRpcSessionId(conf) {
+    return adapterConfigCacheKey(readConfObject(conf, 'adapter'));
+}
 export const UNKNOWN = 'UNKNOWN';
 export const UNSUPPORTED = 'UNSUPPORTED';
 let blobMap = {};
@@ -257,34 +283,6 @@ export function findFileHandleIds(obj) {
 export async function restoreFileHandlesFromSnapshot(sessionSnapshot, requestPermission = false) {
     return restoreFileHandles([...findFileHandleIds(sessionSnapshot)], requestPermission);
 }
-/**
- * creates a new location from the provided location including the appropriate
- * suffix and location type
- *
- * @param location - the FileLocation
- * @param suffix - the file suffix (e.g. .bam)
- * @returns the constructed location object from the provided parameters
- */
-export function makeIndex(location, suffix) {
-    if ('uri' in location) {
-        return {
-            uri: location.uri + suffix,
-            locationType: 'UriLocation',
-            // carry the parent's baseUri so a derived sibling index resolves against
-            // the same config location as the file it indexes
-            ...(location.baseUri ? { baseUri: location.baseUri } : {}),
-        };
-    }
-    else if ('localPath' in location) {
-        return {
-            localPath: location.localPath + suffix,
-            locationType: 'LocalPathLocation',
-        };
-    }
-    else {
-        return location;
-    }
-}
 /**
  * constructs a potential index file (with suffix) from the provided file name
  *
@@ -368,8 +366,12 @@ export function guessAdapter(file, index, adapterHint, model) {
 }
 export function guessTrackType(adapterType, model, file) {
     if (model) {
-        const session = getSession(model);
-        const trackTypeGuesser = getEnv(session).pluginManager.evaluateExtensionPoint(
+        // getEnv(model), not getEnv(getSession(model)): the env is tree-wide, so
+        // the session hop only narrowed what may be passed here — a session itself
+        // has no session ancestor, so guessAdapter above accepted one and this
+        // threw on it
+        const { pluginManager } = getEnv(model);
+        const trackTypeGuesser = pluginManager.evaluateExtensionPoint(
         /** #extensionPoint Core-guessTrackTypeForLocation | sync | Guess a track type from a file location */
         'Core-guessTrackTypeForLocation', () => undefined);
         const trackType = trackTypeGuesser(adapterType, file);
@@ -391,38 +393,39 @@ export function guessTrackType(adapterType, model, file) {
  * the caller can ask for a full config instead.
  */
 export function guessTrackConf(input, pluginManager, assemblyName) {
-    const { uri, index, ...extra } = typeof input === 'string' ? { uri: input } : input;
-    const file = { uri, locationType: 'UriLocation' };
-    const indexLocation = index
-        ? { uri: index, locationType: 'UriLocation' }
-        : undefined;
+    const { uri, index, baseUri, ...extra } = typeof input === 'string' ? { uri: input } : input;
+    const base = baseUri ? { baseUri } : {};
+    return {
+        ...guessTrackConfForLocation({ uri, locationType: 'UriLocation', ...base }, index ? { uri: index, locationType: 'UriLocation', ...base } : undefined, pluginManager, assemblyName),
+        ...extra,
+    };
+}
+/**
+ * {@link guessTrackConf} over an already-built {@link FileLocation}, for a
+ * caller holding a location the loose `{ uri }` vocabulary cannot spell — a
+ * desktop local path. Kept separate so `LooseTrackInput` stays URI-only: it
+ * sits on the track-config union and the root config's `tracks`, where a
+ * local path would be a config a web deployment could not open.
+ *
+ * The `trackId` is a content hash of the adapter, not a timestamp, so adding
+ * the same file twice is idempotent — `addToSession` dedupes on it.
+ */
+export function guessTrackConfForLocation(file, index, pluginManager, assemblyName) {
     const adapterGuesser = pluginManager.evaluateExtensionPoint('Core-guessAdapterForLocation', () => undefined);
-    const adapter = adapterGuesser(file, indexLocation, undefined);
+    const adapter = adapterGuesser(file, index, undefined);
+    const name = getFileName(file);
     if (!adapter || adapter.type === UNKNOWN) {
-        throw new Error(`could not infer a track type from "${uri}"; pass a full track config instead`);
+        throw new Error(`could not infer a track type from "${name}"; pass a full track config instead`);
     }
     const trackTypeGuesser = pluginManager.evaluateExtensionPoint('Core-guessTrackTypeForLocation', () => undefined);
-    const name = getFileName(file);
     return {
         trackId: `${name}-${objectHash(adapter).slice(0, 8)}`,
         type: trackTypeGuesser(adapter.type, file) ?? 'FeatureTrack',
         name,
         assemblyNames: assemblyName ? [assemblyName] : [],
         adapter,
-        ...extra,
     };
 }
-/**
- * Whether a track snapshot is the loose `{ uri, ... }` form — a data file with
- * no `adapter` — that {@link expandLooseTrackConfig} expands.
- */
-export function isLooseTrackConfig(snap) {
-    return (typeof snap === 'object' &&
-        snap !== null &&
-        !Array.isArray(snap) &&
-        typeof snap.uri === 'string' &&
-        !('adapter' in snap));
-}
 /**
  * Expand a loose track config into a full one and leave any other snapshot
  * untouched, so it can sit on every path a track snapshot enters the tree by:
@@ -476,27 +479,83 @@ export function getTrackName(conf, session) {
         : (conf.trackId ?? '');
     return trackName || trackId;
 }
-/**
- * Which display a track opens with in a given view, and the display config that
- * display must use: `{ type, conf }`, or undefined when the view supports none
- * of the track's displays.
- *
- * Two decisions, in this order, and the order is the point. The **type** is what
- * the caller asked for, else the track's first declared display the view
- * supports, else the track type's first supported display. The **config** is
- * then whichever declared entry has that type — never "the first supported one",
- * which is what let a display be created wearing another display's config node
- * (a multi-sample VCF declares both the matrix and the regular display, so the
- * regular one inherited the matrix's 20px connector-line zone and drew its
- * clustering tree offset from the rows it labels). `display.type ===
- * display.configuration.type` is the invariant `DisplayConfigurationReference`
- * already assumes when it falls back to resolving a display config by type; this
- * is where it has to hold.
- *
- * `conf` is undefined when the track config declares no entry of that type;
- * `baseTrackConfig.preProcessSnapshot` injects one for every registered display
- * type, so the caller's `${trackId}-${type}` id resolves to it.
- */
+// The first-show path spreads the same settings into the display's `create()`
+// snapshot, so a DECLARED PROP (`resolution` on the wiggle displays) has
+// already landed by the time applyDisplaySettings reports it took no slot.
+// Only a declared prop: MST restores nothing else from a snapshot, so a
+// volatile or a getter of the same name (`scrollTop`) did not land and the
+// caller has to hear about it.
+function didNotLand(unapplied, display) {
+    const model = display ? asModelType(getType(display)) : undefined;
+    const props = model ? Object.keys(model.properties) : [];
+    return unapplied.filter(entry => !props.includes(entry.key));
+}
+function notifySettingsReport(session, trackId, displayType, unapplied, failed) {
+    const label = `${displayType} for track "${trackId}"`;
+    const keys = (of) => of.map(entry => entry.key);
+    const setterOnly = unapplied.filter(e => e.reason === 'setter-only');
+    const unknown = unapplied.filter(e => e.reason !== 'setter-only');
+    if (unknown.length) {
+        session.notifyError(unknownKeysMessage(label, keys(unknown)));
+    }
+    if (setterOnly.length) {
+        session.notifyError(setterOnlyMessage(label, keys(setterOnly)));
+    }
+    if (failed.length) {
+        session.notifyError(`Track "${trackId}" rejected ${failed.map(f => `${f.key}: ${f.error}`).join('; ')}`);
+    }
+}
+// The display a shown track switches to for a `type` it is not drawn as.
+function displaySwitch(self, trackId, track, requested) {
+    if (requested === undefined) {
+        return undefined;
+    }
+    const { pluginManager } = getEnv(self);
+    const type = pluginManager.resolveDisplayTypeRecord(requested)?.name;
+    if (type === track.activeDisplay.type) {
+        return undefined;
+    }
+    const target = track.compatibleDisplays.find(d => d.type === type);
+    if (!target) {
+        const view = isViewModel(self) ? self : getContainingView(self);
+        throw new Error(`Track "${trackId}" cannot be shown as "${requested}" in a ${view.type}. It takes: ${track.compatibleDisplays.map(d => d.type).join(', ')}`);
+    }
+    return target;
+}
+// A switch carries the settings in the new display's snapshot, as a first show
+// does, and hands off to the async launch while that display's state model is
+// still a dynamic import.
+function restyleShown(self, trackId, found, displayInitialSnapshot) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    const track = found;
+    const { type, ...settings } = displayInitialSnapshot;
+    try {
+        const target = displaySwitch(self, trackId, track, type);
+        if (target) {
+            const record = pluginManager.resolveDisplayTypeRecord(target.type);
+            if (record && !record.isStateModelLoaded) {
+                void launchTrackGeneric(self, trackId, {}, displayInitialSnapshot);
+                return undefined;
+            }
+            track.replaceDisplay(track.activeDisplay.configuration.displayId, target.displayId, {
+                ...track.activeDisplay.getPortableSettings?.(target.displayId),
+                ...settings,
+            });
+        }
+        if (Object.keys(settings).length && track.applyDisplaySettings) {
+            const report = track.applyDisplaySettings(settings);
+            notifySettingsReport(session, trackId, track.activeDisplay.type, target
+                ? didNotLand(report.unapplied, track.displays[0])
+                : report.unapplied, report.failed);
+        }
+        return found;
+    }
+    catch (e) {
+        session.notifyError(`${e}`, e);
+        return undefined;
+    }
+}
 /**
  * The display type names a view can render, as a lookup set. Built once per
  * view and handed to {@link viewCanDisplayTrack} for every track, rather than
@@ -506,17 +565,10 @@ export function viewDisplayNames(pluginManager, viewType) {
     return new Set(pluginManager.getViewType(viewType).displayTypes.map(d => d.name));
 }
 /**
- * Whether a view rendering `viewDisplays` can open a track of this type at all
- * — does the track type declare a display the view draws. The coarse half of
- * the question {@link pickDisplayForView} answers precisely: a picker that
- * offers a track this says no to is offering one `showTrackGeneric` will
- * refuse.
- *
- * Reads the *track type's* registered displays rather than a config's own
- * `displays` array, which is both cheaper and the only form available on an
- * un-hydrated frozen track config (ADR-032). The two agree, since
- * `preprocessTrackConfigSnapshot` injects a stub display for every display the
- * track type registers.
+ * Whether a view rendering `viewDisplays` can open a track at all: does the
+ * track's adapter feed a display the view draws. The coarse half of the
+ * question {@link pickDisplayForView} answers precisely, over the same
+ * candidates, so a picker never offers a track `showTrackGeneric` will refuse.
  *
  * Two answers that are easy to get wrong, and both have been:
  *
@@ -530,20 +582,101 @@ export function viewDisplayNames(pluginManager, viewType) {
  *   every track passes. That is a policy rather than a fact, and it lives here
  *   so the pickers agree on it.
  */
-export function viewCanDisplayTrack(pluginManager, viewDisplays, trackType) {
-    if (!pluginManager.trackTypes.has(trackType)) {
+export function viewCanDisplayTrack(pluginManager, viewDisplays, track) {
+    if (!pluginManager.trackTypes.has(track.type)) {
         return false;
     }
     return (viewDisplays.size === 0 ||
-        pluginManager
-            .getTrackType(trackType)
-            .displayTypes.some(d => viewDisplays.has(d.name)));
+        displayTypesFedBy(pluginManager, track.type, track.adapter).some(name => viewDisplays.has(name)));
+}
+/**
+ * Whether every name in `subset` appears in `superset`. An absent superset
+ * contains nothing; an absent subset is contained by anything.
+ */
+function containsAll(superset = [], subset = []) {
+    const s = new Set(superset);
+    return subset.every(x => s.has(x));
+}
+/**
+ * The tracks a view can be offered: those that support every assembly it
+ * displays, and that declare a display it can draw. The track selector's tree
+ * and every other picker that opens a track into a view read this one answer,
+ * or one of them offers a track the next hides.
+ */
+export function filterTracks(tracks, self) {
+    const { view } = self;
+    if (!view) {
+        return [];
+    }
+    const { assemblyManager } = getSession(view);
+    const { pluginManager } = getEnv(view);
+    const canonical = (names) => canonicalAssemblyNames(names, assemblyManager);
+    const viewAssemblyNames = canonical(self.assemblyNames);
+    const viewDisplays = viewDisplayNames(pluginManager, view.type);
+    return tracks.filter(c => {
+        const trackAssemblyNames = readConfObject(c, 'assemblyNames');
+        return (
+        // a view that declares no assemblies (one still initializing) constrains
+        // nothing; otherwise the track must cover every one of them
+        (viewAssemblyNames.length === 0 ||
+            containsAll(trackAssemblyNames && canonical(trackAssemblyNames), viewAssemblyNames)) &&
+            viewCanDisplayTrack(pluginManager, viewDisplays, {
+                type: c.type,
+                adapter: c.adapter,
+            }));
+    });
+}
+/**
+ * The assembly's own sequence track, when the view can draw one. It is in no
+ * track list — the config lives on the assembly (see {@link getConfAssemblyNames}
+ * on why a sequence track's assembly is positional) — so a picker that walks
+ * `session.tracks` alone cannot offer the track most views open first.
+ */
+function refSeqTrackConf(assemblyName, view) {
+    const { assemblyManager } = getSession(view);
+    const { pluginManager } = getEnv(view);
+    const conf = assemblyManager.get(assemblyName)?.configuration.sequence;
+    // the same display-compatibility question filterTracks asks of every other
+    // track, so a view that cannot draw a sequence is not offered one
+    return conf &&
+        viewCanDisplayTrack(pluginManager, viewDisplayNames(pluginManager, view.type), { type: conf.type, adapter: conf.adapter })
+        ? conf
+        : undefined;
+}
+/**
+ * Every track config a view can be offered, each assembly's sequence track
+ * first and then {@link filterTracks} over the list handed in.
+ */
+export function offeredTracks(tracks, self) {
+    const { view, assemblyNames } = self;
+    if (!view) {
+        return [];
+    }
+    return [
+        ...assemblyNames.map(name => refSeqTrackConf(name, view)),
+        ...filterTracks(tracks, self),
+    ].filter(conf => conf !== undefined);
 }
-export function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, }) {
+/**
+ * Which display a track opens with in a given view, and the declared entry
+ * that configures it: `{ type, conf }`, or undefined when the view draws none
+ * of the candidates or the requested type is not among them.
+ *
+ * The **type** is the requested one, checked rather than taken on faith (an
+ * unchecked one resolved its dangling `<trackId>-<type>` id back to the
+ * track's default display, and the caller was told it got what it asked for),
+ * else the first candidate among the view's own display types, else the first
+ * it draws at all. The **config** is then the declared entry of that type,
+ * never another one the view supports: `display.type ===
+ * display.configuration.type` is the invariant `DisplayConfigurationReference`
+ * assumes when it falls back to resolving by type.
+ */
+export function pickDisplayForView({ candidates, declaredDisplays, requestedType, viewDisplayTypes, preferredDisplayTypes = new Set(), }) {
     const supported = new Set(viewDisplayTypes);
-    const type = requestedType ??
-        declaredDisplays.find(d => supported.has(d.type))?.type ??
-        trackDisplayTypes.find(name => supported.has(name));
+    const drawable = candidates.filter(name => supported.has(name));
+    const type = requestedType === undefined
+        ? (drawable.find(name => preferredDisplayTypes.has(name)) ?? drawable[0])
+        : drawable.find(name => name === requestedType);
     return type === undefined
         ? undefined
         : { type, conf: declaredDisplays.find(d => d.type === type) };
@@ -572,6 +705,79 @@ export function normalizeTrackInit(t) {
         };
     }
 }
+function resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    // `trackId` seeds the expansion because `guessTrackConf` otherwise
+    // synthesizes one from the filename, and the dedupe in the callers and
+    // `hideTrackGeneric` both look the track up by the id the caller passed.
+    // Only for the loose form: spreading a live MST node (SvInspector's
+    // circular track) would flatten it out of the `isStateTreeNode` branch.
+    const inlineRawConf = isLooseTrackConfig(inlineConf)
+        ? expandLooseTrackConfig({ trackId, ...inlineConf }, pluginManager)
+        : inlineConf;
+    const rawConf = inlineRawConf ?? session.getTrackById(trackId);
+    if (!rawConf) {
+        throw new Error(`Could not resolve identifier "${trackId}"`);
+    }
+    const confSnapshot = structuredClone(isStateTreeNode(rawConf) ? getSnapshot(rawConf) : rawConf);
+    // `& { type: string }` because `rawConf` unions a live node with a loose
+    // `Record<string, unknown>`, and the node's `type: string` widens back to
+    // `unknown` across that union
+    const conf = pluginManager.evaluateExtensionPoint('Core-preProcessTrackConfig', confSnapshot);
+    const trackType = pluginManager.getTrackType(conf.type);
+    // Validate only a conf that is not already in the tree. `configSchema.create`
+    // here builds an entire config node and throws it away purely to surface a
+    // nice error; its preProcessSnapshot also re-runs Core-preProcessTrackConfig
+    // on a snapshot this function just preprocessed. A conf that is a state tree
+    // node was validated when MST created it, so all of that is pure waste on
+    // the common showTrack path.
+    if (!isStateTreeNode(rawConf)) {
+        try {
+            trackType.configSchema.create(conf, getEnv(self));
+        }
+        catch (e) {
+            throw new Error(`Track "${trackId}" has an invalid configuration: ${e}`, {
+                cause: e,
+            });
+        }
+    }
+    // A track container that isn't itself a view — a synteny level, which owns
+    // a track list but has no width and no registered view type — takes the
+    // display choice from the view it sits in, which is the same node
+    // getContainingView already resolves to for everything else beneath it.
+    const view = isViewModel(self) ? self : getContainingView(self);
+    const viewType = pluginManager.getViewType(view.type);
+    const candidates = displayCandidates(pluginManager, conf);
+    const viewDisplayTypes = viewType.displayTypes.map(d => d.name);
+    // Aliases resolve first, so a caller or a config naming a pre-consolidation
+    // display type (`LinearPileupDisplay`) reaches the type that replaced it; a
+    // name no display answers to stays as written, for the refusal to quote.
+    const canonical = (name) => pluginManager.resolveDisplayTypeRecord(name)?.name ?? name;
+    const requested = displayInitialSnapshot.type;
+    const declaredDisplays = conf.displays ?? [];
+    const picked = pickDisplayForView({
+        candidates,
+        declaredDisplays: declaredDisplays.map(d => ({
+            ...d,
+            type: canonical(d.type),
+        })),
+        requestedType: requested === undefined ? undefined : canonical(requested),
+        viewDisplayTypes,
+        preferredDisplayTypes: new Set(viewType.displayTypes
+            .filter(d => d.viewType === view.type)
+            .map(d => d.name)),
+    });
+    if (!picked) {
+        const drawable = candidates.filter(name => viewDisplayTypes.includes(name));
+        throw new Error(requested === undefined
+            ? `Could not find a compatible display for view type ${view.type}`
+            : `Track "${trackId}" cannot be shown as "${requested}" in a ${view.type}. ${drawable.length > 0
+                ? `It takes: ${drawable.join(', ')}`
+                : 'This view draws none of its display types'}`);
+    }
+    return { rawConf, conf, trackType, picked };
+}
 export function showTrackGeneric(self, trackId, 
 // `object`, annotated, rather than inferred from the default. A bare `{}`
 // accepts every non-nullish value, numbers included, which is how a synteny
@@ -591,85 +797,60 @@ inlineConf) {
     const session = getSession(self);
     const found = self.tracks.find(t => t.configuration.trackId === trackId);
     if (found) {
-        return found;
+        return restyleShown(self, trackId, found, displayInitialSnapshot);
     }
     // Single choke point for all "open a track" paths — errors surface as
     // snackbars. Config is validated before the push so the open set never holds
     // a broken track.
     try {
-        const rawConf = (inlineConf && expandLooseTrackConfig(inlineConf, pluginManager)) ??
-            session.getTrackById(trackId);
-        if (!rawConf) {
-            throw new Error(`Could not resolve identifier "${trackId}"`);
-        }
-        const confSnapshot = structuredClone(isStateTreeNode(rawConf) ? getSnapshot(rawConf) : rawConf);
-        const conf = pluginManager.evaluateExtensionPoint('Core-preProcessTrackConfig', confSnapshot);
-        const trackType = pluginManager.getTrackType(conf.type);
-        // Validate only a conf that is not already in the tree. `configSchema.create`
-        // here builds an entire config node and throws it away purely to surface a
-        // nice error; its preProcessSnapshot also re-runs Core-preProcessTrackConfig
-        // on a snapshot this function just preprocessed. A conf that is a state tree
-        // node was validated when MST created it, so all of that is pure waste on
-        // the common showTrack path.
-        if (!isStateTreeNode(rawConf)) {
-            try {
-                trackType.configSchema.create(conf, getEnv(self));
-            }
-            catch (e) {
-                throw new Error(`Track "${trackId}" has an invalid configuration: ${e}`, { cause: e });
-            }
-        }
-        // A track container that isn't itself a view — a synteny level, which owns
-        // a track list but has no width and no registered view type — takes the
-        // display choice from the view it sits in, which is the same node
-        // getContainingView already resolves to for everything else beneath it.
-        const view = isViewModel(self) ? self : getContainingView(self);
-        const viewType = pluginManager.getViewType(view.type);
-        const picked = pickDisplayForView({
-            declaredDisplays: conf.displays ?? [],
-            requestedType: displayInitialSnapshot.type,
-            trackDisplayTypes: trackType.displayTypes.map(d => d.name),
-            viewDisplayTypes: viewType.displayTypes.map(d => d.name),
-        });
-        if (!picked) {
-            throw new Error(`Could not find a compatible display for view type ${view.type}`);
-        }
+        const { rawConf, conf, trackType, picked } = resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf);
         const { type: displayType, conf: displayConf } = picked;
         const displayId = displayConf?.displayId ?? `${trackId}-${displayType}`;
+        // a registered display whose model is not loaded yet: the load re-enters
+        // through the view's own showTrack action, so a synchronous caller gets the
+        // track a tick late; a caller that needs it back awaits launchTrack
+        const displayRecord = pluginManager.resolveDisplayTypeRecord(displayType);
+        if (displayRecord && !displayRecord.isStateModelLoaded) {
+            void launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
+            return undefined;
+        }
         const track = trackType.stateModel.create({
             ...initialSnapshot,
             type: conf.type,
-            configuration: inlineConf ?? trackId,
+            // `rawConf`, not the caller's `inlineConf`: the loose `{ trackId, uri }`
+            // form has no `type` for the config schema to dispatch on, and the
+            // concrete schema this lands on carries no loose preprocessor — that one
+            // is on `pluggableConfigSchemaType('track')`, which a track model's
+            // `ConfigurationReference` is not. Not `conf` either: that has already
+            // run Core-preProcessTrackConfig, which the schema's own
+            // preProcessSnapshot runs again.
+            configuration: inlineConf ? rawConf : trackId,
             displays: [
                 {
                     ...displayConf,
-                    type: displayType,
                     configuration: displayId,
                     ...displayInitialSnapshot,
+                    type: displayType,
                 },
             ],
         });
         self.tracks.push(track);
         // Display settings (height, color, …) are config slots now, not display
         // instance props — passed in the display snapshot they'd be dropped as
-        // unknown MST keys. Route the ones that are real slots onto the persistent
-        // display config so they take effect and survive hide/retick (#5591). Runs
-        // after the push so the display's config reference can resolve.
-        //
-        // preProcessSlotValues first, so a display schema's shorthand expansions
-        // and legacy-key migrations reach this path too: a session spec, share
-        // link, or embed writes slots here rather than creating a config from a
-        // snapshot, and those two surfaces are meant to speak the same vocabulary.
-        const display = track.displays[0];
-        const displaySlots = preProcessSlotValues(display.configuration, displayInitialSnapshot);
-        for (const [key, value] of Object.entries(displaySlots)) {
-            if (key !== 'type' && isConfigurationSlot(display.configuration, key)) {
-                // the key comes from a snapshot at runtime, and setConf's slot name is
-                // a compile-time type
-                // eslint-disable-next-line no-restricted-syntax
-                display.configuration.setSlot(key, value);
-            }
-        }
+        // unknown MST keys. applyDisplaySettings routes the ones that are real
+        // slots onto the persistent display config so they take effect and
+        // survive hide/retick (#5591), running the schema's preProcessSnapshot
+        // first so shorthand expansions and legacy-key migrations reach this path
+        // too — a session spec, share link, or embed writes slots here rather
+        // than creating a config from a snapshot, and those surfaces are meant to
+        // speak the same vocabulary. Runs after the push so the display's config
+        // reference can resolve. Slots only, deliberately: this is the
+        // declarative surface, and `allowSetters` stays off so a spec key cannot
+        // reach internal display actions.
+        const displaySettings = Object.fromEntries(Object.entries(displayInitialSnapshot).filter(([key]) => key !== 'type'));
+        const report = track.applyDisplaySettings(displaySettings);
+        const drawn = track.displays[0];
+        notifySettingsReport(session, trackId, displayType, didNotLand(report.unapplied, drawn), report.failed);
         // if this track came from a connection, persist its config so it survives
         // reload without re-establishing the connection (no-op otherwise)
         session.captureConnectionTrack?.(trackId);
@@ -708,6 +889,137 @@ export function toggleTrackGeneric(self, trackId) {
         ? false
         : !!showTrackGeneric(self, trackId);
 }
+/**
+ * Start loading the state model and component of the display a track would
+ * open with, without opening it, for a caller that knows the track is coming.
+ * Anything that fails here is the launch's to report.
+ */
+export function warmTrackDisplayGeneric(self, trackId, displayInitialSnapshot = {}, assemblyName) {
+    const { pluginManager } = getEnv(self);
+    try {
+        const { picked } = resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot);
+        pluginManager
+            .resolveDisplayTypeRecord(picked.type)
+            ?.loadStateModel()
+            .catch(() => { });
+        warmTrackAdapter(self, trackId, assemblyName);
+    }
+    catch {
+        // the launch reports an unresolvable track
+    }
+}
+function adapterTypesIn(value, pluginManager, found = new Set()) {
+    if (typeof value === 'object' && value !== null) {
+        const { type } = value;
+        if (typeof type === 'string' && pluginManager.hasAdapterType(type)) {
+            found.add(type);
+        }
+        for (const child of Object.values(value)) {
+            adapterTypesIn(child, pluginManager, found);
+        }
+    }
+    return found;
+}
+/**
+ * Load the track's adapter code and read its index in the worker, beside the
+ * assembly load the track's first request waits for.
+ *
+ * Sent under the id the track's own requests will use, so it reaches, and
+ * boots, the worker that serves them. That id hashes the adapter config as the
+ * track's config node reads it, so a frozen config.json entry is read through a
+ * node of its type: its raw adapter snapshot hashes to another worker.
+ *
+ * `assemblyName` is the one the view is launching on. The track's own
+ * `assemblyNames[0]` is not that: a reference-reading adapter is built for the
+ * genome its request names, and warming it for the config's first assembly
+ * would build an instance the view never reads.
+ */
+function declaresLanes(adapterConfig, pluginManager) {
+    const { type } = adapterConfig;
+    return (typeof type === 'string' &&
+        pluginManager.hasAdapterType(type) &&
+        pluginManager
+            .getAdapterType(type)
+            .adapterCapabilities.includes('headerLanes'));
+}
+function warmTrackAdapter(self, trackId, assemblyName) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    const raw = session.getTrackById(trackId);
+    const conf = isStateTreeNode(raw)
+        ? raw
+        : typeof raw?.type === 'string'
+            ? pluginManager
+                .getTrackType(raw.type)
+                .configSchema.create(raw, { pluginManager })
+            : undefined;
+    if (conf) {
+        const adapterConfig = readConfObject(conf, 'adapter');
+        const sessionId = getConfRpcSessionId(conf);
+        session.rpcManager
+            // eslint-disable-next-line no-restricted-syntax -- a code download the track's first request would make anyway: nothing to show, and nothing a user can move on from
+            .call(sessionId, 'CoreLoadAdapterCode', {
+            adapterTypes: [...adapterTypesIn(adapterConfig, pluginManager)],
+        })
+            .catch(() => { });
+        // a source that declares its lanes reads an index per lane asked about,
+        // and only its display knows which; asked about none it would read all
+        if (assemblyName && !declaresLanes(adapterConfig, pluginManager)) {
+            session.rpcManager
+                // eslint-disable-next-line no-restricted-syntax -- an index read the track's first request would make anyway: nothing to show, and nothing a user can move on from
+                .call(sessionId, 'CoreGetRefNames', {
+                adapterConfig,
+                assemblyName,
+                signal: undefined,
+            })
+                .catch(() => { });
+        }
+    }
+}
+export async function launchTrackGeneric(self, trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    const found = self.tracks.find(t => t.configuration.trackId === trackId);
+    if (found) {
+        let target;
+        try {
+            target = displaySwitch(self, trackId, found, displayInitialSnapshot.type);
+            if (target) {
+                await pluginManager
+                    .resolveDisplayTypeRecord(target.type)
+                    ?.loadStateModel();
+            }
+        }
+        catch (e) {
+            session.notifyError(`${e}`, e);
+            return undefined;
+        }
+        if (!target) {
+            return restyleShown(self, trackId, found, displayInitialSnapshot);
+        }
+        return isAlive(self) && isAlive(found)
+            ? self.showTrack?.(trackId, initialSnapshot, displayInitialSnapshot, inlineConf)
+            : undefined;
+    }
+    try {
+        const { picked } = resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf);
+        await pluginManager.resolveDisplayTypeRecord(picked.type)?.loadStateModel();
+    }
+    catch (e) {
+        session.notifyError(`${e}`, e);
+        return undefined;
+    }
+    if (!isAlive(self)) {
+        return undefined;
+    }
+    return self.showTrack?.(trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
+}
+// the hide runs in the synchronous prologue, so it keeps action context
+export async function launchToggleTrackGeneric(self, trackId) {
+    return hideTrackGeneric(self, trackId)
+        ? false
+        : !!(await launchTrackGeneric(self, trackId));
+}
 /**
  * Every track config the session can show, connection-supplied ones included.
  *
@@ -726,3 +1038,41 @@ export function allSessionTracks(session) {
         ? [...session.tracks, ...connectionTracks]
         : session.tracks;
 }
+/**
+ * The session's annotation for `assemblyName`, as trackIds: what a view opened
+ * on another genome starts with. Only FeatureTracks, not everything configured
+ * for the assembly — an alignments track turned on behind the user's back
+ * fetches data nobody asked for, and a FeatureTrack over a few kb is one tabix
+ * range query.
+ */
+export function annotationTrackIds(session, assemblyName) {
+    return allSessionTracks(session).flatMap(track => readConfObject(track, 'type') === 'FeatureTrack' &&
+        readConfObject(track, 'assemblyNames').some(name => isSameAssemblyName(name, assemblyName, session.assemblyManager))
+        ? [readConfObject(track, 'trackId')]
+        : []);
+}
+function isNavigableView(view) {
+    return 'navToLocString' in view;
+}
+/**
+ * One assembly on its own in a linear genome view, at `loc`. Keyed on `id`:
+ * following several alignments to one genome re-navigates the view rather than
+ * stacking a new one each time.
+ */
+export async function openAssemblyInLinearView({ session, id, assemblyName, loc, tracks, }) {
+    const view = session.views.find(v => v.id === id);
+    if (view && isNavigableView(view)) {
+        await view.navToLocString(loc, assemblyName);
+    }
+    else {
+        session.addView('LinearGenomeView', {
+            id,
+            assembly: assemblyName,
+            loc,
+            tracks,
+        });
+    }
+}
+export function openMateLabel(assemblyName) {
+    return `Open ${assemblyName} at the matching region`;
+}