@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/data_adapters/BaseAdapter/util.js

@@ -1,12 +1,23 @@
-export function isSequenceAdapter(t) {
-    return 'getRegions' in t && 'getFeatures' in t;
-}
 export function isRegionsAdapter(t) {
     return 'getRegions' in t;
 }
 export function isFeatureAdapter(t) {
     return 'getFeatures' in t;
 }
+// An adapter that can report the refNames its file uses, which is all refName
+// renaming needs. Deliberately broader than isFeatureAdapter: an adapter can
+// serve a non-feature payload (precomputed LD pairs, say) and still need its
+// contig names reconciled with the assembly's. Gating refName lookup on
+// isFeatureAdapter instead meant such an adapter reported *zero* refNames, so
+// the refName map came back empty, so renaming silently did nothing and every
+// record was later dropped on an exact-match refName test - a blank track with
+// no error. See CoreGetRefNames.
+export function isRefNameSource(t) {
+    return typeof t.getRefNames === 'function';
+}
+export function isSequenceAdapter(t) {
+    return 'getSequence' in t;
+}
 export function isRefNameAliasAdapter(t) {
     return 'getRefNameAliases' in t;
 }

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

@@ -1,6 +1,6 @@
 import { SimpleFeature } from '../../util/index.ts';
 import { BaseAdapter } from '../BaseAdapter/index.ts';
-import type { BaseOptions } from '../BaseAdapter/BaseOptions.ts';
+import type { BaseOptions } from '../BaseAdapter/types.ts';
 export default class CytobandAdapter extends BaseAdapter {
     getData(opts?: BaseOptions): Promise<SimpleFeature[]>;
 }

package/esm/data_adapters/CytobandAdapter/CytobandAdapter.js

@@ -1,13 +1,13 @@
-import { SimpleFeature, fetchAndMaybeUnzipText } from "../../util/index.js";
-import { openLocation } from "../../util/io/index.js";
-import { BaseAdapter } from "../BaseAdapter/index.js";
+import { SimpleFeature, fetchAndMaybeUnzipText } from '../../util/index.js';
+import { openLocation } from '../../util/io/index.js';
+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') {
             return [];
         }
-        const text = await fetchAndMaybeUnzipText(openLocation(conf, this.pluginManager), opts);
+        const text = await fetchAndMaybeUnzipText(openLocation(conf, this.pluginManager), opts, 'Downloading cytobands');
         return text
             .split(/\n|\r\n|\r/)
             .filter(f => !!f.trim())

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

@@ -1,8 +1,40 @@
+/**
+ * #config CytobandAdapter
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `cytobands` — not on a track. It draws the
+ * ideogram banding in the linear genome view's overview bar:
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   cytobands: {
+ *     adapter: {
+ *       type: 'CytobandAdapter',
+ *       uri: 'https://example.com/hg38.cytoBand.txt.gz',
+ *     },
+ *   },
+ * }
+ * ```
+ */
 declare const configSchema: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-    cytobandLocation: {
-        type: string;
-        defaultValue: {
-            uri: string;
+    /**
+     * #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.
+     */
+    readonly cytobandLocation: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/cytoband.txt.gz";
         };
     };
 }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;

package/esm/data_adapters/CytobandAdapter/configSchema.js

