@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/configuration/formatDetailsConfigSchema.js

@@ -0,0 +1,90 @@
+import { ConfigurationSchema } from './configurationSchema.js';
+/**
+ * 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 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 function FormatDetailsConfigSchemaFactory() {
+    return ConfigurationSchema('FormatDetails', {
+        /**
+         * #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
+         */
+        feature: {
+            type: 'frozen',
+            description: 'adds extra fields to the feature details',
+            defaultValue: {},
+            contextVariable: ['feature'],
+        },
+        /**
+         * #slot formatDetails.subfeatures
+         * the same, applied to each subfeature down to `depth`
+         */
+        subfeatures: {
+            type: 'frozen',
+            description: 'adds extra fields to the subfeatures of a feature',
+            defaultValue: {},
+            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
+         */
+        depth: {
+            // `maybeNumber`, so unset is expressible. With a `defaultValue` the two
+            // tiers cannot be told apart -- a plain number slot reads back its own
+            // default, so "the track set 2" and "the track set nothing" are the same
+            // read, and the session-wide value can never apply to a track. The
+            // resolved default is DEFAULT_FORMAT_DETAILS_DEPTH, applied by the reader
+            type: 'maybeNumber',
+            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
+         */
+        maxDepth: {
+            // `maybeNumber` for the same reason as `depth`, and here unset is also
+            // the meaningful value: no limit at all
+            type: 'maybeNumber',
+            description: 'hide subfeatures nested deeper than this, default no limit',
+        },
+    });
+}

package/esm/configuration/fullConfSnapshot.d.ts

@@ -0,0 +1,28 @@
+import type { AnyConfigurationModel } from './types.ts';
+/**
+ * Plain-object snapshot of a configuration model including ALL values, even
+ * defaults. Unlike `getSnapshot()`, which strips a slot sitting at its default
+ * via `types.stripDefault`, this returns every slot's current value, so the
+ * result is a self-contained config object an RPC worker can read with no
+ * schema. JEXL callback slots keep their raw `"jexl:..."` string for the worker
+ * to evaluate per-feature.
+ *
+ * **Why this isn't exported from `@jbrowse/core/configuration`.** It was
+ * (as `getConfSnapshot`), and being reachable was the hazard. A promotable slot
+ * resolves against the session at read time, so snapshotting one raw ships the
+ * bare `undefined` inherit sentinel to a worker with no session to resolve it
+ * against — and every display in the repo now has promotable slots. The public
+ * form used to defend itself by *throwing* on such a config, which meant the
+ * obvious spelling in a new `rpcProps()` failed at runtime, on the first fetch,
+ * in whichever product exercised that display. Off the barrel, the same mistake
+ * is an unresolved import: it can't be written at all, and
+ * `getConfigSnapshotWithPromotables(display)` is the one way across the boundary.
+ * So this is the shared walker those resolvers are built on, not an entry point.
+ *
+ * The nested-schema guard below is the part of that defense still worth
+ * enforcing at runtime, since no import can express it.
+ *
+ * Note: only handles slots and direct sub-configuration models. Arrays or maps
+ * of sub-schemas are silently dropped — nothing has needed them.
+ */
+export declare function fullConfSnapshot(confObject: AnyConfigurationModel): Record<string, unknown>;

package/esm/configuration/fullConfSnapshot.js

