@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/assemblyManager/geneticCodes.js

@@ -0,0 +1,44 @@
+import { fetchAndMaybeUnzipText } from '../util/fetchAndMaybeUnzip.js';
+import { parseTranslTable } from '../util/geneticCodes.js';
+import { openLocation } from '../util/io/index.js';
+/** NCBI's standard genetic code, used by any refName without a mapping */
+const STANDARD_GENETIC_CODE_ID = 1;
+/**
+ * NCBI genetic-code (translation table) id for `refName`, taken from the first
+ * of `maps` holding an entry for it, else the standard code (1).
+ *
+ * A map key and `refName` may each independently be a canonical name or an
+ * alias of one: a config generated from NCBI keys by the GFF's RefSeq accession
+ * while the assembly's canonical name is the UCSC-style one, and callers that
+ * pass a feature's own refName rather than the canonical one. Both sides are
+ * resolved through `refNameAliases` (loaded from the chromAlias file) so they
+ * meet. The maps are per-assembly contig lists, so scanning them is cheap.
+ */
+export function lookupGeneticCodeId(refName, refNameAliases, maps) {
+    const canonicalize = (name) => refNameAliases?.[name] ?? name;
+    const target = canonicalize(refName);
+    return (maps
+        .map(map => map[refName] ??
+        Object.entries(map).find(([k]) => canonicalize(k) === target)?.[1])
+        .find(id => id !== undefined) ?? STANDARD_GENETIC_CODE_ID);
+}
+// Loads an optional `refName<TAB>geneticCodeId` TSV (# comments allowed) into a
+// map; no location yields {} so the inline geneticCodes slot is the only
+// source. Kept as a plain file read rather than a pluggable adapter because the
+// mapping is trivial and format-fixed.
+export async function getGeneticCodesFromFile({ location, pluginManager, opts, }) {
+    const map = {};
+    if (location) {
+        const text = await fetchAndMaybeUnzipText(openLocation(location, pluginManager), opts, 'Downloading genetic codes');
+        for (const line of text.split(/\r\n|\r|\n/)) {
+            if (line && !line.startsWith('#')) {
+                const [refName, codeColumn] = line.split('\t');
+                const id = parseTranslTable(codeColumn);
+                if (refName && id !== undefined) {
+                    map[refName] = id;
+                }
+            }
+        }
+    }
+    return map;
+}

package/esm/assemblyManager/getSequenceAdapterConfig.d.ts

@@ -0,0 +1,19 @@
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+import type { Assembly } from './assembly.ts';
+/**
+ * The assembly's reference-sequence adapter config as a plain snapshot, or
+ * undefined if the assembly (or its config) isn't available. Snapshotted
+ * because MST nodes can't be assigned into another tree or sent over RPC.
+ * configuration is a safeReference, so it's either a live node (getSnapshot is
+ * safe) or undefined (?. handles it).
+ */
+export declare function getSequenceAdapterConfig(assembly?: Pick<Assembly, 'configuration'>): Record<string, unknown> | undefined;
+/**
+ * {@link getSequenceAdapterConfig} for a name, canonical or alias, read off
+ * the config rather than the built model, so it answers before the model
+ * exists and does not report an unknown name the way `assemblyManager.get`
+ * does; a track config may name an assembly the session lacks.
+ */
+export declare function getSequenceAdapterConfigByName(assemblyManager: {
+    confByName: Map<string, AnyConfigurationModel>;
+}, assemblyName: string): Record<string, unknown> | undefined;

package/esm/assemblyManager/getSequenceAdapterConfig.js