@@ -1,6 +1,37 @@
-import { ConfigurationSchema } from "../../configuration/index.js";
-function x() { }
+import { ConfigurationSchema } from '../../configuration/index.js';
+/**
+ * #config CytobandAdapter
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `cytobands` — not on a track. It draws the
+ * ideogram banding in the linear genome view's overview bar:
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   cytobands: {
+ *     adapter: {
+ *       type: 'CytobandAdapter',
+ *       uri: 'https://example.com/hg38.cytoBand.txt.gz',
+ *     },
+ *   },
+ * }
+ * ```
+ */
 const configSchema = ConfigurationSchema('CytobandAdapter', {
+    /**
+     * #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.
+     */
     cytobandLocation: {
         type: 'fileLocation',
         defaultValue: {
@@ -9,7 +40,20 @@ const configSchema = ConfigurationSchema('CytobandAdapter', {
     },
 }, {
     explicitlyTyped: true,
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "CytobandAdapter",
+     *   "uri": "yourfile.bed"
+     * }
+     * ```
+     */
     preProcessSnapshot: snap => {
+        // populate from just snap.uri
         return snap.uri
             ? {
                 ...snap,

package/esm/data_adapters/CytobandAdapter/index.js

@@ -1,5 +1,5 @@
-import configSchema from "./configSchema.js";
-import { AdapterType } from "../../pluggableElementTypes/index.js";
+import { AdapterType } from '../../pluggableElementTypes/index.js';
+import configSchema from './configSchema.js';
 export default function CytobandAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'CytobandAdapter',
@@ -7,6 +7,6 @@ export default function CytobandAdapterF(pluginManager) {
         adapterMetadata: {
             hiddenFromGUI: true,
         },
-        getAdapterClass: () => import("./CytobandAdapter.js").then(f => f.default),
+        getAdapterClass: () => import('./CytobandAdapter.js').then(f => f.default),
     }));
 }

package/esm/data_adapters/adapterSessionRefcount.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Counts how many live track models are using each rpcSessionId, so the
+ * worker-side dataAdapterCache can be told when the last one goes away.
+ *
+ * ## Why a refcount and not just "track closed"
+ *
+ * An rpcSessionId is derived from the *adapter config* (BaseTrackModel's
+ * `rpcSessionId` getter is `adapterConfigCacheKey(adapter)`), so it is shared by
+ * every track model with that config — the same track shown in two linear genome
+ * views is two model instances with one id, as is a pair of tracks configured
+ * alike. Freeing on any close would evict an adapter the other view is still
+ * querying. The count is incremented per track model and the free only fires at
+ * zero.
+ *
+ * Counting here rather than walking the state tree at teardown keeps it exact:
+ * during a session teardown the tree is already coming apart, and "is any other
+ * track still using this?" is not a question worth asking of a half-destroyed
+ * tree.
+ *
+ * ## Why a WeakMap keyed on the rpcManager
+ *
+ * The counts belong to one session. Keying them on the session's own RpcManager
+ * means a discarded session's counts are collected with it, with no reset call
+ * for anyone to forget. This is the case the adapter cache itself cannot use —
+ * see dataAdapterCache — because here the key is a main-thread object whose
+ * lifetime already matches, rather than a string that crossed a worker boundary.
+ */
+/**
+ * The slice of RpcManager this needs. Structural rather than the concrete class
+ * so that the partial stubs the model tests build satisfy it, and so that
+ * adapter-lifetime bookkeeping does not depend on the RPC transport.
+ */
+interface RpcCaller {
+    freeSession(sessionId: string): Promise<void>;
+}
+/** Record that a track model is using `sessionId`. Pair with release. */
+export declare function retainAdapterSession(rpcManager: RpcCaller | undefined, sessionId: string): void;
+/**
+ * Give up one claim on `sessionId`. When the last one goes, ask the worker to
+ * drop the adapters cached under it — which is the only thing that ever makes
+ * them collectable, since the cache is a strong reference rooted in module
+ * scope.
+ *
+ * The free lands on the same driver the track's queries ran on, because every
+ * call in the app runs on the one the session resolved — and, under a worker
+ * pool, on the same worker, without booting one for a session that never
+ * dispatched anything. See `BaseRpcDriver.freeSession`.
+ *
+ * Errors are swallowed on purpose. This runs on teardown, where a worker
+ * already terminated by a session switch is the expected case rather than a
+ * fault, and nothing downstream could act on the failure anyway.
+ *
+ * Closing and immediately reopening the same track can race: the free is in
+ * flight while the reopened track re-retains, and the eviction lands on the
+ * adapter the new track just claimed. It costs that track one re-setup and
+ * heals itself on the next query, because an evicted adapter is only ever a
+ * cold cache. Sequencing it away would mean generation counters on a cache,
+ * which is a poor trade for a mis-click.
+ */
+export declare function releaseAdapterSession(rpcManager: RpcCaller | undefined, sessionId: string): Promise<void>;
+export {};

package/esm/data_adapters/adapterSessionRefcount.js

@@ -0,0 +1,96 @@
+/**
+ * Counts how many live track models are using each rpcSessionId, so the
+ * worker-side dataAdapterCache can be told when the last one goes away.
+ *
+ * ## Why a refcount and not just "track closed"
+ *
+ * An rpcSessionId is derived from the *adapter config* (BaseTrackModel's
+ * `rpcSessionId` getter is `adapterConfigCacheKey(adapter)`), so it is shared by
+ * every track model with that config — the same track shown in two linear genome
+ * views is two model instances with one id, as is a pair of tracks configured
+ * alike. Freeing on any close would evict an adapter the other view is still
+ * querying. The count is incremented per track model and the free only fires at
+ * zero.
+ *
+ * Counting here rather than walking the state tree at teardown keeps it exact:
+ * during a session teardown the tree is already coming apart, and "is any other
+ * track still using this?" is not a question worth asking of a half-destroyed
+ * tree.
+ *
+ * ## Why a WeakMap keyed on the rpcManager
+ *
+ * The counts belong to one session. Keying them on the session's own RpcManager
+ * means a discarded session's counts are collected with it, with no reset call
+ * for anyone to forget. This is the case the adapter cache itself cannot use —
+ * see dataAdapterCache — because here the key is a main-thread object whose
+ * lifetime already matches, rather than a string that crossed a worker boundary.
+ */
+const refcounts = new WeakMap();
+/**
+ * Whether there is an rpcManager to key counts on and to send a free to. A
+ * session model assembled without one — which model unit tests do routinely —
+ * should not make opening a track throw over what is only a cache hint, so both
+ * entry points degrade to no-ops. It also has to be an object before it can be
+ * a WeakMap key at all.
+ */
+function isUsable(rpcManager) {
+    return typeof rpcManager?.freeSession === 'function';
+}
+function countsFor(rpcManager) {
+    let counts = refcounts.get(rpcManager);
+    if (!counts) {
+        counts = new Map();
+        refcounts.set(rpcManager, counts);
+    }
+    return counts;
+}
+/** Record that a track model is using `sessionId`. Pair with release. */
+export function retainAdapterSession(rpcManager, sessionId) {
+    if (!isUsable(rpcManager)) {
+        return;
+    }
+    const counts = countsFor(rpcManager);
+    counts.set(sessionId, (counts.get(sessionId) ?? 0) + 1);
+}
+/**
+ * Give up one claim on `sessionId`. When the last one goes, ask the worker to
+ * drop the adapters cached under it — which is the only thing that ever makes
+ * them collectable, since the cache is a strong reference rooted in module
+ * scope.
+ *
+ * The free lands on the same driver the track's queries ran on, because every
+ * call in the app runs on the one the session resolved — and, under a worker
+ * pool, on the same worker, without booting one for a session that never
+ * dispatched anything. See `BaseRpcDriver.freeSession`.
+ *
+ * Errors are swallowed on purpose. This runs on teardown, where a worker
+ * already terminated by a session switch is the expected case rather than a
+ * fault, and nothing downstream could act on the failure anyway.
+ *
+ * Closing and immediately reopening the same track can race: the free is in
+ * flight while the reopened track re-retains, and the eviction lands on the
+ * adapter the new track just claimed. It costs that track one re-setup and
+ * heals itself on the next query, because an evicted adapter is only ever a
+ * cold cache. Sequencing it away would mean generation counters on a cache,
+ * which is a poor trade for a mis-click.
+ */
+export async function releaseAdapterSession(rpcManager, sessionId) {
+    if (!isUsable(rpcManager)) {
+        return;
+    }
+    const counts = countsFor(rpcManager);
+    // a release with no matching retain floors at zero and frees, rather than
+    // going negative and silently suppressing the next real free
+    const remaining = (counts.get(sessionId) ?? 1) - 1;
+    if (remaining > 0) {
+        counts.set(sessionId, remaining);
+        return;
+    }
+    counts.delete(sessionId);
+    try {
+        await rpcManager.freeSession(sessionId);
+    }
+    catch {
+        // teardown; see above
+    }
+}

package/esm/data_adapters/dataAdapterCache.d.ts

@@ -3,12 +3,46 @@ import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
 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;
 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>;
+/**
+ * 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
+ * ID
+ */
 export type getSubAdapterType = (adapterConfigSnap: ConfigSnap) => ReturnType<typeof getAdapter>;
-export declare function freeAdapterResources(args: Record<string, any>): Promise<void>;
+/**
+ * Drop this session's claim on every cached adapter, and evict the ones no
+ * other session still claims. Reached from the CoreFreeResources RPC when the
+ * last track using an adapter config closes.
+ *
+ * Deleting the key is the whole reclamation: the cache is the only strong
+ * reference to an adapter, so once it goes the instance and everything it holds
+ * — a whole parsed GFF3, a BAM chunk cache — become unreachable and are
+ * collected normally. There is nothing to free by hand.
+ *
+ * "Collected normally" is not the same as "collected now", and for the indexed
+ * adapters it is not even soon. @gmod/bam, @gmod/cram and @gmod/tabix each hold
+ * their parsed chunks in a SharedReadCache that sweeps itself on a setInterval,
+ * and a pending timer is a GC root — so the instance stays reachable through its
+ * own sweep timer until that sweep empties the cache and stops itself, three
+ * minutes later. Measured: closing a panned alignments track reclaims nothing at
+ * the time it happens, and the worker falls from 296 MB to 7 MB four minutes on.
+ * Deleting the key is still the only thing to do here; just don't read a heap
+ * immediately after a close and conclude this did nothing.
+ *
+ * The refcount is what makes this safe to call on any track close: an adapter
+ * pulled in as a sub-adapter carries its parent's sessionId (getSubAdapter
+ * passes it straight through), so a sequence adapter shared by two alignments
+ * tracks survives either one of them closing.
+ */
+export declare function freeAdapterResources(args: {
+    sessionId?: string;
+}): Promise<void>;
 export declare function clearAdapterCache(): void;
 export {};

package/esm/data_adapters/dataAdapterCache.js

@@ -1,16 +1,31 @@
-import { adapterConfigCacheKey } from "./util.js";
+import idMaker from '../util/idMaker.js';
+export function adapterConfigCacheKey(conf = {}) {
+    const { adapterId } = conf;
+    return typeof adapterId === 'string' && adapterId ? adapterId : idMaker(conf);
+}
+// 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
+// whose track stays open lives as long as its worker, by design.
 let adapterCache = {};
+/** stores a promise in the cache and auto-evicts if it rejects */
+function storeWithEvict(key, p) {
+    p.catch(() => {
+        delete adapterCache[key];
+    });
+    adapterCache[key] = p;
+    return p;
+}
 async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
     const adapterType = adapterConfigSnapshot?.type;
     if (!adapterType) {
         throw new Error(`could not determine adapter type from adapter config snapshot ${JSON.stringify(adapterConfigSnapshot)}`);
     }
     const dataAdapterType = pluginManager.getAdapterType(adapterType);
-    if (!dataAdapterType) {
-        throw new Error(`unknown data adapter type ${adapterType}`);
-    }
+    // instantiate the data adapter's config schema so it gets its defaults,
+    // callbacks, etc
     const adapterConfig = dataAdapterType.configSchema.create(adapterConfigSnapshot, { pluginManager });
-    const getSubAdapter = getAdapter.bind(null, pluginManager, sessionId);
+    const getSubAdapter = conf => getAdapter(pluginManager, sessionId, conf);
     const CLASS = await dataAdapterType.getAdapterClass();
     const dataAdapter = new CLASS(adapterConfig, getSubAdapter, pluginManager);
     return {
@@ -18,34 +33,59 @@ async function getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot) {
         sessionIds: new Set([sessionId]),
     };
 }
-export async function getAdapter(pluginManager, sessionId, adapterConfigSnapshot) {
+/** look up the cached entry for a config, creating and storing it if absent */
+function getOrCreateEntry(pluginManager, sessionId, adapterConfigSnapshot) {
     const cacheKey = adapterConfigCacheKey(adapterConfigSnapshot);
-    adapterCache[cacheKey] ??= getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot);
-    const ret = await adapterCache[cacheKey];
+    return (adapterCache[cacheKey] ??
+        storeWithEvict(cacheKey, getAdapterPre(pluginManager, sessionId, adapterConfigSnapshot)));
+}
+/** 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);
     ret.sessionIds.add(sessionId);
     return ret;
 }
+/**
+ * Drop this session's claim on every cached adapter, and evict the ones no
+ * other session still claims. Reached from the CoreFreeResources RPC when the
+ * last track using an adapter config closes.
+ *
+ * Deleting the key is the whole reclamation: the cache is the only strong
+ * reference to an adapter, so once it goes the instance and everything it holds
+ * — a whole parsed GFF3, a BAM chunk cache — become unreachable and are
+ * collected normally. There is nothing to free by hand.
+ *
+ * "Collected normally" is not the same as "collected now", and for the indexed
+ * adapters it is not even soon. @gmod/bam, @gmod/cram and @gmod/tabix each hold
+ * their parsed chunks in a SharedReadCache that sweeps itself on a setInterval,
+ * and a pending timer is a GC root — so the instance stays reachable through its
+ * own sweep timer until that sweep empties the cache and stops itself, three
+ * minutes later. Measured: closing a panned alignments track reclaims nothing at
+ * the time it happens, and the worker falls from 296 MB to 7 MB four minutes on.
+ * Deleting the key is still the only thing to do here; just don't read a heap
+ * immediately after a close and conclude this did nothing.
+ *
+ * The refcount is what makes this safe to call on any track close: an adapter
+ * pulled in as a sub-adapter carries its parent's sessionId (getSubAdapter
+ * passes it straight through), so a sequence adapter shared by two alignments
+ * tracks survives either one of them closing.
+ */
 export async function freeAdapterResources(args) {
-    const specKeys = Object.keys(args);
-    if (specKeys.length === 1 && specKeys[0] === 'sessionId') {
-        const { sessionId } = args;
-        for (const [cacheKey, cacheEntryP] of Object.entries(adapterCache)) {
+    const { sessionId } = args;
+    if (!sessionId) {
+        return;
+    }
+    for (const [cacheKey, cacheEntryP] of Object.entries(adapterCache)) {
+        try {
             const cacheEntry = await cacheEntryP;
             cacheEntry.sessionIds.delete(sessionId);
             if (cacheEntry.sessionIds.size === 0) {
                 delete adapterCache[cacheKey];
             }
         }
-    }
-    else {
-        for (const cacheEntryP of Object.values(adapterCache)) {
-            const cacheEntry = await cacheEntryP;
-            const regions = args.regions || (args.region ? [args.region] : []);
-            for (const region of regions) {
-                if (region.refName !== undefined) {
-                    cacheEntry.dataAdapter.freeResources(region);
-                }
-            }
+        catch (e) {
+            console.error(`dataAdapterCache: evicting failed adapter "${cacheKey}"`, e);
+            delete adapterCache[cacheKey];
         }
     }
 }

package/esm/data_adapters/getFeatureAdapter.d.ts

@@ -0,0 +1,22 @@
+import type PluginManager from '../PluginManager.ts';
+import type { BaseFeatureDataAdapter } from './BaseAdapter/index.ts';
+export interface GetFeatureAdapterArgs {
+    pluginManager: PluginManager;
+    sessionId: string;
+    adapterConfig: Record<string, unknown>;
+    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
+ * {@link getFeatureAdapterOrThrow} when a feature adapter is required.
+ */
+export declare function getFeatureAdapter({ pluginManager, sessionId, adapterConfig, sequenceAdapter, }: GetFeatureAdapterArgs): Promise<BaseFeatureDataAdapter | undefined>;
+/**
+ * {@link getFeatureAdapter} for the common case where the RPC cannot proceed
+ * without a feature adapter: throws a clear error instead of returning
+ * undefined, so callers get a definite type and no cast.
+ */
+export declare function getFeatureAdapterOrThrow(args: GetFeatureAdapterArgs): Promise<BaseFeatureDataAdapter>;

package/esm/data_adapters/getFeatureAdapter.js

@@ -0,0 +1,27 @@
+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
+ * {@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;
+}
+/**
+ * {@link getFeatureAdapter} for the common case where the RPC cannot proceed
+ * without a feature adapter: throws a clear error instead of returning
+ * undefined, so callers get a definite type and no cast.
+ */
+export async function getFeatureAdapterOrThrow(args) {
+    const dataAdapter = await getFeatureAdapter(args);
+    if (!dataAdapter) {
+        throw new Error(`adapter "${args.adapterConfig.type}" is not a feature adapter`);
+    }
+    return dataAdapter;
+}

package/esm/data_adapters/getSequenceSubAdapter.d.ts

@@ -0,0 +1,21 @@
+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.
+ *
+ * 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.
+ *
+ * `configured` is passed in rather than read here so each adapter reads its own
+ * slot through its own config type.
+ */
+export declare function getSequenceSubAdapter(adapter: BaseAdapter, configured: unknown): Promise<BaseSequenceAdapter>;

package/esm/data_adapters/getSequenceSubAdapter.js

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * `configured` is passed in rather than read here so each adapter reads its own
+ * slot through its own config type.
+ */
+export async function getSequenceSubAdapter(adapter, configured) {
+    const config = configured ?? adapter.sequenceAdapterConfig;
+    if (!config) {
+        throw new Error('No sequence adapter available: either set the `sequenceAdapter` slot or display this track against an assembly that has one');
+    }
+    const result = await adapter.getSubAdapter?.(config);
+    if (!result) {
+        throw new Error('Error getting subadapter');
+    }
+    // An assembly can be backed by an adapter that carries no residues at all
+    // (ChromSizesAdapter defines refName lengths only), and auto-resolution makes
+    // that reachable without anyone having named a sequence adapter. Check for the
+    // method rather than casting blind, so this fails with the reason instead of
+    // `getSequence is not a function` deep in a scan.
+    const { dataAdapter } = result;
+    if (!isSequenceAdapter(dataAdapter)) {
+        // named from the config, not `constructor.name`, which minifies to noise
+        const { type } = config;
+        throw new Error(`Cannot scan the reference: adapter "${String(type)}" provides no sequence`);
+    }
+    return dataAdapter;
+}
+function isSequenceAdapter(adapter) {
+    return (typeof adapter.getSequence === 'function');
+}