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

package/esm/configuration/configurationSlot.js

@@ -3,28 +3,22 @@ import { isCssColor } from '../util/cssColorParse.js';
 import { isJexl, stringToJexlExpression } from '../util/jexlStrings.js';
 import { FileLocation, JexlExpressionString } from '../util/types/mst.js';
 import { isCallbackValue } from './slotValueUtils.js';
-// What a color slot admits is what the painters parse (`isCssColor`), plus the
-// empty string a slot such as `outlineColor` spells "none" with; a field name
-// written where a color goes used to load and paint the invalid sentinel.
 function notAColor(value) {
-    return `${JSON.stringify(value)} is not a color. A color is a CSS color: a name like "red" or "steelblue", "#rgb" / "#rrggbb" / "#rrggbbaa", "rgb()" / "rgba()" / "hsl()" / "hsla()", or "transparent"; a color computed per feature is a "jexl:" callback, in a slot that takes one`;
+    return `${JSON.stringify(value)} is not a color. A color is a CSS color: a name like "red" or "steelblue", "#rgb" / "#rrggbb" / "#rrggbbaa", "rgb()" / "rgba()" / "hsl()" / "hsla()", "transparent" or a BED triple like "255,0,0"; a color computed per feature is a "jexl:" callback, in a slot that takes one`;
 }
+// '' is a color slot's "none", as in `rowColor.unknown`
 const CssColorType = types.refinement('CssColor', types.string, value => value === '' || isCssColor(value), notAColor);
-// An entry of a colour list has no "none" to spell, so '' is refused with the
-// rest of what is not a colour.
+// a color list's entry has no "none" to spell
 const CssColorEntryType = types.refinement('CssColorEntry', types.string, isCssColor, notAColor);
 const MaybeFileLocation = types.snapshotProcessor(types.maybe(FileLocation), {
-    preProcessor: (snap) => snap && 'uri' in snap && snap.uri === '' ? undefined : snap,
+    preProcessor: (snap) => snap &&
+        (('uri' in snap && snap.uri === '') ||
+            ('localPath' in snap && snap.localPath === ''))
+        ? undefined
+        : snap,
 });
