@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/configuration/promotableDefaults.js

@@ -0,0 +1,332 @@
+/**
+ * @module
+ * Session-wide "promoted defaults" for display-type config slots — the UI /
+ * control layer over the read-time cascade in `promotableResolve.ts`, whose
+ * `SlotResolution` every function here reads a field off. The session store
+ * (`get/setDisplayTypeDefault`) holds the promoted value.
+ */
+import { getSnapshot, isAlive } from '@jbrowse/mobx-state-tree';
+import { deepEqual } from '../util/deepEqual.js';
+import { getSession } from '../util/mstUtils.js';
+import { isObject } from '../util/objectUtils.js';
+import { openPromotableDisplays } from '../util/openDisplays.js';
+import { pluralize } from '../util/stringUtils.js';
+import { fullConfSnapshot } from './fullConfSnapshot.js';
+import { setConf } from './getConf.js';
+import { cascadeContextFor, isPromotableValue, resolveSlot, resolveSlotIn, storedSlotValue, } from './promotableResolve.js';
+import { promotableSlotNames } from './promotableSlots.js';
+import { isConfigurationModel } from './schemaTypes.js';
+/**
+ * #api core/configuration
+ * Whether this track has customized the slot (holds a non-default value of its
+ * own) rather than following the display type's default. The correct "reset to
+ * default" predicate for a promotable slot: comparing the resolved value to the
+ * base instead reads as at-default for a track merely *following* a non-base
+ * promoted default, so the reset control lights up on a no-op.
+ *
+ * `SLOT` is constrained the way `getConf`'s is. A pin or a reset over a slot
+ * name the schema does not declare is inert and silent — `resolveSlot` answers
+ * about nothing, so the control draws outline forever — and a widened `self`
+ * switches the check off (`HostChecksSlotNames`).
+ */
+export function isSlotCustomized(self, slot) {
+    return resolveSlot(self, slot).customized;
+}
+/**
+ * #api core/configuration
+ * The display's full config snapshot with every `promotable`
+ * slot overwritten by its resolved value in place. For building a worker payload:
+ * a promotable slot serializes as its raw inherit sentinel (`undefined`, since
+ * they're all `maybe*` types), which the worker can't interpret — it has no
+ * session to resolve against. This hands it concrete values instead, with no per-slot
+ * bookkeeping, so adding a promotable worker-consumed slot needs no rpcProps
+ * change and can't silently ship a sentinel. Main-thread only (the cascade
+ * consults the session). Display-only promotable slots the worker never reads
+ * (e.g. displayMode) are still excluded by the caller — resolving them here is a
+ * harmless no-op since they're dropped anyway.
+ *
+ * The return type is branded (`ResolvedConfigSnapshot`) so a payload builder can
+ * demand a snapshot that has been through here. The assertion below is the one
+ * place the brand is applied, and it sits on the line after the resolve.
+ */
+export function getConfigSnapshotWithPromotables(self) {
+    // the unresolved walk: this is the one place allowed to snapshot a promotable
+    // config, because `resolvePromotablesInto` is what resolves every such slot
+    const snap = fullConfSnapshot(self.configuration);
+    resolvePromotablesInto(cascadeContextFor(self), snap);
+    return snap;
+}
+/**
+ * The subsystem's one resolve loop: every promotable slot of `ctx.config`
+ * written into `snap` in place, returning the slots whose value came from a
+ * promoted default rather than from the config. Both serialization boundaries
+ * are this function over a different context — a display state node for the
+ * worker payload, a bare display config for the About dialog's copy.
+ */
+function resolvePromotablesInto(ctx, snap) {
+    const inherited = [];
+    for (const slot of promotableSlotNames(ctx.config)) {
+        const res = resolveSlotIn(ctx, slot);
+        snap[slot] = res.value;
+        if (res.inherited) {
+            inherited.push(slot);
+        }
+    }
+    return inherited;
+}
+/**
+ * #api core/configuration
+ * See {@link TrackConfigWithPromotables}.
+ */
+export function getTrackConfigWithPromotables(session, trackConfig) {
+    const config = structuredClone(getSnapshot(trackConfig));
+    const fromDisplayTypeDefaults = [];
+    const displayConfigs = trackConfig.displays;
+    const displaySnaps = config.displays;
+    // a config with no `displays` (an assembly, a plain customized About config)
+    // has no promotable slot to resolve — every one of them is display-level
+    if (Array.isArray(displayConfigs) && Array.isArray(displaySnaps)) {
+        for (const [i, displayConfig] of displayConfigs.entries()) {
+            const snap = displaySnaps[i];
+            if (!isConfigurationModel(displayConfig) || !isObject(snap)) {
+                continue;
+            }
+            // off the live config node, not off `snap` — the snapshot is what this
+            // function *writes*, so the key it resolves against shouldn't depend on
+            // what survived `stripDefault` on the way out. A display schema is
+            // `explicitlyTyped`, so the node always carries `type`; reading the
+            // snapshot's copy meant a display whose `type` ever stopped being emitted
+            // got skipped whole, and a skipped display is a copied config that
+            // silently isn't flattened. Same source `cascadeContextFor` reads.
+            const displayType = displayConfig.type;
+            if (typeof displayType === 'string') {
+                const ctx = { config: displayConfig, displayType, defaults: session };
+                for (const slot of resolvePromotablesInto(ctx, snap)) {
+                    fromDisplayTypeDefaults.push(`${displayType}.${slot}`);
+                }
+            }
+        }
+    }
+    return { config, fromDisplayTypeDefaults };
+}
+/**
+ * Open displays of this display's type, **one entry per track** — the set the
+ * pin's click writes. Module-internal (exercised by promotableDefaults.test.ts);
+ * not part of the public barrel.
+ *
+ * A track open in two views is two display *models* over one display *config* —
+ * `TrackConfigurationReference` resolves both through the hydration cache
+ * (ADR-031) — so the raw walk yields it twice. That is the ordinary case in a
+ * breakpoint-split view, which shows the same track in both halves and is one of
+ * the composite shapes `openPromotableDisplays` recurses into. The count reaches
+ * the user in the snackbar and the set gets written, and both
+ * go wrong on a duplicate: the toast offered to act on "2 tracks" over a single
+ * track, and the second write was a no-op against a node the first had already
+ * set.
+ *
+ * Keying on the config node rather than on `trackId` is what keeps this
+ * cast-free: the node is a member of `ResolvableDisplay`, and within one display
+ * type it is 1:1 with the track.
+ */
+export function openTracksOfType(self) {
+    // seeded with the clicked display so it is in the set by construction rather
+    // than by the walk happening to reach it. A display the walk misses used to
+    // cost nothing — the click wrote only the session default — and would now be
+    // the whole of the click. A duplicate from the walk lands on the same config
+    // key, so this adds no entry.
+    const byTrack = new Map([
+        [self.configuration, self],
+    ]);
+    for (const display of openPromotableDisplays(getSession(self))) {
+        if (display.type === self.type) {
+            byTrack.set(display.configuration, display);
+        }
+    }
+    return [...byTrack.values()];
+}
+/**
+ * Whether `value` is the current session default for `slot`. The live state the
+ * pin's filled/outline reflects — a session-wide fact, so it reads the raw
+ * promoted default rather than what this display resolves to (a customized track
+ * can be showing something else entirely). The named form of the comparison
+ * {@link makePin} inlines off a resolution it already holds. Module-internal
+ * (exercised by promotableDefaults.test.ts); not part of the public barrel.
+ */
+export function isPromotableDefault(self, slot, value) {
+    return deepEqual(resolveSlot(self, slot).promoted, value);
+}
+/**
+ * Write `value` into each display's own config for `slot`, so the track *holds*
+ * it rather than resolving it through the cascade. The pin's click, over every
+ * open track of the display type.
+ *
+ * **A track already showing `value` still has to be written**, which is why this
+ * compares the *stored* value and not the resolved one: a follower stores
+ * nothing and is showing `value` only by way of some promoted default, so
+ * skipping it would leave it to move again the moment that default changed.
+ * Comparing the stored value is also what lets a `jexl:` value answer "is this
+ * already what we would write?" without being evaluated.
+ *
+ * Skips dead displays, since the caller supplies the list and MST throws on any
+ * read or write to a destroyed node.
+ */
+export function applySlotToOpenTracks(displays, slot, value) {
+    for (const display of displays.filter(display => isAlive(display))) {
+        if (!deepEqual(storedSlotValue(display.configuration, slot), value)) {
+            setConf(display, slot, value);
+        }
+    }
+}
+/**
+ * The pin's click. Two branches, chosen by whether this value is *already* the
+ * display type's promoted default:
+ *
+ * - **It isn't** — write `value` into every open track of the type, and offer
+ *   the promotion as a snackbar action. Applying to the tracks in front of the
+ *   user is the click they mean far more often, so it is the one that needs no
+ *   second click; a default outlives the tracks it was set for and governs every
+ *   track of the type opened later, so it is the escalation (ADR-048).
+ * - **It is** — clear it, touching no track. The open tracks hold their values
+ *   because the user applied them, so reverting them here would make a toggle
+ *   into a bulk discard.
+ *
+ * The apply is one operation over *every* open track, not a labeled pair over
+ * the tracks that differ and the tracks that follow. Overwriting a customized
+ * track is the same write as filling in a follower, and the distinction the two
+ * actions drew is not one the user has any reason to see.
+ *
+ * The snackbar outlives the click that raised it, so the promotion closes over
+ * the display TYPE — a string — rather than reaching back through `self`. A
+ * promoted default is keyed by display type and governs tracks opened later, so
+ * it has nothing to do with the clicked display still being open; guarding on
+ * `self` instead meant a user who applied a value, closed the track, then took
+ * the offer got a silent no-op. What is still guarded is the session, which owns
+ * the map the write lands in. ADR-048 has the decisions this does not change:
+ * no track set and no apply/promote decision may be closed over.
+ */
+function applyPinClick(self, slot, value, isDefault) {
+    const session = getSession(self);
+    const displayType = self.type;
+    if (isDefault) {
+        session.setDisplayTypeDefault(displayType, slot, undefined);
+        session.notify('Cleared the default', 'info');
+    }
+    else {
+        const open = openTracksOfType(self);
+        applySlotToOpenTracks(open, slot, value);
+        session.notify(`Applied to ${open.length} open ${pluralize(open.length, 'track')}`, 'info', {
+            name: 'Set as the default',
+            onClick: () => {
+                if (isAlive(session)) {
+                    session.setDisplayTypeDefault(displayType, slot, value);
+                }
+            },
+        });
+    }
+}
+/**
+ * #api core/configuration
+ * The pin for one promotable slot: "apply this value to every open track of this
+ * display type", and — via the snackbar it raises — "keep it as the default for
+ * the ones opened later".
+ *
+ * `value` chooses between the subsystem's two meanings, which are otherwise
+ * identical:
+ *
+ * - **Give it** for a per-value pin — "make *arcs* the default" — independent of
+ *   what the track currently shows. Use on an always-visible pin so it can never
+ *   promote a meaningless value, and so two rows sharing one slot (arcs `'arc'`
+ *   vs read cloud `'cloud'`; sashimi `'down'` vs `'auto'`) stay independent.
+ * - **Omit it** for "whatever I'm showing", resolved through the cascade. Use for
+ *   a symmetric or continuous setting where no fixed on-value makes sense
+ *   (wiggle point size, arc line width, `mismatchAlpha`).
+ *
+ * One function with an optional argument, rather than the two exported builders
+ * it replaces — a per-value one and a `…CurrentValue…` one, the second of which
+ * was exactly the first applied to `resolveSlot(self, slot).value`. The pair was
+ * one function plus a doc section explaining which name to reach for; omitting
+ * the argument now says what the longer name said.
+ */
+export function makePin(self, slot, ...value) {
+    // One walk of the cascade feeds both halves. The value-omitted form's
+    // on-value IS the settled value, and `active` compares against the raw
+    // promoted default of that same resolution — taking the two from separate
+    // `resolveSlot` calls read as though they could disagree, and cost a second
+    // walk per pin on a menu that builds a dozen of them.
+    const res = resolveSlot(self, slot);
+    // rest-tuple, not `value?: unknown`: the promote-current case has to stay
+    // distinguishable from an explicit `undefined` rather than collapsing into it.
+    const onValue = value.length ? value[0] : res.value;
+    // The value-omitted form can't fail this — the cascade only ever settles on a
+    // usable value — so this is entirely about a caller-supplied one. An on-value
+    // the cascade would refuse builds a pin that is inert *and* silent: clicking
+    // it stores a key `resolveSlotIn` then drops, so no track moves and the pin
+    // draws outline forever. The reachable mistakes are the inherit sentinel
+    // itself (`makePin(self, slot, undefined)`, which additionally reads as the
+    // default the moment nothing is promoted, so it draws *filled* and does
+    // nothing), a non-finite number, and a value outside a `maybeStringEnum`'s
+    // vocabulary. The `value` parameter's type catches those wherever the slot
+    // resolves to a real value type; what is left for runtime is the slot whose
+    // schema widened to `any` — a `frozen`/`maybeFrozen` one by design, or a
+    // display whose config model was not narrowed. Same bargain `ConfigSlot`
+    // strikes over `promotedBase`, which is this gate at the other end.
+    if (!isPromotableValue(self.configuration, slot, onValue)) {
+        throw new Error(`cannot pin ${JSON.stringify(onValue)} as the default for config slot "${slot}": the cascade refuses it, so the pin could never light up`);
+    }
+    // `isPromotableDefault` off the resolution already in hand — same comparison,
+    // same `deepEqual`, no second walk.
+    const active = deepEqual(res.promoted, onValue);
+    return {
+        slot,
+        onValue,
+        active,
+        toggle: () => {
+            applyPinClick(self, slot, onValue, active);
+        },
+    };
+}
+/**
+ * #api core/configuration
+ * Effective differences a track following the default inherits from session-wide
+ * defaults, one per promotable slot whose inherited value differs from its schema
+ * default. Drives the track-selector "affected by a session default" badge.
+ */
+export function getDisplayTypeDefaultChanges(self) {
+    const changes = [];
+    for (const slot of promotableSlotNames(self.configuration)) {
+        const res = resolveSlot(self, slot);
+        if (res.inherited) {
+            changes.push({
+                path: [slot],
+                // a cascade value is `unknown` here but JSON by contract — it has to
+                // survive `postMessage` to a worker. Asserted per field rather than on
+                // the whole entry, so `path` stays type-checked.
+                from: res.base,
+                to: res.value,
+            });
+        }
+    }
+    return changes;
+}
+/**
+ * #api core/configuration
+ * Clear the named promoted defaults for this display type, so every track
+ * following one reverts to its own config value. Backs the badge's "clear
+ * session default" action, which passes the slots it actually listed
+ * (`getDisplayTypeDefaultChanges`).
+ *
+ * **`slots` is required, and an all-slots default is not the convenience it
+ * looks like.** It reaches further than any list a dialog can have shown: a
+ * promoted default the track *customized* over, or one promoted to a value
+ * equal to `promotedBase`, is `inherited: false` and so appears in no row, yet
+ * still governs sibling tracks — so clearing it from a dialog that never showed
+ * it moves tracks other than the one whose badge was clicked. Clearing every
+ * promoted default at once is a preferences-scope action, and Preferences →
+ * "Reset to defaults" is where it lives (`clearPreferenceOverrides`).
+ */
+export function clearPromotedDefaults(self, slots) {
+    const session = getSession(self);
+    for (const slot of slots) {
+        session.setDisplayTypeDefault(self.type, slot, undefined);
+    }
+}