@@ -0,0 +1,22 @@
+import { getSnapshot } from '@jbrowse/mobx-state-tree';
+/**
+ * The assembly's reference-sequence adapter config as a plain snapshot, or
+ * undefined if the assembly (or its config) isn't available. Snapshotted
+ * because MST nodes can't be assigned into another tree or sent over RPC.
+ * configuration is a safeReference, so it's either a live node (getSnapshot is
+ * safe) or undefined (?. handles it).
+ */
+export function getSequenceAdapterConfig(assembly) {
+    const adapter = assembly?.configuration?.sequence?.adapter;
+    return adapter ? getSnapshot(adapter) : undefined;
+}
+/**
+ * {@link getSequenceAdapterConfig} for a name, canonical or alias, read off
+ * the config rather than the built model, so it answers before the model
+ * exists and does not report an unknown name the way `assemblyManager.get`
+ * does; a track config may name an assembly the session lacks.
+ */
+export function getSequenceAdapterConfigByName(assemblyManager, assemblyName) {
+    const adapter = assemblyManager.confByName.get(assemblyName)?.sequence?.adapter;
+    return adapter ? getSnapshot(adapter) : undefined;
+}

package/esm/assemblyManager/index.d.ts

@@ -1,4 +1,4 @@
 export { default } from './assemblyManager.ts';
 export type { AssemblyBaseOpts } from './assemblyManager.ts';
 export { default as assemblyConfigSchemaFactory } from './assemblyConfigSchema.ts';
-export type { BaseAssemblyConfigSchema } from './assemblyConfigSchema.ts';
+export type { BaseAssemblyConfigModel, BaseAssemblyConfigSchema, } from './assemblyConfigSchema.ts';

package/esm/assemblyManager/index.js

@@ -1,2 +1,2 @@
-export { default } from "./assemblyManager.js";
-export { default as assemblyConfigSchemaFactory } from "./assemblyConfigSchema.js";
+export { default } from './assemblyManager.js';
+export { default as assemblyConfigSchemaFactory } from './assemblyConfigSchema.js';

package/esm/assemblyManager/indexAssemblyNames.d.ts

@@ -0,0 +1,9 @@
+/**
+ * name -> item for every name an assembly answers to. An assembly's own name
+ * beats another assembly's alias, and otherwise the first to claim a name keeps
+ * it, so the answer never depends on which array an assembly sits in.
+ */
+export declare function indexAssemblyNames<T>(items: Iterable<T>, namesOf: (item: T) => {
+    name: string;
+    aliases: readonly string[];
+}): Map<string, T>;

package/esm/assemblyManager/indexAssemblyNames.js

@@ -0,0 +1,22 @@
+/**
+ * name -> item for every name an assembly answers to. An assembly's own name
+ * beats another assembly's alias, and otherwise the first to claim a name keeps
+ * it, so the answer never depends on which array an assembly sits in.
+ */
+export function indexAssemblyNames(items, namesOf) {
+    const index = new Map();
+    const named = Array.from(items, item => ({ item, ...namesOf(item) }));
+    for (const { item, name } of named) {
+        if (!index.has(name)) {
+            index.set(name, item);
+        }
+    }
+    for (const { item, aliases } of named) {
+        for (const alias of aliases) {
+            if (!index.has(alias)) {
+                index.set(alias, item);
+            }
+        }
+    }
+    return index;
+}

package/esm/assemblyManager/loadRefNameMap.d.ts

@@ -0,0 +1,5 @@
+import type { BaseOptions } from '../data_adapters/BaseAdapter/index.ts';
+import type { Assembly } from './assembly.ts';
+import type { RefNameAliases } from './refNameMaps.ts';
+export type RefNameMapAssembly = Pick<Assembly, 'name' | 'load' | 'error' | 'regions' | 'refNames' | 'refNameAliases' | 'rpcManager' | 'getCanonicalRefName' | 'setRefNameMismatch'>;
+export declare function loadRefNameMap(assembly: RefNameMapAssembly, adapterConfig: unknown, options: BaseOptions): Promise<RefNameAliases>;

package/esm/assemblyManager/loadRefNameMap.js