-// Single source of truth for the builtin slot type names, pairing each with its
-// MST value type and its editor fallback default. Keeping model + fallback in
-// one table means adding a slot type is one edit and can't half-register.
-//
-// `satisfies` rather than an annotation: a `Record<string, …>` annotation
-// widens the keys to `string`, which is what let `type: 'enum'` — a name this
-// table has never had — compile for years and silently lose the config
-// editor's dropdown. The literal keys are what `ConfigSlotType` below is made
-// of.
+// The slot type vocabulary. `satisfies`, not an annotation, so the literal keys
+// make up `ConfigSlotType`; every surface naming a type checks against it.
 const slotTypes = {
     stringArray: { model: types.array(types.string), fallbackDefault: [] },
     expressionArray: {
@@ -42,23 +36,17 @@ const slotTypes = {
     color: { model: CssColorType, fallbackDefault: 'black' },
     integer: { model: types.integer, fallbackDefault: 1 },
     number: { model: types.number, fallbackDefault: 1 },
-    // The `maybe*` types spend `undefined` on "not explicitly set", which is the
-    // one value no config can spell and so the only reliable way to say it — a
-    // computed/auto fallback, e.g. a drag-resized track height.
+    // a `maybe*` type's unset is `undefined`, the one value no config spells:
+    // "decide from the data", as an auto-fitted height or a BED itemRgb color
     maybeNumber: { model: types.maybe(types.number) },
     maybeBoolean: { model: types.maybe(types.boolean) },
-    // for a slot whose unset state means "decide from the data" — a feature's own
-    // BED itemRgb, say
     maybeColor: { model: types.maybe(CssColorType) },
-    // object-valued, e.g. alignments `sortedBy`
     maybeFrozen: { model: types.maybe(types.frozen()) },
-    // for text whose unset state is a third thing beside some text and none: an
-    // axis title is derived while unset, and drawn bare once it is ''
     maybeString: { model: types.maybe(types.string) },
     string: { model: types.string, fallbackDefault: '' },
     text: { model: types.string, fallbackDefault: '' },
-    // a field the display reads per feature: a name, a dotted path, or a
-    // `jexl:` expression, which the display evaluates and the reader never does
+    // a field the display reads per feature; its `jexl:` expression is the
+    // display's to evaluate, never the reader's
     featureField: { model: types.string, fallbackDefault: '' },
     fileLocation: {
         model: FileLocation,
@@ -67,48 +55,25 @@ const slotTypes = {
             locationType: 'UriLocation',
         },
     },
-    // for a sidecar the adapter works without: unset means no file is
-    // configured, and so does the `{ uri: '' }` a cleared URL field in the
-    // config editor writes
+    // a sidecar the adapter works without; the editor's cleared `{ uri: '' }`
+    // reads as unset
     maybeFileLocation: { model: MaybeFileLocation },
     frozen: { model: types.frozen(), fallbackDefault: {} },
 };
-// The types with no builtin table entry, because the author supplies the
-// `types.enumeration` as `model` and `ConfigSlot` wraps it: in `types.maybe`
-// for `maybeStringEnum`, in `types.array` for `stringEnumArray`. Named once,
-// and spliced into both the type union and the runtime set below so those two
-// cannot drift apart.
+// the author supplies the `types.enumeration` as `model`, and `ConfigSlot`
+// wraps it in `types.maybe` or `types.array`
 const ENUM_SLOT_TYPES = [
     'stringEnum',
     'maybeStringEnum',
     'stringEnumArray',
 ];
-/**
- * The same closed set, at runtime, because the type alone does not close it for
- * the callers that matter most: `ConfigSlot` is plugin-facing, and a JS plugin
- * or one built against an older core reaches it with no checking at all. Those
- * are exactly the callers that hit the silent-degradation trap above, and
- * `type: 'enum'` — a name this table has never had — is the one that did.
- *
- * Typed `Set<string>` rather than `Set<ConfigSlotType>` so the membership test
- * stays a question TypeScript has not already answered for in-tree callers. It
- * is a real runtime check, not a restatement of the signature.
- */
+// the same set at runtime, for a JS plugin the type never checked
 const CONFIG_SLOT_TYPE_NAMES = new Set([
     ...Object.keys(slotTypes),
     ...ENUM_SLOT_TYPES,
 ]);
-// Lookup view over the table. The two enum types are legal `ConfigSlotType`s
-// with no entry, so indexing by the union has to tolerate a miss — this states
-// that in the type rather than casting it away at each call.
 const builtinSlotTypes = slotTypes;
-// The slot types whose default is `undefined` — the genuine "unset" state,
-// distinguishable from every value a config can spell. Mostly derived from the
-// table above (they're exactly the entries with no `fallbackDefault`, since
-// "unset" is their fixed form) so the two can't drift. `maybeStringEnum` is
-// named explicitly because, like plain `stringEnum`, it has no builtin model:
-// the author supplies the enumeration and `ConfigSlot` wraps it in
-// `types.maybe`.
+// an entry with no `fallbackDefault` is one whose fixed form is unset
 const MAYBE_TYPES = new Set([
     ...Object.entries(slotTypes)
         .filter(([, spec]) => spec.fallbackDefault === undefined)
@@ -135,23 +100,10 @@ function refusingCallbacks(model) {
     return types.refinement(model, value => !isJexl(value), notACallbackSlot);
 }
 /**
- * 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) {
     const { model, type, defaultValue } = definition;
@@ -162,24 +114,15 @@ export default function ConfigSlot(definition) {
     if (!valueModel) {
         throw new Error(`no builtin config slot type "${type}", and no 'model' param provided`);
     }
-    // the `maybe*` types intentionally default to `undefined` (the "unset"
-    // state); every other slot type must declare a concrete default so a missing
-    // one is caught as an authoring mistake.
+    if (defaultValue === null) {
+        throw new Error(`a slot cannot default to null, which a write reads as a reset to the default (ADR-146): a slot meaning "unset" is a maybe* type, such as maybeFrozen`);
+    }
     if (defaultValue === undefined && !MAYBE_TYPES.has(type)) {
         throw new Error("no 'defaultValue' provided");
     }
-    // The inverse of the `defaultValue === undefined` check above, and the half
-    // that had no guard. A `maybe*` slot whose default is concrete can never *be*
-    // unset — no config can spell `undefined` — so the unset state such a slot
-    // exists to express (auto-fit, decide-from-the-data, inherit) is unreachable
-    // and the branch reading it never runs. There is no symptom: the slot reads as
-    // a perfectly good value everywhere.
-    //
-    // The way this happens is **inheritance**, which is why the type can't catch
-    // it: a `maybe*` override of a plain base slot inherits the base's concrete
-    // default through the definition spread, and the override's own literal looks
-    // right. `LinearMafDisplay.height` over `BaseLinearDisplay`'s `number`/100 is
-    // the case in the repo, and only that display's own tests noticed.
+    // A concrete default makes a maybe* slot's unset state unreachable, with no
+    // symptom. It arrives by inheritance: an override spread over a base slot's
+    // default.
     if (defaultValue !== undefined && MAYBE_TYPES.has(type)) {
         throw new Error(`a "${type}" slot cannot have a concrete defaultValue (${JSON.stringify(defaultValue)}): unset is the state a maybe* slot exists for, and no config can spell undefined, so it would be unreachable. If this slot overrides a base slot, the base's defaultValue merged in — state 'defaultValue: undefined' to overwrite it. Otherwise use the non-maybe form of the type.`);
     }
@@ -187,7 +130,7 @@ export default function ConfigSlot(definition) {
     if (type === 'featureField' && callback) {
         throw new Error('a "featureField" slot names a field the display reads per feature, and its jexl: expression is evaluated there, never called with a contextVariable. If this slot overrides a base callback slot, state \'contextVariable: undefined\'.');
     }
-    if (!callback && isJexl(defaultValue)) {
+    if (!callback && type !== 'featureField' && isJexl(defaultValue)) {
         throw new Error(`the defaultValue ${JSON.stringify(defaultValue)} is a jexl: callback, so the slot declares the contextVariable names it reads`);
     }
     const value = enumShaped(type, valueModel);
@@ -197,8 +140,6 @@ export default function ConfigSlot(definition) {
             ? value
             : refusingCallbacks(value), defaultValue);
 }
-// The author writes an enum slot's plain vocabulary, and the slot's shape
-// around it is added here.
 function enumShaped(type, model) {
     return type === 'maybeStringEnum'
         ? types.maybe(model)
@@ -206,14 +147,7 @@ function enumShaped(type, model) {
             ? types.array(model)
             : model;
 }
-/**
- * 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 function toCallbackValue(value) {
     return isCallbackValue(value) ? value : `jexl:${JSON.stringify(value)}`;
 }

package/esm/configuration/fillLocations.d.ts

@@ -1,7 +1,9 @@
 /**
  * A shorthand snapshot with its location slots filled in: `derived` supplies
  * what the shorthand implies, and any key the config spells out for itself
- * wins.
+ * wins. The shorthand's own keys leave the result, `uri` and `baseUri` and
+ * whichever others `consumed` names, since an adapter's schema is `closed`
+ * and would name one left behind as undeclared.
  *
  * Spread the other way round — derived over the snapshot — a config naming both
  * a `uri` and a location that is not the sibling of it, `{ uri: 'x.fa',
@@ -9,6 +11,6 @@
  * the one the shorthand invents. Every adapter's normalizer had its own copy of
  * the spread, so the precedence had to be got right 30-odd times.
  */
-export declare function fillLocations(snap: Record<string, unknown>, derived: Record<string, unknown>): {
+export declare function fillLocations(snap: Record<string, unknown>, derived: Record<string, unknown>, consumed?: readonly string[]): {
     [x: string]: unknown;
 };

package/esm/configuration/fillLocations.js

@@ -1,7 +1,9 @@
 /**
  * A shorthand snapshot with its location slots filled in: `derived` supplies
  * what the shorthand implies, and any key the config spells out for itself
- * wins.
+ * wins. The shorthand's own keys leave the result, `uri` and `baseUri` and
+ * whichever others `consumed` names, since an adapter's schema is `closed`
+ * and would name one left behind as undeclared.
  *
  * Spread the other way round — derived over the snapshot — a config naming both
  * a `uri` and a location that is not the sibling of it, `{ uri: 'x.fa',
@@ -9,6 +11,10 @@
  * the one the shorthand invents. Every adapter's normalizer had its own copy of
  * the spread, so the precedence had to be got right 30-odd times.
  */
-export function fillLocations(snap, derived) {
-    return { ...derived, ...snap };
+export function fillLocations(snap, derived, consumed = []) {
+    const written = { ...snap };
+    for (const key of ['uri', 'baseUri', ...consumed]) {
+        delete written[key];
+    }
+    return { ...derived, ...written };
 }

package/esm/configuration/formatAboutConfigSchema.d.ts

@@ -1,8 +1,8 @@
 /**
  * #config FormatAbout
  * #category root
- * jexl callbacks that add, rewrite or hide fields in a track's About dialog.
- * The same schema hangs off every track and off the session as
+ * Holds jexl callbacks that add, rewrite or hide fields in a track's About
+ * dialog. Every track has this schema, and so does the root config as
  * `configuration.formatAbout`, which applies to every track at once. Where both
  * are set the track's object is spread over the session's, so a track can
  * override individual keys the global callback added.

package/esm/configuration/formatAboutConfigSchema.js

@@ -2,8 +2,8 @@ import { ConfigurationSchema } from './configurationSchema.js';
 /**
  * #config FormatAbout
  * #category root
- * jexl callbacks that add, rewrite or hide fields in a track's About dialog.
- * The same schema hangs off every track and off the session as
+ * Holds jexl callbacks that add, rewrite or hide fields in a track's About
+ * dialog. Every track has this schema, and so does the root config as
  * `configuration.formatAbout`, which applies to every track at once. Where both
  * are set the track's object is spread over the session's, so a track can
  * override individual keys the global callback added.

package/esm/configuration/formatDetailsConfigSchema.d.ts

@@ -7,8 +7,8 @@ export declare const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
 /**
  * #config FormatDetails
  * #category root
- * jexl callbacks that add, rewrite or hide fields in the feature-details panel.
- * The same schema hangs off every track and off the session as
+ * Holds jexl callbacks that add, rewrite or hide fields in the feature-details
+ * panel. Every track has this schema, and so does the root config as
  * `configuration.formatDetails`, which applies to every track at once. Where
  * both are set, the callbacks merge with the track's object over the session's,
  * so a track can override individual keys the global callback added, and the

package/esm/configuration/formatDetailsConfigSchema.js

@@ -8,8 +8,8 @@ export const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
 /**
  * #config FormatDetails
  * #category root
- * jexl callbacks that add, rewrite or hide fields in the feature-details panel.
- * The same schema hangs off every track and off the session as
+ * Holds jexl callbacks that add, rewrite or hide fields in the feature-details
+ * panel. Every track has this schema, and so does the root config as
  * `configuration.formatDetails`, which applies to every track at once. Where
  * both are set, the callbacks merge with the track's object over the session's,
  * so a track can override individual keys the global callback added, and the
@@ -64,7 +64,7 @@ export function FormatDetailsConfigSchemaFactory() {
         },
         /**
          * #slot formatDetails.depth
-         * how many levels of subfeature the `subfeatures` callback runs on,
+         * The number of subfeature levels the `subfeatures` callback runs on,
          * defaulting to 2, which stops at a gene's transcripts rather than
          * descending into their exons and CDSs. A track's value wins over the
          * session's
@@ -72,16 +72,18 @@ export function FormatDetailsConfigSchemaFactory() {
         depth: {
             type: 'maybeNumber',
             description: 'levels of subfeature the formatDetails.subfeatures callback runs on, default 2',
+            advanced: true,
         },
         /**
          * #slot formatDetails.maxDepth
-         * how many levels of subfeature card the panel renders at all, which is a
-         * separate question from how deep `subfeatures` formats. Unset means no
+         * The number of subfeature card levels the panel renders at all,
+         * independent of how deep `subfeatures` formats. Unset means no
          * limit. A track's value wins over the session's
          */
         maxDepth: {
             type: 'maybeNumber',
             description: 'hide subfeatures nested deeper than this, default no limit',
+            advanced: true,
         },
     });
 }

package/esm/configuration/getConf.d.ts

@@ -1,15 +1,8 @@
 import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
- * Reads a configuration value from a state model that has a `.configuration`
- * member (a track or display state model). For a raw configuration model, use
- * `readConfObject` instead.
- *
- * **This is exactly `readConfObject(model.configuration, path)`** — sugar for
- * the `.configuration` hop, and nothing more. The two readers carry the same
- * slot-name check, so reaching for the other one does not get a typo past tsc.
- * It does not consult the session and has no per-slot behavior; what you read is
- * what the track stores.
+ * Reads a configuration value from a track or display state model: exactly
+ * `readConfObject(model.configuration, path)`, with the same slot-name check.
  *
  * @param model - object containing a 'configuration' member
  * @param slotPaths - array of paths to read
@@ -29,33 +22,11 @@ export declare function getConf<CONFMODEL extends AnyConfigurationModel, const S
  * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
  * model, or a config node directly.
  *
- * **The path length says what the write replaces.** A path ending on a slot
- * writes that slot and leaves the object around it alone; a path ending on a
- * sub-schema replaces the whole object, which is how a channel whose members
- * move together — a facet's field and the domain that field's values order —
- * gets written without a stale member surviving underneath.
- *
- * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
- * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
- * unknown slot name is a compile error. `setSlot` itself stays untyped on
- * purpose — the config editor's slot facade routes dynamic slot names through
- * it (`configurationSchema.ts`) — and guards the name at runtime instead
- * (ADR-052), so a misspelled write is diagnosed one way or the other.
- *
- * **The read is the half with no diagnostic at all.** `getConf` for a name the
- * schema doesn't declare returns `undefined` and reports nothing, at any layer,
- * so the slot keeps reading as its default forever. Which makes the
- * compile-time constraint worth keeping *reachable*: it is only as good as the
- * schema of the holder handed in, and a holder widened to
- * `AnyConfigurationModel` switches it off entirely — the trap a mixin casting
- * to reach its host walks into. Every such cast names a concrete schema instead
- * (`ConfigModelForFields`, or the base schema when the slot is the base's), and
- * `HostChecksSlotNames` pins each one.
- *
- * A wrong *value* type still throws at runtime (MST type-checks the assignment)
- * rather than at compile time. `value` is deliberately `unknown` because
- * `undefined` is a legitimate write — it resets a slot to its schema default —
- * and the declared slot value type doesn't include it.
+ * A path ending on a slot writes that slot; one ending on a sub-schema replaces
+ * the whole object, so a channel's members (a facet's field and its domain)
+ * move together. On a concrete schema an unknown slot name is a compile error,
+ * and `setSlot` refuses one at runtime (ADR-052). A wrong value type throws at
+ * runtime; `null` or `undefined` resets the slot to its default (ADR-146).
  *
  * @param target - a model with a `configuration` member, or a config node
  * @param slotPath - the slot to write, or the path to one

package/esm/configuration/getConf.js

@@ -1,9 +1,9 @@
-import { getType, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { getSnapshot, getType, isStateTreeNode } from '@jbrowse/mobx-state-tree';
 import { isPlainObject } from '../util/objectUtils.js';
 import { readConfObject } from './readConfObject.js';
 import { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.js';
 import { isConfigurationModel, isConfigurationSchemaType, isConstantEntry, } from './schemaTypes.js';
-import { preProcessSnapshotWith } from './snapshotPreprocess.js';
+import { preProcessSnapshotWith, refusingUndeclaredKeys, } from './snapshotPreprocess.js';
 export function getConf(model, slotPath, args = {}) {
     return readConfObject(model.configuration, slotPath, args);
 }
@@ -14,33 +14,11 @@ export function getConf(model, slotPath, args = {}) {
  * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
  * model, or a config node directly.
  *
- * **The path length says what the write replaces.** A path ending on a slot
- * writes that slot and leaves the object around it alone; a path ending on a
- * sub-schema replaces the whole object, which is how a channel whose members
- * move together — a facet's field and the domain that field's values order —
- * gets written without a stale member surviving underneath.
- *
- * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
- * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
- * unknown slot name is a compile error. `setSlot` itself stays untyped on
- * purpose — the config editor's slot facade routes dynamic slot names through
- * it (`configurationSchema.ts`) — and guards the name at runtime instead
- * (ADR-052), so a misspelled write is diagnosed one way or the other.
- *
- * **The read is the half with no diagnostic at all.** `getConf` for a name the
- * schema doesn't declare returns `undefined` and reports nothing, at any layer,
- * so the slot keeps reading as its default forever. Which makes the
- * compile-time constraint worth keeping *reachable*: it is only as good as the
- * schema of the holder handed in, and a holder widened to
- * `AnyConfigurationModel` switches it off entirely — the trap a mixin casting
- * to reach its host walks into. Every such cast names a concrete schema instead
- * (`ConfigModelForFields`, or the base schema when the slot is the base's), and
- * `HostChecksSlotNames` pins each one.
- *
- * A wrong *value* type still throws at runtime (MST type-checks the assignment)
- * rather than at compile time. `value` is deliberately `unknown` because
- * `undefined` is a legitimate write — it resets a slot to its schema default —
- * and the declared slot value type doesn't include it.
+ * A path ending on a slot writes that slot; one ending on a sub-schema replaces
+ * the whole object, so a channel's members (a facet's field and its domain)
+ * move together. On a concrete schema an unknown slot name is a compile error,
+ * and `setSlot` refuses one at runtime (ADR-052). A wrong value type throws at
+ * runtime; `null` or `undefined` resets the slot to its default (ADR-146).
  *
  * @param target - a model with a `configuration` member, or a config node
  * @param slotPath - the slot to write, or the path to one
@@ -49,13 +27,7 @@ export function getConf(model, slotPath, args = {}) {
 export function setConf(target, slotPath, value) {
     writeConfPath(isConfigurationModel(target) ? target : target.configuration, typeof slotPath === 'string' ? [slotPath] : slotPath, value);
 }
-/**
- * Walk to the node the last segment names a member of, then write that member
- * through whichever of the node's two write actions the member is: a
- * sub-schema, single or a collection, is replaced whole, and a slot goes
- * through `setSlot` so ADR-052's name guard and the value-type guard both run.
- * MST's `applyPatch` takes the same path and runs neither guard.
- */
+// through setSlot or setSubschema, whose guards MST's `applyPatch` would skip
 function writeConfPath(conf, path, value) {
     if (!path.length) {
         throw new Error('setConf needs a slot name or a path to one');
@@ -69,9 +41,7 @@ function writeConfPath(conf, path, value) {
         node = child;
     }
     const leaf = path.at(-1);
-    // Classify off the declaration, never off what the member holds: a
-    // `stringArray` slot holds an array node, and an optional sub-schema nobody
-    // has written yet holds nothing.
+    // off the declaration: a stringArray slot holds an array node too
     const declared = getConfigurationSchemaDefinition(node)?.[leaf];
     if (isConfigurationSchemaType(declared)) {
         // eslint-disable-next-line no-restricted-syntax -- this is setConf
@@ -96,7 +66,14 @@ function writeConfMember(conf, key, value) {
     const member = conf[key];
     const namespace = isPlainObject(value) ? namespaceMetadata(member) : undefined;
     if (namespace) {
-        for (const [k, v] of Object.entries(preProcessSnapshotWith(namespace, value))) {
+        // refused as a whole before any member lands, so a bad member leaves the
+        // namespace as it was rather than half written and reported as rejected
+        const members = refusingUndeclaredKeys(() => {
+            const lifted = preProcessSnapshotWith(namespace, value);
+            getType(member).create({ ...getSnapshot(member), ...lifted });
+            return lifted;
+        });
+        for (const [k, v] of Object.entries(members)) {
             writeConfMember(member, k, v);
         }
     }
@@ -119,7 +96,9 @@ function writeConfMember(conf, key, value) {
 export function applyConfSettings(target, settings) {
     const conf = isConfigurationModel(target) ? target : target.configuration;
     const meta = getConfigurationSchemaMetadata(conf);
-    const values = meta ? preProcessSnapshotWith(meta, settings) : settings;
+    const values = meta
+        ? preProcessSnapshotWith(meta, settings, { routesUndeclared: true })
+        : settings;
     const report = { applied: [], undeclared: {}, failed: [] };
     for (const [key, value] of Object.entries(values)) {
         const declared = Object.hasOwn(meta?.definition ?? {}, key)

package/esm/configuration/index.d.ts

@@ -3,18 +3,19 @@ export type { ConfigurationSchemaDefinition, RetiredSpelling, } from './configur
 export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.ts';
 export type { ConfigurationSchemaUnionType } from './configurationSchemaUnion.ts';
 export type { ConfigSlotDefinition } from './configurationSlot.ts';
-export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, IdentifierSlotDef, PluggableConfigNode, TypeSlotDef, } from './types.ts';
+export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, AnyTrackConfig, ConfigModelForFields, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, IdentifierSlotDef, PluggableConfigNode, TrackConfigEntry, TypeSlotDef, } from './types.ts';
 export { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.ts';
 export type { ConfigurationSchemaUnionMetadata } from './schemaRegistry.ts';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.ts';
+export { partitionAdvanced } from './partitionAdvanced.ts';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.ts';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.ts';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.ts';
-export { readConfObject, readConfigValue } from './readConfObject.ts';
+export { evaluateForFeature, readConfObject, readConfigValue, } from './readConfObject.ts';
 export { applyConfSettings, getConf, setConf } from './getConf.ts';
 export type { ConfSettingsReport } from './getConf.ts';
 export { fillLocations } from './fillLocations.ts';
-export { applyRetiredSpellings, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, } from './snapshotPreprocess.ts';
+export { applyRetiredSpellings, declaredSnapshot, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, refusingUndeclaredKeys, } from './snapshotPreprocess.ts';
 export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.ts';
 export type { ShorthandForm } from './schemaTypes.ts';
 export { requirementProblems } from './requirements.ts';

package/esm/configuration/index.js

@@ -7,13 +7,14 @@ export { getConfigurationSchemaDefinition,
 // way to write the config
 getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.js';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
+export { partitionAdvanced } from './partitionAdvanced.js';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.js';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.js';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.js';
-export { readConfObject, readConfigValue } from './readConfObject.js';
+export { evaluateForFeature, 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 { applyRetiredSpellings, declaredSnapshot, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, refusingUndeclaredKeys, } from './snapshotPreprocess.js';
 export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.js';
 export { requirementProblems } from './requirements.js';
 export { expandTabixShorthand, indexSnapshot, requestedIndexType, tabixIndexSnapshot, } from './tabixShorthand.js';

package/esm/configuration/partitionAdvanced.d.ts

@@ -0,0 +1,12 @@
+import type { AnyConfigurationModel } from './types.ts';
+/**
+ * Splits a config snapshot in two: the slots a schema flags `advanced` or gives
+ * a `contextVariable` (a `jexl:` callback), and everything else. A sub-schema
+ * member splits member by member and appears on a side only if something landed
+ * there. A key the schema does not define as a slot (`trackId`, a typed
+ * schema's `type`, an array of sub-schemas) stays with the rest.
+ */
+export declare function partitionAdvanced(node: AnyConfigurationModel, snapshot: Record<string, unknown>): {
+    rest: Record<string, unknown>;
+    advanced: Record<string, unknown>;
+};

package/esm/configuration/partitionAdvanced.js

@@ -0,0 +1,42 @@
+import { isPlainObject } from '../util/objectUtils.js';
+import { getConfigurationSchemaDefinition } from './schemaRegistry.js';
+import { isConfigurationModel, isSlotDefinitionEntry } from './schemaTypes.js';
+// wider than the config editor's toggle, which reads only `advanced`: a callback
+// is editable there, and only jexl noise to a reader of the About dialog
+function foldsIntoAdvancedCard(def) {
+    return !!def.advanced || !!def.contextVariable?.length;
+}
+/**
+ * Splits a config snapshot in two: the slots a schema flags `advanced` or gives
+ * a `contextVariable` (a `jexl:` callback), and everything else. A sub-schema
+ * member splits member by member and appears on a side only if something landed
+ * there. A key the schema does not define as a slot (`trackId`, a typed
+ * schema's `type`, an array of sub-schemas) stays with the rest.
+ */
+export function partitionAdvanced(node, snapshot) {
+    const definition = getConfigurationSchemaDefinition(node);
+    const rest = {};
+    const advanced = {};
+    for (const [key, value] of Object.entries(snapshot)) {
+        const def = definition?.[key];
+        if (isSlotDefinitionEntry(def)) {
+            const side = foldsIntoAdvancedCard(def) ? advanced : rest;
+            side[key] = value;
+            continue;
+        }
+        const child = node[key];
+        if (isPlainObject(value) && isConfigurationModel(child)) {
+            const split = partitionAdvanced(child, value);
+            if (Object.keys(split.rest).length) {
+                rest[key] = split.rest;
+            }
+            if (Object.keys(split.advanced).length) {
+                advanced[key] = split.advanced;
+            }
+        }
+        else {
+            rest[key] = value;
+        }
+    }
+    return { rest, advanced };
+}

package/esm/configuration/plot.d.ts

@@ -59,3 +59,9 @@ export declare function liftPlot(conf: AnyConfigurationModel, draft: Plot): AnyC
  * Throws a refusal before anything is written.
  */
 export declare function plotWrites(conf: AnyConfigurationModel, draft: Plot): Record<string, unknown>;
+/**
+ * What a lifted plot's color objects and `scales.y` say together that the
+ * display cannot draw as written, as corner-notice lines: each color object
+ * under its schema's `fieldPresets`, as `jbrowse validate` judges it.
+ */
+export declare function schemaPlotProblems(lifted: AnyConfigurationModel): string[];