@jbrowse/core 5.0.0-beta.7 → 5.0.0-beta.9

package/esm/configuration/configurationSchema.d.ts

@@ -1,8 +1,9 @@
 import type PluginManager from '../PluginManager.ts';
 import type { IsAny } from '../util/types/isAny.ts';
 import type { ConfigSlotDefinition } from './configurationSlot.ts';
-import type { AnyConfigurationModel, AnyConfigurationSchemaType, GetInheritedIdentifier } from './types.ts';
-import type { IAnyType, IType, ReferenceIdentifier, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+import type { ConfigurationSchemaRequirement } from './requirements.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, IdentifierSlotDef, MergeConfigDef, TypeSlotDef } from './types.ts';
+import type { IAnyType, ISimpleType, IType, ReferenceIdentifier, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
 export type { AnyConfigurationModel, AnyConfigurationSchemaType, } from './types.ts';
 /**
  * The three entry kinds `makeConfigurationSchemaModel` classifies: a slot
@@ -20,15 +21,37 @@ export type { AnyConfigurationModel, AnyConfigurationSchemaType, } from './types
 export interface ConfigurationSchemaDefinition {
     [n: string]: ConfigSlotDefinition | string | number | IAnyType;
 }
-export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined> {
-    explicitlyTyped?: boolean;
+export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined, EXPLICITLY_TYPED extends boolean | undefined = boolean | undefined, REQUIREMENT extends ConfigurationSchemaRequirement = ConfigurationSchemaRequirement> {
+    explicitlyTyped?: EXPLICITLY_TYPED;
     explicitIdentifier?: EXPLICIT_IDENTIFIER;
     implicitIdentifier?: string | boolean;
     baseConfiguration?: BASE_SCHEMA;
     actions?: (self: unknown) => any;
     views?: (self: unknown) => any;
     extend?: (self: unknown) => any;
+    /**
+     * The slot a bare string snapshot lifts into, so `color: "red"` and
+     * `color: { value: "red" }` are one config. Applied before
+     * `preProcessSnapshot`, on every path a snapshot arrives by; the JSON schema,
+     * `describeSlots` and the config editor read it here.
+     */
+    shorthand?: string;
+    /**
+     * Slots a bare value sets beside `shorthand`, for a schema whose defaults
+     * would hide it: LGVSyntenyColor's `field` defaults to `strand`, so its
+     * `color: "steelblue"` is `{ value: "steelblue", scale: "none" }`.
+     */
+    shorthandWith?: Record<string, unknown>;
+    /**
+     * Refuse a snapshot key the schema does not declare, where MST would drop
+     * it in silence. Checked after the `shorthand` lift and before
+     * `preProcessSnapshot`, on the same paths.
+     */
+    closed?: boolean;
+    /** A colour object's scale by `field` while `scale` is unset, `*` for any other. */
+    fieldScale?: Readonly<Record<string, string>>;
     preProcessSnapshot?: (snapshot: Record<string, unknown>) => Record<string, unknown>;
+    requires?: REQUIREMENT[];
 }
 type SchemaHook = (self: unknown) => any;
 /**
@@ -55,45 +78,66 @@ export interface MergedConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigu
     views?: SchemaHook | SchemaHook[];
     extend?: SchemaHook | SchemaHook[];
 }
-declare function makeConfigurationSchemaModel<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends MergedConfigurationSchemaOptions<any, any>>(modelName: string, schemaDefinition: DEFINITION, options: OPTIONS): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<Record<string, any>, {
-    setSubschema(slotName: string, data: Record<string, unknown>): any;
-    setSlot(slotName: string, value: unknown): void;
-}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, [undefined]>;
-export interface ConfigurationSchemaType<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<any, any>> extends ReturnType<typeof makeConfigurationSchemaModel<DEFINITION, OPTIONS>> {
-    type: string;
+declare function makeConfigurationSchemaModel<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends MergedConfigurationSchemaOptions<any, any>>(modelName: string, schemaDefinition: DEFINITION, options: OPTIONS): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<Record<string, any>, ConfigNodeActions, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, [undefined]>;
+/**
+ * DEFINITION is unconstrained on purpose. It carries the *merged* definition —
+ * `MergeConfigDef`, an unresolved conditional that cannot be checked against a
+ * constraint — and intersecting it with `ConfigurationSchemaDefinition` to
+ * satisfy one would put an index signature straight back into
+ * `keyof DEFINITION`. The authoring check lives on `ConfigurationSchema`'s own
+ * parameter, where the literal arrives, and on the `extends` clause below.
+ */
+export interface ConfigurationSchemaType<out DEFINITION, OPTIONS extends ConfigurationSchemaOptions<any, any>> extends ReturnType<typeof makeConfigurationSchemaModel<DEFINITION & ConfigurationSchemaDefinition, OPTIONS>> {
+    /**
+     * Overrides the factory's, whose props come off a `Record<string, any>` and
+     * so admit every name. Slots come from the definition — the identifier and
+     * an `explicitlyTyped` schema's `type` ride in as two of them — and the brand
+     * names this schema, which is what `ConfigurationSchemaForModel` infers back
+     * out.
+     */
+    readonly Type: ConfigNodeProps<DEFINITION> & ConfigNodeActions & ConfigNodeBrand<this>;
 }
-export declare function ConfigurationSchema<const DEFINITION extends ConfigurationSchemaDefinition, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>): ConfigurationSchemaType<DEFINITION, ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>>;
+type RequirementPath<D> = {
+    [K in keyof D & string]: K | (D[K] extends ConfigurationSchemaType<infer SUB, any> ? `${K}.${RequirementPath<SUB>}` : never);
+}[keyof D & string];
+type RequirementWhen<D> = {
+    [K in keyof D & string as D[K] extends {
+        type: string;
+    } ? K : never]?: (D[K] extends {
+        model: ISimpleType<infer V extends string>;
+    } ? V : string)[];
+};
+type RequirementOf<D, BASE> = BASE extends ConfigurationSchemaType<infer BD, any> ? ConfigurationSchemaRequirement<RequirementWhen<D> & RequirementWhen<BD>, RequirementPath<D> | RequirementPath<BD>> : ConfigurationSchemaRequirement<RequirementWhen<D>, RequirementPath<D>>;
+export declare function ConfigurationSchema<const DEFINITION extends ConfigurationSchemaDefinition, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined, EXPLICITLY_TYPED extends boolean | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER, EXPLICITLY_TYPED, RequirementOf<NoInfer<DEFINITION>, NoInfer<BASE_SCHEMA>>>): ConfigurationSchemaType<MergeConfigDef<DEFINITION & Record<EXPLICIT_IDENTIFIER & string, IdentifierSlotDef> & (EXPLICITLY_TYPED extends true ? {
+    type: TypeSlotDef;
+} : unknown), BASE_SCHEMA>, ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER, EXPLICITLY_TYPED>>;
 /**
  * #api core/configuration
  * Hydrate a plain track config into a live config node, dispatching on its
  * `type` to find the schema. `session.tracks` holds `types.frozen` plain
- * objects until something references a track (ADR-031), so a caller handed one
- * of those has a config that reads nothing but what was literally authored: a
- * slot at its schema default is absent, `preProcessSnapshot` has not run, and
- * nothing that walks a live node applies to it.
+ * objects until something references a track (ADR-031). One of those holds only
+ * what was literally authored: a slot at its schema default is absent,
+ * `preProcessSnapshot` has not run, and nothing that walks a live node applies
+ * to it.
  *
- * For the callers that need the resolved answer rather than the authored one
- * and cannot know which of the two they were handed. The About dialog's "Copy
- * config" is the case this exists for: it is reached from two menus, and one of
+ * Use it where a caller needs the resolved config and may be handed either
+ * form. The About dialog's "Copy config" is reached from two menus, and one of
  * them passes a `session.tracks` entry.
  *
- * Returns **undefined** rather than throwing when the config names a track type
- * no plugin registered, or when it is invalid enough that `create` rejects it —
- * an un-hydrated config has never been validated, so a dialog that opens over
- * it must not be the thing that discovers this. Callers fall back to treating
- * it as the plain object it is.
+ * Returns **undefined** when the config names a track type no plugin
+ * registered, or when `create` rejects it as invalid. An un-hydrated config has
+ * never been validated, so the dialog opening over it should not throw. Callers
+ * fall back to using the plain object.
  *
  * Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating
- * the same entry twice returns the same node — and in admin/embedded sessions a
- * track opened later resolves to that same node. A non-admin's open track does
- * not: it resolves to the session's private working copy (ADR-032) and this is
- * the pristine mirror beside it. The two agree in content, which is what the
- * caller needs; `CopyConfigEntryPoints.test.ts` pins both halves.
+ * the same entry twice returns the same node, and in an admin session a track
+ * opened later resolves to that same node. A non-admin's open track
+ * resolves to the session's private working copy (ADR-032), and this function
+ * returns the pristine mirror beside it. The two have the same content;
+ * `CopyConfigEntryPoints.test.ts` tests both cases.
  */
 export declare function hydrateTrackConfig(pluginManager: PluginManager, config: Record<string, unknown>): AnyConfigurationModel | undefined;