@@ -0,0 +1,75 @@
+import { adapterConfigCacheKey } from '../data_adapters/dataAdapterCache.js';
+import { updateStatus } from '../util/progress.js';
+import { checkRefName } from './refNameMaps.js';
+import { detectRefNameMismatch } from './refNameMismatch.js';
+export async function loadRefNameMap(assembly, adapterConfig, options) {
+    const { sessionId } = options;
+    if (!sessionId) {
+        throw new Error('sessionId is required for loadRefNameMap');
+    }
+    // load() is idempotent and resolves only after regions + refNameAliases are
+    // set, so awaiting it is a direct, promise-based alternative to a reactive
+    // `when` on those volatiles. It rejects on failure, so no error check follows
+    await assembly.load();
+    // Labelled, because this is the multi-second stall before any RPC's own
+    // status appears: `renameRegionsIfNeeded` runs inside `serializeArguments`,
+    // so every fetch waits here first, and the byte-granularity progress below
+    // arrives with no phase name on it. Without the label a whole-file in-memory
+    // load reads as a bare percentage climbing under no heading. The wording is
+    // deliberately generic: refname resolution is an implementation detail a
+    // user has no use for, and this is just the front of the load to them.
+    const refNames = await updateStatus('Loading', options.statusCallback, () => assembly.rpcManager.call(sessionId, 'CoreGetRefNames', {
+        adapterConfig: adapterConfig,
+        assemblyName: assembly.name,
+        haplotypes: options.haplotypes,
+        // signal intentionally not passed, fixes issues like #2221.
+        // alternative fix #2540 was proposed but non-working currently
+        signal: undefined,
+        // Forwarded rather than dropped (unlike signal above), because the
+        // adapter's index download happens here during refname mapping
+        // (getRefNames -> setup) and this is the only place its "Downloading
+        // index" progress can surface. For an in-memory adapter it is not an
+        // index but the whole file — GWAS LD coloring resolves a second map
+        // against its PLINK `.ld` sub-adapter, and that adapter parses all of it
+        // to answer `getRefNames`.
+        //
+        // This was latent for a while, and what revived it is one line elsewhere
+        // that is easy to undo by tidying: `BaseRpcDriver.call` strips
+        // `statusCallback` off the *result* of `serializeArguments` rather than
+        // off the args going in. Strip it going in and the rename pass — which
+        // runs inside serialization — is handed undefined for every RPC there is,
+        // which is what it was.
+        statusCallback: options.statusCallback,
+    }));
+    const { refNameAliases } = assembly;
+    if (!refNameAliases) {
+        throw new Error(`error loading assembly ${assembly.name}'s refNameAliases`);
+    }
+    const result = {};
+    for (const name of refNames) {
+        checkRefName(name);
+        // `?? name` keeps a name the assembly does not know, so the map is total.
+        // For ONE unknown name that is right — the region it would have renamed
+        // simply never comes up. For ALL of them it is an identity map that matches
+        // no region, and the track then draws nothing and says nothing, which is
+        // what the check below is for.
+        result[assembly.getCanonicalRefName(name) ?? name] = name;
+    }
+    // This function is the only place both name sets are in scope at once, so it
+    // is the only place the disagreement is visible. Recorded rather than thrown:
+    // a track whose file genuinely has no features in view looks identical from
+    // here, and failing on a guess would take a working track away from someone.
+    // The record is keyed by adapter cache key and the map load is memoized under
+    // the same key, so this runs once per (assembly, adapter config) — a track
+    // reads it back through `BaseTrackModel.refNameMismatch`.
+    const mismatch = detectRefNameMismatch({
+        assemblyName: assembly.name,
+        adapterRefNames: refNames,
+        assemblyRefNames: assembly.refNames ?? [],
+        getCanonicalRefName: name => assembly.getCanonicalRefName(name),
+    });
+    if (mismatch) {
+        assembly.setRefNameMismatch(adapterConfigCacheKey(adapterConfig), mismatch);
+    }
+    return result;
+}

package/esm/assemblyManager/refNameColors.d.ts

@@ -0,0 +1 @@
+export declare const defaultRefNameColors: string[];

package/esm/assemblyManager/refNameColors.js

