@jbrowse/core 5.0.0-beta.3 → 5.0.0-beta.7

package/esm/util/markEncodingTypes.d.ts

@@ -0,0 +1,331 @@
+/**
+ * #api
+ * Where a channel's value comes from: a feature field name, read natively
+ * (`feature.get(name)`), or a `jexl:` expression over `feature` — the opt-in
+ * escape, three orders of magnitude slower per feature.
+ */
+export type FieldRef = string;
+/**
+ * #api
+ * The ramp a continuous colour scale samples: a named ramp, or evenly spaced
+ * CSS colour stops.
+ */
+export type RampRef = 'viridis' | string[];
+/**
+ * #api
+ * A field bound to a categorical scale: each distinct value takes one entry
+ * of the channel's range — a palette entry for `color`, a glyph name for
+ * `glyph`. With a `domain`, the listed values take the range in that order
+ * and whatever else the region meets follows, sorted; without one each value
+ * derives its entry from itself (an integer takes the slot it names, anything
+ * else hashes in), so every region agrees on a value it shares with another at
+ * the cost of an occasional collision, and `domain` is the way to spend the
+ * range deliberately.
+ */
+export interface CategoricalRef {
+    field: FieldRef;
+    scale: 'categorical';
+    domain?: (string | number)[];
+}
+/**
+ * #api
+ * How a mark's `color` channel resolves. A CSS colour or a `jexl:` expression
+ * returning one paints per feature with no scale; the two object forms bind a
+ * field to a scale, which is what a legend can describe. A continuous scale
+ * reads the field through `domain` (the region's own extremes when absent)
+ * into `ramp`, and there a listed `domain` is what pins the answer across a
+ * whole view.
+ */
+export type ColorEncoding = string | (CategoricalRef & {
+    palette?: string[];
+}) | {
+    field: FieldRef;
+    scale: 'linear' | 'log';
+    domain?: [number, number];
+    ramp?: RampRef;
+};
+/**
+ * #api
+ * How a mark's `y` channel resolves: a feature field (or `jexl:` expression)
+ * read on a linear scale over the loaded regions' extremes, or the same field
+ * with the scale spelled out — `log` to read the domain logarithmically,
+ * `domain` to pin `[min, max]` instead of autoscaling. The declaration is the
+ * one owner: the display's axis, its ticks and the shader's placement are all
+ * resolved from it.
+ *
+ * `resolve` is which axis the mark reads. `shared` — the default — folds it
+ * into the display's one y domain with every other mark. `independent` gives
+ * it a domain folded from its layers alone and a second axis on the right, so
+ * a coverage run and the raw features can share a plot; one mark per display
+ * may ask for it.
+ */
+export type ValueEncoding = FieldRef | {
+    field: FieldRef;
+    scale?: 'linear' | 'log';
+    domain?: [number, number];
+    resolve?: 'shared' | 'independent';
+};
+export type GlyphName = 'disc' | 'triangle' | 'diamond';
+/**
+ * #api
+ * A {@link GlyphName}, a `jexl:` expression over `feature` returning one, or
+ * a field bound to a categorical scale whose `range` lists the glyph names
+ * handed out — the three glyphs, in order, when absent.
+ */
+export type GlyphEncoding = GlyphName | `jexl:${string}` | (CategoricalRef & {
+    range?: GlyphName[];
+});
+/**
+ * #api
+ * The declared mapping from a feature's fields to a mark's channels. `x`
+ * defaults to `start` and `x2` to `end`; a mark that plots no value leaves `y`
+ * off. `glyph` is read by the `point` shape alone, `row` — an integer field,
+ * 0 where missing — by the `span` shape, which stacks a feature on the band
+ * it names.
+ */
+export interface MarkEncoding {
+    x?: FieldRef;
+    x2?: FieldRef;
+    y?: ValueEncoding;
+    row?: FieldRef;
+    color?: ColorEncoding;
+    glyph?: GlyphEncoding;
+}
+/**
+ * #api
+ * The lanes a caller asks the encoder to fill, beyond `x`, `x2` and
+ * `featureIndex`, which every payload carries: a shape's channels, and
+ * `index` for the Flatbush a hover reads. A lane not asked for is neither
+ * allocated nor transferred, and a caller that never hovers declines the
+ * index, which is most of the encoder's cost after the walk.
+ */
+export type LaneName = 'y' | 'color' | 'colorValue' | 'glyph' | 'row' | 'index';
+/**
+ * #api
+ * The scale a colour channel was resolved through, as the legend reads it —
+ * the same table the colours in the payload came from, so the key cannot
+ * disagree with the painting.
+ */
+export type ColorScaleTable = {
+    kind: 'categorical';
+    field: string;
+    entries: {
+        label: string;
+        color: number;
+    }[];
+} | {
+    kind: 'ramp';
+    field: string;
+    scale: 'linear' | 'log';
+    /** What the ramp spans here: the declared domain, else `extent`. */
+    domain: [number, number];
+    /** Whether `domain` was declared, and so already agrees across regions. */
+    pinned: boolean;
+    /** This region's own extremes of the field, what a display unions. */
+    extent: [number, number];
+    lut: Uint8Array;
+};
+/**
+ * #api
+ * The scale a glyph channel was resolved through: which glyph each value of
+ * the field took.
+ */
+export interface GlyphScaleTable {
+    kind: 'glyph';
+    field: string;
+    entries: {
+        label: string;
+        glyph: GlyphName;
+    }[];
+}
+/**
+ * #api
+ * Any channel's scale table; the kind names the channel.
+ */
+export type ScaleTable = ColorScaleTable | GlyphScaleTable;
+/**
+ * #api
+ * One encoding's channels over one region's features, dense and
+ * index-aligned: instance `i` of every array is the same feature, and
+ * `featureIndex[i]` says which one of the input list it was. A lane is
+ * present when the caller asked for it ({@link LaneName}); {@link Encoded}
+ * is this type with a known lane set required.
+ */
+export interface EncodedChannels {
+    count: number;
+    /**
+     * Features the walk left out: one whose `x`, `x2` or `y` read as missing
+     * or not a number. A mistyped field skips every feature, so a display
+     * reads this beside `count` to say so.
+     */
+    skipped: number;
+    x: Uint32Array;
+    x2: Uint32Array;
+    featureIndex: Uint32Array;
+    y?: Float32Array;
+    color?: Uint32Array;
+    /**
+     * The raw values of a ramp colour channel, for a caller that named the
+     * `colorValue` lane: the scale then resolves on the main thread against a
+     * domain unioned over the loaded regions, and `scale.extent` is this
+     * region's contribution to it.
+     */
+    colorValue?: Float32Array;
+    glyph?: Uint8Array;
+    row?: Uint32Array;
+    /** The finite `y` extremes, `Infinity`/`-Infinity` when nothing plotted. */
+    yMin: number;
+    yMax: number;
+    /** A Flatbush over (x, y, x2, y), when `index` was asked for and `count` is not 0. */
+    flatbushData?: ArrayBuffer;
+    /** The colour channel's table, when `color` is a scale. */
+    scale?: ColorScaleTable;
+    /** The glyph channel's table, when `glyph` is a scale. */
+    glyphScale?: GlyphScaleTable;
+}
+/**
+ * #api
+ * {@link EncodedChannels} with the lanes in `L` present — what
+ * `encodeFeatures` answers a caller that named them.
+ */
+export type Encoded<L extends LaneName> = EncodedChannels & Required<Pick<EncodedChannels, Exclude<L, 'index'>>>;
+/**
+ * #api
+ * One layer of a `CoreEncodeFeatures` request: the encoding to evaluate and
+ * the lanes the display's shape reads.
+ */
+export interface LayerRequest {
+    encoding: MarkEncoding;
+    lanes: LaneName[];
+    /** This layer's own steps, run after the request's shared ones. */
+    transform?: TransformStep[];
+}
+/**
+ * #api
+ * What `CoreEncodeFeatures` answers for one region: `layers[i]` is the
+ * request's `layers[i]` over the region's features, so a display's mark
+ * list indexes straight into it.
+ */
+export interface EncodedFeaturesResult {
+    layers: EncodedChannels[];
+    bytes?: number;
+}
+/**
+ * #api
+ * Keep the features a `jexl:` expression over `feature` admits.
+ */
+export interface FilterStep {
+    type: 'filter';
+    expr: string;
+}
+/**
+ * #api
+ * Write a `jexl:` expression's value over `feature` into the field `as` of
+ * every feature.
+ */
+export interface FormulaStep {
+    type: 'formula';
+    expr: string;
+    as: string;
+}
+/**
+ * #api
+ * Snap every feature to the genome-aligned bin of `step` bp its `field`
+ * (`start` by default) falls in, writing the bin's edges over the fields
+ * `as` names — `start` and `end` by default, so an `aggregate` grouped by
+ * those counts per bin and the bar spans the bin.
+ */
+export interface BinStep {
+    type: 'bin';
+    step: number;
+    field?: FieldRef;
+    as?: [string, string];
+}
+/**
+ * #api
+ * One summary over a group: `count` needs no field; `sum`, `mean`, `min` and
+ * `max` read one, skipping values that are not numbers. The output field is
+ * `as`, else `count` or `<op>_<field>`.
+ */
+export interface AggregateOp {
+    op: 'count' | 'sum' | 'mean' | 'min' | 'max';
+    field?: FieldRef;
+    as?: string;
+}
+/**
+ * #api
+ * One feature per distinct `groupby` value set (one for the whole region
+ * with none), spanning its members' extent, carrying the group's fields and
+ * every `ops` entry.
+ */
+export interface AggregateStep {
+    type: 'aggregate';
+    groupby?: FieldRef[];
+    ops: AggregateOp[];
+}
+/**
+ * #api
+ * Replace the features with runs of constant depth: how many of them overlap
+ * each stretch of the region, in a field `as` (`coverage` by default), with
+ * the stretches nothing overlaps left out.
+ */
+export interface CoverageStep {
+    type: 'coverage';
+    as?: string;
+}
+/**
+ * #api
+ * Fan each feature out into one feature per element of an array-valued field
+ * — `subfeatures`, so a gene answers its transcripts and a transcript its
+ * exons. Each answer reads the element's own fields first and the feature it
+ * came from for everything else, so an exon still knows its gene's name and
+ * strand. A feature whose field holds no array drops out unless `keepEmpty`
+ * says otherwise.
+ */
+export interface FlattenStep {
+    type: 'flatten';
+    field?: FieldRef;
+    /** Written with the element's position in its parent's array. */
+    index?: string;
+    keepEmpty?: boolean;
+}
+/**
+ * #api
+ * Assign every feature the lowest row on which it overlaps nothing already
+ * there — greedy first fit in start order, the packing a pileup is — and
+ * write it to the field `as` (`row`). `fields` names the interval read
+ * (`start`, `end`); `padding` is bp of clearance kept between two features
+ * sharing a row; `groupby` packs each distinct value set on its own rows,
+ * each numbered from 0. The answer is the input in start order, so a `span`
+ * encoding `row` stacks it.
+ */
+export interface StackStep {
+    type: 'stack';
+    as?: string;
+    fields?: [string, string];
+    padding?: number;
+    groupby?: FieldRef[];
+}
+/**
+ * #api
+ * One step over the features before a layer is encoded, named by `type` the
+ * way GenomeSpy spells a transform; every step runs in order and the next
+ * reads what the last answered.
+ */
+export type TransformStep = FilterStep | FormulaStep | FlattenStep | BinStep | AggregateStep | CoverageStep | StackStep;
+export type CoreEncodeFeaturesArgs = {
+    adapterConfig: Record<string, unknown>;
+    region: {
+        refName: string;
+        start: number;
+        end: number;
+        assemblyName: string;
+    };
+    layers: LayerRequest[];
+    /** The steps over the features, in order, before every layer encodes. */
+    transform?: TransformStep[];
+    /** Sugar for leading `filter` steps: `jexl:`-prefixed expressions. */
+    filters?: string[];
+    byteLimit?: number;
+    sequenceAdapter?: Record<string, unknown>;
+};

