@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/configuration/tabixShorthand.d.ts

@@ -1,15 +1,32 @@
+import type { IndexType, SiblingIndexType } from './indexType.ts';
 /**
- * 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.
+ * The index type a config asks for, by whichever of its three spellings: the
+ * `csi` flag, `index.indexType`, or the extension on the index file it names.
+ * Explicit beats derived.
  *
- * 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.
+ * One reader for all three, because they are one fact and disagreeing copies of
+ * it open the wrong parser — `openTabixIndexFilehandle` hands @gmod/tabix a
+ * `csiFilehandle` or a `tbiFilehandle` off `indexType` alone.
  */
+export declare function requestedIndexType(snap: Record<string, unknown>, fallback: SiblingIndexType): IndexType;
+/**
+ * The `index` half of an indexed adapter's shorthand snapshot. The filename
+ * follows from {@link requestedIndexType}, so the type and the extension cannot
+ * disagree, and whatever the config wrote under `index` then wins member by
+ * member: naming a location keeps the derived type, naming a type keeps the
+ * derived location, and an `indexType` the enumeration does not have reaches MST
+ * to be refused rather than being quietly read as the sibling format.
+ */
+export declare function indexSnapshot(snap: Record<string, unknown>, fallback: SiblingIndexType): {
+    indexType: IndexType;
+    location: {
+        uri: string;
+        baseUri: unknown;
+    };
+};
+/** {@link indexSnapshot} for the tabix family, whose sibling format is TBI. */
 export declare function tabixIndexSnapshot(snap: Record<string, unknown>): {
-    indexType: string;
+    indexType: IndexType;
     location: {
         uri: string;
         baseUri: unknown;
@@ -18,17 +35,17 @@ export declare function tabixIndexSnapshot(snap: Record<string, 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.
+ * snapshot 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.
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …). An
+ * adapter whose shorthand carries more (maf's `nhUri`) composes
+ * `tabixIndexSnapshot` directly.
  *
- * 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.
+ * Kept a plain function rather than folded into `ConfigurationSchema`:
+ * `scripts/generateConfigManifest.ts` derives each adapter's `shorthandKeys` by
+ * EXECUTING `normalizeSnapshot` against probe snapshots, so the manifest and the
+ * config docs follow this without knowing it exists. It finds the candidate keys
+ * by reading them out of source, following what an adapter schema imports.
  */
 export declare function expandTabixShorthand(snap: Record<string, unknown>, locationKey: string): Record<string, unknown>;

package/esm/configuration/tabixShorthand.js

@@ -1,44 +1,71 @@
+import { isPlainObject } from '../util/objectUtils.js';
+import { fillLocations } from './fillLocations.js';
+import { indexSuffix, isCsiLocation } from './indexType.js';
 /**
- * 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.
+ * The index type a config asks for, by whichever of its three spellings: the
+ * `csi` flag, `index.indexType`, or the extension on the index file it names.
+ * Explicit beats derived.
  *
- * 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.
+ * One reader for all three, because they are one fact and disagreeing copies of
+ * it open the wrong parser — `openTabixIndexFilehandle` hands @gmod/tabix a
+ * `csiFilehandle` or a `tbiFilehandle` off `indexType` alone.
  */
-export function tabixIndexSnapshot(snap) {
-    const csi = Boolean(snap.csi);
+export function requestedIndexType(snap, fallback) {
+    const written = isPlainObject(snap.index) ? snap.index : undefined;
+    const declared = written?.indexType;
+    if (declared === 'CSI') {
+        return 'CSI';
+    }
+    if (declared === fallback) {
+        return fallback;
+    }
+    return snap.csi || isCsiLocation(written?.location) ? 'CSI' : fallback;
+}
+/**
+ * The `index` half of an indexed adapter's shorthand snapshot. The filename
+ * follows from {@link requestedIndexType}, so the type and the extension cannot
+ * disagree, and whatever the config wrote under `index` then wins member by
+ * member: naming a location keeps the derived type, naming a type keeps the
+ * derived location, and an `indexType` the enumeration does not have reaches MST
+ * to be refused rather than being quietly read as the sibling format.
+ */
+export function indexSnapshot(snap, fallback) {
+    const indexType = requestedIndexType(snap, fallback);
     return {
-        indexType: csi ? 'CSI' : 'TBI',
+        indexType,
         location: {
-            uri: `${snap.uri}.${csi ? 'csi' : 'tbi'}`,
+            uri: `${snap.uri}${indexSuffix(indexType)}`,
             baseUri: snap.baseUri,
         },
+        ...(isPlainObject(snap.index) ? snap.index : {}),
     };
 }
+/** {@link indexSnapshot} for the tabix family, whose sibling format is TBI. */
+export function tabixIndexSnapshot(snap) {
+    return indexSnapshot(snap, 'TBI');
+}
 /**
  * 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.
+ * snapshot 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.
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …). An
+ * adapter whose shorthand carries more (maf's `nhUri`) composes
+ * `tabixIndexSnapshot` directly.
  *
- * 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.
+ * Kept a plain function rather than folded into `ConfigurationSchema`:
+ * `scripts/generateConfigManifest.ts` derives each adapter's `shorthandKeys` by
+ * EXECUTING `normalizeSnapshot` against probe snapshots, so the manifest and the
+ * config docs follow this without knowing it exists. It finds the candidate keys
+ * by reading them out of source, following what an adapter schema imports.
  */
 export function expandTabixShorthand(snap, locationKey) {
     return snap.uri
         ? {
-            ...snap,
-            [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+            ...fillLocations(snap, {
+                [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+            }),
             index: tabixIndexSnapshot(snap),
         }
         : snap;

package/esm/configuration/types.d.ts

@@ -1,29 +1,143 @@
 import type { FileLocation } from '../util/types/index.ts';
+import type { IsAny } from '../util/types/isAny.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;
+import type { IAnyType, IArrayType, IOptionalIType, ISimpleType, IStateTreeNode, Instance, SnapshotOut } from '@jbrowse/mobx-state-tree';
+export type ConfigurationSchemaForModel<MODEL> = IsAny<MODEL> extends true ? AnyConfigurationSchemaType : MODEL extends IStateTreeNode<infer T> ? T extends AnyConfigurationSchemaType ? T : T extends IOptionalIType<infer INNER extends AnyConfigurationSchemaType, any> ? INNER : AnyConfigurationSchemaType : never;
+/**
+ * A schema's definition as **stored**: the author's own entries over the ones
+ * its `baseConfiguration` contributed, the type-level twin of
+ * `mergeSchemaDefinition`. The base arrives already merged with its own base,
+ * so one level here covers a chain of any depth.
+ *
+ * A flat mapped type over the union of both key sets, not
+ * `Omit<BASE, keyof D> & D`: an intersection's `keyof` is a union of key sets,
+ * and mapping over a union that includes `string` — which
+ * `ConfigurationSchemaDefinition`'s index signature contributes — collapses
+ * back to an index signature, which is the thing `ConfigNodeProps` exists to
+ * get rid of.
+ */
+export type MergeConfigDef<D, BASE> = BASE extends ConfigurationSchemaType<infer BD, any> ? {
+    [K in keyof BD | keyof D]: NormalizeSlotDef<K extends keyof D ? K extends keyof BD ? MergeSlotDef<BD[K], D[K]> : D[K] : K extends keyof BD ? BD[K] : never>;
+} : {
+    [K in keyof D]: NormalizeSlotDef<D[K]>;
+};
+/**
+ * A redeclared slot merges field-by-field over the base's; a sub-schema or a
+ * constant keeps replace semantics, matching `mergeSchemaDefinition`'s
+ * `isSlotDefinitionEntry` guard.
+ */
+type MergeSlotDef<BASE_ENTRY, ENTRY> = BASE_ENTRY extends {
+    type: string;
+} ? ENTRY extends {
+    type: string;
+} ? Omit<BASE_ENTRY, keyof ENTRY> & ENTRY : ENTRY : ENTRY;
+/**
+ * What the type level reads off a slot definition: the slot's `type`, a
+ * `stringEnum`'s `model`, and whether a `defaultValue` is there at all — widened
+ * off its literal. The description, `advanced`, `contextVariable` and the
+ * literal default are documentation and runtime, and carrying them makes two
+ * schemas that differ only in one of them mutually unassignable: a subclass
+ * raising `height` from 100 to 250 stopped satisfying a parameter pinned to its
+ * base. `SlotValueRawFromDef` re-widens a scalar default anyway, and reaches
+ * `any` for everything else, so nothing downstream loses precision.
+ */
+type NormalizeSlotDef<E> = E extends AnyConfigurationSchemaType ? E : E extends {
+    type: infer T;
+} ? {
+    type: T;
+} & (E extends {
+    model: infer M;
+} ? {
+    model: M;
+} : unknown) & (E extends {
+    defaultValue: infer V;
+} ? {
+    defaultValue: WidenDefaultValue<V>;
+} : unknown) : E;
+type WidenDefaultValue<V> = [V] extends [boolean] ? boolean : [V] extends [string] ? string : [V] extends [number] ? number : unknown;
+type ConfigNodeValue<DEF> = IsAny<DEF> extends true ? any : DEF extends AnyConfigurationSchemaType ? DEF['Type'] : DEF extends IArrayType<any> | IOptionalIType<IArrayType<any>, any> ? DEF['Type'] : DEF extends string ? string : DEF extends number ? number : SlotValueRawFromDef<DEF>;
+/**
+ * The slots a config node presents, read off the schema's own DEFINITION rather
+ * than the `Record<string, any>` `makeConfigurationSchemaModel` assembles its
+ * MST props from. Those props carry an index signature, so every
+ * `node.anything` resolves to `any`; mapping the definition instead is what
+ * makes `node.colorr` a compile error.
+ *
+ * A plain mapped type, and it has to stay one. Wrapping it in a conditional —
+ * to answer early for a widened definition, say — makes TypeScript measure
+ * DEFINITION as covariant instead of invariant, and it refuses a failed
+ * covariant check on a type argument outright where a failed invariant one
+ * falls back to comparing the two schemas structurally. Structural is the
+ * comparison that matters: a subclass schema's node has every slot the base's
+ * does, while its *definition* restates `defaultValue` and `description` and so
+ * matches nothing. The widened case belongs on `AnyConfigurationModel`.
+ */
+export type ConfigNodeProps<DEFINITION> = {
+    [K in keyof DEFINITION]: ConfigNodeValue<DEFINITION[K]>;
+};
+/**
+ * The two write actions every config node carries, which `setConf` is the
+ * spelling of. A type alias rather than an interface because it annotates the
+ * `.actions` block: MST constrains that to `ModelActions`, an index signature
+ * of functions, and only a type alias of an object literal gets the implicit
+ * index signature that satisfies it.
+ */
+export type ConfigNodeActions = {
+    setSubschema: (slotName: string, data: unknown) => unknown;
+    setSlot: (slotName: string, value: unknown) => void;
+};
+/**
+ * MST's node brand, restated. A config node carries its own schema here by
+ * polymorphic `this`, and `ConfigurationSchemaForModel` walks it back out —
+ * which is what every `getConf` / `readConfObject` / `setConf` slot-name
+ * constraint hangs off, so losing it switches the read-side check off with no
+ * error anywhere. `scripts/audit-config-read-types.ts` is the only thing that
+ * reports that; run it after touching this.
+ *
+ * Structurally identical to `IStateTreeNode<IT>`, but an alias rather than an
+ * interface: TypeScript infers an implicit index signature for an intersection
+ * only when every constituent is an alias or a mapped type, and that is what
+ * leaves a concrete config node — whose props are a mapped type with no index
+ * signature of its own — assignable to `AnyConfigurationModel`.
+ */
+export type ConfigNodeBrand<IT extends IAnyType> = {
+    readonly $treenode?: any;
+    readonly $__mstStateTreeNodeType__?: [IT] | [any];
+};
+/**
+ * The identifier a schema's `explicitIdentifier` installs, folded into the
+ * definition as if it were a declared string slot — which is what it is at
+ * runtime, `makeConfigurationSchemaModel` just builds it from the options rather
+ * than from the table. Folding it in rather than intersecting it onto `Type`
+ * keeps it out of `ConfigurationSchemaType`'s parameter list: as a parameter it
+ * reads as invariant (it lands in a `Record<K, …>` key position), which stops a
+ * concrete schema widening to `AnyConfigurationSchemaType`. Inheritance comes
+ * free, since `MergeConfigDef` already folds the base's whole definition in.
+ */
+export interface IdentifierSlotDef {
+    type: 'string';
+    defaultValue: '';
+}
+/**
+ * The `type` prop an `explicitlyTyped` schema installs, folded into the
+ * definition the same way and for the same reasons. Separate from
+ * `IdentifierSlotDef` despite the identical shape, because the runtime prop is
+ * `types.literal(modelName)` and this is where that would be said if the model
+ * name ever became a type parameter.
+ */
+export interface TypeSlotDef {
+    type: 'string';
+    defaultValue: '';
+}
+export type ConfigurationSlotName<SCHEMA> = IsAny<SCHEMA> extends true ? string : SCHEMA extends ConfigurationSchemaType<infer D, any> ? keyof D & string : 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
+ * callback string, or (for a `maybe*` 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 —
@@ -31,14 +145,7 @@ export type ConfigurationSlotName<SCHEMA> = SCHEMA extends undefined ? never : S
  */
 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>;
+} : unknown;
 /**
  * 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.
@@ -54,21 +161,24 @@ type SlotValueResolvedFromDef<DEF> = DEF extends {
  */
 interface SlotValueByType {
     stringArray: string[];
+    expressionArray: string[];
     stringArrayMap: Record<string, string[]>;
     numberMap: Record<string, number>;
+    stringMap: Record<string, string>;
     fileLocation: FileLocation;
+    maybeFileLocation: FileLocation | undefined;
     maybeNumber: number | undefined;
     maybeBoolean: boolean | undefined;
     maybeColor: string | undefined;
+    maybeString: 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.
+     * `any` for these only by accident: no `frozen` slot in the repo happens to
+     * default to a scalar.
      */
     frozen: any;
     maybeFrozen: any;
@@ -77,7 +187,9 @@ interface SlotValueByType {
     boolean: boolean;
     string: string;
     text: string;
+    featureField: string;
     color: string;
+    colorArray: string[];
 }
 /**
  * The two tables name the same builtin slot types, checked rather than
@@ -99,18 +211,37 @@ type SlotValueRawFromDef<DEF> = DEF extends AnyConfigurationSchemaType ? AnyConf
     model: ISimpleType<infer T extends string>;
 } ? DEF extends {
     type: 'maybeStringEnum';
-} ? T | undefined : T : DEF extends {
+} ? T | undefined : DEF extends {
+    type: 'stringEnumArray';
+} ? T[] : 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;
+type SubSchemaOf<SCHEMA, K> = IsAny<SCHEMA> extends true ? any : SCHEMA extends ConfigurationSchemaType<infer D, any> ? K extends keyof D ? D[K] : never : never;
+type SubSchemaSlotPath<SCHEMA> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? readonly string[] : {
+    [K in keyof D & string]: D[K] extends AnyConfigurationSchemaType ? readonly [K, ConfigurationSlotName<D[K]>] | readonly [K, ...SubSchemaSlotPath<D[K]>] : D[K] extends IAnyType | {
+        type: 'frozen' | 'maybeFrozen';
+    } ? readonly [K, ...string[]] : never;
+}[keyof D & string] : readonly string[];
 /**
- * what `resolveConf` yields: the same, minus the inherit sentinel on a
- * promotable slot — the cascade always produces a real value.
+ * The array paths a read may take into `SCHEMA`. Past one segment each is
+ * checked: a sub-schema's name, then one of its slot names or a deeper path. A
+ * head naming something other than a sub-schema — a pluggable adapter union, an
+ * array or map of sub-schemas, a `frozen` slot — keeps an unchecked tail, and a
+ * widened schema admits any `string[]`.
+ *
+ * A one-segment path stays unchecked: it is how a generic class body, where
+ * `SCHEMA` is unresolved, reads a slot at all (`FastaAdapterBase`).
  */
-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;
+export type ConfigurationSlotPath<SCHEMA> = readonly [] | readonly [string] | SubSchemaSlotPath<SCHEMA>;
+/** what a read of `PATH` into `SCHEMA` yields */
+export type ConfigurationSlotPathValue<SCHEMA, PATH> = PATH extends readonly [
+    infer HEAD,
+    ...infer REST
+] ? SubSchemaOf<SCHEMA, HEAD> extends infer SUB extends AnyConfigurationSchemaType ? REST extends readonly [infer SLOT extends string] ? ConfigurationSlotValue<SUB, SLOT> : ConfigurationSlotPathValue<SUB, REST> : 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]> : any : any;
 /**
  * Naming convention for config types, paired per schema:
  * - `XConfigSchema` is the MST IType (the schema itself). Use it for
@@ -125,7 +256,15 @@ export type ConfigurationSlotValueResolved<SCHEMA, K extends string> = SCHEMA ex
  * model-or-snapshot union, not a plain instance).
  */
 export type AnyConfigurationSchemaType = ConfigurationSchemaType<any, any>;
-export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType>;
+export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType> & Record<string, any>;
+/**
+ * A node of a pluggable element union — a track's, a display's, an adapter's —
+ * whichever member it is, naming its `type`. An interface rather than an
+ * intersection so a generated doc prints the name.
+ */
+export interface PluggableConfigNode extends AnyConfigurationModel {
+    type: string;
+}
 /**
  * The `XConfigModel` for a **field table** — a `*ConfigSchemaFields` export —
  * rather than for a whole assembled schema. What it is for is the cast a
@@ -144,7 +283,7 @@ export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType>;
  * `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>>>;
+export type ConfigModelForFields<FIELDS extends ConfigurationSchemaDefinition, BASE extends AnyConfigurationSchemaType | undefined = undefined> = Instance<ConfigurationSchemaType<MergeConfigDef<FIELDS, BASE>, 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:
@@ -154,8 +293,7 @@ export type ConfigModelForFields<FIELDS extends ConfigurationSchemaDefinition, B
  * ```
  *
  * 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
+ * cast to `AnyConfigurationModel` 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.
@@ -167,11 +305,12 @@ export type HostChecksSlotNames<HOST extends {
 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).
+ * plain snapshot of one. `session.tracks` holds plain base or merged configs
+ * that hydrate to MST only on first reference access, `getTrackById` also
+ * answers live assembly-sequence and connection nodes, 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/configuration/uriShorthand.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Expand a one-file adapter's `{ uri }` shorthand into the single location slot
+ * it declares, or pass a snapshot already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between the twenty-odd adapters
+ * reading one file (`bedLocation`, `bigWigLocation`, `hicLocation`,
+ * `pafLocation`, …). `expandTabixShorthand` is the indexed families' version.
+ */
+export declare function expandUriShorthand(snap: Record<string, unknown>, locationKey: string): Record<string, unknown>;

package/esm/configuration/uriShorthand.js

@@ -0,0 +1,16 @@
+import { fillLocations } from './fillLocations.js';
+/**
+ * Expand a one-file adapter's `{ uri }` shorthand into the single location slot
+ * it declares, or pass a snapshot already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between the twenty-odd adapters
+ * reading one file (`bedLocation`, `bigWigLocation`, `hicLocation`,
+ * `pafLocation`, …). `expandTabixShorthand` is the indexed families' version.
+ */
+export function expandUriShorthand(snap, locationKey) {
+    return snap.uri
+        ? fillLocations(snap, {
+            [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+        })
+        : snap;
+}

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

@@ -1,30 +1,24 @@
 import type PluginManager from '../../PluginManager.ts';
-import type { AnyConfigurationModel, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue } from '../../configuration/index.ts';
+import type { AnyConfigurationModel, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.ts';
 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?: 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.
+     * The reference sequence this instance reads, as the adapter config of the
+     * assembly the request that built it named. Part of the instance's identity:
+     * dataAdapterCache keys a {@link READS_REFERENCE} adapter on its config AND
+     * this, so one BAM shown on two genomes is two instances, each reading its
+     * own. Undefined when the building request named no genome, and a reference
+     * read then throws rather than guessing. Instance state rather than a
+     * per-call argument because `CramAdapter` binds its reference fetch into the
+     * `IndexedCramFile` at construction, inside @gmod/cram's slice cache.
      */
-    setSequenceAdapterConfig(config: Record<string, unknown> | undefined): void;
+    readonly sequenceAdapterConfig?: Record<string, unknown>;
+    static capabilities: string[];
+    constructor(config?: CONF, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager, sequenceAdapterConfig?: Record<string, unknown>);
     /** 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;
+    getConf<const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONF>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONF>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONF>>>(arg: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONF>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONF>, SLOT>;
 }

package/esm/data_adapters/BaseAdapter/BaseAdapter.js

@@ -6,32 +6,25 @@ export class BaseAdapter {
     config;
     getSubAdapter;
     pluginManager;
+    /**
+     * The reference sequence this instance reads, as the adapter config of the
+     * assembly the request that built it named. Part of the instance's identity:
+     * dataAdapterCache keys a {@link READS_REFERENCE} adapter on its config AND
+     * this, so one BAM shown on two genomes is two instances, each reading its
+     * own. Undefined when the building request named no genome, and a reference
+     * read then throws rather than guessing. Instance state rather than a
+     * per-call argument because `CramAdapter` binds its reference fetch into the
+     * `IndexedCramFile` at construction, inside @gmod/cram's slice cache.
+     */
     sequenceAdapterConfig;
     static capabilities = [];
-    constructor(config = EmptyConfig.create(), getSubAdapter, pluginManager) {
+    constructor(config = EmptyConfig.create(), getSubAdapter, pluginManager, sequenceAdapterConfig) {
         this.config = config;
         this.getSubAdapter = getSubAdapter;
         this.pluginManager = pluginManager;
+        this.sequenceAdapterConfig = sequenceAdapterConfig;
         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;
-    }
     /** shorthand for `readConfObject(this.config, arg)` */
     getConf(arg, args) {
         return readConfObject(this.config, arg, args);