@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/configuration/promotableSlots.js

@@ -0,0 +1,45 @@
+import { getType, isType } from '@jbrowse/mobx-state-tree';
+import { getConfigurationSchemaDefinition } from './schemaRegistry.js';
+import { isSlotDefinitionEntry } from './schemaTypes.js';
+// The `promotable` slot names of one config schema (includes slots inherited via
+// baseConfiguration — merged into the table at construction), cached by MST type
+// since a schema's slot table is fixed.
+//
+// Only the functions that genuinely *enumerate* promotable slots call this — the
+// worker-payload resolver, the badge diff, "clear every default", and
+// `assertNoPromotableSlots`. It is deliberately NOT on any read path:
+// `getConf` used to consult it on all ~1300 config reads in the repo to decide
+// whether to cascade, which cost a `getType` per read (measured at ~60% overhead
+// over `readConfObject`) to serve the ~15 promotable ones. `resolveConf` names
+// the cascade at the call site instead, so there is nothing to look up.
+//
+// Its own module, and a leaf one, because `ui/promotablePinCoverage.ts` wants
+// the slot names and nothing else: reaching them through a module that also held
+// `readConfObject` pulled jexl and the whole read path into the ui graph. See the
+// note on that export in `ui/index.ts`.
+const promotableSlotsByType = new WeakMap();
+/**
+ * Takes a live config node *or* the schema type itself, for the reason
+ * `getConfigurationSchemaDefinition` does: every resolver here holds a node,
+ * while a caller enumerating registered display types
+ * (`displayTypesWithPromotableSlots`) holds only `DisplayType.configSchema` and
+ * has nothing to create a node from. Caching under whichever handle it was
+ * given is safe — a schema registers both its outer `stripDefault` wrapper and
+ * its inner model against the same slot table, so the two entries agree.
+ */
+export function promotableSlotNames(configOrType) {
+    const type = isType(configOrType) ? configOrType : getType(configOrType);
+    const cached = promotableSlotsByType.get(type);
+    if (cached) {
+        return cached;
+    }
+    const names = new Set();
+    const table = getConfigurationSchemaDefinition(configOrType);
+    for (const [name, def] of Object.entries(table ?? {})) {
+        if (isSlotDefinitionEntry(def) && def.promotedBase !== undefined) {
+            names.add(name);
+        }
+    }
+    promotableSlotsByType.set(type, names);
+    return names;
+}

package/esm/configuration/readConfObject.d.ts

@@ -0,0 +1,56 @@
+import type { Feature } from '../util/index.ts';
+import type { JexlInstance } from '../util/jexlStrings.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue } from './types.ts';
+import type { IMSTMap } from '@jbrowse/mobx-state-tree';
+/**
+ * #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`.
+ *
+ * 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.
+ *
+ * @param model - instance of ConfigurationSchema
+ * @param slotPaths - array of paths to read
+ * @param args - extra arguments e.g. for a feature callback,
+ *  will be sent to each of the slotNames
+ */
+export declare function readConfObject(confObject: AnyConfigurationModel): AnyConfigurationSnapshot;
+export declare function readConfObject<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : any;
+export declare function readConfObject(confObject: IMSTMap<AnyConfigurationSchemaType>, slotPath?: string | string[], args?: Record<string, unknown>): any;
+/**
+ * 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.
+ */
+export declare function readConfigValue<T>(config: Record<string, unknown>, key: string | string[], feature: Feature, jexl: JexlInstance): T;
+/**
+ * #api core/configuration
+ * Read a single config slot from a config that may be **either** a live MST
+ * node or a plain snapshot object, evaluating the value if it is a `jexl:`
+ * expression. For the dialogs and panels that are handed a track config without
+ * knowing which of the two they got. An About panel gets a hydrated track
+ * config from the session and a bare object from an embedded caller.
+ *
+ * Reach for `readConfObject` or `readConfigValue` when the shape is known:
+ * this one decides at runtime, and the plain branch inherits the snapshot
+ * caveat (a slot at its default is absent from a snapshot, so it reads
+ * `undefined`).
+ *
+ * @param config - live config model or plain config object
+ * @param slotPath - slot name, or path of sub-config names ending in a slot
+ * @param args - extra arguments for a callback slot, e.g. `{ feature }`
+ * @param jexl - realm jexl instance, required only to evaluate a callback slot
+ *  on a plain object (a live node resolves its own from env)
+ */
+export declare function readConfSlot<T = unknown>(config: AnyConfigurationModel | Record<string, unknown>, slotPath: string | string[], args?: Record<string, unknown>, jexl?: JexlInstance): T;

