@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/configuration/slotShape.js

@@ -0,0 +1,84 @@
+/**
+ * @module
+ * The one gate a candidate value for a `promotable` slot has to pass. Shared,
+ * deliberately, by the two places that ask the question:
+ *
+ *  - `promotableResolve.ts` at read time, for both cascade tiers — a session-wide
+ *    promoted default and a track's own value out of an untyped saved snapshot;
+ *  - `configurationSlot.ts` at construction, for the slot's own `promotedBase`.
+ *
+ * One implementation is what makes "the base is always a usable value" true by
+ * construction rather than assumed: the resolver falls back to `promotedBase`
+ * whenever a tier fails this gate, so a base that would itself fail has nowhere
+ * left to fall.
+ */
+import { getEnumerationValues } from '../util/mst-reflection.js';
+import { isCallbackValue } from './slotValueUtils.js';
+// Per-slot-type JS shape checks, for the slot types whose value needs more than
+// a `typeof` against `promotedBase`. Only the `maybe*` types appear, because
+// `ConfigSlot` rejects a `promotedBase` on anything else and this table is only
+// ever consulted for a promotable slot. Any type absent here (`maybeBoolean`,
+// `maybeColor`, `maybeFrozen`) falls through to the `promotedBase`-derived check
+// in `matchesSlotShape`.
+const SHAPE_CHECKS = {
+    // a bare `typeof value === 'number'` would admit `NaN`/`±Infinity`, which no
+    // slot legitimately holds
+    maybeNumber: value => Number.isFinite(value),
+    // a `maybeStringEnum` with no `model` can't be membership-checked; reject
+    // rather than admit any string. `def.model` is the author's plain enumeration
+    // (ConfigSlot adds the nullability), so this reads the real vocabulary.
+    maybeStringEnum: (value, def) => !!def.model &&
+        typeof value === 'string' &&
+        getEnumerationValues(def.model).includes(value),
+};
+/**
+ * Whether `value` has a JS shape this slot could hold. Guards the untyped
+ * session store / saved snapshot against garbage; not a full validation
+ * (`validate` layers semantics on top).
+ *
+ * Module-private on purpose: `isUsableValue` is the gate, and this is only one
+ * of its four checks. A caller reaching for the shape test alone would skip the
+ * `jexl:` refusal and the slot's `validate` hook — the two checks that exist
+ * precisely because a shape-valid value can still be unusable.
+ *
+ * Keyed off `promotedBase` because that is the only concrete specimen of the
+ * slot's value space a promotable slot declares — `defaultValue` is always the
+ * inherit sentinel, so keying off it would demand `typeof value === 'undefined'`.
+ * A `promotedBase` checked against itself therefore only exercises the
+ * `SHAPE_CHECKS` entries, which is exactly the half that can be authored wrong
+ * (an enum member that isn't in the vocabulary, a non-finite number).
+ *
+ * Can't delegate to the slot's MST `model.is(value)`, which is too permissive
+ * exactly where this guard matters — `slotShape.test.ts` pins the two cases.
+ */
+function matchesSlotShape(def, value) {
+    const { promotedBase } = def;
+    const check = SHAPE_CHECKS[def.type];
+    return check
+        ? check(value, def)
+        : typeof promotedBase === 'object' && promotedBase !== null
+            ? // object/array slot (e.g. `colorBy`): match null-ness and array-ness —
+                // a bare `typeof` compare would admit `null` (typeof null === 'object')
+                // and an array against an object base
+                typeof value === 'object' &&
+                    value !== null &&
+                    Array.isArray(value) === Array.isArray(promotedBase)
+            : typeof value === typeof promotedBase;
+}
+/**
+ * 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 function isUsableValue(def, value) {
+    const { validate } = def;
+    return (value !== undefined &&
+        !isCallbackValue(value) &&
+        matchesSlotShape(def, value) &&
+        (!validate || validate(value)));
+}

package/esm/configuration/slotValueUtils.d.ts

@@ -0,0 +1,17 @@
+import type { JexlInstance } from '../util/jexlStrings.ts';
+/**
+ * The shared, MST-free jexl primitives for config values, with no knowledge of
+ * slot type names. Both the MST read path (`readConfObject`) and the
+ * plain-object/worker read path (`readConfigValue`) route through here.
+ *
+ * The value<->callback *conversions* (`toFixedValue`/`toCallbackValue`), which
+ * depend on the slot-type registry, live in `configurationSlot.ts`.
+ */
+export declare function isCallbackValue(value: unknown): value is string;
+/**
+ * The single jexl-evaluation boundary for config values.
+ *
+ * An empty body (`'jexl:'`, e.g. mid-typing in the editor) has no compilable
+ * code — return it literally instead of throwing (#4181).
+ */
+export declare function evaluateJexl(value: string, args: Record<string, unknown>, jexl: JexlInstance): unknown;