package/esm/configuration/promotablePin.d.ts

@@ -0,0 +1,55 @@
+/**
+ * #api core/configuration
+ * The "apply this to every open track of this type" affordance on a menu row —
+ * the trailing `PushPin`, bundled so the row consumes it as one prop. Built by
+ * {@link makePin}.
+ *
+ * `active` = this value is currently the session default (a filled pin), which
+ * is the state, not the click. `toggle` **applies the value to every open track
+ * of the display type** and raises a snackbar whose one action promotes it to
+ * the display type's default; on an already-promoted value it clears that
+ * default instead, touching no track (see `applyPinClick`).
+ *
+ * **`toggle` rather than an `apply`/`clear` pair**, which was tried and dropped:
+ * the sole renderer is a MUI `ToggleButton` whose `onChange` means exactly
+ * "flip", so splitting it adds a member *and* a branch at the one call site that
+ * never needed one. `active` is already public for a caller that wants to state a
+ * direction. (The house preference for explicit setters over toggles is about MST
+ * actions, where a toggle destroys the ability to set a known state; nothing here
+ * stores a value.)
+ *
+ * Lives here, alone and with no imports, rather than beside `makePin` in
+ * `promotableDefaults.ts`: the menu types describe a pin without building one,
+ * and `MenuTypes.ts` taking this one interface from that module gave a
+ * React-free type file a type closure of 374 files. See
+ * `agent-docs/ideas/barrels-block-extraction.md` and `scripts/moduleClosure.ts`.
+ */
+export interface Pin {
+    /**
+     * The promotable slot this pin promotes a value of. Nothing in the UI reads
+     * it — a pin renders from `active`, `onValue` and the toggle. It is here so a
+     * *built menu* can be asked which promotable slots it offers a pin for, which
+     * is the only way that question has an answer: declaring `promotedBase` is a
+     * schema fact and the pin is a menu fact, and a display that inherits the slot
+     * but never builds a row has a slot nothing can ever promote, silently
+     * (`promotableSlotsWithoutPin`, guarded by
+     * `products/jbrowse-web/src/tests/PromotablePinCoverage.test.ts`).
+     */
+    slot: string;
+    /**
+     * The value `toggle` promotes — the on-value {@link makePin} was given, or the
+     * track's current resolved value for the value-omitted form.
+     *
+     * `PinAdornment` words itself from this, and has to: a **boolean** on-value
+     * promotes a *state*, so a row whose label names the setting rather than a
+     * value ("Show legend") gets a pin that promotes hiding the legend as often as
+     * showing it. Every other on-value IS what the row's label says — a radio
+     * option, a slider's current size — so those keep the value-shaped copy.
+     *
+     * Required, like `slot`: a pin that cannot say what it promotes is what let
+     * that copy state the opposite of what the click does.
+     */
+    onValue: unknown;
+    active: boolean;
+    toggle: () => void;
+}

