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

package/esm/configuration/configurationSchema.js

@@ -6,26 +6,17 @@ 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';
+import { preProcessSnapshotWith, refusingUndeclaredKeys, } from './snapshotPreprocess.js';
 function hookList(hook) {
     return hook === undefined ? [] : Array.isArray(hook) ? hook : [hook];
 }
-// 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.
- */
+// A redeclared slot merges field-by-field over the base's, so an override states
+// only what differs; a sub-schema or a constant is replaced whole.
 function mergeSchemaDefinition(baseDefinition, childDefinition) {
     const merged = {
         ...baseDefinition,
@@ -33,8 +24,6 @@ function mergeSchemaDefinition(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 };
         }
@@ -58,32 +47,19 @@ function preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition
     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;
     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.
+        // The hooks, `requires` and `retired` compose, base first, where every
+        // other option is replaced by the child's: a track schema's own
+        // preProcessSnapshot must not drop the base's display-stub injection.
         const basePreProcess = baseMeta.options.preProcessSnapshot;
         const childPreProcess = inputOptions.preProcessSnapshot;
         const requires = [
@@ -106,10 +82,12 @@ function preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition
             requires: requires.length ? requires : undefined,
         };
     }
+    if (options.explicitlyTyped && options.explicitIdentifier === 'displayId') {
+        options = { ...options, closed: options.closed ?? true };
+    }
     return { schemaDefinition, options };
 }
 function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
