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

package/esm/LinearGenomeView/model.js

@@ -2,12 +2,14 @@ import { canonicalLocString } from '@jbrowse/core/TextSearch/places';
 import { getConf, readConfObject } from '@jbrowse/core/configuration';
 import { BaseViewModel } from '@jbrowse/core/pluggableElementTypes/models';
 import { exportViewSvg } from '@jbrowse/core/svg/exportViewSvg';
-import { assembleLocString, clamp, getBpDisplayStr, getNotificationSink, getSession, isSessionModelWithWidgets, localStorageGetBoolean, localStorageGetItem, localStorageSetBoolean, localStorageSetItem, springAnimate, sum, } from '@jbrowse/core/util';
+import { highlightListMenuItems } from '@jbrowse/core/ui/menuItems';
+import { assembleLocString, clamp, getBpDisplayStr, getEnv, getNotificationSink, getSession, isSessionModelWithWidgets, localStorageGetBoolean, localStorageGetItem, localStorageSetBoolean, localStorageSetItem, springAnimate, sum, } from '@jbrowse/core/util';
 import { bpToLinearBp, bpToPx, computeMoveToLayout, createOverviewLayout, getLayoutHighlightCoords, getOverviewRegionPxSpan, moveTo, pxToBp, } from '@jbrowse/core/util/Base1DUtils';
 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 +19,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 +29,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).