package/esm/util/markEncodingTypes.js

@@ -0,0 +1,8 @@
+// The declared shape of a mark encoding and what evaluating one produces —
+// split from markEncoding.ts because that file's runtime half reaches
+// render-core's whole HAL/color-ramp graph for encodeFeatures' native scale
+// tables, and RpcRegistry.ts needs only these types for CoreEncodeFeatures'
+// wire shape. Importing them from markEncoding.ts would carry that graph into
+// every leaf that reaches the RPC registry. scripts/moduleClosure.test.ts
+// holds the ceiling.
+export {};

package/esm/util/renderToStaticMarkup.js

@@ -50,7 +50,7 @@ export function renderToStaticMarkup(node) {
     // they cannot parse, so the alpha is stripped rather than left to break the
     // whole shape. It is *dropped*, not converted, so a translucent color exports
     // fully opaque: components that need transparency to survive set a separate
-    // opacity attribute instead (`CrossHatches`, `MultiWiggleOverlayLines`).
+    // opacity attribute instead (`CrossHatches`, `RowSeparatorLines`).
     //
     // Rewriting `fill="rgba(r,g,b,a)"` into `fill="rgb(r,g,b)" fill-opacity="a"`
     // would preserve the appearance and let those two drop their workarounds, but

package/esm/util/starFusion.d.ts

@@ -0,0 +1,26 @@
+export type FusionBreakpoint = {
+    refName: string;
+    start: number;
+    end: number;
+    strand?: number;
+    /** which way the sequence this end keeps runs from it: 1 right, -1 left, 0 unknown */
+    mateDirection: number;
+};
+/**
+ * The column names of a STAR-Fusion `fusion_predictions.tsv` header line. The
+ * leading `#` is not universal across STAR-Fusion versions and wrappers, so it
+ * is stripped when present. Throws a named error for a header without the two
+ * breakpoint columns, which is the wrong file or the wrong File Type guess.
+ */
+export declare function starFusionColumns(header: string | undefined): string[];
+/**
+ * A STAR-Fusion `refName:pos:strand` breakpoint as an interbase feature, read
+ * from the RIGHT because a refName may contain colons (GRCh38's
+ * `HLA-A*01:01:01:01`). The position is 1-based in the file. The strand is the
+ * gene's transcription strand, and the fusion transcript keeps the donor's
+ * sequence 5' of the junction and the acceptor's 3' of it, so `mateDirection`
+ * is the strand negated for a donor and taken as read for an acceptor: the
+ * convention `parseSvAlt` states for a breakend and the paired-arc display
+ * draws its ticks from.
+ */
+export declare function parseStarFusionBreakpoint(str: string, isDonor: boolean): FusionBreakpoint;

package/esm/util/starFusion.js

@@ -0,0 +1,37 @@
+/**
+ * The column names of a STAR-Fusion `fusion_predictions.tsv` header line. The
+ * leading `#` is not universal across STAR-Fusion versions and wrappers, so it
+ * is stripped when present. Throws a named error for a header without the two
+ * breakpoint columns, which is the wrong file or the wrong File Type guess.
+ */
+export function starFusionColumns(header) {
+    const columns = (header?.startsWith('#') ? header.slice(1) : header)?.split('\t') ?? [];
+    const missing = ['LeftBreakpoint', 'RightBreakpoint'].filter(c => !columns.includes(c));
+    if (missing.length) {
+        throw new Error(`Not a STAR-Fusion file: no ${missing.join(' or ')} column. Found: ${columns.slice(0, 6).join(', ')}`);
+    }
+    return columns;
+}
+/**
+ * A STAR-Fusion `refName:pos:strand` breakpoint as an interbase feature, read
+ * from the RIGHT because a refName may contain colons (GRCh38's
+ * `HLA-A*01:01:01:01`). The position is 1-based in the file. The strand is the
+ * gene's transcription strand, and the fusion transcript keeps the donor's
+ * sequence 5' of the junction and the acceptor's 3' of it, so `mateDirection`
+ * is the strand negated for a donor and taken as read for an acceptor: the
+ * convention `parseSvAlt` states for a breakend and the paired-arc display
+ * draws its ticks from.
+ */
+export function parseStarFusionBreakpoint(str, isDonor) {
+    const parts = str.split(':');
+    const strandStr = parts.length >= 3 ? parts.pop() : undefined;
+    const pos = parts.length >= 2 ? +parts.pop() : Number.NaN;
+    const strand = strandStr === '+' ? 1 : strandStr === '-' ? -1 : undefined;
+    return {
+        refName: parts.join(':'),
+        start: pos - 1,
+        end: pos,
+        strand,
+        mateDirection: strand === undefined ? 0 : isDonor ? -strand : strand,
+    };
+}

package/esm/util/trackConfigDelta.d.ts

@@ -22,10 +22,8 @@
  * What it is NOT free to conflate is a removal with a reset. Both diff to an
  * empty delta, and `SessionTracks.updateTrackConfiguration` used to read that as
  * "the edit netted back to the base" and revert the track's working copy — which
- * undid a removal on screen 400ms after it landed. Promotable slots made that
- * reachable rather than rare: a slider row's reset unsets its slot, and an
- * admin config is free to set one. That branch now keeps the working copy; see
- * the comment there.
+ * undid a removal on screen 400ms after it landed. That branch now keeps the
+ * working copy; see the comment there.
  *
  * `displays` is merged by `displayId` so an edit to one display doesn't pin the
  * others. Nested config objects (e.g. `adapter`) recurse. Any other array (value
@@ -58,10 +56,8 @@ export declare function mergeTrackConfig(base: Record<string, unknown>, delta: R
 /** A single overridden slot: the dotted `path`, its base `from` and edited `to`. */
 export interface TrackConfigChange {
     /**
-     * Where the setting lives, and — for a row a UI can revert — its **address**:
-     * product-core's `resetDisplayDefault` parses a promoted display-type
-     * default's path back into the type and slot it clears. So a producer that
-     * wants a friendlier heading sets `label` and leaves this alone.
+     * Where the setting lives. A producer that wants a friendlier heading sets
+     * `label` and leaves this alone.
      */
     path: string[];
     from: Json;

package/esm/util/trackConfigDelta.js

@@ -22,10 +22,8 @@
  * What it is NOT free to conflate is a removal with a reset. Both diff to an
  * empty delta, and `SessionTracks.updateTrackConfiguration` used to read that as
  * "the edit netted back to the base" and revert the track's working copy — which
- * undid a removal on screen 400ms after it landed. Promotable slots made that
- * reachable rather than rare: a slider row's reset unsets its slot, and an
- * admin config is free to set one. That branch now keeps the working copy; see
- * the comment there.
+ * undid a removal on screen 400ms after it landed. That branch now keeps the
+ * working copy; see the comment there.
  *
  * `displays` is merged by `displayId` so an edit to one display doesn't pin the
  * others. Nested config objects (e.g. `adapter`) recurse. Any other array (value

package/esm/util/tracks.d.ts

@@ -383,11 +383,17 @@ export declare function viewDisplayNames(pluginManager: PluginManager, viewType:
  *   so the pickers agree on it.
  */
 export declare function viewCanDisplayTrack(pluginManager: PluginManager, viewDisplays: Set<string>, trackType: string): boolean;
-export declare function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, }: {
+export declare function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, preferredDisplayTypes, }: {
     declaredDisplays: DisplayConfSnapshot[];
     requestedType: string | undefined;
     trackDisplayTypes: string[];
     viewDisplayTypes: string[];
+    /**
+     * The display types the view registered as its own, ahead of those it
+     * inherits through `extendedName`: a variant track on the circular view
+     * draws its chords, not the linear display the view also accepts as a ring.
+     */
+    preferredDisplayTypes?: Set<string>;
 }): {
     type: string;
     conf: DisplayConfSnapshot | undefined;

package/esm/util/tracks.js

@@ -564,10 +564,31 @@ export function viewCanDisplayTrack(pluginManager, viewDisplays, trackType) {
             .getTrackType(trackType)
             .displayTypes.some(d => viewDisplays.has(d.name)));
 }
-export function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, }) {
+export function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, preferredDisplayTypes = new Set(), }) {
     const supported = new Set(viewDisplayTypes);
-    const type = requestedType ??
-        declaredDisplays.find(d => supported.has(d.type))?.type ??
+    // A requested type is CHECKED, not taken on faith. It used to pass straight
+    // through: an unsupported or misspelled one produced a synthesized
+    // `<trackId>-<type>` displayId that no config declares, and the display
+    // configuration reference then resolved that dangling id back to the track's
+    // DEFAULT display by type — so a caller that asked for read arcs got the
+    // pileup, and every layer reported success. The caller turns this
+    // `undefined` into an error naming what the track can be drawn as.
+    //
+    // Callers pass a CANONICAL name (resolveTrackDisplayChoice resolves an alias
+    // first), because these two lists hold canonical names only.
+    if (requestedType !== undefined) {
+        return supported.has(requestedType) &&
+            trackDisplayTypes.includes(requestedType)
+            ? {
+                type: requestedType,
+                conf: declaredDisplays.find(d => d.type === requestedType),
+            }
+            : undefined;
+    }
+    const declared = declaredDisplays.filter(d => supported.has(d.type));
+    const type = declared.find(d => preferredDisplayTypes.has(d.type))?.type ??
+        declared[0]?.type ??
+        trackDisplayTypes.find(name => preferredDisplayTypes.has(name)) ??
         trackDisplayTypes.find(name => supported.has(name));
     return type === undefined
         ? undefined
@@ -637,14 +658,32 @@ function resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inline
     // getContainingView already resolves to for everything else beneath it.
     const view = isViewModel(self) ? self : getContainingView(self);
     const viewType = pluginManager.getViewType(view.type);
+    const trackDisplayTypes = trackType.displayTypes.map(d => d.name);
+    const viewDisplayTypes = viewType.displayTypes.map(d => d.name);
+    // An alias first, so a session spec or a caller naming a pre-consolidation
+    // display type (`LinearPileupDisplay`) reaches the type that replaced it
+    // instead of being refused — and so the membership checks below, which are
+    // over canonical names, ask the right question.
+    const requested = displayInitialSnapshot.type;
+    const requestedType = requested === undefined
+        ? undefined
+        : pluginManager.resolveDisplayTypeRecord(requested)?.name;
     const picked = pickDisplayForView({
         declaredDisplays: conf.displays ?? [],
-        requestedType: displayInitialSnapshot.type,
-        trackDisplayTypes: trackType.displayTypes.map(d => d.name),
-        viewDisplayTypes: viewType.displayTypes.map(d => d.name),
+        requestedType,
+        trackDisplayTypes,
+        viewDisplayTypes,
+        preferredDisplayTypes: new Set(viewType.displayTypes
+            .filter(d => d.viewType === view.type)
+            .map(d => d.name)),
     });
     if (!picked) {
-        throw new Error(`Could not find a compatible display for view type ${view.type}`);
+        const drawable = trackDisplayTypes.filter(name => viewDisplayTypes.includes(name));
+        throw new Error(requested === undefined
+            ? `Could not find a compatible display for view type ${view.type}`
+            : `Track "${trackId}" cannot be shown as "${requested}" in a ${view.type}. ${drawable.length > 0
+                ? `It takes: ${drawable.join(', ')}`
+                : 'This view draws none of its display types'}`);
     }
     return { rawConf, conf, trackType, picked };
 }
@@ -727,6 +766,32 @@ inlineConf) {
         // took the message away with it.
         const displaySettings = Object.fromEntries(Object.entries(displayInitialSnapshot).filter(([key]) => key !== 'type'));
         const report = track.applyDisplaySettings(displaySettings);
+        // A key that reached NOTHING, told apart from the ones `unapplied` holds
+        // legitimately. `unapplied` means "not a config slot", which covers both an
+        // MST display prop the snapshot spread above already applied and a
+        // misspelling that did nothing at all — so reporting the list wholesale
+        // called a correct spec broken, and reporting none of it let
+        // `{ trackId, colorSchem: 'x' }` load a plausible track with the setting
+        // silently missing. The display's own model type says which is which.
+        // Asked of the display NODE, not of its model type: `type.properties` sees
+        // declared props and misses everything else a key can legitimately reach —
+        // a volatile the snapshot spread above just set (`resolution` on the GC
+        // content display is one) reads as unreached and gets reported over a
+        // correct call.
+        // `unapplied` holds three kinds of entry, and only one of them means the
+        // key did nothing at all: applyDisplaySettings annotates `type` and the
+        // "a setter exists, pass allowSetters" case in parentheses, and pushes a
+        // BARE key when the display has neither a slot nor a setter for it. So the
+        // bare ones are the candidates, and the node itself settles the rest — the
+        // snapshot spread above may already have landed the key as a prop or a
+        // volatile, which is what `resolution` on the GC content display is.
+        const drawn = track.displays[0];
+        const reachedNothing = drawn
+            ? report.unapplied.filter(entry => !entry.includes(' (') && !(entry in drawn))
+            : [];
+        if (reachedNothing.length > 0) {
+            session.notifyError(`Track "${trackId}" ignored ${reachedNothing.join(', ')}: neither a setting the ${displayType} accepts nor one of its properties`);
+        }
         if (report.failed.length) {
             session.notifyError(`Track "${trackId}" rejected ${report.failed
                 .map(f => `${f.key}: ${f.error}`)

package/esm/util/types/index.d.ts

@@ -1,6 +1,6 @@
 import type { ViewSnapshotInput } from '../../PluginManager.ts';
 import type TextSearchManager from '../../TextSearch/TextSearchManager.ts';
-import type { AnyConfigurationModel, ResolvableDisplay } from '../../configuration/index.ts';
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { BaseInternetAccountModel } from '../../pluggableElementTypes/models/index.ts';
 import type { PluginDefinition } from '../../pluginDefinitions.ts';
 import type RpcManager from '../../rpc/RpcManager.ts';
@@ -82,8 +82,6 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     setPreferenceOverride: (key: string, value: unknown) => void;
     clearPreferenceOverrides: () => void;
     setScrollZoom: (flag: boolean) => void;
-    getDisplayTypeDefault: (displayType: string, slot: string) => unknown;
-    setDisplayTypeDefault: (displayType: string, slot: string, value: unknown) => void;
     hovered: unknown;
     setHovered: (arg: unknown) => void;
     setFocusedViewId?: (id: string) => void;
@@ -425,7 +423,10 @@ export interface TrackContainer {
         configuration: {
             trackId: string;
         };
-        displays: ResolvableDisplay[];
+        displays: {
+            type: string;
+            configuration: AnyConfigurationModel;
+        }[];
     }[];
     assemblyNames?: string[];
     /**
@@ -479,6 +480,13 @@ export interface AbstractViewModel {
      * the view itself.
      */
     trackContainerFor?: (id: string) => TrackContainer | undefined;
+    /**
+     * the node a display in this view lays its regions out against, where that
+     * is not the view's own box — the circular view's strip. A display's
+     * foundation reads its host through `containingHost`, which answers this
+     * before the view itself.
+     */
+    regionHost?: unknown;
     /**
      * every track container this view owns INSTEAD of a `tracks` array of its
      * own. The synteny view is the only one: its tracks hang off the levels, one