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

package/esm/configuration/readConfObject.js

@@ -1,27 +1,14 @@
 /**
  * @module
- * The config **readers**: `readConfObject` off a live MST config node, and
- * `readConfigValue` off a plain snapshot object in a worker or a renderer. Both
- * exist to evaluate a slot's `jexl:...` callback on read; they differ only in
- * where the jexl instance comes from, the node's env or an explicit argument.
- * A `featureField` slot's `jexl:` expression is the display's to evaluate per
- * feature, so `readConfObject` hands it over as written.
+ * The config readers: `readConfObject` off a live config node, whose env
+ * supplies the jexl instance, and `readConfigValue` off a plain snapshot in a
+ * worker or renderer, which is handed one.
  */
 import { getEnv, getSnapshot, getType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
-// Evaluate a slot's `jexl:...` callback string against the realm's single jexl
-// instance (carrying plugin-registered functions), read from the config node's
-// env. readConfObject only ever operates on live MST configs — nested sub-config
-// reads stay MST (env resolves to the root), and frozen track configs hydrate to
-// MST before any callback is read — so the env instance is always present here.
 function evalConfigCallback(expr, args, confObject) {
     if (!isStateTreeNode(confObject)) {
-        // A jexl slot needs the realm's jexl instance, which is read from a live
-        // config node's env. A plain config snapshot (e.g. an un-hydrated
-        // session.tracks entry) carries no env — read it through a hydrated model,
-        // or use readConfigValue(config, key, feature, jexl) which takes jexl
-        // explicitly.
         throw new Error(`cannot evaluate jexl config callback ${JSON.stringify(expr)}: config is a plain snapshot, not a live model (no env to resolve the jexl instance)`);
     }
     const jexl = getEnv(confObject)
@@ -35,11 +22,7 @@ function isFeatureField(confObject, slotName) {
     return (isStateTreeNode(confObject) &&
         !!getConfigurationSchemaMetadata(getType(confObject))?.featureFields.has(slotName));
 }
-// Read and resolve a single slot: raw value, jexl callback evaluation, then a
-// referentially-stable snapshot for sub-config nodes.
 function readSlot(confObject, slotName, args) {
-    // strict undefined check, not truthiness — a slot value can legitimately be
-    // falsy (0, '', false, null)
     const value = confObject[slotName];
     if (value === undefined) {
         return undefined;
@@ -47,42 +30,25 @@ function readSlot(confObject, slotName, args) {
     const val = isCallbackValue(value) && !isFeatureField(confObject, slotName)
         ? evalConfigCallback(value, args, confObject)
         : value;
-    // Fast path for primitives (most common case)
     if (val === null || typeof val !== 'object') {
         return val;
     }
-    // Return the live, referentially-stable snapshot (frozen in dev) rather than
-    // a per-read clone: stable identity lets downstream computeds memoize, and
-    // the old structuredClone was both a hot-path allocation and a source of
-    // spurious recomputation. Treat as read-only.
+    // the live snapshot, stable across reads so downstream computeds memoize;
+    // read-only
     return isStateTreeNode(val) ? getSnapshot(val) : val;
 }
-// loose implementation signature: the body returns values that are `any` by
-// nature (raw slot values, snapshots); the typed overloads above are what
-// callers see. No looser overload admits the model: one that did was a
-// catch-all a slot-name typo fell through to, compiling clean as `any`.
+// No looser overload admits the model: a catch-all lets a slot-name typo
+// compile as `any`.
 export function readConfObject(confObject, slotPath, args = {}) {
-    // the single-slot read, first and allocation-free: it is the shape of nearly
-    // every one of the ~1300 call sites, so it doesn't get normalized into a
-    // one-element array on the way past
     if (typeof slotPath === 'string') {
         return readSlot(confObject, slotPath, args);
     }
     if (slotPath !== undefined && !Array.isArray(slotPath)) {
         throw new TypeError('slotPath must be a string or array');
     }
-    // No path, or an empty one — which means the same thing, and used not to: `[]`
-    // is truthy, so it reached the walk below and read `confObject[undefined]`.
-    //
-    // Returns the whole config as a plain object: the live, referentially-stable
-    // snapshot (frozen in dev), not a fresh clone — treat as read-only.
     if (!slotPath?.length) {
         return isStateTreeNode(confObject) ? getSnapshot(confObject) : confObject;
     }
-    // every segment but the last names a sub-config, and only the last is a slot
-    // read — which is where jexl evaluation and snapshotting happen, and nowhere
-    // else. Iterative rather than a self-call per segment, which re-entered the
-    // whole argument-shape preamble above at each level.
     let conf = confObject;
     for (let i = 0; i < slotPath.length - 1; i++) {
         const subConf = conf[slotPath[i]];
@@ -93,9 +59,6 @@ export function readConfObject(confObject, slotPath, args = {}) {
     }
     return readSlot(conf, slotPath[slotPath.length - 1], args);
 }
-// The plain-object half of the slot walk, for readConfigValue. The MST half is
-// readSlot/rawSlotValue above. A plain object has no map entries and no
-// sub-config nodes to snapshot, so it is just a path reduce.
 function resolveConfigValue(config, key) {
     if (Array.isArray(key)) {
         let val = config;
@@ -107,12 +70,18 @@ function resolveConfigValue(config, key) {
     return config[key];
 }
 /**
- * Read a value from a plain config snapshot object. Automatically evaluates
- * "jexl:..." strings per-feature. Works without MST — intended for use in
- * rendering code (GPU, Canvas2D, workers). Pass the realm's `pluginManager.jexl`
- * so plugin-registered functions (e.g. in a custom `mouseover` slot) resolve.
+ * Read a value from a plain config snapshot, evaluating a `jexl:` callback
+ * against `feature`. For rendering code and workers; pass the realm's
+ * `pluginManager.jexl` so plugin-registered functions resolve.
  */
 export function readConfigValue(config, key, feature, jexl) {
-    const raw = resolveConfigValue(config, key);
-    return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
+    return evaluateForFeature(resolveConfigValue(config, key), feature, jexl);
+}
+/**
+ * #api core/configuration
+ * A config value as `feature` reads it: a `jexl:` callback evaluated against
+ * the feature, anything else as written.
+ */
+export function evaluateForFeature(value, feature, jexl) {
+    return isCallbackValue(value) ? evaluateJexl(value, { feature }, jexl) : value;
 }

package/esm/configuration/schemaTypes.js

@@ -67,7 +67,11 @@ export function isSlotDefinitionEntry(def) {
 export function isConfigurationModel(thing) {
     return isStateTreeNode(thing) && isConfigurationSchemaType(getType(thing));
 }
-const NUMBER_SLOT_TYPES = new Set(['number', 'integer', 'maybeNumber']);
+const NUMBER_SLOT_TYPES = new Set([
+    'number',
+    'integer',
+    'maybeNumber',
+]);
 /**
  * The slot a bare value of each form lifts into, off a `shorthand` option:
  * each slot it names takes the form its own type holds, a number where it

package/esm/configuration/snapshotPreprocess.js

@@ -1,4 +1,5 @@
 import { isJexl } from '../util/jexlStrings.js';
+import { isPlainObject } from '../util/objectUtils.js';
 import { slotWriteRefusal } from './configurationSlot.js';
 import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { bareFormOf, isConstantEntry, shorthandTargets } from './schemaTypes.js';
@@ -60,9 +61,6 @@ function isOwnSnapshot({ name, options }, snapshot) {
         snapshot.type === undefined ||
         snapshot.type === name);
 }
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 // `lifted` under `written`: what the snapshot spells wins, member by member
 // where both are objects.
 function underWritten(written, lifted) {

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

@@ -53,6 +53,12 @@ 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;
     /**
@@ -70,6 +76,7 @@ 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,6 +24,12 @@ 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;
     /**
@@ -42,6 +48,7 @@ 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/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/models/BaseDisplayModel.d.ts

@@ -759,8 +759,9 @@ export declare const BaseDisplay: import("@jbrowse/mobx-state-tree").IModelType<
     /**
      * #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.
+     * `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[];
     /**

package/esm/pluggableElementTypes/models/BaseDisplayModel.js

@@ -1,6 +1,6 @@
 import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
 import { applyConfSettings, getConfigurationSchemaMetadata, getConf, setConf, } from '../../configuration/index.js';
-import { liftPlot as liftPlotDraft, plotKeysOf, plotOf, plotWrites as plotWritesOf, } from '../../configuration/plot.js';
+import { liftPlot as liftPlotDraft, plotKeysOf, plotOf, plotWrites as plotWritesOf, schemaPlotProblems, } 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';
@@ -324,12 +324,12 @@ function stateModelFactory() {
         /**
          * #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.
+         * `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) {
-            this.liftPlot(draft);
-            return [];
+            return schemaPlotProblems(liftPlotDraft(self.configuration, draft));
         },
         /**
          * #method

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

@@ -200,10 +200,8 @@ export declare function createBaseTrackModel(pm: PluginManager, trackType: strin
      * completely untouched ones — `reaction` only fires on an actual change.
      *
      * `equals: compareStructural` is load-bearing, not an optimization:
-     * `self.configuration` is a re-resolving reference, and persisting a save
-     * can swap the resolved node identity (the delta path reconciles in place
-     * but still churns once, and a session without deltas replaces the frozen
-     * `jbrowse.tracks` entry, rehydrating a brand-new MST node every write).
+     * `self.configuration` is a re-resolving reference, and an undo or a
+     * session restore swaps the resolved node for a new working copy.
      * Referential comparison would treat every such swap as a fresh change
      * and re-fire the save, an unbounded debounced loop. Structural
      * comparison settles once the content stops changing.