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

package/esm/configuration/index.js

@@ -1,19 +1,28 @@
 export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.js';
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.js';
 export { getConfigurationSchemaDefinition, 
 // exported for scripts/generateConfigManifest.ts, which needs the
 // preProcessSnapshot off a schema whose pluggable type does not expose one —
 // TextSearchAdapterType, where the shorthand is nonetheless the documented
 // way to write the config
-getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.js';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.js';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.js';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.js';
-export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.js';
-export { getConf, resolveConf, setConf } from './getConf.js';
-export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.js';
-export { tabixIndexFields } from './tabixIndexFields.js';
+export { readConfObject, readConfigValue } from './readConfObject.js';
+export { applyConfSettings, getConf, setConf } from './getConf.js';
+export { fillLocations } from './fillLocations.js';
+export { applyRetiredSpellings, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, } from './snapshotPreprocess.js';
+export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.js';
+export { requirementProblems } from './requirements.js';
+export { expandTabixShorthand, indexSnapshot, requestedIndexType, tabixIndexSnapshot, } from './tabixShorthand.js';
+export { expandUriShorthand } from './uriShorthand.js';
+export { bamIndexFields, bamIndexSchema } from './bamIndexFields.js';
+export { tabixIndexFields, tabixIndexSchema } from './tabixIndexFields.js';
+export { fillIndexType, indexSuffix, isCsiLocation } from './indexType.js';
 export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 export { toCallbackValue, toFixedValue } from './configurationSlot.js';
-export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.js';
-export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.js';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, slotChoices, slotValueRefusal, } from './slotFacade.js';
+export { fullConfSnapshot } from './fullConfSnapshot.js';
+export { PLOT_VOCABULARY, liftPlot, parsePlot, plotKeysOf, plotOf, plotWrites, } from './plot.js';

package/esm/configuration/indexType.d.ts

@@ -0,0 +1,26 @@
+/** The sibling index format of a family: TBI for tabix, BAI for BAM. */
+export type SiblingIndexType = 'TBI' | 'BAI';
+export type IndexType = SiblingIndexType | 'CSI';
+/** The extension an index of this type carries: `CSI` → `.csi`, `TBI` → `.tbi`. */
+export declare function indexSuffix(indexType: IndexType): string;
+/**
+ * Whether a file location names a CSI. htslib writes `.csi` in place of a `.bai`
+ * or a `.tbi` for a reference over 512 Mb and on request at any size, so the
+ * extension is the only thing distinguishing the two parsers.
+ *
+ * `makeIndexType` in `util/tracks.ts` asks this of a bare filename, for the
+ * guessers and add-track forms that WRITE an `indexType` beside the location.
+ * Those stay: a config the CLI or jbrowse-img writes is read by older JBrowse
+ * versions, which have no inference to fall back on.
+ */
+export declare function isCsiLocation(location: unknown): boolean;
+/**
+ * An index sub-schema's snapshot with `indexType` filled in from the location it
+ * names, where it states none. Only CSI is ever filled in — the sibling format
+ * is the slot's own default.
+ *
+ * Belongs to the sub-schema rather than to the `uri` shorthand because it has to
+ * cover the paths no shorthand runs on: a long-form config, and an add-track
+ * form that writes a location and nothing else.
+ */
+export declare function fillIndexType(snap: Record<string, unknown>): Record<string, unknown>;

package/esm/configuration/indexType.js

@@ -0,0 +1,38 @@
+import { isPlainObject } from '../util/objectUtils.js';
+/** The extension an index of this type carries: `CSI` → `.csi`, `TBI` → `.tbi`. */
+export function indexSuffix(indexType) {
+    return `.${indexType.toLowerCase()}`;
+}
+/**
+ * Whether a file location names a CSI. htslib writes `.csi` in place of a `.bai`
+ * or a `.tbi` for a reference over 512 Mb and on request at any size, so the
+ * extension is the only thing distinguishing the two parsers.
+ *
+ * `makeIndexType` in `util/tracks.ts` asks this of a bare filename, for the
+ * guessers and add-track forms that WRITE an `indexType` beside the location.
+ * Those stay: a config the CLI or jbrowse-img writes is read by older JBrowse
+ * versions, which have no inference to fall back on.
+ */
+export function isCsiLocation(location) {
+    if (!isPlainObject(location)) {
+        return false;
+    }
+    const { uri, localPath } = location;
+    const name = typeof uri === 'string' ? uri : localPath;
+    // a presigned url carries its query string after the name
+    return typeof name === 'string' && /\.csi$/i.test(name.split(/[?#]/)[0]);
+}
+/**
+ * An index sub-schema's snapshot with `indexType` filled in from the location it
+ * names, where it states none. Only CSI is ever filled in — the sibling format
+ * is the slot's own default.
+ *
+ * Belongs to the sub-schema rather than to the `uri` shorthand because it has to
+ * cover the paths no shorthand runs on: a long-form config, and an add-track
+ * form that writes a location and nothing else.
+ */
+export function fillIndexType(snap) {
+    return snap.indexType === undefined && isCsiLocation(snap.location)
+        ? { ...snap, indexType: 'CSI' }
+        : snap;
+}

package/esm/configuration/mergeFormatCallbacks.d.ts

@@ -4,12 +4,11 @@
  * first, so a track's object is spread over the session-wide one and can
  * override individual keys the global callback added.
  *
- * A tier that isn't a plain object is dropped rather than spread. The classic
- * slip is `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant;
- * spreading the resulting string produced attribute rows keyed `0`, `1`, `2`,
- * and an array does the same, which is why `isObject` alone isn't the gate.
- *
- * `null` and `undefined` *values* survive on purpose: they are how a callback
- * hides a field, and the panels filter them out downstream.
+ * A tier that returns something other than an object is an authoring mistake,
+ * `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant, and it
+ * throws rather than vanishing: spread, the string became rows keyed 0, 1, 2,
+ * and dropped, the author's callback silently did nothing. A tier returning
+ * null or undefined has nothing to add. `null` and `undefined` *values* survive:
+ * they are how a callback hides a field, and the panels filter them downstream.
  */
 export declare function mergeFormatCallbacks(...tiers: unknown[]): Record<string, unknown>;

package/esm/configuration/mergeFormatCallbacks.js

@@ -1,24 +1,27 @@
-import { isObject } from '../util/objectUtils.js';
+import { isPlainObject } from '../util/objectUtils.js';
 /**
  * Combine the tiers of an object-returning format callback (`formatDetails` on
  * the feature-details panel, `formatAbout` on the About dialog), earliest
  * first, so a track's object is spread over the session-wide one and can
  * override individual keys the global callback added.
  *
- * A tier that isn't a plain object is dropped rather than spread. The classic
- * slip is `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant;
- * spreading the resulting string produced attribute rows keyed `0`, `1`, `2`,
- * and an array does the same, which is why `isObject` alone isn't the gate.
- *
- * `null` and `undefined` *values* survive on purpose: they are how a callback
- * hides a field, and the panels filter them out downstream.
+ * A tier that returns something other than an object is an authoring mistake,
+ * `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant, and it
+ * throws rather than vanishing: spread, the string became rows keyed 0, 1, 2,
+ * and dropped, the author's callback silently did nothing. A tier returning
+ * null or undefined has nothing to add. `null` and `undefined` *values* survive:
+ * they are how a callback hides a field, and the panels filter them downstream.
  */
 export function mergeFormatCallbacks(...tiers) {
     const out = {};
     for (const tier of tiers) {
-        if (isObject(tier) && !Array.isArray(tier)) {
-            Object.assign(out, tier);
+        if (tier == null) {
+            continue;
+        }
+        if (!isPlainObject(tier)) {
+            throw new Error(`a format callback returned ${Array.isArray(tier) ? 'an array' : `a ${typeof tier}`} where an object of fields was expected, e.g. "jexl:{name:feature.name}" rather than "jexl:feature.name"`);
         }
+        Object.assign(out, tier);
     }
     return out;
 }

package/esm/configuration/plot.d.ts

@@ -0,0 +1,61 @@
+import type { AnyConfigurationModel } from './types.ts';
+/**
+ * #api core/configuration
+ * The grammar's settings, by the slot name every display that has one gives
+ * it, and what each holds: what "Edit plot..." shows and an agent reads as a
+ * display's `plot`. A display's plot is the ones its config declares
+ * (`plotKeysOf`).
+ */
+export declare const PLOT_VOCABULARY: Readonly<Record<string, string>>;
+/**
+ * #api core/configuration
+ * A display's plot settings as written: a key left out is left alone, and
+ * `null` resets that setting. Untyped, since a value may be a shorthand the
+ * schema lifts, and the schema is what judges it.
+ */
+export type Plot = Record<string, unknown>;
+/**
+ * #api core/configuration
+ * A worked example of a display's plot: the text it fills the editor with,
+ * and what it does.
+ */
+export interface PlotExample {
+    plot: string;
+    description: string;
+}
+/**
+ * #api core/configuration
+ * The plot keys a display config declares.
+ */
+export declare function plotKeysOf(conf: AnyConfigurationModel): string[];
+/**
+ * #api core/configuration
+ * A display's plot as declared, defaults left off. A list sitting at a
+ * default it shares with no other display, a default plot's marks, shows its
+ * entries, since they are what is drawn.
+ */
+export declare function plotOf(conf: AnyConfigurationModel): Plot;
+/**
+ * #api core/configuration
+ * The text as a plot, refusing a key the display's plot does not hold. The
+ * schema is the parser past this point.
+ */
+export declare function parsePlot(text: string, keys: readonly string[]): Plot;
+/**
+ * #api core/configuration
+ * A draft as the display's config would hold it, through the schema's own
+ * lift and checks: a shorthand becomes its object, a default falls off, and
+ * what a config file is refused for throws, a key outside the plot included.
+ * The node is never attached, so nothing on the display is touched; a display
+ * reads its typed members off it. The draft is copied first, since MST
+ * freezes what it creates from.
+ */
+export declare function liftPlot(conf: AnyConfigurationModel, draft: Plot): AnyConfigurationModel;
+/**
+ * #api core/configuration
+ * What applying a draft writes: each setting whose lifted value differs from
+ * the plot, as the lifted value, and `null` for one it resets. A value
+ * spelled another way but lifting to the same setting writes nothing.
+ * Throws a refusal before anything is written.
+ */
+export declare function plotWrites(conf: AnyConfigurationModel, draft: Plot): Record<string, unknown>;

package/esm/configuration/plot.js

@@ -0,0 +1,142 @@
+import { getSnapshot, getType, isArrayType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { compareStructural } from 'mobx';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { bareFormOf, shorthandTargets } from './schemaTypes.js';
+/**
+ * #api core/configuration
+ * The grammar's settings, by the slot name every display that has one gives
+ * it, and what each holds: what "Edit plot..." shows and an agent reads as a
+ * display's `plot`. A display's plot is the ones its config declares
+ * (`plotKeysOf`).
+ */
+export const PLOT_VOCABULARY = {
+    marks: 'the marks drawn in order, each a mark and an encoding',
+    transform: 'the steps run over the features before any mark',
+    facet: 'one section per value of a field',
+    rows: 'the rows: their field or order, labels, focus and tree',
+    rowColor: 'the colour of each row label',
+    color: 'the colour',
+    baseColor: 'the per-base layer over the reads',
+    arcColor: 'the colour of the arcs between mates',
+    ribbonColor: 'the colour of the ribbons between lanes',
+    laneLayers: 'the layers drawn over each lane',
+    scales: 'the axes, scales.y the value axis',
+    filter: 'the jexl: expressions a feature has to pass',
+    filterBy: 'the read flags and tags a read has to pass',
+};
+const LIFT_ID = 'plotLift';
+/**
+ * #api core/configuration
+ * The plot keys a display config declares.
+ */
+export function plotKeysOf(conf) {
+    const definition = getConfigurationSchemaMetadata(conf)?.definition ?? {};
+    return Object.keys(PLOT_VOCABULARY).filter(key => Object.hasOwn(definition, key));
+}
+// A one-member object a shorthand would write as a bare value prints as that
+// value, as a config file writes it: `color: "red"`, `facet: "strand"`.
+function folded(member, value) {
+    if (!isStateTreeNode(member) ||
+        typeof value !== 'object' ||
+        value === null ||
+        Array.isArray(value)) {
+        return value;
+    }
+    const meta = getConfigurationSchemaMetadata(member);
+    const entries = Object.entries(value);
+    if (!meta || meta.options.shorthandWith || entries.length !== 1) {
+        return value;
+    }
+    const [slot, bare] = entries[0];
+    const form = bareFormOf(bare);
+    return form && shorthandTargets(meta)[form] === slot ? bare : value;
+}
+/**
+ * #api core/configuration
+ * A display's plot as declared, defaults left off. A list sitting at a
+ * default it shares with no other display, a default plot's marks, shows its
+ * entries, since they are what is drawn.
+ */
+export function plotOf(conf) {
+    const snapshot = getSnapshot(conf);
+    const plot = {};
+    for (const key of plotKeysOf(conf)) {
+        const member = conf[key];
+        const value = snapshot[key] ??
+            (isStateTreeNode(member) &&
+                isArrayType(getType(member)) &&
+                member.length > 0
+                ? getSnapshot(member)
+                : undefined);
+        if (value !== undefined) {
+            plot[key] = folded(member, value);
+        }
+    }
+    return plot;
+}
+function checkKeys(draft, keys) {
+    const unknown = Object.keys(draft).filter(key => !keys.includes(key));
+    if (unknown.length > 0) {
+        throw new Error(`This display's plot is ${keys.join(', ')}, not ${unknown.join(', ')}`);
+    }
+}
+/**
+ * #api core/configuration
+ * The text as a plot, refusing a key the display's plot does not hold. The
+ * schema is the parser past this point.
+ */
+export function parsePlot(text, keys) {
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`A plot is one JSON object of ${keys.join(', ')}`);
+    }
+    checkKeys(parsed, keys);
+    return parsed;
+}
+function merged(draft, current) {
+    const out = { ...current };
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === null) {
+            delete out[key];
+        }
+        else if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * #api core/configuration
+ * A draft as the display's config would hold it, through the schema's own
+ * lift and checks: a shorthand becomes its object, a default falls off, and
+ * what a config file is refused for throws, a key outside the plot included.
+ * The node is never attached, so nothing on the display is touched; a display
+ * reads its typed members off it. The draft is copied first, since MST
+ * freezes what it creates from.
+ */
+export function liftPlot(conf, draft) {
+    checkKeys(draft, plotKeysOf(conf));
+    return getType(conf).create({
+        displayId: LIFT_ID,
+        ...structuredClone(merged(draft, plotOf(conf))),
+    });
+}
+/**
+ * #api core/configuration
+ * What applying a draft writes: each setting whose lifted value differs from
+ * the plot, as the lifted value, and `null` for one it resets. A value
+ * spelled another way but lifting to the same setting writes nothing.
+ * Throws a refusal before anything is written.
+ */
+export function plotWrites(conf, draft) {
+    const current = plotOf(conf);
+    const lifted = plotOf(liftPlot(conf, draft));
+    const writes = {};
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === undefined || compareStructural(lifted[key], current[key])) {
+            continue;
+        }
+        writes[key] = lifted[key] ?? null;
+    }
+    return writes;
+}

package/esm/configuration/readConfObject.d.ts

@@ -1,7 +1,6 @@
 import type { Feature } from '../util/index.ts';
 import type { JexlInstance } from '../util/jexlStrings.ts';
-import type { AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue } from './types.ts';
-import type { IMSTMap } from '@jbrowse/mobx-state-tree';
+import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
  * Given a configuration model (an instance of a ConfigurationSchema), read the
@@ -25,8 +24,7 @@ import type { IMSTMap } from '@jbrowse/mobx-state-tree';
  *  will be sent to each of the slotNames
  */
 export declare function readConfObject(confObject: AnyConfigurationModel): AnyConfigurationSnapshot;
-export declare function readConfObject<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : any;
-export declare function readConfObject(confObject: IMSTMap<AnyConfigurationSchemaType>, slotPath?: string | string[], args?: Record<string, unknown>): any;
+export declare function readConfObject<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
 /**
  * Read a value from a plain config snapshot object. Automatically evaluates
  * "jexl:..." strings per-feature. Works without MST — intended for use in
@@ -34,23 +32,3 @@ export declare function readConfObject(confObject: IMSTMap<AnyConfigurationSchem
  * so plugin-registered functions (e.g. in a custom `mouseover` slot) resolve.
  */
 export declare function readConfigValue<T>(config: Record<string, unknown>, key: string | string[], feature: Feature, jexl: JexlInstance): T;
-/**
- * #api core/configuration
- * Read a single config slot from a config that may be **either** a live MST
- * node or a plain snapshot object, evaluating the value if it is a `jexl:`
- * expression. For the dialogs and panels that are handed a track config without
- * knowing which of the two they got. An About panel gets a hydrated track
- * config from the session and a bare object from an embedded caller.
- *
- * Reach for `readConfObject` or `readConfigValue` when the shape is known:
- * this one decides at runtime, and the plain branch inherits the snapshot
- * caveat (a slot at its default is absent from a snapshot, so it reads
- * `undefined`).
- *
- * @param config - live config model or plain config object
- * @param slotPath - slot name, or path of sub-config names ending in a slot
- * @param args - extra arguments for a callback slot, e.g. `{ feature }`
- * @param jexl - realm jexl instance, required only to evaluate a callback slot
- *  on a plain object (a live node resolves its own from env)
- */
-export declare function readConfSlot<T = unknown>(config: AnyConfigurationModel | Record<string, unknown>, slotPath: string | string[], args?: Record<string, unknown>, jexl?: JexlInstance): T;

package/esm/configuration/readConfObject.js

@@ -1,13 +1,14 @@
 /**
  * @module
- * The config **readers**: `readConfObject` off a live MST config node,
- * `readConfigValue` off a plain snapshot object in a worker or a renderer, and
- * `readConfSlot` for the callers that hold either and don't know which. All
- * three exist to evaluate a slot's `jexl:...` callback on read; they differ only
- * in where the jexl instance comes from (the node's env vs. an explicit
- * argument) and in how much of that they are willing to decide at runtime.
+ * The config **readers**: `readConfObject` off a live MST config node, and
+ * `readConfigValue` off a plain snapshot object in a worker or a renderer. Both
+ * exist to evaluate a slot's `jexl:...` callback on read; they differ only in
+ * where the jexl instance comes from, the node's env or an explicit argument.
+ * A `featureField` slot's `jexl:` expression is the display's to evaluate per
+ * feature, so `readConfObject` hands it over as written.
  */
-import { getEnv, getSnapshot, getType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getEnv, getSnapshot, getType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 // Evaluate a slot's `jexl:...` callback string against the realm's single jexl
 // instance (carrying plugin-registered functions), read from the config node's
@@ -30,26 +31,20 @@ function evalConfigCallback(expr, args, confObject) {
     }
     return evaluateJexl(expr, args, jexl);
 }
-function isConfigMap(confObject) {
-    return isStateTreeNode(confObject) && isMapType(getType(confObject));
-}
-// Read a slot's raw stored value, drilling into a map entry via `.get()` when
-// the config is itself a types.map.
-function rawSlotValue(confObject, slotName) {
-    return isConfigMap(confObject)
-        ? confObject.get(slotName)
-        : confObject[slotName];
+function isFeatureField(confObject, slotName) {
+    return (isStateTreeNode(confObject) &&
+        !!getConfigurationSchemaMetadata(getType(confObject))?.featureFields.has(slotName));
 }
 // Read and resolve a single slot: raw value, jexl callback evaluation, then a
 // referentially-stable snapshot for sub-config nodes.
 function readSlot(confObject, slotName, args) {
     // strict undefined check, not truthiness — a slot value can legitimately be
     // falsy (0, '', false, null)
-    const value = rawSlotValue(confObject, slotName);
+    const value = confObject[slotName];
     if (value === undefined) {
         return undefined;
     }
-    const val = isCallbackValue(value)
+    const val = isCallbackValue(value) && !isFeatureField(confObject, slotName)
         ? evalConfigCallback(value, args, confObject)
         : value;
     // Fast path for primitives (most common case)
@@ -63,8 +58,9 @@ function readSlot(confObject, slotName, args) {
     return isStateTreeNode(val) ? getSnapshot(val) : val;
 }
 // loose implementation signature: the body returns values that are `any` by
-// nature (raw slot values, snapshots); the typed overload above is what callers
-// see.
+// nature (raw slot values, snapshots); the typed overloads above are what
+// callers see. No looser overload admits the model: one that did was a
+// catch-all a slot-name typo fell through to, compiling clean as `any`.
 export function readConfObject(confObject, slotPath, args = {}) {
     // the single-slot read, first and allocation-free: it is the shape of nearly
     // every one of the ~1300 call sites, so it doesn't get normalized into a
@@ -89,7 +85,7 @@ export function readConfObject(confObject, slotPath, args = {}) {
     // whole argument-shape preamble above at each level.
     let conf = confObject;
     for (let i = 0; i < slotPath.length - 1; i++) {
-        const subConf = rawSlotValue(conf, slotPath[i]);
+        const subConf = conf[slotPath[i]];
         if (subConf === undefined) {
             return undefined;
         }
@@ -97,10 +93,9 @@ export function readConfObject(confObject, slotPath, args = {}) {
     }
     return readSlot(conf, slotPath[slotPath.length - 1], args);
 }
-// The plain-object half of the slot walk, shared by readConfigValue and
-// readConfSlot. The MST half is readSlot/rawSlotValue above. A plain object has
-// no map entries and no sub-config nodes to snapshot, so it is just a path
-// reduce.
+// The plain-object half of the slot walk, for readConfigValue. The MST half is
+// readSlot/rawSlotValue above. A plain object has no map entries and no
+// sub-config nodes to snapshot, so it is just a path reduce.
 function resolveConfigValue(config, key) {
     if (Array.isArray(key)) {
         let val = config;
@@ -121,41 +116,3 @@ export function readConfigValue(config, key, feature, jexl) {
     const raw = resolveConfigValue(config, key);
     return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
 }
-/**
- * #api core/configuration
- * Read a single config slot from a config that may be **either** a live MST
- * node or a plain snapshot object, evaluating the value if it is a `jexl:`
- * expression. For the dialogs and panels that are handed a track config without
- * knowing which of the two they got. An About panel gets a hydrated track
- * config from the session and a bare object from an embedded caller.
- *
- * Reach for `readConfObject` or `readConfigValue` when the shape is known:
- * this one decides at runtime, and the plain branch inherits the snapshot
- * caveat (a slot at its default is absent from a snapshot, so it reads
- * `undefined`).
- *
- * @param config - live config model or plain config object
- * @param slotPath - slot name, or path of sub-config names ending in a slot
- * @param args - extra arguments for a callback slot, e.g. `{ feature }`
- * @param jexl - realm jexl instance, required only to evaluate a callback slot
- *  on a plain object (a live node resolves its own from env)
- */
-export function readConfSlot(config, slotPath, args = {}, jexl) {
-    if (isStateTreeNode(config)) {
-        // pass slotPath through rather than normalizing a string into a one-element
-        // array: readConfObject keeps the single-slot read allocation-free
-        return readConfObject(config, slotPath, args);
-    }
-    const value = resolveConfigValue(config, slotPath);
-    // A plain-object config has no MST env, so the realm's jexl instance can't be
-    // resolved automatically — callers reading a callback slot must pass it. Only
-    // reached when the slot actually holds a `jexl:` value (trackId/adapter/etc.
-    // never do), so non-callback readers need not supply it.
-    if (isCallbackValue(value)) {
-        if (!jexl) {
-            throw new Error(`cannot evaluate jexl config slot ${JSON.stringify(slotPath)} on a plain-object config: no jexl instance provided`);
-        }
-        return evaluateJexl(value, args, jexl);
-    }
-    return value;
-}

package/esm/configuration/requirements.d.ts

@@ -0,0 +1,37 @@
+import type { ConfigurationSchemaDefinition } from './configurationSchema.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * A combination one config object cannot mean, declared once: when every slot
+ * named in `when` holds one of the listed values, each dotted path in `slots`
+ * has to name a value — a non-empty string, or a sub-schema a string lifts
+ * into. `message` says why, and `id` is the stable name a report carries.
+ * `requirementProblems` reads it for a display's notice, and the generated
+ * JSON Schema carries it as `if`/`then` with the message, which the CLI
+ * validator and an editor report.
+ *
+ * `ConfigurationSchema()` types `when`, its values and `slots` off the
+ * definition and throws at construction for what the types cannot reach: a
+ * misspelt `when` key or value would never fire, and a misspelt path would
+ * require a key `closed` then refuses.
+ */
+export interface ConfigurationSchemaRequirement<WHEN extends Partial<Record<string, string[]>> = Partial<Record<string, string[]>>, PATH extends string = string> {
+    id: string;
+    when: WHEN;
+    slots: PATH[];
+    message: string;
+}
+/** A requirement a snapshot does not meet: the slot path left empty, and why. */
+export interface RequirementProblem {
+    id: string;
+    slot: string;
+    message: string;
+}
+export declare function checkRequirements(modelName: string, definition: ConfigurationSchemaDefinition, requires: ConfigurationSchemaRequirement[]): void;
+/**
+ * #api core/configuration
+ * The `requires` entries of a configuration schema that `snapshot` does not
+ * meet, as a config file or `getSnapshot` spells it: a slot left off reads as
+ * its default, so a `when` value that is the default fires for an absent slot,
+ * which is what the generated JSON Schema's `if` does.
+ */
+export declare function requirementProblems(type: IAnyType, snapshot: Record<string, unknown>): RequirementProblem[];