@jbrowse/plugin-linear-genome-view 5.0.0-beta.17 → 5.0.0-beta.18

package/esm/FeatureTrack/configSchema.d.ts

@@ -37,7 +37,9 @@ import type PluginManager from '@jbrowse/core/PluginManager';
  *     type: 'Gff3TabixAdapter',
  *     uri: 'https://example.com/genes.sorted.gff.gz',
  *   },
- *   displayDefaults: { color: "jexl:feature.type=='CDS'?'red':'blue'" },
+ *   displayDefaults: {
+ *     encoding: { color: { value: "jexl:feature.type=='CDS'?'red':'blue'" } },
+ *   },
  * }
  * ```
  */

package/esm/FeatureTrack/configSchema.js

@@ -38,7 +38,9 @@ import { createBaseTrackConfig } from '@jbrowse/core/pluggableElementTypes';
  *     type: 'Gff3TabixAdapter',
  *     uri: 'https://example.com/genes.sorted.gff.gz',
  *   },
- *   displayDefaults: { color: "jexl:feature.type=='CDS'?'red':'blue'" },
+ *   displayDefaults: {
+ *     encoding: { color: { value: "jexl:feature.type=='CDS'?'red':'blue'" } },
+ *   },
  * }
  * ```
  */

package/esm/LinearGenomeView/afterAttach.js

@@ -2,8 +2,10 @@ import { getSession, isSessionModelWithWidgets, resolveNamedRegions, } from '@jb
 import { coerceHighlight } from '@jbrowse/core/util/highlights';
 import { installInitAutorun } from '@jbrowse/core/util/installInitAutorun';
 import { normalizeTrackInit, warmTrackDisplayGeneric, } from '@jbrowse/core/util/tracks';
+import { requestedDisplayType } from '@jbrowse/launch-args/displaySettings';
 import { addDisposer } from '@jbrowse/mobx-state-tree';
 import { autorun, untracked, when } from 'mobx';
+import { launchTrackInit } from '../TrackModifiers/index.js';
 import { SearchResultsNotFoundError } from '../searchUtils.js';
 // `init` is a frozen blob that often comes from hand-authored JSON, where a
 // lone entry gets written bare (`tracks: 'genes'`). A string is iterable, so