package/esm/configuration/slotValueUtils.js

@@ -0,0 +1,25 @@
+import { isJexl, stringToJexlExpression } from '../util/jexlStrings.js';
+import { buildJexlContext } from '../util/simpleFeature.js';
+/**
+ * The shared, MST-free jexl primitives for config values, with no knowledge of
+ * slot type names. Both the MST read path (`readConfObject`) and the
+ * plain-object/worker read path (`readConfigValue`) route through here.
+ *
+ * The value<->callback *conversions* (`toFixedValue`/`toCallbackValue`), which
+ * depend on the slot-type registry, live in `configurationSlot.ts`.
+ */
+export function isCallbackValue(value) {
+    return isJexl(value);
+}
+/**
+ * The single jexl-evaluation boundary for config values.
+ *
+ * An empty body (`'jexl:'`, e.g. mid-typing in the editor) has no compilable
+ * code — return it literally instead of throwing (#4181).
+ */
+export function evaluateJexl(value, args, jexl) {
+    if (value.length <= 'jexl:'.length) {
+        return value;
+    }
+    return stringToJexlExpression(value, jexl).eval(buildJexlContext(args));
+}

package/esm/configuration/tabixIndexFields.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The `index` sub-schema every tabix-indexed adapter declares: which index kind,
+ * and where it is.
+ *
+ * The **snapshot** half of this was extracted first (`tabixIndexSnapshot`, whose
+ * header explains why eight adapters writing out `CSI`/`TBI` and `.csi`/`.tbi`
+ * separately is a crossed pair waiting to happen). This is the schema half of
+ * the same job, and it was still nine hand-written copies under eight different
+ * type names — `TabixIndex`, `Index`, `VcfIndex`, `Gff3TabixIndex`,
+ * `GtfTabixIndex`, `BedGraphTabixIndex`, `PlinkLDTabixIndex` — for one concept,
+ * which is what let four of them drift:
+ *
+ * - `MafTabixAdapter` omitted `locationType` from its default and declared its
+ *   two slots in the opposite order
+ * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
+ *   default said `my.paf.gz.tbi`
+ * - `PlinkLDTabixAdapter` dropped the `(or .csi)` clause
+ * - the placeholder extensions disagreed with each other for no reason
+ *
+ * The description is written for every tabix adapter rather than naming one
+ * file type, since none of them is more canonical than the others and the
+ * placeholder is not a value anyone copies — the `uri` shorthand derives the
+ * real one.
+ *
+ * **BAM is deliberately not here.** Its index is BAI/CSI rather than TBI/CSI, so
+ * it is a different enumeration with a different default, and folding the two
+ * would mean a slot whose vocabulary depends on its adapter.
+ */
+export declare const tabixIndexFields: {
+    readonly indexType: {
+        readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"CSI" | "TBI">;
+        readonly type: 'stringEnum';
+        readonly defaultValue: 'TBI';
+        readonly description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address.';
+    };
+    readonly location: {
+        readonly type: 'fileLocation';
+        readonly defaultValue: {
+            readonly uri: '/path/to/my.gz.tbi';
+            readonly locationType: 'UriLocation';
+        };
+        readonly description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.';
+    };
+};

