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

package/esm/configuration/types.d.ts

@@ -5,42 +5,23 @@ import type { BuiltinSlotTypeName } from './configurationSlot.ts';
 import type { IAnyType, IArrayType, IOptionalIType, ISimpleType, IStateTreeNode, Instance, SnapshotOut } from '@jbrowse/mobx-state-tree';
 export type ConfigurationSchemaForModel<MODEL> = IsAny<MODEL> extends true ? AnyConfigurationSchemaType : MODEL extends IStateTreeNode<infer T> ? T extends AnyConfigurationSchemaType ? T : T extends IOptionalIType<infer INNER extends AnyConfigurationSchemaType, any> ? INNER : AnyConfigurationSchemaType : never;
 /**
- * A schema's definition as **stored**: the author's own entries over the ones
- * its `baseConfiguration` contributed, the type-level twin of
- * `mergeSchemaDefinition`. The base arrives already merged with its own base,
- * so one level here covers a chain of any depth.
- *
- * A flat mapped type over the union of both key sets, not
- * `Omit<BASE, keyof D> & D`: an intersection's `keyof` is a union of key sets,
- * and mapping over a union that includes `string` — which
- * `ConfigurationSchemaDefinition`'s index signature contributes — collapses
- * back to an index signature, which is the thing `ConfigNodeProps` exists to
- * get rid of.
+ * A schema's definition over its `baseConfiguration`'s, the type-level twin of
+ * `mergeSchemaDefinition`. A flat mapped type rather than
+ * `Omit<BASE, keyof D> & D`, which states it less clearly. ADR-145.
  */
 export type MergeConfigDef<D, BASE> = BASE extends ConfigurationSchemaType<infer BD, any> ? {
     [K in keyof BD | keyof D]: NormalizeSlotDef<K extends keyof D ? K extends keyof BD ? MergeSlotDef<BD[K], D[K]> : D[K] : K extends keyof BD ? BD[K] : never>;
 } : {
     [K in keyof D]: NormalizeSlotDef<D[K]>;
 };