@@ -0,0 +1,32 @@
+// Based on the UCSC Genome Browser chromosome color palette:
+// https://github.com/ucscGenomeBrowser/kent/blob/a50ed53aff81d6fb3e34e6913ce18578292bc24e/src/hg/inc/chromColors.h
+// Some colors darkened to have at least a 3:1 contrast ratio on a white
+// background
+export const defaultRefNameColors = [
+    'rgb(153, 102, 0)',
+    'rgb(102, 102, 0)',
+    'rgb(153, 153, 30)',
+    'rgb(204, 0, 0)',
+    'rgb(255, 0, 0)',
+    'rgb(255, 0, 204)',
+    'rgb(165, 132, 132)', // originally 'rgb(255, 204, 204)'
+    'rgb(204, 122, 0)', // originally rgb(255, 153, 0)'
+    'rgb(178, 142, 0)', // originally 'rgb(255, 204, 0)'
+    'rgb(153, 153, 0)', // originally 'rgb(255, 255, 0)'
+    'rgb(122, 153, 0)', // originally 'rgb(204, 255, 0)'
+    'rgb(0, 165, 0)', // originally 'rgb(0, 255, 0)'
+    'rgb(53, 128, 0)',
+    'rgb(0, 0, 204)',
+    'rgb(96, 145, 242)', // originally 'rgb(102, 153, 255)'
+    'rgb(107, 142, 178)', // originally 'rgb(153, 204, 255)'
+    'rgb(0, 165, 165)', // originally 'rgb(0, 255, 255)'
+    'rgb(122, 153, 153)', // originally 'rgb(204, 255, 255)'
+    'rgb(153, 0, 204)',
+    'rgb(204, 51, 255)',
+    'rgb(173, 130, 216)', // originally 'rgb(204, 153, 255)'
+    'rgb(102, 102, 102)',
+    'rgb(145, 145, 145)', // originally 'rgb(153, 153, 153)'
+    'rgb(142, 142, 142)', // originally 'rgb(204, 204, 204)'
+    'rgb(142, 142, 107)', // originally 'rgb(204, 204, 153)'
+    'rgb(96, 163, 48)', // originally 'rgb(121, 204, 61)'
+];

package/esm/assemblyManager/refNameMapKey.d.ts

@@ -0,0 +1,7 @@
+import type { BaseOptions } from '../data_adapters/BaseAdapter/index.ts';
+/**
+ * A source that reads only the lanes it is asked about answers a different
+ * refName set per selection, so each selection loads its own map; the worker
+ * keeps each lane's names, so a second selection reads only its new lanes.
+ */
+export declare function refNameMapKey(adapterConf: Record<string, unknown>, options: BaseOptions): string;

package/esm/assemblyManager/refNameMapKey.js

@@ -0,0 +1,12 @@
+import { adapterConfigCacheKey } from '../data_adapters/dataAdapterCache.js';
+/**
+ * A source that reads only the lanes it is asked about answers a different
+ * refName set per selection, so each selection loads its own map; the worker
+ * keeps each lane's names, so a second selection reads only its new lanes.
+ */
+export function refNameMapKey(adapterConf, options) {
+    const key = adapterConfigCacheKey(adapterConf);
+    return options.haplotypes === undefined
+        ? key
+        : `${key}|${[...options.haplotypes].sort().join(',')}`;
+}

package/esm/assemblyManager/refNameMaps.d.ts

@@ -0,0 +1,26 @@
+import type { Alias } from '../data_adapters/BaseAdapter/index.ts';
+export type RefNameAliases = Record<string, string>;
+export declare function checkRefName(refName: string): void;
+export interface RefNameMaps {
+    refNameAliases: RefNameAliases;
+    lowerCaseRefNameAliases: RefNameAliases;
+    canonicalToSeqAdapterRefNames: Record<string, string>;
+}
+export declare function buildRefNameMaps(regions: {
+    refName: string;
+}[], refNameAliasCollection: Alias[]): RefNameMaps;
+/**
+ * Inverts an alias map into canonical refName -> every name for that sequence,
+ * the canonical name first and its aliases after it.
+ *
+ * The aliases come back in the alias map's own key order, which is JS object
+ * key order: an integer-like name (Ensembl's `1`, `2`, `10`) sorts ahead of the
+ * rest, ascending, whatever order the adapter emitted it in. The others keep
+ * insertion order, which for a UCSC chromAlias is the file's column order
+ * (ucsc, assembly, genbank, refseq).
+ *
+ * Feed it `refNameAliases`, never `lowerCaseRefNameAliases` — the latter is a
+ * second index of the same names, and grouping it produces a case-variant twin
+ * of every alias.
+ */
+export declare function groupNamesByCanonicalRefName(refNameAliases: RefNameAliases): Map<string, string[]>;