package/esm/configuration/readConfObject.js

@@ -0,0 +1,161 @@
+/**
+ * @module
+ * The config **readers**: `readConfObject` off a live MST config node,
+ * `readConfigValue` off a plain snapshot object in a worker or a renderer, and
+ * `readConfSlot` for the callers that hold either and don't know which. All
+ * three exist to evaluate a slot's `jexl:...` callback on read; they differ only
+ * in where the jexl instance comes from (the node's env vs. an explicit
+ * argument) and in how much of that they are willing to decide at runtime.
+ */
+import { getEnv, getSnapshot, getType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+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)
+        .pluginManager?.jexl;
+    if (!jexl) {
+        throw new Error(`cannot evaluate jexl config callback ${JSON.stringify(expr)}: no pluginManager jexl instance in config env`);
+    }
+    return evaluateJexl(expr, args, jexl);
+}
+function isConfigMap(confObject) {
+    return isStateTreeNode(confObject) && isMapType(getType(confObject));
+}
+// Read a slot's raw stored value, drilling into a map entry via `.get()` when
+// the config is itself a types.map.
+function rawSlotValue(confObject, slotName) {
+    return isConfigMap(confObject)
+        ? confObject.get(slotName)
+        : confObject[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 = rawSlotValue(confObject, slotName);
+    if (value === undefined) {
+        return undefined;
+    }
+    const val = isCallbackValue(value)
+        ? 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.
+    return isStateTreeNode(val) ? getSnapshot(val) : val;
+}
+// loose implementation signature: the body returns values that are `any` by
+// nature (raw slot values, snapshots); the typed overload above is what callers
+// see.
+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 = rawSlotValue(conf, slotPath[i]);
+        if (subConf === undefined) {
+            return undefined;
+        }
+        conf = subConf;
+    }
+    return readSlot(conf, slotPath[slotPath.length - 1], args);
+}
+// The plain-object half of the slot walk, shared by readConfigValue and
+// readConfSlot. 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;
+        for (const k of key) {
+            val = val?.[k];
+        }
+        return val;
+    }
+    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.
+ */
+export function readConfigValue(config, key, feature, jexl) {
+    const raw = resolveConfigValue(config, key);
+    return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
+}
+/**
+ * #api core/configuration
+ * Read a single config slot from a config that may be **either** a live MST
+ * node or a plain snapshot object, evaluating the value if it is a `jexl:`
+ * expression. For the dialogs and panels that are handed a track config without
+ * knowing which of the two they got. An About panel gets a hydrated track
+ * config from the session and a bare object from an embedded caller.
+ *
+ * Reach for `readConfObject` or `readConfigValue` when the shape is known:
+ * this one decides at runtime, and the plain branch inherits the snapshot
+ * caveat (a slot at its default is absent from a snapshot, so it reads
+ * `undefined`).
+ *
+ * @param config - live config model or plain config object
+ * @param slotPath - slot name, or path of sub-config names ending in a slot
+ * @param args - extra arguments for a callback slot, e.g. `{ feature }`
+ * @param jexl - realm jexl instance, required only to evaluate a callback slot
+ *  on a plain object (a live node resolves its own from env)
+ */
+export function readConfSlot(config, slotPath, args = {}, jexl) {
+    if (isStateTreeNode(config)) {
+        // pass slotPath through rather than normalizing a string into a one-element
+        // array: readConfObject keeps the single-slot read allocation-free
+        return readConfObject(config, slotPath, args);
+    }
+    const value = resolveConfigValue(config, slotPath);
+    // A plain-object config has no MST env, so the realm's jexl instance can't be
+    // resolved automatically — callers reading a callback slot must pass it. Only
+    // reached when the slot actually holds a `jexl:` value (trackId/adapter/etc.
+    // never do), so non-callback readers need not supply it.
+    if (isCallbackValue(value)) {
+        if (!jexl) {
+            throw new Error(`cannot evaluate jexl config slot ${JSON.stringify(slotPath)} on a plain-object config: no jexl instance provided`);
+        }
+        return evaluateJexl(value, args, jexl);
+    }
+    return value;
+}

