@jbrowse/core 5.0.0-beta.8 → 5.0.0-beta.9

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 { 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
@@ -40,6 +41,10 @@ function rawSlotValue(confObject, slotName) {
         ? 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) {
@@ -49,7 +54,7 @@ function readSlot(confObject, slotName, args) {
     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)
@@ -97,10 +102,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 +125,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[];

package/esm/configuration/requirements.js

@@ -0,0 +1,88 @@
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { isBareConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+function memberOf(definition, name) {
+    return Object.hasOwn(definition, name) ? definition[name] : undefined;
+}
+function subSchemaOf(entry) {
+    return isBareConfigurationSchemaType(entry)
+        ? getConfigurationSchemaMetadata(entry)
+        : undefined;
+}
+function requiredPathProblem(modelName, definition, path) {
+    const [head = '', ...rest] = path;
+    const entry = memberOf(definition, head);
+    const sub = subSchemaOf(entry);
+    return entry === undefined
+        ? `${modelName} declares no "${head}"`
+        : rest.length > 0
+            ? sub
+                ? requiredPathProblem(sub.name, sub.definition, rest)
+                : `"${head}" is not a single sub-schema, so no path runs through it`
+            : isSlotDefinitionEntry(entry)
+                ? entry.defaultValue === undefined ||
+                    typeof entry.defaultValue === 'string'
+                    ? undefined
+                    : `"${head}" holds no string, and a requirement is met by naming one`
+                : sub?.options.shorthand !== undefined
+                    ? undefined
+                    : `"${head}" is neither a slot nor a sub-schema a string lifts into`;
+}
+export function checkRequirements(modelName, definition, requires) {
+    for (const { when, slots } of requires) {
+        for (const [slot, values = []] of Object.entries(when)) {
+            const entry = memberOf(definition, slot);
+            if (!isSlotDefinitionEntry(entry)) {
+                throw new Error(`${modelName} requires something when "${slot}" holds a value, and declares no such slot`);
+            }
+            const refused = values.filter(value => entry.model?.is(value) === false);
+            if (refused.length > 0) {
+                throw new Error(`${modelName} requires something when "${slot}" holds ${refused.join(', ')}, which the slot does not take`);
+            }
+        }
+        for (const path of slots) {
+            const problem = requiredPathProblem(modelName, definition, path.split('.'));
+            if (problem) {
+                throw new Error(`${modelName} requires "${path}", and ${problem}`);
+            }
+        }
+    }
+}
+function namesAValue(definition, snapshot, path) {
+    const [head = '', ...rest] = path;
+    const value = typeof snapshot === 'object' && snapshot !== null
+        ? snapshot[head]
+        : undefined;
+    const sub = subSchemaOf(memberOf(definition, head));
+    const shorthand = sub?.options.shorthand;
+    return rest.length > 0
+        ? sub !== undefined && namesAValue(sub.definition, value, rest)
+        : typeof value === 'string'
+            ? value !== ''
+            : sub !== undefined &&
+                shorthand !== undefined &&
+                namesAValue(sub.definition, value, [shorthand]);
+}
+/**
+ * #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 function requirementProblems(type, snapshot) {
+    const schema = getConfigurationSchemaMetadata(type);
+    if (!schema) {
+        return [];
+    }
+    const { definition } = schema;
+    return (schema.options.requires ?? [])
+        .filter(({ when }) => Object.entries(when).every(([slot, values]) => {
+        const entry = memberOf(definition, slot);
+        const held = snapshot[slot] ??
+            (isSlotDefinitionEntry(entry) ? entry.defaultValue : undefined);
+        return typeof held === 'string' && values?.includes(held);
+    }))
+        .flatMap(({ id, slots, message }) => slots
+        .filter(path => !namesAValue(definition, snapshot, path.split('.')))
+        .map(slot => ({ id, slot, message })));
+}

package/esm/configuration/schemaRegistry.d.ts

@@ -1,7 +1,9 @@
 import type { ConfigurationSchemaDefinition, MergedConfigurationSchemaOptions } from './configurationSchema.ts';
-import type { AnyConfigurationModel } from './types.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType } from './types.ts';
 import type { IAnyType } from '@jbrowse/mobx-state-tree';
 export interface ConfigurationSchemaMetadata {
+    /** the name `ConfigurationSchema` was given, e.g. `FeatureColor` */
+    name: string;
     /** the raw slot/sub-schema/constant table, also carrying per-slot editor metadata */
     definition: ConfigurationSchemaDefinition;
     /**
@@ -9,10 +11,28 @@ export interface ConfigurationSchemaMetadata {
      * i.e. with any `baseConfiguration`'s hooks already composed in
      */
     options: MergedConfigurationSchemaOptions<any, any>;
+    /** the frozen-family slots, the only members a snapshot's `null` is stored in */
+    storesNull: ReadonlySet<string>;
+    /** the `featureField` slots, which the reader hands over as written */
+    featureFields: ReadonlySet<string>;
+    /** the slots that refuse a `jexl:` string: every one but a callback and a featureField */
+    takesNoCallback: ReadonlyMap<string, string>;
 }
 export declare function registerConfigurationSchema(type: IAnyType, metadata: ConfigurationSchemaMetadata): void;
 export declare function getConfigurationSchemaMetadata(type: IAnyType): ConfigurationSchemaMetadata | undefined;
 export declare function isRegisteredConfigurationSchema(type: IAnyType): boolean;
+export interface ConfigurationSchemaUnionMetadata {
+    /** the name `ConfigurationSchemaUnion` was given, e.g. `MarkTransform` */
+    name: string;
+    /** each member schema, keyed by the `type` it answers to */
+    members: Record<string, AnyConfigurationSchemaType>;
+}
+export declare function registerConfigurationSchemaUnion(type: IAnyType, metadata: ConfigurationSchemaUnionMetadata): void;
+/**
+ * The name and members of a union `ConfigurationSchemaUnion` built, or
+ * undefined for any other type — a pluggable element union included.
+ */
+export declare function getConfigurationSchemaUnion(type: IAnyType): ConfigurationSchemaUnionMetadata | undefined;
 /**
  * The slot/sub-schema/constant table for a config (includes slots merged in from
  * `baseConfiguration` at schema construction). Undefined when the argument isn't

package/esm/configuration/schemaRegistry.js

@@ -19,6 +19,17 @@ export function getConfigurationSchemaMetadata(type) {
 export function isRegisteredConfigurationSchema(type) {
     return schemaRegistry.has(type);
 }
+const unionRegistry = new WeakMap();
+export function registerConfigurationSchemaUnion(type, metadata) {
+    unionRegistry.set(type, metadata);
+}
+/**
+ * The name and members of a union `ConfigurationSchemaUnion` built, or
+ * undefined for any other type — a pluggable element union included.
+ */
+export function getConfigurationSchemaUnion(type) {
+    return unionRegistry.get(type);
+}
 // The three lookups above take a schema *type*; the two below take a live config
 // *node* and make the `getType` hop themselves, which is what every reader
 // actually wants — a node is what they hold. Leaving the hop to the call site is

package/esm/configuration/schemaTypes.d.ts

@@ -1,3 +1,4 @@
+import type { MergedConfigurationSchemaOptions } from './configurationSchema.ts';
 import type { ConfigSlotDefinition } from './configurationSlot.ts';
 import type { AnyConfigurationModel, AnyConfigurationSchemaType } from './types.ts';
 /**
@@ -20,4 +21,6 @@ export declare function isConfigurationSchemaType(thing: unknown): thing is AnyC
  */
 export declare function isConstantEntry(def: unknown): def is string | number;
 export declare function isSlotDefinitionEntry(def: unknown): def is ConfigSlotDefinition;
+/** The prop an explicit or implicit identifier option installs, named `id` when the option is `true`. */
+export declare function identifierName({ explicitIdentifier, implicitIdentifier, }: MergedConfigurationSchemaOptions<any, any>): string | undefined;
 export declare function isConfigurationModel(thing: unknown): thing is AnyConfigurationModel;

package/esm/configuration/schemaTypes.js

@@ -21,6 +21,11 @@ export function getTypeNamesFromExplicitlyTypedUnion(maybeUnionType) {
         if (isUnionType(resolved)) {
             const typeNames = [];
             for (const subType of getUnionSubTypes(resolved)) {
+                // the branch a `maybe`-like union adds so the slot can be absent, not
+                // a schema — `isConfigurationSchemaType` already skips it the same way
+                if (subType.name === 'undefined') {
+                    continue;
+                }
                 const resolvedSub = resolveLateType(subType);
                 // a nested union contributes its own names; otherwise the subtype is a
                 // single explicitly-typed schema whose name is its default's `type`
@@ -89,6 +94,11 @@ export function isConstantEntry(def) {
 export function isSlotDefinitionEntry(def) {
     return (typeof def === 'object' && def !== null && !isType(def) && 'type' in def);
 }
+/** The prop an explicit or implicit identifier option installs, named `id` when the option is `true`. */
+export function identifierName({ explicitIdentifier, implicitIdentifier, }) {
+    const spec = explicitIdentifier || implicitIdentifier;
+    return spec ? (typeof spec === 'string' ? spec : 'id') : undefined;
+}
 export function isConfigurationModel(thing) {
     return isStateTreeNode(thing) && isConfigurationSchemaType(getType(thing));
 }

package/esm/configuration/slotFacade.d.ts

@@ -1,11 +1,32 @@
 import type PluginManager from '../PluginManager.ts';
 import type { ConfigSlotDefinition, ConfigSlotType } from './configurationSlot.ts';
 import type { AnyConfigurationModel } from './types.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
 /**
  * Whether `slotName` on a config node is a slot (vs a nested sub-schema or a
  * string/number constant).
  */
 export declare function isConfigurationSlot(node: AnyConfigurationModel, slotName: string): boolean;
+/**
+ * Whether `slotName` on a config node is a single nested sub-schema, the kind
+ * `setSubschema` replaces whole (not an array or map of them).
+ */
+export declare function isConfigurationSubschema(node: AnyConfigurationModel, slotName: string): boolean;
+/**
+ * What to hand `setSubschema` for a write of `slotName`: `value` itself where
+ * the sub-schema is a channel, and the node's own snapshot with `value`'s
+ * members over it — recursing into the namespaces inside it — where it is not.
+ * `null` resets at any depth of a namespace, the way it resets a slot (ADR-146).
+ *
+ * **A `shorthand` is what tells the two apart.** A sub-schema that takes a bare
+ * string takes one written value, so `{ field: 'biotype' }` after
+ * `{ field: 'biotype', domain: [...] }` is a colour or facet with no domain,
+ * and a merge would leave the old one standing with no way to clear it. A
+ * sub-schema with no shorthand is a namespace of independent settings, where
+ * `{ scales: { y: { domainMin: 5 } } }` means "pin the bottom" and used to
+ * reset `type` and `autoscale` with it.
+ */
+export declare function mergedSubschemaValue(node: AnyConfigurationModel, slotName: string, value: unknown): {};
 /**
  * Run `node`'s own schema `preProcessSnapshot` over a partial bag of slot
  * values headed for that config.
@@ -19,6 +40,13 @@ export declare function isConfigurationSlot(node: AnyConfigurationModel, slotNam
  * is the same shape they already tolerate.
  */
 export declare function preProcessSlotValues(node: AnyConfigurationModel, values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Why a config of type `schema` cannot hold `value` at `key`, or undefined
+ * when it can: the schema's own lift first, then the slot's type, or a
+ * sub-schema's lift and checks. Also undefined for a key the schema does not
+ * declare, which is a question for its caller.
+ */
+export declare function slotValueRefusal(schema: IAnyType, key: string, value: unknown): string | undefined;
 /**
  * The duck-typed object the config editor's leaf components consume. They never
  * touch MST internals — only this shape (see ColorEditor.test.tsx, which passes
@@ -32,7 +60,10 @@ export interface SlotFacade {
     type: ConfigSlotType;
     contextVariable: string[];
     defaultValue: unknown;
-    /** enum choices, present only for `stringEnum`/`maybeStringEnum` slots */
+    /**
+     * enum choices, present only for the enum slot types; a `stringEnumArray`'s
+     * are the choices of each entry
+     */
     choices?: string[];
     pluginManager: PluginManager;
     readonly value: unknown;
@@ -47,9 +78,9 @@ export interface SlotFacade {
 }
 /**
  * The vocabulary an enum slot offers, or undefined for any other slot. Reads the
- * author's own `types.enumeration` off `model` — `stringEnum` and
- * `maybeStringEnum` are the only two types the editor takes choices from, so a
- * slot typed anything else renders as free text however valid its `model` is.
+ * author's own `types.enumeration` off `model` — the enum types are the only
+ * ones the editor takes choices from, so a slot typed anything else renders as
+ * free text however valid its `model` is.
  *
  * Shared by the config editor's facade below and by
  * `ConfigSlotDefaults.test.ts`, which snapshots every schema's vocabularies:

package/esm/configuration/slotFacade.js

@@ -1,8 +1,10 @@
-import { getSnapshot } from '@jbrowse/mobx-state-tree';
+import { getSnapshot, getType, isArrayType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import { getEnumerationValues } from '../util/mst-reflection.js';
 import { getEnv } from '../util/mstUtils.js';
-import { getConfigurationSchemaDefinition, getConfigurationSchemaOptions, } from './schemaRegistry.js';
-import { isSlotDefinitionEntry } from './schemaTypes.js';
+import ConfigSlot, { slotWriteRefusal } from './configurationSlot.js';
+import { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, getConfigurationSchemaOptions, } from './schemaRegistry.js';
+import { isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
 /**
  * The slot's metadata entry, or undefined when `slotName` names a nested
  * sub-schema or a string/number constant rather than a slot.
@@ -18,6 +20,59 @@ function slotDefinition(node, slotName) {
 export function isConfigurationSlot(node, slotName) {
     return !!slotDefinition(node, slotName);
 }
+/**
+ * Whether `slotName` on a config node is a single nested sub-schema, the kind
+ * `setSubschema` replaces whole (not an array or map of them).
+ */
+export function isConfigurationSubschema(node, slotName) {
+    const def = getConfigurationSchemaDefinition(node)?.[slotName];
+    return isConfigurationSchemaType(def) && !isArrayType(def) && !isMapType(def);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isNamespace(member) {
+    const options = isStateTreeNode(member)
+        ? getConfigurationSchemaOptions(member)
+        : undefined;
+    return !!options && options.shorthand === undefined;
+}
+// JSON Merge Patch (RFC 7396) over a namespace's snapshot: a `null` member
+// leaves the key out, which a stripDefault snapshot reads as the default
+function mergePatch(namespace, patch) {
+    const out = { ...getSnapshot(namespace) };
+    for (const [k, v] of Object.entries(patch)) {
+        const member = namespace[k];
+        if (v === null) {
+            delete out[k];
+        }
+        else {
+            out[k] =
+                isPlainObject(v) && isNamespace(member) ? mergePatch(member, v) : v;
+        }
+    }
+    return out;
+}
+/**
+ * What to hand `setSubschema` for a write of `slotName`: `value` itself where
+ * the sub-schema is a channel, and the node's own snapshot with `value`'s
+ * members over it — recursing into the namespaces inside it — where it is not.
+ * `null` resets at any depth of a namespace, the way it resets a slot (ADR-146).
+ *
+ * **A `shorthand` is what tells the two apart.** A sub-schema that takes a bare
+ * string takes one written value, so `{ field: 'biotype' }` after
+ * `{ field: 'biotype', domain: [...] }` is a colour or facet with no domain,
+ * and a merge would leave the old one standing with no way to clear it. A
+ * sub-schema with no shorthand is a namespace of independent settings, where
+ * `{ scales: { y: { domainMin: 5 } } }` means "pin the bottom" and used to
+ * reset `type` and `autoscale` with it.
+ */
+export function mergedSubschemaValue(node, slotName, value) {
+    const existing = node[slotName];
+    return isPlainObject(value) && isNamespace(existing)
+        ? mergePatch(existing, value)
+        : (value ?? {});
+}
 /**
  * Run `node`'s own schema `preProcessSnapshot` over a partial bag of slot
  * values headed for that config.
@@ -31,14 +86,43 @@ export function isConfigurationSlot(node, slotName) {
  * is the same shape they already tolerate.
  */
 export function preProcessSlotValues(node, values) {
-    const preProcess = getConfigurationSchemaOptions(node)?.preProcessSnapshot;
-    return preProcess ? preProcess(values) : values;
+    const schema = getConfigurationSchemaMetadata(getType(node));
+    return schema ? preProcessSnapshotWith(schema, values) : values;
+}
+/**
+ * Why a config of type `schema` cannot hold `value` at `key`, or undefined
+ * when it can: the schema's own lift first, then the slot's type, or a
+ * sub-schema's lift and checks. Also undefined for a key the schema does not
+ * declare, which is a question for its caller.
+ */
+export function slotValueRefusal(schema, key, value) {
+    const meta = getConfigurationSchemaMetadata(schema);
+    const entry = meta?.definition[key];
+    if (!meta || entry === undefined) {
+        return undefined;
+    }
+    const subSchema = isConfigurationSchemaType(entry)
+        ? entry
+        : undefined;
+    try {
+        const lifted = preProcessSnapshotWith(meta, { [key]: value })[key];
+        if (subSchema) {
+            subSchema.create(lifted);
+        }
+        else if (isSlotDefinitionEntry(entry) && !ConfigSlot(entry).is(lifted)) {
+            return slotWriteRefusal(`${meta.name}.${key}`, entry.type, value);
+        }
+        return undefined;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
 }
 /**
  * The vocabulary an enum slot offers, or undefined for any other slot. Reads the
- * author's own `types.enumeration` off `model` — `stringEnum` and
- * `maybeStringEnum` are the only two types the editor takes choices from, so a
- * slot typed anything else renders as free text however valid its `model` is.
+ * author's own `types.enumeration` off `model` — the enum types are the only
+ * ones the editor takes choices from, so a slot typed anything else renders as
+ * free text however valid its `model` is.
  *
  * Shared by the config editor's facade below and by
  * `ConfigSlotDefaults.test.ts`, which snapshots every schema's vocabularies:
@@ -47,7 +131,10 @@ export function preProcessSlotValues(node, values) {
  */
 export function slotChoices(def) {
     const { type, model } = def;
-    return (type === 'stringEnum' || type === 'maybeStringEnum') && model
+    return (type === 'stringEnum' ||
+        type === 'maybeStringEnum' ||
+        type === 'stringEnumArray') &&
+        model
         ? getEnumerationValues(model)
         : undefined;
 }

package/esm/configuration/snapshotPreprocess.d.ts

@@ -0,0 +1,27 @@
+import type { ConfigurationSchemaMetadata } from './schemaRegistry.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+export declare function listed(keys: readonly string[]): string;
+/**
+ * The bare value a schema's `shorthand` lifts: a number where the slot it
+ * names holds one (`rules: [7.3]`), a string otherwise (`color: 'red'`).
+ */
+export declare function shorthandForm({ definition, options, }: ConfigurationSchemaMetadata): 'string' | 'number' | undefined;
+/**
+ * What a schema does to every snapshot on its way in, whichever door it
+ * arrives by (`create`, `applySnapshot`, `setSubschema`, a settings bag): a
+ * bare string or number lifts into the declared `shorthand` slot, beside any
+ * `shorthandWith` slots, and `null` into the empty object that clears it; a
+ * `null` member reads as unset, except in a frozen-family slot, which stores
+ * it; a `closed` schema refuses a key it does not declare, then the schema's
+ * own `preProcessSnapshot` runs, and a `jexl:` callback in a slot declaring no
+ * `contextVariable` is refused. A bare value the shorthand does not lift
+ * passes through for MST to refuse.
+ */
+export declare function preProcessSnapshotWith(schema: ConfigurationSchemaMetadata, snapshot: unknown): Record<string, unknown>;
+/**
+ * #api core/configuration
+ * A snapshot as `type` admits it: the same lift and checks `type.create`
+ * applies, so a dialog or a validator refuses exactly what a config file
+ * cannot hold. Throws what the schema's `preProcessSnapshot` throws.
+ */
+export declare function preProcessConfigSnapshot(type: IAnyType, snapshot: unknown): Record<string, unknown>;

package/esm/configuration/snapshotPreprocess.js

@@ -0,0 +1,102 @@
+import { isJexl } from '../util/jexlStrings.js';
+import { slotWriteRefusal } from './configurationSlot.js';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { identifierName, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
+// the keys a config file may annotate any object with, as the JSON schema's
+// `patternProperties` admits them
+const COMMENT_KEY = /^_+comment/;
+export function listed(keys) {
+    return keys.length > 1
+        ? `${keys.slice(0, -1).join(', ')} and ${keys.at(-1)}`
+        : (keys[0] ?? 'nothing');
+}
+function refuseUndeclaredKeys({ name, definition, options }, snapshot) {
+    const id = identifierName(options);
+    const declared = [
+        ...Object.keys(definition).filter(key => !isConstantEntry(definition[key])),
+        ...(options.explicitlyTyped ? ['type'] : []),
+        ...(id ? [id] : []),
+    ];
+    const unknown = typeof snapshot === 'string'
+        ? [JSON.stringify(snapshot)]
+        : Object.keys(snapshot ?? {}).filter(key => !declared.includes(key) && !COMMENT_KEY.test(key));
+    if (unknown.length > 0) {
+        throw new Error(`${name} takes ${listed(declared)}, not ${unknown.join(', ')}`);
+    }
+}
+// Checked here as well as by each slot's MST type because this runs on every
+// create, where MST's own check is off in a build that has not enabled it
+function refuseCallbacks({ name, takesNoCallback }, snapshot) {
+    if (typeof snapshot === 'object' && snapshot !== null) {
+        for (const key in snapshot) {
+            const type = takesNoCallback.get(key);
+            const value = snapshot[key];
+            if (type !== undefined && isJexl(value)) {
+                throw new Error(slotWriteRefusal(`${name}.${key}`, type, value));
+            }
+        }
+    }
+}
+const NUMBER_SLOT_TYPES = new Set(['number', 'integer', 'maybeNumber']);
+/**
+ * The bare value a schema's `shorthand` lifts: a number where the slot it
+ * names holds one (`rules: [7.3]`), a string otherwise (`color: 'red'`).
+ */
+export function shorthandForm({ definition, options, }) {
+    const { shorthand } = options;
+    const entry = shorthand === undefined ? undefined : definition[shorthand];
+    return shorthand === undefined
+        ? undefined
+        : isSlotDefinitionEntry(entry) && NUMBER_SLOT_TYPES.has(entry.type)
+            ? 'number'
+            : 'string';
+}
+// ADR-146's reset, on the snapshot path: the member keeps its key, so a
+// settings bag still resets it, and `create` reads `undefined` as the default
+function nullMembersAsUnset(snapshot, storesNull) {
+    let out = snapshot;
+    for (const key in snapshot) {
+        if (snapshot[key] === null && !storesNull.has(key)) {
+            out = out === snapshot ? { ...snapshot } : out;
+            out[key] = undefined;
+        }
+    }
+    return out;
+}
+/**
+ * What a schema does to every snapshot on its way in, whichever door it
+ * arrives by (`create`, `applySnapshot`, `setSubschema`, a settings bag): a
+ * bare string or number lifts into the declared `shorthand` slot, beside any
+ * `shorthandWith` slots, and `null` into the empty object that clears it; a
+ * `null` member reads as unset, except in a frozen-family slot, which stores
+ * it; a `closed` schema refuses a key it does not declare, then the schema's
+ * own `preProcessSnapshot` runs, and a `jexl:` callback in a slot declaring no
+ * `contextVariable` is refused. A bare value the shorthand does not lift
+ * passes through for MST to refuse.
+ */
+export function preProcessSnapshotWith(schema, snapshot) {
+    const { shorthand, shorthandWith, closed, preProcessSnapshot } = schema.options;
+    const lifted = snapshot === null
+        ? {}
+        : shorthand !== undefined && typeof snapshot === shorthandForm(schema)
+            ? { ...shorthandWith, [shorthand]: snapshot }
+            : nullMembersAsUnset(snapshot, schema.storesNull);
+    if (closed) {
+        refuseUndeclaredKeys(schema, lifted);
+    }
+    const processed = preProcessSnapshot ? preProcessSnapshot(lifted) : lifted;
+    refuseCallbacks(schema, processed);
+    return processed;
+}
+/**
+ * #api core/configuration
+ * A snapshot as `type` admits it: the same lift and checks `type.create`
+ * applies, so a dialog or a validator refuses exactly what a config file
+ * cannot hold. Throws what the schema's `preProcessSnapshot` throws.
+ */
+export function preProcessConfigSnapshot(type, snapshot) {
+    const schema = getConfigurationSchemaMetadata(type);
+    return schema
+        ? preProcessSnapshotWith(schema, snapshot)
+        : snapshot;
+}