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

package/esm/data_adapters/BaseAdapter/BaseFeatureDataAdapter.js

@@ -4,6 +4,13 @@ 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.
@@ -110,6 +117,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 = 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 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,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/index.d.ts

@@ -7,6 +7,7 @@ export type { BaseOptions, BaseOptionsWithRegions, BaseTextSearchArgs, SearchTyp
 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 { 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, } 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';

package/esm/data_adapters/BaseAdapter/stats.js

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

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

@@ -13,6 +13,7 @@ export interface BaseOptions {
     assemblyName?: string;
     targetAssemblyName?: string;
     lodMode?: 'fine' | 'coarse';
+    topLevelOnly?: boolean;
 }
 export interface BaseOptionsWithRegions extends BaseOptions {
     regions?: Region[];

package/esm/pluggableElementTypes/DisplayType.d.ts

@@ -3,17 +3,17 @@ import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
 import type { AnyReactComponentType } from '../util/index.ts';
 import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
 export default class DisplayType extends PluggableElementBase {
-    stateModel: IAnyModelType;
+    private loadedStateModel?;
+    get stateModel(): IAnyModelType;
+    stateModelLoader?: () => Promise<IAnyModelType>;
+    private stateModelPromise?;
+    private pendingStateModelExtensions;
     configSchema: AnyConfigurationSchemaType;
     ReactComponent: AnyReactComponentType;
     /**
      * The track type the display is associated with
      */
     trackType: string;
-    subDisplay?: {
-        type: string;
-        [key: string]: unknown;
-    };
     /**
      * The view type the display is associated with
      */
@@ -24,17 +24,16 @@ export default class DisplayType extends PluggableElementBase {
     helpText?: string;
     constructor(stuff: {
         name: string;
-        stateModel: IAnyModelType;
+        stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
         trackType: string;
         viewType: string;
         displayName?: string;
-        subDisplay?: {
-            type: string;
-            [key: string]: unknown;
-        };
         configSchema: AnyConfigurationSchemaType;
         ReactComponent: AnyReactComponentType;
         helpText?: string;
         aliases?: string[];
     });
+    get isStateModelLoaded(): boolean;
+    loadStateModel(): Promise<IAnyModelType>;
+    extendStateModel(extend: (stateModel: IAnyModelType) => IAnyModelType): void;
 }

package/esm/pluggableElementTypes/DisplayType.js

@@ -1,17 +1,19 @@
 import PluggableElementBase from './PluggableElementBase.js';
 export default class DisplayType extends PluggableElementBase {
-    stateModel;
+    loadedStateModel;
+    // same contract as ViewType.stateModel
+    get stateModel() {
+        return this.loadedStateModel;
+    }
+    stateModelLoader;
+    stateModelPromise;
+    pendingStateModelExtensions = [];
     configSchema;
     ReactComponent;
     /**
      * The track type the display is associated with
      */
     trackType;
-    /*
-     * Indicates that this display type can be a "sub-display" of another type of
-     * display, e.g. in AlignmentsDisplay, has Pileup and SNPCoverage subDisplays
-     */
-    subDisplay;
     /**
      * The view type the display is associated with
      */
@@ -22,12 +24,45 @@ export default class DisplayType extends PluggableElementBase {
     helpText;
     constructor(stuff) {
         super(stuff);
-        this.stateModel = stuff.stateModel;
-        this.subDisplay = stuff.subDisplay;
+        if (typeof stuff.stateModel === 'function') {
+            this.stateModelLoader = stuff.stateModel;
+        }
+        else {
+            this.loadedStateModel = stuff.stateModel;
+        }
         this.configSchema = stuff.configSchema;
         this.ReactComponent = stuff.ReactComponent;
         this.trackType = stuff.trackType;
         this.viewType = stuff.viewType;
         this.helpText = stuff.helpText;
     }
+    get isStateModelLoaded() {
+        return this.loadedStateModel !== undefined;
+    }
+    loadStateModel() {
+        if (this.loadedStateModel !== undefined) {
+            return Promise.resolve(this.loadedStateModel);
+        }
+        if (!this.stateModelLoader) {
+            throw new Error(`display type ${this.name} has neither a state model nor a loader`);
+        }
+        this.stateModelPromise ??= this.stateModelLoader().then(loaded => {
+            let stateModel = loaded;
+            for (const extend of this.pendingStateModelExtensions) {
+                stateModel = extend(stateModel);
+            }
+            this.pendingStateModelExtensions = [];
+            this.loadedStateModel = stateModel;
+            return stateModel;
+        });
+        return this.stateModelPromise;
+    }
+    extendStateModel(extend) {
+        if (this.loadedStateModel !== undefined) {
+            this.loadedStateModel = extend(this.loadedStateModel);
+        }
+        else {
+            this.pendingStateModelExtensions.push(extend);
+        }
+    }
 }

package/esm/pluggableElementTypes/ViewType.d.ts

@@ -1,4 +1,5 @@
 import PluggableElementBase from './PluggableElementBase.ts';
+import type { LaunchKeyRegistration } from '../util/withLaunchInput.ts';
 import type DisplayType from './DisplayType.ts';
 import type { IAnyModelType, IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
 import type React from 'react';
@@ -12,19 +13,41 @@ interface ViewMetadata {
 }
 export default class ViewType extends PluggableElementBase {
     ReactComponent: ViewComponentType;
-    stateModel: IAnyModelType;
+    private loadedStateModel?;
+    get stateModel(): IAnyModelType;
+    stateModelLoader?: () => Promise<IAnyModelType>;
+    private stateModelPromise?;
+    private pendingStateModelExtensions;
+    launchKeys?: LaunchKeyRegistration<unknown, string>;
     displayTypes: DisplayType[];
     viewMetadata: ViewMetadata;
     extendedName?: string;
     constructor(stuff: {
         name: string;
         displayName?: string;
-        stateModel: IAnyModelType;
+        stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
+        launchKeys?: LaunchKeyRegistration<unknown, string>;
         extendedName?: string;
         viewMetadata?: ViewMetadata;
         ReactComponent: ViewComponentType;
         aliases?: string[];
     });
+    /**
+     * Every key this view accepts written on the view object — its declared MST
+     * properties plus the launch keys above. `undefined` for a view that
+     * registers none: nothing there says which of its launcher's arguments are
+     * settings, so a caller must classify nothing rather than call them all typos.
+     * Also `undefined` while a lazily registered state model is not loaded yet,
+     * for the same reason: nothing is known, so nothing is a typo.
+     *
+     * This is the set `withLaunchInput`'s partition reads off the same two
+     * declarations, published for the surfaces that never build a view snapshot —
+     * a session spec launches straight through `LaunchView-<type>`.
+     */
+    get acceptedKeys(): string[] | undefined;
+    get isStateModelLoaded(): boolean;
+    loadStateModel(): Promise<IAnyModelType>;
+    extendStateModel(extend: (stateModel: IAnyModelType) => IAnyModelType): void;
     addDisplayType(display: DisplayType): void;
 }
 export {};

package/esm/pluggableElementTypes/ViewType.js

@@ -1,7 +1,23 @@
 import PluggableElementBase from './PluggableElementBase.js';
 export default class ViewType extends PluggableElementBase {
     ReactComponent;
-    stateModel;
+    loadedStateModel;
+    // Non-optional because nearly every reader holds a view instance, which
+    // implies the model is loaded; code that can run before any instance exists
+    // (session preloading, pruning, union membership) must check
+    // isStateModelLoaded first.
+    get stateModel() {
+        return this.loadedStateModel;
+    }
+    // named `stateModel` + `Loader` because pluggableMstType and
+    // pruneUnbuildableNodes probe `${fieldName}Loader` generically
+    stateModelLoader;
+    stateModelPromise;
+    pendingStateModelExtensions = [];
+    // What `withLaunchInput` partitioned out of this view's snapshots, published
+    // beside the model so an out-of-tree plugin, the doc generator and the
+    // validator read one declaration rather than each keeping a list.
+    launchKeys;
     displayTypes = [];
     viewMetadata = {};
     // extendedName can be used for when you extend a given view type, and want
@@ -16,9 +32,66 @@ export default class ViewType extends PluggableElementBase {
         super(stuff);
         this.ReactComponent = stuff.ReactComponent;
         this.viewMetadata = stuff.viewMetadata ?? {};
-        this.stateModel = stuff.stateModel;
+        if (typeof stuff.stateModel === 'function') {
+            this.stateModelLoader = stuff.stateModel;
+        }
+        else {
+            this.loadedStateModel = stuff.stateModel;
+        }
+        this.launchKeys = stuff.launchKeys;
         this.extendedName = stuff.extendedName;
     }
+    /**
+     * Every key this view accepts written on the view object — its declared MST
+     * properties plus the launch keys above. `undefined` for a view that
+     * registers none: nothing there says which of its launcher's arguments are
+     * settings, so a caller must classify nothing rather than call them all typos.
+     * Also `undefined` while a lazily registered state model is not loaded yet,
+     * for the same reason: nothing is known, so nothing is a typo.
+     *
+     * This is the set `withLaunchInput`'s partition reads off the same two
+     * declarations, published for the surfaces that never build a view snapshot —
+     * a session spec launches straight through `LaunchView-<type>`.
+     */
+    get acceptedKeys() {
+        const properties = this.loadedStateModel?.properties;
+        return this.launchKeys && properties
+            ? [
+                ...Object.keys(properties),
+                ...Object.keys(this.launchKeys.keys),
+                ...this.launchKeys.passThrough,
+            ]
+            : undefined;
+    }
+    get isStateModelLoaded() {
+        return this.loadedStateModel !== undefined;
+    }
+    loadStateModel() {
+        if (this.loadedStateModel !== undefined) {
+            return Promise.resolve(this.loadedStateModel);
+        }
+        if (!this.stateModelLoader) {
+            throw new Error(`view type ${this.name} has neither a state model nor a loader`);
+        }
+        this.stateModelPromise ??= this.stateModelLoader().then(loaded => {
+            let stateModel = loaded;
+            for (const extend of this.pendingStateModelExtensions) {
+                stateModel = extend(stateModel);
+            }
+            this.pendingStateModelExtensions = [];
+            this.loadedStateModel = stateModel;
+            return stateModel;
+        });
+        return this.stateModelPromise;
+    }
+    extendStateModel(extend) {
+        if (this.loadedStateModel !== undefined) {
+            this.loadedStateModel = extend(this.loadedStateModel);
+        }
+        else {
+            this.pendingStateModelExtensions.push(extend);
+        }
+    }
     addDisplayType(display) {
         this.displayTypes.push(display);
     }

package/esm/pluggableElementTypes/extendElementType.js

@@ -45,8 +45,12 @@ export function extendViewType(pluginManager, name, extend) {
             // point of the signature; widening it once here costs nothing, since
             // the only operation is handing the model to `extend` and storing what
             // comes back.
+            //
+            // Routed through extendStateModel rather than assigning `.stateModel`
+            // directly so a view registered with a lazy loader queues the
+            // extension and composes it when the loader resolves.
             const view = element;
-            view.stateModel = widen(extend)(view.stateModel);
+            view.extendStateModel(widen(extend));
         }
         return element;
     });
@@ -59,9 +63,10 @@ export function extendDisplayType(pluginManager, name, extend) {
     const names = namesOf(name);
     pluginManager.addToExtensionPoint('Core-extendPluggableElement', (element, props) => {
         if (props.group === 'display' && names.has(element.name)) {
-            // widened for the reason in extendViewType
+            // widened for the reason in extendViewType; routed through
+            // extendStateModel so a lazy registration queues the extension
             const display = element;
-            display.stateModel = widen(extend)(display.stateModel);
+            display.extendStateModel(widen(extend));
         }
         return element;
     });

package/esm/pluggableElementTypes/models/BaseDisplayModel.d.ts

@@ -684,6 +684,47 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
      * base display reload does nothing, see specialized displays for details
      */
     reload(): void;
+    /**
+     * #action
+     * Apply a bag of display settings to the LIVE display, and report what
+     * landed. Each key runs through the display config schema's
+     * `preProcessSnapshot` (shorthand expansions, legacy-key migrations —
+     * the same lowering a session spec's inline track keys get in
+     * `showTrackGeneric`), then writes the matching config slot. Keys that
+     * are not slots come back in `unapplied` rather than vanishing: the
+     * settings vocabulary's historical failure mode is the silently dropped
+     * key.
+     *
+     * `allowSetters` additionally routes a non-slot key to a conventionally
+     * named single-argument `set<Key>` action. Opt-in, never the default:
+     * the declarative surfaces (session specs, share links, embeds) feed
+     * this whole bags of untyped JSON, and a blanket fallback would let
+     * them reach internal setters (`setError`, `setScrollTop`, ...) and
+     * call multi-argument setters with one argument. A caller that wants a
+     * specific action can also simply call it.
+     *
+     * A key whose write THREW is reported separately, in `failed` — it is the
+     * only one of the three that means the caller got something wrong, and
+     * the only one worth a notification. `unapplied` is not: at the
+     * `showTrackGeneric` call site it also collects keys that surface
+     * consumed itself (`type`) and MST display props the display snapshot
+     * already applied (`resolution`), so treating it as "dropped" would
+     * report a correct call as broken.
+     *
+     * Per-key errors do not abort the rest of the bag — a caller
+     * mid-`showTrack` has already pushed the track, and one rejected value
+     * must not strand a half-configured track.
+     */
+    applyDisplaySettings(settings: Record<string, unknown>, options?: {
+        allowSetters?: boolean;
+    }): {
+        applied: string[];
+        unapplied: string[];
+        failed: {
+            key: string;
+            error: string;
+        }[];
+    };
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type BaseDisplayStateModel = typeof BaseDisplay;
 export type BaseDisplayModel = Instance<BaseDisplayStateModel>;