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

package/esm/data_adapters/BaseAdapter/featureDensity.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A density source's intervals over one region, the payload of the density
+ * tier that stands in for the features a gated fetch refused: features per bin
+ * for a `make-density` sidecar, whatever the bigWig measures otherwise, each
+ * value a level over its span so a zoomed read means the same thing. Absolute
+ * genomic coordinates.
+ */
+export interface FeatureDensity {
+    starts: Uint32Array;
+    ends: Uint32Array;
+    scores: Float32Array;
+}
+/**
+ * The slot a feature adapter spreads to take a density sidecar — a
+ * quantitative sub-adapter (typically a BigWig of feature starts per bin) the
+ * display reads at the view's bp/px in place of features the region-too-large
+ * gate refused. Mirrors MAF's `summaryAdapter`: on the adapter, so the tier
+ * names the file it summarizes.
+ */
+export declare const densityAdapterConfigSchemaFields: {
+    /**
+     * #slot
+     */
+    readonly densityAdapter: {
+        readonly type: 'maybeFrozen';
+        readonly description: 'optional quantitative sub-adapter (e.g. a BigWigAdapter over a features-per-bin bigWig) drawn as a density band where the region is too large to fetch features; leave it unset to disable';
+    };
+};
+/**
+ * Whether the `densityAdapter` slot holds something a sub-adapter can be built
+ * from. Beside the slot because both ends of the tier ask it and they have to
+ * agree: the display, deciding the band stands in, and `getFeatureDensity`,
+ * resolving the sidecar. They disagreed — the display took any object, the
+ * adapter wanted a type — so the shorthand every location slot accepts
+ * (`{ uri }`) turned the band on for a read that answered `undefined`, which
+ * commits nothing, and the phase then waited on bins no read would ever bring.
+ */
+export declare function isSubAdapterConfig(value: unknown): value is Record<string, unknown> & {
+    type: string;
+};

package/esm/data_adapters/BaseAdapter/featureDensity.js

@@ -0,0 +1,31 @@
+/**
+ * The slot a feature adapter spreads to take a density sidecar — a
+ * quantitative sub-adapter (typically a BigWig of feature starts per bin) the
+ * display reads at the view's bp/px in place of features the region-too-large
+ * gate refused. Mirrors MAF's `summaryAdapter`: on the adapter, so the tier
+ * names the file it summarizes.
+ */
+export const densityAdapterConfigSchemaFields = {
+    /**
+     * #slot
+     */
+    densityAdapter: {
+        type: 'maybeFrozen',
+        description: 'optional quantitative sub-adapter (e.g. a BigWigAdapter over a features-per-bin bigWig) drawn as a density band where the region is too large to fetch features; leave it unset to disable',
+    },
+};
+/**
+ * Whether the `densityAdapter` slot holds something a sub-adapter can be built
+ * from. Beside the slot because both ends of the tier ask it and they have to
+ * agree: the display, deciding the band stands in, and `getFeatureDensity`,
+ * resolving the sidecar. They disagreed — the display took any object, the
+ * adapter wanted a type — so the shorthand every location slot accepts
+ * (`{ uri }`) turned the band on for a read that answered `undefined`, which
+ * commits nothing, and the phase then waited on bins no read would ever bring.
+ */
+export function isSubAdapterConfig(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        typeof value.type === 'string');
+}

package/esm/data_adapters/BaseAdapter/index.d.ts

@@ -1,15 +1,35 @@
 import type PluginManager from '../../PluginManager.ts';
-import type { AnyConfigurationModel } from '../../configuration/index.ts';
+import type { AnyConfigurationSchemaType } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.ts';
 import type { AnyDataAdapter } from './util.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
 export { type AnyDataAdapter, isFeatureAdapter, isRefNameAliasAdapter, isRegionsAdapter, isSequenceAdapter, isTextSearchAdapter, } from './util.ts';
-export type { BaseOptions, BaseOptionsWithRegions, BaseTextSearchArgs, SearchType, } from './types.ts';
+export type { BaseOptions, BaseTextSearchArgs, LodTier, SearchType, ZoomRange, } from './types.ts';
 export { BaseAdapter } from './BaseAdapter.ts';
 export { cachedSetup } from '../../util/cachedSetup.ts';
 export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.ts';
