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

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);

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

@@ -1,8 +1,10 @@
 import { BaseAdapter } from './BaseAdapter.ts';
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
+import type { FeatureTable } from '../../util/featureTable.ts';
 import type { Feature } from '../../util/simpleFeature.ts';
 import type { AugmentedRegion as Region } from '../../util/types/index.ts';
-import type { BaseOptions } from './types.ts';
+import type { FeatureDensity } from './featureDensity.ts';
+import type { BaseOptions, ZoomRange } from './types.ts';
 import type { Observable } from 'rxjs';
 /**
  * Base class for feature adapters to extend. Defines some methods that
@@ -75,11 +77,18 @@ export declare abstract class BaseFeatureDataAdapter<CONF extends AnyConfigurati
     /**
      * Convenience wrapper that collects {@link getFeatures} for a region into an
      * array — the common shape across RPC methods (RenderFeatureData, Manhattan,
-     * Wiggle, etc.). Pass `opts` so `statusCallback`/`stopToken` reach the
+     * Wiggle, etc.). Pass `opts` so `statusCallback`/`signal` reach the
      * adapter; omitting them means no download progress and a fetch that can't be
      * interrupted mid-flight.
      */
     getFeaturesArray(region: Region, opts?: BaseOptions): Promise<Feature[]>;
+    /**
+     * The features overlapping a region as the table a mark's declaration runs
+     * over: by default a table over {@link getFeaturesArray}. An adapter that
+     * already holds its rows as typed arrays answers a `ColumnTable` over them
+     * instead, and makes no object per row.
+     */
+    getFeatureTable(region: Region, opts?: BaseOptions): Promise<FeatureTable>;
     /**
      * {@link getFeaturesArray} across multiple regions — collects
      * {@link getFeaturesInMultipleRegions} into an array. The common shape in
@@ -117,6 +126,35 @@ export declare abstract class BaseFeatureDataAdapter<CONF extends AnyConfigurati
      * agent-docs/reference/REGION_TOO_LARGE.md.
      */
     getRegionByteSize(_regions: Region[], _opts?: BaseOptions): Promise<number | undefined>;
