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

package/esm/configuration/promotableDefaults.js

@@ -24,10 +24,10 @@ import { isConfigurationModel } from './schemaTypes.js';
  * base instead reads as at-default for a track merely *following* a non-base
  * promoted default, so the reset control lights up on a no-op.
  *
- * `SLOT` is constrained the way `getConf`'s is. A pin or a reset over a slot
- * name the schema does not declare is inert and silent — `resolveSlot` answers
- * about nothing, so the control draws outline forever — and a widened `self`
- * switches the check off (`HostChecksSlotNames`).
+ * `SLOT` is constrained the way `getConf`'s is, and a widened `self` switches
+ * the check off (`HostChecksSlotNames`). A slot name the schema does not
+ * declare throws at the first read (`getSlotDefinition`), and a declared but
+ * non-promotable one throws in `resolveSlotIn`.
  */
 export function isSlotCustomized(self, slot) {
     return resolveSlot(self, slot).customized;
@@ -178,62 +178,79 @@ export function applySlotToOpenTracks(displays, slot, value) {
     }
 }
 /**
- * The pin's click. Two branches, chosen by whether this value is *already* the
- * display type's promoted default:
- *
- * - **It isn't** — write `value` into every open track of the type, and offer
- *   the promotion as a snackbar action. Applying to the tracks in front of the
- *   user is the click they mean far more often, so it is the one that needs no
- *   second click; a default outlives the tracks it was set for and governs every
- *   track of the type opened later, so it is the escalation (ADR-048).
- * - **It is** — clear it, touching no track. The open tracks hold their values
- *   because the user applied them, so reverting them here would make a toggle
- *   into a bulk discard.
+ * The pin's click: write `value` into every open track of the type, and offer
+ * the promotion as a snackbar action. Applying to the tracks in front of the
+ * user is the click they mean far more often, so it is the one that needs no
+ * second click; a default outlives the tracks it was set for and governs every
+ * track of the type opened later, so it is the escalation (ADR-048).
  *
  * The apply is one operation over *every* open track, not a labeled pair over
  * the tracks that differ and the tracks that follow. Overwriting a customized
  * track is the same write as filling in a follower, and the distinction the two
  * actions drew is not one the user has any reason to see.
  *
- * The snackbar outlives the click that raised it, so the promotion re-derives
- * `self`'s liveness inside `onClick` rather than closing over a decision —
- * ADR-048 has the ways that goes wrong.
+ * The snackbar outlives the click that raised it, so the promotion closes over
+ * the display TYPE — a string — rather than reaching back through `self`. A
+ * promoted default is keyed by display type and governs tracks opened later, so
+ * it has nothing to do with the clicked display still being open; guarding on
+ * `self` instead meant a user who applied a value, closed the track, then took
+ * the offer got a silent no-op. What is still guarded is the session, which owns
+ * the map the write lands in. ADR-048 has the decisions this does not change:
+ * no track set and no apply/promote decision may be closed over.
+ *
+ * **Promoting the slot's base value clears the default instead of storing it.**
+ * The cascade resolves the two identically, but a stored base was a third
+ * state the rest of the subsystem could see: the Preferences inventory listed a
+ * row reading "from X to X", and the base option's radio pin drew filled. Now
+ * "Set as the default" on the base row is the per-value way to undo a promoted
+ * default, and a filled pin only ever means a non-base value is promoted. The
+ * base is read here rather than at click time because it is a schema literal
+ * and cannot change.
  */