+export { type FeatureDensity, densityAdapterConfigSchemaFields, isSubAdapterConfig, } from './featureDensity.ts';
 export { BaseSequenceAdapter } from './BaseSequenceAdapter.ts';
 export type { BaseTextSearchAdapter } from './BaseTextSearchAdapter.ts';
 export type { Alias, BaseRefNameAliasAdapter, } from './BaseRefNameAliasAdapter.ts';
 export type { RegionsAdapter } from './RegionsAdapter.ts';
 export type { CytobandAdapter } from './CytobandAdapter.ts';
-export type AnyAdapter = new (config: AnyConfigurationModel, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager) => AnyDataAdapter;
+/**
+ * The adapter class that goes with SCHEMA — the class whose `config` is that
+ * schema's node. `AdapterType` is generic over the schema so registering the
+ * two together checks that they are the same adapter's; the pairing is
+ * otherwise only a shared `type` string, and nothing reports a class reading
+ * slots its declared schema never had.
+ *
+ * see
+ * https://www.typescriptlang.org/docs/handbook/2/classes.html#abstract-construct-signatures
+ * for why this is the abstract construct signature
+ */
+export type AdapterClassFor<SCHEMA> = new (config: SCHEMA extends AnyConfigurationSchemaType ? Instance<SCHEMA> : any, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager, sequenceAdapterConfig?: Record<string, unknown>) => AnyDataAdapter;
+/**
+ * An adapter class with its schema forgotten, which is what the registry holds
+ * and `dataAdapterCache` constructs: the config node it has in hand came from
+ * the `AdapterType` the same `type` name resolved to, and that lookup is the
+ * only thing tying the two together.
+ */
+export type AnyAdapter = AdapterClassFor<any>;

package/esm/data_adapters/BaseAdapter/index.js

@@ -2,4 +2,5 @@ export { isFeatureAdapter, isRefNameAliasAdapter, isRegionsAdapter, isSequenceAd
 export { BaseAdapter } from './BaseAdapter.js';
 export { cachedSetup } from '../../util/cachedSetup.js';
 export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.js';
+export { densityAdapterConfigSchemaFields, isSubAdapterConfig, } from './featureDensity.js';
 export { BaseSequenceAdapter } from './BaseSequenceAdapter.js';

package/esm/data_adapters/BaseAdapter/rowSources.d.ts

@@ -0,0 +1,37 @@
+import type { BaseOptions } from './types.ts';
+/**
+ * #api
+ * One row an adapter lists: `name` is a value of the listing's field, and
+ * `label` and `color` are what the adapter names and colours that row with.
+ */
+export interface ListedRowSource {
+    name: string;
+    label?: string;
+    color?: string;
+}
+/**
+ * #api
+ * Every row an adapter has, in its own order, whatever the loaded regions hold,
+ * so a row display gives a row with nothing in view its place, label and
+ * colour.
+ */
+export interface RowSourceListing {
+    /** The feature field the listed names are values of: `source` on a multi-BigWig, `alignments` on a MAF, whose per-species record is keyed by them. */
+    field: string;
+    sources: ListedRowSource[];
+    /** A guide tree over the names, as Newick, where the adapter ships one. */
+    tree?: string;
+}
+/**
+ * #api
+ * An adapter that lists its rows without reading a region: a multi-BigWig its
+ * files, a MAF its species.
+ */
+export interface RowSourceLister {
+    listRowSources(opts?: BaseOptions): Promise<RowSourceListing>;
+}
+/**
+ * #api
+ * Whether an adapter implements {@link RowSourceLister}.
+ */
+export declare function listsRowSources(adapter: object): adapter is RowSourceLister;

package/esm/data_adapters/BaseAdapter/rowSources.js

@@ -0,0 +1,7 @@
+/**
+ * #api
+ * Whether an adapter implements {@link RowSourceLister}.
+ */
+export function listsRowSources(adapter) {
+    return (typeof adapter.listRowSources === 'function');
+}

package/esm/data_adapters/BaseAdapter/stats.d.ts

@@ -3,8 +3,40 @@ import type { RectifiedQuantitativeStats } from '../../util/stats.ts';
 import type { AugmentedRegion as Region } from '../../util/types/index.ts';
 import type { BaseOptions } from './types.ts';
 import type { Observable } from 'rxjs';
+/**
+ * What a caller that will *judge* the density knows and the probe does not: how
+ * wide a window has to be before its count can settle that judgement, and when
+ * a count has settled it. Supplying it turns the ladder below from "grow until
+ * the estimate is precise" into "grow until the verdict is decided", which at
+ * whole-genome zoom is one window instead of thirteen.
+ *
+ * The probe stays ignorant of what the budget means — `plugins/canvas`'s
+ * `densityProbeGate` owns both numbers, so the comparison that refuses a region
+ * lives beside the one the banner re-derives rather than in a second copy here.
+ */
+export interface DensityProbeGate {
+    /** First window to sample: the narrowest one whose count can settle it. */
+    initialInterval: number;
+    /** Whether this many admitted features in this many bp decides the verdict. */
+    settled: (admitted: number, sampledBp: number) => boolean;
+}
+/**
+ * The adapter options a probe forwards, plus the two things only its caller
+ * knows. Named rather than trailing positionals: `BaseOptions` has no required
+ * member, so every one of its slots structurally accepts anything, and an
+ * `admit` handed to the `opts` slot typechecks and then never filters.
+ */
+export interface DensityProbeOptions extends BaseOptions {
+    /**
+     * The caller's feature-admission predicate (config filters, type gates, ...).
+     * See the note on the growth/report asymmetry below.
+     */
+    admit?: (feature: Feature) => boolean;
+    /** Stop as soon as the verdict is decided rather than when it is precise. */
+    gate?: DensityProbeGate;
+}
 export declare function aggregateQuantitativeStats(stats: RectifiedQuantitativeStats[]): RectifiedQuantitativeStats;
-export declare function calculateFeatureDensityStats(region: Region, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, opts?: BaseOptions, admit?: (feature: Feature) => boolean): Promise<{
+export declare function calculateFeatureDensityStats(region: Region, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, { admit, gate, ...opts }?: DensityProbeOptions): Promise<{
     featureDensity: number;
 }>;
 export { blankStats } from '../../util/stats.ts';

package/esm/data_adapters/BaseAdapter/stats.js

@@ -19,13 +19,16 @@ export function aggregateQuantitativeStats(stats) {
         ...(meanMaxs.length > 0 ? { scoreMeanMax: max(meanMaxs) } : {}),
     });
 }
