@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/configuration/configurationSchema.js

@@ -1,102 +1,207 @@
-import { getEnv, getRoot, getSnapshot, isLateType, isStateTreeNode, isType, resolveIdentifier, types, } from '@jbrowse/mobx-state-tree';
-import ConfigSlot from "./configurationSlot.js";
-import { isConfigurationSchemaType } from "./util.js";
-import { getContainingTrack, getSession } from "../util/index.js";
-import { ElementId } from "../util/types/mst.js";
-function isEmptyObject(thing) {
-    return (typeof thing === 'object' &&
-        !Array.isArray(thing) &&
-        thing !== null &&
-        Object.keys(thing).length === 0);
+import { getEnv, isArrayType, isMapType, isOptionalType, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
+import { isObservableArray } from 'mobx';
+import { getContainingTrack, getSession } from '../util/mstUtils.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, shorthandTargetsOf, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
+function hookList(hook) {
+    return hook === undefined ? [] : Array.isArray(hook) ? hook : [hook];
 }
-function isEmptyArray(thing) {
-    return Array.isArray(thing) && thing.length === 0;
+// base first, then child. Returns the single function unchanged when only one
+// side declares the hook, so the common case never allocates a chain.
+function chainHooks(base, child) {
+    return base && child
+        ? [...hookList(base), ...hookList(child)]
+        : (child ?? base);
+}
+/**
+ * Fold a subclass's schema definition over its `baseConfiguration`'s. New slots
+ * are added and sub-schema entries replaced wholesale, but a slot the subclass
+ * **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`.) The cases are pinned by the
+ * "baseConfiguration slot override merge" tests.
+ */
+function mergeSchemaDefinition(baseDefinition, childDefinition) {
+    const merged = {
+        ...baseDefinition,
+        ...childDefinition,
+    };
+    for (const [slot, childEntry] of Object.entries(childDefinition)) {
+        const baseEntry = baseDefinition[slot];
+        // both sides must be slot definitions: a sub-schema (or a constant) is an
+        // opaque entry with no fields to fold, so it keeps replace semantics
+        if (isSlotDefinitionEntry(baseEntry) && isSlotDefinitionEntry(childEntry)) {
+            merged[slot] = { ...baseEntry, ...childEntry };
+        }
+    }
+    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');
     }
+    // if we have a base configuration schema that we are
+    // extending, grab the slot definitions from that
     let schemaDefinition = inputSchemaDefinition;
     let options = inputOptions;
-    if (inputOptions.baseConfiguration?.jbrowseSchemaDefinition) {
-        schemaDefinition = {
-            ...inputOptions.baseConfiguration.jbrowseSchemaDefinition,
-            ...schemaDefinition,
-        };
+    const baseMeta = inputOptions.baseConfiguration
+        ? getConfigurationSchemaMetadata(inputOptions.baseConfiguration)
+        : 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:
+    // `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 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, `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 = {
-            ...inputOptions.baseConfiguration.jbrowseSchemaOptions,
+            ...baseMeta.options,
             ...inputOptions,
             baseConfiguration: undefined,
+            actions: chainHooks(baseMeta.options.actions, inputOptions.actions),
+            views: chainHooks(baseMeta.options.views, inputOptions.views),
+            extend: chainHooks(baseMeta.options.extend, inputOptions.extend),
+            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 };
 }
 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}`);
-    }
-    if (options.explicitIdentifier) {
-        if (typeof options.explicitIdentifier === 'string') {
-            modelDefinition[options.explicitIdentifier] = types.identifier;
-            identifier = options.explicitIdentifier;
-        }
-        else {
-            modelDefinition.id = types.identifier;
-            identifier = 'id';
-        }
-    }
-    else if (options.implicitIdentifier) {
-        if (typeof options.implicitIdentifier === 'string') {
-            modelDefinition[options.implicitIdentifier] = ElementId;
-            identifier = options.implicitIdentifier;
-        }
-        else {
-            modelDefinition.id = ElementId;
-            identifier = 'id';
-        }
+    const identifier = options.explicitIdentifier;
+    if (identifier) {
+        modelDefinition[identifier] = types.identifier;
     }
-    const volatileConstants = {
-        isJBrowseConfigurationSchema: true,
-        jbrowseSchema: {
-            modelName,
-            definition: schemaDefinition,
-            options,
-        },
-    };
+    // 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 = {};
+    // 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 ((isType(slotDefinition) && isLateType(slotDefinition)) ||
-            isConfigurationSchemaType(slotDefinition)) {
-            modelDefinition[slotName] = slotDefinition;
+        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 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;
+                subSchemaKeys.add(slotName);
+            }
         }
-        else if (typeof slotDefinition === 'string' ||
-            typeof slotDefinition === 'number') {
+        else if (isConstantEntry(slotDefinition)) {
             volatileConstants[slotName] = slotDefinition;
         }
-        else if (typeof slotDefinition === 'object') {
-            if (!slotDefinition.type) {
-                throw new Error(`no type set for config slot ${modelName}.${slotName}`);
-            }
+        else if (isSlotDefinitionEntry(slotDefinition)) {
+            // slotDefinition is narrowed to ConfigSlotDefinition here (no cast)
+            slotKeys.add(slotName);
             try {
-                modelDefinition[slotName] = ConfigSlot(slotName, slotDefinition);
+                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}`);
+                throw new Error(`invalid config slot definition for ${modelName}.${slotName}: ${e}`, { cause: e });
             }
         }