package/esm/assemblyManager/refNameMaps.js

@@ -0,0 +1,87 @@
+// The SAM spec's reference-name grammar, verbatim: printable ASCII apart from
+// backslash, comma, quotes, brackets and braces, not starting with `*` or `=`
+// (SAMv1 §1.2.1, https://samtools.github.io/hts-specs/SAMv1.pdf).
+//
+// Anchored, because the spec says names *match* this expression -- it is the
+// grammar for a whole name, not something to search for inside one. Unanchored,
+// `test` asked only whether a name contained one legal character anywhere, so it
+// passed `chr 1`, ` chr1` and `x[bad]` and rejected only names made entirely of
+// illegal characters. Note what that let through: a refName with whitespace in
+// it, which is what an unindexed FASTA yields when its defline separates the id
+// from the description with a tab rather than a space, and which then breaks
+// every locstring and url that carries it.
+//
+// Anchoring rejects nothing real: measured against the chrom.sizes and
+// chromAlias files of 25 UCSC/GenArk genomes (hg38, hs1, mm39, dm6, sacCer3,
+// and a random sample of the rest), all 4,935,269 names pass.
+/* biome-ignore lint/complexity/useRegexLiterals: keeps the character classes 1:1 with the spec, no `/` escaping */
+const refNameRegex = new RegExp('^[0-9A-Za-z!#$%&+./:;?@^_|~-][0-9A-Za-z!#$%&*+./:;=?@^_|~-]*$');
+export function checkRefName(refName) {
+    if (!refNameRegex.test(refName)) {
+        throw new Error(`Encountered invalid refName: "${refName}". Reference names may not be empty, may not start with * or =, and may not contain whitespace, backslashes, commas, quotes, brackets or braces`);
+    }
+}
+// Build the alias/name lookups used throughout the model from the sequence
+// adapter's regions plus the optional refNameAliasAdapter collection.
+export function buildRefNameMaps(regions, refNameAliasCollection) {
+    const fastaRefNames = new Set(regions.map(r => r.refName));
+    const refNameAliases = {};
+    for (const { refName, aliases, override } of refNameAliasCollection) {
+        // override:true (the default), or unset as with chromAlias files whose
+        // refName column already matches the FASTA, makes the adapter's refName the
+        // canonical name. override:false instead keeps the sequence adapter's own
+        // name canonical, resolving it from whichever alias matches a FASTA contig.
+        const canonical = override === false
+            ? (aliases.find(a => fastaRefNames.has(a)) ?? refName)
+            : refName;
+        for (const alias of aliases) {
+            checkRefName(alias);
+            refNameAliases[alias] = canonical;
+        }
+        refNameAliases[canonical] = canonical;
+    }
+    // identity-map each region's refName (??= so an override alias wins) and
+    // record where the canonical name differs from the sequence adapter's name
+    const canonicalToSeqAdapterRefNames = {};
+    for (const { refName } of regions) {
+        const canonical = (refNameAliases[refName] ??= refName);
+        if (canonical !== refName) {
+            canonicalToSeqAdapterRefNames[canonical] = refName;
+        }
+    }
+    // a lowercase index, so getCanonicalRefName can resolve a lower-case query
+    const lowerCaseRefNameAliases = {};
+    for (const [key, canonical] of Object.entries(refNameAliases)) {
+        lowerCaseRefNameAliases[key.toLowerCase()] = canonical;
+    }
+    return {
+        refNameAliases,
+        lowerCaseRefNameAliases,
+        canonicalToSeqAdapterRefNames,
+    };
+}
+/**
+ * Inverts an alias map into canonical refName -> every name for that sequence,
+ * the canonical name first and its aliases after it.
+ *
+ * The aliases come back in the alias map's own key order, which is JS object
+ * key order: an integer-like name (Ensembl's `1`, `2`, `10`) sorts ahead of the
+ * rest, ascending, whatever order the adapter emitted it in. The others keep
+ * insertion order, which for a UCSC chromAlias is the file's column order
+ * (ucsc, assembly, genbank, refseq).
+ *
+ * Feed it `refNameAliases`, never `lowerCaseRefNameAliases` — the latter is a
+ * second index of the same names, and grouping it produces a case-variant twin
+ * of every alias.
+ */
+export function groupNamesByCanonicalRefName(refNameAliases) {
+    const groups = new Map();
+    for (const [name, canonical] of Object.entries(refNameAliases)) {
+        const group = groups.get(canonical) ?? [canonical];
+        if (name !== canonical) {
+            group.push(name);
+        }
+        groups.set(canonical, group);
+    }
+    return groups;
+}