-// A sample window of `interval` bp centered ~25% into the region, so the sample
-// avoids the region edges where coverage often tapers. Clamped to the region
-// bounds so it never samples features outside the region being measured (the
-// left edge clamps to the region start, not to the chromosome origin).
-function sampleWindow(region, interval) {
+// Where the probe samples, as a fraction into the region. The primary point
+// avoids the region edges, where coverage often tapers.
+const DENSITY_SAMPLE_POINT = 0.25;
+const DENSITY_CONFIRM_POINT = 0.7;
+// A sample window of `interval` bp centered `at` into the region. Clamped to the
+// region bounds so it never samples features outside the region being measured
+// (the left edge clamps to the region start, not to the chromosome origin).
+function sampleWindow(region, interval, at) {
     const { start, end } = region;
-    const sampleCenter = start * 0.75 + end * 0.25;
+    const sampleCenter = start + (end - start) * at;
     return {
         start: Math.max(start, Math.round(sampleCenter - interval / 2)),
         end: Math.min(end, Math.round(sampleCenter + interval / 2)),
@@ -49,20 +52,56 @@ function sampleWindow(region, interval) {
 // count would make a selective filter double the window over and over until it
 // spanned the whole region — turning the cheap pre-fetch probe into a second
 // full download for exactly the views that need it most.
-export async function calculateFeatureDensityStats(region, getFeatures, opts, admit) {
+export async function calculateFeatureDensityStats(region, getFeatures, { admit, gate, ...opts } = {}) {
     const refLen = region.end - region.start;
     const t0 = performance.now();
-    let interval = DENSITY_SAMPLE_INITIAL_INTERVAL;
+    let interval = Math.max(DENSITY_SAMPLE_INITIAL_INTERVAL, gate?.initialInterval ?? 0);
+    const sampleAt = async (at) => {
+        const { start, end } = sampleWindow(region, interval, at);
+        const features = await firstValueFrom(getFeatures({ ...region, start, end }, opts).pipe(toArray()));
+        return {
+            sampledBp: end - start,
+            raw: features.length,
+            admitted: admit ? features.filter(admit).length : features.length,
+        };
+    };
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     while (true) {
-        const { start, end } = sampleWindow(region, interval);
-        const sampledBp = end - start;
-        const features = await firstValueFrom(getFeatures({ ...region, start, end }, opts).pipe(toArray()));
-        const admitted = admit ? features.filter(admit).length : features.length;
+        const { sampledBp, raw, admitted } = await sampleAt(DENSITY_SAMPLE_POINT);
+        // The verdict is already decided by a margin, so a precise density would
+        // only make it more decided. Tested on the admitted count, which is the
+        // population the caller judges — the raw count below governs window growth
+        // for the reason in the note above, and the two must not be swapped.
+        //
+        // A second point has to agree before the probe answers a verdict the old
+        // ladder could not have reached — and `raw` is exactly what separates the
+        // two. A window already holding DENSITY_SAMPLE_MIN_FEATURES is one the exit
+        // below would have answered from anyway, so there is nothing new to confirm
+        // and this falls through to it for the same number. Under that count the
+        // ladder would have kept widening, diluting a local cluster, and answering
+        // here instead is what lets a sparse track with a cluster at the fixed
+        // sample point read as dense and banner at that zoom until the user
+        // force-loads.
+        //
+        // So the confirmation is owed only by the case that is new, which is also
+        // the case that is cheap: every dense annotation track measured clears
+        // DENSITY_SAMPLE_MIN_FEATURES in its first window and pays nothing. A
+        // disagreement is not a verdict — the ladder simply carries on.
+        if (gate?.settled(admitted, sampledBp) &&
+            raw < DENSITY_SAMPLE_MIN_FEATURES) {
+            const other = await sampleAt(DENSITY_CONFIRM_POINT);
+            if (gate.settled(other.admitted, other.sampledBp)) {
+                // the lower of two agreeing readings, so the count the banner quotes is
+                // never the high one of a pair
+                return {
+                    featureDensity: Math.min(admitted / sampledBp, other.admitted / other.sampledBp),
+                };
+            }
+        }
         // Enough features to be meaningful, or the window already spans the whole
         // region (growing further can't sample more) — report density over the bp
         // actually sampled, not the nominal interval.
-        if (features.length >= DENSITY_SAMPLE_MIN_FEATURES || sampledBp >= refLen) {
+        if (raw >= DENSITY_SAMPLE_MIN_FEATURES || sampledBp >= refLen) {
             return { featureDensity: admitted / sampledBp };
         }
         // Sparse region or slow adapter: sampling ran past the time budget without

package/esm/data_adapters/BaseAdapter/types.d.ts

@@ -1,25 +1,21 @@
 import type { StatusCallback } from '../../util/progress.ts';
-import type { StopToken } from '../../util/stopToken.ts';
-import type { Region } from '../../util/types/index.ts';
+export type { ZoomRange } from './zoomRange.ts';
+export type LodTier = 'fine' | 'coarse';
 export interface BaseOptions {
-    stopToken?: StopToken;
+    signal?: AbortSignal;
     bpPerPx?: number;
     sessionId?: string;
-    trackInstanceId?: string;
-    signal?: AbortSignal;
     statusCallback?: StatusCallback;
+    notices?: string[];
     headers?: Record<string, string>;
-    statsEstimationMode?: boolean;
     assemblyName?: string;
-    targetAssemblyName?: string;
-    lodMode?: 'fine' | 'coarse';
-}
-export interface BaseOptionsWithRegions extends BaseOptions {
-    regions?: Region[];
+    lodMode?: LodTier;
+    haplotypes?: string[];
+    topLevelOnly?: boolean;
 }
 export type SearchType = 'full' | 'prefix' | 'exact';
 export interface BaseTextSearchArgs {
     queryString: string;
     searchType?: SearchType;
-    stopToken?: StopToken;
+    signal?: AbortSignal;
 }

package/esm/data_adapters/BaseAdapter/zoomRange.d.ts

@@ -0,0 +1,10 @@
+/**
+ * #api
+ * The bp/px interval, `[minBpPerPx, maxBpPerPx)`, over which an adapter with
+ * zoom levels answers a fetch from the same level it answered `opts.bpPerPx`
+ * from. A display holding the answer refetches when the view leaves it.
+ */
+export interface ZoomRange {
+    minBpPerPx: number;
+    maxBpPerPx: number;
+}

package/esm/data_adapters/CytobandAdapter/CytobandAdapter.js

@@ -4,7 +4,7 @@ import { BaseAdapter } from '../BaseAdapter/index.js';
 export default class CytobandAdapter extends BaseAdapter {
     async getData(opts) {
         const conf = this.getConf('cytobandLocation');
-        if (conf.uri === '' || conf.uri === '/path/to/cytoband.txt.gz') {
+        if (!conf) {
             return [];
         }
         const text = await fetchAndMaybeUnzipText(openLocation(conf, this.pluginManager), opts, 'Downloading cytobands');

package/esm/data_adapters/CytobandAdapter/configSchema.d.ts

@@ -25,17 +25,13 @@
  * ```
  */
 declare const configSchema: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-    /**
-     * #slot
-     * location of a UCSC-style `cytoBand.txt` (`chrom start end name
-     * gieStain`), which draws the ideogram banding in the view's overview bar.
-     * May be gzipped. Configured on an assembly, not on a track.
-     */
+    type: {
+        type: "string";
+    } & {
+        defaultValue: string;
+    };
     readonly cytobandLocation: {
-        readonly type: "fileLocation";
-        readonly defaultValue: {
-            readonly uri: "/path/to/cytoband.txt.gz";
-        };
+        type: "maybeFileLocation";
     };
-}, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
+}, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, true, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
 export default configSchema;

package/esm/data_adapters/CytobandAdapter/configSchema.js

@@ -1,4 +1,4 @@
-import { ConfigurationSchema } from '../../configuration/index.js';
+import { ConfigurationSchema, expandUriShorthand, } from '../../configuration/index.js';
 /**
  * #config CytobandAdapter
  *
@@ -33,10 +33,7 @@ const configSchema = ConfigurationSchema('CytobandAdapter', {
      * May be gzipped. Configured on an assembly, not on a track.
      */
     cytobandLocation: {
-        type: 'fileLocation',
-        defaultValue: {
-            uri: '/path/to/cytoband.txt.gz',
-        },
+        type: 'maybeFileLocation',
     },
 }, {
     explicitlyTyped: true,
@@ -52,17 +49,6 @@ const configSchema = ConfigurationSchema('CytobandAdapter', {
      * }
      * ```
      */
-    preProcessSnapshot: snap => {
-        // populate from just snap.uri
-        return snap.uri
-            ? {
-                ...snap,
-                cytobandLocation: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    preProcessSnapshot: snap => expandUriShorthand(snap, 'cytobandLocation'),
 });
 export default configSchema;

package/esm/data_adapters/dataAdapterCache.d.ts

@@ -4,12 +4,29 @@ import type { AnyDataAdapter } from './BaseAdapter/index.ts';
 import type { SnapshotIn } from '@jbrowse/mobx-state-tree';
 type ConfigSnap = SnapshotIn<AnyConfigurationSchemaType>;
 export declare function adapterConfigCacheKey(conf?: Record<string, unknown>): string;
+/**
+ * #api
+ * The `adapterCapabilities` entry of an adapter that reads the reference
+ * sequence of the assembly it is displayed against: BAM and SAM for mismatches
+ * without an MD tag, CRAM to rebuild bases, GC content and the reference scans
+ * for everything they answer. Such an adapter is built with that reference and
+ * keyed on it as well as on its config, so one config shown on two genomes is
+ * two instances, each reading its own, and an instance never changes reference
+ * for its life. Every other adapter keys on its config alone: a synteny adapter
+ * is fetched from each of its assemblies and reads no reference.
+ */
+export declare const READS_REFERENCE = "readsReference";
 interface AdapterCacheEntry {
     dataAdapter: AnyDataAdapter;
     sessionIds: Set<string>;
 }
-/** instantiate a data adapter, or return a cached one with the same config */
-export declare function getAdapter(pluginManager: PluginManager, sessionId: string, adapterConfigSnapshot: SnapshotIn<AnyConfigurationSchemaType>): Promise<AdapterCacheEntry>;
+/**
+ * instantiate a data adapter, or return a cached one with the same config.
+ * `sequenceAdapter` is the reference of the genome the request names; a
+ * {@link READS_REFERENCE} type is keyed on it and built with it, any other
+ * type ignores it
+ */
+export declare function getAdapter(pluginManager: PluginManager, sessionId: string, adapterConfigSnapshot: SnapshotIn<AnyConfigurationSchemaType>, sequenceAdapter?: Record<string, unknown>): Promise<AdapterCacheEntry>;
 /**
  * this is a callback that is passed to adapters that allows them to get any
  * sub-adapters that they need internally, staying with the same worker session

package/esm/data_adapters/dataAdapterCache.js

@@ -3,6 +3,25 @@ export function adapterConfigCacheKey(conf = {}) {
     const { adapterId } = conf;
     return typeof adapterId === 'string' && adapterId ? adapterId : idMaker(conf);
 }
+/**
+ * #api
+ * The `adapterCapabilities` entry of an adapter that reads the reference
+ * sequence of the assembly it is displayed against: BAM and SAM for mismatches
+ * without an MD tag, CRAM to rebuild bases, GC content and the reference scans
+ * for everything they answer. Such an adapter is built with that reference and
+ * keyed on it as well as on its config, so one config shown on two genomes is
+ * two instances, each reading its own, and an instance never changes reference
+ * for its life. Every other adapter keys on its config alone: a synteny adapter
+ * is fetched from each of its assemblies and reads no reference.
+ */
+export const READS_REFERENCE = 'readsReference';
+function readsReference(pluginManager, adapterConfig) {
+    const type = adapterConfig?.type;
+    return (typeof type === 'string' &&
+        pluginManager
+            .getAdapterType(type)
+            .adapterCapabilities.includes(READS_REFERENCE));
+}
 // Pruned by storeWithEvict (rejections) and by freeAdapterResources, which the
 // CoreFreeResources RPC reaches when the last track holding an adapter config is
 // closed (releaseAdapterSession). There is still no size bound: an adapter
@@ -16,7 +35,7 @@ function storeWithEvict(key, p) {
     adapterCache[key] = p;
     return p;
 }
-async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
+async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence) {
     const adapterType = adapterConfigSnapshot?.type;
     if (!adapterType) {
         throw new Error(`could not determine adapter type from adapter config snapshot ${JSON.stringify(adapterConfigSnapshot)}`);
@@ -25,23 +44,38 @@ async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
     // instantiate the data adapter's config schema so it gets its defaults,
     // callbacks, etc
     const adapterConfig = dataAdapterType.configSchema.create(adapterConfigSnapshot, { pluginManager });
-    const getSubAdapter = conf => getAdapter(pluginManager, sessionId, conf);
+    // a sub-adapter reads the reference its parent was built with
+    const getSubAdapter = conf => getAdapter(pluginManager, sessionId, conf, keyedSequence);
     const CLASS = await dataAdapterType.getAdapterClass();
-    const dataAdapter = new CLASS(adapterConfig, getSubAdapter, pluginManager);
+    const dataAdapter = new CLASS(adapterConfig, getSubAdapter, pluginManager, keyedSequence);
     return {
         dataAdapter,
         sessionIds: new Set([sessionId]),
     };
 }
-/** look up the cached entry for a config, creating and storing it if absent */
-function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot) {
-    const cacheKey = adapterConfigCacheKey(adapterConfigSnapshot);
+/**
+ * look up the cached entry for a config, creating and storing it if absent.
+ * Keyed synchronously, so concurrent callers share one pending entry
+ */
+function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter) {
+    const keyedSequence = sequenceAdapter && readsReference(pluginManager, adapterConfigSnapshot)
+        ? sequenceAdapter
+        : undefined;
+    const configKey = adapterConfigCacheKey(adapterConfigSnapshot);
+    const cacheKey = keyedSequence
+        ? `${configKey}|${adapterConfigCacheKey(keyedSequence)}`
+        : configKey;
     return (adapterCache[cacheKey] ??
-        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot)));
+        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot, keyedSequence)));
 }
-/** instantiate a data adapter, or return a cached one with the same config */
-export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot) {
-    const ret = await getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot);
+/**
+ * instantiate a data adapter, or return a cached one with the same config.
+ * `sequenceAdapter` is the reference of the genome the request names; a
+ * {@link READS_REFERENCE} type is keyed on it and built with it, any other
+ * type ignores it
+ */
+export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter) {
+    const ret = await getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot, sequenceAdapter);
     ret.sessionIds.add(sessionId);
     return ret;
 }

package/esm/data_adapters/getFeatureAdapter.d.ts

@@ -7,10 +7,12 @@ export interface GetFeatureAdapterArgs {
     sequenceAdapter?: Record<string, unknown>;
 }
 /**
- * Resolve a feature data adapter and prime its reference-sequence adapter
- * config in one step — the single resolution path for every RPC that reads
- * features. Returns undefined when the config resolves to a non-feature
- * adapter, so callers that can degrade (e.g. getRefNames → []) decide how; use
+ * Resolve a feature data adapter — the single resolution path for every RPC
+ * that reads features. An RPC passes its whole args (`{ ...args, pluginManager
+ * }`) so the `sequenceAdapter` serialization attached reaches the cache without
+ * being named, and a reference-reading type comes back built for that genome.
+ * Returns undefined when the config resolves to a non-feature adapter, so
+ * callers that can degrade (e.g. getRefNames → []) decide how; use
  * {@link getFeatureAdapterOrThrow} when a feature adapter is required.
  */
 export declare function getFeatureAdapter({ pluginManager, sessionId, adapterConfig, sequenceAdapter, }: GetFeatureAdapterArgs): Promise<BaseFeatureDataAdapter | undefined>;

package/esm/data_adapters/getFeatureAdapter.js

@@ -1,17 +1,17 @@
 import { isFeatureAdapter } from './BaseAdapter/index.js';
 import { getAdapter } from './dataAdapterCache.js';
 /**
- * Resolve a feature data adapter and prime its reference-sequence adapter
- * config in one step — the single resolution path for every RPC that reads
- * features. Returns undefined when the config resolves to a non-feature
- * adapter, so callers that can degrade (e.g. getRefNames → []) decide how; use
+ * Resolve a feature data adapter — the single resolution path for every RPC
+ * that reads features. An RPC passes its whole args (`{ ...args, pluginManager
+ * }`) so the `sequenceAdapter` serialization attached reaches the cache without
+ * being named, and a reference-reading type comes back built for that genome.
+ * Returns undefined when the config resolves to a non-feature adapter, so
+ * callers that can degrade (e.g. getRefNames → []) decide how; use
  * {@link getFeatureAdapterOrThrow} when a feature adapter is required.
  */
 export async function getFeatureAdapter({ pluginManager, sessionId, adapterConfig, sequenceAdapter, }) {
-    const { dataAdapter } = await getAdapter(pluginManager, sessionId, adapterConfig);
-    const featureAdapter = isFeatureAdapter(dataAdapter) ? dataAdapter : undefined;
-    featureAdapter?.setSequenceAdapterConfig(sequenceAdapter);
-    return featureAdapter;
+    const { dataAdapter } = await getAdapter(pluginManager, sessionId, adapterConfig, sequenceAdapter);
+    return isFeatureAdapter(dataAdapter) ? dataAdapter : undefined;
 }
 /**
  * {@link getFeatureAdapter} for the common case where the RPC cannot proceed

package/esm/data_adapters/getSequenceSubAdapter.d.ts

@@ -3,17 +3,15 @@ import type { BaseAdapter, BaseSequenceAdapter } from './BaseAdapter/index.ts';
  * Resolves the reference sequence an adapter reads from.
  *
  * **The assembly is the source, and a hand-written `sequenceAdapter` slot is an
- * anti-pattern.** `getFeatureAdapter` and `CoreGetRefNames` prime every feature
- * adapter's `sequenceAdapterConfig` from the assembly the track is displayed
- * against, so no config has to copy a sequence adapter into a track. The slot
- * survives as an escape hatch for reading some *other* sequence, and setting it
- * pins the track to that source even when the assembly's own sequence changes —
- * so it wins only when explicitly present, and `jbrowse validate` warns about it.
+ * anti-pattern.** A reference-reading adapter is built with the sequence of the
+ * assembly the request that created it named (dataAdapterCache), so no config
+ * has to copy a sequence adapter into a track. The slot survives as an escape
+ * hatch for reading some *other* sequence, and setting it pins the track to
+ * that source even when the assembly's own sequence changes — so it wins only
+ * when explicitly present, and `jbrowse validate` warns about it.
  *
  * In core rather than beside one of its callers because the field it reads is
- * `BaseAdapter`'s. Deliberately NOT in `BaseAdapter/index.ts`: that barrel is a
- * `@jbrowse/core/*` re-export, and a name published there is load-bearing ABI —
- * `abi.test.ts`/`abiBaseline.json` fails a removal from it.
+ * `BaseAdapter`'s.
  *
  * `configured` is passed in rather than read here so each adapter reads its own
  * slot through its own config type.