@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/tracks.js

@@ -1,48 +1,122 @@
-import { getParent, getSnapshot, isRoot, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
-import { getFileHandle, storeFileHandle, verifyPermission, } from "./fileHandleStore.js";
-import { getEnv, getSession, objectHash } from "./index.js";
-import { readConfObject } from "../configuration/index.js";
-const trackAssemblyNamesCache = new WeakMap();
+// Re-exported because `@jbrowse/core/util/tracks` is the path plugins import it
+// from. It must come first: `../configuration` imports the util barrel, which
+// imports this module back, and a re-export declared after that cycle has a
+// getter that fires before its own require has run.
+export { getFileName } from './getFileName.js';
+// Lives in `./mstUtils.ts` with the rest of the tree walks, and is re-exported
+// here because `@jbrowse/core/util/tracks` is a plugin ABI module that offers
+// 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, hasParent, isAlive, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { observable, runInAction, untracked } from 'mobx';
+import { readConfObject } from '../configuration/index.js';
+import { getFileHandle, storeFileHandle, verifyPermission, } from './fileHandleStore.js';
+import { getFileName } from './getFileName.js';
+import { getContainingView, getEnv, getSession, objectHash, } from './mstUtils.js';
+import { isViewModel } from './types/index.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
+// assemblyNames in the config editor did not invalidate it. The reads are
+// per-view-change, not per-feature, so MobX's own computed caching is enough.
 export function getTrackAssemblyNames(track) {
-    let cached = trackAssemblyNamesCache.get(track);
-    if (!cached) {
-        cached = getConfAssemblyNames(track.configuration);
-        trackAssemblyNamesCache.set(track, cached);
-    }
-    return cached;
-}
-export function getConfAssemblyNames(conf) {
+    return getConfAssemblyNames(track.configuration);
+}
+/**
+ * Assembly names as the aliases resolve them, so a track configured against
+ * `hg38` compares equal to a view on `GRCh38`. Every "does this track belong to
+ * these assemblies" test should run both sides through this, or the same track
+ * is offered by one picker and hidden by another.
+ *
+ * A name the assembly manager doesn't know is kept **as written**, not dropped.
+ * Dropping it means "matches nothing" on the track side but "no constraint at
+ * all" on the list side, and those disagree; kept, both sides compare the same
+ * raw string and matching degrades to the exact name — which is also the right
+ * answer in the window before the assembly manager has built its models. Empty
+ * names are dropped: a half-initialized view pads its assembly list with them.
+ */
+export function canonicalAssemblyNames(names, assemblyManager) {
+    return names
+        .filter(name => !!name)
+        .map(name => assemblyManager.getCanonicalAssemblyName(name) ?? name);
+}
+/**
+ * Whether two names name the same assembly, resolving aliases on both sides.
+ *
+ * The pairwise counterpart to {@link canonicalAssemblyNames}, for the two
+ * places a list cannot be mapped: an index-aligned array, which that function's
+ * empty-name filter would desync, and a comparison where one side must come
+ * back in the caller's own spelling rather than the canonical one.
+ *
+ * **Both sides, or it buys nothing.** The names meeting at these comparisons
+ * come from different places — a view holds what the session opened it on, a
+ * track config holds what its author wrote, and a synteny mate holds whatever
+ * the adapter resolved a PanSN prefix to. Any two of those can be aliases of
+ * one assembly, and `===` says no.
+ *
+ * A name the assembly manager doesn't know compares as written, the same
+ * degradation {@link canonicalAssemblyNames} makes and for the same reason: an
+ * all-vs-all file carries sample names no config declares, and those still have
+ * to compare equal to themselves.
+ */
+export function isSameAssemblyName(a, b, assemblyManager) {
+    if (!a || !b) {
+        return false;
+    }
+    return (a === b ||
+        (assemblyManager.getCanonicalAssemblyName(a) ?? a) ===
+            (assemblyManager.getCanonicalAssemblyName(b) ?? b));
+}
+/**
+ * The assemblies a track config names, or `undefined` when it names none.
+ *
+ * Two shapes, and the second is why this is a function rather than a slot read.
+ * A track built on `createBaseTrackConfig` carries `assemblyNames`.
+ * `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) {
-        const parent = getParent(conf);
-        if ('sequence' in parent) {
-            return [readConfObject(parent, 'name')];
-        }
-        else {
-            throw new Error('unknown assembly names');
-        }
+    if (trackAssemblyNames) {
+        return trackAssemblyNames;
     }
-    return trackAssemblyNames;
-}
-export function getRpcSessionId(thisNode) {
-    let highestRpcSessionId;
-    for (let node = thisNode; !isRoot(node); node = getParent(node)) {
-        if ('rpcSessionId' in node) {
-            highestRpcSessionId = node.rpcSessionId;
-        }
-    }
-    if (!highestRpcSessionId) {
-        throw new Error('getRpcSessionId failed, no parent node in the state tree has an `rpcSessionId` attribute');
+    if (!hasParent(conf)) {
+        return undefined;
     }
-    return highestRpcSessionId;
+    const parent = getParent(conf);
+    return 'sequence' in parent
+        ? [readConfObject(parent, 'name')]
+        : undefined;
 }
-export function getParentRenderProps(node) {
-    for (let currentNode = getParent(node); !isRoot(currentNode); currentNode = getParent(currentNode)) {
-        if ('renderProps' in currentNode) {
-            return currentNode.renderProps();
-        }
-    }
-    return {};
+export function getConfAssemblyNames(conf) {
+    const names = confAssemblyNames(conf);
+    if (!names) {
+        throw new Error('unknown assembly names');
+    }
+    return names;
+}
+/**
+ * {@link getConfAssemblyNames} for a caller that cannot afford its throw — a
+ * config answering neither way leaves the question unanswered instead.
+ *
+ * `BaseTrackModel.refNameMismatch` is the caller: it runs on every render of
+ * every track label, so an unanswerable question must not become a thrown
+ * getter. It used to read the raw `assemblyNames` slot itself for that reason,
+ * which is a second, subtly different copy of the walk above — and one that
+ * answers `[]` for a ReferenceSequenceTrack whose assembly this already knows
+ * how to name.
+ */
+export function getConfAssemblyNamesOrNone(conf) {
+    return confAssemblyNames(conf) ?? [];
 }
 export const UNKNOWN = 'UNKNOWN';
 export const UNSUPPORTED = 'UNSUPPORTED';
@@ -53,10 +127,17 @@ export function getBlob(id) {
 export function getBlobMap() {
     return blobMap;
 }
+// Populates the blobMap in a fresh JS realm (e.g. a web worker, which starts
+// with an empty module-level blobMap). RPC args are the only channel into the
+// worker, so the main thread ships its full blobMap and the worker replaces its
+// own here before adapters call the synchronous getBlob() during openLocation.
 export function setBlobMap(map) {
     blobMap = map;
 }
 let counter = 0;
+// blob files are stored in a global map. the blobId is based on a combination
+// of timestamp plus counter to be unique across sessions and fast repeated
+// calls
 export function storeBlobLocation(location) {
     if ('blob' in location) {
         const blobId = `b${Date.now()}-${counter++}`;
@@ -69,24 +150,33 @@ export function storeBlobLocation(location) {
     }
     return location;
 }
-let fileHandleCache = {};
+// openLocation is synchronous, so File objects are cached here after async handle
+// resolution. Observable so an open LocalFileChooser reactively clears its "needs
+// reload" notice once a restore (afterAttach / "Restore access") populates the
+// cache; the worker/RPC readers run outside any reaction so nothing else
+// subscribes.
+const fileHandleCache = observable.map();
 export function getFileFromCache(handleId) {
-    return fileHandleCache[handleId];
+    return fileHandleCache.get(handleId);
 }
 export function setFileInCache(handleId, file) {
-    fileHandleCache[handleId] = file;
+    runInAction(() => {
+        fileHandleCache.set(handleId, file);
+    });
 }
 export function clearFileFromCache(handleId) {
-    delete fileHandleCache[handleId];
-}
-export function getFileHandleCache() {
-    return fileHandleCache;
+    runInAction(() => {
+        fileHandleCache.delete(handleId);
+    });
 }
-export function setFileHandleCache(cache) {
-    fileHandleCache = cache;
+export function hasFileHandlesInCache() {
+    // read in RpcMethodType.serializeArguments, which an RPC-fetch autorun can
+    // reach; untracked so populating the cache never re-triggers that autorun
+    // eslint-disable-next-line no-restricted-syntax -- self-write: the fetch this is reached from populates the cache
+    return untracked(() => fileHandleCache.size > 0);
 }
 export async function ensureFileHandleReady(handleId, requestPermission = true) {
-    const cached = fileHandleCache[handleId];
+    const cached = fileHandleCache.get(handleId);
     if (cached) {
         return cached;
     }
@@ -99,88 +189,100 @@ export async function ensureFileHandleReady(handleId, requestPermission = true)
         throw new Error(`Permission denied for file "${handle.name}". Click "Restore access" to grant permission.`);
     }
     const file = await handle.getFile();
-    fileHandleCache[handleId] = file;
+    setFileInCache(handleId, file);
     return file;
 }
 export async function storeFileHandleLocation(handle) {
     const handleId = await storeFileHandle(handle);
     const file = await handle.getFile();
-    fileHandleCache[handleId] = file;
+    setFileInCache(handleId, file);
     return {
         locationType: 'FileHandleLocation',
         name: handle.name,
         handleId,
     };
 }
+async function settleFileHandle(handleId, requestPermission) {
+    try {
+        await ensureFileHandleReady(handleId, requestPermission);
+        return { handleId, success: true };
+    }
+    catch (error) {
+        return { handleId, success: false, error };
+    }
+}
+/**
+ * Resolves a batch of stored file handles, one result per id.
+ *
+ * With `requestPermission` set these run ONE AT A TIME, and that is the whole
+ * point of the branch. `requestPermission()` needs transient user activation and
+ * the browser puts a single file-access prompt on screen at a time, so N of them
+ * fired off one "Restore access" click means the first call takes the prompt and
+ * the rest are refused without the user ever seeing a dialog — files reported
+ * back as permission failures that nobody was asked about. Taking turns, each
+ * prompt waits for the one before it to be answered, and whatever the activation
+ * window no longer covers is simply still pending for the next click instead of
+ * being spent.
+ *
+ * Without it nothing can prompt, so there is nothing to take turns over and the
+ * batch runs at once.
+ */
 export async function restoreFileHandles(handleIds, requestPermission = false) {
+    if (!requestPermission) {
+        return Promise.all(handleIds.map(id => settleFileHandle(id, false)));
+    }
     const results = [];
     for (const handleId of handleIds) {
-        try {
-            await ensureFileHandleReady(handleId, requestPermission);
-            results.push({ handleId, success: true });
-        }
-        catch (e) {
-            results.push({ handleId, success: false, error: e });
-        }
+        results.push(await settleFileHandle(handleId, true));
     }
     return results;
 }
-export function findFileHandleIds(obj, handleIds = new Set(), seen = new WeakSet()) {
-    if (!obj || typeof obj !== 'object') {
-        return handleIds;
-    }
-    if (seen.has(obj)) {
-        return handleIds;
-    }
-    seen.add(obj);
-    if (Array.isArray(obj)) {
-        for (const item of obj) {
-            findFileHandleIds(item, handleIds, seen);
+export function findFileHandleIds(obj) {
+    const handleIds = new Set();
+    const seen = new WeakSet();
+    function walk(o) {
+        if (!o || typeof o !== 'object' || seen.has(o)) {
+            return;
         }
-    }
-    else {
-        const record = obj;
-        if (record.locationType === 'FileHandleLocation' &&
-            typeof record.handleId === 'string') {
-            handleIds.add(record.handleId);
+        seen.add(o);
+        if (Array.isArray(o)) {
+            for (const item of o) {
+                walk(item);
+            }
         }
-        for (const value of Object.values(record)) {
-            findFileHandleIds(value, handleIds, seen);
+        else {
+            const record = o;
+            if (record.locationType === 'FileHandleLocation' &&
+                typeof record.handleId === 'string') {
+                handleIds.add(record.handleId);
+            }
+            for (const value of Object.values(record)) {
+                walk(value);
+            }
         }
     }
+    walk(obj);
     return handleIds;
 }
 export async function restoreFileHandlesFromSnapshot(sessionSnapshot, requestPermission = false) {
-    const handleIds = findFileHandleIds(sessionSnapshot);
-    if (handleIds.size > 0) {
-        return restoreFileHandles([...handleIds], requestPermission);
-    }
-    return [];
-}
-let pendingFileHandleIds = [];
-export function getPendingFileHandleIds() {
-    return pendingFileHandleIds;
-}
-export function setPendingFileHandleIds(ids) {
-    pendingFileHandleIds = ids;
-}
-export function clearPendingFileHandleIds() {
-    pendingFileHandleIds = [];
-}
-export async function restorePendingFileHandles() {
-    if (pendingFileHandleIds.length === 0) {
-        return [];
-    }
-    const results = await restoreFileHandles(pendingFileHandleIds, true);
-    const stillFailed = results.filter(r => !r.success).map(r => r.handleId);
-    pendingFileHandleIds = stillFailed;
-    return results;
-}
+    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) {
@@ -193,36 +295,78 @@ export function makeIndex(location, suffix) {
         return location;
     }
 }
+/**
+ * constructs a potential index file (with suffix) from the provided file name
+ *
+ * @param name - the name of the index file
+ * @param typeA - one option of a potential two file suffix (e.g. CSI, BAI)
+ * @param typeB - the second option of a potential two file suffix (e.g. CSI, BAI)
+ * @returns a likely name of the index file for a given filename
+ */
 export function makeIndexType(name, typeA, typeB) {
     return name?.toUpperCase().endsWith(typeA) ? typeA : typeB;
 }
-export function getFileName(track) {
-    const uri = 'uri' in track ? track.uri : undefined;
-    const localPath = 'localPath' in track ? track.localPath : undefined;
-    const blob = 'blobId' in track ? track : undefined;
-    const fileHandle = 'handleId' in track ? track : undefined;
-    if (blob?.name) {
-        return blob.name;
-    }
-    if (fileHandle?.name) {
-        return fileHandle.name;
-    }
-    if (uri) {
-        const normalized = uri.replace(/\\/g, '/');
-        return normalized.slice(normalized.lastIndexOf('/') + 1);
-    }
-    if (localPath) {
-        const normalized = localPath.replace(/\\/g, '/');
-        return normalized.slice(normalized.lastIndexOf('/') + 1);
-    }
-    return '';
+/**
+ * The `index` block a tabix-indexed adapter's guess writes: where the index is,
+ * and which of the two kinds it is.
+ *
+ * Eight guessers spelled this pair out by hand, which is the crossed-pair hazard
+ * `tabixIndexSnapshot` was extracted for on the config side: a `.csi` location
+ * filed under `indexType: 'TBI'` is a valid-looking config that opens no index
+ * at all, and nothing downstream can tell it from a correct one.
+ *
+ * BAM is deliberately not here, for the reason `tabixIndexFields` gives: BAI/CSI
+ * is a different enumeration over a different default, and folding the two would
+ * mean a slot whose vocabulary depends on its adapter.
+ */
+export function guessTabixIndex(file, index) {
+    return {
+        location: index ?? makeIndex(file, '.tbi'),
+        indexType: makeIndexType(index && getFileName(index), 'CSI', 'TBI'),
+    };
+}
+/**
+ * Register a guess on `Core-guessAdapterForLocation`. Return an adapter config
+ * to claim the file, or `undefined` to defer to the plugins registered before
+ * this one.
+ *
+ * Prefer this over calling `addToExtensionPoint` directly: the chaining is done
+ * once here, so a plugin cannot break the chain by forgetting to delegate, nor
+ * drop an argument on the way through.
+ */
+export function addAdapterGuesser(pluginManager, guess) {
+    pluginManager.addToExtensionPoint('Core-guessAdapterForLocation', next => (file, index, adapterHint) => guess(file, index, adapterHint) ?? next(file, index, adapterHint));
+}
+/**
+ * Register a guess on `Core-guessTrackTypeForLocation`. Return a track type
+ * name to claim the adapter, or `undefined` to defer. See `addAdapterGuesser`
+ * for why this wrapper exists — hand-written delegates here used to drop the
+ * optional `file`, which hid it from every guesser registered earlier in the
+ * chain.
+ */
+export function addTrackTypeGuesser(pluginManager, guess) {
+    pluginManager.addToExtensionPoint('Core-guessTrackTypeForLocation', next => (adapterName, file) => guess(adapterName, file) ?? next(adapterName, file));
+}
+const COMPRESSION_SUFFIXES = ['.gz', '.bgz', '.bz2', '.zst'];
+/**
+ * Drop the format extension from a filename, plus any compression suffix, so
+ * `volvox.vcf.gz` becomes `volvox` rather than `volvox.vcf`. Names with no
+ * extension, and dotfiles, are returned unchanged.
+ */
+export function stripFileExtension(name) {
+    const lower = name.toLowerCase();
+    const base = COMPRESSION_SUFFIXES.some(suffix => lower.endsWith(suffix))
+        ? name.slice(0, name.lastIndexOf('.'))
+        : name;
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
 }
 export function guessAdapter(file, index, adapterHint, model) {
     if (model) {
         const { pluginManager } = getEnv(model);
-        const adapterGuesser = pluginManager.evaluateExtensionPoint('Core-guessAdapterForLocation', (_file, _index, _adapterHint) => {
-            return undefined;
-        });
+        const adapterGuesser = pluginManager.evaluateExtensionPoint(
+        /** #extensionPoint Core-guessAdapterForLocation | sync | Guess an adapter config from a file location */
+        'Core-guessAdapterForLocation', () => undefined);
         const adapter = adapterGuesser(file, index, adapterHint);
         if (adapter) {
             return adapter;
@@ -234,10 +378,14 @@ 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('Core-guessTrackTypeForLocation', (_adapterName) => {
-            return undefined;
-        });
+        // 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);
         if (trackType) {
             return trackType;
@@ -245,102 +393,462 @@ export function guessTrackType(adapterType, model, file) {
     }
     return 'FeatureTrack';
 }
-export function generateUnsupportedTrackConf(trackName, trackUrl, categories) {
-    const conf = {
-        type: 'FeatureTrack',
-        name: `${trackName} (Unsupported)`,
-        description: `Support not yet implemented for "${trackUrl}"`,
-        category: categories,
-        trackId: '',
+/**
+ * Expand a loose track description — a bare data-file URI, or an object with
+ * `uri` (and optional `index`) plus any extra config keys — into a full track
+ * config, the same inference the "Add track" flow does: the adapter and track
+ * type are guessed from the file via the format plugins, a stable `trackId` and
+ * a `name` are derived from the filename, and the assembly is stamped on. Extra
+ * keys on the input (`name`, `category`, `displays`, ...) override the inferred
+ * defaults. Takes a `pluginManager` (not a model) so it runs headlessly — in a
+ * worker/Node export as well as the browser. Throws when no format matches, so
+ * 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;
+    return {
+        ...guessTrackConfForLocation({ uri, locationType: 'UriLocation' }, index ? { uri: index, locationType: 'UriLocation' } : undefined, pluginManager, assemblyName),
+        ...extra,
     };
-    conf.trackId = objectHash(conf);
-    return conf;
 }
-export function generateUnknownTrackConf(trackName, trackUrl, categories) {
+/**
+ * {@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, index, undefined);
+    const name = getFileName(file);
+    if (!adapter || adapter.type === UNKNOWN) {
+        throw new Error(`could not infer a track type from "${name}"; pass a full track config instead`);
+    }
+    const trackTypeGuesser = pluginManager.evaluateExtensionPoint('Core-guessTrackTypeForLocation', () => undefined);
+    return {
+        trackId: `${name}-${objectHash(adapter).slice(0, 8)}`,
+        type: trackTypeGuesser(adapter.type, file) ?? 'FeatureTrack',
+        name,
+        assemblyNames: assemblyName ? [assemblyName] : [],
+        adapter,
+    };
+}
+/**
+ * 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:
+ * the track config union, the root config's frozen `tracks`, `addTrackConf`,
+ * and `showTrackGeneric`'s inline config.
+ *
+ * `{ "trackId": "reads", "uri": "reads.bam", "assemblyNames": ["hg38"] }` is a
+ * whole track: the adapter and track type come from the file's extension
+ * through the format plugins' guessers, the same inference the "Add track"
+ * flow runs, and `name` defaults to the file name. Any key written beside
+ * `uri` — `trackId`, `name`, `category`, `displayDefaults`, an explicit `type`
+ * — overrides what was inferred. `assemblyName` fills `assemblyNames` when the
+ * snapshot has none, for a config or embed that has exactly one assembly.
+ */
+export function expandLooseTrackConfig(snap, pluginManager, assemblyName) {
+    return isLooseTrackConfig(snap)
+        ? guessTrackConf(snap, pluginManager, assemblyName)
+        : snap;
+}
+function generateProblemTrackConf(trackName, categories, label, description) {
     const conf = {
         type: 'FeatureTrack',
-        name: `${trackName} (Unknown)`,
-        description: `Could not determine track type for "${trackUrl}"`,
+        name: `${trackName} (${label})`,
+        description,
         category: categories,
         trackId: '',
     };
     conf.trackId = objectHash(conf);
     return conf;
 }
+export function generateUnsupportedTrackConf(trackName, trackUrl, categories) {
+    return generateProblemTrackConf(trackName, categories, 'Unsupported', `Support not yet implemented for "${trackUrl}"`);
+}
+export function generateUnknownTrackConf(trackName, trackUrl, categories) {
+    return generateProblemTrackConf(trackName, categories, 'Unknown', `Could not determine track type for "${trackUrl}"`);
+}
 export function getTrackName(conf, session) {
-    const trackName = isStateTreeNode(conf)
+    const isMst = isStateTreeNode(conf);
+    const trackName = isMst
         ? readConfObject(conf, 'name')
         : (conf.name ?? '');
-    const trackType = isStateTreeNode(conf)
-        ? readConfObject(conf, 'type')
-        : conf.type;
+    const trackType = isMst ? readConfObject(conf, 'type') : conf.type;
     if (!trackName && trackType === 'ReferenceSequenceTrack') {
         const asm = session.assemblies.find(a => a.sequence === conf);
         return asm
             ? `Reference sequence (${readConfObject(asm, 'displayName') || readConfObject(asm, 'name')})`
             : 'Reference sequence';
     }
-    return trackName;
+    const trackId = isMst
+        ? readConfObject(conf, 'trackId')
+        : (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 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
+ * rebuilt per track.
+ */
+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.
+ *
+ * Two answers that are easy to get wrong, and both have been:
+ *
+ * - A type **no plugin registered** answers false rather than throwing.
+ *   `getTrackType` throws on an unknown name, and a frozen track config never
+ *   passes the schema that would have rejected it at load — so a config naming
+ *   a plugin that failed to load put that throw inside whatever loop was
+ *   filtering tracks, and one unopenable track took out the entire list. The
+ *   track selector and jb2export's circular-view filter met this separately.
+ * - A view type registering **no displays at all** constrains nothing, so
+ *   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)) {
+        return false;
+    }
+    return (viewDisplays.size === 0 ||
+        pluginManager
+            .getTrackType(trackType)
+            .displayTypes.some(d => viewDisplays.has(d.name)));
+}
+export function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, }) {
+    const supported = new Set(viewDisplayTypes);
+    const type = requestedType ??
+        declaredDisplays.find(d => supported.has(d.type))?.type ??
+        trackDisplayTypes.find(name => supported.has(name));
+    return type === undefined
+        ? undefined
+        : { type, conf: declaredDisplays.find(d => d.type === type) };
+}
+// #endregion
+// Resolve a session-spec `TrackInit` into the (trackId, trackSnapshot,
+// displaySnapshot) triple that `showTrackGeneric` expects. Display props written
+// inline on the track object (everything except trackId/trackSnapshot/
+// displaySnapshot) fold into the display snapshot, so a spec can write
+// `{ trackId, showDescriptions: false }` instead of nesting under
+// `displaySnapshot`. An explicit `displaySnapshot` still wins over an inline
+// key of the same name, and the older nested form keeps working unchanged.
+// `showTrackGeneric` then routes any inline key that is a real config slot (e.g.
+// `forceLoad`) onto the display config, so a session spec can declaratively
+// force-load a track with `{ trackId, forceLoad: true }`.
+export function normalizeTrackInit(t) {
+    if (typeof t === 'string') {
+        return { trackId: t, trackSnapshot: {}, displaySnapshot: {} };
+    }
+    else {
+        const { trackId, trackSnapshot, displaySnapshot, ...rest } = t;
+        return {
+            trackId,
+            trackSnapshot: trackSnapshot ?? {},
+            displaySnapshot: { ...rest, ...displaySnapshot },
+        };
+    }
 }
-export function showTrackGeneric(self, trackId, initialSnapshot = {}, displayInitialSnapshot = {}) {
+function resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf) {
     const { pluginManager } = getEnv(self);
     const session = getSession(self);
-    const found = self.tracks.find(t => t.configuration.trackId === trackId);
-    if (found) {
-        return found;
-    }
-    const rawConf = session.getTracksById()[trackId];
+    // `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 = isStateTreeNode(rawConf)
-        ? getSnapshot(rawConf)
-        : structuredClone(rawConf);
+    const confSnapshot = structuredClone(isStateTreeNode(rawConf) ? getSnapshot(rawConf) : rawConf);
     const conf = pluginManager.evaluateExtensionPoint('Core-preProcessTrackConfig', confSnapshot);
     const trackType = pluginManager.getTrackType(conf.type);
-    if (!trackType) {
-        throw new Error(`Unknown track type ${conf.type}`);
-    }
-    const viewType = pluginManager.getViewType(self.type);
-    const supportedDisplays = new Set(viewType.displayTypes.map(d => d.name));
-    const displays = conf.displays ?? [];
-    const displayConf = displays.find((d) => supportedDisplays.has(d.type));
-    const snapshotType = displayInitialSnapshot.type;
-    const defaultDisplayType = displayConf?.type ??
-        trackType.displayTypes.find(d => supportedDisplays.has(d.name))?.name;
-    const displayType = snapshotType ?? defaultDisplayType;
-    if (!displayType) {
-        throw new Error(`Could not find a compatible display for view type ${self.type}`);
-    }
-    const displayId = displayConf?.displayId ?? `${trackId}-${displayType}`;
-    const { type: _type, displayId: _displayId, ...displayConfState } = displayConf ?? {};
-    const track = trackType.stateModel.create({
-        ...initialSnapshot,
-        type: conf.type,
-        configuration: trackId,
-        displays: [
-            {
-                type: displayType,
-                configuration: displayId,
-                ...displayConfState,
-                ...displayInitialSnapshot,
-            },
-        ],
+    // 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),
     });
-    self.tracks.push(track);
-    return track;
+    if (!picked) {
+        throw new Error(`Could not find a compatible display for view type ${view.type}`);
+    }
+    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
+// level index typechecked its way into a track snapshot — see the dotplot and
+// comparative views' own `showTrack`, whose second parameter is this one.
+//
+// `object` and not `Record<string, unknown>`: the hazard is a primitive, and
+// an index signature additionally rejects the precise snapshot interfaces
+// callers legitimately pass (jbrowse-img's `DisplaySnapshot` is one).
+initialSnapshot = {}, displayInitialSnapshot = {}, 
+// The config itself, for a track no session list holds: a view that
+// synthesizes a track only it can draw passes the config here and it lives on
+// the track node, so closing the track takes the config with it. Without it
+// such a config has to be parked in a session list that outlives the view.
+inlineConf) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    const found = self.tracks.find(t => t.configuration.trackId === trackId);
+    if (found) {
+        return found;
+    }
+    // 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, 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,
+            // `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,
+                },
+            ],
+        });
+        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. 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.
+        //
+        // `type` is dropped first because this function already consumed it
+        // (pickDisplayForView above), and only `failed` — a key whose write threw —
+        // is notified: `unapplied` here also holds the MST display props the
+        // snapshot spread above already applied, so notifying on it would report a
+        // correct call as broken. A throwing slot value used to reach the outer
+        // catch and raise a snackbar; per-key catching kept the track intact but
+        // took the message away with it.
+        const displaySettings = Object.fromEntries(Object.entries(displayInitialSnapshot).filter(([key]) => key !== 'type'));
+        const report = track.applyDisplaySettings(displaySettings);
+        if (report.failed.length) {
+            session.notifyError(`Track "${trackId}" rejected ${report.failed
+                .map(f => `${f.key}: ${f.error}`)
+                .join('; ')}`);
+        }
+        // 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);
+        return track;
+    }
+    catch (e) {
+        session.notifyError(`${e}`, e);
+        return undefined;
+    }
+}
+// Strip a track's identifier and its nested display identifiers (both are
+// types.identifier) so a duplicated/copied snapshot doesn't collide with the
+// source's ids when added back into the same session tree.
+export function stripTrackIds(tracks) {
+    return tracks.map(({ id, displays, ...rest }) => ({
+        ...rest,
+        displays: displays.map(({ id, ...d }) => d),
+    }));
 }
 export function hideTrackGeneric(self, trackId) {
     const t = self.tracks.find(t => t.configuration.trackId === trackId);
     if (t) {
         self.tracks.remove(t);
-        return 1;
+        // drop the persisted connection-track config if no other view holds it
+        // (persisted → guards saved-session size; the volatile working-copy cache
+        // in SessionTracks is deliberately not pruned, see editableTrackConfigs)
+        getSession(self).pruneConnectionTrackConfig?.(trackId);
+        return true;
     }
-    return 0;
+    return false;
 }
+// Returns true if the track is now shown, false if it was hidden or failed to
+// open (callers use this to e.g. record only newly-opened tracks as recent).
 export function toggleTrackGeneric(self, trackId) {
-    const hiddenCount = hideTrackGeneric(self, trackId);
-    if (!hiddenCount) {
-        showTrackGeneric(self, trackId);
+    return hideTrackGeneric(self, trackId)
+        ? false
+        : !!showTrackGeneric(self, trackId);
+}
+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) {
+        return found;
+    }
+    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.
+ *
+ * `session.tracks` is only sessionTracks plus the admin config (see
+ * product-core's SessionTracks), so a track that arrived from a hub or registry
+ * connection is absent from it while still being toggleable from the track
+ * selector, which unions the same two sources. Anything answering "what tracks
+ * exist for X" wants this, or a feature silently can't see connection tracks.
+ *
+ * Note `session.tracks` already contains `sessionTracks` — unioning those two
+ * yields every session track twice.
+ */
+export function allSessionTracks(session) {
+    const connectionTracks = (session.connectionInstances ?? []).flatMap(conn => conn.tracks);
+    return connectionTracks.length
+        ? [...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`;
+}