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

package/esm/configuration/plot.js

@@ -1,7 +1,10 @@
 import { getSnapshot, getType, isArrayType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import { compareStructural } from 'mobx';
+import { colorProblems, colorSlotsOf, noticeLines, scaleEndProblems, scaleEndsOf, withImpliedField, } from '../util/colorScale.js';
+import { readConfObject } from './readConfObject.js';
 import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { bareFormOf, shorthandTargets } from './schemaTypes.js';
+import { refusingUndeclaredKeys } from './snapshotPreprocess.js';
 /**
  * #api core/configuration
  * The grammar's settings, by the slot name every display that has one gives
@@ -9,20 +12,30 @@ import { bareFormOf, shorthandTargets } from './schemaTypes.js';
  * display's `plot`. A display's plot is the ones its config declares
  * (`plotKeysOf`).
  */
+// The multi-row display's `rowGroups` is not here yet; it joins when "Edit
+// plot..." should show the row grouping.
 export const PLOT_VOCABULARY = {
     marks: 'the marks drawn in order, each a mark and an encoding',
+    mark: 'the shape each value is drawn as: a bar, a point, a line or a span',
+    interpolate: 'the path a line takes between values: held across each bin, or centre to centre',
+    aggregate: 'the stored zoom-bin summary drawn: mean, min or max',
+    extent: "the span drawn around each bin's aggregate: its min to max, or none",
     transform: 'the steps run over the features before any mark',
+    unit: 'the unit one row draws: a read or a chain, a sample or a haplotype',
     facet: 'one section per value of a field',
+    sort: 'the order the rows stack in: one over the whole window, or by a column at one base',
     rows: 'the rows: their field or order, labels, focus and tree',
-    rowColor: 'the colour of each row label',
-    color: 'the colour',
+    rowColor: 'the color of each row, by a row attribute',
+    color: 'the color',
     baseColor: 'the per-base layer over the reads',
-    arcColor: 'the colour of the arcs between mates',
-    ribbonColor: 'the colour of the ribbons between lanes',
+    arcColor: 'the color of the arcs between mates',
+    ribbonColor: 'the color of the ribbons between lanes',
     laneLayers: 'the layers drawn over each lane',
     scales: 'the axes, scales.y the value axis',
-    filter: 'the jexl: expressions a feature has to pass',
-    filterBy: 'the read flags and tags a read has to pass',
+    y: 'the field plotted on the value axis',
+    size: "a point's diameter or a line's width, in px",
+    origin: 'the value bars grow from',
+    filter: 'the tests a feature has to pass: jexl: expressions, or on an alignments display the read flags, name, tags and categories',
 };
 const LIFT_ID = 'plotLift';
 /**
@@ -116,10 +129,10 @@ function merged(draft, current) {
  */
 export function liftPlot(conf, draft) {
     checkKeys(draft, plotKeysOf(conf));
-    return getType(conf).create({
+    return refusingUndeclaredKeys(() => getType(conf).create({
         displayId: LIFT_ID,
         ...structuredClone(merged(draft, plotOf(conf))),
-    });
+    }));
 }
 /**
  * #api core/configuration
@@ -136,7 +149,41 @@ export function plotWrites(conf, draft) {
         if (value === undefined || compareStructural(lifted[key], current[key])) {
             continue;
         }
-        writes[key] = lifted[key] ?? null;
+        writes[key] = value === null ? null : (lifted[key] ?? null);
     }
     return writes;
 }
+function subConfOf(conf, key) {
+    const member = conf[key];
+    return isStateTreeNode(member) ? member : undefined;
+}
+// `value` raw, as `colorSettingOf` reads it: a `jexl:` constant is a constant
+// to judge, never a callback to evaluate here.
+function membersOf(node) {
+    return (name) => name === 'value'
+        ? node.value
+        : readConfObject(node, name);
+}
+/**
+ * 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 function schemaPlotProblems(lifted) {
+    return plotKeysOf(lifted).flatMap(key => {
+        const node = subConfOf(lifted, key);
+        const options = node
+            ? getConfigurationSchemaMetadata(node)?.options
+            : undefined;
+        const presets = options?.fieldPresets;
+        const y = key === 'scales' && node ? subConfOf(node, 'y') : undefined;
+        return [
+            ...(node && presets
+                ? noticeLines(key, colorProblems(withImpliedField(colorSlotsOf(membersOf(node)), options.impliedField), presets))
+                : []),
+            ...(y
+                ? noticeLines('scales.y', scaleEndProblems(scaleEndsOf(membersOf(y))))
+                : []),
+        ];
+    });
+}

package/esm/configuration/readConfObject.d.ts

@@ -3,20 +3,13 @@ import type { JexlInstance } from '../util/jexlStrings.ts';
 import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
- * Given a configuration model (an instance of a ConfigurationSchema), read the
- * configuration value at the given path. Use this when you hold the
- * configuration model directly, e.g. an entry from `session.tracks`.
+ * Read the value at a path of a live config node, such as a track's
+ * `configuration`, evaluating a `jexl:` callback with `args`.
  *
- * Wants a **live config node**, not a snapshot of one, and passing a snapshot is
- * a type error. Slots are built with `types.stripDefault`, so a slot sitting at
- * its default is absent from a snapshot — "unset" and "at its default" are
- * indistinguishable there, and a read off one reports a default as missing.
- *
- * That is enforced in the types only, deliberately: it can't be a runtime check.
- * `generateHierarchy` reads slots straight off the **un-hydrated frozen** entries
- * of `jbrowse.tracks` on purpose, because hydrating every track to answer the
- * track selector is what `types.frozen` exists to avoid — and those reads are
- * indistinguishable at runtime from the broken spelling.
+ * A snapshot is refused by the types, since a slot at its default is absent
+ * from one. A `session.tracks` entry is one (`TrackConfigEntry`): read its
+ * `trackId` and `type` directly, and a slot through a helper that supplies the
+ * default, such as `getConfAssemblyNamesOrNone`.
  *
  * @param model - instance of ConfigurationSchema
  * @param slotPaths - array of paths to read
@@ -26,9 +19,14 @@ import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSche
 export declare function readConfObject(confObject: AnyConfigurationModel): AnyConfigurationSnapshot;
 export declare function readConfObject<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
 /**
- * Read a value from a plain config snapshot object. Automatically evaluates
- * "jexl:..." strings per-feature. Works without MST — intended for use in
- * rendering code (GPU, Canvas2D, workers). Pass the realm's `pluginManager.jexl`
- * so plugin-registered functions (e.g. in a custom `mouseover` slot) resolve.
+ * Read a value from a plain config snapshot, evaluating a `jexl:` callback
+ * against `feature`. For rendering code and workers; pass the realm's
+ * `pluginManager.jexl` so plugin-registered functions resolve.
  */
 export declare function readConfigValue<T>(config: Record<string, unknown>, key: string | string[], feature: Feature, jexl: JexlInstance): T;
+/**
+ * #api core/configuration
+ * A config value as `feature` reads it: a `jexl:` callback evaluated against
+ * the feature, anything else as written.
+ */
+export declare function evaluateForFeature(value: unknown, feature: Feature, jexl: JexlInstance): unknown;

package/esm/configuration/readConfObject.js

@@ -1,27 +1,14 @@
 /**
  * @module
- * 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.
+ * The config readers: `readConfObject` off a live config node, whose env
+ * supplies the jexl instance, and `readConfigValue` off a plain snapshot in a
+ * worker or renderer, which is handed one.
  */
 import { getEnv, getSnapshot, getType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
-// Evaluate a slot's `jexl:...` callback string against the realm's single jexl
-// instance (carrying plugin-registered functions), read from the config node's
-// env. readConfObject only ever operates on live MST configs — nested sub-config
-// reads stay MST (env resolves to the root), and frozen track configs hydrate to
-// MST before any callback is read — so the env instance is always present here.
 function evalConfigCallback(expr, args, confObject) {
     if (!isStateTreeNode(confObject)) {
-        // A jexl slot needs the realm's jexl instance, which is read from a live
-        // config node's env. A plain config snapshot (e.g. an un-hydrated
-        // session.tracks entry) carries no env — read it through a hydrated model,
-        // or use readConfigValue(config, key, feature, jexl) which takes jexl
-        // explicitly.
         throw new Error(`cannot evaluate jexl config callback ${JSON.stringify(expr)}: config is a plain snapshot, not a live model (no env to resolve the jexl instance)`);
     }
     const jexl = getEnv(confObject)
@@ -35,11 +22,7 @@ function isFeatureField(confObject, slotName) {
     return (isStateTreeNode(confObject) &&
         !!getConfigurationSchemaMetadata(getType(confObject))?.featureFields.has(slotName));
 }
-// Read and resolve a single slot: raw value, jexl callback evaluation, then a
-// referentially-stable snapshot for sub-config nodes.
 function readSlot(confObject, slotName, args) {
-    // strict undefined check, not truthiness — a slot value can legitimately be
-    // falsy (0, '', false, null)
     const value = confObject[slotName];
     if (value === undefined) {
         return undefined;
@@ -47,42 +30,25 @@ function readSlot(confObject, slotName, args) {
     const val = isCallbackValue(value) && !isFeatureField(confObject, slotName)
         ? evalConfigCallback(value, args, confObject)
         : value;
-    // Fast path for primitives (most common case)
     if (val === null || typeof val !== 'object') {
         return val;
     }
-    // Return the live, referentially-stable snapshot (frozen in dev) rather than
-    // a per-read clone: stable identity lets downstream computeds memoize, and
-    // the old structuredClone was both a hot-path allocation and a source of
-    // spurious recomputation. Treat as read-only.
+    // the live snapshot, stable across reads so downstream computeds memoize;
+    // read-only
     return isStateTreeNode(val) ? getSnapshot(val) : val;
 }
-// loose implementation signature: the body returns values that are `any` by
-// nature (raw slot values, snapshots); the typed overloads above are what
-// callers see. No looser overload admits the model: one that did was a
-// catch-all a slot-name typo fell through to, compiling clean as `any`.
+// No looser overload admits the model: a catch-all lets a slot-name typo
+// compile as `any`.
 export function readConfObject(confObject, slotPath, args = {}) {
-    // the single-slot read, first and allocation-free: it is the shape of nearly
-    // every one of the ~1300 call sites, so it doesn't get normalized into a
-    // one-element array on the way past
     if (typeof slotPath === 'string') {
         return readSlot(confObject, slotPath, args);
     }
     if (slotPath !== undefined && !Array.isArray(slotPath)) {
         throw new TypeError('slotPath must be a string or array');
     }
-    // No path, or an empty one — which means the same thing, and used not to: `[]`
-    // is truthy, so it reached the walk below and read `confObject[undefined]`.
-    //
-    // Returns the whole config as a plain object: the live, referentially-stable
-    // snapshot (frozen in dev), not a fresh clone — treat as read-only.
     if (!slotPath?.length) {
         return isStateTreeNode(confObject) ? getSnapshot(confObject) : confObject;
     }
-    // every segment but the last names a sub-config, and only the last is a slot
-    // read — which is where jexl evaluation and snapshotting happen, and nowhere
-    // else. Iterative rather than a self-call per segment, which re-entered the
-    // whole argument-shape preamble above at each level.
     let conf = confObject;
     for (let i = 0; i < slotPath.length - 1; i++) {
         const subConf = conf[slotPath[i]];
@@ -93,9 +59,6 @@ export function readConfObject(confObject, slotPath, args = {}) {
     }
     return readSlot(conf, slotPath[slotPath.length - 1], args);
 }
-// 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;
@@ -107,12 +70,18 @@ function resolveConfigValue(config, key) {
     return config[key];
 }
 /**
- * Read a value from a plain config snapshot object. Automatically evaluates
- * "jexl:..." strings per-feature. Works without MST — intended for use in
- * rendering code (GPU, Canvas2D, workers). Pass the realm's `pluginManager.jexl`
- * so plugin-registered functions (e.g. in a custom `mouseover` slot) resolve.
+ * Read a value from a plain config snapshot, evaluating a `jexl:` callback
+ * against `feature`. For rendering code and workers; pass the realm's
+ * `pluginManager.jexl` so plugin-registered functions resolve.
  */
 export function readConfigValue(config, key, feature, jexl) {
-    const raw = resolveConfigValue(config, key);
-    return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
+    return evaluateForFeature(resolveConfigValue(config, key), feature, jexl);
+}
+/**
+ * #api core/configuration
+ * A config value as `feature` reads it: a `jexl:` callback evaluated against
+ * the feature, anything else as written.
+ */
+export function evaluateForFeature(value, feature, jexl) {
+    return isCallbackValue(value) ? evaluateJexl(value, { feature }, jexl) : value;
 }

package/esm/configuration/schemaRegistry.d.ts

@@ -11,8 +11,6 @@ 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 */

package/esm/configuration/schemaTypes.js

@@ -67,7 +67,11 @@ export function isSlotDefinitionEntry(def) {
 export function isConfigurationModel(thing) {
     return isStateTreeNode(thing) && isConfigurationSchemaType(getType(thing));
 }
-const NUMBER_SLOT_TYPES = new Set(['number', 'integer', 'maybeNumber']);
+const NUMBER_SLOT_TYPES = new Set([
+    'number',
+    'integer',
+    'maybeNumber',
+]);
 /**
  * The slot a bare value of each form lifts into, off a `shorthand` option:
  * each slot it names takes the form its own type holds, a number where it

package/esm/configuration/slotFacade.js

@@ -5,7 +5,7 @@ import { slotWriteRefusal } from './configurationSlot.js';
 import { setConf } from './getConf.js';
 import { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.js';
 import { isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
-import { preProcessSnapshotWith } from './snapshotPreprocess.js';
+import { preProcessSnapshotWith, refusingUndeclaredKeys, } 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.
@@ -42,7 +42,7 @@ export function slotValueRefusal(schema, key, value) {
     try {
         const lifted = preProcessSnapshotWith(meta, { [key]: value })[key];
         if (subSchema) {
-            subSchema.create(lifted);
+            refusingUndeclaredKeys(() => subSchema.create(lifted));
         }
         else if (isSlotDefinitionEntry(entry) && !slotType?.is(lifted)) {
             return slotWriteRefusal(`${meta.name}.${key}`, entry.type, value);

package/esm/configuration/snapshotPreprocess.d.ts

@@ -2,42 +2,66 @@ import type { RetiredSpelling } from './configurationSchema.ts';
 import type { ConfigurationSchemaMetadata } from './schemaRegistry.ts';
 import type { IAnyType } from '@jbrowse/mobx-state-tree';
 export declare function listed(keys: readonly string[]): string;
+/**
+ * #api core/configuration
+ * Runs `write` as a write: a `closed` schema created inside it refuses a key
+ * it does not declare, at any depth, where a config loading only names the
+ * key on the console. `setConf`, a settings bag and a plot draft write this
+ * way, so a typo in an edit is an error and a config written for another
+ * version still draws.
+ */
+export declare function refusingUndeclaredKeys<T>(write: () => T): T;
 /**
  * The snapshot with each spelling `retired` names rewritten: a lift's members
  * take the old key's place, and what the snapshot already spells wins, member
  * by member inside an object, since writing the current name is the stronger
  * statement — so a retired flag lifting into `scales.y` lands beside a
  * `scales.y` the snapshot writes. The old key goes whether or not it carried a
- * value, so a `closed` schema never meets it. Where two retired names lift
- * onto one member — a slot the entry spelt directly and the same slot inside a
- * retired `renderer` — the one declared first wins.
+ * value, so a `closed` schema never meets it, and a member a lift produces
+ * that no slot takes goes with it: a v4 `renderer` block carried settings
+ * the display has no slot for, and they were dropped then too. Where two
+ * retired names lift onto one member — a slot the entry spelt directly and
+ * the same slot inside a retired `renderer` — the one declared first wins.
+ * A retired name the schema itself declares is that slot, not a spelling,
+ * so a list shared across displays leaves it alone where one still takes it.
  */
 export declare function liftRetiredSpellings(schema: ConfigurationSchemaMetadata, snapshot: Record<string, unknown>): Record<string, unknown>;
 /**
- * `liftRetiredSpellings` over a map directly, for a schema whose own
- * `preProcessSnapshot` uncovers a retired name the pass above could not see —
- * one that arrives out of a legacy sub-config rather than off the entry.
+ * `liftRetiredSpellings` over a map directly, for a lift that uncovers a
+ * retired name one level down, as a v4 `renderer` block carries a `color1`.
  * Applying the same map twice costs nothing, since a lift deletes the name it
- * reads.
+ * reads. `takes` says which lifted members land; every one does unless given.
  */
-export declare function applyRetiredSpellings(retired: Record<string, RetiredSpelling>, snapshot: Record<string, unknown>): Record<string, unknown>;
+export declare function applyRetiredSpellings(retired: Record<string, RetiredSpelling>, snapshot: Record<string, unknown>, takes?: (name: string) => boolean): Record<string, unknown>;
 /**
  * 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 `shorthand` slot taking its form, 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 `retired` spelling becomes the members that replaced 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.
+ * `null` member reads as unset; a `retired` spelling becomes the members that
+ * replaced it; the schema's own `preProcessSnapshot` runs, which is where a
+ * track folds `displayDefaults` into its displays; then a `closed` schema
+ * names a key it does not declare on the console, or refuses it inside
+ * `refusingUndeclaredKeys`, unless the caller is a settings bag that routes
+ * an undeclared key itself (`routesUndeclared`); it refuses a bare value no
+ * shorthand lifted on every door, and so is a `jexl:` callback in a slot
+ * declaring no `contextVariable`.
+ */
+export declare function preProcessSnapshotWith(schema: ConfigurationSchemaMetadata, snapshot: unknown, { routesUndeclared }?: {
+    routesUndeclared?: boolean | undefined;
+}): Record<string, unknown>;
+/**
+ * #api core/configuration
+ * A snapshot as `type` lifts it, without the keys it does not declare: the
+ * config half of an entry that carries its owner's keys beside one, as a
+ * `MultiWiggleAdapter` subadapter carries its row's `name` and `color`.
  */
-export declare function preProcessSnapshotWith(schema: ConfigurationSchemaMetadata, snapshot: unknown): Record<string, unknown>;
+export declare function declaredSnapshot(type: IAnyType, snapshot: Record<string, 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.
+ * A snapshot as a write to `type` admits it: the lift and checks `setConf`
+ * applies, so a dialog or a validator refuses what an edit cannot hold, an
+ * undeclared key included. Throws what the schema's `preProcessSnapshot`
+ * throws.
  */
 export declare function preProcessConfigSnapshot(type: IAnyType, snapshot: unknown): Record<string, unknown>;

package/esm/configuration/snapshotPreprocess.js

@@ -1,4 +1,5 @@
 import { isJexl } from '../util/jexlStrings.js';
+import { isPlainObject } from '../util/objectUtils.js';
 import { slotWriteRefusal } from './configurationSlot.js';
 import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { bareFormOf, isConstantEntry, shorthandTargets } from './schemaTypes.js';
@@ -10,18 +11,51 @@ export function listed(keys) {
         ? `${keys.slice(0, -1).join(', ')} and ${keys.at(-1)}`
         : (keys[0] ?? 'nothing');
 }
-function refuseUndeclaredKeys({ name, definition, options }, snapshot) {
+function declaredKeys({ definition, options }) {
     const id = options.explicitIdentifier;
-    const declared = [
+    return [
         ...Object.keys(definition).filter(key => !isConstantEntry(definition[key])),
         ...(options.explicitlyTyped ? ['type'] : []),
         ...(id ? [id] : []),
     ];
-    const unknown = typeof snapshot === 'string'
+}
+const warned = new Set();
+let writes = 0;
+/**
+ * #api core/configuration
+ * Runs `write` as a write: a `closed` schema created inside it refuses a key
+ * it does not declare, at any depth, where a config loading only names the
+ * key on the console. `setConf`, a settings bag and a plot draft write this
+ * way, so a typo in an edit is an error and a config written for another
+ * version still draws.
+ */
+export function refusingUndeclaredKeys(write) {
+    writes++;
+    try {
+        return write();
+    }
+    finally {
+        writes--;
+    }
+}
+function checkUndeclaredKeys(schema, snapshot) {
+    const { name, options } = schema;
+    const declared = declaredKeys(schema);
+    const bare = snapshot !== undefined &&
+        (typeof snapshot !== 'object' || Array.isArray(snapshot));
+    const unknown = bare
         ? [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(', ')}`);
+        if (bare || writes > 0) {
+            throw new Error(`${name} takes ${listed(declared)}, not ${unknown.join(', ')}`);
+        }
+        const key = `${name} ${unknown.toSorted().join(' ')}`;
+        if (!warned.has(key)) {
+            warned.add(key);
+            const id = snapshot[options.explicitIdentifier ?? ''];
+            console.warn(`${name}${typeof id === 'string' ? ` "${id}"` : ''} does not declare ${listed(unknown)}: loading without it`);
+        }
     }
 }
 // Checked here as well as by each slot's MST type because this runs on every
@@ -38,11 +72,13 @@ function refuseCallbacks({ name, takesNoCallback }, snapshot) {
     }
 }
 // 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) {
+// settings bag still resets it, and `create` reads `undefined` as the default.
+// A frozen slot resets too, since its readers take the default's shape and
+// `setSlot` already resets it; storing the null put one past them.
+function nullMembersAsUnset(snapshot) {
     let out = snapshot;
     for (const key in snapshot) {
-        if (snapshot[key] === null && !storesNull.has(key)) {
+        if (snapshot[key] === null) {
             out = out === snapshot ? { ...snapshot } : out;
             out[key] = undefined;
         }
@@ -60,9 +96,6 @@ function isOwnSnapshot({ name, options }, snapshot) {
         snapshot.type === undefined ||
         snapshot.type === name);
 }
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 // `lifted` under `written`: what the snapshot spells wins, member by member
 // where both are objects.
 function underWritten(written, lifted) {
@@ -84,24 +117,30 @@ function underWritten(written, lifted) {
  * by member inside an object, since writing the current name is the stronger
  * statement — so a retired flag lifting into `scales.y` lands beside a
  * `scales.y` the snapshot writes. The old key goes whether or not it carried a
- * value, so a `closed` schema never meets it. Where two retired names lift
- * onto one member — a slot the entry spelt directly and the same slot inside a
- * retired `renderer` — the one declared first wins.
+ * value, so a `closed` schema never meets it, and a member a lift produces
+ * that no slot takes goes with it: a v4 `renderer` block carried settings
+ * the display has no slot for, and they were dropped then too. Where two
+ * retired names lift onto one member — a slot the entry spelt directly and
+ * the same slot inside a retired `renderer` — the one declared first wins.
+ * A retired name the schema itself declares is that slot, not a spelling,
+ * so a list shared across displays leaves it alone where one still takes it.
  */
 export function liftRetiredSpellings(schema, snapshot) {
     const { retired } = schema.options;
-    return retired && isOwnSnapshot(schema, snapshot)
-        ? applyRetiredSpellings(retired, snapshot)
-        : snapshot;
+    if (!retired || !isOwnSnapshot(schema, snapshot)) {
+        return snapshot;
+    }
+    const declared = new Set(declaredKeys(schema));
+    const spellings = Object.fromEntries(Object.entries(retired).filter(([name]) => !declared.has(name)));
+    return applyRetiredSpellings(spellings, snapshot, name => declared.has(name));
 }
 /**
- * `liftRetiredSpellings` over a map directly, for a schema whose own
- * `preProcessSnapshot` uncovers a retired name the pass above could not see —
- * one that arrives out of a legacy sub-config rather than off the entry.
+ * `liftRetiredSpellings` over a map directly, for a lift that uncovers a
+ * retired name one level down, as a v4 `renderer` block carries a `color1`.
  * Applying the same map twice costs nothing, since a lift deletes the name it
- * reads.
+ * reads. `takes` says which lifted members land; every one does unless given.
  */
-export function applyRetiredSpellings(retired, snapshot) {
+export function applyRetiredSpellings(retired, snapshot, takes = () => true) {
     const present = Object.keys(retired).filter(key => key in snapshot);
     if (present.length === 0) {
         return snapshot;
@@ -113,7 +152,9 @@ export function applyRetiredSpellings(retired, snapshot) {
     for (const key of present.filter(key => snapshot[key] !== undefined)) {
         const lifted = retired[key](snapshot[key]);
         for (const [name, value] of Object.entries(lifted)) {
-            out[name] = underWritten(out[name], value);
+            if (takes(name)) {
+                out[name] = underWritten(out[name], value);
+            }
         }
     }
     return out;
@@ -123,14 +164,16 @@ export function applyRetiredSpellings(retired, snapshot) {
  * arrives by (`create`, `applySnapshot`, `setSubschema`, a settings bag): a
  * bare string or number lifts into the `shorthand` slot taking its form, 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 `retired` spelling becomes the members that replaced 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.
+ * `null` member reads as unset; a `retired` spelling becomes the members that
+ * replaced it; the schema's own `preProcessSnapshot` runs, which is where a
+ * track folds `displayDefaults` into its displays; then a `closed` schema
+ * names a key it does not declare on the console, or refuses it inside
+ * `refusingUndeclaredKeys`, unless the caller is a settings bag that routes
+ * an undeclared key itself (`routesUndeclared`); it refuses a bare value no
+ * shorthand lifted on every door, and so is a `jexl:` callback in a slot
+ * declaring no `contextVariable`.
  */
-export function preProcessSnapshotWith(schema, snapshot) {
+export function preProcessSnapshotWith(schema, snapshot, { routesUndeclared = false } = {}) {
     const { shorthandWith, closed, preProcessSnapshot } = schema.options;
     const form = bareFormOf(snapshot);
     const target = form && shorthandTargets(schema)[form];
@@ -138,24 +181,39 @@ export function preProcessSnapshotWith(schema, snapshot) {
         ? {}
         : target !== undefined
             ? { ...shorthandWith, [target]: snapshot }
-            : nullMembersAsUnset(snapshot, schema.storesNull);
+            : nullMembersAsUnset(snapshot);
     const named = liftRetiredSpellings(schema, lifted);
-    if (closed) {
-        refuseUndeclaredKeys(schema, named);
-    }
     const processed = preProcessSnapshot ? preProcessSnapshot(named) : named;
+    if (closed && !routesUndeclared && isOwnSnapshot(schema, processed)) {
+        checkUndeclaredKeys(schema, processed);
+    }
     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.
+ * A snapshot as `type` lifts it, without the keys it does not declare: the
+ * config half of an entry that carries its owner's keys beside one, as a
+ * `MultiWiggleAdapter` subadapter carries its row's `name` and `color`.
+ */
+export function declaredSnapshot(type, snapshot) {
+    const schema = getConfigurationSchemaMetadata(type);
+    if (!schema) {
+        return snapshot;
+    }
+    const declared = new Set(declaredKeys(schema));
+    return Object.fromEntries(Object.entries(preProcessSnapshotWith(schema, snapshot, { routesUndeclared: true })).filter(([key]) => declared.has(key)));
+}
+/**
+ * #api core/configuration
+ * A snapshot as a write to `type` admits it: the lift and checks `setConf`
+ * applies, so a dialog or a validator refuses what an edit cannot hold, an
+ * undeclared key included. Throws what the schema's `preProcessSnapshot`
+ * throws.
  */
 export function preProcessConfigSnapshot(type, snapshot) {
     const schema = getConfigurationSchemaMetadata(type);
     return schema
-        ? preProcessSnapshotWith(schema, snapshot)
+        ? refusingUndeclaredKeys(() => preProcessSnapshotWith(schema, snapshot))
         : snapshot;
 }

package/esm/configuration/tabixShorthand.js

@@ -63,9 +63,7 @@ export function tabixIndexSnapshot(snap) {
 export function expandTabixShorthand(snap, locationKey) {
     return snap.uri
         ? {
-            ...fillLocations(snap, {
-                [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
-            }),
+            ...fillLocations(snap, { [locationKey]: { uri: snap.uri, baseUri: snap.baseUri } }, ['csi']),
             index: tabixIndexSnapshot(snap),
         }
         : snap;