@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/pluggableElementTypes/models/components/SaveTrackData.js

@@ -1,158 +1,130 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useState } from 'react';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
 import ContentCopyIcon from '@mui/icons-material/ContentCopy';
 import GetAppIcon from '@mui/icons-material/GetApp';
-import HelpOutlineIcon from '@mui/icons-material/HelpOutline';
-import { Button, DialogActions, DialogContent, DialogContentText, DialogTitle, FormControl, FormControlLabel, FormLabel, IconButton, Radio, RadioGroup, TextField, } from '@mui/material';
-import copy from 'copy-to-clipboard';
-import { saveAs } from 'file-saver-es';
+import HelpOutlineIcon from '@mui/icons-material/HelpOutlined';
+import { Button, DialogContentText, FormControl, FormControlLabel, FormLabel, IconButton, Radio, RadioGroup, TextField, } from '@mui/material';
 import { observer } from 'mobx-react';
-import { getConf } from "../../../configuration/index.js";
-import { Dialog, ErrorMessage } from "../../../ui/index.js";
-import { getContainingView, getEnv, getSession } from "../../../util/index.js";
-import { getRpcSessionId } from "../../../util/tracks.js";
-import { makeStyles } from "../../../util/tss-react/index.js";
+import { getConf } from '../../../configuration/index.js';
+import { CopyToClipboardButton, ErrorBanner, InfoDialog, } from '../../../ui/index.js';
+import { assembleLocStrings, getContainingView, getDisplayStr, saveAs, statusProgressLabel, } from '../../../util/index.js';
+import { makeStyles } from '../../../util/tss-react/index.js';
+import { useFetch } from '../../../util/useFetch.js';
+import { fetchTrackData, roundRegions } from './fetchTrackData.js';
+const MAX_PREVIEW_CHARS = 500_000;
+const TOO_BIG_TO_PREVIEW = 'File greater than 500kb, too large to view here. Click "Download" to save results to file';
 const useStyles = makeStyles()({
-    root: {
-        width: '80em',
-    },
+    root: { width: '80em' },
     textAreaFont: {
         fontFamily: 'Courier New',
         whiteSpace: 'pre',
     },
+    formatRow: {
+        display: 'flex',
+        alignItems: 'center',
+        gap: '4px',
+    },
 });
