@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/configuration/configurationSlot.js

@@ -1,239 +1,218 @@
 import { types } from '@jbrowse/mobx-state-tree';
-import { getEnv } from "../util/index.js";
-import { stringToJexlExpression } from "../util/jexlStrings.js";
-import { FileLocation } from "../util/types/mst.js";
-function isValidColorString(_str) {
-    return true;
-}
-const typeModels = {
-    stringArray: types.array(types.string),
-    stringArrayMap: types.map(types.array(types.string)),
-    numberMap: types.map(types.number),
-    boolean: types.boolean,
-    color: types.refinement('Color', types.string, isValidColorString),
-    integer: types.integer,
-    number: types.number,
-    string: types.string,
-    text: types.string,
-    fileLocation: FileLocation,
-    frozen: types.frozen(),
-};
-const fallbackDefaults = {
-    stringArray: [],
-    stringArrayMap: {},
-    numberMap: {},
-    boolean: true,
-    color: 'black',
-    integer: 1,
-    number: 1,
-    string: '',
-    text: '',
-    fileLocation: { uri: '/path/to/resource.txt', locationType: 'UriLocation' },
-    frozen: {},
-};
-const literalJSON = (self) => ({
-    views: {
-        get valueJSON() {
-            return self.value;
-        },
+import { freezeDeep } from '../util/freezeDeep.js';
+import { isJexl, stringToJexlExpression } from '../util/jexlStrings.js';
+import { FileLocation } from '../util/types/mst.js';
+import { isUsableValue } from './slotShape.js';
+import { isCallbackValue } from './slotValueUtils.js';
+// 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.
+const slotTypes = {
+    stringArray: { model: types.array(types.string), fallbackDefault: [] },
+    stringArrayMap: {
+        model: types.map(types.array(types.string)),
+        fallbackDefault: {},
     },
-});
-const objectJSON = (self) => ({
-    views: {
-        get valueJSON() {
-            return JSON.stringify(self.value);
+    numberMap: { model: types.map(types.number), 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' },
+    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`).
+    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`
+    maybeFrozen: { model: types.maybe(types.frozen()) },
+    string: { model: types.string, fallbackDefault: '' },
+    text: { model: types.string, fallbackDefault: '' },
+    fileLocation: {
+        model: FileLocation,
+        fallbackDefault: {
+            uri: '/path/to/resource.txt',
+            locationType: 'UriLocation',
         },
     },
-});
-const typeModelExtensions = {
-    fileLocation: objectJSON,
-    number: literalJSON,
-    integer: literalJSON,
-    boolean: literalJSON,
-    frozen: objectJSON,
-    stringArray: (self) => ({
-        views: {
-            get valueJSON() {
-                return JSON.stringify(self.value);
-            },
-        },
-        actions: {
-            add(val) {
-                self.value.push(val);
-            },
-            removeAtIndex(idx) {
-                self.value.splice(idx, 1);
-            },
-            setAtIndex(idx, val) {
-                self.value[idx] = val;
-            },
-        },
-    }),
-    stringArrayMap: (self) => ({
-        views: {
-            get valueJSON() {
-                return JSON.stringify(self.value);
-            },
-        },
-        actions: {
-            add(key, val) {
-                self.value.set(key, val);
-            },
-            remove(key) {
-                self.value.delete(key);
-            },
-            addToKey(key, val) {
-                const ar = self.value.get(key);
-                if (!ar) {
-                    throw new Error(`${key} not found`);
-                }
-                ar.push(val);
-            },
-            removeAtKeyIndex(key, idx) {
-                const ar = self.value.get(key);
-                if (!ar) {
-                    throw new Error(`${key} not found`);
-                }
-                ar.splice(idx, 1);
-            },
-            setAtKeyIndex(key, idx, val) {
-                const ar = self.value.get(key);
-                if (!ar) {
-                    throw new Error(`${key} not found`);
-                }
-                ar[idx] = val;
-            },
-        },
-    }),
-    numberMap: (self) => ({
-        views: {
-            get valueJSON() {
-                return JSON.stringify(self.value);
-            },
-        },
-        actions: {
-            add(key, val) {
-                self.value.set(key, val);
-            },
-            remove(key) {
-                self.value.delete(key);
-            },
-        },
-    }),
+    frozen: { model: types.frozen(), fallbackDefault: {} },
 };
-const JexlStringType = types.refinement('JexlString', types.string, str => str.startsWith('jexl:'));
-function json(value) {
-    return value?.toJSON ? value.toJSON() : `"${value}"`;
-}
-export default function ConfigSlot(slotName, { description = '', model, type, defaultValue, contextVariable = [], }) {
-    if (!type) {
-        throw new Error('type name required');
-    }
-    if (!model) {
-        model = typeModels[type];
+// 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 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.
+ */
+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`.
+const MAYBE_TYPES = new Set([
+    ...Object.entries(slotTypes)
+        .filter(([, spec]) => spec.fallbackDefault === undefined)
+        .map(([name]) => name),
+    'maybeStringEnum',
+]);
+const JexlStringType = types.refinement('JexlString', types.string, isJexl);
+/**
+ * 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`.
+ */
+export default function ConfigSlot(definition) {
+    const { model, type, defaultValue, promotedBase } = definition;
+    if (!CONFIG_SLOT_TYPE_NAMES.has(type)) {
+        throw new Error(`config slot needs a known type name, got ${JSON.stringify(type)}`);
     }
-    if (!model) {
+    const valueModel = model ?? builtinSlotTypes[type]?.model;
+    if (!valueModel) {
         throw new Error(`no builtin config slot type "${type}", and no 'model' param provided`);
     }
-    if (defaultValue === undefined) {
+    // 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 === undefined && !MAYBE_TYPES.has(type)) {
         throw new Error("no 'defaultValue' provided");
     }
-    const configSlotModelName = `${slotName.charAt(0).toUpperCase()}${slotName.slice(1)}ConfigSlot`;
-    let slot = types
-        .model(configSlotModelName, {
-        name: types.literal(slotName),
-        description: types.literal(description),
-        type: types.literal(type),
-        value: types.optional(types.union(JexlStringType, model), defaultValue),
-    })
-        .volatile(() => ({
-        contextVariable,
-    }))
-        .views(self => ({
-        get isCallback() {
-            return String(self.value).startsWith('jexl:');
-        },
-    }))
-        .views(self => ({
-        get expr() {
-            return self.isCallback
-                ? stringToJexlExpression(String(self.value), getEnv(self).pluginManager.jexl)
-                : {
-                    eval: () => self.value,
-                };
-        },
-        get valueJSON() {
-            return self.isCallback ? undefined : json(self.value);
-        },
-    }))
-        .views(self => ({
-        getValue(args = {}) {
-            const v = self.value;
-            return typeof v === 'string' && v.startsWith('jexl:')
-                ? self.expr.eval(args)
-                : v;
-        },
-    }))
-        .preProcessSnapshot(val => typeof val === 'object' && val.name === slotName
-        ? val
-        : {
-            name: slotName,
-            description,
-            type,
-            value: val,
-        })
-        .postProcessSnapshot(snap => {
-        if (typeof snap.value === 'object') {
-            return JSON.stringify(snap.value) !== JSON.stringify(defaultValue)
-                ? snap.value
-                : undefined;
+    // `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}"`);
         }
-        return snap.value !== defaultValue ? snap.value : undefined;
-    })
-        .actions(self => ({
-        set(newVal) {
-            self.value = newVal;
-        },
-        reset() {
-            self.value = defaultValue;
-        },
-        convertToCallback() {
-            if (self.isCallback) {
-                return;
-            }
-            self.value = `jexl:${self.valueJSON || "''"}`;
-        },
-        convertToValue() {
-            if (!self.isCallback) {
-                return;
-            }
-            try {
-                const funcResult = self.expr.eval();
-                if (funcResult !== undefined) {
-                    self.value = funcResult;
-                    return;
-                }
-            }
-            catch (e) {
-            }
-            self.value = defaultValue;
-            if (!(type in fallbackDefaults)) {
-                throw new Error(`no fallbackDefault defined for type ${type}`);
-            }
-            self.value = fallbackDefaults[type];
-        },
-    }));
-    if (typeModelExtensions[type]) {
-        slot = slot.extend(typeModelExtensions[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
+    // 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.
+    //
+    // 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
+    // right. `LinearMafDisplay.height` over `BaseLinearDisplay`'s `number`/100 is
+    // the case in the repo, and only that display's own tests noticed.
+    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);
+}
+/**
+ * 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.
+ */
+export function toCallbackValue(value) {
+    return isCallbackValue(value) ? value : `jexl:${JSON.stringify(value)}`;
+}
+/**
+ * New value when converting a jexl callback back to a fixed value: try
+ * evaluating with no args, else fall back to the slot default (and to the slot
+ * type's `fallbackDefault` if the default is itself a callback).
+ */
+export function toFixedValue(value, type, defaultValue, jexl) {
+    if (!isCallbackValue(value)) {
+        return value;
+    }
+    try {
+        const result = stringToJexlExpression(value, jexl).eval();
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    catch {
+        /* fall through to default */
+    }
+    if (isCallbackValue(defaultValue)) {
+        const spec = builtinSlotTypes[type];
+        if (spec?.fallbackDefault === undefined) {
+            throw new Error(`no fallbackDefault defined for type ${type}`);
+        }
+        return spec.fallbackDefault;
     }
-    const completeModel = types.optional(slot, {
-        name: slotName,
-        type,
-        description,
-        value: defaultValue,
-    });
-    Object.defineProperty(completeModel, 'isJBrowseConfigurationSlot', {
-        value: true,
-    });
-    return completeModel;
+    return defaultValue;
 }

package/esm/configuration/formatAboutConfigSchema.d.ts

@@ -0,0 +1,55 @@
+/**
+ * #config FormatAbout
+ * #category root
+ * jexl callbacks that add, rewrite or hide fields in a track's About dialog.
+ * The same schema hangs off every track and off the session as
+ * `configuration.formatAbout`, which applies to every track at once. Where both
+ * are set the track's object is spread over the session's, so a track can
+ * override individual keys the global callback added.
+ *
+ * #example
+ * On a track. The callback's variable is `config`, not `feature`, since the
+ * dialog shows the track's own configuration rather than a feature:
+ * ```js
+ * {
+ *   type: 'FeatureTrack',
+ *   trackId: 'genes',
+ *   name: 'Genes',
+ *   assemblyNames: ['hg38'],
+ *   adapter: {
+ *     type: 'Gff3TabixAdapter',
+ *     uri: 'https://example.com/genes.gff.gz',
+ *   },
+ *   formatAbout: {
+ *     hideUris: true,
+ *     config: "jexl:{Source:'GENCODE v44', adapter:undefined}",
+ *   },
+ * }
+ * ```
+ */
+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"];
+    };
+    /**
+     * #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;
+    };
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;

package/esm/configuration/formatAboutConfigSchema.js

@@ -0,0 +1,58 @@
+import { ConfigurationSchema } from './configurationSchema.js';
+/**
+ * #config FormatAbout
+ * #category root
+ * jexl callbacks that add, rewrite or hide fields in a track's About dialog.
+ * The same schema hangs off every track and off the session as
+ * `configuration.formatAbout`, which applies to every track at once. Where both
+ * are set the track's object is spread over the session's, so a track can
+ * override individual keys the global callback added.
+ *
+ * #example
+ * On a track. The callback's variable is `config`, not `feature`, since the
+ * dialog shows the track's own configuration rather than a feature:
+ * ```js
+ * {
+ *   type: 'FeatureTrack',
+ *   trackId: 'genes',
+ *   name: 'Genes',
+ *   assemblyNames: ['hg38'],
+ *   adapter: {
+ *     type: 'Gff3TabixAdapter',
+ *     uri: 'https://example.com/genes.gff.gz',
+ *   },
+ *   formatAbout: {
+ *     hideUris: true,
+ *     config: "jexl:{Source:'GENCODE v44', adapter:undefined}",
+ *   },
+ * }
+ * ```
+ */
+export function FormatAboutConfigSchemaFactory() {
+    return ConfigurationSchema('FormatAbout', {
+        /**
+         * #slot formatAbout.config
+         * callback returning an object of fields to merge over the config shown
+         */
+        config: {
+            type: 'frozen',
+            description: 'formats configuration object in about dialog',
+            defaultValue: {},
+            contextVariable: ['config'],
+        },
+        /**
+         * #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`
+         */
+        hideUris: {
+            type: 'boolean',
+            defaultValue: false,
+        },
+    });
+}

package/esm/configuration/formatDetailsConfigSchema.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Levels of subfeature the `subfeatures` callback runs on when no tier sets
+ * `depth`. Lives here rather than as the slot's `defaultValue` because the slot
+ * has to be able to say "unset": see the `depth` slot's own comment.
+ */
+export declare const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
+/**
+ * #config FormatDetails
+ * #category root
+ * jexl callbacks that add, rewrite or hide fields in the feature-details panel.
+ * The same schema hangs off every track and off the session as
+ * `configuration.formatDetails`, which applies to every track at once. Where
+ * both are set, the callbacks merge with the track's object over the session's,
+ * so a track can override individual keys the global callback added, and the
+ * numeric slots take the track's value when the track sets one.
+ *
+ * #example
+ * On a track. The callback returns an object merged over the feature: a new key
+ * adds a row, an existing key rewrites it, and `undefined` hides it. A bare URL
+ * is turned into a link for you, so no `<a>` markup is needed:
+ * ```js
+ * {
+ *   type: 'FeatureTrack',
+ *   trackId: 'genes',
+ *   name: 'Genes',
+ *   assemblyNames: ['hg38'],
+ *   adapter: {
+ *     type: 'Gff3TabixAdapter',
+ *     uri: 'https://example.com/genes.gff.gz',
+ *   },
+ *   formatDetails: {
+ *     feature: "jexl:{ncbi:'https://www.ncbi.nlm.nih.gov/gene/?term='+feature.name, phase:undefined}",
+ *   },
+ * }
+ * ```
+ */
+export declare function FormatDetailsConfigSchemaFactory(): import("./configurationSchema.ts").ConfigurationSchemaType<{
+    /**
+     * #slot formatDetails.feature
+     * callback returning an object of fields to merge onto the clicked feature.
+     * A plain object works too, for fields that are the same on every feature
+     */
+    readonly feature: {
+        readonly type: "frozen";
+        readonly description: "adds extra fields to the feature details";
+        readonly defaultValue: {};
+        readonly contextVariable: ["feature"];
+    };
+    /**
+     * #slot formatDetails.subfeatures
+     * the same, applied to each subfeature down to `depth`
+     */
+    readonly subfeatures: {
+        readonly type: "frozen";
+        readonly description: "adds extra fields to the subfeatures of a feature";
+        readonly defaultValue: {};
+        readonly contextVariable: ["feature"];
+    };
+    /**
+     * #slot formatDetails.depth
+     * how many levels of subfeature the `subfeatures` callback runs on,
+     * defaulting to 2, which stops at a gene's transcripts rather than
+     * descending into their exons and CDSs. A track's value wins over the
+     * session's
+     */
+    readonly depth: {
+        readonly type: "maybeNumber";
+        readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
+    };
+    /**
+     * #slot formatDetails.maxDepth
+     * how many levels of subfeature card the panel renders at all, which is a
+     * separate question from how deep `subfeatures` formats. Unset means no
+     * limit. A track's value wins over the session's
+     */
+    readonly maxDepth: {
+        readonly type: "maybeNumber";
+        readonly description: "hide subfeatures nested deeper than this, default no limit";
+    };
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;