package/esm/configuration/schemaRegistry.d.ts

@@ -0,0 +1,35 @@
+import type { ConfigurationSchemaDefinition, MergedConfigurationSchemaOptions } from './configurationSchema.ts';
+import type { AnyConfigurationModel } from './types.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+export interface ConfigurationSchemaMetadata {
+    /** the raw slot/sub-schema/constant table, also carrying per-slot editor metadata */
+    definition: ConfigurationSchemaDefinition;
+    /**
+     * construction options (identifier kind, baseConfiguration, etc.) as stored,
+     * i.e. with any `baseConfiguration`'s hooks already composed in
+     */
+    options: MergedConfigurationSchemaOptions<any, any>;
+}
+export declare function registerConfigurationSchema(type: IAnyType, metadata: ConfigurationSchemaMetadata): void;
+export declare function getConfigurationSchemaMetadata(type: IAnyType): ConfigurationSchemaMetadata | undefined;
+export declare function isRegisteredConfigurationSchema(type: IAnyType): boolean;
+/**
+ * The slot/sub-schema/constant table for a config (includes slots merged in from
+ * `baseConfiguration` at schema construction). Undefined when the argument isn't
+ * a registered configuration schema. The single accessor for "what are this
+ * config's slots?" — shared by the slot facade, promotable defaults, and
+ * `fullConfSnapshot`.
+ *
+ * Takes a live node *or* the schema type itself. Every in-tree reader holds a
+ * node, which is why the `getType` hop is here; a caller enumerating registered
+ * element types (`ConfigSlotDefaults.test.ts`) holds only the type, and for a
+ * track schema it cannot get a node — `explicitIdentifier` makes `trackId` a
+ * required MST identifier, so there is nothing to `create({})`.
+ */
+export declare function getConfigurationSchemaDefinition(nodeOrType: AnyConfigurationModel | IAnyType): ConfigurationSchemaDefinition | undefined;
+/**
+ * The construction options a live config node's schema was built with
+ * (identifier kind, `explicitlyTyped`, the `preProcessSnapshot` hook). Undefined
+ * when the node's type isn't a registered configuration schema.
+ */
+export declare function getConfigurationSchemaOptions(node: AnyConfigurationModel): MergedConfigurationSchemaOptions<any, any> | undefined;

package/esm/configuration/schemaRegistry.js

