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

package/esm/pluggableElementTypes/RpcMethodTypeWithFiltersAndRenameRegions.d.ts

@@ -2,7 +2,6 @@ import RpcMethodTypeWithRenameRegions from './RpcMethodTypeWithRenameRegions.ts'
 import SerializableFilterChain from './renderers/util/serializableFilterChain.ts';
 import type { Region } from '../util/index.ts';
 import type { StatusCallback } from '../util/progress.ts';
-import type { StopToken } from '../util/stopToken.ts';
 interface FilterRenameArgs {
     sessionId: string;
     regions?: Region[];
@@ -14,7 +13,7 @@ export default abstract class RpcMethodTypeWithFiltersAndRenameRegions<MethodNam
         filters?: unknown;
     }): Promise<T>;
     serializeArguments(args: FilterRenameArgs & {
-        stopToken?: StopToken;
+        signal?: AbortSignal;
         statusCallback?: StatusCallback;
     }): Promise<Record<string, unknown>>;
 }

package/esm/pluggableElementTypes/TextSearchAdapterType.d.ts

@@ -1,18 +1,18 @@
 import PluggableElementBase from './PluggableElementBase.ts';
 import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
-import type { AnyAdapter } from '../data_adapters/BaseAdapter/index.ts';
-export default class TextSearchAdapterType extends PluggableElementBase {
-    getAdapterClass: () => Promise<AnyAdapter>;
-    configSchema: AnyConfigurationSchemaType;
+import type { AdapterClassFor } from '../data_adapters/BaseAdapter/index.ts';
+export default class TextSearchAdapterType<SCHEMA extends AnyConfigurationSchemaType = any> extends PluggableElementBase {
+    getAdapterClass: () => Promise<AdapterClassFor<SCHEMA>>;
+    configSchema: SCHEMA;
     description?: string;
     constructor(stuff: {
         name: string;
-        configSchema: AnyConfigurationSchemaType;
+        configSchema: SCHEMA;
         displayName?: string;
         description?: string;
     } & ({
-        getAdapterClass: () => Promise<AnyAdapter>;
+        getAdapterClass: () => Promise<AdapterClassFor<SCHEMA>>;
     } | {
-        AdapterClass: AnyAdapter;
+        AdapterClass: AdapterClassFor<SCHEMA>;
     }));
 }

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/addMenuItems.d.ts

@@ -12,9 +12,10 @@ type ModelOf<T> = T extends IAnyType ? Instance<T> : never;
 /**
  * The methods on a model that return a menu. Derived from the model rather than
  * listed, which is what makes a renamed or retired method a compile error at
- * the call site: there are six of them across views and displays (`menuItems`,
+ * the call site: there are seven of them across views and displays (`menuItems`,
  * `trackMenuItems`, `contextMenuItems`, `rubberBandMenuItems`,
- * `rubberBandLaunchMenuItems`, `highlightMenuItems`), they are a convention
+ * `rubberBandLaunchMenuItems`, `highlightMenuItems`, `highlightsSubMenuItems`),
+ * they are a convention
  * rather than one declared interface, and a contribution to a name the model no
  * longer has is otherwise silent.
  *

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/index.d.ts

@@ -8,7 +8,7 @@ import type TextSearchAdapterType from './TextSearchAdapterType.ts';
 import type TrackType from './TrackType.ts';
 import type ViewType from './ViewType.ts';
 import type WidgetType from './WidgetType.ts';
-export { BaseConnectionModelFactory, BaseDisplay, type BaseDisplayModel, type BaseDisplayStateModel, BaseInternetAccountConfig, type BaseInternetAccountModel, type BaseInternetAccountStateModel, type BaseTrackConfig, type BaseTrackModel, type BaseTrackStateModel, BaseViewModel, type DisplayModel, type FileTypeExporter, HighlightsMixin, type IBaseViewModel, InternetAccount, addDisplayConfigMigration, baseConnectionConfig, createBaseTrackConfig, createBaseTrackModel, preprocessTrackConfigSnapshot, type TrackConfigSnapshot, trackConfigActions, } from './models/index.ts';
+export { BaseConnectionModelFactory, BaseDisplay, type BaseDisplayModel, type BaseDisplayStateModel, BaseInternetAccountConfig, type BaseInternetAccountModel, type BaseInternetAccountStateModel, type BaseTrackConfig, type BaseTrackModel, type BaseTrackStateModel, BaseViewModel, type DisplayModel, type FileTypeExporter, type IBaseViewModel, InternetAccount, baseConnectionConfig, createBaseTrackConfig, createBaseTrackModel, preprocessTrackConfigSnapshot, type TrackConfigSnapshot, } from './models/index.ts';
 export type PluggableElementType = AdapterType | ConnectionType | WidgetType | TrackType | DisplayType | ViewType | RpcMethodType | InternetAccountType | TextSearchAdapterType | AddTrackWorkflowType;
 export { extendDisplayType, extendViewType } from './extendElementType.ts';
 export { addDisplayMenuItems, addViewMenuItems } from './addMenuItems.ts';
@@ -18,6 +18,7 @@ export { default as TrackType } from './TrackType.ts';
 export { default as WidgetType } from './WidgetType.ts';
 export { default as ViewType } from './ViewType.ts';
 export { default as DisplayType } from './DisplayType.ts';
+export type { DisplayEntry, RetiredDisplayState, RetiredDisplayType, } from './DisplayType.ts';
 export { default as InternetAccountType } from './InternetAccountType.ts';
 export { default as RpcMethodType } from './RpcMethodType.ts';
 export { default as RpcMethodTypeWithRenameRegion } from './RpcMethodTypeWithRenameRegion.ts';

package/esm/pluggableElementTypes/index.js

@@ -1,4 +1,4 @@
-export { BaseConnectionModelFactory, BaseDisplay, BaseInternetAccountConfig, BaseViewModel, HighlightsMixin, InternetAccount, addDisplayConfigMigration, baseConnectionConfig, createBaseTrackConfig, createBaseTrackModel, preprocessTrackConfigSnapshot, trackConfigActions, } from './models/index.js';
+export { BaseConnectionModelFactory, BaseDisplay, BaseInternetAccountConfig, BaseViewModel, InternetAccount, baseConnectionConfig, createBaseTrackConfig, createBaseTrackModel, preprocessTrackConfigSnapshot, } from './models/index.js';
 export { extendDisplayType, extendViewType } from './extendElementType.js';
 export { addDisplayMenuItems, addViewMenuItems } from './addMenuItems.js';
 export { default as AdapterType } from './AdapterType.js';

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

@@ -8,22 +8,32 @@ declare function stateModelFactory(pluginManager: PluginManager): import("@jbrow
     /**
      * #property
      */
-    tracks: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    tracks: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/core/PluginManager").PluggableConfigSchemaType>;
     /**
      * #property
      */
     configuration: import("../../configuration/configurationSchema.ts").IConfigurationReference<import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
         readonly name: {
-            readonly type: "string";
-            readonly defaultValue: "nameOfConnection";
-            readonly description: "a unique name for this connection";
+            type: "string";
+        } & {
+            defaultValue: string;
         };
         readonly assemblyNames: {
-            readonly type: "stringArray";
-            readonly defaultValue: readonly [];
-            readonly description: "optional list of names of assemblies in this connection";
+            type: "stringArray";
+        } & {
+            defaultValue: unknown;
         };
-    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "connectionId">>>;
+        type: {
+            type: "string";
+        } & {
+            defaultValue: string;
+        };
+        connectionId: {
+            type: "string";
+        } & {
+            defaultValue: string;
+        };
+    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "connectionId", true, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>>;
     /**
      * #property
      * set when the connection is being re-established on session load (its
@@ -70,7 +80,7 @@ declare function stateModelFactory(pluginManager: PluginManager): import("@jbrow
     /**
      * #action
      */
-    addTrackConf(trackConf: TrackConf): any;
+    addTrackConf(trackConf: TrackConf): (import("../../configuration/types.ts").PluggableConfigNode & import("@jbrowse/mobx-state-tree").IStateTreeNode<import("@jbrowse/core/PluginManager").PluggableConfigSchemaType>) | undefined;
     /**
      * #action
      */

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

@@ -1,6 +1,7 @@
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { MenuItem } from '../../ui/index.ts';
 import type { RpcStatus } from '../../util/progress.ts';
+import type { UnappliedSetting } from '../../util/unknownSnapshotKeys.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
 import type React from 'react';
 export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<{
@@ -161,7 +162,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`,
@@ -202,15 +203,14 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
     readonly featureNoun: string;
     /**
      * #getter
-     * Overridable hook: which widget `openFeatureWidget` opens for one of
-     * this display's features. The default is the generic one, which is what
-     * a display drawing plain features wants and what the canvas base spelled
-     * out by hand.
+     * The widget `openFeatureWidget` opens for one of this display's
+     * features. Displays may override it. The default is the generic feature
+     * widget, for displays drawing plain features.
      *
-     * An override is a display whose features have a vocabulary of their own —
-     * a read, a variant, a synteny block — and the `id` is deliberately part
-     * of it: two displays naming one id share the drawer panel, which is the
-     * behaviour when the two are showing the same kind of thing.
+     * Displays whose features are a specific kind (a read, a variant, a
+     * synteny block) override it, including the `id`: two displays naming
+     * one id share the drawer panel, which suits two displays showing the
+     * same kind of feature.
      */
     readonly featureWidgetType: {
         type: string;
@@ -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`,
@@ -423,15 +423,14 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
             readonly featureNoun: string;
             /**
              * #getter
-             * Overridable hook: which widget `openFeatureWidget` opens for one of
-             * this display's features. The default is the generic one, which is what
-             * a display drawing plain features wants and what the canvas base spelled
-             * out by hand.
+             * The widget `openFeatureWidget` opens for one of this display's
+             * features. Displays may override it. The default is the generic feature
+             * widget, for displays drawing plain features.
              *
-             * An override is a display whose features have a vocabulary of their own —
-             * a read, a variant, a synteny block — and the `id` is deliberately part
-             * of it: two displays naming one id share the drawer panel, which is the
-             * behaviour when the two are showing the same kind of thing.
+             * Displays whose features are a specific kind (a read, a variant, a
+             * synteny block) override it, including the `id`: two displays naming
+             * one id share the drawer panel, which suits two displays showing the
+             * same kind of feature.
              */
             readonly featureWidgetType: {
                 type: string;
@@ -595,7 +594,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`,
@@ -636,15 +635,14 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
             readonly featureNoun: string;
             /**
              * #getter
-             * Overridable hook: which widget `openFeatureWidget` opens for one of
-             * this display's features. The default is the generic one, which is what
-             * a display drawing plain features wants and what the canvas base spelled
-             * out by hand.
+             * The widget `openFeatureWidget` opens for one of this display's
+             * features. Displays may override it. The default is the generic feature
+             * widget, for displays drawing plain features.
              *
-             * An override is a display whose features have a vocabulary of their own —
-             * a read, a variant, a synteny block — and the `id` is deliberately part
-             * of it: two displays naming one id share the drawer panel, which is the
-             * behaviour when the two are showing the same kind of thing.
+             * Displays whose features are a specific kind (a read, a variant, a
+             * synteny block) override it, including the `id`: two displays naming
+             * one id share the drawer panel, which suits two displays showing the
+             * same kind of feature.
              */
             readonly featureWidgetType: {
                 type: string;
@@ -684,6 +682,46 @@ 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 set of display settings to the live display, and report which
+     * were applied. Each key runs through the display config schema's
+     * `preProcessSnapshot` (shorthand expansions and legacy-key migrations,
+     * as `showTrackGeneric` applies to a session spec's inline track keys),
+     * then writes the matching config slot. A key naming a sub-schema
+     * (`facet`, `color`) replaces the whole object, its string shorthand
+     * lifted by that schema, and `null` clears it. Keys that are not slots
+     * come back in `unapplied` as `{ key, reason }`, so a caller can tell a
+     * misspelling from a key that has an action instead of a slot.
+     *
+     * `allowSetters` also routes a non-slot key to a single-argument action
+     * named `set<Key>`. It is off by default because session specs, share
+     * links and embeds pass untyped JSON here, and a default fallback would
+     * let them call internal setters (`setError`, `setScrollTop`, ...) and
+     * call multi-argument setters with one argument. A caller that wants a
+     * specific action can call it directly.
+     *
+     * A key whose write threw is reported in `failed`. Only `failed` means
+     * the caller passed a bad value. `unapplied` needs the caller's own
+     * context to read: `showTrackGeneric` spreads the same settings into the
+     * display's snapshot, so a declared prop (`resolution`) has already
+     * landed by the time it reports here, while the restyle path spreads
+     * nothing and every entry there did nothing.
+     *
+     * A per-key error does not abort the remaining keys. A caller
+     * mid-`showTrack` has already pushed the track, and one rejected value
+     * should not leave it half-configured.
+     */
+    applyDisplaySettings(settings: Record<string, unknown>, options?: {
+        allowSetters?: boolean;
+    }): {
+        applied: string[];
+        unapplied: UnappliedSetting[];
+        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,7 +1,8 @@
 import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
-import { getConf } from '../../configuration/index.js';
+import { applyConfSettings, getConf } from '../../configuration/index.js';
 import { getContainingTrack, getEnv, statusFraction, statusMessageText, } from '../../util/index.js';
 import { ElementId } from '../../util/types/mst.js';
+import { displaySetterName } from '../../util/unknownSnapshotKeys.js';
 /**
  * #stateModel BaseDisplay
  * #category display
@@ -94,7 +95,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`,
@@ -139,15 +140,14 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * Overridable hook: which widget `openFeatureWidget` opens for one of
-         * this display's features. The default is the generic one, which is what
-         * a display drawing plain features wants and what the canvas base spelled
-         * out by hand.
+         * The widget `openFeatureWidget` opens for one of this display's
+         * features. Displays may override it. The default is the generic feature
+         * widget, for displays drawing plain features.
          *
-         * An override is a display whose features have a vocabulary of their own —
-         * a read, a variant, a synteny block — and the `id` is deliberately part
-         * of it: two displays naming one id share the drawer panel, which is the
-         * behaviour when the two are showing the same kind of thing.
+         * Displays whose features are a specific kind (a read, a variant, a
+         * synteny block) override it, including the `id`: two displays naming
+         * one id share the drawer panel, which suits two displays showing the
+         * same kind of feature.
          */
         get featureWidgetType() {
             return {
@@ -210,6 +210,68 @@ function stateModelFactory() {
          * base display reload does nothing, see specialized displays for details
          */
         reload() { },
+        /**
+         * #action
+         * Apply a set of display settings to the live display, and report which
+         * were applied. Each key runs through the display config schema's
+         * `preProcessSnapshot` (shorthand expansions and legacy-key migrations,
+         * as `showTrackGeneric` applies to a session spec's inline track keys),
+         * then writes the matching config slot. A key naming a sub-schema
+         * (`facet`, `color`) replaces the whole object, its string shorthand
+         * lifted by that schema, and `null` clears it. Keys that are not slots
+         * come back in `unapplied` as `{ key, reason }`, so a caller can tell a
+         * misspelling from a key that has an action instead of a slot.
+         *
+         * `allowSetters` also routes a non-slot key to a single-argument action
+         * named `set<Key>`. It is off by default because session specs, share
+         * links and embeds pass untyped JSON here, and a default fallback would
+         * let them call internal setters (`setError`, `setScrollTop`, ...) and
+         * call multi-argument setters with one argument. A caller that wants a
+         * specific action can call it directly.
+         *
+         * A key whose write threw is reported in `failed`. Only `failed` means
+         * the caller passed a bad value. `unapplied` needs the caller's own
+         * context to read: `showTrackGeneric` spreads the same settings into the
+         * display's snapshot, so a declared prop (`resolution`) has already
+         * landed by the time it reports here, while the restyle path spreads
+         * nothing and every entry there did nothing.
+         *
+         * A per-key error does not abort the remaining keys. A caller
+         * mid-`showTrack` has already pushed the track, and one rejected value
+         * should not leave it half-configured.
+         */
+        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, undeclared, failed } = applyConfSettings(configuration, settings);
+            const unapplied = [];
+            for (const [key, value] of Object.entries(undeclared)) {
+                if (!key || key === 'type') {
+                    unapplied.push({ key, reason: key ? 'display-type' : 'no-slot' });
+                    continue;
+                }
+                const setter = self[displaySetterName(key)];
+                if (typeof setter !== 'function') {
+                    unapplied.push({ key, reason: 'no-slot' });
+                }
+                else if (!options?.allowSetters) {
+                    unapplied.push({ key, reason: 'setter-only' });
+                }
+                else {
+                    try {
+                        ;
+                        setter(value);
+                        applied.push(`${key} (via setter)`);
+                    }
+                    catch (e) {
+                        failed.push({ key, error: `${e}` });
+                    }
+                }
+            }
+            return { applied, unapplied, failed };
+        },
     }));
 }
 export const BaseDisplay = stateModelFactory();