@@ -127,8 +129,7 @@ async function navigateInit(self, session, init) {
 // display's state model first when it is registered lazily
 async function showInitTracks(self, init) {
     for (const t of asArray(init.tracks)) {
-        const { trackId, trackSnapshot, displaySnapshot } = normalizeTrackInit(t);
-        await self.launchTrack(trackId, trackSnapshot, displaySnapshot);
+        await launchTrackInit(self, t);
     }
 }
 /**
@@ -219,8 +220,9 @@ function setupInitWarmup(self) {
                 }
             }
             for (const t of tracks) {
-                const { trackId, displaySnapshot } = normalizeTrackInit(t);
-                warmTrackDisplayGeneric(self, trackId, displaySnapshot, assembly);
+                const { trackId, displaySnapshot, modifiers } = normalizeTrackInit(t);
+                const type = requestedDisplayType(modifiers);
+                warmTrackDisplayGeneric(self, trackId, type ? { ...displaySnapshot, type } : displaySnapshot, assembly);
             }
         });
     }, { name: 'LGVInitWarmup' }));

package/esm/LinearGenomeView/components/LinearGenomeViewContainer.js

@@ -102,7 +102,9 @@ const LinearGenomeViewContainer = observer(function LinearGenomeViewContainer({
                     .flatMap(t => t.displays)
                     .map(d => d.hoveredFeature)
                     .find(Boolean);
-                session.setHovered({ hoverPosition, hoverFeature });
+                // `viewId` lets a view paired with one linear view ignore another
+                // showing the same locus
+                session.setHovered({ hoverPosition, hoverFeature, viewId: model.id });
             }, children: [_jsx(NavigationAnnouncer, { model: model }), _jsxs("div", { ref: headerRef, "data-testid": `lgv-header-${model.id}`, className: classes.header, style: { position: stickyViewHeaders ? 'sticky' : undefined }, children: [_jsx(Header, { model: model }), hideHeader ? _jsx(MiniControls, { model: model }) : null] }), _jsx("div", { ref: tracksRef, children: model.scalebarOnly ? (_jsx(Rubberband, { model: model })) : (_jsx(TracksContainer, { model: model, children: !tracks.length ? (_jsx(NoTracksActiveButton, { model: model })) : (_jsxs(_Fragment, { children: [pinnedTracks.length ? (_jsx(Paper, { elevation: 2, "data-testid": "pinned-tracks", className: classes.pinnedTracks, style: {
                                         top: stickyTops.pinnedTracks,
                                         // the scroll port this sticks in, not the window: a

package/esm/LinearGenomeView/components/useSearchBoxPrefs.d.ts

@@ -22,7 +22,7 @@ export type SearchBoxPrefs = ReturnType<typeof useSearchBoxPrefs>;
 /**
  * The menu rows that drive those prefs. "Stacked" rather than "Vertical": the
  * two headers name the same state and had drifted apart on it once already.
- * A caller spreading the rows into a "Show..." submenu passes `'Search boxes'`
+ * A caller spreading the rows into a "Show" submenu passes `'Search boxes'`
  * as the toggle's label.
  */
 export declare function searchBoxMenuItems({ showSearchBoxes, setShowSearchBoxes, sideBySide, setSideBySide, }: SearchBoxPrefs, toggleLabel?: string): MenuItem[];

package/esm/LinearGenomeView/components/useSearchBoxPrefs.js

@@ -22,7 +22,7 @@ export function useSearchBoxPrefs(prefix, numViews) {
 /**
  * The menu rows that drive those prefs. "Stacked" rather than "Vertical": the
  * two headers name the same state and had drifted apart on it once already.
- * A caller spreading the rows into a "Show..." submenu passes `'Search boxes'`
+ * A caller spreading the rows into a "Show" submenu passes `'Search boxes'`
  * as the toggle's label.
  */
 export function searchBoxMenuItems({ showSearchBoxes, setShowSearchBoxes, sideBySide, setSideBySide, }, toggleLabel = 'Show search boxes') {

package/esm/LinearGenomeView/model.d.ts

@@ -1,4 +1,4 @@
-import type { BpOffset, ExportSvgOptions, HighlightType, InitState, NavLocation, ViewTrackLabelMode, VolatileGuide } from './types.ts';
+import type { BpOffset, ExportSvgOptions, HighlightInput, HighlightType, InitState, NavLocation, ViewTrackLabelMode, VolatileGuide } from './types.ts';
 import type { RegionEdit } from './util.ts';
 import type PluginManager from '@jbrowse/core/PluginManager';
 import type BaseResult from '@jbrowse/core/TextSearch/BaseResults';
@@ -20,18 +20,24 @@ export interface SearchPickerRow {
     trackName: string;
 }
 /**
- * The hits of a name search that point at more than one place, waiting for the
- * user to choose. A host draws them however it likes: the Material view shows
- * a dialog, and `SearchPicker` in `@jbrowse/display-ui/embed` a plain list.
+ * A name search's hits as a host lists them: what `view.search` returns, and
+ * what the picker holds.
  */
-export interface SearchPickerState {
+export interface SearchHits {
     query: string;
     assemblyName: string;
-    /** one row per place, hits in a track the view already shows first */
+    /** one row per hit, hits in a track the view already shows first */
     rows: SearchPickerRow[];
-    /** navigates to the row's place, reports a failure and closes the picker */
+    /** lands on the row's place and reports a failure */
     pick: (id: string) => Promise<unknown>;
 }
+/**
+ * The hits of a name search that point at more than one place, waiting for the
+ * user to choose; its `pick` also closes the picker. A host draws them however
+ * it likes: the Material view shows a dialog, and `SearchPicker` in
+ * `@jbrowse/display-ui/embed` a plain list.
+ */
+export type SearchPickerState = SearchHits;
 export type { PaddingSpan } from './util.ts';
 export interface HighlightRegion {
     assemblyName?: string;
@@ -172,6 +178,13 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * #volatile
      */
     coarseBpPerPx: number;
+    /**
+     * #volatile
+     * the scroll offset the coarse blocks were laid out at, in px at
+     * `coarseBpPerPx`: the settled viewport's left edge, which the first
+     * coarse block is not while the view is scrolled before the first region
+     */
+    coarseOffsetPx: number;
     /**
      * #volatile
      */
@@ -967,6 +980,15 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * there and shows the track its index came from
      */
     setSearchResults(searchResults: BaseResult[], searchQuery: string, assemblyName: string, onPick?: (result: BaseResult) => Promise<unknown>): void;
+    /**
+     * #action
+     * Search the view's assembly by name, for a host listing the hits
+     * itself. A row's `pick` lands as the search box does: it navigates
+     * there and shows the track the hit's index came from.
+     */
+    search(query: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SearchHits>;
     /**
      * #action
      */
@@ -988,6 +1010,22 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * loaded: loads it, then shows
      */
     launchTrack(trackId: string, initialSnapshot?: any, displayInitialSnapshot?: any, inlineConf?: Record<string, unknown>): Promise<any>;
+    /**
+     * #action
+     * Replace the highlights `highlights` reads, each written as the launch
+     * spec's `highlight` writes one: a locstring, or an object whose
+     * `assemblyName` defaults to the view's. Throws on one that names no
+     * region, writing none.
+     */
+    setHighlights(highlights: readonly (string | HighlightInput)[]): void;
+    /**
+     * #action
+     * Show files from the user's disk as session tracks: one per data file,
+     * beside the index among them that names it, its type guessed from its
+     * name. Adds nothing when one file has no known type. Resolves the new
+     * tracks' ids.
+     */
+    showFiles(files: readonly File[]): Promise<string[]>;
 } & {
     /**
      * #method
@@ -1911,6 +1949,13 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * #volatile
      */
     coarseBpPerPx: number;
+    /**
+     * #volatile
+     * the scroll offset the coarse blocks were laid out at, in px at
+     * `coarseBpPerPx`: the settled viewport's left edge, which the first
+     * coarse block is not while the view is scrolled before the first region
+     */
+    coarseOffsetPx: number;
     /**
      * #volatile
      */
@@ -2706,6 +2751,15 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * there and shows the track its index came from
      */
     setSearchResults(searchResults: BaseResult[], searchQuery: string, assemblyName: string, onPick?: (result: BaseResult) => Promise<unknown>): void;
+    /**
+     * #action
+     * Search the view's assembly by name, for a host listing the hits
+     * itself. A row's `pick` lands as the search box does: it navigates
+     * there and shows the track the hit's index came from.
+     */
+    search(query: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SearchHits>;
     /**
      * #action
      */
@@ -2727,6 +2781,22 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * loaded: loads it, then shows
      */
     launchTrack(trackId: string, initialSnapshot?: any, displayInitialSnapshot?: any, inlineConf?: Record<string, unknown>): Promise<any>;
+    /**
+     * #action
+     * Replace the highlights `highlights` reads, each written as the launch
+     * spec's `highlight` writes one: a locstring, or an object whose
+     * `assemblyName` defaults to the view's. Throws on one that names no
+     * region, writing none.
+     */
+    setHighlights(highlights: readonly (string | HighlightInput)[]): void;
+    /**
+     * #action
+     * Show files from the user's disk as session tracks: one per data file,
+     * beside the index among them that names it, its type guessed from its
+     * name. Adds nothing when one file has no known type. Resolves the new
+     * tracks' ids.
+     */
+    showFiles(files: readonly File[]): Promise<string[]>;
 } & {
     /**
      * #method

package/esm/LinearGenomeView/model.js

@@ -8,6 +8,7 @@ import { scaleBandHeights } from '@jbrowse/core/util/bandHeight';
 import { wholeBaseRegions } from '@jbrowse/core/util/blockTypes';
 import calculateDynamicBlocks from '@jbrowse/core/util/calculateDynamicBlocks';
 import calculateStaticBlocks from '@jbrowse/core/util/calculateStaticBlocks';
+import { coerceHighlight } from '@jbrowse/core/util/highlights';
 import { hideTrackGeneric, launchToggleTrackGeneric, launchTrackGeneric, showTrackGeneric, toggleTrackGeneric, } from '@jbrowse/core/util/tracks';
 import { ElementId } from '@jbrowse/core/util/types/mst';
 import { highlightsOnAssemblies } from '@jbrowse/core/util/viewHighlights';
@@ -17,7 +18,7 @@ import { MIN_DISPLAY_HEIGHT } from '@jbrowse/display-kit/const';
 import { contentRightEdgePx } from '@jbrowse/display-kit/regionHost';
 import { cast, getParent, getSnapshot, hasParent, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import { observable, when } from 'mobx';
-import { handleSelectedRegion, isOpenInView, navToOption, } from '../searchUtils.js';
+import { fetchResults, handleSelectedRegion, isOpenInView, navToOption, } from '../searchUtils.js';
 import { doAfterAttach } from './afterAttach.js';
 import { linearGenomeViewAxisConfigSchema } from './axisConfigSchema.js';
 import { getCytobands, shouldSwapTracks } from './components/util.js';
@@ -27,7 +28,43 @@ import { setupKeyboardHandler } from './keyboardHandler.js';
 import { lgvLaunchKeys } from './launchKeys.js';
 import { buildHighlightsSubMenuItems, buildMenuItems, buildRubberBandMenuItems, buildRubberbandClickMenuItems, } from './menuItems.js';
 import { sharedScaleContainerOf } from './sharedScaleContainer.js';
+import { showFiles } from './showFiles.js';
 import { calculateVisibleLocStrings, cytobandLabelGutterWidth, expandRegion, fitAllRegionsWindow, generateLocations, getGridlineTicks, getPaddingSpans, getScalebarLabels, getScalebarRefNameLabels, regionsOrientation, setDisplayedRegionsKeepingCenter, } from './util.js';
+function searchHitsOf(model, results, query, assemblyName, land) {
+    const session = getSession(model);
+    const assembly = session.assemblyManager.get(assemblyName);
+    const ordered = [...results].sort((a, b) => Number(isOpenInView(b, model)) - Number(isOpenInView(a, model)));
+    return {
+        query,
+        assemblyName,
+        rows: ordered.map(result => {
+            const location = result.getLocation() ?? '';
+            const trackId = result.getTrackId();
+            return {
+                id: result.getId(),
+                label: result.getLabel(),
+                location: assembly && location
+                    ? canonicalLocString(location, assembly)
+                    : location,
+                trackName: trackId ? (session.getTrackById(trackId)?.name ?? '') : '',
+            };
+        }),
+        pick: async (id) => {
+            const picked = ordered.find(result => result.getId() === id);
+            try {
+                if (picked) {
+                    await land(picked);
+                }
+            }
+            catch (e) {
+                console.error(e);
+                if (isAlive(model)) {
+                    getNotificationSink(model).notifyError(`${e}`, e);
+                }
+            }
+        },
+    };
+}
 /**
  * Calculate the offsetPx needed to center content within a viewport.
  * Returns a negative offset when content is smaller than viewport (padding on left).
@@ -388,6 +425,13 @@ export function stateModelFactory(pluginManager) {
             // displays that lay out against it; `setWidth` seeds the true one at
             // the first measure.
             coarseBpPerPx: 1,
+            /**
+             * #volatile
+             * the scroll offset the coarse blocks were laid out at, in px at
+             * `coarseBpPerPx`: the settled viewport's left edge, which the first
+             * coarse block is not while the view is scrolled before the first region
+             */
+            coarseOffsetPx: 0,
             /**
              * #volatile
              */
@@ -1139,6 +1183,7 @@ export function stateModelFactory(pluginManager) {
                 // The debounced coarse autorun is 500ms out; a restored snapshot's
                 // consumers would lay out and fetch at 1 bp/px until then.
                 self.coarseBpPerPx = self.bpPerPx;
+                self.coarseOffsetPx = self.offsetPx;
             }
         },
         /**
@@ -1264,40 +1309,11 @@ export function stateModelFactory(pluginManager) {
             model: self,
             assemblyName,
         })) {
-            const session = getSession(self);
-            const assembly = session.assemblyManager.get(assemblyName);
-            const ordered = [...searchResults].sort((a, b) => Number(isOpenInView(b, self)) -
-                Number(isOpenInView(a, self)));
+            const hits = searchHitsOf(self, searchResults, searchQuery, assemblyName, onPick);
             const picker = {
-                query: searchQuery,
-                assemblyName,
-                rows: ordered.map(result => {
-                    const location = result.getLocation() ?? '';
-                    const trackId = result.getTrackId();
-                    return {
-                        id: result.getId(),
-                        label: result.getLabel(),
-                        location: assembly && location
-                            ? canonicalLocString(location, assembly)
-                            : location,
-                        trackName: trackId
-                            ? (session.getTrackById(trackId)?.name ?? '')
-                            : '',
-                    };
-                }),
+                ...hits,
                 pick: async (id) => {
-                    const picked = ordered.find(result => result.getId() === id);
-                    try {
-                        if (picked) {
-                            await onPick(picked);
-                        }
-                    }
-                    catch (e) {
-                        console.error(e);
-                        if (isAlive(self)) {
-                            getNotificationSink(self).notifyError(`${e}`, e);
-                        }
-                    }
+                    await hits.pick(id);
                     if (isAlive(self) && self.searchPicker === picker) {
                         self.closeSearchPicker();
                     }
@@ -1305,6 +1321,31 @@ export function stateModelFactory(pluginManager) {
             };
             self.searchPicker = picker;
         },
+        /**
+         * #action
+         * Search the view's assembly by name, for a host listing the hits
+         * itself. A row's `pick` lands as the search box does: it navigates
+         * there and shows the track the hit's index came from.
+         */
+        async search(query, opts) {
+            const assemblyName = self.assemblyNames[0] ?? self.launchAssemblyName;
+            if (!assemblyName) {
+                throw new Error('the view has no assembly to search yet');
+            }
+            const { assemblyManager, textSearchManager } = getSession(self);
+            const results = await fetchResults({
+                queryString: query,
+                assemblyName,
+                textSearchManager,
+                assembly: await assemblyManager.waitForAssembly(assemblyName),
+                signal: opts?.signal,
+            });
+            return searchHitsOf(self, results, query, assemblyName, result => navToOption({
+                option: result,
+                model: self,
+                assemblyName,
+            }));
+        },
         /**
          * #action
          */
@@ -1337,6 +1378,34 @@ export function stateModelFactory(pluginManager) {
         async launchTrack(trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
             return launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
         },
+        /**
+         * #action
+         * Replace the highlights `highlights` reads, each written as the launch
+         * spec's `highlight` writes one: a locstring, or an object whose
+         * `assemblyName` defaults to the view's. Throws on one that names no
+         * region, writing none.
+         */
+        setHighlights(highlights) {
+            const session = getSession(self);
+            const assemblyName = self.assemblyNames[0] ?? self.launchAssemblyName ?? '';
+            session.setHighlights(highlights.map(h => {
+                const highlight = coerceHighlight(h, assemblyName, (ref, asm) => session.assemblyManager.isValidRefName(ref, asm ?? assemblyName));
+                if (!highlight) {
+                    throw new Error(`not a region to highlight: ${JSON.stringify(h)}`);
+                }
+                return highlight;
+            }));
+        },
+        /**
+         * #action
+         * Show files from the user's disk as session tracks: one per data file,
+         * beside the index among them that names it, its type guessed from its
+         * name. Adds nothing when one file has no known type. Resolves the new
+         * tracks' ids.
+         */
+        async showFiles(files) {
+            return showFiles(self, files);
+        },
     }))
         .views(self => ({
         /**
@@ -2167,6 +2236,9 @@ export function stateModelFactory(pluginManager) {
                 self.coarseTotalBp = blocks.totalBp;
                 self.coarseBpPerPx = bpPerPx;
             }
+            // on every call, since a scroll through the padding before the first
+            // region moves the viewport and leaves the blocks the same
+            self.coarseOffsetPx = self.offsetPx;
         },
     }))
         .actions(self => ({

package/esm/LinearGenomeView/rExport/rScript.d.ts

@@ -15,6 +15,18 @@ export interface RExportTrack {
     heightMode?: unknown;
     height?: unknown;
 }
+/**
+ * Each display ggjbrowse reads, by the reader that reads it, and the adapters
+ * it opens (the slot holding the file and the extension the reader knows it
+ * by).
+ */
+export declare const READERS: Record<string, {
+    call: string;
+    adapters: Record<string, {
+        slot?: string;
+        ext?: RegExp;
+    }>;
+}>;
 /** The ggjbrowse release whose readers and `jbrowse_stack` the script calls. */
 export declare const GGJBROWSE_VERSION = "0.10.0";
 /**
@@ -35,6 +47,15 @@ export declare function rValue(value: unknown): string;
  * `file://` URL as its path, or a `localPath`.
  */
 export declare function locationPath(location: unknown): string | undefined;
+/**
+ * Each sequence adapter `jbrowse_assembly()` builds from a path, by the
+ * extension ggjbrowse reads it off, and the index each takes beside it.
+ */
+export declare const SEQUENCE_ADAPTERS: Record<string, {
+    slot: string;
+    ext: RegExp;
+    beside: Record<string, string>;
+}>;
 /**
  * The view's assembly as the R value every reader takes: `jbrowse_assembly()`
  * of its sequence and alias files where ggjbrowse builds the same config from

package/esm/LinearGenomeView/rExport/rScript.js

@@ -5,7 +5,7 @@ import { resolveUri } from '@jbrowse/core/util';
  * it opens (the slot holding the file and the extension the reader knows it
  * by).
  */
-const READERS = {
+export const READERS = {
     LinearBasicDisplay: {
         call: 'jbrowse_features',
         adapters: {
@@ -216,7 +216,7 @@ function fileArgument(adapters, adapter) {
  * Each sequence adapter `jbrowse_assembly()` builds from a path, by the
  * extension ggjbrowse reads it off, and the index each takes beside it.
  */
-const SEQUENCE_ADAPTERS = {
+export const SEQUENCE_ADAPTERS = {
     TwoBitAdapter: { slot: 'twoBitLocation', ext: /\.2bit$/, beside: {} },
     BgzipFastaAdapter: {
         slot: 'fastaLocation',
@@ -330,7 +330,7 @@ function trackNames(tracks) {
 }
 /** What the figure cannot show of a track whose settings ggjbrowse reads. */
 function settingNotes(track) {
-    const color = track.display.color;
+    const { color } = track.display.encoding ?? {};
     return [
         ...(color?.field === 'mateRefName'
             ? [

package/esm/LinearGenomeView/sharedScaleContainer.js

@@ -1,17 +1,7 @@
-import { getParent, hasParent, isAlive } from '@jbrowse/mobx-state-tree';
+import { findParent } from '@jbrowse/mobx-state-tree';
 export function isSharedScaleContainer(thing) {
     return typeof thing === 'object' && thing !== null && 'sharedFit' in thing;
 }
-// Walks rather than using findParentThatIs because having no such container is
-// the ordinary standalone case here, not the error that helper reports.
 export function sharedScaleContainerOf(node) {
-    let current = node;
-    let found;
-    while (!found && hasParent(current) && isAlive(current)) {
-        current = getParent(current);
-        if (isSharedScaleContainer(current)) {
-            found = current;
-        }
-    }
-    return found;
+    return findParent(node, isSharedScaleContainer);
 }

package/esm/LinearGenomeView/showFiles.d.ts

@@ -0,0 +1,2 @@
+import type { LinearGenomeViewModel } from './model.ts';
+export declare function showFiles(view: LinearGenomeViewModel, files: readonly File[]): Promise<string[]>;

package/esm/LinearGenomeView/showFiles.js

@@ -0,0 +1,19 @@
+import { fileToLocation, getEnv, getSession, isSessionWithAddSessionTrack, } from '@jbrowse/core/util';
+import { pairIndexFiles } from '@jbrowse/core/util/indexCandidates';
+import { guessTrackConfForLocation } from '@jbrowse/core/util/tracks';
+// Every type is guessed before any track is added, so a selection holding one
+// file of no known type adds nothing rather than half of itself.
+export async function showFiles(view, files) {
+    const session = getSession(view);
+    if (!isSessionWithAddSessionTrack(session)) {
+        throw new Error('this session does not take new tracks');
+    }
+    const { pluginManager } = getEnv(view);
+    const assemblyName = view.assemblyNames[0] ?? view.launchAssemblyName;
+    const confs = pairIndexFiles(files).map(({ data, index }) => guessTrackConfForLocation(fileToLocation(data), index && fileToLocation(index), pluginManager, assemblyName));
+    for (const conf of confs) {
+        session.addSessionTrackConf(conf);
+    }
+    await Promise.all(confs.map(conf => view.launchTrack(conf.trackId)));
+    return confs.map(conf => conf.trackId);
+}

package/esm/TrackModifiers/index.d.ts

@@ -0,0 +1,80 @@
+import type { FieldPredicate } from '@jbrowse/core/util/fieldPredicate';
+import type { TrackInit } from '@jbrowse/core/util/tracks';
+import type { DisplaySettings } from '@jbrowse/launch-args/displaySettings';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/** The linear view a command line's tracks open in, as these helpers read it. */
+export interface ModifierView {
+    centerLineInfo?: {
+        refName?: string;
+        offset: number;
+        start: number;
+        end: number;
+        reversed?: boolean;
+        oob?: boolean;
+    };
+    launchTrack: (trackId: string, trackSnapshot?: object, displaySnapshot?: object) => Promise<{
+        displays: unknown[];
+    } | undefined>;
+    showTrack: (trackId: string, trackSnapshot?: object, displaySnapshot?: object) => unknown;
+    tracks: {
+        configuration: {
+            trackId: string;
+        };
+        displays: unknown[];
+        activeDisplay: {
+            configuration: Record<string, unknown>;
+        };
+    }[];
+}
+/**
+ * `displayTypeOf` for a track the session holds, undefined for one it does
+ * not; `displayType` is the display the caller opens it as when no
+ * `display:` modifier names one.
+ */
+export declare function openedDisplayType(session: {
+    getTrackById: (trackId: string) => unknown;
+}, trackId: string, modifiers: string[], displayType?: string): string | undefined;
+/**
+ * Write the `filter` of `trackId`'s `settings` onto its display open in
+ * `view`, by field over the configured filter, as the track menu would.
+ * Returns the display's filter as written, which reopens the track as drawn,
+ * or undefined when the settings write no filter.
+ */
+export declare function writeFilter(view: Pick<ModifierView, 'tracks' | 'showTrack'>, trackId: string, settings: DisplaySettings): FieldPredicate[] | undefined;
+/**
+ * @deprecated `writeFilter`, which every display category takes. This one
+ * writes an alignments `display`'s filter only.
+ */
+export declare function writeReadFilter(display: unknown, displayType: string | undefined, settings: DisplaySettings): FieldPredicate[] | undefined;
+interface LaunchOptions {
+    /** the track entry's own display settings, which the modifiers write over */
+    displaySnapshot?: Record<string, unknown>;
+    trackSnapshot?: Record<string, unknown>;
+    /** changes the settings after the center-line sort resolves, before the open */
+    adjust?: (settings: DisplaySettings) => void;
+    warn?: (message: string) => void;
+}
+/**
+ * Open `trackId` in `view` with its command-line modifiers applied, and return
+ * the session-spec track entry that reopens it as drawn, or undefined when the
+ * open fails, which `launchTrack` reports to the session.
+ */
+export declare function launchTrackWithModifiers(view: ModifierView, trackId: string, displayType: string | undefined, modifiers: string[], { displaySnapshot, trackSnapshot, adjust, warn, }?: LaunchOptions): Promise<{
+    trackId: string;
+    filter?: FieldPredicate[] | undefined;
+} | undefined>;
+/**
+ * Open a session spec's track entry in a navigated `view`, its `modifiers`
+ * written over its display settings. When a modifier or the open fails, the
+ * session's snackbar says why and the track opens with its own settings.
+ */
+export declare function launchTrackInit(view: ModifierView & IAnyStateTreeNode, t: TrackInit): Promise<void>;
+/**
+ * Write a track's `memberWrites` onto what its display in `view` already has,
+ * after every other modifier, so a member write keeps the rest of the setting
+ * whatever order the command line gives them in. A display replaces a color
+ * or facet object whole, which is why these cannot ride in on the launch
+ * snapshot.
+ */
+export declare function writeMembers(view: Pick<ModifierView, 'tracks' | 'showTrack'>, trackId: string, members: string[]): Record<string, unknown>;
+export {};

package/esm/TrackModifiers/index.js

@@ -0,0 +1,212 @@
+import { mergeConfSettings } from '@jbrowse/core/configuration';
+import { getEnv, getSession } from '@jbrowse/core/util';
+import { basePaintedAt } from '@jbrowse/core/util/Base1DUtils';
+import { predicatesOf, testsSomething, withFields, } from '@jbrowse/core/util/fieldPredicate';
+import { normalizeTrackInit, trackDisplayType } from '@jbrowse/core/util/tracks';
+import { buildDisplaySnapshot, displayCategory, memberPatch, memberWrites, mergeSettings, requestedDisplayType, } from '@jbrowse/launch-args/displaySettings';
+import { getSnapshot, getType, isArrayType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+/**
+ * The display a linear view opens `conf` as, read off the display picker so it
+ * follows `display:` and the adapter rather than a list of track types.
+ */
+function displayTypeOf(pluginManager, conf, modifiers, displayType) {
+    return trackDisplayType(pluginManager, conf, 'LinearGenomeView', requestedDisplayType(modifiers) ?? displayType);
+}
+/**
+ * `displayTypeOf` for a track the session holds, undefined for one it does
+ * not; `displayType` is the display the caller opens it as when no
+ * `display:` modifier names one.
+ */
+export function openedDisplayType(session, trackId, modifiers, displayType) {
+    const conf = session.getTrackById(trackId);
+    return conf
+        ? displayTypeOf(getEnv(session).pluginManager, (isStateTreeNode(conf) ? getSnapshot(conf) : conf), modifiers, displayType)
+        : undefined;
+}
+const consoleWarn = (message) => {
+    console.warn(`Warning: ${message}`);
+};
+function modifierLaunch(displayType, modifiers, warn = consoleWarn) {
+    return {
+        displayType,
+        settings: buildDisplaySnapshot(displayType, modifiers, warn),
+        members: memberWrites(displayType, modifiers),
+    };
+}
+// the entries grouped by field, as `setFilterFields` takes them: a field whose
+// entries are all bare is `[]`, which clears it, defaults included
+function filterPatch(entries) {
+    const patch = {};
+    for (const p of entries) {
+        patch[p.field] = [
+            ...(patch[p.field] ?? []),
+            ...(testsSomething(p) ? [p] : []),
+        ];
+    }
+    return patch;
+}
+// the display snapshot a track opens with. `filter` stays out of it:
+// `writeFilter` writes it once the track is open, since the list in a
+// snapshot would replace the configured one
+function launchSnapshot({ settings }) {
+    const { snap, displayType } = settings;
+    const { filter: _filter, ...unfiltered } = snap;
+    return {
+        ...unfiltered,
+        ...(displayType ? { type: displayType } : {}),
+    };
+}
+/**
+ * Write the `filter` of `trackId`'s `settings` onto its display open in
+ * `view`, by field over the configured filter, as the track menu would.
+ * Returns the display's filter as written, which reopens the track as drawn,
+ * or undefined when the settings write no filter.
+ */
+export function writeFilter(view, trackId, settings) {
+    const { filter } = settings.snap;
+    const track = view.tracks.find(t => t.configuration.trackId === trackId);
+    if (!filter || !track) {
+        return undefined;
+    }
+    const patch = filterPatch(filter);
+    const display = track.displays[0];
+    if (display?.setFilterFields) {
+        display.setFilterFields(patch);
+        return display.writtenFilter;
+    }
+    const written = withFields(predicatesOf(track.activeDisplay.configuration.filter), patch);
+    view.showTrack(trackId, {}, { filter: written });
+    return written;
+}
+/**
+ * @deprecated `writeFilter`, which every display category takes. This one
+ * writes an alignments `display`'s filter only.
+ */
+export function writeReadFilter(display, displayType, settings) {
+    const { filter } = settings.snap;
+    if (displayCategory(displayType) !== 'alignments' || !filter) {
+        return undefined;
+    }
+    const filterDisplay = display;
+    filterDisplay?.setFilterFields?.(filterPatch(filter));
+    return filterDisplay?.writtenFilter;
+}
+// the pivot is the base under the view's center, which a view has only once
+// it shows a region
+function centerSort(view, trackId, field, warn) {
+    const center = view.centerLineInfo;
+    if (center && !center.oob) {
+        return {
+            field,
+            pos: basePaintedAt(center, center.offset),
+            refName: center.refName ?? '',
+        };
+    }
+    else {
+        warn(`sort:${field} on "${trackId}" ignored — the view has no center position to sort at (pass --loc)`);
+        return undefined;
+    }
+}
+// The modifiers' settings written over the entry's own as a settings bag
+// writes them (`mergeConfSettings`): a namespace such as `pileup` member by
+// member, a bare value lifted first, and a channel such as `encoding.color`
+// whole, so a `color:` modifier is not mixed into the entry's color by field.
+// Plain JSON where no registered display type says which is which.
+function overEntry(view, displayType, entry, over) {
+    const pluginManager = isStateTreeNode(view)
+        ? getEnv(view).pluginManager
+        : undefined;
+    return displayType && pluginManager?.displayTypes.has(displayType)
+        ? mergeConfSettings(pluginManager.getDisplayType(displayType).configSchema, entry, over)
+        : mergeSettings(structuredClone(entry), over);
+}
+/**
+ * Open `trackId` in `view` with its command-line modifiers applied, and return
+ * the session-spec track entry that reopens it as drawn, or undefined when the
+ * open fails, which `launchTrack` reports to the session.
+ */
+export async function launchTrackWithModifiers(view, trackId, displayType, modifiers, { displaySnapshot = {}, trackSnapshot = {}, adjust, warn = consoleWarn, } = {}) {
+    const launch = modifierLaunch(displayType, modifiers, warn);
+    const { snap, sort } = launch.settings;
+    const at = sort && centerSort(view, trackId, sort.field, warn);
+    if (at) {
+        snap.sort = at;
+    }
+    adjust?.(launch.settings);
+    const launched = overEntry(view, displayType, displaySnapshot, launchSnapshot(launch));
+    const opened = await view.launchTrack(trackId, trackSnapshot, launched);
+    if (!opened) {
+        return undefined;
+    }
+    const drawnFilter = writeFilter(view, trackId, launch.settings);
+    const members = writeMembers(view, trackId, launch.members);
+    return {
+        trackId,
+        ...launched,
+        ...(drawnFilter ? { filter: drawnFilter } : {}),
+        ...members,
+    };
+}
+/**
+ * Open a session spec's track entry in a navigated `view`, its `modifiers`
+ * written over its display settings. When a modifier or the open fails, the
+ * session's snackbar says why and the track opens with its own settings.
+ */
+export async function launchTrackInit(view, t) {
+    const { trackId, trackSnapshot, displaySnapshot, modifiers } = normalizeTrackInit(t);
+    if (modifiers.length === 0) {
+        await view.launchTrack(trackId, trackSnapshot, displaySnapshot);
+        return;
+    }
+    const session = getSession(view);
+    const { type } = displaySnapshot;
+    const notes = [];
+    try {
+        await launchTrackWithModifiers(view, trackId, openedDisplayType(session, trackId, modifiers, typeof type === 'string' ? type : undefined), modifiers, {
+            trackSnapshot,
+            displaySnapshot,
+            warn: message => notes.push(message),
+        });
+    }
+    catch (e) {
+        console.error(e);
+        session.notifyError(`"${trackId}" ${modifiers.join(' ')}: ${e}`, e);
+    }
+    // launchTrack reports its own failure, such as a display:
+    // the track cannot open as
+    if (!view.tracks.some(t => t.configuration.trackId === trackId)) {
+        await view.launchTrack(trackId, trackSnapshot, displaySnapshot);
+    }
+    if (notes.length) {
+        session.notify(notes.join('; '), 'warning');
+    }
+}
+/**
+ * Write a track's `memberWrites` onto what its display in `view` already has,
+ * after every other modifier, so a member write keeps the rest of the setting
+ * whatever order the command line gives them in. A display replaces a color
+ * or facet object whole, which is why these cannot ride in on the launch
+ * snapshot.
+ */
+export function writeMembers(view, trackId, members) {
+    if (members.length === 0) {
+        return {};
+    }
+    const track = view.tracks.find(t => t.configuration.trackId === trackId);
+    if (!track) {
+        throw new Error(`"${trackId}" is not open, so ${members.join(' ')} has nothing to write to`);
+    }
+    const { configuration } = track.activeDisplay;
+    const configured = getSnapshot(configuration);
+    const patch = memberPatch(members, root => {
+        // a list at a default the snapshot strips, Manhattan's marks, still seeds
+        // the write, so `marks.0.mark=bar` edits the mark drawn
+        const member = configuration[root];
+        return (configured[root] ??
+            (isStateTreeNode(member) && isArrayType(getType(member))
+                ? getSnapshot(member)
+                : undefined));
+    });
+    view.showTrack(trackId, {}, patch);
+    return patch;
+}

package/esm/index.d.ts

@@ -29,12 +29,14 @@ export { searchBoxMenuItems, useSearchBoxPrefs, } from './LinearGenomeView/compo
 export type { SearchBoxPrefs } from './LinearGenomeView/components/useSearchBoxPrefs.ts';
 export { normalizeTrackInit } from '@jbrowse/core/util/tracks';
 export { applyInitHighlights } from './LinearGenomeView/afterAttach.ts';
+export { launchTrackInit, launchTrackWithModifiers, openedDisplayType, writeFilter, writeMembers, writeReadFilter, } from './TrackModifiers/index.ts';
+export type { ModifierView } from './TrackModifiers/index.ts';
 export { MultiLevelRubberband, multiLevelRowClickMenuItems, multiLevelRowMenuItems, rowLabels, } from './MultiLevelRubberband/index.ts';
 export { fetchResults, SearchResultsNotFoundError } from './searchUtils.ts';
 export type { LaunchLinearGenomeViewArgs } from './LaunchLinearGenomeView/index.ts';
 export type { BpOffset, ExportSvgOptions, HighlightInput, HighlightType, InitState, LinearGenomeViewLaunchProps, NavLocation, TrackLabelMode, ViewTrackLabelMode, VolatileGuide, } from './LinearGenomeView/types.ts';
 export type { ScalebarRefNameLabel } from './LinearGenomeView/util.ts';
-export type { HighlightRegion, SearchPickerRow, SearchPickerState, } from './LinearGenomeView/model.ts';
+export type { HighlightRegion, SearchHits, SearchPickerRow, SearchPickerState, } from './LinearGenomeView/model.ts';
 export type { RegionsOrientation } from './LinearGenomeView/util.ts';
 export type { RegionEdit } from './LinearGenomeView/util.ts';
 export { makeTicks } from './LinearGenomeView/util.ts';

package/esm/index.js

@@ -71,6 +71,7 @@ export { default as HeaderSearchBoxRow } from './LinearGenomeView/components/Hea
 export { searchBoxMenuItems, useSearchBoxPrefs, } from './LinearGenomeView/components/useSearchBoxPrefs.js';
 export { normalizeTrackInit } from '@jbrowse/core/util/tracks';
 export { applyInitHighlights } from './LinearGenomeView/afterAttach.js';
+export { launchTrackInit, launchTrackWithModifiers, openedDisplayType, writeFilter, writeMembers, writeReadFilter, } from './TrackModifiers/index.js';
 export { MultiLevelRubberband, multiLevelRowClickMenuItems, multiLevelRowMenuItems, rowLabels, } from './MultiLevelRubberband/index.js';
 export { fetchResults, SearchResultsNotFoundError } from './searchUtils.js';
 // The scalebar's grid, published because it is a contract other views draw

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/plugin-linear-genome-view",
-  "version": "5.0.0-beta.17",
+  "version": "5.0.0-beta.18",
   "type": "module",
   "description": "JBrowse 2 linear genome view",
   "keywords": [
@@ -21,15 +21,16 @@
     "esm"
   ],
   "dependencies": {
-    "@jbrowse/mobx-state-tree": "^6.9.0",
+    "@jbrowse/mobx-state-tree": "^6.10.0",
     "@mui/icons-material": "^9.5.0",
     "@mui/material": "^9.5.0",
-    "mobx": "^7.0.6",
+    "mobx": "^7.1.1",
     "mobx-react": "^10.0.2",
-    "@jbrowse/core": "^5.0.0-beta.17",
-    "@jbrowse/display-ui": "^5.0.0-beta.17",
-    "@jbrowse/render-core": "^5.0.0-beta.17",
-    "@jbrowse/display-kit": "^5.0.0-beta.17"
+    "@jbrowse/display-ui": "^5.0.0-beta.18",
+    "@jbrowse/display-kit": "^5.0.0-beta.18",
+    "@jbrowse/launch-args": "^5.0.0-beta.18",
+    "@jbrowse/render-core": "^5.0.0-beta.18",
+    "@jbrowse/core": "^5.0.0-beta.18"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
@@ -40,7 +41,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@jbrowse/display-test-utils": "^5.0.0-beta.17"
+    "@jbrowse/display-test-utils": "^5.0.0-beta.18"
   },
   "scripts": {
     "prebuild": "pnpm clean",