-type ConfigReferenceInstance<SCHEMA extends AnyConfigurationSchemaType> = (SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? any : SCHEMA['Type'] : SCHEMA['Type']) & {
-    [K in GetInheritedIdentifier<SCHEMA>]: string;
-};
+type ConfigReferenceInstance<SCHEMA extends AnyConfigurationSchemaType> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? any : SCHEMA['Type'] : SCHEMA['Type'];
 /**
  * Static type of the value `ConfigurationReference` produces, and therefore of a
  * track/display state model's `configuration` prop. Its **instance** type is a

package/esm/configuration/configurationSchema.js

@@ -1,9 +1,11 @@
 import { getEnv, isArrayType, isMapType, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
 import { getContainingTrack, getSession } from '../util/mstUtils.js';
 import { ElementId } from '../util/types/mst.js';
-import ConfigSlot from './configurationSlot.js';
+import ConfigSlot, { slotWriteRefusal } from './configurationSlot.js';
+import { checkRequirements } from './requirements.js';
 import { getConfigurationSchemaMetadata, registerConfigurationSchema, } from './schemaRegistry.js';
-import { isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
+import { identifierName, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
 function hookList(hook) {
     return hook === undefined ? [] : Array.isArray(hook) ? hook : [hook];
 }
@@ -86,24 +88,17 @@ function preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition
 function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     // now assemble the MST model of the configuration schema
     const modelDefinition = {};
-    let identifier;
     if (options.explicitlyTyped) {
         modelDefinition.type = types.optional(types.literal(modelName), modelName);
     }
     if (options.explicitIdentifier && options.implicitIdentifier) {
         throw new Error(`Cannot have both explicit and implicit identifiers in ${modelName}`);
     }
-    // explicit identifiers are plain MST identifiers (caller-supplied id);
-    // implicit identifiers auto-generate via ElementId. Both name the field after
-    // the option string, or default to `id` when the option is just `true`.
-    const idSpec = options.explicitIdentifier
-        ? { name: options.explicitIdentifier, idType: types.identifier }
-        : options.implicitIdentifier
-            ? { name: options.implicitIdentifier, idType: ElementId }
-            : undefined;
-    if (idSpec) {
-        identifier = typeof idSpec.name === 'string' ? idSpec.name : 'id';
-        modelDefinition[identifier] = idSpec.idType;
+    const identifier = identifierName(options);
+    if (identifier) {
+        modelDefinition[identifier] = options.explicitIdentifier
+            ? types.identifier
+            : ElementId;
     }
     // String/number entries in the schema definition become volatile instance
     // constants (read via `model.someName`). Per-slot metadata lives in the
@@ -116,10 +111,17 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     // excluded here — collected as the loop classifies each entry rather than
     // re-scanning modelDefinition afterward.
     const subSchemaKeys = new Set();
+    // Keys of array-of-sub-schema slots, which `setSubschemaArray` replaces
+    // whole: a menu that authors a list of sub-schemas — the mark display's
+    // `marks` — has no slot to write and no single node to swap.
+    const arraySubSchemaKeys = new Set();
     // The actual slots, which is a strictly smaller set than `modelDefinition`:
     // that also holds the sub-schema properties and the identifier, neither of
     // which setSlot may write. Same collect-as-you-classify as subSchemaKeys.
     const slotKeys = new Set();
+    const storesNull = new Set();
+    const featureFields = new Set();
+    const takesNoCallback = new Map();
     for (const [slotName, slotDefinition] of Object.entries(schemaDefinition)) {
         if (isConfigurationSchemaType(slotDefinition)) {
             // a sub-configuration. A bare sub-schema is already stripDefault-wrapped
@@ -128,6 +130,7 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             // snapshot.
             if (isArrayType(slotDefinition)) {
                 modelDefinition[slotName] = types.stripDefault(slotDefinition, []);
+                arraySubSchemaKeys.add(slotName);
             }
             else if (isMapType(slotDefinition)) {
                 modelDefinition[slotName] = types.stripDefault(slotDefinition, {});
@@ -145,6 +148,15 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             slotKeys.add(slotName);
             try {
                 modelDefinition[slotName] = ConfigSlot(slotDefinition);
+                if (modelDefinition[slotName].is(null)) {
+                    storesNull.add(slotName);
+                }
+                if (slotDefinition.type === 'featureField') {
+                    featureFields.add(slotName);
+                }
+                else if (!slotDefinition.contextVariable?.length) {
+                    takesNoCallback.set(slotName, slotDefinition.type);
+                }
             }
             catch (e) {
                 throw new Error(`invalid config slot definition for ${modelName}.${slotName}: ${e}`, { cause: e });
@@ -159,9 +171,15 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             throw new Error(`invalid configuration schema definition, "${slotName}" must be either a valid configuration slot definition, a constant, or a nested configuration schema`);
         }
     }
+    checkRequirements(modelName, schemaDefinition, options.requires ?? []);
     let completeModel = types
         .model(`${modelName}ConfigurationSchema`, modelDefinition)
-        .actions(self => ({
+        // annotated so `ConfigurationSchemaType['Type']`, which has to name these
+        // three by hand (the model's own props are a `Record<string, any>`, so
+        // nothing derived off them keeps a signature), cannot drift from them
+        .actions((self) => ({
+        // `data` is whatever the sub-schema's `preProcessSnapshot` takes, a
+        // string shorthand included.
         setSubschema(slotName, data) {
             if (!subSchemaKeys.has(slotName)) {
                 throw new Error(`${slotName} is not a subschema, cannot replace`);
@@ -172,6 +190,12 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             self[slotName] = newSchema;
             return newSchema;
         },
+        setSubschemaArray(slotName, data) {
+            if (!arraySubSchemaKeys.has(slotName)) {
+                throw new Error(`${slotName} is not an array of subschemas, cannot replace`);
+            }
+            self[slotName] = data;
+        },
         // generic slot setter the config editor's slot facade routes through. A
         // slot is a bare value-union property, so this is a plain assignment.
         //
@@ -181,7 +205,14 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
         // Slot-name safety is a write guard (ADR-052); `setSlot`'s tests in
         // `configurationSchema.test.ts` pin both halves. `slotKeys` already has
         // base-schema slots merged in, so an inherited slot passes.
-        setSlot(slotName, value) {
+        // `null` resets, the same thing `undefined` does, because a JSON-borne
+        // caller cannot spell `undefined`: a session spec, share link or agent
+        // call can set a slot and then has no way to put it back. Omitting the
+        // key is not that — this action is the merge path, where an absent key
+        // means "leave it alone". A sub-schema already reads `null` this way
+        // (`mergedSubschemaValue`), and no slot stores `null` as a value.
+        setSlot(slotName, rawValue) {
+            const value = rawValue ?? undefined;
             if (!slotKeys.has(slotName)) {
                 // the sub-schema branch re-classifies off the definition rather than
                 // carrying a second Set: it runs only on the way to a throw, and the
@@ -203,7 +234,7 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
                 const slotType = isSlotDefinitionEntry(declared)
                     ? declared.type
                     : 'value';
-                throw new Error(`${modelName}.${slotName} is a ${slotType} slot and cannot take ${JSON.stringify(value)}`);
+                throw new Error(slotWriteRefusal(`${modelName}.${slotName}`, slotType, value));
             }
             self[slotName] = value;
         },
@@ -222,9 +253,15 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     for (const hook of hookList(options.extend)) {
         completeModel = completeModel.extend(hook);
     }
-    if (options.preProcessSnapshot) {
-        completeModel = completeModel.preProcessSnapshot(options.preProcessSnapshot);
-    }
+    const metadata = {
+        name: modelName,
+        definition: schemaDefinition,
+        options,
+        storesNull,
+        featureFields,
+        takesNoCallback,
+    };
+    completeModel = completeModel.preProcessSnapshot(snapshot => preProcessSnapshotWith(metadata, snapshot));
     const identifierDefault = identifier ? { [identifier]: 'placeholderId' } : {};
     const modelDefault = options.explicitlyTyped
         ? { type: modelName, ...identifierDefault }
@@ -237,7 +274,6 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     // returns for a live config — the config editor's slot facade looks it up
     // from there) and the stripDefault wrapper (what ConfigurationSchema returns
     // and what sub-schema properties hold), so a lookup succeeds from either.
-    const metadata = { definition: schemaDefinition, options };
     registerConfigurationSchema(completeModel, metadata);
     registerConfigurationSchema(wrappedModel, metadata);
     return wrappedModel;
@@ -259,28 +295,26 @@ function hydrateInto(pluginManager, schemaType, frozen) {
  * #api core/configuration
  * Hydrate a plain track config into a live config node, dispatching on its
  * `type` to find the schema. `session.tracks` holds `types.frozen` plain
- * objects until something references a track (ADR-031), so a caller handed one
- * of those has a config that reads nothing but what was literally authored: a
- * slot at its schema default is absent, `preProcessSnapshot` has not run, and
- * nothing that walks a live node applies to it.
+ * objects until something references a track (ADR-031). One of those holds only
+ * what was literally authored: a slot at its schema default is absent,
+ * `preProcessSnapshot` has not run, and nothing that walks a live node applies
+ * to it.
  *
- * For the callers that need the resolved answer rather than the authored one
- * and cannot know which of the two they were handed. The About dialog's "Copy
- * config" is the case this exists for: it is reached from two menus, and one of
+ * Use it where a caller needs the resolved config and may be handed either
+ * form. The About dialog's "Copy config" is reached from two menus, and one of
  * them passes a `session.tracks` entry.
  *
- * Returns **undefined** rather than throwing when the config names a track type
- * no plugin registered, or when it is invalid enough that `create` rejects it —
- * an un-hydrated config has never been validated, so a dialog that opens over
- * it must not be the thing that discovers this. Callers fall back to treating
- * it as the plain object it is.
+ * Returns **undefined** when the config names a track type no plugin
+ * registered, or when `create` rejects it as invalid. An un-hydrated config has
+ * never been validated, so the dialog opening over it should not throw. Callers
+ * fall back to using the plain object.
  *
  * Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating
- * the same entry twice returns the same node — and in admin/embedded sessions a
- * track opened later resolves to that same node. A non-admin's open track does
- * not: it resolves to the session's private working copy (ADR-032) and this is
- * the pristine mirror beside it. The two agree in content, which is what the
- * caller needs; `CopyConfigEntryPoints.test.ts` pins both halves.
+ * the same entry twice returns the same node, and in an admin session a track
+ * opened later resolves to that same node. A non-admin's open track
+ * resolves to the session's private working copy (ADR-032), and this function
+ * returns the pristine mirror beside it. The two have the same content;
+ * `CopyConfigEntryPoints.test.ts` tests both cases.
  */
 export function hydrateTrackConfig(pluginManager, config) {
     const type = config.type;
@@ -349,8 +383,8 @@ function TrackConfigurationReference(schemaType) {
             if (!isStateTreeNode(ret)) {
                 // A non-admin session hands back a private, per-track working copy so a
                 // shown track's in-place quick-edits (setSlot) mutate that copy and
-                // never the shared frozen base node (see agent-docs/ADR-032). Admin and
-                // embedded sessions return undefined here and fall through to the frozen
+                // never the shared frozen base node (see agent-docs/ADR-032). An admin
+                // session returns undefined here and falls through to the frozen
                 // hydration cache (ADR-031) — admin edits the frozen entry in place.
                 const editable = session.getEditableTrackConfig?.(String(id), ret, schemaType);
                 if (editable) {

package/esm/configuration/configurationSchemaUnion.d.ts

@@ -0,0 +1,39 @@
+import type { ConfigurationSchemaOptions, ConfigurationSchemaType } from './configurationSchema.ts';
+import type { AnyConfigurationSchemaType } from './types.ts';
+import type { IAnyType, ISimpleType, IType, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+interface NamedTypeSlotDef<NAME extends string> {
+    type: 'stringEnum';
+    model: ISimpleType<NAME>;
+}
+type Named<SCHEMA, NAME extends string> = SCHEMA extends ConfigurationSchemaType<infer D, infer O extends ConfigurationSchemaOptions<any, any>> ? ConfigurationSchemaType<{
+    [K in keyof D]: K extends 'type' ? NamedTypeSlotDef<NAME> : D[K];
+}, O> : never;
+type UnionNode<MEMBERS> = {
+    [K in keyof MEMBERS & string]: Named<MEMBERS[K], K>['Type'];
+}[keyof MEMBERS & string];
+/**
+ * A union of configuration schemas, each member's node reading its `type` as
+ * the key it is listed under — so a `switch` over it narrows to that member's
+ * own slots.
+ */
+export type ConfigurationSchemaUnionType<MEMBERS extends Record<string, AnyConfigurationSchemaType>> = Omit<IType<SnapshotIn<MEMBERS[keyof MEMBERS]>, SnapshotOut<MEMBERS[keyof MEMBERS]>, UnionNode<MEMBERS>>, 'Type'> & {
+    readonly Type: UnionNode<MEMBERS>;
+};
+/**
+ * #api core/configuration
+ * A list entry that is one of several configuration schemas, each keyed by the
+ * `type` it answers to: `types.array(ConfigurationSchemaUnion('Step', { filter,
+ * bin }))`. The keys are the vocabulary, the snapshot's `type` picks the
+ * member, and a `type` naming no member is refused in every build — where a
+ * bare `types.union` would load it as its first member. Each member is an
+ * `explicitlyTyped`, `closed` schema named by its key, so a key belonging to
+ * another member is refused rather than dropped; one that is not throws here.
+ */
+export declare function ConfigurationSchemaUnion<const MEMBERS extends Record<string, AnyConfigurationSchemaType>>(name: string, members: MEMBERS): ConfigurationSchemaUnionType<MEMBERS>;
+/**
+ * #api core/configuration
+ * The `ConfigurationSchemaUnion` an array slot's entries answer to, read off
+ * the slot's MST type, or undefined for any other slot.
+ */
+export declare function arraySlotUnion(slotType: IAnyType): import("./schemaRegistry.ts").ConfigurationSchemaUnionMetadata | undefined;
+export {};

package/esm/configuration/configurationSchemaUnion.js

@@ -0,0 +1,59 @@
+import { isArrayType, isOptionalType, types } from '@jbrowse/mobx-state-tree';
+import { getSubType } from '../util/mst-reflection.js';
+import { getConfigurationSchemaMetadata, getConfigurationSchemaUnion, registerConfigurationSchemaUnion, } from './schemaRegistry.js';
+import { listed } from './snapshotPreprocess.js';
+function memberRefusal(key, member) {
+    const meta = getConfigurationSchemaMetadata(member);
+    return !meta
+        ? 'which is not a configuration schema'
+        : meta.name !== key
+            ? `whose schema names itself "${meta.name}"`
+            : !meta.options.explicitlyTyped
+                ? 'which is not explicitlyTyped, so its snapshot names no type to dispatch on'
+                : !meta.options.closed
+                    ? 'which is not closed, so a key of another member would be dropped in silence'
+                    : undefined;
+}
+/**
+ * #api core/configuration
+ * A list entry that is one of several configuration schemas, each keyed by the
+ * `type` it answers to: `types.array(ConfigurationSchemaUnion('Step', { filter,
+ * bin }))`. The keys are the vocabulary, the snapshot's `type` picks the
+ * member, and a `type` naming no member is refused in every build — where a
+ * bare `types.union` would load it as its first member. Each member is an
+ * `explicitlyTyped`, `closed` schema named by its key, so a key belonging to
+ * another member is refused rather than dropped; one that is not throws here.
+ */
+export function ConfigurationSchemaUnion(name, members) {
+    for (const [key, member] of Object.entries(members)) {
+        const refusal = memberRefusal(key, member);
+        if (refusal) {
+            throw new Error(`${name} lists "${key}", ${refusal}`);
+        }
+    }
+    const names = Object.keys(members);
+    const union = types.union({
+        dispatcher: (snapshot) => {
+            const type = snapshot?.type;
+            if (typeof type === 'string' && Object.hasOwn(members, type)) {
+                return members[type];
+            }
+            throw new Error(`a ${name} names its type, one of ${listed(names)}, ${type === undefined
+                ? 'and names none'
+                : `not ${JSON.stringify(type)}`}`);
+        },
+    }, ...Object.values(members));
+    registerConfigurationSchemaUnion(union, { name, members });
+    return union;
+}
+/**
+ * #api core/configuration
+ * The `ConfigurationSchemaUnion` an array slot's entries answer to, read off
+ * the slot's MST type, or undefined for any other slot.
+ */
+export function arraySlotUnion(slotType) {
+    const array = isOptionalType(slotType) ? getSubType(slotType) : slotType;
+    return isArrayType(array)
+        ? getConfigurationSchemaUnion(array.getChildType())
+        : undefined;
+}

package/esm/configuration/configurationSlot.d.ts

@@ -5,6 +5,10 @@ declare const slotTypes: {
         model: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
         fallbackDefault: never[];
     };
+    colorArray: {
+        model: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        fallbackDefault: never[];
+    };
     stringArrayMap: {
         model: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>>;
         fallbackDefault: {};
@@ -41,6 +45,9 @@ declare const slotTypes: {
     maybeFrozen: {
         model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IType<any, any, any>>;
     };
+    maybeString: {
+        model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    };
     string: {
         model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         fallbackDefault: string;
@@ -49,6 +56,10 @@ declare const slotTypes: {
         model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         fallbackDefault: string;
     };
+    featureField: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        fallbackDefault: string;
+    };
     fileLocation: {
         model: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<{
             locationType: "LocalPathLocation";
@@ -146,10 +157,10 @@ declare const slotTypes: {
  * `types.ts`, which has to name the same set and is checked against this.
  */
 export type BuiltinSlotTypeName = keyof typeof slotTypes;
-declare const ENUM_SLOT_TYPES: readonly ['stringEnum', 'maybeStringEnum'];
+declare const ENUM_SLOT_TYPES: readonly ['stringEnum', 'maybeStringEnum', 'stringEnumArray'];
 /**
  * Every legal `type` on a slot definition: the builtin table's own names, plus
- * the two enum types.
+ * the enum types.
  *
  * Closed on purpose. A name outside this set still *works* at runtime as long
  * as a `model` is given — which is exactly the trap: the value round-trips
@@ -167,12 +178,17 @@ type MaybeBuiltinSlotTypeName = {
     [K in keyof typeof slotTypes]: 'fallbackDefault' extends keyof (typeof slotTypes)[K] ? never : K;
 }[keyof typeof slotTypes];
 export type MaybeSlotTypeName = MaybeBuiltinSlotTypeName | 'maybeStringEnum';
+/** Why the slot `name`, of type `type`, refuses `value` on a write. */
+export declare function slotWriteRefusal(name: string, type: string, value: unknown): string;
 interface ConfigSlotDefinitionCommon {
     /** human-readable description of the slot's meaning */
     description?: string;
     /** custom base MST model for the slot's value */
     model?: IAnyType;
-    /** parameter names of the function callback */
+    /**
+     * The names a `jexl:` callback in this slot reads. Declaring any is what
+     * makes the slot take a callback; every other slot refuses one.
+     */
     contextVariable?: string[];
     /**
      * hide this slot behind a "Show advanced settings" toggle in the config
@@ -211,16 +227,25 @@ export type ConfigSlotDefinition = (ConfigSlotDefinitionCommon & {
     defaultValue: unknown;
 });
 /**
- * A configuration slot is a plain value-union MST property: the slot's value
- * type, OR a `jexl:...` callback string. The value lives directly on the parent
- * configuration model — there is no per-slot sub-model. `types.stripDefault`
- * omits the property from the parent snapshot when it equals the default, so
- * saved sessions stay minimal. Per-slot metadata
- * (type/description/defaultValue/contextVariable) lives in the schema registry
- * (a WeakMap keyed by the MST type, see schemaRegistry.ts); jexl callbacks are
- * evaluated on read by `readConfObject`.
+ * A configuration slot is a plain MST property holding the slot's value type,
+ * or, where the slot declares a `contextVariable`, that or a `jexl:...`
+ * callback string. Every other slot refuses a `jexl:` string, so a callback
+ * the reader would evaluate is one the schema says it takes. A `featureField`
+ * holds a `jexl:` expression as its value, which the display evaluates per
+ * feature. The value lives directly on the parent configuration model — there
+ * is no per-slot sub-model. `types.stripDefault` omits the property from the
+ * parent snapshot when it equals the default, so saved sessions stay minimal.
+ * Per-slot metadata (type/description/defaultValue/contextVariable) lives in
+ * the schema registry (a WeakMap keyed by the MST type, see
+ * schemaRegistry.ts); jexl callbacks are evaluated on read by
+ * `readConfObject`.
+ *
+ * Interning the returned type on `(type, model, defaultValue)` was prototyped
+ * and declined: a session builds 1197 slot types for 222 distinct ones, and
+ * removing the repeats moves neither the time nor the heap
+ * (`config-schema-construction`, published in `reference/EAGER_BUNDLE.md`).
  */
-export default function ConfigSlot(definition: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, [undefined]>;
+export default function ConfigSlot(definition: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<IAnyType, [undefined]>;
 /**
  * New value when converting a fixed-value slot to a jexl callback. Already-
  * callback values are returned unchanged.