package/esm/configuration/promotableResolve.d.ts

@@ -0,0 +1,108 @@
+import type { AnyConfigurationModel } from './types.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Everything the cascade needs to read a promotable slot: the display type it
+ * keys the session-wide default on, and the config holding the track's own
+ * value. Every entry point takes this — `resolveConf`, the control builders,
+ * the worker snapshot, the badge diff — so each can take a display state node
+ * directly rather than through a cast.
+ *
+ * Read-only, and there is no write-capable variant. A `PromotableDisplay` used
+ * to exist for the one member the subsystem wrote (`setIgnorePromotedDefaults`,
+ * the received-session opt-out); with that flag gone the subsystem writes
+ * nothing to a display but a config slot, which `setConf` reaches through
+ * `configuration`.
+ *
+ * **`CONF` is a parameter rather than always `AnyConfigurationModel` because
+ * intersecting is not narrowing.** A caller wanting the cascade's members *and*
+ * a concrete schema — a mixin casting to reach its host — writes
+ * `ResolvableDisplay<XConfigModel>`. Spelling it
+ * `ResolvableDisplay & { configuration: XConfigModel }` instead reads identical
+ * and silently does the opposite: the intersected `configuration` is
+ * `AnyConfigurationModel & XConfigModel`, `ConfigurationSchemaForModel` infers
+ * the widened brand off it, and every slot name typechecks again. Two mixins
+ * shipped that spelling and only a sabotage found it.
+ */
+export type ResolvableDisplay<CONF extends AnyConfigurationModel = AnyConfigurationModel> = IStateTreeNode & {
+    type: string;
+    configuration: CONF;
+};
+/**
+ * Where the session-wide tier of the cascade is read from. Narrowed to the one
+ * method so the resolver doesn't depend on the whole session type — and exported
+ * for the same reason, so an entry point taking the store directly
+ * (`getTrackConfigWithPromotables`) can ask for what it uses instead of for a
+ * whole session a test then has to fake.
+ */
+export interface PromotedDefaultStore {
+    getDisplayTypeDefault: (displayType: string, slot: string) => unknown;
+}
+/**
+ * The cascade's inputs, stated directly rather than read off a display state
+ * node. `ResolvableDisplay` is the usual way to supply them (see
+ * `cascadeContextFor`), but nothing here *needs* a state node: the About
+ * dialog's "Copy config" resolves a track's display configs directly, which is
+ * what lets it answer "what would this render as" for a track that was never
+ * opened. Reaching for the open display instead buys nothing — its
+ * `configuration` is the same node, and its `type` is that config's own.
+ */
+export interface CascadeContext {
+    config: AnyConfigurationModel;
+    displayType: string;
+    defaults: PromotedDefaultStore;
+}
+export declare function cascadeContextFor(self: ResolvableDisplay): CascadeContext;
+/**
+ * What the slot literally holds, unevaluated — a stray `jexl:` string yields the
+ * raw string rather than running it. Both callers ask "is the slot set, and to
+ * what kind of thing?", which has to be answerable with no feature context.
+ *
+ * Deliberately not `readConfObject`: for a promotable slot this is the whole
+ * stored read, and both of that reader's extra behaviors are unwanted here — it
+ * evaluates a `jexl:` string (which `isUsableValue` refuses anyway) and it
+ * snapshots an MST-node value, which a `maybe*` slot never holds.
+ */
+export declare function storedSlotValue(config: AnyConfigurationModel, slot: string): unknown;
+/**
+ * Whether `value` could actually become this slot's promoted default — the same
+ * `isUsableValue` gate the cascade puts both tiers through, asked ahead of time
+ * about a value a caller is about to offer as a pin's on-value.
+ *
+ * Exists because a pin built over a value the gate refuses is inert in a way
+ * nothing reports: `applyPinClick` writes it to the session store happily,
+ * `resolveSlotIn` then drops it and every track keeps resolving to the tier
+ * below, and `isPromotableDefault` compares the *raw* stored value, so the pin
+ * draws outline forever while a dead key sits in the user's localStorage. See
+ * `makePin`, which is the one caller.
+ */
+export declare function isPromotableValue(config: AnyConfigurationModel, slot: string, value: unknown): boolean;
+/**
+ * The outcome of walking the cascade for one slot: the two tiers that fed it,
+ * whether the track customized it, and the settled value.
+ *
+ * There is deliberately **no callback case** — a `jexl:` value fails
+ * `isUsableValue` like any other unusable value and degrades to the inherited
+ * one, so `value` is always readable. See `isUsableValue`.
+ */
+export interface SlotResolution {
+    /** value a track following the default shows with nothing promoted (CSS `initial`) */
+    base: unknown;
+    /** the raw session-wide promoted default, if any */
+    promoted: unknown;
+    /** track holds its own value rather than following the default */
+    customized: boolean;
+    /**
+     * the value came from the session-wide tier — the track follows the default
+     * *and* that default moves it off `base`. The "this display picked something
+     * up from the session" predicate, for the badge diff and the About dialog's
+     * copy-config note. A field rather than a `!customized && !deepEqual(value,
+     * base)` at each call site, because getting either half wrong is silent:
+     * dropping `customized` reports a customized track as inheriting, dropping
+     * the `base` compare flags a promoted default that changes nothing.
+     */
+    inherited: boolean;
+    /** the final cascaded value (never the `undefined` inherit sentinel) */
+    value: unknown;
+}
+export declare function resolveSlot(self: ResolvableDisplay, slot: string): SlotResolution;
+export declare function resolveSlotIn(ctx: CascadeContext, slot: string): SlotResolution;