package/esm/assemblyManager/refNameMismatch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The one disagreement between a file's reference names and an assembly's that
+ * can be diagnosed from the names alone: they have **nothing** in common.
+ *
+ * Only the empty intersection is a verdict. Partial overlap is ordinary — a
+ * track covering some contigs, a sample-specific VCF, a file that stops at the
+ * primary assembly — so a name the assembly does not know says nothing on its
+ * own, and a per-name warning would fire on most real tracks. `RefNameInfoDialog`
+ * (`@jbrowse/product-core/ui`) is where the partial case belongs: it shows both
+ * lists in full, on demand.
+ *
+ * The comparative case reaches the same conclusion from the other side.
+ * `detectSwappedAssemblies` (`@jbrowse/synteny-core`) is conclusive only when
+ * the two assemblies have distinct contig names, because an overlapping name
+ * resolves on its own axis and tips nothing.
+ */
+/** the first few of a name list, plus how many there were in all */
+export interface RefNameSample {
+    names: string[];
+    total: number;
+}
+export interface RefNameMismatch {
+    assemblyName: string;
+    /** what the file calls its contigs */
+    adapter: RefNameSample;
+    /** what the assembly calls its contigs, canonically */
+    assembly: RefNameSample;
+}
+/**
+ * Both name sets are non-empty and no name from the file resolves to one of the
+ * assembly's — the `1/2/3` file loaded against a `chr1/chr2/chr3` assembly.
+ * Returns undefined for every other case, including either list being empty:
+ * an adapter that reports no refNames at all (many do) is not evidence of
+ * anything.
+ *
+ * Names from the file go through `getCanonicalRefName`, which resolves aliases
+ * and casing together — testing them against the assembly's names directly
+ * would get neither, and would then report a mismatch on exactly the aliased
+ * tracks `refNameAliases` exists to fix.
+ */
+export declare function detectRefNameMismatch({ assemblyName, adapterRefNames, assemblyRefNames, getCanonicalRefName, }: {
+    assemblyName: string;
+    /** the names the adapter reports for its own file (`CoreGetRefNames`) */
+    adapterRefNames: string[];
+    /** the assembly's canonical refNames (`assembly.refNames`) */
+    assemblyRefNames: string[];
+    /** the assembly's one normalization layer, aliases and casing both */
+    getCanonicalRefName: (refName: string) => string | undefined;
+}): RefNameMismatch | undefined;
+/**
+ * What to tell the user, in the voice the CORS and Range hints use: what is
+ * wrong, the evidence, and the two things that fix it.
+ */
+export declare function refNameMismatchMessage({ assemblyName, adapter, assembly, }: RefNameMismatch): string;

package/esm/assemblyManager/refNameMismatch.js

