@jbrowse/core 5.0.0-beta.10 → 5.0.0-beta.13

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 `outlineColor`
 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 colour 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 colour
     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.`);
     }
@@ -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/formatDetailsConfigSchema.js

@@ -72,6 +72,7 @@ export function FormatDetailsConfigSchemaFactory() {
         depth: {
             type: 'maybeNumber',
             description: 'levels of subfeature the formatDetails.subfeatures callback runs on, default 2',
+            advanced: true,
         },
         /**
          * #slot formatDetails.maxDepth
@@ -82,6 +83,7 @@ export function FormatDetailsConfigSchemaFactory() {
         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

@@ -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

package/esm/configuration/index.d.ts

@@ -3,14 +3,15 @@ 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';
@@ -30,3 +31,5 @@ export { toCallbackValue, toFixedValue } from './configurationSlot.ts';
 export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, slotChoices, slotValueRefusal, } from './slotFacade.ts';
 export type { SlotFacade } from './slotFacade.ts';
 export { fullConfSnapshot } from './fullConfSnapshot.ts';
+export { PLOT_VOCABULARY, liftPlot, parsePlot, plotKeysOf, plotOf, plotWrites, } from './plot.ts';
+export type { Plot, PlotExample } from './plot.ts';

package/esm/configuration/index.js

@@ -7,10 +7,11 @@ 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';
@@ -25,3 +26,4 @@ export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 export { toCallbackValue, toFixedValue } from './configurationSlot.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/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

@@ -0,0 +1,67 @@
+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>;
+/**
+ * What a lifted plot's colour objects and `scales.y` say together that the
+ * display cannot draw as written, as corner-notice lines: each colour object
+ * under its schema's `fieldPresets`, as `jbrowse validate` judges it.
+ */
+export declare function schemaPlotProblems(lifted: AnyConfigurationModel): string[];