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

package/esm/pluggableElementTypes/WidgetType.js

@@ -6,6 +6,11 @@ export default class WidgetType extends PluggableElementBase {
     ReactComponent;
     stateModel;
     helpText;
+    /**
+     * Closing the widget removes it from the session rather than hiding it, so
+     * what it holds stops riding along in every saved and shared session (#3538)
+     */
+    discardOnClose;
     constructor(stuff) {
         super(stuff);
         this.heading = stuff.heading;
@@ -14,5 +19,6 @@ export default class WidgetType extends PluggableElementBase {
         this.stateModel = stuff.stateModel;
         this.ReactComponent = stuff.ReactComponent;
         this.helpText = stuff.helpText;
+        this.discardOnClose = stuff.discardOnClose ?? false;
     }
 }

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';
@@ -9,15 +9,8 @@ export { default as ViewType } from './ViewType.js';
 export { default as DisplayType } from './DisplayType.js';
 export { default as InternetAccountType } from './InternetAccountType.js';
 export { default as RpcMethodType } from './RpcMethodType.js';
-// The two region-renaming bases, which nearly every RPC method that takes a
-// viewport wants — without them an external plugin deep-imports the file and
-// bundles its own copy, which is only harmless because RPC methods are keyed by
-// name (PluginManager.rpcMethods) and nothing does an instanceof.
 // `RpcMethodTypeWithFiltersAndRenameRegions` is deliberately not here: it pulls
-// in `renderers/util/serializableFilterChain`, and RFC-001 §9 deletes
-// `pluggableElementTypes/renderers/*` after the legacy renderer migration. This
-// barrel is served as ABI, so exporting it would pin a directory we intend to
-// remove.
+// in `renderers/util/serializableFilterChain`, and this barrel is served as ABI.
 export { default as RpcMethodTypeWithRenameRegion } from './RpcMethodTypeWithRenameRegion.js';
 export { default as RpcMethodTypeWithRenameRegions } from './RpcMethodTypeWithRenameRegions.js';
 export { default as AddTrackWorkflowType } from './AddTrackWorkflowType.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,8 @@
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
+import type { Plot, PlotExample } from '../../configuration/plot.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 +163,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 +204,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 +383,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 +424,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 +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`,
@@ -636,15 +636,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;
@@ -672,7 +671,7 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
      * `installClearHoverOnViewportChange` calls.
      *
      * A display that STORES its hover owes an override; one that derives it
-     * from the live pointer (MAF, Hi-C, LD) owes nothing, and the default
+     * from the live pointer (Hi-C, LD) owes nothing, and the default
      * costs it nothing. Declared here so the clear can be installed for every
      * display rather than remembered per display — forgetting it is the
      * failure ARCHITECTURE.md's stored-hover section is about, and it used to
@@ -684,6 +683,101 @@ 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;
+        }[];
+    };
+} & {
+    /**
+     * #getter
+     * The grammar settings this display's config declares, by slot name
+     * (`PLOT_VOCABULARY`): what "Edit plot..." edits. Empty on a display
+     * with none, which then offers no editor.
+     */
+    readonly plotKeys: string[];
+    /**
+     * #getter
+     * Those settings as declared, defaults left off and a shorthand written
+     * as a config file writes it. An agent edits a `structuredClone` of it,
+     * checks it with `plotProblems` and hands it to `applyPlot`.
+     */
+    readonly plot: Plot;
+    /**
+     * #getter
+     * The worked examples this display type declares, which "Edit plot..."
+     * offers as buttons.
+     */
+    readonly plotExamples: readonly PlotExample[];
+    /**
+     * #getter
+     * This display type's page in the config reference, which lists every
+     * setting it takes.
+     */
+    readonly configDocsUrl: string;
+    /**
+     * #method
+     * A draft as the config would hold it, merged over `plot`, throwing what
+     * a config file would be refused for. Nothing on the display changes.
+     */
+    liftPlot(draft: Plot): AnyConfigurationModel;
+    /**
+     * #method
+     * What a draft would report once applied, throwing a refusal as
+     * `liftPlot` does. A display with a rule list over its settings
+     * overrides it; the draft still applies, and draws what it can.
+     */
+    plotProblems(draft: Plot): string[];
+    /**
+     * #method
+     * What applying a draft would write, by setting: the lifted value where
+     * it differs from `plot`, `null` where it resets one. Throws a refusal.
+     */
+    plotWrites(draft: Plot): Record<string, unknown>;
+} & {
+    /**
+     * #action
+     * Write a draft over `plot`: each setting it changes is replaced whole,
+     * so a member left out of an object goes back to its default, and `null`
+     * resets the setting. A draft the schema refuses, or naming a setting
+     * outside the plot, throws before anything is written.
+     */
+    applyPlot(draft: Plot): void;
 }, 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,9 @@
 import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