+        else if (typeof slotDefinition === 'object') {
+            // an object that's neither a sub-schema nor a slot is almost always a
+            // slot definition missing its required `type` field
+            throw new Error(`no type set for config slot ${modelName}.${slotName}`);
+        }
         else {
             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 (!isConfigurationSchemaType(modelDefinition[slotName])) {
+            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`);
             }
             const newSchema = isStateTreeNode(data)
@@ -105,126 +210,315 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             self[slotName] = newSchema;
             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,
+        // 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
+        // sub-schema properties, neither of which is a write this action is for.
+        // 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.
+        // `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
+                // predicate is the same one the loop above classified with
+                throw new Error(isConfigurationSchemaType(schemaDefinition[slotName])
+                    ? `${slotName} is a sub-schema on ${modelName}, not a config slot — replace it with setSubschema`
+                    : `${modelName} has no config slot "${slotName}". Valid slots: ${[
+                        ...slotKeys,
+                    ]
+                        .sort()
+                        .join(', ')}`);
+            }
+            // 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) {
-        completeModel = completeModel.volatile(() => volatileConstants);
+        completeModel = completeModel.volatile(( /* self */) => volatileConstants);
     }
-    if (options.actions) {
-        completeModel = completeModel.actions(options.actions);
+    // one MST call per entry, base's before the subclass's — chaining is what
+    // makes the base's members visible on `self` inside the subclass's function
+    for (const hook of hookList(options.actions)) {
+        completeModel = completeModel.actions(hook);
     }
-    if (options.views) {
-        completeModel = completeModel.views(options.views);
+    for (const hook of hookList(options.views)) {
+        completeModel = completeModel.views(hook);
     }
-    if (options.extend) {
-        completeModel = completeModel.extend(options.extend);
+    for (const hook of hookList(options.extend)) {
+        completeModel = completeModel.extend(hook);
     }
+    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 }
         : identifierDefault;
-    const defaultSnap = getSnapshot(completeModel.create(modelDefault));
-    completeModel = completeModel.postProcessSnapshot(snap => {
-        const newSnap = {};
-        let matchesDefault = true;
-        for (const [key, value] of Object.entries(snap)) {
-            if (matchesDefault) {
-                if (typeof defaultSnap[key] === 'object' && typeof value === 'object') {
-                    if (JSON.stringify(defaultSnap[key]) !== JSON.stringify(value)) {
-                        matchesDefault = false;
-                    }
-                }
-                else if (defaultSnap[key] !== value) {
-                    matchesDefault = false;
-                }
-            }
-            if (value !== undefined &&
-                volatileConstants[key] === undefined &&
-                !isEmptyObject(value) &&
-                !isEmptyArray(value)) {
-                newSnap[key] = value;
-            }
-        }
-        if (matchesDefault) {
-            return {};
-        }
-        return newSnap;
-    });
-    if (options.preProcessSnapshot) {
-        completeModel = completeModel.preProcessSnapshot(options.preProcessSnapshot);
+    // 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.
+    registerConfigurationSchema(completeModel, metadata);
+    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);
     }
-    return types.optional(completeModel, modelDefault);
 }
 export function ConfigurationSchema(modelName, inputSchemaDefinition, inputOptions) {
     const { schemaDefinition, options } = preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition, inputOptions);