-/**
- * A redeclared slot merges field-by-field over the base's; a sub-schema or a
- * constant keeps replace semantics, matching `mergeSchemaDefinition`'s
- * `isSlotDefinitionEntry` guard.
- */
 type MergeSlotDef<BASE_ENTRY, ENTRY> = BASE_ENTRY extends {
     type: string;
 } ? ENTRY extends {
     type: string;
 } ? Omit<BASE_ENTRY, keyof ENTRY> & ENTRY : ENTRY : ENTRY;
 /**
- * What the type level reads off a slot definition: the slot's `type`, a
- * `stringEnum`'s `model`, and whether a `defaultValue` is there at all — widened
- * off its literal. The description, `advanced`, `contextVariable` and the
- * literal default are documentation and runtime, and carrying them makes two
- * schemas that differ only in one of them mutually unassignable: a subclass
- * raising `height` from 100 to 250 stopped satisfying a parameter pinned to its
- * base. `SlotValueRawFromDef` re-widens a scalar default anyway, and reaches
- * `any` for everything else, so nothing downstream loses precision.
+ * Only `type`, `model` and a widened `defaultValue`: carrying a description or
+ * a literal default makes a subclass that changes one unassignable to its base.
  */
 type NormalizeSlotDef<E> = E extends AnyConfigurationSchemaType ? E : E extends {
     type: infer T;
@@ -58,106 +39,58 @@ type NormalizeSlotDef<E> = E extends AnyConfigurationSchemaType ? E : E extends
 type WidenDefaultValue<V> = [V] extends [boolean] ? boolean : [V] extends [string] ? string : [V] extends [number] ? number : unknown;
 type ConfigNodeValue<DEF> = IsAny<DEF> extends true ? any : DEF extends AnyConfigurationSchemaType ? DEF['Type'] : DEF extends IArrayType<any> | IOptionalIType<IArrayType<any>, any> ? DEF['Type'] : DEF extends string ? string : DEF extends number ? number : SlotValueRawFromDef<DEF>;
 /**
- * The slots a config node presents, read off the schema's own DEFINITION rather
- * than the `Record<string, any>` `makeConfigurationSchemaModel` assembles its
- * MST props from. Those props carry an index signature, so every
- * `node.anything` resolves to `any`; mapping the definition instead is what
- * makes `node.colorr` a compile error.
- *
- * A plain mapped type, and it has to stay one. Wrapping it in a conditional —
- * to answer early for a widened definition, say — makes TypeScript measure
- * DEFINITION as covariant instead of invariant, and it refuses a failed
- * covariant check on a type argument outright where a failed invariant one
- * falls back to comparing the two schemas structurally. Structural is the
- * comparison that matters: a subclass schema's node has every slot the base's
- * does, while its *definition* restates `defaultValue` and `description` and so
- * matches nothing. The widened case belongs on `AnyConfigurationModel`.
+ * A config node's slots, off the schema's definition, so `node.colorr` is a
+ * compile error (ADR-145). It must stay a plain mapped type: a conditional
+ * wrapper makes TypeScript refuse a subclass schema where the base is expected
+ * instead of comparing the two structurally.
  */
 export type ConfigNodeProps<DEFINITION> = {
     [K in keyof DEFINITION]: ConfigNodeValue<DEFINITION[K]>;
 };
 /**
- * The two write actions every config node carries, which `setConf` is the
- * spelling of. A type alias rather than an interface because it annotates the
- * `.actions` block: MST constrains that to `ModelActions`, an index signature
- * of functions, and only a type alias of an object literal gets the implicit
- * index signature that satisfies it.
+ * The two write actions under `setConf`. An alias, not an interface: only an
+ * alias gets the implicit index signature MST's `ModelActions` requires.
  */
 export type ConfigNodeActions = {
     setSubschema: (slotName: string, data: unknown) => unknown;
     setSlot: (slotName: string, value: unknown) => void;
 };
 /**
- * MST's node brand, restated. A config node carries its own schema here by
- * polymorphic `this`, and `ConfigurationSchemaForModel` walks it back out —
- * which is what every `getConf` / `readConfObject` / `setConf` slot-name
- * constraint hangs off, so losing it switches the read-side check off with no
- * error anywhere. `scripts/audit-config-read-types.ts` is the only thing that
- * reports that; run it after touching this.
- *
- * Structurally identical to `IStateTreeNode<IT>`, but an alias rather than an
- * interface: TypeScript infers an implicit index signature for an intersection
- * only when every constituent is an alias or a mapped type, and that is what
- * leaves a concrete config node — whose props are a mapped type with no index
- * signature of its own — assignable to `AnyConfigurationModel`.
+ * MST's node brand restated as an alias, which keeps a concrete node assignable
+ * to `AnyConfigurationModel`. It carries the schema by polymorphic `this`, and
+ * every slot-name check hangs off `ConfigurationSchemaForModel` walking it back
+ * out: run `scripts/audit-config-read-types.ts` after touching it.
  */
 export type ConfigNodeBrand<IT extends IAnyType> = {
     readonly $treenode?: any;
     readonly $__mstStateTreeNodeType__?: [IT] | [any];
 };
 /**
- * The identifier a schema's `explicitIdentifier` installs, folded into the
- * definition as if it were a declared string slot — which is what it is at
- * runtime, `makeConfigurationSchemaModel` just builds it from the options rather
- * than from the table. Folding it in rather than intersecting it onto `Type`
- * keeps it out of `ConfigurationSchemaType`'s parameter list: as a parameter it
- * reads as invariant (it lands in a `Record<K, …>` key position), which stops a
- * concrete schema widening to `AnyConfigurationSchemaType`. Inheritance comes
- * free, since `MergeConfigDef` already folds the base's whole definition in.
+ * The `explicitIdentifier` prop, folded into the definition as a string slot
+ * rather than a type parameter, which would read as invariant and stop a
+ * concrete schema widening to `AnyConfigurationSchemaType`.
  */
 export interface IdentifierSlotDef {
     type: 'string';
     defaultValue: '';
 }
-/**
- * The `type` prop an `explicitlyTyped` schema installs, folded into the
- * definition the same way and for the same reasons. Separate from
- * `IdentifierSlotDef` despite the identical shape, because the runtime prop is
- * `types.literal(modelName)` and this is where that would be said if the model
- * name ever became a type parameter.
- */
+/** An `explicitlyTyped` schema's `type` prop, folded in the same way. */
 export interface TypeSlotDef {
     type: 'string';
     defaultValue: '';
 }
 export type ConfigurationSlotName<SCHEMA> = IsAny<SCHEMA> extends true ? string : SCHEMA extends ConfigurationSchemaType<infer D, any> ? keyof D & string : never;
 /**
- * The names a config snapshot for `SCHEMA` may use — its own slots, its
- * sub-schemas recursively, its identifier and everything it inherits — with
- * every value left `unknown`.
- *
- * Names are the whole point of it. A slot value can be its own type, a `jexl:`
- * callback string, or (for a `maybe*` slot) absent, and nothing here tries to
- * check that; a *name* the schema does not declare is dropped on the way in
- * without a word, so `preferance` is a setting that reads as applied and never
- * applies. Against an object literal — which is how an embedder writes one —
- * TypeScript's excess-property check turns that into a compile error.
+ * The names a config snapshot for `SCHEMA` may use, sub-schemas included, with
+ * every value `unknown`. MST drops an undeclared name silently; against an
+ * object literal, the excess-property check makes it a compile error.
  */
 export type ConfigurationSnapshot<SCHEMA> = SCHEMA extends undefined ? never : SCHEMA extends ConfigurationSchemaType<infer D, any> ? {
     [K in keyof D]?: D[K] extends ConfigurationSchemaType<any, any> ? ConfigurationSnapshot<D[K]> : unknown;
 } : unknown;
 /**
- * The value each builtin slot `type` reads as — the type-level twin of
- * `slotTypes` in `configurationSlot.ts`, which is the same list as MST models.
- * A table rather than the fourteen-deep conditional staircase this used to be:
- * adding a slot type is now one row here and one there, and the two tables sit
- * side by side where a name present in one and missing from the other is
- * visible. Missing a row is not silent either — it drops the slot to the
- * `defaultValue` fallback below, which is what `SlotValueRawFromDef` documents.
- *
- * `stringEnum`/`maybeStringEnum` are deliberately absent: their value type comes
- * from the author's own `types.enumeration`, read off `model` before this table
- * is consulted.
+ * What each builtin slot type reads as, beside `slotTypes` in
+ * `configurationSlot.ts`. The enum types read their members off `model`.
  */
 interface SlotValueByType {
     stringArray: string[];
@@ -171,15 +104,7 @@ interface SlotValueByType {
     maybeBoolean: boolean | undefined;
     maybeColor: string | undefined;
     maybeString: string | undefined;
-    /**
-     * `frozen` and its `maybe*` form are `any` deliberately — arbitrary dynamic
-     * JSON whose shape the caller asserts at the read boundary. `unknown` would
-     * only add cast ceremony on values that are legitimately dynamic.
-     *
-     * Stated here rather than left to the `defaultValue` fallback, which reaches
-     * `any` for these only by accident: no `frozen` slot in the repo happens to
-     * default to a scalar.
-     */
+    /** arbitrary JSON, whose shape the caller asserts where it reads it */
     frozen: any;
     maybeFrozen: any;
     number: number;
@@ -191,19 +116,6 @@ interface SlotValueByType {
     color: string;
     colorArray: string[];
 }
-/**
- * The two tables name the same builtin slot types, checked rather than
- * remembered.
- *
- * A row present in one and missing from the other is otherwise **not** an
- * error: the slot drops through to `SlotValueRawFromDef`'s `defaultValue`
- * fallback, which re-widens a scalar default but reaches `any` for everything
- * else — so a new `stringArray`-shaped type would silently read as `any` at
- * every call site. The "every builtin slot type reads as its declared value
- * type" case in `configTypeNarrowing.test.ts` lists the rows by hand, so it
- * only catches the drift if whoever adds the type also edits the test; this
- * catches it either way.
- */
 type MutuallyExtends<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
 type Assert<T extends true> = T;
 export type SlotValueTableCoversBuiltinSlotTypes = Assert<MutuallyExtends<BuiltinSlotTypeName, keyof SlotValueByType>>;
@@ -225,14 +137,10 @@ type SubSchemaSlotPath<SCHEMA> = SCHEMA extends ConfigurationSchemaType<infer D,
     } ? readonly [K, ...string[]] : never;
 }[keyof D & string] : readonly string[];
 /**
- * The array paths a read may take into `SCHEMA`. Past one segment each is
- * checked: a sub-schema's name, then one of its slot names or a deeper path. A
- * head naming something other than a sub-schema — a pluggable adapter union, an
- * array or map of sub-schemas, a `frozen` slot — keeps an unchecked tail, and a
- * widened schema admits any `string[]`.
- *
- * A one-segment path stays unchecked: it is how a generic class body, where
- * `SCHEMA` is unresolved, reads a slot at all (`FastaAdapterBase`).
+ * The array paths a read may take into `SCHEMA`, checked segment by segment
+ * through sub-schemas. A pluggable union, a collection or a `frozen` slot keeps
+ * an unchecked tail. A one-segment path stays unchecked, since a generic class
+ * body with `SCHEMA` unresolved reads a slot that way (`FastaAdapterBase`).
  */
 export type ConfigurationSlotPath<SCHEMA> = readonly [] | readonly [string] | SubSchemaSlotPath<SCHEMA>;
 /** what a read of `PATH` into `SCHEMA` yields */
@@ -243,17 +151,8 @@ export type ConfigurationSlotPathValue<SCHEMA, PATH> = PATH extends readonly [
 /** what a raw read (`getConf` / `readConfObject`) of this slot yields */
 export type ConfigurationSlotValue<SCHEMA, K extends string> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? K extends keyof D ? SlotValueRawFromDef<D[K]> : any : any;
 /**
- * Naming convention for config types, paired per schema:
- * - `XConfigSchema` is the MST IType (the schema itself). Use it for
- *   `getConf`, `ConfigurationReference`, and factory params — anywhere a schema
- *   is expected.
- * - `XConfigModel` is `Instance<XConfigSchema>` (a resolved config node). Use it
- *   for `readConfObject` results, model fields, and values read off a session.
- *
- * Prefer a named `XConfigModel` alias over inlining `Instance<XConfigSchema>` at
- * call sites. Two historical names predate this convention and stay as-is:
- * `BaseTrackConfig` (the track instance type) and `AnyConfiguration` (a
- * model-or-snapshot union, not a plain instance).
+ * Naming: `XConfigSchema` is the schema (an MST type), for factory params and
+ * `ConfigurationReference`; `XConfigModel` is `Instance<XConfigSchema>`, a node.
  */
 export type AnyConfigurationSchemaType = ConfigurationSchemaType<any, any>;
 export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType> & Record<string, any>;
@@ -266,22 +165,11 @@ export interface PluggableConfigNode extends AnyConfigurationModel {
     type: string;
 }
 /**
- * The `XConfigModel` for a **field table** — a `*ConfigSchemaFields` export —
- * rather than for a whole assembled schema. What it is for is the cast a
- * cross-cutting mixin uses to reach the `configuration` its composing display
- * supplies but its own `self` cannot see: cast to `AnyConfigurationModel` there
- * and `getConf`/`setConf` derive their slot-name constraint from a schema
- * widened to `any`, so every name typechecks and a misspelled *read* returns
- * `undefined` with no diagnostic at any layer. Name the mixin's own field table
- * instead and the check comes back, scoped to exactly the slots that mixin owns.
- *
- * `BASE` is for the mixin that also reads a slot off the schema its displays
- * inherit from — `ConfigurationSlotName` walks the base chain, so passing it
- * admits those names too and nothing else (`HeightModeMixin` and `height`).
- *
- * The pairing this depends on is a mixin and its field table living together:
- * `RowHeightMixin` + `rowHeightConfigSchemaFields` is the worked example, and
- * `packages/tree-sidebar/CLAUDE.md` has the reasoning.
+ * The node type for a mixin's field table (a `*ConfigSchemaFields` export), for
+ * the cast a mixin uses to reach its host's `configuration`. A cast to
+ * `AnyConfigurationModel` there checks no slot name, so a misspelled read
+ * returns `undefined` silently. `BASE` admits the slots of the schema the
+ * mixin's displays inherit (`HeightModeMixin`'s `height`).
  */
 export type ConfigModelForFields<FIELDS extends ConfigurationSchemaDefinition, BASE extends AnyConfigurationSchemaType | undefined = undefined> = Instance<ConfigurationSchemaType<MergeConfigDef<FIELDS, BASE>, ConfigurationSchemaOptions<BASE, undefined>>>;
 /**
@@ -292,11 +180,8 @@ export type ConfigModelForFields<FIELDS extends ConfigurationSchemaDefinition, B
  * const pin: HostChecksSlotNames<HeightModeHost> = true
  * ```
  *
- * Worth a named type because the widened form has **no symptom** — a mixin host
- * cast to `AnyConfigurationModel` compiles and runs and checks nothing. Every
- * misspelled slot name below it typechecks, and a misspelled *read* returns
- * `undefined` with no diagnostic at any layer, so only a sabotage or this
- * assertion tells the two apart.
+ * The widened form has no symptom: a host cast to `AnyConfigurationModel`
+ * compiles, runs and checks nothing.
  */
 export type HostChecksSlotNames<HOST extends {
     configuration: AnyConfigurationModel;
@@ -305,12 +190,28 @@ export type HostChecksSlotNames<HOST extends {
 export type AnyConfigurationSnapshot = SnapshotOut<AnyConfigurationModel>;
 /**
  * A value readable as configuration: either a live configuration model or a
- * plain snapshot of one. `session.tracks` holds plain base or merged configs
- * that hydrate to MST only on first reference access, `getTrackById` also
- * answers live assembly-sequence and connection nodes, and `readConfObject`
- * reads both — so this is the honest type at those boundaries. Reserve
- * `AnyConfigurationModel` for values that must be live (actions, identity,
- * reference resolution).
+ * plain snapshot of one, such as a config a caller hands to an add action.
+ * Reserve `AnyConfigurationModel` for values that must be live (actions,
+ * identity, reference resolution).
  */
 export type AnyConfiguration = AnyConfigurationModel | AnyConfigurationSnapshot;
+/**
+ * A track config as `jbrowse.tracks` and `session.tracks` hold it: a frozen
+ * plain object, which hydrates to a config node only when a track reads its
+ * `configuration`. It holds what was written, so a slot at its default is
+ * absent. `readConfObject` refuses one for that reason; read `trackId` and
+ * `type` off it directly, and a slot through a helper that supplies the
+ * default, such as `getConfAssemblyNamesOrNone`.
+ */
+export interface TrackConfigEntry {
+    trackId: string;
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * What `getTrackById` answers: a {@link TrackConfigEntry}, or a live node for
+ * an assembly's sequence track or a track a connection holds. A raw member
+ * read works on both, and finds a slot at its default only on the node.
+ */
+export type AnyTrackConfig = TrackConfigEntry | AnyConfigurationModel;
 export {};

package/esm/pluggableElementTypes/DisplayType.d.ts

@@ -1,5 +1,6 @@
 import LazyStateModelElement from './LazyStateModelElement.ts';
 import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
+import type { PlotExample } from '../configuration/plot.ts';
 import type { AnyReactComponentType } from '../util/index.ts';
 import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
 export type DisplayEntry = Record<string, unknown>;
@@ -52,8 +53,19 @@ export default class DisplayType extends LazyStateModelElement {
      * not given one.
      */
     adapterCapabilities: readonly string[];
+    /**
+     * The RPC methods this display's first fetch calls. A track launching with
+     * it loads their code in its worker beside the adapter's
+     * (`RpcMethodType.preload`).
+     */
+    rpcMethods: readonly string[];
     retiredTypes: readonly RetiredDisplayType[];
     retiredState?: RetiredDisplayState;
+    /**
+     * Worked examples of this display's plot, which "Edit plot..." offers as
+     * buttons. Each has to pass the display's config schema.
+     */
+    plotExamples: readonly PlotExample[];
     constructor(stuff: {
         name: string;
         stateModel: IAnyModelType | (() => Promise<IAnyModelType>);
@@ -64,7 +76,9 @@ export default class DisplayType extends LazyStateModelElement {
         ReactComponent: AnyReactComponentType;
         helpText?: string;
         adapterCapabilities?: readonly string[];
+        rpcMethods?: readonly string[];
         retiredTypes?: readonly RetiredDisplayType[];
         retiredState?: RetiredDisplayState;
+        plotExamples?: readonly PlotExample[];
     });
 }

package/esm/pluggableElementTypes/DisplayType.js

@@ -24,8 +24,19 @@ export default class DisplayType extends LazyStateModelElement {
      * not given one.
      */
     adapterCapabilities;
+    /**
+     * The RPC methods this display's first fetch calls. A track launching with
+     * it loads their code in its worker beside the adapter's
+     * (`RpcMethodType.preload`).
+     */
+    rpcMethods;
     retiredTypes;
     retiredState;
+    /**
+     * Worked examples of this display's plot, which "Edit plot..." offers as
+     * buttons. Each has to pass the display's config schema.
+     */
+    plotExamples;
     constructor(stuff) {
         super({
             ...stuff,
@@ -37,7 +48,9 @@ export default class DisplayType extends LazyStateModelElement {
         this.viewType = stuff.viewType;
         this.helpText = stuff.helpText;
         this.adapterCapabilities = stuff.adapterCapabilities ?? [];
+        this.rpcMethods = stuff.rpcMethods ?? [];
         this.retiredTypes = stuff.retiredTypes ?? [];
         this.retiredState = stuff.retiredState;
+        this.plotExamples = stuff.plotExamples ?? [];
     }
 }

package/esm/pluggableElementTypes/RpcMethodType.d.ts

@@ -70,6 +70,13 @@ export default abstract class RpcMethodType<MethodName extends string = string>
     name: MethodName;
     pluginManager: PluginManager;
     constructor(pluginManager: PluginManager);
+    /**
+     * Start loading the code `execute` runs, for a method whose body is a dynamic
+     * import. A display that names the method in `rpcMethods` has its worker call
+     * this when its track launches, so the import lands beside the adapter's code
+     * instead of after the first request's refName lookup.
+     */
+    preload(): Promise<unknown>;
     serializeArguments(args: object): Promise<Record<string, unknown>>;
     /**
      * The reference sequence of the genome a call names in `assemblyName`, as a

package/esm/pluggableElementTypes/RpcMethodType.js

@@ -167,6 +167,15 @@ export default class RpcMethodType extends PluggableElementBase {
         super();
         this.pluginManager = pluginManager;
     }
+    /**
+     * Start loading the code `execute` runs, for a method whose body is a dynamic
+     * import. A display that names the method in `rpcMethods` has its worker call
+     * this when its track launches, so the import lands beside the adapter's code
+     * instead of after the first request's refName lookup.
+     */
+    async preload() {
+        return undefined;
+    }
     async serializeArguments(args) {
         const augmented = await this.augmentLocationObjects(this.attachReference(args));
         return {

package/esm/pluggableElementTypes/WidgetType.d.ts

@@ -14,6 +14,11 @@ export default class WidgetType extends PluggableElementBase {
     ReactComponent: WidgetComponentType;
     stateModel: IAnyModelType;
     helpText?: React.ReactNode;
+    /**
+     * 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: boolean;
     constructor(stuff: {
         name: string;
         heading?: string;
@@ -22,6 +27,7 @@ export default class WidgetType extends PluggableElementBase {
         stateModel: IAnyModelType;
         ReactComponent: WidgetComponentType;
         helpText?: React.ReactNode;
+        discardOnClose?: boolean;
     });
 }
 export {};

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

@@ -71,7 +71,8 @@ export declare function addViewMenuItems<N extends ViewTypeName, K extends MenuM
  * Add items to a menu on a display type belonging to another plugin, e.g. an
  * "open this read in a dotplot" entry on the alignments display's context menu.
  * See {@link addViewMenuItems}; the name is checked against
- * `DisplayTypeRegistry`.
+ * `DisplayTypeRegistry`. It matches the registered name only, so an item added
+ * to `LinearMarkDisplay` misses `LinearManhattanDisplay`, which subtypes it.
  *
  * ```ts
  * addDisplayMenuItems(pluginManager, 'LinearAlignmentsDisplay', {

package/esm/pluggableElementTypes/addMenuItems.js

@@ -63,7 +63,8 @@ export function addViewMenuItems(pluginManager, name, options) {
  * Add items to a menu on a display type belonging to another plugin, e.g. an
  * "open this read in a dotplot" entry on the alignments display's context menu.
  * See {@link addViewMenuItems}; the name is checked against
- * `DisplayTypeRegistry`.
+ * `DisplayTypeRegistry`. It matches the registered name only, so an item added
+ * to `LinearMarkDisplay` misses `LinearManhattanDisplay`, which subtypes it.
  *
  * ```ts
  * addDisplayMenuItems(pluginManager, 'LinearAlignmentsDisplay', {

package/esm/pluggableElementTypes/index.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/BaseDisplayModel.d.ts

@@ -1,4 +1,5 @@
 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';
@@ -670,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
@@ -722,6 +723,62 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
             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: what its colour objects and `scales.y` say together
+     * that cannot be drawn as written. 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>;