@@ -0,0 +1,66 @@
+import { getSnapshot, isArrayType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { promotableSlotNames } from './promotableSlots.js';
+import { getConfigurationSchemaDefinition } from './schemaRegistry.js';
+import { isConfigurationModel, isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+/**
+ * Plain-object snapshot of a configuration model including ALL values, even
+ * defaults. Unlike `getSnapshot()`, which strips a slot sitting at its default
+ * via `types.stripDefault`, this returns every slot's current value, so the
+ * result is a self-contained config object an RPC worker can read with no
+ * schema. JEXL callback slots keep their raw `"jexl:..."` string for the worker
+ * to evaluate per-feature.
+ *
+ * **Why this isn't exported from `@jbrowse/core/configuration`.** It was
+ * (as `getConfSnapshot`), and being reachable was the hazard. A promotable slot
+ * resolves against the session at read time, so snapshotting one raw ships the
+ * bare `undefined` inherit sentinel to a worker with no session to resolve it
+ * against — and every display in the repo now has promotable slots. The public
+ * form used to defend itself by *throwing* on such a config, which meant the
+ * obvious spelling in a new `rpcProps()` failed at runtime, on the first fetch,
+ * in whichever product exercised that display. Off the barrel, the same mistake
+ * is an unresolved import: it can't be written at all, and
+ * `getConfigSnapshotWithPromotables(display)` is the one way across the boundary.
+ * So this is the shared walker those resolvers are built on, not an entry point.
+ *
+ * The nested-schema guard below is the part of that defense still worth
+ * enforcing at runtime, since no import can express it.
+ *
+ * Note: only handles slots and direct sub-configuration models. Arrays or maps
+ * of sub-schemas are silently dropped — nothing has needed them.
+ */
+export function fullConfSnapshot(confObject) {
+    const result = {};
+    const table = getConfigurationSchemaDefinition(confObject);
+    for (const [key, def] of Object.entries(table ?? {})) {
+        const v = confObject[key];
+        if (isSlotDefinitionEntry(def)) {
+            // jexl callback strings pass through raw for per-feature evaluation in
+            // the worker.
+            result[key] = isStateTreeNode(v) ? getSnapshot(v) : v;
+        }
+        else if (isConfigurationSchemaType(def) &&
+            !isArrayType(def) &&
+            !isMapType(def) &&
+            isConfigurationModel(v)) {
+            // a direct sub-configuration recurses. Arrays/maps of sub-schemas are
+            // dropped: their MST node also reports as a config model, but the
+            // array/map type carries no registered slot table, so recursing would
+            // emit a meaningless `{}` (a type-confusion hazard for a consumer
+            // expecting the array). Constants are skipped entirely.
+            assertNoPromotableSlots(v);
+            result[key] = fullConfSnapshot(v);
+        }
+    }
+    return result;
+}
+// A promotable slot is only ever resolvable at a config's own top level — the
+// resolver walks that one slot table (`promotableSlotNames` / `getSlotDefinition`)
+// and never descends. So one declared inside a *nested* schema would resolve
+// nowhere and serialize as its bare inherit sentinel, with no import to get wrong
+// and no symptom until a worker read the sentinel. Fail at the snapshot instead.
+function assertNoPromotableSlots(confObject) {
+    const promotable = promotableSlotNames(confObject);
+    if (promotable.size > 0) {
+        throw new Error(`nested config schema declares promotable slots (${[...promotable].join(', ')}): the cascade only resolves a display config's own top-level slots, so these would serialize as the bare inherit sentinel. Declare them on the display's own schema instead.`);
+    }
+}

package/esm/configuration/getConf.d.ts

@@ -0,0 +1,88 @@
+import type { ResolvableDisplay } from './promotableResolve.ts';
+import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue, ConfigurationSlotValueResolved } from './types.ts';
+/**
+ * #api core/configuration
+ * Reads a configuration value from a state model that has a `.configuration`
+ * member (a track or display state model). For a raw configuration model, use
+ * `readConfObject` instead.
+ *
+ * **This is exactly `readConfObject(model.configuration, path)`** — sugar for
+ * the `.configuration` hop, and nothing more. The two readers carry the same
+ * slot-name check, so reaching for the other one does not get a typo past tsc.
+ * It does not consult the session and has no per-slot behavior; what you read is
+ * what the track stores.
+ *
+ * A `promotable` slot read this way therefore yields the raw stored value,
+ * `undefined` included — that `undefined` is the cascade's inherit sentinel, and
+ * `resolveConf` is what turns it into a real value. The read type keeps the
+ * `undefined` on purpose, so reaching for the wrong reader is a compile error
+ * rather than a silent one.
+ *
+ * @param model - object containing a 'configuration' member
+ * @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 getConf(model: {
+    configuration: AnyConfigurationModel;
+}): AnyConfigurationSnapshot;
+export declare function getConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+    configuration: CONFMODEL;
+}, slotPath: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : any;
+/**
+ * #api core/configuration
+ * Reads a `promotable` slot through the display-type-default cascade — the
+ * track's own value, else the session-wide promoted default for this display
+ * type, else the slot's `promotedBase`. Always yields a real value, never the
+ * `undefined` inherit sentinel, so a display's value getter is
+ * `get displayMode(): DisplayMode { return resolveConf(self, 'displayMode') }`
+ * with no post-guard and no cast.
+ *
+ * Separate from `getConf` rather than folded into it, deliberately: resolution
+ * consults the session, so it is main-thread only and throws on a detached node.
+ * Folding it in was built and reverted — ADR-046.
+ *
+ * Throws if `slot` isn't promotable — the cascade has nothing to say about a
+ * plain slot, and `getConf` is what you want there.
+ *
+ * Takes no jexl `args`, unlike `getConf`: a promotable slot cannot hold a
+ * callback (see `SlotResolution`), so there is no per-feature context to supply.
+ *
+ * @param model - the display state model (needs the session + display type)
+ * @param slot - the promotable slot to resolve
+ */
+export declare function resolveConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: ResolvableDisplay<CONFMODEL>, slot: SLOT): ConfigurationSlotValueResolved<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
+/**
+ * #api core/configuration
+ * Write counterpart to `getConf`: sets a slot on a state model that has a
+ * `.configuration` member (a track or display state model).
+ *
+ * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
+ * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
+ * unknown slot name is a compile error. `setSlot` itself stays untyped on
+ * purpose — the config editor's slot facade routes dynamic slot names through
+ * it (`configurationSchema.ts`) — and guards the name at runtime instead
+ * (ADR-052), so a misspelled write is diagnosed one way or the other.
+ *
+ * **The read is the half with no diagnostic at all.** `getConf` for a name the
+ * schema doesn't declare returns `undefined` and reports nothing, at any layer,
+ * so the slot keeps reading as its default forever. Which makes the
+ * compile-time constraint worth keeping *reachable*: it is only as good as the
+ * schema of the holder handed in, and a holder widened to
+ * `AnyConfigurationModel` switches it off entirely — the trap a mixin casting
+ * to reach its host walks into. Every such cast names a concrete schema instead
+ * (`ConfigModelForFields`, or the base schema when the slot is the base's), and
+ * `HostChecksSlotNames` pins each one.
+ *
+ * A wrong *value* type still throws at runtime (MST type-checks the assignment)
+ * rather than at compile time. `value` is deliberately `unknown` because the
+ * inherit sentinel (`undefined`/`null`) is a legitimate write on every
+ * promotable slot, which the declared slot value type doesn't include.
+ *
+ * @param model - object containing a 'configuration' member
+ * @param slotName - the slot to write
+ * @param value - the new value
+ */
+export declare function setConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+    configuration: CONFMODEL;
+}, slotName: SLOT, value: unknown): void;