@@ -0,0 +1,50 @@
+import { getType, isType } from '@jbrowse/mobx-state-tree';
+// Per-schema metadata keyed by the MST type itself. Registered for BOTH the
+// outer stripDefault wrapper (what `ConfigurationSchema` returns and what
+// sub-schema properties hold) and the inner model (what `getType(node)` returns
+// for a live config), so a lookup succeeds from either handle.
+//
+// This replaces stamping `jbrowseSchemaDefinition`/`jbrowseSchemaOptions`/
+// `isJBrowseConfigurationSchema` onto the MST type objects: the type stays a
+// plain MST type, "is this a config schema" is registry membership instead of a
+// flag-or-name-match, and the metadata is reached by type identity. The map is
+// weak, so a discarded schema type is collected normally.
+const schemaRegistry = new WeakMap();
+export function registerConfigurationSchema(type, metadata) {
+    schemaRegistry.set(type, metadata);
+}
+export function getConfigurationSchemaMetadata(type) {
+    return schemaRegistry.get(type);
+}
+export function isRegisteredConfigurationSchema(type) {
+    return schemaRegistry.has(type);
+}
+// The three lookups above take a schema *type*; the two below take a live config
+// *node* and make the `getType` hop themselves, which is what every reader
+// actually wants — a node is what they hold. Leaving the hop to the call site is
+// how `slotFacade` came to reach the registry directly for `options` while going
+// through a helper for `definition`.
+/**
+ * The slot/sub-schema/constant table for a config (includes slots merged in from
+ * `baseConfiguration` at schema construction). Undefined when the argument isn't
+ * a registered configuration schema. The single accessor for "what are this
+ * config's slots?" — shared by the slot facade, promotable defaults, and
+ * `fullConfSnapshot`.
+ *
+ * Takes a live node *or* the schema type itself. Every in-tree reader holds a
+ * node, which is why the `getType` hop is here; a caller enumerating registered
+ * element types (`ConfigSlotDefaults.test.ts`) holds only the type, and for a
+ * track schema it cannot get a node — `explicitIdentifier` makes `trackId` a
+ * required MST identifier, so there is nothing to `create({})`.
+ */
+export function getConfigurationSchemaDefinition(nodeOrType) {
+    return getConfigurationSchemaMetadata(isType(nodeOrType) ? nodeOrType : getType(nodeOrType))?.definition;
+}
+/**
+ * The construction options a live config node's schema was built with
+ * (identifier kind, `explicitlyTyped`, the `preProcessSnapshot` hook). Undefined
+ * when the node's type isn't a registered configuration schema.
+ */
+export function getConfigurationSchemaOptions(node) {
+    return getConfigurationSchemaMetadata(getType(node))?.options;
+}

package/esm/configuration/schemaTypes.d.ts

@@ -0,0 +1,23 @@
+import type { ConfigSlotDefinition } from './configurationSlot.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType } from './types.ts';
+/**
+ * given a union of explicitly typed configuration schema types,
+ * extract an array of the type names contained in the union
+ *
+ * @param unionType -
+ * @returns Array of type names contained in the union
+ */
+export declare function getTypeNamesFromExplicitlyTypedUnion(maybeUnionType: unknown): string[];
+export declare function isBareConfigurationSchemaType(thing: unknown): thing is AnyConfigurationSchemaType;
+export declare function isConfigurationSchemaType(thing: unknown): thing is AnyConfigurationSchemaType;
+/**
+ * A configuration schema definition maps each key to exactly one of three kinds
+ * of entry:
+ *
+ *  - constant   → a bare string/number (becomes a volatile instance constant)
+ *  - slot       → a ConfigSlotDefinition object (has a `type` field, not a type)
+ *  - sub-schema → an MST configuration-schema type, see isConfigurationSchemaType
+ */
+export declare function isConstantEntry(def: unknown): def is string | number;
+export declare function isSlotDefinitionEntry(def: unknown): def is ConfigSlotDefinition;
+export declare function isConfigurationModel(thing: unknown): thing is AnyConfigurationModel;

package/esm/configuration/schemaTypes.js