-async function fetchFeatures(track, regions) {
-    const session = getSession(track);
-    const { rpcManager } = session;
-    const adapterConfig = getConf(track, ['adapter']);
-    const sessionId = getRpcSessionId(track);
-    return rpcManager.call(sessionId, 'CoreGetFeatures', {
-        adapterConfig,
+/**
+ * The export in the selected format, and the confirmation the size gate needs.
+ * `force` lives here rather than in the component because it is a fetch input:
+ * saying yes has to re-run the fetch, and then stay said for the rest of the
+ * dialog, including a later format change.
+ */
+function useTrackDataExport({ model, regions, regionStr, type, options, }) {
+    const [force, setForce] = useState(false);
+    const { data, error, isLoading, status } = useFetch(regions.length
+        ? [
+            'fetchTrackData',
+            getConf(model, 'trackId'),
+            regionStr,
+            type,
+            force,
+        ]
+        : null, async (_name, _trackId, _regions, fileType, forced, signal, statusCallback) => fetchTrackData({
+        model,
         regions,
-        sessionId,
-    });
-}
-function roundRegions(regions) {
-    return regions.map(r => ({
-        ...r,
-        start: Math.floor(r.start),
-        end: Math.ceil(r.end),
+        type: fileType,
+        options,
+        force: forced,
+        signal,
+        statusCallback,
     }));
+    return { result: data, error, loading: isLoading, status, setForce };
+}
+/**
+ * The format picker, owning the per-format help text and the dialog that shows
+ * it — nothing above needs to know a format can carry one.
+ */
+function FormatSelector({ options, type, setType, usedAdapterExport, }) {
+    const { classes } = useStyles();
+    const [helpText, setHelpText] = useState();
+    return (_jsxs(FormControl, { children: [_jsx(FormLabel, { children: `File type${usedAdapterExport ? ' (adapter export)' : ''}` }), _jsx(RadioGroup, { value: type, onChange: e => {
+                    setType(e.target.value);
+                }, children: Object.entries(options).map(([key, val]) => (_jsxs("div", { className: classes.formatRow, children: [_jsx(FormControlLabel, { value: key, control: _jsx(Radio, {}), label: val.name }), val.helpText ? (_jsx(IconButton, { size: "small", onClick: () => {
+                                setHelpText(val.helpText);
+                            }, title: "Show help for this format", children: _jsx(HelpOutlineIcon, { fontSize: "small" }) })) : null] }, key))) }), _jsx(InfoDialog, { open: helpText !== undefined, onClose: () => {
+                    setHelpText(undefined);
+                }, title: "Format Information", children: _jsx(DialogContentText, { children: helpText }) })] }));
+}
+/**
+ * What the preview pane says — the export itself only once there is one, and
+ * before that whichever of the four other states the dialog is in. In
+ * precedence order, because more than one can hold at a time.
+ */
+function previewText({ regions, loading, status, tooLarge, regionStr, str, }) {
+    if (!regions.length) {
+        return 'This view has no region on screen to export.';
+    }
+    if (loading) {
+        return statusProgressLabel(status) || 'Loading...';
+    }
+    if (tooLarge) {
+        return `${regionStr} is an estimated ${getDisplayStr(tooLarge.bytes)} on this track, over the ${getDisplayStr(tooLarge.limit)} this export asks about. Nothing has been downloaded — click "Download anyway" to fetch it.`;
+    }
+    return str.length > MAX_PREVIEW_CHARS ? TOO_BIG_TO_PREVIEW : str;
 }
 const SaveTrackDataDialog = observer(function SaveTrackDataDialog({ model, handleClose, }) {
     const { classes } = useStyles();
-    const options = useMemo(() => model.saveTrackFileFormatOptions(), [model]);
-    const [error, setError] = useState();
+    const options = model.saveTrackFileFormatOptions();
+    // every track type declaring this view declares at least one format
     const [type, setType] = useState(Object.keys(options)[0]);
-    const [str, setStr] = useState('');
-    const [usedAdapterExport, setUsedAdapterExport] = useState(false);
-    const [loading, setLoading] = useState(false);
-    const [helpDialogOpen, setHelpDialogOpen] = useState(false);
-    const [helpDialogContent, setHelpDialogContent] = useState('');
-    const [copied, setCopied] = useState(false);
+    // Captured once rather than read live. The dialog is modal, so the user
+    // cannot navigate under it, but the view's visible regions are derived from
+    // its width — and a window resize behind the dialog would otherwise change
+    // the fetch key and restart a long export from zero. Captured, they are also
+    // what the Region field can name, so the label always describes the bytes.
     const view = getContainingView(model);
-    const { visibleRegions, coarseVisibleLocStrings: regionStr } = view;
-    useEffect(() => {
-        let cancelled = false;
-        (async () => {
-            try {
-                setError(undefined);
-                setLoading(true);
-                const session = getSession(model);
-                if (!visibleRegions?.length || !type) {
-                    return;
-                }
-                const { pluginManager } = getEnv(model);
-                const adapterConfig = getConf(model, ['adapter']);
-                const adapterType = pluginManager.getAdapterType(adapterConfig.type);
-                const supportsExport = adapterType?.adapterCapabilities?.includes('exportData');
-                const regions = roundRegions(visibleRegions);
-                if (supportsExport) {
-                    const { rpcManager } = session;
-                    const sessionId = getRpcSessionId(model);
-                    const exportResult = (await rpcManager.call('getExportData', 'CoreGetExportData', {
-                        adapterConfig,
+    const [regions] = useState(() => roundRegions(view.visibleRegions ?? []));
+    const regionStr = assembleLocStrings(regions);
+    const { result, error, loading, status, setForce } = useTrackDataExport({
+        model,
+        regions,
+        regionStr,
+        type,
+        options,
+    });
+    const tooLarge = result?.tooLarge;
+    const str = result?.str ?? '';
+    // no regions means no fetch ran at all — without that term Copy and Download
+    // stayed live over the empty string and saved a plausible-looking empty file
+    const noResult = loading || !!error || !!tooLarge || !regions.length;
+    return (_jsx(InfoDialog, { maxWidth: "xl", open: true, onClose: handleClose, title: "Save track data", actions: _jsxs(_Fragment, { children: [tooLarge ? (_jsx(Button, { onClick: () => {
+                        setForce(true);
+                    }, children: "Download anyway" })) : null, _jsx(CopyToClipboardButton, { disabled: noResult, value: str, copiedLabel: "Copied!", startIcon: _jsx(ContentCopyIcon, {}), children: "Copy to clipboard" }), _jsx(Button, { variant: "contained", disabled: noResult, onClick: () => {
+                        saveAs(new Blob([str], { type: 'text/plain;charset=utf-8' }), `jbrowse_track_data.${options[type].extension}`);
+                    }, startIcon: _jsx(GetAppIcon, {}), children: "Download" })] }), children: _jsxs("div", { className: classes.root, children: [error ? _jsx(ErrorBanner, { error: error }) : null, _jsx("div", { children: _jsx(TextField, { label: "Region", value: regionStr, slotProps: { input: { readOnly: true } } }) }), _jsx(FormatSelector, { options: options, type: type, setType: setType, usedAdapterExport: !!result?.usedAdapterExport }), _jsx(TextField, { variant: "outlined", multiline: true, minRows: 5, maxRows: 15, fullWidth: true, value: previewText({
                         regions,
-                        formatType: type,
-                        sessionId,
-                    }));
-                    if (cancelled) {
-                        return;
-                    }
-                    setUsedAdapterExport(true);
-                    setStr(exportResult ?? '');
-                }
-                else {
-                    const features = await fetchFeatures(model, regions);
-                    if (cancelled) {
-                        return;
-                    }
-                    const result = await options[type].callback({
-                        features,
-                        session,
-                        assemblyName: regions[0].assemblyName,
-                    });
-                    if (cancelled) {
-                        return;
-                    }
-                    setUsedAdapterExport(false);
-                    setStr(result ?? '');
-                }
-            }
-            catch (e) {
-                if (!cancelled) {
-                    setError(e);
-                    console.error(e);
-                }
-            }
-            finally {
-                if (!cancelled) {
-                    setLoading(false);
-                }
-            }
-        })();
-        return () => {
-            cancelled = true;
-        };
-    }, [type, visibleRegions, options, model]);
-    return (_jsxs(Dialog, { maxWidth: "xl", open: true, onClose: handleClose, title: "Save track data", children: [_jsxs(DialogContent, { className: classes.root, children: [error ? _jsx(ErrorMessage, { error: error }) : null, _jsx("div", { children: _jsx(TextField, { label: "Region", value: regionStr, slotProps: {
-                                input: {
-                                    readOnly: true,
-                                },
-                            } }) }), _jsxs(FormControl, { children: [_jsx(FormLabel, { children: ['File type', usedAdapterExport ? '(adapter export)' : '']
-                                    .filter(f => !!f)
-                                    .join(' ') }), _jsx(RadioGroup, { value: type, onChange: e => {
-                                    setType(e.target.value);
-                                }, children: Object.entries(options).map(([key, val]) => (_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '4px' }, children: [_jsx(FormControlLabel, { value: key, control: _jsx(Radio, {}), label: val.name }), val.helpText ? (_jsx(IconButton, { size: "small", onClick: () => {
-                                                setHelpDialogContent(val.helpText);
-                                                setHelpDialogOpen(true);
-                                            }, title: "Show help for this format", children: _jsx(HelpOutlineIcon, { fontSize: "small" }) })) : null] }, key))) })] }), _jsx(TextField, { variant: "outlined", multiline: true, minRows: 5, maxRows: 15, fullWidth: true, value: loading
-                            ? 'Loading...'
-                            : str.length > 500_000
-                                ? 'File greater than 500kb, too large to view here. Click "Download" to save results to file'
-                                : str, slotProps: {
-                            input: {
-                                readOnly: true,
-                                classes: {
-                                    input: classes.textAreaFont,
-                                },
-                            },
-                        } })] }), _jsxs(DialogActions, { children: [_jsx(Button, { disabled: loading || !!error, onClick: () => {
-                            copy(str);
-                            setCopied(true);
-                            setTimeout(() => {
-                                setCopied(false);
-                            }, 1000);
-                        }, startIcon: _jsx(ContentCopyIcon, {}), children: copied ? 'Copied!' : 'Copy to clipboard' }), _jsx(Button, { disabled: loading || !!error, onClick: () => {
-                            const ext = options[type].extension;
-                            const blob = new Blob([str], { type: 'text/plain;charset=utf-8' });
-                            saveAs(blob, `jbrowse_track_data.${ext}`, { autoBom: false });
-                        }, startIcon: _jsx(GetAppIcon, {}), children: "Download" }), _jsx(Button, { variant: "contained", type: "submit", onClick: () => {
-                            handleClose();
-                        }, children: "Close" })] }), _jsxs(Dialog, { open: helpDialogOpen, onClose: () => {
-                    setHelpDialogOpen(false);
-                }, children: [_jsx(DialogTitle, { children: "Format Information" }), _jsx(DialogContent, { children: _jsx(DialogContentText, { children: helpDialogContent }) }), _jsx(DialogActions, { children: _jsx(Button, { autoFocus: true, onClick: () => {
-                                setHelpDialogOpen(false);
-                            }, children: "Close" }) })] })] }));
+                        loading,
+                        status,
+                        tooLarge,
+                        regionStr,
+                        str,
+                    }), slotProps: {
+                        input: {
+                            readOnly: true,
+                            classes: { input: classes.textAreaFont },
+                        },
+                    } })] }) }));
 });
 export default SaveTrackDataDialog;

package/esm/pluggableElementTypes/models/components/fetchTrackData.d.ts

@@ -0,0 +1,54 @@
+import type { AnyConfigurationModel } from '../../../configuration/index.ts';
+import type { Region } from '../../../util/index.ts';
+import type { StatusCallback } from '../../../util/progress.ts';
+import type { FileTypeExporter } from '../saveTrackFileTypes/types.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * What the export needs off the track, duck-typed rather than imported: this
+ * module is behind `BaseTrackModel`'s lazy dialog import, so naming that model
+ * type here would close the circle. `exportsDataViaAdapter` and
+ * `exportByteLimit` are its getters.
+ */
+export interface ExportableTrack extends IStateTreeNode {
+    configuration: AnyConfigurationModel;
+    exportsDataViaAdapter: boolean;
+    exportByteLimit: number;
+    saveTrackFileFormatOptions: () => Record<string, FileTypeExporter>;
+}
+/**
+ * The four fields a region fetch needs, with the fractional bounds a view hands
+ * out widened to whole bases. Narrowed rather than spread whole: an LGV's
+ * `visibleRegions` blocks also carry screen geometry and a `reversed` flag, and
+ * `reversed` is what put a stray "[rev]" on the region the dialog says it is
+ * exporting — the export itself is in reference order either way.
+ */
+export declare function roundRegions(regions: Region[]): Region[];
+export interface TrackDataResult {
+    str: string;
+    usedAdapterExport: boolean;
+    /**
+     * Set, with an empty `str` and nothing downloaded, when the pre-flight
+     * estimate came back over budget and the caller had not passed `force`.
+     */
+    tooLarge?: {
+        bytes: number;
+        limit: number;
+    };
+}
+/**
+ * The data behind the "Save track data" dialog, in the selected format.
+ *
+ * This reads every feature in the visible region, which on a deep track is the
+ * same work the display itself does — worth cancelling when the dialog closes,
+ * and worth naming while it runs, hence the signal and status callback.
+ */
+export declare function fetchTrackData({ model, regions, type, options, force, signal, statusCallback, }: {
+    model: ExportableTrack;
+    regions: Region[];
+    type: string;
+    options: Record<string, FileTypeExporter>;
+    /** skip the size pre-flight — the user has seen the estimate and said yes */
+    force?: boolean;
+    signal?: AbortSignal;
+    statusCallback?: StatusCallback;
+}): Promise<TrackDataResult>;

package/esm/pluggableElementTypes/models/components/fetchTrackData.js

@@ -0,0 +1,83 @@
+import { getConf } from '../../../configuration/index.js';
+import { getSession } from '../../../util/index.js';
+import { getRpcSessionId } from '../../../util/tracks.js';
+/**
+ * The four fields a region fetch needs, with the fractional bounds a view hands
+ * out widened to whole bases. Narrowed rather than spread whole: an LGV's
+ * `visibleRegions` blocks also carry screen geometry and a `reversed` flag, and
+ * `reversed` is what put a stray "[rev]" on the region the dialog says it is
+ * exporting — the export itself is in reference order either way.
+ */
+export function roundRegions(regions) {
+    return regions.map(({ assemblyName, refName, start, end }) => ({
+        assemblyName,
+        refName,
+        start: Math.floor(start),
+        end: Math.ceil(end),
+    }));
+}
+/**
+ * A text file ends with a newline, and deciding that once here is what keeps
+ * the three adapters and seven writers from each deciding it: every one of them
+ * ends in a `join('\n')`, and they disagreed — GFF3, BED and GenBank appended
+ * one, VCF, SAM, bedGraph and FASTA did not. An empty export stays empty.
+ */
+function endWithNewline(str) {
+    return str && !str.endsWith('\n') ? `${str}\n` : str;
+}
+/**
+ * The data behind the "Save track data" dialog, in the selected format.
+ *
+ * This reads every feature in the visible region, which on a deep track is the
+ * same work the display itself does — worth cancelling when the dialog closes,
+ * and worth naming while it runs, hence the signal and status callback.
+ */
+export async function fetchTrackData({ model, regions, type, options, force, signal, statusCallback, }) {
+    const session = getSession(model);
+    const sessionId = getRpcSessionId(model);
+    const adapterConfig = getConf(model, ['adapter']);
+    const opts = { signal, statusCallback };
+    const { exportsDataViaAdapter } = model;
+    // The same index lookup the display's gate takes before it fetches, for the
+    // same reason: this menu item pulls the region the display just refused to
+    // render, and did so with no ceiling at all. An adapter quoting no estimate
+    // (BigWig, sequence, HiC) answers `undefined` and nothing gates — see
+    // reference/REGION_TOO_LARGE.md.
+    if (!force) {
+        const bytes = await session.rpcManager.call(sessionId, 'CoreGetRegionByteEstimate', 
+        // a save downloads every region in one file, so the total is what the
+        // user approves — unlike the gate, whose budget is per-region
+        { adapterConfig, regions, scope: 'wholeRequest', ...opts });
+        const limit = model.exportByteLimit;
+        if (bytes !== undefined && bytes > limit) {
+            return {
+                str: '',
+                usedAdapterExport: exportsDataViaAdapter,
+                tooLarge: { bytes, limit },
+            };
+        }
+    }
+    if (exportsDataViaAdapter) {
+        const str = await session.rpcManager.call(sessionId, 'CoreGetExportData', {
+            adapterConfig,
+            regions,
+            formatType: type,
+            ...opts,
+        });
+        if (str !== undefined) {
+            return { str: endWithNewline(str), usedAdapterExport: true };
+        }
+    }
+    const feats = await session.rpcManager.call(sessionId, 'CoreGetFeatures', {
+        adapterConfig,
+        regions,
+        ...opts,
+    });
+    const str = await options[type].callback({
+        features: feats,
+        session,
+        assemblyName: regions[0].assemblyName,
+        ...opts,
+    });
+    return { str: endWithNewline(str), usedAdapterExport: false };
+}

package/esm/pluggableElementTypes/models/expandTrackConfigShorthand.d.ts

@@ -0,0 +1,50 @@
+import type PluginManager from '../../PluginManager.ts';
+import type { AnyConfigurationSchemaType } from '../../configuration/index.ts';
+export interface DisplaySnapshot {
+    type: string;
+    displayId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Route each shorthand `displayDefaults: {...}` setting to the display types
+ * whose member of that name takes its value: `color: 'red'` reaches every
+ * display with a colour, `color: { field: 'type' }` only those whose colour
+ * maps a field, and a spelling a display retired reaches that display as the
+ * members it became. `reached` names the displays each key went to. A key no
+ * display knows is an `unknownKeys` entry, and one every display that knows it
+ * refuses a `refused` entry carrying each reason.
+ */
+export declare function collectDisplayOverrides(displaySettings: Record<string, unknown>, displaySchemas: ReadonlyMap<string, AnyConfigurationSchemaType>): {
+    overrides: Map<string, Record<string, unknown>>;
+    reached: Map<string, string[]>;
+    unknownKeys: string[];
+    refused: {
+        key: string;
+        reasons: string[];
+    }[];
+};
+/**
+ * Fold per-display override props into the entries a `displays` array already
+ * has; explicit props win. A display with no entry gets none: a setting never
+ * adds a display to a track.
+ */
+export declare function mergeOverridesIntoDisplays(displays: DisplaySnapshot[], overrides: Map<string, Record<string, unknown>>): DisplaySnapshot[];
+/**
+ * Expands the shorthand `displayDefaults` **object** into the explicit `displays`
+ * **array**, so users can set display settings without naming the display type
+ * or nesting in `displays:[{type,...}]`. `displayDefaults:{color:'green'}` routes
+ * each setting to the display type(s) whose slot takes it, folding them into
+ * the entries the `displays` array has (explicit props win). A key whose every
+ * taker is missing from the array, a display the track's adapter cannot feed,
+ * is reported rather than giving the track that display.
+ *
+ * `displayDefaults` is kept separate from `displays` (rather than overloading
+ * `displays` by shape) so a config using it still loads in a JBrowse version
+ * that predates the feature — the unknown key is ignored, instead of crashing
+ * when the array-typed `displays` slot receives an object.
+ *
+ * Runs inside `baseTrackConfig.preProcessSnapshot`, after display-stub
+ * injection. Takes/returns the loosely-typed snapshot (as `evaluateExtensionPoint`
+ * does) — the caller casts the result to its snapshot type for validation.
+ */
+export declare function expandTrackConfigShorthand(input: unknown, pluginManager: PluginManager): unknown;

package/esm/pluggableElementTypes/models/expandTrackConfigShorthand.js

@@ -0,0 +1,147 @@
+import { getConfigurationSchemaMetadata } from '../../configuration/schemaRegistry.js';
+import { slotValueRefusal } from '../../configuration/slotFacade.js';
+import { isPlainObject } from '../../util/objectUtils.js';
+/**
+ * What one display would do with a shorthand setting: the members it would
+ * write, or why it will not take it. `undefined` means the display has no
+ * member of that name and no retired spelling of one, so it is not a candidate
+ * and the key is not its business.
+ */
+function verdictOf(schema, key, value) {
+    const meta = getConfigurationSchemaMetadata(schema);
+    const retired = meta?.options.retired?.[key];
+    let members;
+    try {
+        members = retired
+            ? retired(value)
+            : meta?.definition[key]
+                ? { [key]: value }
+                : undefined;
+    }
+    catch (e) {
+        return { refusal: e instanceof Error ? e.message : String(e) };
+    }
+    // A lift answering nothing has not placed the value — a `colorBy` naming a
+    // scheme this display never had, a `renderer` holding none of the props it
+    // retired. That is the `unknownKeys` report, not a silent write of nothing.
+    if (!members || Object.keys(members).length === 0) {
+        return undefined;
+    }
+    const refusal = Object.entries(members)
+        .map(([name, member]) => slotValueRefusal(schema, name, member))
+        .find(reason => reason !== undefined);
+    return refusal === undefined ? { members } : { refusal };
+}
+/**
+ * Route each shorthand `displayDefaults: {...}` setting to the display types
+ * whose member of that name takes its value: `color: 'red'` reaches every
+ * display with a colour, `color: { field: 'type' }` only those whose colour
+ * maps a field, and a spelling a display retired reaches that display as the
+ * members it became. `reached` names the displays each key went to. A key no
+ * display knows is an `unknownKeys` entry, and one every display that knows it
+ * refuses a `refused` entry carrying each reason.
+ */
+export function collectDisplayOverrides(displaySettings, displaySchemas) {
+    const overrides = new Map();
+    const reached = new Map();
+    const unknownKeys = [];
+    const refused = [];
+    for (const [key, value] of Object.entries(displaySettings)) {
+        const verdicts = [...displaySchemas].flatMap(([name, schema]) => {
+            const verdict = verdictOf(schema, key, value);
+            return verdict ? [{ name, ...verdict }] : [];
+        });
+        const targets = verdicts.filter(v => v.members);
+        if (verdicts.length === 0) {
+            unknownKeys.push(key);
+        }
+        else if (targets.length === 0) {
+            refused.push({
+                key,
+                reasons: verdicts.map(v => `${v.name}: ${v.refusal}`),
+            });
+        }
+        for (const { name, members } of targets) {
+            overrides.set(name, { ...overrides.get(name), ...members });
+        }
+        reached.set(key, targets.map(t => t.name));
+    }
+    return { overrides, reached, unknownKeys, refused };
+}
+/**
+ * Fold per-display override props into the entries a `displays` array already
+ * has; explicit props win. A display with no entry gets none: a setting never
+ * adds a display to a track.
+ */
+export function mergeOverridesIntoDisplays(displays, overrides) {
+    return displays.map(d => ({ ...overrides.get(d.type), ...d }));
+}
+/**
+ * Expands the shorthand `displayDefaults` **object** into the explicit `displays`
+ * **array**, so users can set display settings without naming the display type
+ * or nesting in `displays:[{type,...}]`. `displayDefaults:{color:'green'}` routes
+ * each setting to the display type(s) whose slot takes it, folding them into
+ * the entries the `displays` array has (explicit props win). A key whose every
+ * taker is missing from the array, a display the track's adapter cannot feed,
+ * is reported rather than giving the track that display.
+ *
+ * `displayDefaults` is kept separate from `displays` (rather than overloading
+ * `displays` by shape) so a config using it still loads in a JBrowse version
+ * that predates the feature — the unknown key is ignored, instead of crashing
+ * when the array-typed `displays` slot receives an object.
+ *
+ * Runs inside `baseTrackConfig.preProcessSnapshot`, after display-stub
+ * injection. Takes/returns the loosely-typed snapshot (as `evaluateExtensionPoint`
+ * does) — the caller casts the result to its snapshot type for validation.
+ */
+export function expandTrackConfigShorthand(input, pluginManager) {
+    if (!isPlainObject(input)) {
+        return input;
+    }
+    // `rest` is the snapshot without the consumed shorthand key, so the expanded
+    // result never carries `displayDefaults` forward.
+    const { displayDefaults: shorthand, ...rest } = input;
+    const snap = input;
+    const type = typeof snap.type === 'string' ? snap.type : undefined;
+    const trackId = typeof snap.trackId === 'string' ? snap.trackId : undefined;
+    if (!isPlainObject(shorthand) ||
+        !type ||
+        !trackId ||
+        trackId === 'placeholderId') {
+        return snap;
+    }
+    // getTrackType throws on an unknown type; let downstream emit its detailed
+    // "Unknown track type" error rather than masking it here.
+    let trackType;
+    try {
+        trackType = pluginManager.getTrackType(type);
+    }
+    catch {
+        return snap;
+    }
+    if (!trackType.displayTypes.length) {
+        return snap;
+    }
+    const { overrides, reached, unknownKeys, refused } = collectDisplayOverrides(shorthand, new Map(trackType.displayTypes.map(d => [d.name, d.configSchema])));
+    for (const key of unknownKeys) {
+        console.warn(`Track "${trackId}": display setting "${key}" is not a slot on any display of a ${type}`);
+    }
+    if (refused.length > 0) {
+        throw new Error(refused
+            .map(({ key, reasons }) => `Track "${trackId}": no display of a ${type} takes displayDefaults.${key} (${reasons.join('; ')})`)
+            .join('\n'));
+    }
+    const displays = Array.isArray(rest.displays)
+        ? rest.displays
+        : [];
+    const listed = new Set(displays.map(d => d.type));
+    for (const [key, names] of reached) {
+        if (names.length > 0 && !names.some(name => listed.has(name))) {
+            console.warn(`Track "${trackId}": displayDefaults.${key} reaches only ${names.join(', ')}, which its adapter cannot feed`);
+        }
+    }
+    return {
+        ...rest,
+        displays: mergeOverridesIntoDisplays(displays, overrides),
+    };
+}

package/esm/pluggableElementTypes/models/index.d.ts

@@ -3,12 +3,14 @@ export { default as BaseConnectionModelFactory } from './BaseConnectionModelFact
 export { default as BaseViewModel } from './BaseViewModel.ts';
 export type { IBaseViewModel } from './BaseViewModel.ts';
 export { BaseDisplay } from './BaseDisplayModel.tsx';
-export type { BaseDisplayModel, BaseDisplayStateModel, } from './BaseDisplayModel.tsx';
+export type { BaseDisplayModel, BaseDisplayStateModel, DisplayModel, } from './BaseDisplayModel.tsx';
 export { InternetAccount } from './InternetAccountModel.ts';
 export type { BaseInternetAccountModel, BaseInternetAccountStateModel, } from './InternetAccountModel.ts';
 export { BaseInternetAccountConfig } from './baseInternetAccountConfig.ts';
 export { createBaseTrackModel } from './BaseTrackModel.ts';
 export type { BaseTrackModel, BaseTrackStateModel } from './BaseTrackModel.ts';
-export { createBaseTrackConfig } from './baseTrackConfig.ts';
-export type { BaseTrackConfig, BaseTrackConfigSchema as BaseTrackConfigModel, } from './baseTrackConfig.ts';
+export { createBaseTrackConfig, preprocessTrackConfigSnapshot, } from './baseTrackConfig.ts';
+export type { BaseTrackConfig } from './baseTrackConfig.ts';
+export { migrateRetiredDisplays } from './migrateTrackConfig.ts';
+export type { TrackConfigSnapshot } from './migrateTrackConfig.ts';
 export type { FileTypeExporter } from './saveTrackFileTypes/types.ts';

package/esm/pluggableElementTypes/models/index.js

@@ -1,8 +1,9 @@
-export { default as baseConnectionConfig } from "./baseConnectionConfig.js";
-export { default as BaseConnectionModelFactory } from "./BaseConnectionModelFactory.js";
-export { default as BaseViewModel } from "./BaseViewModel.js";
-export { BaseDisplay } from "./BaseDisplayModel.js";
-export { InternetAccount } from "./InternetAccountModel.js";
-export { BaseInternetAccountConfig } from "./baseInternetAccountConfig.js";
-export { createBaseTrackModel } from "./BaseTrackModel.js";
-export { createBaseTrackConfig } from "./baseTrackConfig.js";
+export { default as baseConnectionConfig } from './baseConnectionConfig.js';
+export { default as BaseConnectionModelFactory } from './BaseConnectionModelFactory.js';
+export { default as BaseViewModel } from './BaseViewModel.js';
+export { BaseDisplay } from './BaseDisplayModel.js';
+export { InternetAccount } from './InternetAccountModel.js';
+export { BaseInternetAccountConfig } from './baseInternetAccountConfig.js';
+export { createBaseTrackModel } from './BaseTrackModel.js';
+export { createBaseTrackConfig, preprocessTrackConfigSnapshot, } from './baseTrackConfig.js';
+export { migrateRetiredDisplays } from './migrateTrackConfig.js';