@@ -0,0 +1,66 @@
+/**
+ * The one disagreement between a file's reference names and an assembly's that
+ * can be diagnosed from the names alone: they have **nothing** in common.
+ *
+ * Only the empty intersection is a verdict. Partial overlap is ordinary — a
+ * track covering some contigs, a sample-specific VCF, a file that stops at the
+ * primary assembly — so a name the assembly does not know says nothing on its
+ * own, and a per-name warning would fire on most real tracks. `RefNameInfoDialog`
+ * (`@jbrowse/product-core/ui`) is where the partial case belongs: it shows both
+ * lists in full, on demand.
+ *
+ * The comparative case reaches the same conclusion from the other side.
+ * `detectSwappedAssemblies` (`@jbrowse/synteny-core`) is conclusive only when
+ * the two assemblies have distinct contig names, because an overlapping name
+ * resolves on its own axis and tips nothing.
+ */
+// enough to recognize a naming scheme (`1, 2, 3` against `chr1, chr2, chr3`)
+// without carrying a mammalian assembly's whole contig list around in a
+// volatile
+const SAMPLE_SIZE = 5;
+function sample(names) {
+    return { names: names.slice(0, SAMPLE_SIZE), total: names.length };
+}
+/**
+ * Both name sets are non-empty and no name from the file resolves to one of the
+ * assembly's — the `1/2/3` file loaded against a `chr1/chr2/chr3` assembly.
+ * Returns undefined for every other case, including either list being empty:
+ * an adapter that reports no refNames at all (many do) is not evidence of
+ * anything.
+ *
+ * Names from the file go through `getCanonicalRefName`, which resolves aliases
+ * and casing together — testing them against the assembly's names directly
+ * would get neither, and would then report a mismatch on exactly the aliased
+ * tracks `refNameAliases` exists to fix.
+ */
+export function detectRefNameMismatch({ assemblyName, adapterRefNames, assemblyRefNames, getCanonicalRefName, }) {
+    if (adapterRefNames.length === 0 || assemblyRefNames.length === 0) {
+        return undefined;
+    }
+    const canonical = new Set(assemblyRefNames);
+    for (const name of adapterRefNames) {
+        const resolved = getCanonicalRefName(name);
+        if (resolved !== undefined && canonical.has(resolved)) {
+            return undefined;
+        }
+    }
+    return {
+        assemblyName,
+        adapter: sample(adapterRefNames),
+        assembly: sample(assemblyRefNames),
+    };
+}
+function list({ names, total }) {
+    const rest = total - names.length;
+    return rest > 0 ? `${names.join(', ')} (and ${rest} more)` : names.join(', ');
+}
+/**
+ * What to tell the user, in the voice the CORS and Range hints use: what is
+ * wrong, the evidence, and the two things that fix it.
+ */
+export function refNameMismatchMessage({ assemblyName, adapter, assembly, }) {
+    return (`None of this track's reference sequence names match assembly "${assemblyName}", ` +
+        `so no features can be drawn: the file uses ${list(adapter)}, the assembly uses ${list(assembly)}. ` +
+        'Add a refNameAliases entry to the assembly configuration mapping the two ' +
+        "naming schemes to each other, or rebuild the file with the assembly's names.");
+}

package/esm/checkPlugins.d.ts

@@ -0,0 +1,13 @@
+import type { PluginDefinition } from './pluginDefinitions.ts';
+import type { JBrowsePlugin } from './util/types/index.ts';
+export declare const TRUSTED_PLUGIN_URL_PREFIXES: string[];
+export declare const PLUGIN_STORE_URL = "https://jbrowse.org/plugin-store/v2/plugins.json";
+export declare function fetchPlugins(): Promise<{
+    plugins: JBrowsePlugin[];
+}>;
+/** Drops the cached manifest, so the next read fetches again. For tests. */
+export declare function forgetFetchedPlugins(): void;
+export declare function checkPluginsAgainstStore(pluginsToCheck: PluginDefinition[], storePlugins: {
+    plugins: JBrowsePlugin[];
+}): boolean;
+export declare function checkPlugins(pluginsToCheck: PluginDefinition[]): Promise<boolean>;

package/esm/checkPlugins.js