-function applyPinClick(self, slot, value, isDefault) {
+function applyAndOfferDefault(self, slot, value) {
     const session = getSession(self);
-    if (isDefault) {
-        session.setDisplayTypeDefault(self.type, slot, undefined);
-        session.notify('Cleared the default', 'info');
-    }
-    else {
-        const open = openTracksOfType(self);
-        applySlotToOpenTracks(open, slot, value);
-        session.notify(`Applied to ${open.length} open ${pluralize(open.length, 'track')}`, 'info', {
-            name: 'Set as the default',
-            onClick: () => {
-                if (isAlive(self)) {
-                    session.setDisplayTypeDefault(self.type, slot, value);
-                }
-            },
-        });
-    }
+    const displayType = self.type;
+    const { base } = resolveSlot(self, slot);
+    const promoted = deepEqual(value, base) ? undefined : value;
+    const open = openTracksOfType(self);
+    applySlotToOpenTracks(open, slot, value);
+    session.notify(`Applied to ${open.length} open ${pluralize(open.length, 'track')}`, 'info', {
+        name: 'Set as the default',
+        onClick: () => {
+            if (isAlive(session)) {
+                session.setDisplayTypeDefault(displayType, slot, promoted);
+            }
+        },
+    });
+}
+/**
+ * A value pin's click when its value is already the promoted default: clear
+ * it, touching no track. The open tracks hold their values because the user
+ * applied them, so reverting them here would make a toggle into a bulk discard.
+ */
+function clearDefault(self, slot) {
+    const session = getSession(self);
+    session.setDisplayTypeDefault(self.type, slot, undefined);
+    session.notify('Cleared the default', 'info');
 }
 /**
  * #api core/configuration
- * The pin for one promotable slot: "apply this value to every open track of this
- * display type", and — via the snackbar it raises — "keep it as the default for
- * the ones opened later".
+ * The pin on a radio or slider row: "apply this value to every open track of
+ * this display type", and — via the snackbar it raises — "keep it as the
+ * default for the ones opened later".
  *
  * `value` chooses between the subsystem's two meanings, which are otherwise
  * identical:
  *
- * - **Give it** for a per-value pin — "make *arcs* the default" — independent of
- *   what the track currently shows. Use on an always-visible pin so it can never
- *   promote a meaningless value, and so two rows sharing one slot (arcs `'arc'`
- *   vs read cloud `'cloud'`; sashimi `'down'` vs `'auto'`) stay independent.
+ * - **Give it** for a per-value pin — "make *compact* the default" —
+ *   independent of what the track currently shows. Use on an always-visible pin
+ *   so it can never promote a meaningless value, and so two rows sharing one
+ *   slot (sashimi `'down'` vs `'auto'`) stay independent.
  * - **Omit it** for "whatever I'm showing", resolved through the cascade. Use for
- *   a symmetric or continuous setting where no fixed on-value makes sense
- *   (wiggle point size, arc line width, `mismatchAlpha`).
+ *   a continuous setting where no fixed on-value makes sense (wiggle point size,
+ *   arc line width).
+ *
+ * A checkbox row takes neither: {@link makeTogglePin}.
  *
  * One function with an optional argument, rather than the two exported builders
  * it replaces — a per-value one and a `…CurrentValue…` one, the second of which
@@ -271,11 +288,63 @@ export function makePin(self, slot, ...value) {
     // same `deepEqual`, no second walk.
     const active = deepEqual(res.promoted, onValue);
     return {
+        kind: 'value',
+        slot,
+        onValue,
+        active,
+        toggle: () => {
+            if (active) {
+                clearDefault(self, slot);
+            }
+            else {
+                applyAndOfferDefault(self, slot, onValue);
+            }
+        },
+    };
+}
+/**
+ * #api core/configuration
+ * The pin on a checkbox row: the row's own checkbox, acting on every open track
+ * of the display type. `active` mirrors the row, so the pin draws filled
+ * exactly when the box is ticked; a click flips the row's state on every open
+ * track and offers the new state as the display type's default. It never
+ * clears a default the way {@link makePin}'s filled pin does — flipping back
+ * and taking the offer promotes the other value, and promoting the base value
+ * clears the default (`applyAndOfferDefault`).
+ *
+ * Replaces a symmetric `makePin(self, slot)` on these rows, which carried the
+ * row's current state: beside an unchecked box that applied *off* everywhere
+ * and visibly did nothing. It also replaces the per-value `makePin` a checkbox
+ * row over a shared enum slot used to carry, which gave two checkbox rows in
+ * one submenu two different pins: one filled when its value was promoted and
+ * clearing on a second click, the other filled when the box was ticked and
+ * flipping. With `states`, a checkbox row is always the toggle kind.
+ */
+export function makeTogglePin(self, slot, 
+// rest-tuple, like `makePin`'s value: a boolean slot may omit the states, and
+// any other slot has to name them, so the type says which without a runtime
+// check that could only fire on a schema widened to `any`
+...states) {
+    const current = resolveSlot(self, slot).value;
+    const [given] = states;
+    if (!given && typeof current !== 'boolean') {
+        throw new Error(`cannot build a toggle pin over config slot "${slot}" without naming its on/off states: it resolves to ${JSON.stringify(current)}, not a boolean`);
+    }
+    const { on, off } = given ?? { on: true, off: false };
+    for (const state of [on, off]) {
+        if (!isPromotableValue(self.configuration, slot, state)) {
+            throw new Error(`cannot toggle config slot "${slot}" to ${JSON.stringify(state)}: the cascade refuses it, so the pin could never apply it`);
+        }
+    }
+    const active = deepEqual(current, on);
+    const onValue = active ? off : on;
+    return {
+        kind: 'toggle',
         slot,
         onValue,
         active,
         toggle: () => {
-            applyPinClick(self, slot, onValue, active);
+            applyAndOfferDefault(self, slot, onValue);
         },
     };
 }
@@ -311,9 +380,9 @@ export function getDisplayTypeDefaultChanges(self) {
  *
  * **`slots` is required, and an all-slots default is not the convenience it
  * looks like.** It reaches further than any list a dialog can have shown: a
- * promoted default the track *customized* over, or one promoted to a value
- * equal to `promotedBase`, is `inherited: false` and so appears in no row, yet
- * still governs sibling tracks — so clearing it from a dialog that never showed
+ * promoted default the track *customized* over is `inherited: false` and so
+ * appears in no row, yet still governs sibling tracks — so clearing it from a
+ * dialog that never showed
  * it moves tracks other than the one whose badge was clicked. Clearing every
  * promoted default at once is a preferences-scope action, and Preferences →
  * "Reset to defaults" is where it lives (`clearPreferenceOverrides`).

package/esm/configuration/promotablePin.d.ts

@@ -1,55 +1,65 @@
 /**
- * #api core/configuration
- * The "apply this to every open track of this type" affordance on a menu row —
- * the trailing `PushPin`, bundled so the row consumes it as one prop. Built by
- * {@link makePin}.
+ * Shared by both pin kinds: which promotable slot the pin writes, whether it
+ * draws filled, and the one click it takes.
  *
- * `active` = this value is currently the session default (a filled pin), which
- * is the state, not the click. `toggle` **applies the value to every open track
- * of the display type** and raises a snackbar whose one action promotes it to
- * the display type's default; on an already-promoted value it clears that
- * default instead, touching no track (see `applyPinClick`).
+ * `slot` is here so a *built menu* can be asked which promotable slots it offers
+ * a pin for, which is the only way that question has an answer: declaring
+ * `promotedBase` is a schema fact and the pin is a menu fact, and a display that
+ * inherits the slot but never builds a row has a slot nothing can ever promote,
+ * silently (`promotableSlotsWithoutPin`, guarded by
+ * `products/jbrowse-web/src/tests/PromotablePinCoverage.test.ts`).
  *
  * **`toggle` rather than an `apply`/`clear` pair**, which was tried and dropped:
  * the sole renderer is a MUI `ToggleButton` whose `onChange` means exactly
  * "flip", so splitting it adds a member *and* a branch at the one call site that
- * never needed one. `active` is already public for a caller that wants to state a
- * direction. (The house preference for explicit setters over toggles is about MST
- * actions, where a toggle destroys the ability to set a known state; nothing here
- * stores a value.)
+ * never needed one. `active` is already public for a caller that wants to state
+ * a direction.
  *
  * Lives here, alone and with no imports, rather than beside `makePin` in
  * `promotableDefaults.ts`: the menu types describe a pin without building one,
- * and `MenuTypes.ts` taking this one interface from that module gave a
- * React-free type file a type closure of 374 files. See
- * `agent-docs/ideas/barrels-block-extraction.md` and `scripts/moduleClosure.ts`.
+ * and `MenuTypes.ts` taking this from that module gave a React-free type file a
+ * type closure of 374 files. See `agent-docs/ideas/barrels-block-extraction.md`
+ * and `scripts/moduleClosure.ts`.
  */
-export interface Pin {
-    /**
-     * The promotable slot this pin promotes a value of. Nothing in the UI reads
-     * it — a pin renders from `active`, `onValue` and the toggle. It is here so a
-     * *built menu* can be asked which promotable slots it offers a pin for, which
-     * is the only way that question has an answer: declaring `promotedBase` is a
-     * schema fact and the pin is a menu fact, and a display that inherits the slot
-     * but never builds a row has a slot nothing can ever promote, silently
-     * (`promotableSlotsWithoutPin`, guarded by
-     * `products/jbrowse-web/src/tests/PromotablePinCoverage.test.ts`).
-     */
+interface PinBase {
     slot: string;
-    /**
-     * The value `toggle` promotes — the on-value {@link makePin} was given, or the
-     * track's current resolved value for the value-omitted form.
-     *
-     * `PinAdornment` words itself from this, and has to: a **boolean** on-value
-     * promotes a *state*, so a row whose label names the setting rather than a
-     * value ("Show legend") gets a pin that promotes hiding the legend as often as
-     * showing it. Every other on-value IS what the row's label says — a radio
-     * option, a slider's current size — so those keep the value-shaped copy.
-     *
-     * Required, like `slot`: a pin that cannot say what it promotes is what let
-     * that copy state the opposite of what the click does.
-     */
+    /** what `toggle` writes into every open track of the display type */
     onValue: unknown;
     active: boolean;
     toggle: () => void;
 }
+/**
+ * #api core/configuration
+ * The pin on a radio or slider row, built by {@link makePin}: `onValue` is the
+ * row's own value, `active` means that value is the display type's promoted
+ * default, and `toggle` on an outline pin applies the value to every open track
+ * and offers it as the default, while on a filled pin it clears that default
+ * and touches no track (`applyAndOfferDefault` / `clearDefault`).
+ */
+export interface ValuePin extends PinBase {
+    kind: 'value';
+}
+/**
+ * #api core/configuration
+ * The pin on a checkbox row, built by {@link makeTogglePin}: the row's own
+ * checkbox over every open track of the display type. `active` mirrors the row,
+ * `onValue` is the state a click applies (the row's opposite), and `toggle`
+ * applies it everywhere and offers it as the default. It never clears a default
+ * on its own — promoting the slot's base value is what clears one.
+ */
+export interface TogglePin extends PinBase {
+    kind: 'toggle';
+}
+/**
+ * #api core/configuration
+ * The "apply this to every open track of this type" affordance on a menu row —
+ * the trailing `PushPin`, bundled so the row consumes it as one prop.
+ *
+ * `kind` is what the adornment words itself from and what the row builders
+ * check: a checkbox row takes a {@link TogglePin}, a radio or slider row a
+ * {@link ValuePin}. The two used to be told apart by `typeof onValue ===
+ * 'boolean'`, which let a value pin over a boolean slot compile and read as a
+ * toggle while clearing on its second click.
+ */
+export type Pin = ValuePin | TogglePin;
+export {};

package/esm/configuration/promotableResolve.d.ts

@@ -69,7 +69,7 @@ export declare function storedSlotValue(config: AnyConfigurationModel, slot: str
  * about a value a caller is about to offer as a pin's on-value.
  *
  * Exists because a pin built over a value the gate refuses is inert in a way
- * nothing reports: `applyDefaultToggle` writes it to the session store happily,
+ * nothing reports: `applyAndOfferDefault` writes it to the session store happily,
  * `resolveSlotIn` then drops it and every track keeps resolving to the tier
  * below, and `isPromotableDefault` compares the *raw* stored value, so the pin
  * draws outline forever while a dead key sits in the user's localStorage. See

package/esm/configuration/promotableResolve.js

@@ -51,7 +51,7 @@ export function storedSlotValue(config, slot) {
  * about a value a caller is about to offer as a pin's on-value.
  *
  * Exists because a pin built over a value the gate refuses is inert in a way
- * nothing reports: `applyDefaultToggle` writes it to the session store happily,
+ * nothing reports: `applyAndOfferDefault` writes it to the session store happily,
  * `resolveSlotIn` then drops it and every track keeps resolving to the tier
  * below, and `isPromotableDefault` compares the *raw* stored value, so the pin
  * draws outline forever while a dead key sits in the user's localStorage. See

package/esm/configuration/tabixIndexFields.d.ts

@@ -14,7 +14,7 @@
  *   two slots in the opposite order
  * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
  *   default said `my.paf.gz.tbi`
- * - `PlinkLDTabixAdapter` dropped the `(or .csi)` clause
+ * - `PlinkLDTabixAdapter`'s description dropped a clause the other eight carried
  * - the placeholder extensions disagreed with each other for no reason
  *
  * The description is written for every tabix adapter rather than naming one
@@ -39,6 +39,6 @@ export declare const tabixIndexFields: {
             readonly uri: '/path/to/my.gz.tbi';
             readonly locationType: 'UriLocation';
         };
-        readonly description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.';
+        readonly description: 'location of the tabix index. Only needed when it is not named `<file>.tbi`, which is what the `uri` shorthand assumes — a `.csi` beside the file is reached with `csi: true` rather than by spelling this out.';
     };
 };

package/esm/configuration/tabixIndexFields.js

@@ -15,7 +15,7 @@ import { types } from '@jbrowse/mobx-state-tree';
  *   two slots in the opposite order
  * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
  *   default said `my.paf.gz.tbi`
- * - `PlinkLDTabixAdapter` dropped the `(or .csi)` clause
+ * - `PlinkLDTabixAdapter`'s description dropped a clause the other eight carried
  * - the placeholder extensions disagreed with each other for no reason
  *
  * The description is written for every tabix adapter rather than naming one
@@ -40,6 +40,6 @@ export const tabixIndexFields = {
             uri: '/path/to/my.gz.tbi',
             locationType: 'UriLocation',
         },
-        description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.',
+        description: 'location of the tabix index. Only needed when it is not named `<file>.tbi`, which is what the `uri` shorthand assumes — a `.csi` beside the file is reached with `csi: true` rather than by spelling this out.',
     },
 };

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

@@ -2,6 +2,7 @@ import { BaseAdapter } from './BaseAdapter.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';
+import type { FeatureDensity } from './featureDensity.ts';
 import type { BaseOptions } from './types.ts';
 import type { Observable } from 'rxjs';
 /**
@@ -117,6 +118,17 @@ export declare abstract class BaseFeatureDataAdapter<CONF extends AnyConfigurati
      * 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;

package/esm/data_adapters/BaseAdapter/BaseFeatureDataAdapter.js

@@ -3,7 +3,9 @@ import { toArray } from 'rxjs/operators';
 import { createStatusFanOut } from '../../util/progress.js';
 import { blankStats, scoresToStats } from '../../util/stats.js';
 import { BaseAdapter } from './BaseAdapter.js';
+import { isSubAdapterConfig } from './featureDensity.js';
 import { aggregateQuantitativeStats } from './stats.js';
+import { isFeatureAdapter } from './util.js';
 /**
  * Base class for feature adapters to extend. Defines some methods that
  * subclasses must implement.
@@ -76,10 +78,7 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
      * features over a region, primarily used for quantitative tracks
      */
     async getRegionQuantitativeStats(region, opts) {
-        const feats = this.getFeatures(region, {
-            ...opts,
-            statsEstimationMode: true,
-        });
+        const feats = this.getFeatures(region, opts);
         return scoresToStats(region, feats);
     }
     /**
@@ -110,6 +109,38 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
     async getRegionByteSize(_regions, _opts) {
         return 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.
+     */
+    async getFeatureDensity(regions, opts) {
+        const sidecar = this.getConf(['densityAdapter']);
+        const resolved = isSubAdapterConfig(sidecar) && this.getSubAdapter
+            ? (await this.getSubAdapter(sidecar)).dataAdapter
+            : undefined;
+        if (resolved && !isFeatureAdapter(resolved)) {
+            throw new Error(`densityAdapter ${isSubAdapterConfig(sidecar) ? sidecar.type : ''} is not a feature adapter`);
+        }
+        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, opts = {}) {
         const features = await this.getFeaturesInMultipleRegionsArray(regions, opts);
         const sources = new Set();

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

@@ -0,0 +1,41 @@
+/**
+ * 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';
+    };
+};
+/**
+ * Whether the `densityAdapter` slot holds something a sub-adapter can be built
+ * from. Beside the slot because both ends of the tier ask it and they have to
+ * agree: the display, deciding the band stands in, and `getFeatureDensity`,
+ * resolving the sidecar. They disagreed — the display took any object, the
+ * adapter wanted a type — so the shorthand every location slot accepts
+ * (`{ uri }`) turned the band on for a read that answered `undefined`, which
+ * commits nothing, and the phase then waited on bins no read would ever bring.
+ */
+export declare function isSubAdapterConfig(value: unknown): value is Record<string, unknown> & {
+    type: string;
+};

package/esm/data_adapters/BaseAdapter/featureDensity.js

@@ -0,0 +1,32 @@
+/**
+ * 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',
+    },
+};
+/**
+ * Whether the `densityAdapter` slot holds something a sub-adapter can be built
+ * from. Beside the slot because both ends of the tier ask it and they have to
+ * agree: the display, deciding the band stands in, and `getFeatureDensity`,
+ * resolving the sidecar. They disagreed — the display took any object, the
+ * adapter wanted a type — so the shorthand every location slot accepts
+ * (`{ uri }`) turned the band on for a read that answered `undefined`, which
+ * commits nothing, and the phase then waited on bins no read would ever bring.
+ */
+export function isSubAdapterConfig(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        typeof value.type === 'string');
+}

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

@@ -3,10 +3,11 @@ import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.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 type { BaseOptions, BaseTextSearchArgs, LodTier, SearchType, } from './types.ts';
 export { BaseAdapter } from './BaseAdapter.ts';
 export { cachedSetup } from '../../util/cachedSetup.ts';
 export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.ts';
+export { type FeatureDensity, densityAdapterConfigSchemaFields, isSubAdapterConfig, } from './featureDensity.ts';
 export { BaseSequenceAdapter } from './BaseSequenceAdapter.ts';
 export type { BaseTextSearchAdapter } from './BaseTextSearchAdapter.ts';
 export type { Alias, BaseRefNameAliasAdapter, } from './BaseRefNameAliasAdapter.ts';

package/esm/data_adapters/BaseAdapter/index.js

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

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

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