package/esm/configuration/getConf.js

@@ -0,0 +1,74 @@
+import { resolveSlot } from './promotableResolve.js';
+import { readConfObject } from './readConfObject.js';
+export function getConf(model, slotPath, args = {}) {
+    return readConfObject(model.configuration, slotPath, args);
+}
+/**
+ * #api core/configuration
+ * Reads a `promotable` slot through the display-type-default cascade — the
+ * track's own value, else the session-wide promoted default for this display
+ * type, else the slot's `promotedBase`. Always yields a real value, never the
+ * `undefined` inherit sentinel, so a display's value getter is
+ * `get displayMode(): DisplayMode { return resolveConf(self, 'displayMode') }`
+ * with no post-guard and no cast.
+ *
+ * Separate from `getConf` rather than folded into it, deliberately: resolution
+ * consults the session, so it is main-thread only and throws on a detached node.
+ * Folding it in was built and reverted — ADR-046.
+ *
+ * Throws if `slot` isn't promotable — the cascade has nothing to say about a
+ * plain slot, and `getConf` is what you want there.
+ *
+ * Takes no jexl `args`, unlike `getConf`: a promotable slot cannot hold a
+ * callback (see `SlotResolution`), so there is no per-feature context to supply.
+ *
+ * @param model - the display state model (needs the session + display type)
+ * @param slot - the promotable slot to resolve
+ */
+export function resolveConf(
+// the display state node itself, not just its `.configuration`: the cascade
+// keys the session-wide tier on `type` and reaches the session through the
+// node. Asking for that shape is what keeps this cast-free — hand it a bare
+// config holder and tsc names the missing members instead of failing at the
+// first read. `ResolvableDisplay<CONFMODEL>`, never
+// `ResolvableDisplay & { configuration: CONFMODEL }`: the intersection
+// re-widens the slot names to `string` (see `ResolvableDisplay`)
+model, slot) {
+    // the resolution is `unknown`, which the declared return type can't infer
+    return resolveSlot(model, slot).value;
+}
+/**
+ * #api core/configuration
+ * Write counterpart to `getConf`: sets a slot on a state model that has a
+ * `.configuration` member (a track or display state model).
+ *
+ * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
+ * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
+ * unknown slot name is a compile error. `setSlot` itself stays untyped on
+ * purpose — the config editor's slot facade routes dynamic slot names through
+ * it (`configurationSchema.ts`) — and guards the name at runtime instead
+ * (ADR-052), so a misspelled write is diagnosed one way or the other.
+ *
+ * **The read is the half with no diagnostic at all.** `getConf` for a name the
+ * schema doesn't declare returns `undefined` and reports nothing, at any layer,
+ * so the slot keeps reading as its default forever. Which makes the
+ * compile-time constraint worth keeping *reachable*: it is only as good as the
+ * schema of the holder handed in, and a holder widened to
+ * `AnyConfigurationModel` switches it off entirely — the trap a mixin casting
+ * to reach its host walks into. Every such cast names a concrete schema instead
+ * (`ConfigModelForFields`, or the base schema when the slot is the base's), and
+ * `HostChecksSlotNames` pins each one.
+ *
+ * A wrong *value* type still throws at runtime (MST type-checks the assignment)
+ * rather than at compile time. `value` is deliberately `unknown` because the
+ * inherit sentinel (`undefined`/`null`) is a legitimate write on every
+ * promotable slot, which the declared slot value type doesn't include.
+ *
+ * @param model - object containing a 'configuration' member
+ * @param slotName - the slot to write
+ * @param value - the new value
+ */
+export function setConf(model, slotName, value) {
+    // eslint-disable-next-line no-restricted-syntax -- this is setConf
+    model.configuration.setSlot(slotName, value);
+}

