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

package/esm/configuration/configurationSchema.js

@@ -1,9 +1,12 @@
-import { getEnv, isArrayType, isMapType, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
+import { getEnv, isArrayType, isMapType, isOptionalType, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
+import { isObservableArray } from 'mobx';
 import { getContainingTrack, getSession } from '../util/mstUtils.js';
-import { ElementId } from '../util/types/mst.js';
-import ConfigSlot from './configurationSlot.js';
+import { isSessionWithEditableTrackConfig } from '../util/types/index.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 { isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, shorthandTargetsOf, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
 function hookList(hook) {
     return hook === undefined ? [] : Array.isArray(hook) ? hook : [hook];
 }
@@ -20,12 +23,8 @@ function chainHooks(base, child) {
  * **redeclares merges field-by-field over the base's** — so an override states
  * only what actually differs and inherits the rest. (`type` comes along
  * regardless: it is what marks an entry as a slot rather than a nested
- * sub-schema, per `isSlotDefinitionEntry`.)
- *
- * A subclass that really wants a plain slot states `promotedBase: undefined`,
- * which works *because* this is a spread: a stated `undefined` overwrites the
- * base's value where an omitted key would inherit it. The four cases are pinned
- * by the "baseConfiguration slot override merge" tests.
+ * sub-schema, per `isSlotDefinitionEntry`.) The cases are pinned by the
+ * "baseConfiguration slot override merge" tests.
  */
 function mergeSchemaDefinition(baseDefinition, childDefinition) {
     const merged = {
@@ -42,6 +41,19 @@ function mergeSchemaDefinition(baseDefinition, childDefinition) {
     }
     return merged;
 }
+// No two slots a shorthand names take the same bare form, since a bare value
+// lifts by its form alone. A name may be a key `preProcessSnapshot` expands
+// rather than a slot, as an assembly sidecar's `uri` is.
+function checkShorthand(modelName, definition, shorthand) {
+    const slots = shorthand === undefined
+        ? []
+        : typeof shorthand === 'string'
+            ? [shorthand]
+            : shorthand;
+    if (Object.keys(shorthandTargetsOf(definition, shorthand)).length < slots.length) {
+        throw new Error(`${modelName}'s shorthand names ${slots.join(' and ')}, which take the same bare form, so a bare value could not say which it means`);
+    }
+}
 function preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition, inputOptions = {}) {
     if (typeof modelName !== 'string') {
         throw new Error('first arg must be string name of the model that this config schema goes with');
@@ -55,24 +67,29 @@ function preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition
         : undefined;
     // A base with no registry entry used to be skipped in silence, producing a
     // schema missing every inherited slot with nothing thrown anywhere, and
-    // reachable without doing anything obviously wrong: `isBareConfigurationSchemaType`
-    // answers true for a `types.late` wrapper, and
-    // `pluginManager.pluggableConfigSchemaType(…)` hands back a `types.union`.
-    // Neither is registered, because only the type `ConfigurationSchema` itself
-    // returns carries the slot table.
+    // reachable without doing anything obviously wrong:
+    // `pluginManager.pluggableConfigSchemaType(…)` hands back a `types.union`,
+    // which carries no slot table of its own.
     if (inputOptions.baseConfiguration && !baseMeta) {
-        throw new Error(`${modelName}'s baseConfiguration is not a configuration schema: it has no registered slot table, so every slot it was meant to inherit would be dropped silently. Pass the type ConfigurationSchema() returned, not a types.late wrapper, a union (pluginManager.pluggableConfigSchemaType), or a plain MST model.`);
+        throw new Error(`${modelName}'s baseConfiguration is not a configuration schema: it has no registered slot table, so every slot it was meant to inherit would be dropped silently. Pass the type ConfigurationSchema() returned, not a union (pluginManager.pluggableConfigSchemaType) or a plain MST model.`);
     }
     if (baseMeta) {
         schemaDefinition = mergeSchemaDefinition(baseMeta.definition, schemaDefinition);
         // Everything else merges as a shallow `{...base, ...child}` spread, where
-        // the child's value replaces the base's. The four hooks below must not:
-        // `createBaseTrackConfig` alone declares two of them, so replace-semantics
-        // meant no track config schema could ever declare its own without silently
-        // dropping display-stub injection and the legacy-key migration. They
-        // compose instead, base first. See MergedConfigurationSchemaOptions.
+        // the child's value replaces the base's. The four hooks, `requires` and
+        // `retired` must not: `createBaseTrackConfig` alone declares two of the hooks, so
+        // replace-semantics meant no track config schema could ever declare its
+        // own without silently dropping display-stub injection and the legacy-key
+        // migration, and a subclass stating one requirement would have dropped
+        // every one its base stated. They compose instead, base first, and
+        // `retired` merges per key so a subclass adds a spelling without dropping
+        // the ones its base retired. See MergedConfigurationSchemaOptions.
         const basePreProcess = baseMeta.options.preProcessSnapshot;
         const childPreProcess = inputOptions.preProcessSnapshot;
+        const requires = [
+            ...(baseMeta.options.requires ?? []),
+            ...(inputOptions.requires ?? []),
+        ];
         options = {
             ...baseMeta.options,
             ...inputOptions,
@@ -83,6 +100,10 @@ function preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition
             preProcessSnapshot: basePreProcess && childPreProcess
                 ? snapshot => childPreProcess(basePreProcess(snapshot))
                 : (childPreProcess ?? basePreProcess),
+            retired: baseMeta.options.retired || inputOptions.retired
+                ? { ...baseMeta.options.retired, ...inputOptions.retired }
+                : undefined,
+            requires: requires.length ? requires : undefined,
         };
     }
     return { schemaDefinition, options };
@@ -90,51 +111,42 @@ 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 = options.explicitIdentifier;
+    if (identifier) {
+        modelDefinition[identifier] = types.identifier;
     }
     // String/number entries in the schema definition become volatile instance
     // constants (read via `model.someName`). Per-slot metadata lives in the
     // schema registry (a WeakMap keyed by the MST type, see schemaRegistry.ts),
     // not on the instance.
     const volatileConstants = {};
-    // Keys of single sub-schema slots (not array/map-of-sub-schema). setSubschema
-    // replaces such a node via `.create(data)`, which throws a confusing MST
-    // validation error if pointed at an array/map-typed slot, so those are
-    // excluded here — collected as the loop classifies each entry rather than
-    // re-scanning modelDefinition afterward.
+    // The members `setSubschema` replaces: a single sub-schema, swapped for a
+    // node built from the data, or a collection of them, assigned whole so MST
+    // reconciles the entries. Collected as the loop classifies each entry.
     const subSchemaKeys = new Set();
+    const collectionKeys = 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
             // (so it strips when all-default); an array/map of sub-schemas gets
-            // wrapped so an empty/default collection is likewise omitted from the
-            // snapshot.
-            if (isArrayType(slotDefinition)) {
-                modelDefinition[slotName] = types.stripDefault(slotDefinition, []);
-            }
-            else if (isMapType(slotDefinition)) {
-                modelDefinition[slotName] = types.stripDefault(slotDefinition, {});
+            // wrapped so an empty collection is likewise omitted from the snapshot,
+            // unless it is wrapped in a default of its own: a display built on
+            // another names its own default plot that way.
+            if (isArrayType(slotDefinition) || isMapType(slotDefinition)) {
+                modelDefinition[slotName] = isOptionalType(slotDefinition)
+                    ? slotDefinition
+                    : types.stripDefault(slotDefinition, isArrayType(slotDefinition) ? [] : {});
+                collectionKeys.add(slotName);
             }
             else {
                 modelDefinition[slotName] = slotDefinition;
@@ -149,6 +161,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 });
@@ -163,10 +184,23 @@ 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 ?? []);
+    checkShorthand(modelName, schemaDefinition, options.shorthand);
     let completeModel = types
         .model(`${modelName}ConfigurationSchema`, modelDefinition)
-        .actions(self => ({
+        // annotated so `ConfigurationSchemaType['Type']`, which has to name these
+        // two 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) => ({
+        // Replace a sub-schema member whole. `data` is whatever the sub-schema's
+        // `preProcessSnapshot` takes, a string shorthand included; for a
+        // collection it is the whole list or map, and `null` resets it to its
+        // default, empty unless the collection names one.
         setSubschema(slotName, data) {
+            if (collectionKeys.has(slotName)) {
+                self[slotName] = data ?? undefined;
+                return self[slotName];
+            }
             if (!subSchemaKeys.has(slotName)) {
                 throw new Error(`${slotName} is not a subschema, cannot replace`);
             }
@@ -177,7 +211,8 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             return newSchema;
         },
         // 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.
+        // slot is a bare value-union property, so this is a plain assignment,
+        // save an array, which `refillArray` writes.
         //
         // **Don't weaken the membership check to a warning, and don't check
         // against `modelDefinition`** — that also holds the identifier and the
@@ -185,7 +220,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 reads `null` the same way, 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
@@ -198,7 +240,24 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
                         .sort()
                         .join(', ')}`);
             }
-            self[slotName] = value;
+            // MST skips its own type check in a production build, and a value the
+            // slot's union cannot take is then dropped with no throw: the write
+            // reported success and the slot kept its old value. `is` still runs
+            // there, so the guard holds in both builds.
+            if (!modelDefinition[slotName].is(value)) {
+                const declared = schemaDefinition[slotName];
+                const slotType = isSlotDefinitionEntry(declared)
+                    ? declared.type
+                    : 'value';
+                throw new Error(slotWriteRefusal(`${modelName}.${slotName}`, slotType, value));
+            }
+            const held = self[slotName];
+            if (isObservableArray(held) && Array.isArray(value)) {
+                refillArray(held, value);
+            }
+            else {
+                self[slotName] = value;
+            }
         },
     }));
     if (Object.keys(volatileConstants).length) {
@@ -215,9 +274,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 }
@@ -225,73 +290,58 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     // stripDefault (not optional) so a nested all-default sub-schema is omitted
     // from its parent's snapshot: the slot props strip themselves, the sub-schema
     // collapses to its default, and the parent's stripDefault drops the key.
-    const wrappedModel = types.stripDefault(completeModel, modelDefault);
-    // Register metadata against BOTH handles: the inner model (what getType(node)
-    // 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;
+    return types.stripDefault(completeModel, modelDefault);
+}
+// Assigning an array makes MST reconcile it, scanning ahead for a node to reuse
+// at each mismatch: seconds for a reorder of 5,000 row names. A slot array
+// holds scalars, so no reused node keeps anything of its own, and emptying and
+// refilling it takes 50 ms for the 5,000. spliceWithArray, since spreading into
+// `push` overflows the stack past about 120,000 names. An unchanged array is
+// left alone, so it fires no observer.
+function refillArray(held, value) {
+    if (held.length !== value.length || held.some((v, i) => v !== value[i])) {
+        held.clear();
+        held.spliceWithArray(0, 0, value);
+    }
 }
 export function ConfigurationSchema(modelName, inputSchemaDefinition, inputOptions) {
     const { schemaDefinition, options } = preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition, inputOptions);
     return makeConfigurationSchemaModel(modelName, schemaDefinition, options);
 }
-// The hydration cache lives on the PluginManager instance (see
-// trackConfigHydrationCache's doc comment there and ADR-031), not as a
-// module-level singleton: it must never hand a track resolved on one
-// PluginManager instance a node built with another instance's env, and
-// scoping it to the instance rules that out structurally rather than by
-// convention. Nested a second level by schemaType, since one PluginManager
-// registers a distinct schemaType per track type.
-function frozenTrackHydrationCache(pluginManager, schemaType) {
-    const byType = pluginManager.trackConfigHydrationCache;
-    let cache = byType.get(schemaType);
-    if (!cache) {
-        cache = new WeakMap();
-        byType.set(schemaType, cache);
-    }
-    return cache;
-}
 // The frozen -> live half of TrackConfigurationReference's `get`, shared with
-// hydrateTrackConfig below so there is one hydration and one cache rather than
-// two that can drift on which env or which key they use.
+// hydrateTrackConfig below so there is one hydration rather than two that can
+// drift on which env they build with. The memo it goes through belongs to the
+// PluginManager instance (ADR-031): a node built with one instance's env must
+// never be handed to another, and `pluginManager.hydratedTrackConfig` scopes
+// that structurally rather than by convention.
 function hydrateInto(pluginManager, schemaType, frozen) {
-    const cache = frozenTrackHydrationCache(pluginManager, schemaType);
-    const cached = cache.get(frozen);
-    if (cached) {
-        return cached;
-    }
-    const model = schemaType.create(frozen, { pluginManager });
-    cache.set(frozen, model);
-    return model;
+    return pluginManager.hydratedTrackConfig(schemaType, frozen, () => schemaType.create(frozen, { pluginManager }));
 }
 /**
  * #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 — the promotable cascade above all — applies
+ * 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 a track that gets opened later
- * reuses it.
+ * 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;
@@ -315,7 +365,18 @@ export function hydrateTrackConfig(pluginManager, config) {
 // config snapshot (held as a standalone schema instance). Both reference kinds
 // resolve to `schemaType` instances, so MST can't auto-dispatch on the instance
 // side — the explicit snapshot dispatcher (string → ref, object → schema)
-// disambiguates. Shared by TrackConfigurationReference/DisplayConfigurationReference.
+// disambiguates. Shared by TrackConfigurationReference/DisplayConfigurationReference,
+// and by neither accident nor oversight NOT by the plain branch — see the note
+// on it in `ConfigurationReference`.
+//
+// One consequence, because both refs' `set` callbacks read as if it were not
+// true: assigning a config **node** here does not store a reference to it. The
+// dispatcher sees a non-string and picks `schemaType`, so MST tries to adopt the
+// node as an inline child — which throws if it already has a parent. `set` is
+// therefore unreachable on both refs (checked by making it throw: 231 suites
+// stayed green), and exists only because MST rejects a custom reference
+// declaring `get` without it. The plain branch, with no dispatcher, does the
+// opposite and stores the reference.
 function idOrSnapshotUnion(ref, schemaType) {
     return types.union({
         dispatcher: snapshot => (typeof snapshot === 'string' ? ref : schemaType),
@@ -335,33 +396,26 @@ function idOrSnapshotUnion(ref, schemaType) {
  * to just the object branch, forcing callers to wrap string ids in
  * `@ts-expect-error`. The inferred union SnapshotIn is `string | SnapshotIn<schema>`.
  */
-export function TrackConfigurationReference(schemaType) {
+function TrackConfigurationReference(schemaType) {
     const trackRef = types.reference(schemaType, {
         get(id, parent) {
             const session = getSession(parent);
+            const trackId = String(id);
             // Per-id lookup: subscribes only to this trackId's derivation, so
-            // resolving one track's config doesn't re-render the others. Derived on
-            // read, so it's fresh during hydration and add-and-show — no dual path.
-            let ret = session.getTrackById(String(id));
+            // resolving one track's config doesn't re-render the others. A session
+            // with track deltas hands back a private, per-track working copy so a
+            // shown track's in-place quick-edits mutate that copy and never the
+            // shared frozen base (ADR-032); any other session falls through to the
+            // frozen hydration cache (ADR-031).
+            const ret = isSessionWithEditableTrackConfig(session)
+                ? session.getEditableTrackConfig(trackId, schemaType)
+                : session.getTrackById(trackId);
             if (!ret) {
                 throw new Error(`Could not resolve trackId "${id}"`);
             }
-            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
-                // hydration cache (ADR-031) — admin edits the frozen entry in place.
-                const editable = session.getEditableTrackConfig?.(String(id), ret, schemaType);
-                if (editable) {
-                    ret = editable;
-                }
-                else {
-                    const env = getEnv(parent);
-                    ret = hydrateInto(env.pluginManager, schemaType, ret);
-                }
-            }
-            return ret;
+            return isStateTreeNode(ret)
+                ? ret
+                : hydrateInto(getEnv(parent).pluginManager, schemaType, ret);
         },
         set(value) {
             return value.trackId;
@@ -381,15 +435,26 @@ export function TrackConfigurationReference(schemaType) {
  * Step 2 is the safety net because `baseTrackConfig.preProcessSnapshot`
  * already injects a stub display for every registered displayType on the
  * track, so a same-type lookup always succeeds at runtime for properly
- * loaded tracks. An older third step auto-created a *detached* config when
- * neither matched — that produced an orphaned MST node whose edits silently
- * didn't persist. Removed in favor of a clear throw, since
- * preProcessSnapshot's injection makes the path effectively dead.
+ * loaded tracks. It is what carries a **renamed display type** across for a
+ * catalog track: the injected stub is named for the new type, the display
+ * model's own `preProcessSnapshot` rewrites the state model's, and the saved
+ * `configuration` id still spells the old name, so only the type match
+ * reconnects them. Not every pre-rename session reaches it — a track config
+ * that itself declares the old display entry keeps that entry's `displayId`
+ * through the alias rewrite (`{ ...d, type: canonical }`) and wins the
+ * first-wins dedupe, so its session resolves by id. An older third step
+ * auto-created a *detached* config when neither matched — that produced an
+ * orphaned MST node whose edits silently didn't persist. Removed in favor of a
+ * clear throw.
  *
- * Union-with-schemaType branch is for the same reason as `TrackConfigurationReference`:
- * `CircularView.addTrackConf` passes inline display configs as MST instances.
+ * The union's schemaType branch is symmetry with `TrackConfigurationReference`
+ * rather than a path anything in tree takes: the two production writers,
+ * `showTrackGeneric` and `BaseTrackModel.replaceDisplay`, both write a
+ * displayId string, because a display config belongs in its track config's
+ * `displays` array. It stays because it costs nothing and because dropping it
+ * narrows `SnapshotIn` for every caller.
  */
-export function DisplayConfigurationReference(schemaType) {
+function DisplayConfigurationReference(schemaType) {
     const displayRef = types.reference(schemaType, {
         get(id, parent) {
             // track.configuration is a hydrated MST node (hydrated lazily via
@@ -443,9 +508,17 @@ export function ConfigurationReference(schemaType) {
         ? TrackConfigurationReference(schemaType)
         : id === 'displayId'
             ? DisplayConfigurationReference(schemaType)
-            : // Plain (non-track/display) ref. The union accepts either an id
-                // string (resolved via `types.reference`) or an inline schema
-                // snapshot (held as a standalone schema instance).
+            : // Plain (non-track/display) ref — internet accounts, connections —
+                // resolved by MST's own identifier lookup rather than through the
+                // session. **Deliberately not `idOrSnapshotUnion`**, even though it is
+                // the same two members: this branch is also handed a *live, in-tree*
+                // config node (`initializeInternetAccount` pushes
+                // `jbrowse.internetAccounts[i]` straight through), and an undispatched
+                // union sends that to the reference member because
+                // `BaseReferenceType.isAssignableFrom` defers to its target type. A
+                // `typeof snapshot === 'string'` dispatcher sends it to the schema
+                // member instead, and MST refuses to adopt a node that already has a
+                // parent. `InternetAccounts.test.ts` is the canary.
                 types.union(types.reference(schemaType), schemaType);
     return ref;
 }

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,56 @@
+import { asArrayType, types } from '@jbrowse/mobx-state-tree';
+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 = asArrayType(slotType);
+    return array ? getConfigurationSchemaUnion(array.getChildType()) : undefined;
+}