@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/configuration/configurationSchema.js

@@ -1,37 +1,94 @@
-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, 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 { getConfigurationSchemaMetadata, registerConfigurationSchema, } from './schemaRegistry.js';
+import { isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.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`.)
+ *
+ * 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.
+ */
+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;
 }
 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: `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.
+    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.`);
+    }
+    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.
+        const basePreProcess = baseMeta.options.preProcessSnapshot;
+        const childPreProcess = inputOptions.preProcessSnapshot;
         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),
         };
     }
     return { schemaDefinition, options };
 }
 function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
+    // now assemble the MST model of the configuration schema
     const modelDefinition = {};
     let identifier;
     if (options.explicitlyTyped) {
@@ -40,54 +97,68 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     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';
-        }
+    // 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;
     }
-    else if (options.implicitIdentifier) {
-        if (typeof options.implicitIdentifier === 'string') {
-            modelDefinition[options.implicitIdentifier] = ElementId;
-            identifier = options.implicitIdentifier;
-        }
-        else {
-            modelDefinition.id = ElementId;
-            identifier = 'id';
-        }
-    }
-    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 = {};
+    // 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.
+    const subSchemaKeys = 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();
     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/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, {});
+            }
+            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);
             }
             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`);
         }
@@ -96,7 +167,7 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
         .model(`${modelName}ConfigurationSchema`, modelDefinition)
         .actions(self => ({
         setSubschema(slotName, data) {
-            if (!isConfigurationSchemaType(modelDefinition[slotName])) {
+            if (!subSchemaKeys.has(slotName)) {
                 throw new Error(`${slotName} is not a subschema, cannot replace`);
             }
             const newSchema = isStateTreeNode(data)
@@ -105,126 +176,276 @@ 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.
+        //
+        // **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.
+        setSlot(slotName, value) {
+            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(', ')}`);
+            }
+            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);
+    }
+    if (options.preProcessSnapshot) {
+        completeModel = completeModel.preProcessSnapshot(options.preProcessSnapshot);
     }
     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);
-    }
-    return types.optional(completeModel, modelDefault);
+    // 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;
 }
 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);
 }
+// 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.
+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;
+}
+/**
+ * #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
+ * 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
+ * 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.
+ *
+ * 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.
+ */
+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.
+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>`.
+ */
 export function TrackConfigurationReference(schemaType) {
     const trackRef = types.reference(schemaType, {
         get(id, parent) {
             const session = getSession(parent);
-            let ret = session.getTracksById()[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));
             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}"`);
+            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 isStateTreeNode(ret) ? ret : schemaType.create(ret, getEnv(parent));
+            return 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);
 }
+/**
+ * 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. 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.
+ *
+ * Union-with-schemaType branch is for the same reason as `TrackConfigurationReference`:
+ * `CircularView.addTrackConf` passes inline display configs as MST instances.
+ */
 export 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. The union accepts either an id
+                // string (resolved via `types.reference`) or an inline schema
+                // snapshot (held as a standalone schema instance).
+                types.union(types.reference(schemaType), schemaType);
+    return ref;
 }