package/esm/configuration/tabixIndexFields.js

@@ -0,0 +1,45 @@
+import { types } from '@jbrowse/mobx-state-tree';
+/**
+ * The `index` sub-schema every tabix-indexed adapter declares: which index kind,
+ * and where it is.
+ *
+ * The **snapshot** half of this was extracted first (`tabixIndexSnapshot`, whose
+ * header explains why eight adapters writing out `CSI`/`TBI` and `.csi`/`.tbi`
+ * separately is a crossed pair waiting to happen). This is the schema half of
+ * the same job, and it was still nine hand-written copies under eight different
+ * type names — `TabixIndex`, `Index`, `VcfIndex`, `Gff3TabixIndex`,
+ * `GtfTabixIndex`, `BedGraphTabixIndex`, `PlinkLDTabixIndex` — for one concept,
+ * which is what let four of them drift:
+ *
+ * - `MafTabixAdapter` omitted `locationType` from its default and declared its
+ *   two slots in the opposite order
+ * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
+ *   default said `my.paf.gz.tbi`
+ * - `PlinkLDTabixAdapter` dropped the `(or .csi)` clause
+ * - the placeholder extensions disagreed with each other for no reason
+ *
+ * The description is written for every tabix adapter rather than naming one
+ * file type, since none of them is more canonical than the others and the
+ * placeholder is not a value anyone copies — the `uri` shorthand derives the
+ * real one.
+ *
+ * **BAM is deliberately not here.** Its index is BAI/CSI rather than TBI/CSI, so
+ * it is a different enumeration with a different default, and folding the two
+ * would mean a slot whose vocabulary depends on its adapter.
+ */
+export const tabixIndexFields = {
+    indexType: {
+        model: types.enumeration('IndexType', ['TBI', 'CSI']),
+        type: 'stringEnum',
+        defaultValue: 'TBI',
+        description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address.',
+    },
+    location: {
+        type: 'fileLocation',
+        defaultValue: {
+            uri: '/path/to/my.gz.tbi',
+            locationType: 'UriLocation',
+        },
+        description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.',
+    },
+};

package/esm/configuration/tabixShorthand.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `index` half of a tabix-indexed adapter's shorthand snapshot: given
+ * `{ uri, baseUri?, csi? }`, where the index file sits and what kind it is.
+ *
+ * Two spellings of the same flag have to agree — `CSI`/`TBI` names the type and
+ * `.csi`/`.tbi` the file extension — and eight adapters were each writing both
+ * out. Getting the pair crossed is an adapter that looks for the wrong index
+ * file, or claims the wrong format for the right one, on a config the user
+ * wrote correctly.
+ */
+export declare function tabixIndexSnapshot(snap: Record<string, unknown>): {
+    indexType: string;
+    location: {
+        uri: string;
+        baseUri: unknown;
+    };
+};
+/**
+ * Expand a tabix adapter's one-line shorthand — `{ uri: 'x.gff.gz' }`, plus
+ * optional `csi` — into the full `{ <locationKey>, index }` snapshot, or pass a
+ * snapshot that is already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between adapters
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …), so
+ * it is the only thing they now supply. An adapter whose shorthand carries more
+ * than this (maf's `nhUri`) composes `tabixIndexSnapshot` directly instead.
+ *
+ * Kept a plain function on the adapter type rather than folded into
+ * `ConfigurationSchema`: `scripts/generateConfigManifest.ts` derives each
+ * adapter's `shorthandKeys` by EXECUTING `normalizeSnapshot` against probe
+ * snapshots and diffing what it derived, so the manifest — and the config docs
+ * built from it — follow this without knowing it exists.
+ */
+export declare function expandTabixShorthand(snap: Record<string, unknown>, locationKey: string): Record<string, unknown>;