-    // now assemble the MST model of the configuration schema
     const modelDefinition = {};
     if (options.explicitlyTyped) {
         modelDefinition.type = types.optional(types.literal(modelName), modelName);
@@ -118,30 +96,18 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     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 = {};
-    // 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.
+    // narrower than `modelDefinition`, which also holds the identifier and the
+    // sub-schemas, neither of which setSlot may write
     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 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.
+            // an empty collection strips from the snapshot as an all-default
+            // sub-schema does, unless it names a default of its own
             if (isArrayType(slotDefinition) || isMapType(slotDefinition)) {
                 modelDefinition[slotName] = isOptionalType(slotDefinition)
                     ? slotDefinition
@@ -157,13 +123,9 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             volatileConstants[slotName] = slotDefinition;
         }
         else if (isSlotDefinitionEntry(slotDefinition)) {
-            // slotDefinition is narrowed to ConfigSlotDefinition here (no cast)
             slotKeys.add(slotName);
             try {
                 modelDefinition[slotName] = ConfigSlot(slotDefinition);
-                if (modelDefinition[slotName].is(null)) {
-                    storesNull.add(slotName);
-                }
                 if (slotDefinition.type === 'featureField') {
                     featureFields.add(slotName);
                 }
@@ -176,8 +138,6 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             }
         }
         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 {
@@ -188,16 +148,17 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     checkShorthand(modelName, schemaDefinition, options.shorthand);
     let completeModel = types
         .model(`${modelName}ConfigurationSchema`, modelDefinition)
-        // 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
+        // annotated so `ConfigurationSchemaType['Type']`, which names these by
+        // hand, 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.
+        // `data` is whatever the sub-schema's preProcessSnapshot takes; a
+        // collection takes the whole list or map, and `null` resets it
         setSubschema(slotName, data) {
             if (collectionKeys.has(slotName)) {
+                // checked on a copy, since the assignment runs patch listeners
+                if (data != null && !isStateTreeNode(data)) {
+                    refusingUndeclaredKeys(() => modelDefinition[slotName].create(data));
+                }
                 self[slotName] = data ?? undefined;
                 return self[slotName];
             }
@@ -206,32 +167,16 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
             }
             const newSchema = isStateTreeNode(data)
                 ? data
-                : modelDefinition[slotName].create(data);
+                : refusingUndeclaredKeys(() => modelDefinition[slotName].create(data));
             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.
+        // The name check is a write guard (ADR-052), never a warning. `null`
+        // resets, as `undefined` does, since JSON cannot spell `undefined`
+        // (ADR-146).
         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: ${[
@@ -240,10 +185,7 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
                         .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.
+            // MST skips its own type check in a production build; `is` does not
             if (!modelDefinition[slotName].is(value)) {
                 const declared = schemaDefinition[slotName];
                 const slotType = isSlotDefinitionEntry(declared)
@@ -263,8 +205,6 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     if (Object.keys(volatileConstants).length) {
         completeModel = completeModel.volatile(( /* self */) => volatileConstants);
     }
-    // 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);
     }
@@ -278,7 +218,6 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
         name: modelName,
         definition: schemaDefinition,
         options,
-        storesNull,
         featureFields,
         takesNoCallback,
     };
@@ -287,18 +226,15 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
     const modelDefault = options.explicitlyTyped
         ? { type: modelName, ...identifierDefault }
         : identifierDefault;
-    // 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.
+    // stripDefault, not optional, so an all-default sub-schema leaves its
+    // parent's snapshot
     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.
+// Assigning an array makes MST reconcile it entry by entry, seconds for a
+// reorder of 5,000 row names; refilling a scalar array takes 50 ms.
+// spliceWithArray, since spreading into `push` overflows the stack past about
+// 120,000 entries.
 function refillArray(held, value) {
     if (held.length !== value.length || held.some((v, i) => v !== value[i])) {
         held.clear();
@@ -309,39 +245,22 @@ export function ConfigurationSchema(modelName, inputSchemaDefinition, inputOptio
     const { schemaDefinition, options } = preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition, inputOptions);
     return makeConfigurationSchemaModel(modelName, schemaDefinition, options);
 }
-// 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.
+// memoized per PluginManager, so a node never crosses to another instance's env
+// (ADR-031)
 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.
+ * Hydrate a plain track config, such as a `session.tracks` entry, into a live
+ * config node, dispatching on its `type` to find the schema. A plain entry
+ * holds only what was authored: a slot at its default is absent and
+ * `preProcessSnapshot` has not run.
  *
- * 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.
+ * Returns **undefined** when no plugin registered the type or `create` rejects
+ * the config, which has never been validated; callers fall back to the plain
+ * object. Hydrating one entry twice returns one node. A shown track resolves to
+ * the session's working copy instead (ADR-032), which has the same content.
  */
 export function hydrateTrackConfig(pluginManager, config) {
     const type = config.type;
@@ -349,10 +268,6 @@ export function hydrateTrackConfig(pluginManager, config) {
         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);
     }
@@ -361,52 +276,24 @@ export function hydrateTrackConfig(pluginManager, config) {
         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.
+// An id string resolves through `ref`; an object is an inline config. So
+// assigning a node here adopts it as a child rather than storing a reference,
+// which makes both refs' `set` unreachable: MST only requires one beside `get`.
 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>`.
+ * Reference to a track configuration, snapshotted as its trackId. It also takes
+ * a whole config: a view's synthesized track (a read-vs-ref band, an SV
+ * inspector row) holds its config inline and lives and dies with it. ADR-084.
  */
 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. 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);
@@ -424,52 +311,19 @@ function TrackConfigurationReference(schemaType) {
     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. 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.
+ * Reference to a display configuration in the containing track config's
+ * `displays`, snapshotted as its displayId. An id that matches nothing falls
+ * back to the display of the parent's type, which the track config always
+ * holds a stub of: that is what reconnects a session saved before a display
+ * type was renamed.
  */
 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;
             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);
             }
@@ -486,21 +340,10 @@ function DisplayConfigurationReference(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).
+ * A reference resolved by the schema's identifier: a `trackId` through the
+ * session, a `displayId` through the containing track's `displays`, anything
+ * else by MST's own identifier lookup. No `as SCHEMATYPE` on the return: it
+ * would narrow `SnapshotIn` to the object branch and refuse a string id.
  */
 export function ConfigurationReference(schemaType) {
     const id = getConfigurationSchemaMetadata(schemaType)?.options.explicitIdentifier;
@@ -508,17 +351,8 @@ export function ConfigurationReference(schemaType) {
         ? 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.
+            : // not idOrSnapshotUnion: this branch is handed live in-tree nodes
+                // (an internet account), which its dispatcher would try to adopt
                 types.union(types.reference(schemaType), schemaType);
     return ref;
 }

package/esm/configuration/configurationSchemaUnion.d.ts

@@ -27,7 +27,8 @@ export type ConfigurationSchemaUnionType<MEMBERS extends Record<string, AnyConfi
  * 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.
+ * another member is named on a load and refused on a write 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>;
 /**

package/esm/configuration/configurationSchemaUnion.js

@@ -21,7 +21,8 @@ function memberRefusal(key, member) {
  * 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.
+ * another member is named on a load and refused on a write rather than
+ * dropped; one that is not throws here.
  */
 export function ConfigurationSchemaUnion(name, members) {
     for (const [key, member] of Object.entries(members)) {

package/esm/configuration/configurationSlot.d.ts

@@ -261,29 +261,15 @@ declare const slotTypes: {
         fallbackDefault: {};
     };
 };
-/**
- * The builtin table's own names — every slot type whose MST model this module
- * supplies, so excluding the two enum types. Exported for `SlotValueByType` in
- * `types.ts`, which has to name the same set and is checked against this.
- */
+/** the types whose model this module supplies; `SlotValueByType` names the same set */
 export type BuiltinSlotTypeName = keyof typeof slotTypes;
 declare const ENUM_SLOT_TYPES: readonly ['stringEnum', 'maybeStringEnum', 'stringEnumArray'];
 /**
- * Every legal `type` on a slot definition: the builtin table's own names, plus
- * the enum types.
- *
- * Closed on purpose. A name outside this set still *works* at runtime as long
- * as a `model` is given — which is exactly the trap: the value round-trips
- * fine, and the only symptom is that everything keyed off the type name stops
- * recognising the slot (`slotFacade` hands the editor no `choices`, so an enum
- * renders as a free text box).
+ * Every legal `type` on a slot definition. Closed, since a name outside it
+ * would still load with a `model` given, and every surface keyed on the name
+ * would stop recognising the slot.
  */
 export type ConfigSlotType = keyof typeof slotTypes | (typeof ENUM_SLOT_TYPES)[number];
-/**
- * The same set as `MAYBE_TYPES`, at the type level, and derived from the same
- * property of the same table so the two cannot disagree: an entry with no
- * `fallbackDefault` is one whose fixed form is "unset".
- */
 type MaybeBuiltinSlotTypeName = {
     [K in keyof typeof slotTypes]: 'fallbackDefault' extends keyof (typeof slotTypes)[K] ? never : K;
 }[keyof typeof slotTypes];
@@ -301,31 +287,19 @@ interface ConfigSlotDefinitionCommon {
      */
     contextVariable?: string[];
     /**
-     * hide this slot behind a "Show advanced settings" toggle in the config
-     * editor, so common slots aren't crowded out by rarely-changed ones
+     * put this slot behind a toggle so common slots aren't crowded out by
+     * rarely-changed ones: "Show advanced settings" in the config editor, and
+     * the collapsed Advanced card in a track's About dialog, which also takes
+     * every slot with a `contextVariable`
      */
     advanced?: boolean;
 }
 /**
- * A slot definition, split on whether the slot's type spends `undefined` on
- * "unset". The type-level twin of `ConfigSlot`'s
- * `defaultValue === undefined && !MAYBE_TYPES.has(type)` throw, which used to be
- * the only statement of the rule: a `maybe*` slot has exactly one legal
- * `defaultValue`, so requiring the field of every slot alike made 81 slots
- * across the repo carry a `defaultValue: undefined` line that said nothing.
- *
- * A `maybe*` slot's only legal `defaultValue` is the sentinel itself, but the
- * field stays `unknown` rather than being pinned to `undefined`: the spread in
- * `mergeSchemaDefinition` combines a base and a child whose halves may disagree,
- * so pinning it forces a cast through the one place slot definitions are
- * combined. `ConfigSlot` throws on a concrete one instead — and has to anyway,
- * since no type can see what a `baseConfiguration` merged in, which is the way
- * this mistake actually happens.
- *
- * Stating the sentinel stays meaningful in a subclass override, where the merge
- * is a spread and an omitted key inherits the base's value. The same spread is
- * why an enum slot's `model` stays optional here though `ConfigSlot` requires
- * one: a subclass restating only the default inherits the vocabulary.
+ * A slot definition: a `maybe*` type's `defaultValue` is optional, every
+ * other's required. A `maybe*` default stays `unknown` rather than `undefined`
+ * because a subclass override is spread over its base's, which no type can see;
+ * `ConfigSlot` throws on a concrete one. An enum's `model` is optional for the
+ * same spread: an override restating only the default inherits the vocabulary.
  */
 export type ConfigSlotDefinition = (ConfigSlotDefinitionCommon & {
     /** a `maybe*` slot type, whose unset state is `undefined` */
@@ -339,33 +313,13 @@ export type ConfigSlotDefinition = (ConfigSlotDefinitionCommon & {
     defaultValue: unknown;
 });
 /**
- * A configuration slot is a plain MST property holding the slot's value type,
- * or, where the slot declares a `contextVariable`, that or a `jexl:...`
- * callback string. Every other slot refuses a `jexl:` string, so a callback
- * the reader would evaluate is one the schema says it takes. A `featureField`
- * holds a `jexl:` expression as its value, which the display evaluates per
- * feature. The value lives directly on the parent configuration model — there
- * is no per-slot sub-model. `types.stripDefault` omits the property from the
- * parent snapshot when it equals the default, so saved sessions stay minimal.
- * Per-slot metadata (type/description/defaultValue/contextVariable) lives in
- * the schema registry (a WeakMap keyed by the MST type, see
- * schemaRegistry.ts); jexl callbacks are evaluated on read by
- * `readConfObject`.
- *
- * Interning the returned type on `(type, model, defaultValue)` was prototyped
- * and declined: a session builds 1197 slot types for 222 distinct ones, and
- * removing the repeats moves neither the time nor the heap
- * (`config-schema-construction`, published in `reference/EAGER_BUNDLE.md`).
+ * The MST property a slot is: its value type, or that or a `jexl:` callback
+ * where the slot declares a `contextVariable` (ADR-155), stripped from the
+ * snapshot at its default. Interning these was measured and declined
+ * (`config-schema-construction` in `reference/EAGER_BUNDLE.md`).
  */
 export default function ConfigSlot(definition: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<IAnyType, [undefined]>;
-/**
- * New value when converting a fixed-value slot to a jexl callback. Already-
- * callback values are returned unchanged.
- *
- * A single JSON.stringify covers every type: `jexl:${42}` and
- * `jexl:${JSON.stringify(42)}` are identical for numbers/booleans, and the rest
- * need the quoting/serialization anyway.
- */
+/** A fixed value as the `jexl:` callback that returns it. */
 export declare function toCallbackValue(value: unknown): string;
 /**
  * New value when converting a jexl callback back to a fixed value: try