package/esm/configuration/index.d.ts

@@ -1,3 +1,19 @@
-export { ConfigurationReference, ConfigurationSchema, } from './configurationSchema.ts';
-export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSlot, AnyConfigurationSlotType, } from './types.ts';
-export * from './util.ts';
+export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.ts';
+export type { ConfigurationSchemaDefinition } from './configurationSchema.ts';
+export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, } from './types.ts';
+export { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.ts';
+export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.ts';
+export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.ts';
+export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.ts';
+export { mergeFormatCallbacks } from './mergeFormatCallbacks.ts';
+export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.ts';
+export { getConf, resolveConf, setConf } from './getConf.ts';
+export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.ts';
+export { tabixIndexFields } from './tabixIndexFields.ts';
+export { evaluateJexl, isCallbackValue } from './slotValueUtils.ts';
+export { toCallbackValue, toFixedValue } from './configurationSlot.ts';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.ts';
+export type { SlotFacade } from './slotFacade.ts';
+export type { ResolvableDisplay } from './promotableResolve.ts';
+export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.ts';
+export type { Pin, ResolvedConfigSnapshot, TrackConfigWithPromotables, } from './promotableDefaults.ts';

package/esm/configuration/index.js

@@ -1,2 +1,19 @@
-export { ConfigurationReference, ConfigurationSchema, } from "./configurationSchema.js";
-export * from "./util.js";
+export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.js';
+export { getConfigurationSchemaDefinition, 
+// exported for scripts/generateConfigManifest.ts, which needs the
+// preProcessSnapshot off a schema whose pluggable type does not expose one —
+// TextSearchAdapterType, where the shorthand is nonetheless the documented
+// way to write the config
+getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
+export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.js';
+export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.js';
+export { mergeFormatCallbacks } from './mergeFormatCallbacks.js';
+export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.js';
+export { getConf, resolveConf, setConf } from './getConf.js';
+export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.js';
+export { tabixIndexFields } from './tabixIndexFields.js';
+export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
+export { toCallbackValue, toFixedValue } from './configurationSlot.js';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.js';
+export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.js';

package/esm/configuration/mergeFormatCallbacks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Combine the tiers of an object-returning format callback (`formatDetails` on
+ * the feature-details panel, `formatAbout` on the About dialog), earliest
+ * first, so a track's object is spread over the session-wide one and can
+ * override individual keys the global callback added.
+ *
+ * A tier that isn't a plain object is dropped rather than spread. The classic
+ * slip is `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant;
+ * spreading the resulting string produced attribute rows keyed `0`, `1`, `2`,
+ * and an array does the same, which is why `isObject` alone isn't the gate.
+ *
+ * `null` and `undefined` *values* survive on purpose: they are how a callback
+ * hides a field, and the panels filter them out downstream.
+ */
+export declare function mergeFormatCallbacks(...tiers: unknown[]): Record<string, unknown>;

package/esm/configuration/mergeFormatCallbacks.js

@@ -0,0 +1,24 @@
+import { isObject } from '../util/objectUtils.js';
+/**
+ * Combine the tiers of an object-returning format callback (`formatDetails` on
+ * the feature-details panel, `formatAbout` on the About dialog), earliest
+ * first, so a track's object is spread over the session-wide one and can
+ * override individual keys the global callback added.
+ *
+ * A tier that isn't a plain object is dropped rather than spread. The classic
+ * slip is `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant;
+ * spreading the resulting string produced attribute rows keyed `0`, `1`, `2`,
+ * and an array does the same, which is why `isObject` alone isn't the gate.
+ *
+ * `null` and `undefined` *values* survive on purpose: they are how a callback
+ * hides a field, and the panels filter them out downstream.
+ */
+export function mergeFormatCallbacks(...tiers) {
+    const out = {};
+    for (const tier of tiers) {
+        if (isObject(tier) && !Array.isArray(tier)) {
+            Object.assign(out, tier);
+        }
+    }
+    return out;
+}

package/esm/configuration/promotableDefaults.d.ts

@@ -0,0 +1,199 @@
+import type { TrackConfigChange } from '../util/trackConfigDelta.ts';
+import type { Pin } from './promotablePin.ts';
+import type { PromotedDefaultStore, ResolvableDisplay } from './promotableResolve.ts';
+import type { AnyConfigurationModel, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValueResolved } from './types.ts';
+export type { Pin } from './promotablePin.ts';
+/**
+ * #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 declare function isSlotCustomized<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT): boolean;
+declare const promotablesResolved: unique symbol;
+/**
+ * #api core/configuration
+ * A display config snapshot whose promotable slots hold RESOLVED values rather
+ * than the inherit sentinel — what a worker payload has to be built from.
+ *
+ * The brand is required and unforgeable, so a plain `Record<string, unknown>`
+ * is not assignable to it and neither is `getSnapshot(self.configuration)`.
+ * That is the whole point. Everything downstream of the resolve is an ERASED
+ * container — a snapshot is `Record<string, unknown>`, and the payload it
+ * becomes is an `as`-asserted interface — so a payload builder handed the RAW
+ * snapshot instead typechecks, ships `undefined` for every promotable slot, and
+ * types it as the resolved value. That was measured, not supposed: the raw
+ * spelling in `LinearBasicDisplay`'s `rpcProps()` passed `pnpm typecheck` and
+ * every suite in `plugins/canvas`, `packages/core/src/configuration` and
+ * `products/jbrowse-web`, while sending the worker `undefined` for chevrons,
+ * subfeature labels and feature height.
+ *
+ * The rest of this subsystem's guarantees are carried by types that stay
+ * connected to the schema: a raw read of a promotable `maybe*` slot is
+ * `T | undefined` (see `ConfigurationSlotValue`), so `getConf` where
+ * `resolveConf` was meant is a compile error at any typed consumer. The brand is
+ * that guarantee re-established at the point where the connection is cut.
+ */
+export interface ResolvedConfigSnapshot extends Record<string, unknown> {
+    readonly [promotablesResolved]: true;
+}
+/**
+ * #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 declare function getConfigSnapshotWithPromotables(self: ResolvableDisplay): ResolvedConfigSnapshot;
+/**
+ * #api core/configuration
+ * A track config snapshot with every display's `promotable` slots resolved, plus
+ * the list of values that came from a session-wide default rather than from the
+ * config itself.
+ *
+ * For handing a track's config to somewhere that leaves the cascade for good —
+ * the About dialog's "Copy config", whose output a user pastes into a
+ * `config.json`. A raw `getSnapshot` records a slot a track merely *follows* as
+ * absent (`stripDefault` collapsed it), so the copied config renders differently
+ * from the track it was copied from. This is `getComputedStyle` at that
+ * boundary, and `fromDisplayTypeDefaults` is what lets the UI say so rather than
+ * silently materializing a session preference into a track config.
+ *
+ * Resolves from the display *config* alone, whether or not the track is open.
+ * Everything the cascade takes is on the config node: it is the same node an
+ * open display's `configuration` points at (the hydration cache makes it
+ * stable), its `type` is the display type the session-wide tier is keyed on
+ * (every display schema is `explicitlyTyped` under the display type's own name),
+ * and the session is passed in. So an unopened track — which has no display
+ * state at all — still has an answer to "what would this render as", by the same
+ * code path.
+ *
+ * **Writes every promotable slot, including the ones sitting at `promotedBase`,
+ * and that is the decision — don't "align" it with the share bake.** A pasted
+ * `config.json` is read by a mechanism with no cascade in it at all, so writing
+ * only the inherited values would leave every other slot to pick up whatever the
+ * reader has promoted in their own browser. Pinned by
+ * `products/jbrowse-web/src/tests/CopyConfigPromotedDefaults.test.ts`.
+ */
+export interface TrackConfigWithPromotables {
+    config: Record<string, unknown>;
+    /** `<displayType>.<slot>`, one per value inherited from a promoted default */
+    fromDisplayTypeDefaults: string[];
+}
+/**
+ * #api core/configuration
+ * See {@link TrackConfigWithPromotables}.
+ */
+export declare function getTrackConfigWithPromotables(session: PromotedDefaultStore, trackConfig: AnyConfigurationModel): TrackConfigWithPromotables;
+/**
+ * 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 declare function openTracksOfType(self: ResolvableDisplay): ResolvableDisplay[];
+/**
+ * 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 declare function isPromotableDefault(self: ResolvableDisplay, slot: string, value: unknown): boolean;
+/**
+ * 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 declare function applySlotToOpenTracks(displays: ResolvableDisplay[], slot: string, value: unknown): void;
+/**
+ * #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 declare function makePin<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT, ...value: [] | [
+    ConfigurationSlotValueResolved<ConfigurationSchemaForModel<CONFMODEL>, SLOT>
+]): Pin;
+/**
+ * #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 declare function getDisplayTypeDefaultChanges(self: ResolvableDisplay): TrackConfigChange[];
+/**
+ * #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 declare function clearPromotedDefaults(self: ResolvableDisplay, slots: Iterable<string>): void;