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

package/esm/configuration/configurationSlot.d.ts

@@ -5,6 +5,14 @@ declare const slotTypes: {
         model: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
         fallbackDefault: never[];
     };
+    expressionArray: {
+        model: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        fallbackDefault: never[];
+    };
+    colorArray: {
+        model: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        fallbackDefault: never[];
+    };
     stringArrayMap: {
         model: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>>;
         fallbackDefault: {};
@@ -13,6 +21,10 @@ declare const slotTypes: {
         model: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ISimpleType<number>>;
         fallbackDefault: {};
     };
+    stringMap: {
+        model: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        fallbackDefault: {};
+    };
     boolean: {
         model: import("@jbrowse/mobx-state-tree").ISimpleType<boolean>;
         fallbackDefault: boolean;
@@ -41,6 +53,9 @@ declare const slotTypes: {
     maybeFrozen: {
         model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IType<any, any, any>>;
     };
+    maybeString: {
+        model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    };
     string: {
         model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         fallbackDefault: string;
@@ -49,6 +64,10 @@ declare const slotTypes: {
         model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         fallbackDefault: string;
     };
+    featureField: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        fallbackDefault: string;
+    };
     fileLocation: {
         model: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<{
             locationType: "LocalPathLocation";
@@ -135,6 +154,108 @@ declare const slotTypes: {
             locationType: string;
         };
     };
+    maybeFileLocation: {
+        model: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "LocalPathLocation";
+            localPath: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "BlobLocation";
+            name: string;
+            blobId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "FileHandleLocation";
+            name: string;
+            handleId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "UriLocation";
+            uri: string;
+            baseUri: string | undefined;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+                internetAccountType: string;
+                authInfo: any;
+            }> | undefined;
+        }>, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
+            localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | {
+            locationType: "UriLocation";
+            uri: string;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+                internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+                authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
+            }> | undefined;
+        }, import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
+            localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"UriLocation">;
+            uri: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            baseUri: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            internetAccountId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IModelType<{
+                internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+                authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
+            }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+        }>>, import("../util/types/mst.ts").LegacyFileLocation | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "LocalPathLocation";
+            localPath: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "BlobLocation";
+            name: string;
+            blobId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "FileHandleLocation";
+            name: string;
+            handleId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "UriLocation";
+            uri: string;
+            baseUri: string | undefined;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+                internetAccountType: string;
+                authInfo: any;
+            }> | undefined;
+        }>, import("@jbrowse/mobx-state-tree")._NotCustomized>>, import("../util/types/mst.ts").LegacyFileLocation | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "LocalPathLocation";
+            localPath: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "BlobLocation";
+            name: string;
+            blobId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "FileHandleLocation";
+            name: string;
+            handleId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "UriLocation";
+            uri: string;
+            baseUri: string | undefined;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+                internetAccountType: string;
+                authInfo: any;
+            }> | undefined;
+        }> | undefined, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+    };
     frozen: {
         model: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
         fallbackDefault: {};
@@ -146,10 +267,10 @@ declare const slotTypes: {
  * `types.ts`, which has to name the same set and is checked against this.
  */
 export type BuiltinSlotTypeName = keyof typeof slotTypes;
-declare const ENUM_SLOT_TYPES: readonly ['stringEnum', 'maybeStringEnum'];
+declare const ENUM_SLOT_TYPES: readonly ['stringEnum', 'maybeStringEnum', 'stringEnumArray'];
 /**
  * Every legal `type` on a slot definition: the builtin table's own names, plus
- * the two enum types.
+ * the enum types.
  *
  * Closed on purpose. A name outside this set still *works* at runtime as long
  * as a `model` is given — which is exactly the trap: the value round-trips
@@ -167,65 +288,23 @@ type MaybeBuiltinSlotTypeName = {
     [K in keyof typeof slotTypes]: 'fallbackDefault' extends keyof (typeof slotTypes)[K] ? never : K;
 }[keyof typeof slotTypes];
 export type MaybeSlotTypeName = MaybeBuiltinSlotTypeName | 'maybeStringEnum';
+/** Why the slot `name`, of type `type`, refuses `value` on a write. */
+export declare function slotWriteRefusal(name: string, type: string, value: unknown): string;
 interface ConfigSlotDefinitionCommon {
     /** human-readable description of the slot's meaning */
     description?: string;
     /** custom base MST model for the slot's value */
     model?: IAnyType;
-    /** parameter names of the function callback */
+    /**
+     * The names a `jexl:` callback in this slot reads. Declaring any is what
+     * makes the slot take a callback; every other slot refuses one.
+     */
     contextVariable?: string[];
     /**
      * hide this slot behind a "Show advanced settings" toggle in the config
      * editor, so common slots aren't crowded out by rarely-changed ones
      */
     advanced?: boolean;
-    /**
-     * **Declaring this makes the slot promotable**, and it is the only thing that
-     * does: a user can promote the slot's value to a session-wide default for all
-     * tracks of the same display type (the track-menu pin). An *unset* slot
-     * follows (inherits) that promoted default; any concrete value customizes the
-     * track. Read it with `resolveConf`, never `getConf`; see
-     * `promotableResolve.ts`.
-     *
-     * The value itself is what the unset state resolves to when a track inherits
-     * and nothing is promoted. This is the CSS model — being unset is the
-     * `inherit` keyword and `promotedBase` is `initial` (the value at the bottom
-     * of the cascade). Spending only `undefined` on the sentinel is what leaves
-     * every *real* value — `promotedBase` included — customizable over an opposite
-     * session default, so a track can hold `displayMode: 'normal'` under a
-     * promoted `'compact'`.
-     *
-     * Requires a `maybe*` slot type (whose `undefined` is the inherit sentinel)
-     * and no `defaultValue`; `ConfigSlot` throws otherwise, and both stay runtime
-     * checks. Forbidding it on the plain half of `ConfigSlotDefinition` was tried:
-     * it forces a cast into `mergeSchemaDefinition`, whose spread of two slot
-     * definitions lands in neither member, and buys only an earlier version of a
-     * throw that already fires when the schema is built.
-     *
-     * A subclass turns an inherited promotable slot back into a plain one by
-     * stating `promotedBase: undefined` — the definition merge is a spread, so a
-     * stated `undefined` really does overwrite the base's value.
-     */
-    promotedBase?: unknown;
-    /**
-     * For a promotable slot: an extra semantic check a stored value must pass,
-     * on top of the built-in type-shape check, before the cascade
-     * (`promotableResolve.ts`'s `isUsableValue`) treats it as usable. Applies to
-     * both cascade tiers — a session-wide promoted default and a track's own saved
-     * value. Needed when a slot's shape alone can't catch a semantically-invalid
-     * value — e.g. alignments `colorBy`'s `.type` must name a currently-registered
-     * color scheme, not just be *some* string — so a stale scheme name (renamed or
-     * removed since the value was saved) degrades to "not usable" (falls back to
-     * the base) instead of reaching a lookup that assumes every `.type` is
-     * registered. Omit when the type-shape check alone is enough to trust the value.
-     *
-     * Runs at **schema build** too, over the slot's own `promotedBase` — the base
-     * is what every failing tier degrades to, so it has to clear the same bar.
-     * Keep the hook a function of module-level data (as `isRegisteredColorScheme`
-     * is of `COLOR_SCHEMES`); one that consults state its plugin registers later
-     * during `install()` would reject a base that is really fine.
-     */
-    validate?: (value: unknown) => boolean;
 }
 /**
  * A slot definition, split on whether the slot's type spends `undefined` on
@@ -244,7 +323,9 @@ interface ConfigSlotDefinitionCommon {
  * this mistake actually happens.
  *
  * Stating the sentinel stays meaningful in a subclass override, where the merge
- * is a spread and an omitted key inherits the base's value.
+ * is a spread and an omitted key inherits the base's value. The same spread is
+ * why an enum slot's `model` stays optional here though `ConfigSlot` requires
+ * one: a subclass restating only the default inherits the vocabulary.
  */
 export type ConfigSlotDefinition = (ConfigSlotDefinitionCommon & {
     /** a `maybe*` slot type, whose unset state is `undefined` */
@@ -258,16 +339,25 @@ export type ConfigSlotDefinition = (ConfigSlotDefinitionCommon & {
     defaultValue: unknown;
 });
 /**
- * A configuration slot is a plain value-union MST property: the slot's value
- * type, OR a `jexl:...` callback string. 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`.
+ * 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`).
  */
-export default function ConfigSlot(definition: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, [undefined]>;
+export default function ConfigSlot(definition: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<IAnyType, [undefined]>;
 /**
  * New value when converting a fixed-value slot to a jexl callback. Already-
  * callback values are returned unchanged.

package/esm/configuration/configurationSlot.js

@@ -1,9 +1,21 @@
 import { types } from '@jbrowse/mobx-state-tree';
-import { freezeDeep } from '../util/freezeDeep.js';
+import { isCssColor } from '../util/cssColorParse.js';
 import { isJexl, stringToJexlExpression } from '../util/jexlStrings.js';
-import { FileLocation } from '../util/types/mst.js';
-import { isUsableValue } from './slotShape.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`;
+}
+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.
+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,
+});
 // 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.
@@ -15,31 +27,39 @@ import { isCallbackValue } from './slotValueUtils.js';
 // of.
 const slotTypes = {
     stringArray: { model: types.array(types.string), fallbackDefault: [] },
+    expressionArray: {
+        model: types.array(JexlExpressionString),
+        fallbackDefault: [],
+    },
+    colorArray: { model: types.array(CssColorEntryType), fallbackDefault: [] },
     stringArrayMap: {
         model: types.map(types.array(types.string)),
         fallbackDefault: {},
     },
     numberMap: { model: types.map(types.number), fallbackDefault: {} },
+    stringMap: { model: types.map(types.string), fallbackDefault: {} },
     boolean: { model: types.boolean, fallbackDefault: true },
-    // a color is just a string; the editor picks a color widget off the slot's
-    // `type` metadata, and values are accepted unvalidated (CSS names, hex, jexl)
-    color: { model: types.string, fallbackDefault: 'black' },
+    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 (a drag-resized track height), or the inherit
-    // sentinel every promotable slot needs (pair with `promotedBase`, and read
-    // with `resolveConf`).
+    // computed/auto fallback, e.g. a drag-resized track height.
     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(types.string) },
-    // object-valued, e.g. alignments `colorBy`
+    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
+    featureField: { model: types.string, fallbackDefault: '' },
     fileLocation: {
         model: FileLocation,
         fallbackDefault: {
@@ -47,12 +67,22 @@ 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
+    maybeFileLocation: { model: MaybeFileLocation },
     frozen: { model: types.frozen(), fallbackDefault: {} },
 };
-// The two types with no builtin table entry, because the author supplies the
-// `types.enumeration` as `model`. Named once, and spliced into both the type
-// union and the runtime set below so those two cannot drift apart.
-const ENUM_SLOT_TYPES = ['stringEnum', 'maybeStringEnum'];
+// 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.
+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
@@ -86,18 +116,45 @@ const MAYBE_TYPES = new Set([
     'maybeStringEnum',
 ]);
 const JexlStringType = types.refinement('JexlString', types.string, isJexl);
+const CALLBACK_SLOTS = 'a slot that takes a callback declares the names it reads, which its config docs list as callback args';
+function notACallbackSlot(value) {
+    return `${JSON.stringify(value)} is a jexl: callback, and this slot takes a value: ${CALLBACK_SLOTS}`;
+}
+/** Why the slot `name`, of type `type`, refuses `value` on a write. */
+export function slotWriteRefusal(name, type, value) {
+    const bare = type === 'expressionArray' && Array.isArray(value)
+        ? value.find(entry => !isJexl(entry))
+        : undefined;
+    return isJexl(value)
+        ? `${name} takes no jexl: callback, and ${JSON.stringify(value)} is one: ${CALLBACK_SLOTS}`
+        : bare !== undefined
+            ? `${name} takes jexl: expressions, and ${JSON.stringify(bare)} is not an expression: write it with its prefix, as "jexl:${String(bare)}"`
+            : `${name} is a ${type} slot and cannot take ${JSON.stringify(value)}`;
+}
+function refusingCallbacks(model) {
+    return types.refinement(model, value => !isJexl(value), notACallbackSlot);
+}
 /**
- * A configuration slot is a plain value-union MST property: the slot's value
- * type, OR a `jexl:...` callback string. 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`.
+ * 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`).
  */
 export default function ConfigSlot(definition) {
-    const { model, type, defaultValue, promotedBase } = definition;
+    const { model, type, defaultValue } = definition;
     if (!CONFIG_SLOT_TYPE_NAMES.has(type)) {
         throw new Error(`config slot needs a known type name, got ${JSON.stringify(type)}`);
     }
@@ -111,49 +168,6 @@ export default function ConfigSlot(definition) {
     if (defaultValue === undefined && !MAYBE_TYPES.has(type)) {
         throw new Error("no 'defaultValue' provided");
     }
-    // `promotedBase` is what makes a slot promotable, so its presence is the whole
-    // condition here (ADR-047).
-    //
-    // A promotable slot spends being-unset on the inherit sentinel, so it must be a
-    // `maybe*` type. Any *concrete* default would double as the inherit signal,
-    // making that one value un-customizable under an opposite promoted default — an
-    // authoring mistake with no runtime symptom other than a setting that won't
-    // stay put, so fail at construction.
-    if (promotedBase !== undefined) {
-        if (!MAYBE_TYPES.has(type)) {
-            throw new Error(`a 'promotedBase' slot needs a maybe* type whose undefined is the inherit sentinel, not "${type}"`);
-        }
-        if (defaultValue !== undefined) {
-            throw new Error("a promotable slot must leave 'defaultValue' undefined — that IS the inherit sentinel; 'promotedBase' is what an unset slot resolves to");
-        }
-        // The base is the bottom of the cascade: every other tier that fails
-        // `isUsableValue` falls back to it, so a base that would itself fail has
-        // nowhere left to fall and every read of the slot returns a value no
-        // consumer handles — with nothing thrown anywhere. The typo this catches is
-        // a `promotedBase` outside the slot's own vocabulary (an enum member not in
-        // `model`, a non-finite number), which nothing else in the system checks.
-        if (!isUsableValue(definition, promotedBase)) {
-            throw new Error(`a 'promotedBase' must be a value the slot can hold: ${JSON.stringify(promotedBase)} is not a valid "${type}"`);
-        }
-        // A promotable slot cannot hold a callback: `isUsableValue` refuses a
-        // `jexl:` value at both cascade tiers, so one written into the slot is
-        // discarded straight back to the base. `contextVariable` is the only thing
-        // that offers writing one — it is what raises the config editor's jexl
-        // toggle (`SlotEditor`) — so the pair is a control whose every write the
-        // cascade throws away, with nothing thrown anywhere. Nothing else in the
-        // system states this; DISPLAY_TYPE_DEFAULTS.md §"No callbacks" only
-        // describes the read side.
-        if (definition.contextVariable?.length) {
-            throw new Error("a promotable slot ('promotedBase') cannot declare 'contextVariable': the cascade refuses a jexl: callback, so the config editor would offer a toggle whose writes silently degrade back to the base");
-        }
-        // The resolver hands `promotedBase` out by reference, so an object-valued one
-        // (`maybeFrozen`, e.g. alignments `colorBy`) is one literal shared live by
-        // every track sitting at base. Freeze it here, the only place it enters the
-        // system, so mutating a resolved value throws instead of silently rewriting
-        // the default for every other track — and for every later session, since this
-        // object belongs to the schema. See `freezeDeep` for why by-reference stays.
-        freezeDeep(promotedBase);
-    }
     // 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
@@ -161,8 +175,6 @@ export default function ConfigSlot(definition) {
     // and the branch reading it never runs. There is no symptom: the slot reads as
     // a perfectly good value everywhere.
     //
-    // Last, so a promotable slot still gets the more specific message above.
-    //
     // 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
@@ -171,12 +183,28 @@ export default function ConfigSlot(definition) {
     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.`);
     }
-    return types.stripDefault(types.union(JexlStringType, 
-    // `maybeStringEnum` is the only maybe type whose model comes from the
-    // author: they write the plain vocabulary (`['fixed','grow','fit']`) and
-    // the nullability is added here, so no enumeration has to carry a fake
-    // member for the cascade's benefit.
-    type === 'maybeStringEnum' ? types.maybe(valueModel) : valueModel), defaultValue);
+    const callback = !!definition.contextVariable?.length;
+    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)) {
+        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);
+    return types.stripDefault(callback
+        ? types.union(JexlStringType, value)
+        : type === 'featureField'
+            ? 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)
+        : type === 'stringEnumArray'
+            ? types.array(model)
+            : model;
 }
 /**
  * New value when converting a fixed-value slot to a jexl callback. Already-

package/esm/configuration/fillLocations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * 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',
+ * faiLocation: { uri: 'custom.fai' } }`, silently lost the index it named to
+ * 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>): {
+    [x: string]: unknown;
+};

package/esm/configuration/fillLocations.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * 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',
+ * faiLocation: { uri: 'custom.fai' } }`, silently lost the index it named to
+ * 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 };
+}

package/esm/configuration/formatAboutConfigSchema.d.ts

@@ -28,28 +28,14 @@
  * ```
  */
 export declare function FormatAboutConfigSchemaFactory(): import("./configurationSchema.ts").ConfigurationSchemaType<{
-    /**
-     * #slot formatAbout.config
-     * callback returning an object of fields to merge over the config shown
-     */
     readonly config: {
-        readonly type: "frozen";
-        readonly description: "formats configuration object in about dialog";
-        readonly defaultValue: {};
-        readonly contextVariable: ["config"];
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
     };
-    /**
-     * #slot formatAbout.hideUris
-     * leave file locations out of the About dialog, for a deployment that would
-     * rather not show users where the data sits. Hides URIs and local paths
-     * alike, drops the "Copy config" button, and suppresses the File info panel
-     * — a BAM's `@SQ UR:` and `@PG CL:` lines are locations too. "Show ref
-     * names" stays, since it exposes none. The two tiers are OR'd, so a
-     * session-wide `true` cannot be turned back on by a track. It hides the
-     * locations from the dialog only, not from `config.json`
-     */
     readonly hideUris: {
-        readonly type: "boolean";
-        readonly defaultValue: false;
+        type: "boolean";
+    } & {
+        defaultValue: boolean;
     };
-}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("./requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;