-    const schemaType = makeConfigurationSchemaModel(modelName, schemaDefinition, options);
-    schemaType.isJBrowseConfigurationSchema = true;
-    schemaType.jbrowseSchemaDefinition = schemaDefinition;
-    schemaType.jbrowseSchemaOptions = options;
-    return schemaType;
+    return makeConfigurationSchemaModel(modelName, schemaDefinition, options);
 }
-export function TrackConfigurationReference(schemaType) {
+// The frozen -> live half of TrackConfigurationReference's `get`, shared with
+// 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) {
+    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). 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.
+ *
+ * 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** 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 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;
+    if (typeof type !== 'string') {
+        return undefined;
+    }
+    try {
+        // getTrackType throws on an unregistered name rather than returning
+        // undefined, so it is inside the guard with `create` — the two failures are
+        // the same failure (nothing here can build this config) and neither should
+        // reach a dialog that is only trying to show it
+        const { configSchema } = pluginManager.getTrackType(type);
+        return hydrateInto(pluginManager, configSchema, config);
+    }
+    catch (e) {
+        console.error(e);
+        return undefined;
+    }
+}
+// A slot holding either an id string (resolved through `ref`) or a full inline
+// 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,
+// 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),
+    }, ref, schemaType);
+}
+/**
+ * Reference to a track configuration. Snapshot output is the trackId string.
+ *
+ * One load-bearing complication: **`types.union(trackRef, schemaType)` accepts a
+ * string id OR a full config.** A view that synthesizes a track nobody else can
+ * draw — a read-vs-ref synteny band, an SV inspector row, a circular view's
+ * added track — writes the config here rather than registering it in
+ * `session.tracks`, and it then lives and dies with the track that holds it.
+ * `ReadVsRef.test.tsx` and `SVInspector.test.tsx` are the canaries.
+ *
+ * NOTE: don't add `as SCHEMATYPE` to the return value. It narrows SnapshotIn
+ * to just the object branch, forcing callers to wrap string ids in
+ * `@ts-expect-error`. The inferred union SnapshotIn is `string | SnapshotIn<schema>`.
+ */
+function TrackConfigurationReference(schemaType) {
     const trackRef = types.reference(schemaType, {
         get(id, parent) {
             const session = getSession(parent);
-            let ret = session.getTracksById()[id];
+            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. 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) {
-                ret = resolveIdentifier(schemaType, getRoot(parent), id);
+                throw new Error(`Could not resolve trackId "${id}"`);
             }
-            if (!ret) {
-                throw new Error(`Could not resolve identifier "${id}"`);
-            }
-            return isStateTreeNode(ret) ? ret : schemaType.create(ret, getEnv(parent));
+            return isStateTreeNode(ret)
+                ? ret
+                : hydrateInto(getEnv(parent).pluginManager, schemaType, ret);
         },
         set(value) {
             return value.trackId;
         },
     });
-    return types.snapshotProcessor(types.union({
-        dispatcher: snapshot => typeof snapshot === 'string' ? trackRef : schemaType,
-    }, trackRef, schemaType), {
-        postProcessor(snapshot) {
-            if (typeof snapshot === 'object' &&
-                snapshot !== null &&
-                'trackId' in snapshot) {
-                return snapshot.trackId;
-            }
-            return snapshot;
-        },
-    });
+    return idOrSnapshotUnion(trackRef, schemaType);
 }