package/esm/configuration/tabixShorthand.js

@@ -0,0 +1,45 @@
+/**
+ * The `index` half of a tabix-indexed adapter's shorthand snapshot: given
+ * `{ uri, baseUri?, csi? }`, where the index file sits and what kind it is.
+ *
+ * Two spellings of the same flag have to agree — `CSI`/`TBI` names the type and
+ * `.csi`/`.tbi` the file extension — and eight adapters were each writing both
+ * out. Getting the pair crossed is an adapter that looks for the wrong index
+ * file, or claims the wrong format for the right one, on a config the user
+ * wrote correctly.
+ */
+export function tabixIndexSnapshot(snap) {
+    const csi = Boolean(snap.csi);
+    return {
+        indexType: csi ? 'CSI' : 'TBI',
+        location: {
+            uri: `${snap.uri}.${csi ? 'csi' : 'tbi'}`,
+            baseUri: snap.baseUri,
+        },
+    };
+}
+/**
+ * Expand a tabix adapter's one-line shorthand — `{ uri: 'x.gff.gz' }`, plus
+ * optional `csi` — into the full `{ <locationKey>, index }` snapshot, or pass a
+ * snapshot that is already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between adapters
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …), so
+ * it is the only thing they now supply. An adapter whose shorthand carries more
+ * than this (maf's `nhUri`) composes `tabixIndexSnapshot` directly instead.
+ *
+ * Kept a plain function on the adapter type rather than folded into
+ * `ConfigurationSchema`: `scripts/generateConfigManifest.ts` derives each
+ * adapter's `shorthandKeys` by EXECUTING `normalizeSnapshot` against probe
+ * snapshots and diffing what it derived, so the manifest — and the config docs
+ * built from it — follow this without knowing it exists.
+ */
+export function expandTabixShorthand(snap, locationKey) {
+    return snap.uri
+        ? {
+            ...snap,
+            [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+            index: tabixIndexSnapshot(snap),
+        }
+        : snap;
+}

package/esm/configuration/types.d.ts

@@ -1,14 +1,177 @@
-import type { ConfigurationSchemaOptions, ConfigurationSchemaType } from './configurationSchema.ts';
-import type ConfigSlot from './configurationSlot.ts';
-import type { IStateTreeNode, Instance, SnapshotOut } from '@jbrowse/mobx-state-tree';
+import type { FileLocation } from '../util/types/index.ts';
+import type { ConfigurationSchemaDefinition, ConfigurationSchemaOptions, ConfigurationSchemaType } from './configurationSchema.ts';
+import type { BuiltinSlotTypeName } from './configurationSlot.ts';
+import type { ISimpleType, IStateTreeNode, Instance, SnapshotOut } from '@jbrowse/mobx-state-tree';
 export type GetOptions<SCHEMA> = SCHEMA extends ConfigurationSchemaType<any, infer OPTIONS> ? OPTIONS : never;
 export type GetBase<SCHEMA> = SCHEMA extends undefined ? never : GetOptions<SCHEMA> extends ConfigurationSchemaOptions<undefined, any> ? undefined : GetOptions<SCHEMA> extends ConfigurationSchemaOptions<infer BASE extends AnyConfigurationSchemaType, any> ? BASE : never;
 export type GetExplicitIdentifier<SCHEMA> = GetOptions<SCHEMA> extends ConfigurationSchemaOptions<any, infer EXPLICIT_IDENTIFIER extends string> ? EXPLICIT_IDENTIFIER : never;
+/**
+ * The identifier prop a schema declares **or inherits** — `trackId`,
+ * `displayId`, or whatever `explicitIdentifier` names. Recursive because most
+ * display schemas never declare it themselves: they pick up `displayId` from
+ * `baseConfiguration: baseLinearDisplayConfigSchema`, whose options
+ * `preprocessConfigurationSchemaArguments` merges in at runtime, leaving the
+ * subclass's own `EXPLICIT_IDENTIFIER` param `undefined`. Same walk
+ * `ConfigurationSlotName` does for inherited slot names.
+ */
+export type GetInheritedIdentifier<SCHEMA> = SCHEMA extends undefined ? never : SCHEMA extends ConfigurationSchemaType<any, any> ? GetExplicitIdentifier<SCHEMA> | (GetBase<SCHEMA> extends ConfigurationSchemaType<any, any> ? GetInheritedIdentifier<GetBase<SCHEMA>> : never) : never;
 export type ConfigurationSchemaForModel<MODEL> = MODEL extends IStateTreeNode<infer SCHEMA extends AnyConfigurationSchemaType> ? SCHEMA : never;
 export type ConfigurationSlotName<SCHEMA> = SCHEMA extends undefined ? never : SCHEMA extends ConfigurationSchemaType<infer D, any> ? (keyof D & string) | GetExplicitIdentifier<SCHEMA> | (GetBase<SCHEMA> extends ConfigurationSchemaType<any, any> ? ConfigurationSlotName<GetBase<SCHEMA>> : never) : never;
+/**
+ * The names a config snapshot for `SCHEMA` may use — its own slots, its
+ * sub-schemas recursively, its identifier and everything it inherits — with
+ * every value left `unknown`.
+ *
+ * Names are the whole point of it. A slot value can be its own type, a `jexl:`
+ * callback string, or (for a promotable slot) absent, and nothing here tries to
+ * check that; a *name* the schema does not declare is dropped on the way in
+ * without a word, so `preferance` is a setting that reads as applied and never
+ * applies. Against an object literal — which is how an embedder writes one —
+ * TypeScript's excess-property check turns that into a compile error.
+ */
+export type ConfigurationSnapshot<SCHEMA> = SCHEMA extends undefined ? never : SCHEMA extends ConfigurationSchemaType<infer D, any> ? {
+    [K in keyof D]?: D[K] extends ConfigurationSchemaType<any, any> ? ConfigurationSnapshot<D[K]> : unknown;
+} & {
+    [K in GetExplicitIdentifier<SCHEMA>]?: string;
+} & (GetBase<SCHEMA> extends ConfigurationSchemaType<any, any> ? ConfigurationSnapshot<GetBase<SCHEMA>> : unknown) : unknown;
+type SlotValueResolvedFromDef<DEF> = DEF extends {
+    promotedBase: undefined;
+} ? SlotValueRawFromDef<DEF> : DEF extends {
+    promotedBase: unknown;
+} ? Exclude<SlotValueRawFromDef<DEF>, undefined> : SlotValueRawFromDef<DEF>;
+/**
+ * The value each builtin slot `type` reads as — the type-level twin of
+ * `slotTypes` in `configurationSlot.ts`, which is the same list as MST models.
+ * A table rather than the fourteen-deep conditional staircase this used to be:
+ * adding a slot type is now one row here and one there, and the two tables sit
+ * side by side where a name present in one and missing from the other is
+ * visible. Missing a row is not silent either — it drops the slot to the
+ * `defaultValue` fallback below, which is what `SlotValueRawFromDef` documents.
+ *
+ * `stringEnum`/`maybeStringEnum` are deliberately absent: their value type comes
+ * from the author's own `types.enumeration`, read off `model` before this table
+ * is consulted.
+ */
+interface SlotValueByType {
+    stringArray: string[];
+    stringArrayMap: Record<string, string[]>;
+    numberMap: Record<string, number>;
+    fileLocation: FileLocation;
+    maybeNumber: number | undefined;
+    maybeBoolean: boolean | undefined;
+    maybeColor: string | undefined;
+    /**
+     * `frozen` and its `maybe*` form are `any` deliberately — arbitrary dynamic
+     * JSON whose shape the caller asserts at the read boundary. `unknown` would
+     * only add cast ceremony on values that are legitimately dynamic.
+     *
+     * Stated here rather than left to the `defaultValue` fallback, which reaches
+     * `any` for these only by accident: it lands there because no `frozen` slot in
+     * the repo happens to default to a scalar, and a promotable slot's default is
+     * always the `undefined` sentinel.
+     */
+    frozen: any;
+    maybeFrozen: any;
+    number: number;
+    integer: number;
+    boolean: boolean;
+    string: string;
+    text: string;
+    color: string;
+}
+/**
+ * The two tables name the same builtin slot types, checked rather than
+ * remembered.
+ *
+ * A row present in one and missing from the other is otherwise **not** an
+ * error: the slot drops through to `SlotValueRawFromDef`'s `defaultValue`
+ * fallback, which re-widens a scalar default but reaches `any` for everything
+ * else — so a new `stringArray`-shaped type would silently read as `any` at
+ * every call site. The "every builtin slot type reads as its declared value
+ * type" case in `configTypeNarrowing.test.ts` lists the rows by hand, so it
+ * only catches the drift if whoever adds the type also edits the test; this
+ * catches it either way.
+ */
+type MutuallyExtends<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
+type Assert<T extends true> = T;
+export type SlotValueTableCoversBuiltinSlotTypes = Assert<MutuallyExtends<BuiltinSlotTypeName, keyof SlotValueByType>>;
+type SlotValueRawFromDef<DEF> = DEF extends AnyConfigurationSchemaType ? AnyConfigurationSnapshot : DEF extends {
+    model: ISimpleType<infer T extends string>;
+} ? DEF extends {
+    type: 'maybeStringEnum';
+} ? T | undefined : T : DEF extends {
+    type: infer T extends keyof SlotValueByType;
+} ? SlotValueByType[T] : DEF extends {
+    defaultValue: infer V;
+} ? [V] extends [boolean] ? boolean : [V] extends [string] ? string : [V] extends [number] ? number : any : any;
+/** what a raw read (`getConf` / `readConfObject`) of this slot yields */
+export type ConfigurationSlotValue<SCHEMA, K extends string> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? K extends keyof D ? SlotValueRawFromDef<D[K]> : GetBase<SCHEMA> extends ConfigurationSchemaType<any, any> ? ConfigurationSlotValue<GetBase<SCHEMA>, K> : any : any;
+/**
+ * what `resolveConf` yields: the same, minus the inherit sentinel on a
+ * promotable slot — the cascade always produces a real value.
+ */
+export type ConfigurationSlotValueResolved<SCHEMA, K extends string> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? K extends keyof D ? SlotValueResolvedFromDef<D[K]> : GetBase<SCHEMA> extends ConfigurationSchemaType<any, any> ? ConfigurationSlotValueResolved<GetBase<SCHEMA>, K> : any : any;
+/**
+ * Naming convention for config types, paired per schema:
+ * - `XConfigSchema` is the MST IType (the schema itself). Use it for
+ *   `getConf`, `ConfigurationReference`, and factory params — anywhere a schema
+ *   is expected.
+ * - `XConfigModel` is `Instance<XConfigSchema>` (a resolved config node). Use it
+ *   for `readConfObject` results, model fields, and values read off a session.
+ *
+ * Prefer a named `XConfigModel` alias over inlining `Instance<XConfigSchema>` at
+ * call sites. Two historical names predate this convention and stay as-is:
+ * `BaseTrackConfig` (the track instance type) and `AnyConfiguration` (a
+ * model-or-snapshot union, not a plain instance).
+ */
 export type AnyConfigurationSchemaType = ConfigurationSchemaType<any, any>;
 export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType>;
-export type AnyConfigurationSlotType = ReturnType<typeof ConfigSlot>;
-export type AnyConfigurationSlot = Instance<AnyConfigurationSlotType>;
-export type AnyConfiguration = AnyConfigurationModel | SnapshotOut<AnyConfigurationModel>;
-export type ConfigurationModel<SCHEMA extends AnyConfigurationSchemaType> = Instance<SCHEMA>;
+/**
+ * The `XConfigModel` for a **field table** — a `*ConfigSchemaFields` export —
+ * rather than for a whole assembled schema. What it is for is the cast a
+ * cross-cutting mixin uses to reach the `configuration` its composing display
+ * supplies but its own `self` cannot see: cast to `AnyConfigurationModel` there
+ * and `getConf`/`setConf` derive their slot-name constraint from a schema
+ * widened to `any`, so every name typechecks and a misspelled *read* returns
+ * `undefined` with no diagnostic at any layer. Name the mixin's own field table
+ * instead and the check comes back, scoped to exactly the slots that mixin owns.
+ *
+ * `BASE` is for the mixin that also reads a slot off the schema its displays
+ * inherit from — `ConfigurationSlotName` walks the base chain, so passing it
+ * admits those names too and nothing else (`HeightModeMixin` and `height`).
+ *
+ * The pairing this depends on is a mixin and its field table living together:
+ * `RowHeightMixin` + `rowHeightConfigSchemaFields` is the worked example, and
+ * `packages/tree-sidebar/CLAUDE.md` has the reasoning.
+ */
+export type ConfigModelForFields<FIELDS extends ConfigurationSchemaDefinition, BASE extends AnyConfigurationSchemaType | undefined = undefined> = Instance<ConfigurationSchemaType<FIELDS, ConfigurationSchemaOptions<BASE, undefined>>>;
+/**
+ * `true` when HOST's `configuration` still narrows slot names, `false` when it
+ * has widened them back to `string`. One line per mixin pins it:
+ *
+ * ```ts
+ * const pin: HostChecksSlotNames<HeightModeHost> = true
+ * ```
+ *
+ * Worth a named type because the widened form has **no symptom** — a mixin host
+ * cast to `AnyConfigurationModel`, or to the `ResolvableDisplay & { … }`
+ * intersection that re-widens, compiles and runs and checks nothing. Every
+ * misspelled slot name below it typechecks, and a misspelled *read* returns
+ * `undefined` with no diagnostic at any layer, so only a sabotage or this
+ * assertion tells the two apart.
+ */
+export type HostChecksSlotNames<HOST extends {
+    configuration: AnyConfigurationModel;
+}> = string extends ConfigurationSlotName<ConfigurationSchemaForModel<HOST['configuration']>> ? false : true;
+/** a plain-object snapshot of a configuration model (not a live MST node) */
+export type AnyConfigurationSnapshot = SnapshotOut<AnyConfigurationModel>;
+/**
+ * A value readable as configuration: either a live configuration model or a
+ * plain snapshot of one. `session.tracks` legitimately holds a mix (live
+ * `sessionTracks` nodes, plus plain frozen/merged base entries that hydrate to
+ * MST only on first reference access), and `readConfObject` reads both — so this
+ * is the honest type at those boundaries. Reserve `AnyConfigurationModel` for
+ * values that must be live (actions, identity, reference resolution).
+ */
+export type AnyConfiguration = AnyConfigurationModel | AnyConfigurationSnapshot;
+export {};

package/esm/data_adapters/BaseAdapter/BaseAdapter.d.ts

@@ -1,16 +1,30 @@
 import type PluginManager from '../../PluginManager.ts';
-import type { AnyConfigurationModel } from '../../configuration/index.ts';
-import type { AugmentedRegion as Region } from '../../util/types/index.ts';
+import type { AnyConfigurationModel, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.ts';
-export declare class BaseAdapter {
-    config: AnyConfigurationModel;
-    getSubAdapter?: getSubAdapterType | undefined;
-    pluginManager?: PluginManager | undefined;
+export declare class BaseAdapter<CONF extends AnyConfigurationModel = AnyConfigurationModel> {
     id: string;
+    config: CONF;
+    getSubAdapter?: getSubAdapterType;
+    pluginManager?: PluginManager;
     sequenceAdapterConfig?: Record<string, unknown>;
     static capabilities: string[];
-    constructor(config?: AnyConfigurationModel, getSubAdapter?: getSubAdapterType | undefined, pluginManager?: PluginManager | undefined);
-    setSequenceAdapterConfig(config: Record<string, unknown>): void;
-    getConf(arg: string | string[]): any;
-    freeResources(_region: Region): void;
+    constructor(config?: CONF, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager);
+    /**
+     * Stashes the reference-sequence adapter config for adapters that decode
+     * against the reference (e.g. BAM/CRAM). Set once and never cleared: the
+     * adapter is cached per adapterConfig (dataAdapterCache), so a given instance
+     * maps to a single, stable sequence adapter, and an `undefined` from a later
+     * caller must not wipe a config an earlier one already primed. One `??=` does
+     * both; callers don't need to guard.
+     *
+     * **Instance state rather than a per-call argument, and that is forced.**
+     * `CramAdapter` binds its `seqFetch` into the `IndexedCramFile` at
+     * construction, and @gmod/cram invokes it later with `(seqId, start, end)` and
+     * nothing else — there is no call to thread a config through. Threading it per
+     * call is the recurring proposal here and it dies at CRAM, which is the
+     * adapter that needs the reference most.
+     */
+    setSequenceAdapterConfig(config: Record<string, unknown> | undefined): void;
+    /** shorthand for `readConfObject(this.config, arg)` */
+    getConf<SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONF>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONF>>>(arg: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONF>, SLOT> : any;
 }

package/esm/data_adapters/BaseAdapter/BaseAdapter.js

@@ -1,31 +1,39 @@
-import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { ConfigurationSchema, readConfObject, } from "../../configuration/index.js";
-import idMaker from "../../util/idMaker.js";
+import { ConfigurationSchema, readConfObject, } from '../../configuration/index.js';
+import { getAdapterId } from './getAdapterId.js';
 const EmptyConfig = ConfigurationSchema('empty', {});
 export class BaseAdapter {
+    id;
     config;
     getSubAdapter;
     pluginManager;
-    id;
     sequenceAdapterConfig;
     static capabilities = [];
     constructor(config = EmptyConfig.create(), getSubAdapter, pluginManager) {
         this.config = config;
         this.getSubAdapter = getSubAdapter;
         this.pluginManager = pluginManager;
-        if (typeof jest === 'undefined') {
-            const data = isStateTreeNode(config) ? getSnapshot(config) : config;
-            this.id = `${idMaker(data)}`;
-        }
-        else {
-            this.id = 'test';
-        }
+        this.id = getAdapterId(config);
     }
+    /**
+     * Stashes the reference-sequence adapter config for adapters that decode
+     * against the reference (e.g. BAM/CRAM). Set once and never cleared: the
+     * adapter is cached per adapterConfig (dataAdapterCache), so a given instance
+     * maps to a single, stable sequence adapter, and an `undefined` from a later
+     * caller must not wipe a config an earlier one already primed. One `??=` does
+     * both; callers don't need to guard.
+     *
+     * **Instance state rather than a per-call argument, and that is forced.**
+     * `CramAdapter` binds its `seqFetch` into the `IndexedCramFile` at
+     * construction, and @gmod/cram invokes it later with `(seqId, start, end)` and
+     * nothing else — there is no call to thread a config through. Threading it per
+     * call is the recurring proposal here and it dies at CRAM, which is the
+     * adapter that needs the reference most.
+     */
     setSequenceAdapterConfig(config) {
-        this.sequenceAdapterConfig = config;
+        this.sequenceAdapterConfig ??= config;
     }
-    getConf(arg) {
-        return readConfObject(this.config, arg);
+    /** shorthand for `readConfObject(this.config, arg)` */
+    getConf(arg, args) {
+        return readConfObject(this.config, arg, args);
     }
-    freeResources(_region) { }
 }