@@ -0,0 +1,94 @@
+/**
+ * @module
+ * Recognizing configuration schemas and classifying the entries in one. These
+ * predicates are the single source of truth for both questions — shared by
+ * schema construction, every reader, and the config editor — so "is this a
+ * config schema?" and "what kind of entry is this?" have one answer everywhere.
+ */
+import { getType, isArrayType, isLateType, isMapType, isModelType, isOptionalType, isStateTreeNode, isType, isUnionType, } from '@jbrowse/mobx-state-tree';
+import { getDefaultValue, getSubType, getUnionSubTypes, resolveLateType, } from '../util/mst-reflection.js';
+import { isRegisteredConfigurationSchema } from './schemaRegistry.js';
+/**
+ * given a union of explicitly typed configuration schema types,
+ * extract an array of the type names contained in the union
+ *
+ * @param unionType -
+ * @returns Array of type names contained in the union
+ */
+export function getTypeNamesFromExplicitlyTypedUnion(maybeUnionType) {
+    if (isType(maybeUnionType)) {
+        const resolved = resolveLateType(maybeUnionType);
+        if (isUnionType(resolved)) {
+            const typeNames = [];
+            for (const subType of getUnionSubTypes(resolved)) {
+                const resolvedSub = resolveLateType(subType);
+                // a nested union contributes its own names; otherwise the subtype is a
+                // single explicitly-typed schema whose name is its default's `type`
+                const nested = getTypeNamesFromExplicitlyTypedUnion(resolvedSub);
+                if (nested.length) {
+                    typeNames.push(...nested);
+                }
+                else {
+                    const typeName = getDefaultValue(resolvedSub).type;
+                    if (!typeName) {
+                        throw new Error(`invalid config schema type ${resolvedSub}`);
+                    }
+                    typeNames.push(typeName);
+                }
+            }
+            return typeNames;
+        }
+    }
+    return [];
+}
+export function isBareConfigurationSchemaType(thing) {
+    if (isType(thing)) {
+        if (isModelType(thing) && isRegisteredConfigurationSchema(thing)) {
+            return true;
+        }
+        // if it's a late type, assume its a config schema
+        if (isLateType(thing)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function isConfigurationSchemaType(thing) {
+    // written as a series of if-statements instead of a big logical because this
+    // construction gives much better debugging backtraces.
+    // also, note that the order of these statements matters, because for example
+    // some union types are also optional types
+    if (!isType(thing)) {
+        return false;
+    }
+    else if (isBareConfigurationSchemaType(thing)) {
+        return true;
+    }
+    else if (isUnionType(thing)) {
+        return getUnionSubTypes(thing).every(t => isConfigurationSchemaType(t) || t.name === 'undefined');
+    }
+    else if ((isOptionalType(thing) || isArrayType(thing) || isMapType(thing)) &&
+        isConfigurationSchemaType(getSubType(thing))) {
+        return true;
+    }
+    else {
+        return false;
+    }
+}
+/**
+ * A configuration schema definition maps each key to exactly one of three kinds
+ * of entry:
+ *
+ *  - constant   → a bare string/number (becomes a volatile instance constant)
+ *  - slot       → a ConfigSlotDefinition object (has a `type` field, not a type)
+ *  - sub-schema → an MST configuration-schema type, see isConfigurationSchemaType
+ */
+export function isConstantEntry(def) {
+    return typeof def === 'string' || typeof def === 'number';
+}
+export function isSlotDefinitionEntry(def) {
+    return (typeof def === 'object' && def !== null && !isType(def) && 'type' in def);
+}
+export function isConfigurationModel(thing) {
+    return isStateTreeNode(thing) && isConfigurationSchemaType(getType(thing));
+}

package/esm/configuration/slotFacade.d.ts

@@ -0,0 +1,82 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ConfigSlotDefinition, ConfigSlotType } from './configurationSlot.ts';
+import type { AnyConfigurationModel } from './types.ts';
+/**
+ * Whether `slotName` on a config node is a slot (vs a nested sub-schema or a
+ * string/number constant).
+ */
+export declare function isConfigurationSlot(node: AnyConfigurationModel, slotName: string): boolean;
+/**
+ * Run `node`'s own schema `preProcessSnapshot` over a partial bag of slot
+ * values headed for that config.
+ *
+ * A config.json snapshot gets this for free on `create`, but the session/URL
+ * path writes slots one `setSlot` at a time onto an already-created config, so
+ * without this a schema's shorthand expansions and legacy-key migrations apply
+ * to `config.json` and silently no-op in a session spec, share link, or embed —
+ * the surfaces that are supposed to speak the same vocabulary. The hooks are
+ * written to normalize whatever subset of keys they're handed, so a partial bag
+ * is the same shape they already tolerate.
+ */
+export declare function preProcessSlotValues(node: AnyConfigurationModel, values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The duck-typed object the config editor's leaf components consume. They never
+ * touch MST internals — only this shape (see ColorEditor.test.tsx, which passes
+ * a plain object). It is built from `(parentNode, slotName)` + the schema
+ * metadata table. Collection editors edit immutably via `set` (build a new
+ * array/map and assign it).
+ */
+export interface SlotFacade {
+    name: string;
+    description: string;
+    type: ConfigSlotType;
+    contextVariable: string[];
+    defaultValue: unknown;
+    /**
+     * For a `promotable` slot, the value its unset state resolves to when nothing
+     * is promoted (see `promotableResolve.ts`). Undefined on a plain slot, whose
+     * `defaultValue` is already the concrete value.
+     *
+     * Here because a promotable slot's `defaultValue` is always the `undefined`
+     * inherit sentinel, so an editor rendering `defaultValue` for an unset slot
+     * shows nothing at all — for a `maybeBoolean` that reads as a concrete
+     * `false`, which is wrong for every slot whose base is `true`. The editor
+     * still cannot see the *session* tier of the cascade (its target is often a
+     * detached config node), so this is the honest answer it can give: what unset
+     * means with nothing promoted.
+     */
+    promotedBase?: unknown;
+    /** enum choices, present only for `stringEnum`/`maybeStringEnum` slots */
+    choices?: string[];
+    pluginManager: PluginManager;
+    readonly value: unknown;
+    /**
+     * Whether the slot holds a non-default value. Each slot is `stripDefault`-
+     * wrapped, so an at-default slot is omitted from the config snapshot — the
+     * same signal the persistence/delta layer uses (robust for map/array slots
+     * where a live-value `deepEqual` against the plain default would misfire). For
+     * a promotable slot, "non-default" means customized rather than inheriting.
+     */
+    readonly modified: boolean;
+    set: (val: unknown) => void;
+}
+/**
+ * The vocabulary an enum slot offers, or undefined for any other slot. Reads the
+ * author's own `types.enumeration` off `model` — `stringEnum` and
+ * `maybeStringEnum` are the only two types the editor takes choices from, so a
+ * slot typed anything else renders as free text however valid its `model` is.
+ *
+ * Shared by the config editor's facade below and by
+ * `ConfigSlotDefaults.test.ts`, which snapshots every schema's vocabularies:
+ * dropping a member is a silent compatibility break, since a saved session
+ * holding it fails MST validation and the track then fails to hydrate.
+ */
+export declare function slotChoices(def: ConfigSlotDefinition): string[] | undefined;
+/**
+ * Look up a slot's metadata (type/description/defaultValue/contextVariable/
+ * model) from the schema-type table stashed by ConfigurationSchema. Includes
+ * slots inherited via `baseConfiguration`, which are merged into the table at
+ * schema construction.
+ */
+export declare function getSlotDefinition(node: AnyConfigurationModel, slotName: string): ConfigSlotDefinition;
+export declare function makeSlotFacade(node: AnyConfigurationModel, slotName: string): SlotFacade;

package/esm/configuration/slotFacade.js

@@ -0,0 +1,89 @@
+import { getSnapshot } from '@jbrowse/mobx-state-tree';
+import { getEnumerationValues } from '../util/mst-reflection.js';
+import { getEnv } from '../util/mstUtils.js';
+import { getConfigurationSchemaDefinition, getConfigurationSchemaOptions, } from './schemaRegistry.js';
+import { isSlotDefinitionEntry } from './schemaTypes.js';
+/**
+ * The slot's metadata entry, or undefined when `slotName` names a nested
+ * sub-schema or a string/number constant rather than a slot.
+ */
+function slotDefinition(node, slotName) {
+    const def = getConfigurationSchemaDefinition(node)?.[slotName];
+    return isSlotDefinitionEntry(def) ? def : undefined;
+}
+/**
+ * Whether `slotName` on a config node is a slot (vs a nested sub-schema or a
+ * string/number constant).
+ */
+export function isConfigurationSlot(node, slotName) {
+    return !!slotDefinition(node, slotName);
+}
+/**
+ * Run `node`'s own schema `preProcessSnapshot` over a partial bag of slot
+ * values headed for that config.
+ *
+ * A config.json snapshot gets this for free on `create`, but the session/URL
+ * path writes slots one `setSlot` at a time onto an already-created config, so
+ * without this a schema's shorthand expansions and legacy-key migrations apply
+ * to `config.json` and silently no-op in a session spec, share link, or embed —
+ * the surfaces that are supposed to speak the same vocabulary. The hooks are
+ * written to normalize whatever subset of keys they're handed, so a partial bag
+ * is the same shape they already tolerate.
+ */
+export function preProcessSlotValues(node, values) {
+    const preProcess = getConfigurationSchemaOptions(node)?.preProcessSnapshot;
+    return preProcess ? preProcess(values) : values;
+}
+/**
+ * The vocabulary an enum slot offers, or undefined for any other slot. Reads the
+ * author's own `types.enumeration` off `model` — `stringEnum` and
+ * `maybeStringEnum` are the only two types the editor takes choices from, so a
+ * slot typed anything else renders as free text however valid its `model` is.
+ *
+ * Shared by the config editor's facade below and by
+ * `ConfigSlotDefaults.test.ts`, which snapshots every schema's vocabularies:
+ * dropping a member is a silent compatibility break, since a saved session
+ * holding it fails MST validation and the track then fails to hydrate.
+ */
+export function slotChoices(def) {
+    const { type, model } = def;
+    return (type === 'stringEnum' || type === 'maybeStringEnum') && model
+        ? getEnumerationValues(model)
+        : undefined;
+}
+/**
+ * Look up a slot's metadata (type/description/defaultValue/contextVariable/
+ * model) from the schema-type table stashed by ConfigurationSchema. Includes
+ * slots inherited via `baseConfiguration`, which are merged into the table at
+ * schema construction.
+ */
+export function getSlotDefinition(node, slotName) {
+    const def = slotDefinition(node, slotName);
+    if (!def) {
+        throw new Error(`no slot metadata for ${slotName}`);
+    }
+    return def;
+}
+export function makeSlotFacade(node, slotName) {
+    const definition = getSlotDefinition(node, slotName);
+    const { type, description = '', defaultValue, promotedBase, contextVariable = [], } = definition;
+    return {
+        name: slotName,
+        description,
+        type,
+        contextVariable,
+        defaultValue,
+        promotedBase,
+        choices: slotChoices(definition),
+        pluginManager: getEnv(node).pluginManager,
+        get value() {
+            return node[slotName];
+        },
+        get modified() {
+            return slotName in getSnapshot(node);
+        },
+        set(val) {
+            node.setSlot(slotName, val);
+        },
+    };
+}

package/esm/configuration/slotShape.d.ts

@@ -0,0 +1,12 @@
+import type { ConfigSlotDefinition } from './configurationSlot.ts';
+/**
+ * Whether a stored value could really be a value of this slot. An unusable value
+ * is dropped by the cascade, so the getter, the pin and the badge all fall back
+ * in lockstep.
+ *
+ * The `jexl:` check is the only place the subsystem handles a callback, and it
+ * handles it by refusing it — a hand-edited config or default store is untyped,
+ * and a callback string would otherwise reach a renderer as a literal value.
+ * DISPLAY_TYPE_DEFAULTS.md §"No callbacks".
+ */
+export declare function isUsableValue(def: ConfigSlotDefinition, value: unknown): boolean;