-export function DisplayConfigurationReference(schemaType) {
+/**
+ * Reference to a display configuration. Looked up inside the containing track
+ * config's `displays` array. Snapshot output is the displayId string.
+ *
+ * Resolution order:
+ *   1. by displayId
+ *   2. by `parent.type` — handles old sessions where the saved displayId
+ *      no longer matches but a display of the same type exists on the track
+ *
+ * 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. 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.
+ *
+ * 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.
+ */
+function DisplayConfigurationReference(schemaType) {
     const displayRef = types.reference(schemaType, {
         get(id, parent) {
+            // track.configuration is a hydrated MST node (hydrated lazily via
+            // TrackConfigurationReference), so its displays array contains MST nodes.
             const track = getContainingTrack(parent);
-            const displays = track.configuration.displays || [];
-            let ret = displays.find((d) => d.displayId === id);
-            if (!ret) {
-                const displayType = `${id}`.split('-').slice(1).join('-');
-                if (displayType) {
-                    ret = { displayId: `${id}`, type: displayType };
-                }
+            const displays = track.configuration.displays;
+            const displayType = parent.type;
+            let ret = displays.find(d => d.displayId === id);
+            // Fallback: match by display type when the displayId isn't found.
+            // baseTrackConfig.preProcessSnapshot injects a display entry for every
+            // registered displayType for the track, so id-mismatch (e.g. an old
+            // session with a different displayId convention) finds a same-type
+            // entry here. The `if (displayType)` guard prevents an undefined
+            // parent.type from silently matching a display whose `.type` is also
+            // undefined.
+            if (!ret && displayType) {
+                ret = displays.find(d => d.type === displayType);
             }
             if (!ret) {
-                throw new Error(`Display configuration "${id}" not found`);
+                const trackId = track.configuration.trackId;
+                throw new Error(`Display configuration "${id}" not found on track "${trackId}" (looked up by displayId, then by type "${displayType ?? '<no type on parent>'}")`);
             }
-            return isStateTreeNode(ret) ? ret : schemaType.create(ret, getEnv(parent));
+            return ret;
         },
         set(value) {
             return value.displayId;
         },
     });
-    return types.union({
-        dispatcher: snapshot => typeof snapshot === 'string' ? displayRef : schemaType,
-    }, displayRef, schemaType);
+    return idOrSnapshotUnion(displayRef, schemaType);
 }
+/**
+ * Dispatch by the schema's identifier: `trackId` → track-ref (resolves through
+ * `session.getTrackById`), `displayId` → display-ref (resolves through the
+ * parent track's displays array), anything else → plain reference.
+ *
+ * Display schemas must declare `explicitIdentifier: 'displayId'` (directly or
+ * via `baseConfiguration: baseLinearDisplayConfigSchema`, which merges its
+ * options through `preprocessConfigurationSchemaArguments`).
+ *
+ * The return is annotated `IConfigurationReference<SCHEMATYPE>` (see its doc)
+ * so `self.configuration` carries the concrete schema. The three runtime
+ * branches produce MST reference/union types over `schemaType` that are
+ * assignable to that annotation, so `return ref` needs no cast — and must not
+ * get one: a prior `as SCHEMATYPE` was dropped because it narrowed `SnapshotIn`
+ * to just the object branch and forced callers pushing string ids to
+ * `@ts-expect-error` (see `TrackConfigurationReference`'s note).
+ */
 export function ConfigurationReference(schemaType) {
-    const name = schemaType.name;
-    if (name.includes('TrackConfigurationSchema') &&
-        !name.includes('DisplayConfigurationSchema')) {
-        return TrackConfigurationReference(schemaType);
-    }
-    if (name.includes('DisplayConfigurationSchema')) {
-        return DisplayConfigurationReference(schemaType);
-    }
-    return types.union(types.reference(schemaType), schemaType);
+    const id = getConfigurationSchemaMetadata(schemaType)?.options.explicitIdentifier;
+    const ref = id === 'trackId'
+        ? TrackConfigurationReference(schemaType)
+        : id === 'displayId'
+            ? DisplayConfigurationReference(schemaType)
+            : // 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;
 }