@jbrowse/core 4.3.0 → 5.0.0-beta.2

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

@@ -1,24 +1,149 @@
-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 { FeatureDensity } from './featureDensity.ts';
+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>;
+    /**
+     * Features per bin over each region, at the view's `bpPerPx`, for the density
+     * tier the display draws where the region-too-large gate refused the
+     * features. The default reads the `densityAdapter` sidecar slot
+     * (`densityAdapterConfigSchemaFields`) through `getSubAdapter`; `undefined`
+     * means no tier, and the banner stands. ADR-102 records why no index
+     * estimate stands in for a missing sidecar.
+     */
+    getFeatureDensity(regions: Region[], opts: BaseOptions & {
+        bpPerPx: number;
+    }): Promise<FeatureDensity[] | 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,87 @@
 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';
+import { isFeatureAdapter } from './util.js';
+function isAdapterConfigSnapshot(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        typeof value.type === 'string');
+}
+/**
+ * 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 +89,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 +100,79 @@ 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);
+    /**
+     * 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 getMultiRegionFeatureDensityStats(regions, opts) {
-        if (!regions.length) {
-            throw new Error('No regions supplied');
+    /**
+     * Features per bin over each region, at the view's `bpPerPx`, for the density
+     * tier the display draws where the region-too-large gate refused the
+     * features. The default reads the `densityAdapter` sidecar slot
+     * (`densityAdapterConfigSchemaFields`) through `getSubAdapter`; `undefined`
+     * means no tier, and the banner stands. ADR-102 records why no index
+     * estimate stands in for a missing sidecar.
+     */
+    async getFeatureDensity(regions, opts) {
+        const sidecar = this.getConf(['densityAdapter']);
+        const resolved = isAdapterConfigSnapshot(sidecar) && this.getSubAdapter
+            ? (await this.getSubAdapter(sidecar)).dataAdapter
+            : undefined;
+        if (resolved && !isFeatureAdapter(resolved)) {
+            throw new Error(`densityAdapter ${isAdapterConfigSnapshot(sidecar) ? sidecar.type : ''} is not a feature adapter`);
         }
-        return this.getRegionFeatureDensityStats(regions[0], opts);
+        return resolved
+            ? Promise.all(regions.map(async (region) => {
+                const features = await resolved.getFeaturesArray(region, opts);
+                const starts = new Uint32Array(features.length);
+                const ends = new Uint32Array(features.length);
+                const scores = new Float32Array(features.length);
+                features.forEach((feature, i) => {
+                    const score = feature.get('score');
+                    starts[i] = feature.get('start');
+                    ends[i] = feature.get('end');
+                    scores[i] = score === undefined ? 0 : score;
+                });
+                return { starts, ends, scores };
+            }))
+            : 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/featureDensity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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: 'frozen';
+        readonly defaultValue: null;
+        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; null disables it';
+    };
+};

package/esm/data_adapters/BaseAdapter/featureDensity.js

@@ -0,0 +1,17 @@
+/**
+ * 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: 'frozen',
+        defaultValue: null,
+        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; null disables it',
+    },
+};

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,16 @@
-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 { type FeatureDensity, densityAdapterConfigSchemaFields, } from './featureDensity.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,6 @@
-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 { densityAdapterConfigSchemaFields, } from './featureDensity.js';
+export { BaseSequenceAdapter } from './BaseSequenceAdapter.js';

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

@@ -1,10 +1,42 @@
-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';
+/**
+ * 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 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>, { admit, gate, ...opts }?: DensityProbeOptions): Promise<{
+    featureDensity: number;
+}>;
 export { blankStats } from '../../util/stats.ts';