@jbrowse/core 4.2.1 → 5.0.0-beta.1

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

@@ -1,24 +1,137 @@
-import { type Observable } from 'rxjs';
 import { BaseAdapter } from './BaseAdapter.ts';
-import type { BaseOptions } from './BaseOptions.ts';
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { Feature } from '../../util/simpleFeature.ts';
 import type { AugmentedRegion as Region } from '../../util/types/index.ts';
-export declare abstract class BaseFeatureDataAdapter extends BaseAdapter {
+import type { BaseOptions } from './types.ts';
+import type { Observable } from 'rxjs';
+/**
+ * Base class for feature adapters to extend. Defines some methods that
+ * subclasses must implement.
+ */
+/** #adapterBase BaseFeatureDataAdapter | features overlapping a region — genes, reads, variants. The common case */
+export declare abstract class BaseFeatureDataAdapter<CONF extends AnyConfigurationModel = AnyConfigurationModel> extends BaseAdapter<CONF> {
+    /**
+     * Get all reference sequence names used in the data source
+     * Example:
+     * public async getRefNames(opts?: BaseOptions): Promise\<string[]\> \}
+     *   await this.setup()
+     *   const \{ refNames \} = this.metadata
+     *   return refNames
+     * \}
+     *
+     *
+     * NOTE: If an adapter is unable to determine the reference sequence names,
+     * the array will be empty
+     * @param opts - Feature adapter options
+     */
     abstract getRefNames(opts?: BaseOptions): Promise<string[]>;
+    /**
+     * Get features from the data source that overlap a region
+     * Example:
+     * public getFeatures(
+     *   region: Region,
+     *   opts: BaseOptions,
+     * ): Observable<Feature> \{
+     *   return ObservableCreate(observer =\> \{
+     *     const records = getRecords(assembly, refName, start, end)
+     *     records.forEach(record =\> \{
+     *       observer.next(this.recordToFeature(record))
+     *     \})
+     *     observer.complete()
+     *   \})
+     * \}
+     * @param region - Region
+     * @param opts - Feature adapter options
+     * @returns Observable of Feature objects in the region
+     */
     abstract getFeatures(region: Region, opts?: BaseOptions): Observable<Feature>;
+    /**
+     * Return "header info" that is fetched from the data file, or other info
+     * that would not simply be in the config of the file. The return value can
+     * be `{tag:string, data: any}[]` e.g. list of tags with their values which
+     * is how VCF,BAM,CRAM return values for getInfo or it can be a nested JSON
+     * object
+     */
     getHeader(_opts?: BaseOptions): Promise<unknown>;
+    /**
+     * Return info that is primarily used for interpreting the data that is there,
+     * primarily in reference to being used for augmenting feature details panels
+     */
     getMetadata(_opts?: BaseOptions): Promise<unknown>;
-    getFeaturesInRegion(region: Region, opts?: BaseOptions): Observable<Feature>;
+    /**
+     * Adapters that are frequently called on multiple regions simultaneously
+     * may want to implement a more efficient custom version of this method.
+     *
+     * The regions are fetched concurrently, so each gets its own
+     * {@link createStatusFanOut} slot rather than the caller's raw
+     * `statusCallback`: they all report the same phases ("Downloading
+     * features"), and sharing one status field meant the last writer won and the
+     * first region to finish cleared the label while the rest were still
+     * downloading. Aggregated, N regions read as one Σbytes bar — the same helper
+     * `callEachRegion` uses to give the per-region RPCs on the main thread a slot
+     * apiece.
+     */
     getFeaturesInMultipleRegions(regions: Region[], opts?: BaseOptions): Observable<Feature>;
+    /**
+     * Convenience wrapper that collects {@link getFeatures} for a region into an
+     * array — the common shape across RPC methods (RenderFeatureData, Manhattan,
+     * Wiggle, etc.). Pass `opts` so `statusCallback`/`stopToken` reach the
+     * adapter; omitting them means no download progress and a fetch that can't be
+     * interrupted mid-flight.
+     */
+    getFeaturesArray(region: Region, opts?: BaseOptions): Promise<Feature[]>;
+    /**
+     * {@link getFeaturesArray} across multiple regions — collects
+     * {@link getFeaturesInMultipleRegions} into an array. The common shape in
+     * matrix/comparative RPC methods (variants, synteny, dotplot, breakpoint).
+     */
+    getFeaturesInMultipleRegionsArray(regions: Region[], opts?: BaseOptions): Promise<Feature[]>;
+    /**
+     * Check if the store has data for the given reference name.
+     * @param refName - Name of the reference sequence
+     * @returns Whether data source has data for the given reference name
+     */
     hasDataForRefName(refName: string, opts?: BaseOptions): Promise<boolean>;
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over a region, primarily used for quantitative tracks
+     */
     getRegionQuantitativeStats(region: Region, opts?: BaseOptions): Promise<import("../../util/stats.ts").RectifiedQuantitativeStats>;
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over multiple regions, primarily used for quantitative tracks
+     */
     getMultiRegionQuantitativeStats(regions?: Region[], opts?: BaseOptions): Promise<import("../../util/stats.ts").RectifiedQuantitativeStats>;
-    getRegionFeatureDensityStats(region: Region, opts?: BaseOptions): Promise<import("./types.ts").FeatureDensityStats>;
-    getMultiRegionFeatureDensityStats(regions: Region[], opts?: BaseOptions): Promise<import("./types.ts").FeatureDensityStats>;
-    getSources(regions: Region[]): Promise<{
+    /**
+     * Cheap upper bound on the compressed bytes a fetch of `regions` would pull,
+     * derived from an index without downloading or parsing any features. The
+     * default returns `undefined` ("no cheap estimate"); indexed adapters (tabix)
+     * override it, and an adapter that caps what it returns at screen resolution
+     * (BigWig, HiC, sequence) simply doesn't — no estimate means no byte gate.
+     *
+     * The one byte-estimate entry point, used by both halves of the region-too-large
+     * gate: the pre-flight `CoreGetRegionByteEstimate` RPC and the in-fetch
+     * short-circuit in `executeRenderFeatureData`. The byte *budget* it is compared
+     * against is read on the main thread from the adapter's `fetchSizeLimit` config
+     * slot, so it never crosses the worker boundary — see
+     * agent-docs/reference/REGION_TOO_LARGE.md.
+     */
+    getRegionByteSize(_regions: Region[], _opts?: BaseOptions): Promise<number | undefined>;
+    getSources(regions: Region[], opts?: BaseOptions): Promise<{
         name: string;
         color?: string;
         [key: string]: unknown;
     }[]>;
+    /**
+     * Export data from the adapter in a specified format for given regions.
+     * Some adapters (like VcfAdapter) can efficiently export raw data directly
+     * from the file without parsing to features.
+     *
+     * @param regions - Regions to export data from
+     * @param formatType - The format to export to (e.g. 'vcf', 'sam', 'bedgraph')
+     * @param opts - Feature adapter options
+     * @returns Promise resolving to the exported data as a string, or undefined
+     *          if the adapter does not support direct export for this format
+     */
     getExportData(_regions: Region[], _formatType: string, _opts?: BaseOptions): Promise<string | undefined>;
 }

package/esm/data_adapters/BaseAdapter/BaseFeatureDataAdapter.js

@@ -1,34 +1,80 @@
 import { firstValueFrom, merge } from 'rxjs';
 import { toArray } from 'rxjs/operators';
-import { BaseAdapter } from "./BaseAdapter.js";
-import { aggregateQuantitativeStats, calculateFeatureDensityStats, } from "./stats.js";
-import { ObservableCreate } from "../../util/rxjs.js";
-import { blankStats, scoresToStats } from "../../util/stats.js";
+import { createStatusFanOut } from '../../util/progress.js';
+import { blankStats, scoresToStats } from '../../util/stats.js';
+import { BaseAdapter } from './BaseAdapter.js';
+import { aggregateQuantitativeStats } from './stats.js';
+/**
+ * Base class for feature adapters to extend. Defines some methods that
+ * subclasses must implement.
+ */
+/** #adapterBase BaseFeatureDataAdapter | features overlapping a region — genes, reads, variants. The common case */
 export class BaseFeatureDataAdapter extends BaseAdapter {
+    /**
+     * Return "header info" that is fetched from the data file, or other info
+     * that would not simply be in the config of the file. The return value can
+     * be `{tag:string, data: any}[]` e.g. list of tags with their values which
+     * is how VCF,BAM,CRAM return values for getInfo or it can be a nested JSON
+     * object
+     */
     async getHeader(_opts) {
         return null;
     }
+    /**
+     * Return info that is primarily used for interpreting the data that is there,
+     * primarily in reference to being used for augmenting feature details panels
+     */
     async getMetadata(_opts) {
         return null;
     }
-    getFeaturesInRegion(region, opts = {}) {
-        return ObservableCreate(async (observer) => {
-            const hasData = await this.hasDataForRefName(region.refName, opts);
-            if (!hasData) {
-                observer.complete();
-            }
-            else {
-                this.getFeatures(region, opts).subscribe(observer);
-            }
-        });
-    }
+    /**
+     * Adapters that are frequently called on multiple regions simultaneously
+     * may want to implement a more efficient custom version of this method.
+     *
+     * The regions are fetched concurrently, so each gets its own
+     * {@link createStatusFanOut} slot rather than the caller's raw
+     * `statusCallback`: they all report the same phases ("Downloading
+     * features"), and sharing one status field meant the last writer won and the
+     * first region to finish cleared the label while the rest were still
+     * downloading. Aggregated, N regions read as one Σbytes bar — the same helper
+     * `callEachRegion` uses to give the per-region RPCs on the main thread a slot
+     * apiece.
+     */
     getFeaturesInMultipleRegions(regions, opts = {}) {
-        return merge(...regions.map(region => this.getFeaturesInRegion(region, opts)));
+        const slot = createStatusFanOut(opts.statusCallback);
+        return merge(...regions.map(region => this.getFeatures(region, { ...opts, statusCallback: slot() })));
+    }
+    /**
+     * Convenience wrapper that collects {@link getFeatures} for a region into an
+     * array — the common shape across RPC methods (RenderFeatureData, Manhattan,
+     * Wiggle, etc.). Pass `opts` so `statusCallback`/`stopToken` reach the
+     * adapter; omitting them means no download progress and a fetch that can't be
+     * interrupted mid-flight.
+     */
+    getFeaturesArray(region, opts = {}) {
+        return firstValueFrom(this.getFeatures(region, opts).pipe(toArray()));
+    }
+    /**
+     * {@link getFeaturesArray} across multiple regions — collects
+     * {@link getFeaturesInMultipleRegions} into an array. The common shape in
+     * matrix/comparative RPC methods (variants, synteny, dotplot, breakpoint).
+     */
+    getFeaturesInMultipleRegionsArray(regions, opts = {}) {
+        return firstValueFrom(this.getFeaturesInMultipleRegions(regions, opts).pipe(toArray()));
     }
+    /**
+     * Check if the store has data for the given reference name.
+     * @param refName - Name of the reference sequence
+     * @returns Whether data source has data for the given reference name
+     */
     async hasDataForRefName(refName, opts = {}) {
         const refNames = await this.getRefNames(opts);
         return refNames.includes(refName);
     }
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over a region, primarily used for quantitative tracks
+     */
     async getRegionQuantitativeStats(region, opts) {
         const feats = this.getFeatures(region, {
             ...opts,
@@ -36,6 +82,10 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
         });
         return scoresToStats(region, feats);
     }
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over multiple regions, primarily used for quantitative tracks
+     */
     async getMultiRegionQuantitativeStats(regions = [], opts) {
         if (!regions.length) {
             return blankStats();
@@ -43,25 +93,47 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
         const stats = await Promise.all(regions.map(region => this.getRegionQuantitativeStats(region, opts)));
         return aggregateQuantitativeStats(stats);
     }
-    getRegionFeatureDensityStats(region, opts) {
-        return calculateFeatureDensityStats(region, (region2, opts2) => this.getFeatures(region2, opts2), opts);
-    }
-    async getMultiRegionFeatureDensityStats(regions, opts) {
-        if (!regions.length) {
-            throw new Error('No regions supplied');
-        }
-        return this.getRegionFeatureDensityStats(regions[0], opts);
+    /**
+     * Cheap upper bound on the compressed bytes a fetch of `regions` would pull,
+     * derived from an index without downloading or parsing any features. The
+     * default returns `undefined` ("no cheap estimate"); indexed adapters (tabix)
+     * override it, and an adapter that caps what it returns at screen resolution
+     * (BigWig, HiC, sequence) simply doesn't — no estimate means no byte gate.
+     *
+     * The one byte-estimate entry point, used by both halves of the region-too-large
+     * gate: the pre-flight `CoreGetRegionByteEstimate` RPC and the in-fetch
+     * short-circuit in `executeRenderFeatureData`. The byte *budget* it is compared
+     * against is read on the main thread from the adapter's `fetchSizeLimit` config
+     * slot, so it never crosses the worker boundary — see
+     * agent-docs/reference/REGION_TOO_LARGE.md.
+     */
+    async getRegionByteSize(_regions, _opts) {
+        return undefined;
     }
-    async getSources(regions) {
-        const features = await firstValueFrom(this.getFeaturesInMultipleRegions(regions).pipe(toArray()));
+    async getSources(regions, opts = {}) {
+        const features = await this.getFeaturesInMultipleRegionsArray(regions, opts);
         const sources = new Set();
         for (const f of features) {
-            sources.add(f.get('source'));
+            const source = f.get('source');
+            if (source !== undefined) {
+                sources.add(source);
+            }
         }
         return [...sources].map(source => ({
             name: source,
         }));
     }
+    /**
+     * Export data from the adapter in a specified format for given regions.
+     * Some adapters (like VcfAdapter) can efficiently export raw data directly
+     * from the file without parsing to features.
+     *
+     * @param regions - Regions to export data from
+     * @param formatType - The format to export to (e.g. 'vcf', 'sam', 'bedgraph')
+     * @param opts - Feature adapter options
+     * @returns Promise resolving to the exported data as a string, or undefined
+     *          if the adapter does not support direct export for this format
+     */
     async getExportData(_regions, _formatType, _opts) {
         return undefined;
     }

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

@@ -5,6 +5,7 @@ export interface Alias {
     aliases: string[];
     override?: boolean;
 }
+/** #adapterBase BaseRefNameAliasAdapter | refName aliases, e.g. `chr1` for `1` */
 export interface BaseRefNameAliasAdapter extends BaseAdapter {
     getRefNameAliases(opts: BaseOptions): Promise<Alias[]>;
 }

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

@@ -1,11 +1,19 @@
 import { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.ts';
-import type { BaseOptions } from './types.ts';
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { NoAssemblyRegion } from '../../util/index.ts';
 import type { RegionsAdapter } from '../BaseAdapter/index.ts';
-export declare abstract class BaseSequenceAdapter extends BaseFeatureDataAdapter implements RegionsAdapter {
-    getMultiRegionFeatureDensityStats(): Promise<{
-        featureDensity: number;
-    }>;
+import type { BaseOptions } from './types.ts';
+/** #adapterBase BaseSequenceAdapter | a region list plus the sequence for a queried region; extends the feature adapter */
+export declare abstract class BaseSequenceAdapter<CONF extends AnyConfigurationModel = AnyConfigurationModel> extends BaseFeatureDataAdapter<CONF> implements RegionsAdapter {
+    /**
+     * Fetches a list of 'regions' with refName, start, and extends
+     */
     abstract getRegions(opts: BaseOptions): Promise<NoAssemblyRegion[]>;
+    /**
+     * Fetches the sequence string for a given region
+     * @param region - Region to fetch sequence for
+     * @param opts - Adapter options
+     * @returns The sequence string for the region
+     */
     getSequence(region: NoAssemblyRegion, opts?: BaseOptions): Promise<string | undefined>;
 }

package/esm/data_adapters/BaseAdapter/BaseSequenceAdapter.js

@@ -1,12 +1,14 @@
-import { firstValueFrom } from 'rxjs';
-import { toArray } from 'rxjs/operators';
-import { BaseFeatureDataAdapter } from "./BaseFeatureDataAdapter.js";
+import { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.js';
+/** #adapterBase BaseSequenceAdapter | a region list plus the sequence for a queried region; extends the feature adapter */
 export class BaseSequenceAdapter extends BaseFeatureDataAdapter {
-    async getMultiRegionFeatureDensityStats() {
-        return { featureDensity: 0 };
-    }
+    /**
+     * Fetches the sequence string for a given region
+     * @param region - Region to fetch sequence for
+     * @param opts - Adapter options
+     * @returns The sequence string for the region
+     */
     async getSequence(region, opts) {
-        const features = await firstValueFrom(this.getFeatures({ ...region, assemblyName: '' }, opts).pipe(toArray()));
+        const features = await this.getFeaturesArray({ ...region, assemblyName: '' }, opts);
         return features[0]?.get('seq');
     }
 }

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

@@ -1,6 +1,7 @@
+import type BaseResult from '../../TextSearch/BaseResults.ts';
 import type { BaseAdapter } from './BaseAdapter.ts';
 import type { BaseTextSearchArgs } from './types.ts';
-import type BaseResult from '../../TextSearch/BaseResults.ts';
+/** #adapterBase BaseTextSearchAdapter | search-box hits out of a text index */
 export interface BaseTextSearchAdapter extends BaseAdapter {
     searchIndex(args: BaseTextSearchArgs): Promise<BaseResult[]>;
 }

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

@@ -0,0 +1,7 @@
+import type { Feature } from '../../util/index.ts';
+import type { BaseAdapter } from './BaseAdapter.ts';
+import type { BaseOptions } from './types.ts';
+/** #adapterBase CytobandAdapter | cytoband features for the ideogram */
+export interface CytobandAdapter extends BaseAdapter {
+    getData(opts?: BaseOptions): Promise<Feature[]>;
+}

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

@@ -1,6 +1,7 @@
+import type { NoAssemblyRegion } from '../../util/index.ts';
 import type { BaseAdapter } from './BaseAdapter.ts';
 import type { BaseOptions } from './types.ts';
-import type { NoAssemblyRegion } from '../../util/index.ts';
+/** #adapterBase RegionsAdapter | which regions an assembly has, and how long each is */
 export interface RegionsAdapter extends BaseAdapter {
     getRegions(opts: BaseOptions): Promise<NoAssemblyRegion[]>;
 }

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

@@ -0,0 +1,2 @@
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
+export declare function getAdapterId(config: AnyConfigurationModel): string;

package/esm/data_adapters/BaseAdapter/getAdapterId.js

@@ -0,0 +1,9 @@
+import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import idMaker from '../../util/idMaker.js';
+// extracted into its own module so tests can swap it out via jest's
+// moduleNameMapper for a stable 'test' id, keeping the test detection out
+// of the production class
+export function getAdapterId(config) {
+    const data = isStateTreeNode(config) ? getSnapshot(config) : config;
+    return idMaker(data);
+}

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

@@ -1,13 +1,15 @@
-import type { AnyDataAdapter } from './util.ts';
 import type PluginManager from '../../PluginManager.ts';
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.ts';
-export * from './util.ts';
-export * from './types.ts';
+import type { AnyDataAdapter } from './util.ts';
+export { type AnyDataAdapter, isFeatureAdapter, isRefNameAliasAdapter, isRegionsAdapter, isSequenceAdapter, isTextSearchAdapter, } from './util.ts';
+export type { BaseOptions, BaseOptionsWithRegions, BaseTextSearchArgs, SearchType, } from './types.ts';
 export { BaseAdapter } from './BaseAdapter.ts';
+export { cachedSetup } from '../../util/cachedSetup.ts';
 export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.ts';
 export { BaseSequenceAdapter } from './BaseSequenceAdapter.ts';
 export type { BaseTextSearchAdapter } from './BaseTextSearchAdapter.ts';
-export type { BaseRefNameAliasAdapter } from './BaseRefNameAliasAdapter.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;

package/esm/data_adapters/BaseAdapter/index.js

@@ -1,5 +1,5 @@
-export * from "./util.js";
-export * from "./types.js";
-export { BaseAdapter } from "./BaseAdapter.js";
-export { BaseFeatureDataAdapter } from "./BaseFeatureDataAdapter.js";
-export { BaseSequenceAdapter } from "./BaseSequenceAdapter.js";
+export { isFeatureAdapter, isRefNameAliasAdapter, isRegionsAdapter, isSequenceAdapter, isTextSearchAdapter, } from './util.js';
+export { BaseAdapter } from './BaseAdapter.js';
+export { cachedSetup } from '../../util/cachedSetup.js';
+export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.js';
+export { BaseSequenceAdapter } from './BaseSequenceAdapter.js';

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

@@ -1,10 +1,10 @@
-import { type Observable } from 'rxjs';
-import type { BaseOptions } from './BaseOptions.ts';
-import type { FeatureDensityStats } from './types.ts';
 import type { Feature } from '../../util/simpleFeature.ts';
 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';
 export declare function aggregateQuantitativeStats(stats: RectifiedQuantitativeStats[]): RectifiedQuantitativeStats;
-export declare function sampleFeaturesForInterval(region: Region, interval: number, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, opts?: BaseOptions): Promise<Feature[]>;
-export declare function calculateFeatureDensityStats(region: Region, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, opts?: BaseOptions): Promise<FeatureDensityStats>;
+export declare function calculateFeatureDensityStats(region: Region, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, opts?: BaseOptions, admit?: (feature: Feature) => boolean): Promise<{
+    featureDensity: number;
+}>;
 export { blankStats } from '../../util/stats.ts';

package/esm/data_adapters/BaseAdapter/stats.js

@@ -1,7 +1,7 @@
 import { firstValueFrom } from 'rxjs';
 import { toArray } from 'rxjs/operators';
-import { max, min, sum } from "../../util/index.js";
-import { rectifyStats } from "../../util/stats.js";
+import { max, min, sum } from '../../util/index.js';
+import { rectifyStats } from '../../util/stats.js';
 const DENSITY_SAMPLE_INITIAL_INTERVAL = 1000;
 const DENSITY_SAMPLE_MIN_FEATURES = 70;
 const DENSITY_SAMPLE_TIMEOUT_MS = 5000;
@@ -13,40 +13,66 @@ export function aggregateQuantitativeStats(stats) {
         scoreMin: min(stats.map(s => s.scoreMin)),
         scoreSum: sum(stats.map(s => s.scoreSum)),
         scoreSumSquares: sum(stats.map(s => s.scoreSumSquares)),
-        featureCount: sum(stats.map(s => s.featureCount)),
+        featureCount: sum(stats.map(s => s.featureCount ?? 0)),
         basesCovered: sum(stats.map(s => s.basesCovered)),
         ...(meanMins.length > 0 ? { scoreMeanMin: min(meanMins) } : {}),
         ...(meanMaxs.length > 0 ? { scoreMeanMax: max(meanMaxs) } : {}),
     });
 }
-export function sampleFeaturesForInterval(region, interval, getFeatures, opts) {
+// 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) {
     const { start, end } = region;
     const sampleCenter = start * 0.75 + end * 0.25;
-    return firstValueFrom(getFeatures({
-        ...region,
-        start: Math.max(0, Math.round(sampleCenter - interval / 2)),
-        end: Math.min(Math.round(sampleCenter + interval / 2), end),
-    }, opts).pipe(toArray()));
+    return {
+        start: Math.max(start, Math.round(sampleCenter - interval / 2)),
+        end: Math.min(end, Math.round(sampleCenter + interval / 2)),
+    };
 }
-export async function calculateFeatureDensityStats(region, getFeatures, opts) {
+// Cheap pre-fetch density estimate: sample a small window and grow it (doubling)
+// until enough features are seen to be meaningful, then report features-per-bp
+// over the bp actually sampled. Dense regions return after one tiny fetch;
+// sparse regions expand until the window covers the whole region, bounded by a
+// wall-clock timeout. Lets a display reject an unrenderably dense region before
+// downloading the whole region's features.
+//
+// `admit` is the caller's feature-admission predicate (config filters, type
+// gates, ...). When given, the reported density counts only admitted features,
+// so a caller that filters before drawing gates on the population it will
+// actually render rather than the raw one — without it, a filtered view gets
+// rejected on features it was never going to draw.
+//
+// Note the asymmetry, and keep it: the *window growth* below tests the raw
+// count while the *density* reports the admitted count. Growing on the admitted
+// 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) {
     const refLen = region.end - region.start;
+    const t0 = performance.now();
     let interval = DENSITY_SAMPLE_INITIAL_INTERVAL;
-    let expansionTime = 0;
-    let lastTime = performance.now();
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     while (true) {
-        const features = await sampleFeaturesForInterval(region, interval, getFeatures, opts);
-        const featureCount = features.length;
-        if (featureCount >= DENSITY_SAMPLE_MIN_FEATURES || interval * 2 > refLen) {
-            return { featureDensity: featureCount / interval };
+        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;
+        // 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) {
+            return { featureDensity: admitted / sampledBp };
         }
-        if (expansionTime > DENSITY_SAMPLE_TIMEOUT_MS) {
-            console.warn("Stats estimation reached timeout, or didn't get enough features");
+        // Sparse region or slow adapter: sampling ran past the time budget without
+        // hitting the feature target. Report infinite density so the caller never
+        // gates on a timed-out estimate and lets the full fetch decide.
+        if (performance.now() - t0 > DENSITY_SAMPLE_TIMEOUT_MS) {
+            console.warn(`[calculateFeatureDensityStats] gave up sampling density after ${(performance.now() - t0).toFixed(0)}ms without reaching ${DENSITY_SAMPLE_MIN_FEATURES} features`);
             return { featureDensity: Number.POSITIVE_INFINITY };
         }
-        const currTime = performance.now();
-        expansionTime += currTime - lastTime;
-        lastTime = currTime;
         interval *= 2;
     }
 }
-export { blankStats } from "../../util/stats.js";
+export { blankStats } from '../../util/stats.js';

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

@@ -1,23 +1,25 @@
+import type { StatusCallback } from '../../util/progress.ts';
 import type { StopToken } from '../../util/stopToken.ts';
+import type { Region } from '../../util/types/index.ts';
 export interface BaseOptions {
     stopToken?: StopToken;
     bpPerPx?: number;
     sessionId?: string;
     trackInstanceId?: string;
     signal?: AbortSignal;
-    statusCallback?: (message: string) => void;
+    statusCallback?: StatusCallback;
     headers?: Record<string, string>;
+    statsEstimationMode?: boolean;
+    assemblyName?: string;
+    targetAssemblyName?: string;
+    lodMode?: 'fine' | 'coarse';
+}
+export interface BaseOptionsWithRegions extends BaseOptions {
+    regions?: Region[];
 }
 export type SearchType = 'full' | 'prefix' | 'exact';
 export interface BaseTextSearchArgs {
     queryString: string;
     searchType?: SearchType;
     stopToken?: StopToken;
-    limit?: number;
-    pageNumber?: number;
-}
-export interface FeatureDensityStats {
-    featureDensity?: number;
-    fetchSizeLimit?: number;
-    bytes?: number;
 }

package/esm/data_adapters/BaseAdapter/types.js

@@ -1 +1,2 @@
 export {};
+// #endregion

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

@@ -5,8 +5,12 @@ import type { BaseSequenceAdapter } from './BaseSequenceAdapter.ts';
 import type { BaseTextSearchAdapter } from './BaseTextSearchAdapter.ts';
 import type { RegionsAdapter } from './RegionsAdapter.ts';
 export type AnyDataAdapter = BaseAdapter | BaseFeatureDataAdapter | BaseRefNameAliasAdapter | BaseTextSearchAdapter | RegionsAdapter | BaseSequenceAdapter;
-export declare function isSequenceAdapter(t: AnyDataAdapter): t is BaseSequenceAdapter;
+export interface RefNameSource {
+    getRefNames(opts?: Record<string, unknown>): Promise<string[]>;
+}
 export declare function isRegionsAdapter(t: AnyDataAdapter): t is RegionsAdapter;
 export declare function isFeatureAdapter(t: AnyDataAdapter): t is BaseFeatureDataAdapter;
+export declare function isRefNameSource(t: AnyDataAdapter): t is AnyDataAdapter & RefNameSource;
+export declare function isSequenceAdapter(t: AnyDataAdapter): t is BaseSequenceAdapter;
 export declare function isRefNameAliasAdapter(t: object): t is BaseRefNameAliasAdapter;
 export declare function isTextSearchAdapter(t: AnyDataAdapter): t is BaseTextSearchAdapter;