+    /**
+     * The bp/px interval over which this adapter answers a fetch from the same
+     * zoom level it answers `opts.bpPerPx` from, so a display holding the answer
+     * refetches only when the view leaves it. The default, `undefined`, is an
+     * answer that does not depend on the zoom, which a display never refetches
+     * for a zoom. An adapter that reads `bpPerPx` declares its range here
+     * (`BigWigAdapter` from its header's zoom levels).
+     */
+    getZoomRange(_opts?: BaseOptions): Promise<ZoomRange | undefined>;
+    /**
+     * The interval every value this adapter answers lies in by definition, as a
+     * fraction lies in [0, 1], which a value scale's unpinned ends stand at
+     * rather than following the loaded data, so the axis reads alike at every
+     * locus. The default, `undefined`, is a quantity with no such bounds, whose
+     * axis autoscales. `GCContentAdapter` declares [0, 1] for GC content and none
+     * for skew.
+     */
+    getValueDomain(_opts?: BaseOptions): Promise<[number, number] | undefined>;
+    /**
+     * Features per bin over each region, at the view's `bpPerPx`, for the density
+     * tier the display draws where the region-too-large gate refused the
+     * features. The default reads the `densityAdapter` sidecar slot
+     * (`densityAdapterConfigSchemaFields`) through `getSubAdapter`; `undefined`
+     * means no tier, and the banner stands. ADR-102 records why no index
+     * estimate stands in for a missing sidecar.
+     */
+    getFeatureDensity(regions: Region[], opts: BaseOptions & {
+        bpPerPx: number;
+    }): Promise<FeatureDensity[] | undefined>;
     getSources(regions: Region[], opts?: BaseOptions): Promise<{
         name: string;
         color?: string;

package/esm/data_adapters/BaseAdapter/BaseFeatureDataAdapter.js

@@ -1,9 +1,12 @@
 import { firstValueFrom, merge } from 'rxjs';
 import { toArray } from 'rxjs/operators';
+import { asTable } from '../../util/featureTable.js';
 import { createStatusFanOut } from '../../util/progress.js';
 import { blankStats, scoresToStats } from '../../util/stats.js';
 import { BaseAdapter } from './BaseAdapter.js';
+import { isSubAdapterConfig } from './featureDensity.js';
 import { aggregateQuantitativeStats } from './stats.js';
+import { isFeatureAdapter } from './util.js';
 /**
  * Base class for feature adapters to extend. Defines some methods that
  * subclasses must implement.
@@ -47,13 +50,22 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
     /**
      * Convenience wrapper that collects {@link getFeatures} for a region into an
      * array — the common shape across RPC methods (RenderFeatureData, Manhattan,
-     * Wiggle, etc.). Pass `opts` so `statusCallback`/`stopToken` reach the
+     * Wiggle, etc.). Pass `opts` so `statusCallback`/`signal` reach the
      * adapter; omitting them means no download progress and a fetch that can't be
      * interrupted mid-flight.
      */
     getFeaturesArray(region, opts = {}) {
         return firstValueFrom(this.getFeatures(region, opts).pipe(toArray()));
     }
+    /**
+     * The features overlapping a region as the table a mark's declaration runs
+     * over: by default a table over {@link getFeaturesArray}. An adapter that
+     * already holds its rows as typed arrays answers a `ColumnTable` over them
+     * instead, and makes no object per row.
+     */
+    async getFeatureTable(region, opts = {}) {
+        return asTable(await this.getFeaturesArray(region, opts));
+    }
     /**
      * {@link getFeaturesArray} across multiple regions — collects
      * {@link getFeaturesInMultipleRegions} into an array. The common shape in
@@ -76,10 +88,7 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
      * features over a region, primarily used for quantitative tracks
      */
     async getRegionQuantitativeStats(region, opts) {
-        const feats = this.getFeatures(region, {
-            ...opts,
-            statsEstimationMode: true,
-        });
+        const feats = this.getFeatures(region, opts);
         return scoresToStats(region, feats);
     }
     /**
@@ -110,6 +119,60 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
     async getRegionByteSize(_regions, _opts) {
         return undefined;
     }
+    /**
+     * The bp/px interval over which this adapter answers a fetch from the same
+     * zoom level it answers `opts.bpPerPx` from, so a display holding the answer
+     * refetches only when the view leaves it. The default, `undefined`, is an
+     * answer that does not depend on the zoom, which a display never refetches
+     * for a zoom. An adapter that reads `bpPerPx` declares its range here
+     * (`BigWigAdapter` from its header's zoom levels).
+     */
+    async getZoomRange(_opts) {
+        return undefined;
+    }
+    /**
+     * The interval every value this adapter answers lies in by definition, as a
+     * fraction lies in [0, 1], which a value scale's unpinned ends stand at
+     * rather than following the loaded data, so the axis reads alike at every
+     * locus. The default, `undefined`, is a quantity with no such bounds, whose
+     * axis autoscales. `GCContentAdapter` declares [0, 1] for GC content and none
+     * for skew.
+     */
+    async getValueDomain(_opts) {
+        return undefined;
+    }
+    /**
+     * Features per bin over each region, at the view's `bpPerPx`, for the density
+     * tier the display draws where the region-too-large gate refused the
+     * features. The default reads the `densityAdapter` sidecar slot
+     * (`densityAdapterConfigSchemaFields`) through `getSubAdapter`; `undefined`
+     * means no tier, and the banner stands. ADR-102 records why no index
+     * estimate stands in for a missing sidecar.
+     */
+    async getFeatureDensity(regions, opts) {
+        const sidecar = this.getConf(['densityAdapter']);
+        const resolved = isSubAdapterConfig(sidecar) && this.getSubAdapter
+            ? (await this.getSubAdapter(sidecar)).dataAdapter
+            : undefined;
+        if (resolved && !isFeatureAdapter(resolved)) {
+            throw new Error(`densityAdapter ${isSubAdapterConfig(sidecar) ? sidecar.type : ''} is not a feature adapter`);
+        }
+        return resolved
+            ? Promise.all(regions.map(async (region) => {
+                const features = await resolved.getFeaturesArray(region, opts);
+                const starts = new Uint32Array(features.length);
+                const ends = new Uint32Array(features.length);
+                const scores = new Float32Array(features.length);
+                features.forEach((feature, i) => {
+                    const score = feature.get('score');
+                    starts[i] = feature.get('start');
+                    ends[i] = feature.get('end');
+                    scores[i] = score === undefined ? 0 : score;
+                });
+                return { starts, ends, scores };
+            }))
+            : undefined;
+    }
     async getSources(regions, opts = {}) {
         const features = await this.getFeaturesInMultipleRegionsArray(regions, opts);
         const sources = new Set();