-import { getConf } from '../../configuration/index.js';
+import { applyConfSettings, getConfigurationSchemaMetadata, getConf, setConf, } from '../../configuration/index.js';
+import { liftPlot as liftPlotDraft, plotKeysOf, plotOf, plotWrites as plotWritesOf, } from '../../configuration/plot.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 +96,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 +141,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 {
@@ -198,7 +199,7 @@ function stateModelFactory() {
          * `installClearHoverOnViewportChange` calls.
          *
          * A display that STORES its hover owes an override; one that derives it
-         * from the live pointer (MAF, Hi-C, LD) owes nothing, and the default
+         * from the live pointer (Hi-C, LD) owes nothing, and the default
          * costs it nothing. Declared here so the clear can be installed for every
          * display rather than remembered per display — forgetting it is the
          * failure ARCHITECTURE.md's stored-hover section is about, and it used to
@@ -210,6 +211,149 @@ 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 };
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * The grammar settings this display's config declares, by slot name
+         * (`PLOT_VOCABULARY`): what "Edit plot..." edits. Empty on a display
+         * with none, which then offers no editor.
+         */
+        get plotKeys() {
+            return plotKeysOf(self.configuration);
+        },
+        /**
+         * #getter
+         * Those settings as declared, defaults left off and a shorthand written
+         * as a config file writes it. An agent edits a `structuredClone` of it,
+         * checks it with `plotProblems` and hands it to `applyPlot`.
+         */
+        get plot() {
+            return plotOf(self.configuration);
+        },
+        /**
+         * #getter
+         * The worked examples this display type declares, which "Edit plot..."
+         * offers as buttons.
+         */
+        get plotExamples() {
+            const { pluginManager } = getEnv(self);
+            return pluginManager.getDisplayType(self.type).plotExamples;
+        },
+        /**
+         * #getter
+         * This display type's page in the config reference, which lists every
+         * setting it takes.
+         */
+        get configDocsUrl() {
+            const name = getConfigurationSchemaMetadata(self.configuration)?.name;
+            return name
+                ? `https://jbrowse.org/jb2/docs/config/${name.toLowerCase()}/`
+                : 'https://jbrowse.org/jb2/docs/config_guide/';
+        },
+        /**
+         * #method
+         * A draft as the config would hold it, merged over `plot`, throwing what
+         * a config file would be refused for. Nothing on the display changes.
+         */
+        liftPlot(draft) {
+            return liftPlotDraft(self.configuration, draft);
+        },
+        /**
+         * #method
+         * What a draft would report once applied, throwing a refusal as
+         * `liftPlot` does. A display with a rule list over its settings
+         * overrides it; the draft still applies, and draws what it can.
+         */
+        plotProblems(draft) {
+            this.liftPlot(draft);
+            return [];
+        },
+        /**
+         * #method
+         * What applying a draft would write, by setting: the lifted value where
+         * it differs from `plot`, `null` where it resets one. Throws a refusal.
+         */
+        plotWrites(draft) {
+            return plotWritesOf(self.configuration, draft);
+        },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * Write a draft over `plot`: each setting it changes is replaced whole,
+         * so a member left out of an object goes back to its default, and `null`
+         * resets the setting. A draft the schema refuses, or naming a setting
+         * outside the plot, throws before anything is written.
+         */
+        applyPlot(draft) {
+            const { configuration } = self;
+            for (const [key, value] of Object.entries(self.plotWrites(draft))) {
+                setConf(configuration, key, value);
+            }
+        },
     }));
 }
 export const BaseDisplay = stateModelFactory();