@@ -260,11 +298,11 @@ export function stateModelFactory(pluginManager) {
         hideNoTracksActive: types.stripDefault(types.boolean, false),
         /**
          * #property
-         * vestigial: the hierarchical selector is the only one that exists, so
-         * this value is ignored. Retained because saved sessions and share
-         * links persist it.
+         * ignored: the hierarchical selector is the only one. Declared because
+         * saved sessions and share links carry it.
+         * @deprecated
          */
-        trackSelectorType: types.stripDefault(types.enumeration(['hierarchical']), 'hierarchical'),
+        trackSelectorType: types.stripDefault(types.string, 'hierarchical'),
         /**
          * #property
          * show the "center line". A personal preference: never in a session
@@ -388,6 +426,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 +1184,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 +1310,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 +1322,29 @@ 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 results = await fetchResults({
+                session: getSession(self),
+                queryString: query,
+                assemblyName,
+                signal: opts?.signal,
+            });
+            return searchHitsOf(self, results, query, assemblyName, result => navToOption({
+                option: result,
+                model: self,
+                assemblyName,
+            }));
+        },
         /**
          * #action
          */
@@ -1337,6 +1377,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 +2235,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 => ({
@@ -2177,7 +2248,7 @@ export function stateModelFactory(pluginManager) {
          *
          * The coarse blocks are a 500ms throttle, and every consumer trades
          * freshness for not recomputing per animation frame — the location box,
-         * canvas's on-screen feature set, and the two per-bp scans behind
+         * the feature display's on-screen feature set, and the two per-bp scans behind
          * `settledDynamicBlocks`. That trade is only sound while the answer is a
          * few frames old. **A jump makes it unrelated instead**, because there is
          * nothing to coalesce: the viewport left behind is not an approximation of
@@ -2638,16 +2709,26 @@ export function stateModelFactory(pluginManager) {
                 getSession(self).addHighlight(region);
             }
         },
+        /**
+         * #action
+         * navigates to a highlight, zoomed out a little for context. Goes through
+         * a locstring so it reaches a refName the view is not displaying
+         */
+        navToHighlight(highlight) {
+            const { assemblyName, ...region } = highlight;
+            return self.navToLocString(assembleLocString(region), assemblyName, 0.2);
+        },
+    }))
+        .actions(self => ({
         /**
          * #action
          * navigates to the most recently added highlight on this view's
-         * assemblies, zoomed out a little for context
+         * assemblies
          */
         async navigateNewestHighlight() {
             const newest = self.highlights.at(-1);
             if (newest) {
-                const { assemblyName, ...region } = newest;
-                await self.navToLocString(assembleLocString(region), assemblyName, 0.2);
+                await self.navToHighlight(newest);
             }
             else {
                 getSession(self).notify('There are no highlights to navigate to.', 'info');
@@ -2758,11 +2839,10 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #method
-         * returns menu items for a highlight context menu. plugins can extend
-         * this via Core-extendPluggableElement to add items
+         * a highlight chip's menu rows after Dismiss; extend this to add one
          */
         highlightMenuItems(_highlight) {
-            return [];
+            return highlightListMenuItems(getSession(self), getEnv(self).pluginManager);
         },
     }))
         .actions(self => {

package/esm/LinearGenomeView/rExport/exportLinearView.js

@@ -2,9 +2,6 @@ import { fullConfSnapshot, readConfObject } from '@jbrowse/core/configuration';
 import { getSession } from '@jbrowse/core/util';
 import { getSnapshot } from '@jbrowse/mobx-state-tree';
 import { exportTracksToR } from './rScript.js';
-function trackConf(track) {
-    return track.configuration;
-}
 /** The regions on screen, each displayed region cut to what the view shows of it. */
 function viewRegions(view) {
     const blocks = view.dynamicBlocks.contentBlocks;
@@ -52,10 +49,10 @@ function tracksOf(view) {
             const { heightMode, height } = fullConfSnapshot(display.configuration);
             tracks.push({
                 trackId: track.configuration.trackId,
-                trackName: readConfObject(trackConf(track), 'name') ||
+                trackName: readConfObject(track.configuration, 'name') ||
                     track.configuration.trackId,
                 displayType: display.type,
-                adapter: readConfObject(trackConf(track), 'adapter'),
+                adapter: readConfObject(track.configuration, 'adapter'),
                 display: written,
                 heightMode,
                 height,
@@ -71,6 +68,8 @@ export function exportLinearViewToR(view, out) {
         regions: viewRegions(view),
         assembly: assemblyOf(view),
         bpPerPx: view.bpPerPx,
+        colorByFrame: view.colorByFrame,
+        showAminoAcids: view.showAminoAcids,
         out,
         notes: view.displayedRegions.some(r => r.reversed)
             ? ['view: shown right to left, where the figure runs left to right']

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
@@ -54,13 +75,17 @@ export declare function locusOf(refName: string, start: number, end: number): st
  * header instead of stopping the figure: a script that quietly differs from
  * its view says so.
  */
-export declare function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, bpPerPx, out, notes: viewNotes, }: {
+export declare function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, bpPerPx, colorByFrame, showAminoAcids, out, notes: viewNotes, }: {
     tracks: readonly RExportTrack[];
     regions: readonly Region[];
     /** The view's assembly config as written, which names its sequence and its contigs' aliases. */
     assembly?: Record<string, unknown>;
     /** The view's zoom, which decides what a feature or quantitative display shows. */
     bpPerPx?: number;
+    /** The view's "CDS reading frame colors", which a feature track takes. */
+    colorByFrame?: boolean;
+    /** The view's "Amino acids when zoomed in", which a feature track takes. */
+    showAminoAcids?: boolean;
     out?: string;
     /** What the caller knows of the view that the figure does not show. */
     notes?: readonly string[];

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: {
@@ -93,9 +93,15 @@ const RESERVED = new Set([
     'Inf',
     'NaN',
     'NA',
+    'NA_integer_',
+    'NA_real_',
+    'NA_complex_',
+    'NA_character_',
 ]);
 function isIdentifier(s) {
-    return /^[A-Za-z.][A-Za-z0-9._]*$/.test(s) && !RESERVED.has(s);
+    return (/^([A-Za-z]|\.(?!\d))[A-Za-z0-9._]*$/.test(s) &&
+        !/^(\.\.\.|\.\.\d+)$/.test(s) &&
+        !RESERVED.has(s));
 }
 /**
  * A config value as the R literal ggjbrowse hands the engine: a `list` per
@@ -216,7 +222,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',
@@ -328,9 +334,19 @@ function trackNames(tracks) {
         return name;
     });
 }
+/**
+ * A track's `jbrowse_stack()` argument, named as the view labels it so its
+ * band is titled. A name `width` would set the stack's own `width`, so that
+ * one goes in a list, whose names title its tracks too.
+ */
+function stackArgument(title, name) {
+    return title === 'width'
+        ? `list(width = ${name})`
+        : `${isIdentifier(title) ? title : rStr(title)} = ${name}`;
+}
 /** 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'
             ? [
@@ -346,7 +362,7 @@ function settingNotes(track) {
  * header instead of stopping the figure: a script that quietly differs from
  * its view says so.
  */
-export function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, bpPerPx, out = 'figure.png', notes: viewNotes = [], }) {
+export function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, bpPerPx, colorByFrame = false, showAminoAcids = true, out = 'figure.png', notes: viewNotes = [], }) {
     const notes = [...viewNotes];
     const assembly = assemblySnapshot && assemblyArgument(assemblySnapshot);
     if (assembly && 'skipped' in assembly) {
@@ -360,6 +376,7 @@ export function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, b
     const names = trackNames(tracks);
     const reads = [];
     const drawn = [];
+    const bands = [];
     let alignments;
     tracks.forEach((track, i) => {
         const reader = READERS[track.displayType];
@@ -381,10 +398,13 @@ export function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, b
             }
             : track.display;
         const width = viewPx !== undefined;
+        const geneTrack = track.displayType === 'LinearBasicDisplay';
         const args = [
             ...(Object.keys(display).length ? [`display = ${rValue(display)}`] : []),
             ...(width ? ['width = width'] : []),
             ...(assemblyValue ? ['assembly = assembly'] : []),
+            ...(geneTrack && colorByFrame ? ['color_by_cds = TRUE'] : []),
+            ...(geneTrack && !showAminoAcids ? ['amino_acids = FALSE'] : []),
             ...(source.index ? [`index = ${rStr(source.index)}`] : []),
         ];
         const name = names[i];
@@ -397,6 +417,7 @@ export function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, b
             `  ${['locus', ...args].join(',\n  ')})`,
         ].join('\n'));
         drawn.push(name);
+        bands.push(stackArgument(track.trackName, name));
         if (reader.call === 'jbrowse_alignments') {
             alignments ??= name;
         }
@@ -456,7 +477,7 @@ export function exportTracksToR({ tracks, regions, assembly: assemblySnapshot, b
         '',
         reads.join('\n\n'),
         '',
-        `fig <- jbrowse_stack(${drawn.join(', ')})`,
+        `fig <- jbrowse_stack(${bands.join(',\n  ')})`,
         'print(fig)',
         `ggplot2::ggsave(${rStr(out)}, fig, width = jbrowse_width(fig), height = jbrowse_height(fig))`,
         '',

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/LinearGenomeView/showRegionsWithUndo.d.ts

@@ -6,7 +6,7 @@ import type { Region } from '@jbrowse/core/util/types';
  *
  * This is the "navigate the view you are looking at" half of a launcher, as
  * against `session.addView`, which opens a second one. Two features do it —
- * plugin-canvas's collapsed introns and plugin-alignments' "view mate region" —
+ * plugin-features's collapsed introns and plugin-alignments' "view mate region" —
  * and both had their own copy of the same fifteen lines, including the same two
  * decisions worth stating once:
  *

package/esm/LinearGenomeView/showRegionsWithUndo.js

@@ -6,7 +6,7 @@ import { transaction } from 'mobx';
  *
  * This is the "navigate the view you are looking at" half of a launcher, as
  * against `session.addView`, which opens a second one. Two features do it —
- * plugin-canvas's collapsed introns and plugin-alignments' "view mate region" —
+ * plugin-features's collapsed introns and plugin-alignments' "view mate region" —
  * and both had their own copy of the same fifteen lines, including the same two
  * decisions worth stating once:
  *

package/esm/LinearGenomeView/svgcomponents/SVGLinearGenomeView.js

@@ -39,7 +39,9 @@ export async function renderToSvg(model, opts) {
         textHeight,
         trackLabels,
     });
-    notifySkippedSvgTracks(session, skippedTracks);
+    if (opts.announceSkipped !== false) {
+        notifySkippedSvgTracks(session, skippedTracks);
+    }
     // read after the displays' waits, and handed to SVGHeader rather than read
     // again, so the reserved `tracksTop` and the drawn header are one layout
     const { width, effectiveShowCytobands } = model;

package/esm/LinearGenomeView/util.d.ts

@@ -25,7 +25,7 @@ interface CenterKeepingView {
  * A caller building a view SNAPSHOT does: it has no model to call
  * `fitAllRegions()` on, and naming `bpPerPx`/`offsetPx` instead is dropped
  * whenever the snapshot also carries a `windowWidthBp` — which one copied off an
- * existing view always does. plugin-canvas's collapsed-intron launch is that
+ * existing view always does. plugin-features's collapsed-intron launch is that
  * caller. A live view calls `fitAllRegions()`.
  *
  * `width` enters only through the zoom-in floor, which bites for a region set

package/esm/LinearGenomeView/util.js

@@ -18,7 +18,7 @@ import { tickLabelsWorthDrawing } from '@jbrowse/core/util/tickLabels';
  * A caller building a view SNAPSHOT does: it has no model to call
  * `fitAllRegions()` on, and naming `bpPerPx`/`offsetPx` instead is dropped
  * whenever the snapshot also carries a `windowWidthBp` — which one copied off an
- * existing view always does. plugin-canvas's collapsed-intron launch is that
+ * existing view always does. plugin-features's collapsed-intron launch is that
  * caller. A live view calls `fitAllRegions()`.
  *
  * `width` enters only through the zoom-in floor, which bites for a region set

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 {};