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

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

@@ -1,21 +1,16 @@
 import type { StatusCallback } from '../../util/progress.ts';
 import type { StopToken } from '../../util/stopToken.ts';
-import type { Region } from '../../util/types/index.ts';
+export type LodTier = 'fine' | 'coarse';
 export interface BaseOptions {
     stopToken?: StopToken;
     bpPerPx?: number;
     sessionId?: string;
-    trackInstanceId?: string;
     signal?: AbortSignal;
     statusCallback?: StatusCallback;
     headers?: Record<string, string>;
-    statsEstimationMode?: boolean;
     assemblyName?: string;
-    targetAssemblyName?: string;
-    lodMode?: 'fine' | 'coarse';
-}
-export interface BaseOptionsWithRegions extends BaseOptions {
-    regions?: Region[];
+    lodMode?: LodTier;
+    topLevelOnly?: boolean;
 }
 export type SearchType = 'full' | 'prefix' | 'exact';
 export interface BaseTextSearchArgs {

package/esm/pluggableElementTypes/AdapterType.d.ts

@@ -42,7 +42,7 @@ export default class AdapterType extends PluggableElementBase {
      * declaring the shorthand once gets both. It used to be a second, separate
      * registration, and five in-tree adapters had only the schema half
      * (`MafTabixAdapter`, `BgzipMafAdapter`, `BgzipTaffyAdapter`,
-     * `AllVsAllPAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
+     * `MultiGenomePAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
      * because loading such a config from a URL goes through the schema. Only
      * `normalizeAdapterSnapshots` consults *this*, so what broke was `localFiles`
      * in the embedded products: the shorthand stayed unexpanded, `uri` never
@@ -63,6 +63,7 @@ export default class AdapterType extends PluggableElementBase {
         name: string;
         configSchema: AnyConfigurationSchemaType;
         displayName?: string;
+        aliases?: string[];
         adapterCapabilities?: string[];
         adapterMetadata?: AdapterMetadata;
         normalizeSnapshot?: NormalizeSnapshot;

package/esm/pluggableElementTypes/AdapterType.js

@@ -17,7 +17,7 @@ export default class AdapterType extends PluggableElementBase {
      * declaring the shorthand once gets both. It used to be a second, separate
      * registration, and five in-tree adapters had only the schema half
      * (`MafTabixAdapter`, `BgzipMafAdapter`, `BgzipTaffyAdapter`,
-     * `AllVsAllPAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
+     * `MultiGenomePAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
      * because loading such a config from a URL goes through the schema. Only
      * `normalizeAdapterSnapshots` consults *this*, so what broke was `localFiles`
      * in the embedded products: the shorthand stayed unexpanded, `uri` never

package/esm/pluggableElementTypes/DisplayType.d.ts

@@ -1,19 +1,15 @@
-import PluggableElementBase from './PluggableElementBase.ts';
+import LazyStateModelElement from './LazyStateModelElement.ts';
 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;
+export default class DisplayType extends LazyStateModelElement {
+    protected readonly group = "display";
     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,14 +20,10 @@ 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;

package/esm/pluggableElementTypes/DisplayType.js

@@ -1,17 +1,12 @@
-import PluggableElementBase from './PluggableElementBase.js';
-export default class DisplayType extends PluggableElementBase {
-    stateModel;
+import LazyStateModelElement from './LazyStateModelElement.js';
+export default class DisplayType extends LazyStateModelElement {
+    group = 'display';
     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,8 +17,6 @@ export default class DisplayType extends PluggableElementBase {
     helpText;
     constructor(stuff) {
         super(stuff);
-        this.stateModel = stuff.stateModel;
-        this.subDisplay = stuff.subDisplay;
         this.configSchema = stuff.configSchema;
         this.ReactComponent = stuff.ReactComponent;
         this.trackType = stuff.trackType;

package/esm/pluggableElementTypes/LazyStateModelElement.d.ts

@@ -0,0 +1,27 @@
+import PluggableElementBase from './PluggableElementBase.ts';
+import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
+/**
+ * A pluggable element whose state model may arrive through a dynamic import.
+ * Code that can run before any instance exists — session preloading, pruning,
+ * union membership — checks `isStateModelLoaded` before reading `stateModel`.
+ */
+export default abstract class LazyStateModelElement extends PluggableElementBase {
+    protected abstract readonly group: 'view' | 'display';
+    private loadedStateModel?;
+    private stateModelPromise?;
+    private pendingStateModelExtensions;
+    stateModelLoader?: () => Promise<IAnyModelType>;
+    onStateModelLoaded?: () => void;
+    constructor(stuff: {
+        name: string;
+        displayName?: string;
+        aliases?: string[];
+        stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
+    });
+    get stateModel(): IAnyModelType;
+    set stateModel(stateModel: IAnyModelType);
+    get isStateModelLoaded(): boolean;
+    assertStateModelLoaded(): void;
+    loadStateModel(): Promise<IAnyModelType>;
+    extendStateModel(extend: (stateModel: IAnyModelType) => IAnyModelType): void;
+}

package/esm/pluggableElementTypes/LazyStateModelElement.js

@@ -0,0 +1,71 @@
+import PluggableElementBase from './PluggableElementBase.js';
+/**
+ * A pluggable element whose state model may arrive through a dynamic import.
+ * Code that can run before any instance exists — session preloading, pruning,
+ * union membership — checks `isStateModelLoaded` before reading `stateModel`.
+ */
+export default class LazyStateModelElement extends PluggableElementBase {
+    loadedStateModel;
+    stateModelPromise;
+    pendingStateModelExtensions = [];
+    // named `stateModel` + `Loader` because pluggableMstType probes
+    // `${fieldName}Loader` generically
+    stateModelLoader;
+    // set by PluginManager.addElementType: runs Core-extendPluggableElement once
+    // the loader resolves, so a callback reading `stateModel` sees a model
+    onStateModelLoaded;
+    constructor(stuff) {
+        super(stuff);
+        if (typeof stuff.stateModel === 'function') {
+            this.stateModelLoader = stuff.stateModel;
+        }
+        else {
+            this.loadedStateModel = stuff.stateModel;
+        }
+    }
+    // Throws before the loader resolves, so a plugin composing an unloaded
+    // model fails here rather than as an opaque MST error.
+    get stateModel() {
+        this.assertStateModelLoaded();
+        return this.loadedStateModel;
+    }
+    set stateModel(stateModel) {
+        this.loadedStateModel = stateModel;
+    }
+    get isStateModelLoaded() {
+        return this.loadedStateModel !== undefined;
+    }
+    assertStateModelLoaded() {
+        if (this.loadedStateModel === undefined) {
+            const getter = this.group === 'view' ? 'getViewType' : 'getDisplayType';
+            throw new Error(`state model for ${this.group} type ${this.name} is not loaded yet — await ${getter}('${this.name}').loadStateModel() first`);
+        }
+    }
+    loadStateModel() {
+        if (this.loadedStateModel !== undefined) {
+            return Promise.resolve(this.loadedStateModel);
+        }
+        if (!this.stateModelLoader) {
+            throw new Error(`${this.group} 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;
+            this.onStateModelLoaded?.();
+            return this.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 LazyStateModelElement from './LazyStateModelElement.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';
@@ -10,21 +11,36 @@ type ViewComponentType = React.LazyExoticComponent<BasicView> | BasicView;
 interface ViewMetadata {
     hiddenFromGUI?: boolean;
 }
-export default class ViewType extends PluggableElementBase {
+export default class ViewType extends LazyStateModelElement {
+    protected readonly group = "view";
     ReactComponent: ViewComponentType;
-    stateModel: IAnyModelType;
+    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;
     addDisplayType(display: DisplayType): void;
 }
 export {};

package/esm/pluggableElementTypes/ViewType.js

@@ -1,7 +1,11 @@
-import PluggableElementBase from './PluggableElementBase.js';
-export default class ViewType extends PluggableElementBase {
+import LazyStateModelElement from './LazyStateModelElement.js';
+export default class ViewType extends LazyStateModelElement {
+    group = 'view';
     ReactComponent;
-    stateModel;
+    // 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 +20,33 @@ export default class ViewType extends PluggableElementBase {
         super(stuff);
         this.ReactComponent = stuff.ReactComponent;
         this.viewMetadata = stuff.viewMetadata ?? {};
-        this.stateModel = 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.isStateModelLoaded
+            ? this.stateModel.properties
+            : undefined;
+        return this.launchKeys && properties
+            ? [
+                ...Object.keys(properties),
+                ...Object.keys(this.launchKeys.keys),
+                ...this.launchKeys.passThrough,
+            ]
+            : undefined;
+    }
     addDisplayType(display) {
         this.displayTypes.push(display);
     }

package/esm/pluggableElementTypes/extendElementType.d.ts

@@ -5,8 +5,7 @@ import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
  * Replace a view type's state model with an extended one, e.g. to add a menu
  * item to `LinearGenomeView`. Pass an array to extend several at once, which is
  * how a contribution reaches a family: the tree spells a display family as a
- * shared mixin set rather than a chain, so there is no parent to name — see
- * `reference/REJECTED_IDEAS.md`, "Give a pluggable element an `extendsType`".
+ * shared mixin set rather than a chain, so there is no parent to name, which is why an `extendsType` was declined.
  *
  * `Core-extendPluggableElement` fires for every pluggable element there is —
  * adapters, widgets, RPC methods, all of them — so a callback written against

package/esm/pluggableElementTypes/extendElementType.js

@@ -14,8 +14,7 @@ function namesOf(name) {
  * Replace a view type's state model with an extended one, e.g. to add a menu
  * item to `LinearGenomeView`. Pass an array to extend several at once, which is
  * how a contribution reaches a family: the tree spells a display family as a
- * shared mixin set rather than a chain, so there is no parent to name — see
- * `reference/REJECTED_IDEAS.md`, "Give a pluggable element an `extendsType`".
+ * shared mixin set rather than a chain, so there is no parent to name, which is why an `extendsType` was declined.
  *
  * `Core-extendPluggableElement` fires for every pluggable element there is —
  * adapters, widgets, RPC methods, all of them — so a callback written against
@@ -45,8 +44,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 +62,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

@@ -161,7 +161,7 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
      * pointing at" channel a plugin can subscribe to.
      *
      * Declared here because a cross-display consumer can only read a name the
-     * base declares — the same reason `SyntenyFetchStateMixin.fetchInert` is a
+     * base declares — the same reason `FetchMixin.fetchInert` is a
      * hook rather than a getter each display invents. The container used to
      * read `featureUnderMouse`, which only the wiggle, alignments and
      * Manhattan families spelled that way — canvas said `hoveredFeature`,
@@ -382,7 +382,7 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
              * pointing at" channel a plugin can subscribe to.
              *
              * Declared here because a cross-display consumer can only read a name the
-             * base declares — the same reason `SyntenyFetchStateMixin.fetchInert` is a
+             * base declares — the same reason `FetchMixin.fetchInert` is a
              * hook rather than a getter each display invents. The container used to
              * read `featureUnderMouse`, which only the wiggle, alignments and
              * Manhattan families spelled that way — canvas said `hoveredFeature`,
@@ -595,7 +595,7 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
              * pointing at" channel a plugin can subscribe to.
              *
              * Declared here because a cross-display consumer can only read a name the
-             * base declares — the same reason `SyntenyFetchStateMixin.fetchInert` is a
+             * base declares — the same reason `FetchMixin.fetchInert` is a
              * hook rather than a getter each display invents. The container used to
              * read `featureUnderMouse`, which only the wiggle, alignments and
              * Manhattan families spelled that way — canvas said `hoveredFeature`,
@@ -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>;

package/esm/pluggableElementTypes/models/BaseDisplayModel.js

@@ -1,5 +1,5 @@
 import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
-import { getConf } from '../../configuration/index.js';
+import { getConf, isConfigurationSlot, preProcessSlotValues, } from '../../configuration/index.js';
 import { getContainingTrack, getEnv, statusFraction, statusMessageText, } from '../../util/index.js';
 import { ElementId } from '../../util/types/mst.js';
 /**
@@ -94,7 +94,7 @@ function stateModelFactory() {
          * pointing at" channel a plugin can subscribe to.
          *
          * Declared here because a cross-display consumer can only read a name the
-         * base declares — the same reason `SyntenyFetchStateMixin.fetchInert` is a
+         * base declares — the same reason `FetchMixin.fetchInert` is a
          * hook rather than a getter each display invents. The container used to
          * read `featureUnderMouse`, which only the wiggle, alignments and
          * Manhattan families spelled that way — canvas said `hoveredFeature`,
@@ -210,6 +210,79 @@ function stateModelFactory() {
          * base display reload does nothing, see specialized displays for details
          */
         reload() { },
+        /**
+         * #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, options) {
+            // configuration is the reference every concrete display adds at
+            // instantiation (see DisplayModel below); the base model composes
+            // before it exists, hence the cast rather than a prop
+            const { configuration } = self;
+            const applied = [];
+            const unapplied = [];
+            const failed = [];
+            const slots = preProcessSlotValues(configuration, settings);
+            for (const [key, value] of Object.entries(slots)) {
+                if (!key || key === 'type') {
+                    unapplied.push(key ? 'type (switch the display type instead)' : '(empty key)');
+                    continue;
+                }
+                try {
+                    if (isConfigurationSlot(configuration, key)) {
+                        // the key arrives from runtime JSON; setConf's slot name is a
+                        // compile-time type
+                        // eslint-disable-next-line no-restricted-syntax
+                        configuration.setSlot(key, value);
+                        applied.push(key);
+                        continue;
+                    }
+                    const setter = self[`set${key[0].toUpperCase()}${key.slice(1)}`];
+                    if (typeof setter !== 'function') {
+                        unapplied.push(key);
+                    }
+                    else if (options?.allowSetters) {
+                        ;
+                        setter(value);
+                        applied.push(`${key} (via setter)`);
+                    }
+                    else {
+                        unapplied.push(`${key} (not a config slot; a set${key[0].toUpperCase()}${key.slice(1)} action exists — call it, or pass { allowSetters: true })`);
+                    }
+                }
+                catch (e) {
+                    failed.push({ key, error: `${e}` });
+                }
+            }
+            return { applied, unapplied, failed };
+        },
     }));
 }
 export const BaseDisplay = stateModelFactory();