@@ -0,0 +1,98 @@
+import { isStorePluginDefinition, maybePluginUrl, pluginUrl, } from './pluginDefinitions.js';
+// Whether a set of plugin definitions is safe to load without asking the user.
+// Lives in core rather than a product because every product that can be handed
+// a config by an untrusted party needs the same gate: Web from its address bar,
+// Desktop from a jbrowse:// link. Loading a plugin runs its javascript with the
+// product's full privileges — in Desktop that is Node — so a product must not
+// reach PluginLoader with unvetted definitions.
+export const TRUSTED_PLUGIN_URL_PREFIXES = ['https://jbrowse.org/plugins/'];
+// v2 adds per-version JBrowse compatibility ranges + integrity hashes; the v1
+// plugins.json is still served for older clients. Read only through
+// `fetchPlugins` below — the gate, the ref resolver and every install surface
+// have to be looking at the same manifest, and a second copy of the fetch is
+// how one of them silently ends up on the unhashed v1 list and then rejects a
+// plugin the store just offered.
+export const PLUGIN_STORE_URL = 'https://jbrowse.org/plugin-store/v2/plugins.json';
+// One request per page, shared by every reader.
+//
+// There are four in a boot that needs them — the config's trust gate, the
+// config's store refs, the session's gate, the session's refs — plus one per
+// time the plugin store widget is opened, since `useFetch` holds no data cache.
+// The HTTP cache does not fold them: the manifest is served
+// `cache-control: no-cache, must-revalidate`, so each is at least a
+// revalidation round trip, and concurrent ones do not dedupe at all.
+//
+// Held for the life of the page rather than for a window. A manifest that
+// changes mid-session would only matter to a store listing the user is looking
+// at, and an install from a stale row still resolves against the version the
+// row named.
+let cached;
+export async function fetchPlugins() {
+    // Rethrown to every caller and then forgotten, so a store that was down when
+    // the config loaded is retried when the widget opens.
+    cached ??= (async () => {
+        const response = await fetch(PLUGIN_STORE_URL);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status} ${response.statusText} fetching plugins`);
+        }
+        return response.json();
+    })().catch((error) => {
+        cached = undefined;
+        throw error;
+    });
+    return cached;
+}
+/** Drops the cached manifest, so the next read fetches again. For tests. */
+export function forgetFetchedPlugins() {
+    cached = undefined;
+}
+function isTrustedUrl(url) {
+    return TRUSTED_PLUGIN_URL_PREFIXES.some(prefix => url.startsWith(prefix));
+}
+/**
+ * Whether a definition can run without consulting the store listing or asking
+ * the user.
+ *
+ * A store ref names a store entry, and resolution can only turn it into a
+ * `https://jbrowse.org/plugins/` url — the prefix trusted outright above — so a
+ * ref carrying no url of its own is trusted by construction. There would be
+ * nothing to show a user anyway: the url does not exist until the manifest is
+ * read.
+ *
+ * A ref that ALSO carries a fallback url is judged on that url, not on being a
+ * ref. The fallback is what `resolveStoreRefs` loads when the store cannot
+ * answer, so trusting the ref and ignoring the url would vet one thing and run
+ * another — the same drift `assertSingleKind` and `pluginDescriptionString`
+ * exist to prevent on the loader side.
+ */
+function isTrustedDefinition(def) {
+    const url = maybePluginUrl(def);
+    return url === undefined ? isStorePluginDefinition(def) : isTrustedUrl(url);
+}
+// Every url a store entry can resolve to: the top-level fallback plus each
+// version-pinned build. A config plugin is "in the store" if its url is any of
+// these.
+function storePluginUrls(p) {
+    const top = [p.url, p.umdUrl, p.esmUrl];
+    const versioned = (p.versions ?? []).flatMap(v => [v.url, v.umdUrl, v.esmUrl]);
+    return [...top, ...versioned].filter(url => url !== undefined);
+}
+export function checkPluginsAgainstStore(pluginsToCheck, storePlugins) {
+    if (pluginsToCheck.length === 0) {
+        return true;
+    }
+    const storeUrls = new Set(storePlugins.plugins.flatMap(storePluginUrls));
+    return pluginsToCheck.every(p => isTrustedDefinition(p) || storeUrls.has(pluginUrl(p)));
+}
+export async function checkPlugins(pluginsToCheck) {
+    // Trusted-by-prefix plugins and store refs are accepted without consulting
+    // the store listing, so when every plugin is already trusted (the common
+    // case: an empty list, or jbrowse.org-hosted plugins) skip the network
+    // entirely. This keeps a plugin-store outage — or being offline — from
+    // blocking a config/session load that needed no verification (e.g. restoring
+    // your own local session).
+    if (pluginsToCheck.every(isTrustedDefinition)) {
+        return true;
+    }
+    return checkPluginsAgainstStore(pluginsToCheck, await fetchPlugins());
+}