package/esm/configuration/promotableResolve.js

@@ -0,0 +1,117 @@
+/**
+ * @module
+ * The read-time resolver behind `promotable` config slots — a small CSS cascade
+ * for one slot: the track's own set value -> the session-wide default for its
+ * display type -> the slot's `promotedBase`. `resolveSlotIn` is the whole of it;
+ * `resolveConf` and the control builders in `promotableDefaults.ts` each read a
+ * field off the `SlotResolution` it returns.
+ *
+ * Mechanism: `agent-docs/reference/DISPLAY_TYPE_DEFAULTS.md`. Two decisions this
+ * file rests on: resolution is named at its call sites rather than folded into
+ * `getConf` (ADR-046), and unset is the only inherit sentinel — so declaring
+ * `promotedBase` is what makes a slot promotable (ADR-047, enforced by
+ * `ConfigSlot`).
+ *
+ * Every comparison against a promoted or base value is `deepEqual`, never `===`:
+ * an object-valued slot (`maybeFrozen`, e.g. alignments `colorBy`) reconstructs a
+ * fresh value out of MST that is never `===` its stored twin, so `===` would read
+ * it as permanently differing and no pin would ever light up.
+ *
+ * The gate a candidate value passes to count at all is `isUsableValue`, in
+ * `slotShape.ts` — shared with `ConfigSlot`, which applies it to `promotedBase`
+ * at construction so the tier this file falls back to is usable by construction.
+ */
+import { deepEqual } from '../util/deepEqual.js';
+import { getSession } from '../util/mstUtils.js';
+import { getSlotDefinition } from './slotFacade.js';
+import { isUsableValue } from './slotShape.js';
+export function cascadeContextFor(self) {
+    return {
+        config: self.configuration,
+        displayType: self.type,
+        defaults: getSession(self),
+    };
+}
+/**
+ * What the slot literally holds, unevaluated — a stray `jexl:` string yields the
+ * raw string rather than running it. Both callers ask "is the slot set, and to
+ * what kind of thing?", which has to be answerable with no feature context.
+ *
+ * Deliberately not `readConfObject`: for a promotable slot this is the whole
+ * stored read, and both of that reader's extra behaviors are unwanted here — it
+ * evaluates a `jexl:` string (which `isUsableValue` refuses anyway) and it
+ * snapshots an MST-node value, which a `maybe*` slot never holds.
+ */
+export function storedSlotValue(config, slot) {
+    return config[slot];
+}
+/**
+ * Whether `value` could actually become this slot's promoted default — the same
+ * `isUsableValue` gate the cascade puts both tiers through, asked ahead of time
+ * about a value a caller is about to offer as a pin's on-value.
+ *
+ * Exists because a pin built over a value the gate refuses is inert in a way
+ * nothing reports: `applyPinClick` writes it to the session store happily,
+ * `resolveSlotIn` then drops it and every track keeps resolving to the tier
+ * below, and `isPromotableDefault` compares the *raw* stored value, so the pin
+ * draws outline forever while a dead key sits in the user's localStorage. See
+ * `makePin`, which is the one caller.
+ */
+export function isPromotableValue(config, slot, value) {
+    return isUsableValue(getSlotDefinition(config, slot), value);
+}
+// The whole three-tier cascade for one slot, in one place. `resolveConf` is the
+// public reader over it, and the control builders in `promotableDefaults.ts`
+// read a field off it.
+export function resolveSlot(self, slot) {
+    return resolveSlotIn(cascadeContextFor(self), slot);
+}
+// The cascade over explicit inputs. `resolveSlot` is the display-state spelling
+// of this and the one nearly every consumer wants; the direct form exists for
+// the config-only path (a track that isn't open has no display state — see
+// `CascadeContext`).
+export function resolveSlotIn(ctx, slot) {
+    const def = getSlotDefinition(ctx.config, slot);
+    // A plain slot would otherwise resolve silently wrong here — with no
+    // `promotedBase` every tier collapses to `undefined` — and, through a control
+    // builder, write a promoted default nothing ever reads. `getSlotDefinition`
+    // already throws on a slot name that doesn't exist at all.
+    //
+    // Declaring `promotedBase` is what makes a slot promotable, so its absence is
+    // the whole test; there is no separate flag that could disagree with it.
+    if (def.promotedBase === undefined) {
+        throw new Error(`config slot "${slot}" is not promotable`);
+    }
+    // the slot's CSS `initial`
+    const base = def.promotedBase;
+    // a session-wide fact, and `isPromotableDefault` (the pin's filled/outline
+    // state) reports on the session, not on one display's view of it
+    const promoted = ctx.defaults.getDisplayTypeDefault(ctx.displayType, slot);
+    const own = storedSlotValue(ctx.config, slot);
+    // A track is customized exactly when it holds a *usable* value — being unset
+    // is the inherit sentinel, so "set to something the slot could hold" is the
+    // whole test. Routing `own` through the same gate as a promoted default is
+    // what makes a malformed or stale own value (a saved `colorBy` naming a
+    // since-removed scheme) read as not-customized and degrade in lockstep,
+    // instead of reaching a consumer that trusts every value it sees.
+    const customized = isUsableValue(def, own);
+    const inheritedValue = isUsableValue(def, promoted) ? promoted : base;
+    // A customized value wins unconditionally, which is what makes the share bake
+    // sufficient on its own: a baked value lands in the track's config, so the
+    // recipient reads it as customized and their own promoted default never gets
+    // consulted. The one case a bake cannot cover is the sender sitting at `base`
+    // while the recipient has promoted something — nothing is baked (the value
+    // *is* base, and `stripDefault` drops it from the snapshot), so the recipient
+    // resolves it from their own cascade. That is accepted: a promoted default is
+    // personal and local, exactly like the theme a session is viewed in, and the
+    // alternative was a per-display `ignorePromotedDefaults` flag that also
+    // detached received tracks from the recipient's own pins for good.
+    const value = customized ? own : inheritedValue;
+    return {
+        base,
+        customized,
+        promoted,
+        inherited: !customized && !deepEqual(value, base),
+        value,
+    };
+}

package/esm/configuration/promotableSlots.d.ts

@@ -0,0 +1,12 @@
+import type { AnyConfigurationModel } from './types.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * 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 declare function promotableSlotNames(configOrType: AnyConfigurationModel | IAnyType): ReadonlySet<string>;