@jbrowse/plugin-linear-genome-view 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/LinearGenomeView/model.js

@@ -1,29 +1,39 @@
 import { lazy } from 'react';
 import { getConf } from '@jbrowse/core/configuration';
-import { BaseViewModel, HighlightsMixin, } from '@jbrowse/core/pluggableElementTypes/models';
-import { VIEW_HEADER_HEIGHT } from '@jbrowse/core/ui';
+import { BaseViewModel } from '@jbrowse/core/pluggableElementTypes/models';
+import { exportViewSvg } from '@jbrowse/core/svg/exportViewSvg';
 import { assembleLocString, clamp, getBpDisplayStr, getDialogHost, getSession, getTickDisplayStr, isSessionModelWithWidgets, localStorageGetBoolean, localStorageGetItem, 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 { tickLabelsWorthDrawing } from '@jbrowse/core/util/tickLabels';
-import { hideTrackGeneric, showTrackGeneric, toggleTrackGeneric, } from '@jbrowse/core/util/tracks';
+import { hideTrackGeneric, launchToggleTrackGeneric, launchTrackGeneric, showTrackGeneric, toggleTrackGeneric, } from '@jbrowse/core/util/tracks';
 import { ElementId } from '@jbrowse/core/util/types/mst';
-import { computeViewStatus } from '@jbrowse/core/util/viewStatus';
+import { highlightsOnAssemblies } from '@jbrowse/core/util/viewHighlights';
+import { assemblyErrorMessage, computeViewStatus, viewLoading, } from '@jbrowse/core/util/viewStatus';
+import { pendingLaunch, withLaunchInput, } from '@jbrowse/core/util/withLaunchInput';
+import { MIN_DISPLAY_HEIGHT } from '@jbrowse/display-kit/const';
+import { contentRightEdgePx } from '@jbrowse/display-kit/regionHost';
 import { cast, getParent, hasParent, isAlive, types, } from '@jbrowse/mobx-state-tree';
-import { when } from 'mobx';
-import { handleSelectedRegion } from '../searchUtils.js';
+import { observable, when } from 'mobx';
+import { handleSelectedRegion, navToOption } from '../searchUtils.js';
 import { doAfterAttach } from './afterAttach.js';
-import { shouldSwapTracks } from './components/util.js';
-import { HEADER_BAR_HEIGHT, HEADER_OVERVIEW_HEIGHT, MIN_BP_PER_PX, MINIMIZED_TRACK_HEIGHT, RESIZE_HANDLE_HEIGHT, SCALE_BAR_HEIGHT, SHOW_ALL_REGIONS_FILL, TRACK_OUTLINE_BORDER, TRACK_TOP_GAP, } from './consts.js';
+import { getCytobands, shouldSwapTracks } from './components/util.js';
+import { HEADER_BAR_HEIGHT, HEADER_OVERVIEW_HEIGHT, MIN_BP_PER_PX, MINIMIZED_TRACK_HEIGHT, MINIMUM_BLOCK_WIDTH, RESIZE_ALL_HANDLE_HEIGHT, RESIZE_HANDLE_HEIGHT, SCALE_BAR_HEIGHT, SHOW_ALL_REGIONS_FILL, TRACK_OUTLINE_BORDER, TRACK_TOP_GAP, } from './consts.js';
 import { planFlight } from './flyTo.js';
 import { setupKeyboardHandler } from './keyboardHandler.js';
-import { buildMenuItems, buildRubberBandMenuItems, buildRubberbandClickMenuItems, } from './menuItems.js';
+import { lgvLaunchKeys } from './launchKeys.js';
+import { buildHighlightsSubMenuItems, buildMenuItems, buildRubberBandMenuItems, buildRubberbandClickMenuItems, } from './menuItems.js';
 import { sharedScaleContainerOf } from './sharedScaleContainer.js';
-import { calculateVisibleLocStrings, cytobandLabelGutterWidth, expandRegion, fitAllRegionsWindow, generateLocations, getScalebarRefNameLabels, regionsOrientation, groupContiguousBlocks, labelFitsInBlock, makeBlockTicks, runRefNameLabelPx, tickLabelWidth, } from './util.js';
+import { calculateVisibleLocStrings, cytobandLabelGutterWidth, expandRegion, fitAllRegionsWindow, generateLocations, getScalebarRefNameLabels, regionsOrientation, groupContiguousBlocks, labelFitsInBlock, makeBlockTicks, runRefNameLabelPx, setDisplayedRegionsKeepingCenter, tickLabelWidth, } from './util.js';
 // lazies
 const SearchResultsDialog = lazy(() => import('./components/SearchResultsDialog.js'));
+// The one array `paddingSpans` returns when a view has nothing to mask, so that
+// computed's value repeats by identity. Frozen because every consumer maps over
+// it and a caller that sorted in place would do so for the whole session.
+const NO_PADDING_SPANS = Object.freeze([]);
 /**
  * Calculate the offsetPx needed to center content within a viewport.
  * Returns a negative offset when content is smaller than viewport (padding on left).
@@ -32,16 +42,20 @@ function getCenteredOffsetPx(contentPx, viewportPx) {
     return Math.round(contentPx / 2 - viewportPx / 2);
 }
 /**
- * Resolve a region's refName to the assembly's canonical name, falling back to
- * the raw refName when the assemblyName is missing or unknown (so highlights
- * authored without an assembly still render in single-assembly views).
+ * A refName in the named assembly's canonical spelling, or unchanged when that
+ * assembly is missing or unknown, so a highlight authored without one still
+ * lands in a single-assembly view.
  */
-function resolveCanonicalRefName(self, region) {
+function canonicalRefName(assemblyManager, assemblyName, refName) {
+    const asm = assemblyName ? assemblyManager.get(assemblyName) : undefined;
+    return asm?.getCanonicalRefName2(refName) ?? refName;
+}
+function canonicalHighlight(self, region) {
     const { assemblyManager } = getSession(self);
-    const asm = region.assemblyName
-        ? assemblyManager.get(region.assemblyName)
-        : undefined;
-    return asm?.getCanonicalRefName2(region.refName) ?? region.refName;
+    return {
+        ...region,
+        refName: canonicalRefName(assemblyManager, region.assemblyName, region.refName),
+    };
 }
 // bpPerPx deltas smaller than this are treated as no zoom change, avoiding
 // pointless offset re-anchoring on micro-steps
@@ -58,16 +72,6 @@ function sameBlockKeys(a, b) {
     return (a.blocks.length === b.blocks.length &&
         a.blocks.every((block, i) => block.key === b.blocks[i].key));
 }
-/**
- * Resolve a NavLocation's refName to the assembly's canonical name, falling
- * back to the raw refName (and the view's default assembly) when the assembly
- * is missing or unknown.
- */
-function navLocationRefName(assemblyManager, defaultAssemblyName, location) {
-    return (assemblyManager
-        .get(location.assemblyName || defaultAssemblyName)
-        ?.getCanonicalRefName2(location.refName) || location.refName);
-}
 /**
  * Resolve one end of a navigation range to the displayedRegion index that
  * contains it plus the bp offset into that region. `side` selects which edge of
@@ -77,7 +81,7 @@ function navLocationRefName(assemblyManager, defaultAssemblyName, location) {
  * resolved against those raw coords, and only the region it picks bounds `grow`.
  */
 function resolveNavEndpoint({ location, assemblyManager, defaultAssemblyName, side, displayedRegions, grow, }) {
-    const refName = navLocationRefName(assemblyManager, defaultAssemblyName, location);
+    const refName = canonicalRefName(assemblyManager, location.assemblyName || defaultAssemblyName, location.refName);
     const first = displayedRegions.find(r => r.refName === refName);
     if (!first) {
         throw new Error(`could not find a region with refName "${refName}"`);
@@ -141,30 +145,27 @@ function isTrackSelectorVisible(self) {
  * #category view
  *
  * #example
- * A `LinearGenomeView` is what you hand-author under `defaultSession.views`. The
- * `init` shorthand fills in `displayedRegions`/`bpPerPx`/`offsetPx` for you:
+ * A `LinearGenomeView` is what you hand-author under `defaultSession.views`, and
+ * every setting goes directly on the view object. `assembly`/`loc` fill in
+ * `displayedRegions`/`bpPerPx`/`offsetPx` for you:
  * ```js
  * defaultSession: {
  *   name: 'My session',
  *   views: [
  *     {
  *       type: 'LinearGenomeView',
- *       // plain persisted props sit alongside init, not inside it
  *       colorByCDS: true,
- *       init: {
- *         assembly: 'hg38',
- *         loc: 'chr1:1,000,000-1,100,000',
- *         tracks: ['genes', 'alignments'],
- *       },
+ *       assembly: 'hg38',
+ *       loc: 'chr1:1,000,000-1,100,000',
+ *       tracks: ['genes', 'alignments'],
  *     },
  *   ],
  * }
  * ```
- * `init` holds only keys that need on-attach resolution — also `tracklist`,
- * `nav`, `highlight` (see the `init` property below). Plain view props like
- * `colorByCDS`, `showAminoAcids`, `showCenterLine`, `trackLabels`,
- * `showHighlightChips` are set
- * directly on the view (MST restores them natively).
+ * `assembly`, `loc`, `tracks`, `tracklist`, `nav` and `highlight` need
+ * on-attach resolution and are captured into the `launch` property below;
+ * `colorByCDS`, `showAminoAcids`, `showCenterLine` and `trackLabels` are plain
+ * view props MST restores natively. Both are written the same way.
  * At runtime the same model is driven imperatively — every property and action
  * below is reachable on `viewState.session.views[0]`:
  * ```js
@@ -175,8 +176,8 @@ function isTrackSelectorVisible(self) {
  * ```
  */
 export function stateModelFactory(pluginManager) {
-    return types
-        .compose('LinearGenomeView', BaseViewModel, HighlightsMixin(), types.model({
+    const model = types
+        .compose('LinearGenomeView', BaseViewModel, types.model({
         /**
          * #property
          */
@@ -214,8 +215,8 @@ export function stateModelFactory(pluginManager) {
         windowWidthBp: types.stripDefault(types.number, 0),
         /**
          * #property
-         * MIGRATION ONLY, and safe to delete once pre-window sessions are no
-         * longer in circulation.
+         * MIGRATION ONLY, and permanent: share links written before the window
+         * was stored carry `bpPerPx`/`offsetPx`, and there are many of them.
          *
          * A snapshot written before the window was stored carries `offsetPx` and
          * `bpPerPx` but not the width they were measured at, so the window they
@@ -260,8 +261,8 @@ export function stateModelFactory(pluginManager) {
         /**
          * #property
          * vestigial: the hierarchical selector is the only one that exists, so
-         * this value is ignored. Retained because saved sessions and configs
-         * persist it.
+         * this value is ignored. Retained because saved sessions and share
+         * links persist it.
          */
         trackSelectorType: types.stripDefault(types.enumeration(['hierarchical']), 'hierarchical'),
         /**
@@ -282,7 +283,7 @@ export function stateModelFactory(pluginManager) {
          * "hidden", or empty string "" (which results in the
          * LinearGenomeViewPlugin config default being used). the resolved value
          * is the `effectiveTrackLabels` getter. see LinearGenomeViewPlugin
-         * https://jbrowse.org/jb2/docs/config/lineargenomeviewplugin/ docs for
+         * https://jbrowse.org/jb2/docs/config/lineargenomeviewconfigschema/ docs for
          * how conf is used
          */
         trackLabels: types.optional(types.string, () => localStorageGetItem('lgv-trackLabels') ?? ''),
@@ -291,11 +292,6 @@ export function stateModelFactory(pluginManager) {
          * show the "gridlines" in the track area
          */
         showGridlines: types.stripDefault(types.boolean, true),
-        /**
-         * #property
-         * controls whether highlight/bookmark chip labels are shown inline
-         */
-        labelsVisible: types.stripDefault(types.boolean, true),
         /**
          * #property
          * color CDS segments by reading frame
@@ -321,51 +317,52 @@ export function stateModelFactory(pluginManager) {
         scalebarOnly: types.stripDefault(types.boolean, false),
         /**
          * #property
-         * transient declarative launch spec: assembly + optional location,
-         * tracks, and highlights to apply once the view attaches. It is applied
-         * by the afterAttach autorun and then cleared (setInit(undefined)), so a
-         * saved session never retains it. Shared by all three launch surfaces —
-         * URL params, createViewState(), and session/config JSON. example:
-         * ```json
-         * {
-         *   "assembly": "hg19",
-         *   "loc": "chr1:1,000,000-2,000,000",
-         *   "tracks": ["genes", "variants"]
-         * }
-         * ```
-         */
-        init: types.frozen(),
+         * transient launch state: the settings written on the view object that
+         * need resolving before they can be view state — an assembly, a
+         * location, track recipes, highlights. `preProcessSnapshot` moves them
+         * here off the snapshot, the afterAttach autorun applies them and
+         * clears this, so a saved session never retains it. Not written by
+         * hand: author every setting directly on the view.
+         */
+        launch: types.frozen(),
     }))
-        .volatile(self => {
+        .volatile(() => {
         // typed locals so `unknown`/`Record` aren't narrowed to `undefined`/`{}`; inline
         // type assertions here get stripped by no-unnecessary-type-assertion
         const volatileError = undefined;
-        const trackRefs = {};
         return {
             /**
              * #volatile
+             * Height of each track's in-flow label band, measured by
+             * TrackContainer as the rendering container's offset inside its Paper.
+             * Absent (0) while the label is hidden, overlapping, or not yet
+             * measured. Observable, so the offset and height getters re-derive
+             * when a band changes.
              */
-            volatileWidth: undefined,
+            trackLabelBands: observable.map(),
             /**
              * #volatile
+             * How much taller the view's box is than the scroll port it sits in,
+             * in px, negative when it is shorter. Measured by the view component
+             * for a top-level view; undefined until then, and for a nested one.
              */
-            minimumBlockWidth: 3,
+            scrollPortExcess: undefined,
             /**
              * #volatile
              */
-            draggingTrackId: undefined,
+            volatileWidth: undefined,
             /**
              * #volatile
              */
-            lastTrackDragY: undefined,
+            draggingTrackId: undefined,
             /**
              * #volatile
              */
-            volatileError,
+            lastTrackDragY: undefined,
             /**
              * #volatile
              */
-            trackRefs,
+            volatileError,
             /**
              * #volatile
              */
@@ -377,14 +374,10 @@ export function stateModelFactory(pluginManager) {
             /**
              * #volatile
              */
-            // What `bpPerPx` used to hold at creation — the snapshot's value, or
-            // the default of 1 — which cannot be read here now that it is derived
-            // and declared after volatile. It has to be a real scale rather than
-            // the not-yet-measured 0: the canvas displays lay out against
-            // `coarseBpPerPx` rather than the live one, and a zero there is a
-            // degenerate layout for the frame or two before the debounced autorun
-            // first writes it.
-            coarseBpPerPx: self.legacyBpPerPx || 1,
+            // A real scale rather than the not-yet-measured 0, for the canvas
+            // displays that lay out against it; `setWidth` seeds the true one at
+            // the first measure.
+            coarseBpPerPx: 1,
             /**
              * #volatile
              */
@@ -397,10 +390,6 @@ export function stateModelFactory(pluginManager) {
              * #volatile
              */
             isScalebarRefNameMenuOpen: false,
-            /**
-             * #volatile
-             */
-            scalebarRefNameClickPending: false,
             /**
              * #volatile
              * temporary vertical guides that can be set by displays (e.g., LD display hover)
@@ -413,6 +402,14 @@ export function stateModelFactory(pluginManager) {
         // ahead of every other getter so that the ~300 reads of `self.bpPerPx` /
         // `self.offsetPx` across the codebase go on resolving by name. Only the
         // writes had to move, and they are six actions below.
+        /**
+         * #getter
+         * the launch state that still has something to apply — the gate every
+         * loading and error path below reads.
+         */
+        get pendingLaunch() {
+            return pendingLaunch(self.launch);
+        },
         /**
          * #getter
          * corresponds roughly to the zoom level, base-pairs per pixel.
@@ -437,6 +434,14 @@ export function stateModelFactory(pluginManager) {
             const { bpPerPx } = this;
             return bpPerPx <= 0 ? 0 : self.windowStartBp / bpPerPx;
         },
+        /**
+         * #getter
+         * a displayed region narrower than this many pixels draws as an elided
+         * block
+         */
+        get minimumBlockWidth() {
+            return MINIMUM_BLOCK_WIDTH;
+        },
         /**
          * #getter
          * scroll-to-zoom is a global, personal preference resolved from the
@@ -498,6 +503,14 @@ export function stateModelFactory(pluginManager) {
             const { assemblyManager } = getSession(self);
             return this.assemblyNames.map(a => assemblyManager.getDisplayName(a));
         },
+        /**
+         * #getter
+         * the session's highlights on this view's assemblies
+         */
+        get highlights() {
+            const { highlights, assemblyManager } = getSession(self);
+            return highlightsOnAssemblies(highlights, this.assemblyNames, assemblyManager);
+        },
         /**
          * #getter
          * checking if lgv is a 'top-level' view is used for toggling pin track
@@ -524,8 +537,23 @@ export function stateModelFactory(pluginManager) {
         .views(self => ({
         /**
          * #getter
-         * Assembly-name prefix for the scalebar refName labels, or undefined for
-         * none. A container view (e.g. LinearSyntenyView) opts its sub-views in by
+         * The census entry for this view: the tracks it holds itself. Declared
+         * rather than derived — see `BaseViewModel.ownTracks`.
+         */
+        get ownTracks() {
+            return [...self.tracks];
+        },
+        /**
+         * #getter
+         * See `BaseViewModel.rendersDisplays`.
+         */
+        get rendersDisplays() {
+            return !self.scalebarOnly;
+        },
+        /**
+         * #getter
+         * Assembly name captioning the scalebar ahead of its refName labels, or
+         * undefined for none. A container view (e.g. LinearSyntenyView) opts its sub-views in by
          * exposing showAssemblyNameInSubviewScalebar; duck-typed rather than
          * matching a concrete view type so no upward plugin dependency is needed
          * and any container can opt in. A wrong nesting depth simply yields no
@@ -555,10 +583,7 @@ export function stateModelFactory(pluginManager) {
          */
         get assemblyErrors() {
             const { assemblyManager } = getSession(self);
-            return self.assemblyNames
-                .map(name => assemblyManager.get(name)?.error)
-                .filter(e => !!e)
-                .join(', ');
+            return assemblyErrorMessage(assemblyManager, self.assemblyNames);
         },
         /**
          * #getter
@@ -575,10 +600,23 @@ export function stateModelFactory(pluginManager) {
          * and error checks resolve it directly through here.
          */
         get initAssembly() {
-            return self.init
-                ? getSession(self).assemblyManager.get(self.init.assembly)
+            const name = this.launchAssemblyName;
+            return self.pendingLaunch && name !== undefined
+                ? getSession(self).assemblyManager.get(name)
                 : undefined;
         },
+        /**
+         * #getter
+         * The assembly a pending launch is for: the one it names, else the one
+         * the view already shows. A re-launch of a materialized view (a
+         * `jb.setSession` document writing `loc` beside the built state) need
+         * not restate it; without the default the readiness gate waited on
+         * `assemblyManager.get(undefined)` for good. Undefined on a fresh view
+         * whose blob names none, which `error` reports.
+         */
+        get launchAssemblyName() {
+            return self.pendingLaunch?.assembly ?? self.assemblyNames[0];
+        },
         /**
          * #getter
          */
@@ -587,7 +625,7 @@ export function stateModelFactory(pluginManager) {
                 return false;
             }
             // if init is set, wait for that assembly to have regions loaded
-            if (self.init) {
+            if (self.pendingLaunch) {
                 const asm = this.initAssembly;
                 return !!(asm?.initialized && asm.regions);
             }
@@ -606,47 +644,23 @@ export function stateModelFactory(pluginManager) {
          * displayed assemblies that hasn't finished loading.
          */
         get loadingAssembly() {
-            return self.init
+            return self.pendingLaunch
                 ? this.initAssembly
                 : getSession(self).assemblyManager.loadingAssembly(self.assemblyNames);
         },
         /**
          * #getter
-         * What the spinner says. The assembly reports which of its files it is
-         * downloading, so this is "Downloading chromosome aliases" rather than a bare
-         * "Loading" for the part of startup that actually takes time. Falls back
-         * once the assembly is loaded and the remaining wait is the init autorun's
-         * own navigation, which is local.
-         */
-        get loadingMessage() {
-            return this.showLoading
-                ? this.loadingAssembly?.statusMessage || 'Loading'
-                : undefined;
-        },
-        /**
-         * #getter
-         * Determinate fraction for the spinner's bar, when the assembly load
-         * reports one (a whole-file download with a Content-Length)
-         */
-        get loadingProgress() {
-            return this.showLoading
-                ? this.loadingAssembly?.statusProgress
-                : undefined;
-        },
-        /**
-         * #getter
-         * The URL the assembly load is currently fetching, when the phase named
-         * one. Only the stalled-load notice reads it — see
-         * {@link ViewLoadingScreen}.
+         * What the loading screen says while `showLoading`, read off the
+         * assembly whose load is the wait; undefined otherwise.
          */
-        get loadingSource() {
-            return this.showLoading ? this.loadingAssembly?.statusSource : undefined;
+        get loading() {
+            return viewLoading(this.showLoading, () => this.loadingAssembly);
         },
         /**
          * #getter
          */
         get hasSomethingToShow() {
-            return this.hasDisplayedRegions || !!self.init;
+            return this.hasDisplayedRegions || !!self.pendingLaunch;
         },
         /**
          * #getter
@@ -656,7 +670,7 @@ export function stateModelFactory(pluginManager) {
          * would mount over empty regions and pxToBp/hover would throw.
          *
          * **Not dotplot's or synteny's `initPending`**, which is the bare
-         * `!!self.init` — "an init blob has not been applied" — and which those
+         * `!!self.pendingLaunch` — "an init blob has not been applied" — and which those
          * views read from their `settled` gate rather than from `showLoading`.
          * This one is narrower on purpose: it closes only the window where there
          * is nothing on screen. Once navigation has produced regions the view is
@@ -666,7 +680,7 @@ export function stateModelFactory(pluginManager) {
          * theirs.
          */
         get awaitingInitNavigation() {
-            return !!self.init && !this.hasDisplayedRegions;
+            return !!self.pendingLaunch && !this.hasDisplayedRegions;
         },
         /**
          * #getter
@@ -719,12 +733,7 @@ export function stateModelFactory(pluginManager) {
             return computeViewStatus({
                 error: this.error,
                 hasSomethingToShow: this.hasSomethingToShow,
-                loading: () => this.showLoading
-                    ? {
-                        message: this.loadingMessage ?? 'Loading',
-                        progress: this.loadingProgress,
-                    }
-                    : undefined,
+                loading: () => this.loading,
             });
         },
         /**
@@ -754,14 +763,10 @@ export function stateModelFactory(pluginManager) {
          * #getter
          * A track's full cost beyond its display height.
          *
-         * The track *label* is not counted, and cannot be: an offset label is an
-         * in-flow box whose height is whatever the theme renders a Paper of icon
-         * buttons at — 31.140625px on the stock theme, and not a number this file
-         * can derive. So these getters are exact while labels are hidden or
-         * overlapping, and short by one label box per labelled track otherwise.
-         * Anything needing the offset to the pixel with labels showing measures
-         * the DOM; `BreakpointSplitViewOverlay` does, and falls back to this
-         * arithmetic only for a track with no mounted div.
+         * The track *label* is not counted here: an offset label is an in-flow
+         * box whose height is whatever the theme renders a Paper of icon buttons
+         * at, so it is measured into `trackLabelBands` per track and added by
+         * `trackLabelBand` rather than derived.
          */
         get trackChromeHeight() {
             return this.trackLeadingChrome + this.trackTrailingChrome;
@@ -780,25 +785,6 @@ export function stateModelFactory(pluginManager) {
                 return HEADER_BAR_HEIGHT + HEADER_OVERVIEW_HEIGHT;
             }
         },
-        /**
-         * #getter
-         * Where the scalebar pins when the view's chrome is sticky: everything
-         * stacked above it, which is the view's own title bar plus this view's
-         * header. Expressed from `headerHeight` rather than re-summing its
-         * constants — the two are the same box, and a second spelling of the sum
-         * is free to drift from the first while both typecheck.
-         */
-        get rubberbandTop() {
-            return self.stickyViewHeaders
-                ? VIEW_HEADER_HEIGHT + this.headerHeight
-                : 0;
-        },
-        /**
-         * #getter
-         */
-        get pinnedTracksTop() {
-            return this.rubberbandTop + this.scalebarHeight;
-        },
         /**
          * #method
          * rendered height of a single track, collapsing to a fixed height when
@@ -812,6 +798,14 @@ export function stateModelFactory(pluginManager) {
                 ? MINIMIZED_TRACK_HEIGHT
                 : track.activeDisplay.height;
         },
+        /**
+         * #method
+         * the measured in-flow label band above a track's rendering container,
+         * 0 until TrackContainer has measured one or when no label is in flow
+         */
+        trackLabelBand(track) {
+            return self.trackLabelBands.get(track.configuration.trackId) ?? 0;
+        },
         /**
          * #getter
          */
@@ -822,7 +816,9 @@ export function stateModelFactory(pluginManager) {
          * #getter
          */
         get trackHeightsWithChrome() {
-            return this.trackHeights + self.tracks.length * this.trackChromeHeight;
+            return (this.trackHeights +
+                self.tracks.length * this.trackChromeHeight +
+                sum(self.tracks.map(t => this.trackLabelBand(t))));
         },
         /**
          * #getter
@@ -831,7 +827,22 @@ export function stateModelFactory(pluginManager) {
             if (self.scalebarOnly) {
                 return this.headerHeight + this.scalebarHeight;
             }
-            return (this.trackHeightsWithChrome + this.headerHeight + this.scalebarHeight);
+            return (this.trackHeightsWithChrome +
+                this.headerHeight +
+                this.scalebarHeight +
+                (self.tracks.length && self.isTopLevelView
+                    ? RESIZE_ALL_HANDLE_HEIGHT
+                    : 0));
+        },
+        /**
+         * #getter
+         * The display height of each track a whole-stack resize moves, by track
+         * instance id: every shown track that is not minimized.
+         */
+        get resizableTrackHeights() {
+            return new Map(self.tracks
+                .filter(t => !t.minimized)
+                .map(t => [t.id, t.activeDisplay.height]));
         },
         /**
          * #method
@@ -840,14 +851,15 @@ export function stateModelFactory(pluginManager) {
          * first, then unpinned), from the same constants TrackContainer lays its
          * Paper out with. Returns `undefined` if the track is not present.
          *
-         * Exact while track labels are hidden or overlapping. With an offset
-         * label the answer is short by one label box per labelled track above
-         * this one — see `trackChromeHeight` for why that box is not derivable
-         * here.
+         * Includes each track's measured label band, this track's own included,
+         * since an in-flow label sits above the rendering container inside the
+         * same Paper. Exact once TrackContainer has measured; before that it is
+         * short by the unmeasured bands.
          */
         getTrackYOffset(trackId) {
             let y = this.headerHeight + this.scalebarHeight + this.trackLeadingChrome;
             for (const t of [...self.pinnedTracks, ...self.unpinnedTracks]) {
+                y += this.trackLabelBand(t);
                 if (t.configuration.trackId === trackId) {
                     return y;
                 }
@@ -879,24 +891,22 @@ export function stateModelFactory(pluginManager) {
             if (this.totalBp === 0 || self.width === 0) {
                 return 1;
             }
-            // Floor at minBpPerPx so tiny displayed regions (totalBp small enough
-            // that the fill-scaled ratio drops below MIN_BP_PER_PX) can't produce
-            // maxBpPerPx < minBpPerPx, which would invert the zoom-slider bounds
-            // and the clamp() range in zoomTo.
-            return Math.max(MIN_BP_PER_PX, this.totalBp / (self.width * SHOW_ALL_REGIONS_FILL));
+            // floored so a tiny region set cannot put maxBpPerPx under
+            // minBpPerPx, which would invert the zoom slider and zoomTo's clamp
+            return Math.max(this.minBpPerPx, this.totalBp / (self.width * SHOW_ALL_REGIONS_FILL));
         },
         /**
          * #getter
-         * The zoom-out limit. This view's own fit, except while a container holds
-         * it on a shared scale coarser than that — a small genome next to a large
-         * one, drawn short so the two compare by length.
+         * The zoom-out limit. Equal to the fit for this view's regions, except
+         * while a container holds it on a coarser shared scale, such as a small
+         * genome next to a large one, drawn short so the two compare by length.
          *
-         * Raising the LIMIT is what makes such a scale survive: written past the
-         * limit instead, it is undone by the first thing that clamps — a wheel
-         * tick, a rubberband, a `setDisplayedRegions` — which is how the dotplot's
-         * locked aspect ratio once turned "zoom out" into a zoom in
-         * (`axisMaxBpPerPx`). Here every route to a zoom clamps against the same
-         * ceiling, so full zoom-out LANDS on the shared scale.
+         * The shared scale raises the limit. A bpPerPx written past the limit
+         * would be undone by the first operation that clamps (a wheel tick, a
+         * rubberband, a `setDisplayedRegions`), as with the dotplot's locked
+         * aspect ratio turning "zoom out" into a zoom in (`axisMaxBpPerPx`).
+         * Every zoom clamps against the same ceiling, so full zoom-out stops at
+         * the shared scale.
          */
         get maxBpPerPx() {
             return Math.max(this.fitBpPerPx, this.sharedFitBpPerPx);
@@ -935,17 +945,17 @@ export function stateModelFactory(pluginManager) {
                 return this.assembliesNotFound;
             }
             // Check init assembly for errors (displayedRegions may be empty during init)
-            if (self.init) {
+            if (self.pendingLaunch) {
                 // `assembly` is required by InitState, but init is a frozen blob and
                 // hand-authored JSON is what fills it, so the type is not a guarantee.
                 // Naming the authoring mistake beats the downstream symptom, which is
                 // the literal string "Assembly undefined not found".
-                if (!self.init.assembly) {
+                if (!this.launchAssemblyName) {
                     return 'LinearGenomeView init needs an "assembly"';
                 }
                 const asm = this.initAssembly;
                 if (!asm) {
-                    return `Assembly ${self.init.assembly} not found`;
+                    return `Assembly ${this.launchAssemblyName} not found`;
                 }
                 if (asm.error) {
                     return asm.error;
@@ -1045,20 +1055,48 @@ export function stateModelFactory(pluginManager) {
         /**
          * #action
          */
-        // A resize needs no arithmetic: the window is what is stored, so a new
-        // width simply divides into it and `bpPerPx` follows. The view keeps the
-        // sequence it was framing rather than letting the right edge eat into it.
-        //
-        // Keeping the scale instead — which is what storing pixels amounted to —
-        // was a block-cache optimization: block boundaries are
-        // `blockNum * ceil(800 * bpPerPx)` and block keys embed start/end, so
-        // holding bpPerPx across a resize kept every block key, and so every
-        // fetched region, identical. Rescaling makes a resize a zoom, and a zoom
-        // is already a solved case: FetchVisibleRegions' 300ms debounce coalesces
-        // the gesture into one refetch, its in-flight guard caps concurrent
-        // batches at one, and rpcDataMap is overwritten in place rather than
-        // cleared, so nothing blanks (ADR-008, ADR-006).
+        setTrackLabelBand(trackId, band) {
+            if (band === 0) {
+                self.trackLabelBands.delete(trackId);
+            }
+            else {
+                self.trackLabelBands.set(trackId, band);
+            }
+        },
+        /**
+         * #action
+         */
+        setScrollPortExcess(px) {
+            self.scrollPortExcess = px;
+        },
+        /**
+         * #action
+         * Grow or shrink every unminimized track by `distance` px in all, each
+         * by its share of the height it has above the display minimum. `from` is
+         * the heights to scale, by track instance id; a drag passes the heights
+         * it started with, so whole-pixel rounding does not compound frame by
+         * frame. Returns how far the stack moved.
+         */
+        resizeTracks(distance, from = self.resizableTrackHeights) {
+            const tracks = self.tracks.filter(t => !t.minimized && from.has(t.id));
+            const start = tracks.map(t => from.get(t.id));
+            const next = scaleBandHeights(start, distance, MIN_DISPLAY_HEIGHT);
+            for (const [i, track] of tracks.entries()) {
+                const display = track.activeDisplay;
+                const delta = next[i] - display.height;
+                if (delta !== 0) {
+                    display.resizeHeight(delta);
+                }
+            }
+            return sum(next) - sum(start);
+        },
+        /**
+         * #action
+         * A resize keeps the window in bp, so `bpPerPx` follows the new width
+         * and the view keeps framing the same sequence (ADR-070).
+         */
         setWidth(newWidth) {
+            const unmeasured = self.bpPerPx <= 0;
             self.volatileWidth = newWidth;
             if (newWidth > 0 && self.windowWidthBp <= 0) {
                 // First measure, and nothing has established a window yet: a migrated
@@ -1069,6 +1107,11 @@ export function stateModelFactory(pluginManager) {
                 self.windowWidthBp = (self.legacyBpPerPx || 1) * newWidth;
                 self.legacyBpPerPx = 0;
             }
+            if (unmeasured && self.bpPerPx > 0) {
+                // 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;
+            }
         },
         /**
          * #action
@@ -1082,12 +1125,6 @@ export function stateModelFactory(pluginManager) {
         setIsScalebarRefNameMenuOpen(isOpen) {
             self.isScalebarRefNameMenuOpen = isOpen;
         },
-        /**
-         * #action
-         */
-        setScalebarRefNameClickPending(pending) {
-            self.scalebarRefNameClickPending = pending;
-        },
         /**
          * #action
          */
@@ -1118,12 +1155,6 @@ export function stateModelFactory(pluginManager) {
         setShowGridlines(b) {
             self.showGridlines = b;
         },
-        /**
-         * #action
-         */
-        setLabelsVisible(arg) {
-            self.labelsVisible = arg;
-        },
         /**
          * #action
          * set temporary vertical guides (e.g., for LD display hover)
@@ -1196,8 +1227,15 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #action
-         */
-        setSearchResults(searchResults, searchQuery, assemblyName) {
+         * Raise the picker over search results that name more than one place.
+         * @param onPick - where a picked result lands; by default it navigates
+         * there and shows the track its index came from
+         */
+        setSearchResults(searchResults, searchQuery, assemblyName, onPick = result => navToOption({
+            option: result,
+            model: self,
+            assemblyName,
+        })) {
             getDialogHost(self).queueDialog(handleClose => [
                 SearchResultsDialog,
                 {
@@ -1206,6 +1244,7 @@ export function stateModelFactory(pluginManager) {
                     searchQuery,
                     handleClose,
                     assemblyName,
+                    onPick,
                 },
             ]);
         },
@@ -1225,70 +1264,109 @@ export function stateModelFactory(pluginManager) {
         .actions(self => ({
         /**
          * #action
+         * Resize every unminimized track so the view is exactly as tall as the
+         * scroll port it sits in. Does nothing until the view has measured one.
          */
-        moveTrackDown(id) {
-            const section = self.trackSection(id);
-            const idx = section.findIndex(t => t.id === id);
-            if (idx !== -1 && idx < section.length - 1) {
-                this.moveTrack(id, section[idx + 1].id);
+        fitTracksToWindow() {
+            if (self.scrollPortExcess) {
+                self.resizeTracks(-self.scrollPortExcess);
             }
         },
         /**
          * #action
+         * showTrack for a track whose display state model may be lazily
+         * loaded: loads it, then shows
          */
-        moveTrackUp(id) {
-            const section = self.trackSection(id);
-            const idx = section.findIndex(t => t.id === id);
-            if (idx > 0) {
-                this.moveTrack(id, section[idx - 1].id);
-            }
+        async launchTrack(trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
+            return launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
         },
+    }))
+        .views(self => ({
         /**
-         * #action
+         * #method
+         * The shown track a move action means: the menu passes a track model's
+         * own `id`, an agent passes the `trackId` it knows the track by, and
+         * both name one shown track. Answers the model id, or the argument
+         * unchanged when nothing shown matches, so the move reports it.
          */
-        moveTrackToTop(id) {
-            const section = self.trackSection(id);
-            if (section.length && section[0].id !== id) {
-                this.moveTrack(id, section[0].id);
-            }
+        trackModelId(idOrTrackId) {
+            return ((self.tracks.find(t => t.id === idOrTrackId) ??
+                self.tracks.find(t => t.configuration.trackId === idOrTrackId))?.id ?? idOrTrackId);
         },
-        /**
-         * #action
-         */
-        moveTrackToBottom(id) {
-            const section = self.trackSection(id);
-            const last = section[section.length - 1];
-            if (last && last.id !== id) {
-                this.moveTrack(id, last.id);
+    }))
+        .actions(self => {
+        function shownIndex(idOrTrackId) {
+            const id = self.trackModelId(idOrTrackId);
+            const index = self.tracks.findIndex(track => track.id === id);
+            if (index === -1) {
+                throw new Error(`No shown track has id or trackId "${idOrTrackId}" — the view's tracks are ${self.tracks.map(t => t.configuration.trackId).join(', ') || 'none'}`);
             }
-        },
+            return index;
+        }
         /**
          * #action
-         */
-        moveTrack(movingId, targetId) {
-            const oldIndex = self.tracks.findIndex(track => track.id === movingId);
-            if (oldIndex === -1) {
-                throw new Error(`Track ID ${movingId} not found`);
-            }
-            const newIndex = self.tracks.findIndex(track => track.id === targetId);
-            if (newIndex === -1) {
-                throw new Error(`Track ID ${targetId} not found`);
-            }
-            // direction-aware placement: filtering out oldIndex shifts the target
-            // left by one when dragging down (oldIndex < newIndex), so splicing at
-            // newIndex lands the track *after* the target; dragging up leaves the
-            // target's index intact, landing *before* it. This matches the side
-            // the dragged track approaches from.
+         * Move one shown track to another's position; each is a track model id
+         * or a trackId.
+         */
+        function moveTrack(moving, target) {
+            const oldIndex = shownIndex(moving);
+            const newIndex = shownIndex(target);
+            // splicing at newIndex after removing oldIndex lands a track dragged
+            // down after its target and one dragged up before it
             const tracks = self.tracks.filter((_, idx) => idx !== oldIndex);
             tracks.splice(newIndex, 0, self.tracks[oldIndex]);
             self.tracks = cast(tracks);
-        },
+        }
+        function moveWithinSection(idOrTrackId, pick) {
+            const moving = self.tracks[shownIndex(idOrTrackId)];
+            const section = self.trackSection(moving.id);
+            const target = pick(section, section.indexOf(moving));
+            if (target && target !== moving) {
+                moveTrack(moving.id, target.id);
+            }
+        }
+        return {
+            moveTrack,
+            /**
+             * #action
+             */
+            moveTrackDown(idOrTrackId) {
+                moveWithinSection(idOrTrackId, (section, i) => section[i + 1]);
+            },
+            /**
+             * #action
+             */
+            moveTrackUp(idOrTrackId) {
+                moveWithinSection(idOrTrackId, (section, i) => section[i - 1]);
+            },
+            /**
+             * #action
+             */
+            moveTrackToTop(idOrTrackId) {
+                moveWithinSection(idOrTrackId, section => section[0]);
+            },
+            /**
+             * #action
+             */
+            moveTrackToBottom(idOrTrackId) {
+                moveWithinSection(idOrTrackId, section => section.at(-1));
+            },
+        };
+    })
+        .actions(self => ({
         /**
          * #action
          */
         toggleTrack(trackId) {
             return toggleTrackGeneric(self, trackId);
         },
+        /**
+         * #action
+         * toggleTrack with launchTrack's loading behavior
+         */
+        async launchToggleTrack(trackId) {
+            return launchToggleTrackGeneric(self, trackId);
+        },
         /**
          * #action
          */
@@ -1373,12 +1451,6 @@ export function stateModelFactory(pluginManager) {
                 self.lastTrackDragY = undefined;
             }
         },
-        /**
-         * #action
-         */
-        setLastTrackDragY(y) {
-            self.lastTrackDragY = y;
-        },
         /**
          * #action
          * called while dragging a track over the track at `targetId`; reorders
@@ -1394,7 +1466,7 @@ export function stateModelFactory(pluginManager) {
                     const movingDown = targetIdx > draggingIdx;
                     if (shouldSwapTracks(self.lastTrackDragY, currentY, movingDown)) {
                         self.lastTrackDragY = currentY;
-                        this.moveTrack(draggingTrackId, targetId);
+                        self.moveTrack(draggingTrackId, targetId);
                     }
                 }
             }
@@ -1402,18 +1474,18 @@ export function stateModelFactory(pluginManager) {
         /**
          * #action
          */
-        setInit(arg) {
-            self.init = arg;
+        setLaunch(launch) {
+            self.launch = launch;
         },
         /**
          * #method
-         * creates an svg export and save using FileSaver
+         * renders the view to SVG markup, which it returns; saves it through
+         * FileSaver unless `save: false`
          */
+        // Promise<string> is stated: renderToSvg is typed against this very
+        // model, so an inferred return makes the type reference itself (TS2456)
         async exportSvg(opts = {}) {
-            const { renderToSvg } = await import('./svgcomponents/SVGLinearGenomeView.js');
-            const html = await renderToSvg(self, opts);
-            const { saveSvgAsImage } = await import('@jbrowse/core/svg/saveSvgAsImage');
-            await saveSvgAsImage(html, opts);
+            return exportViewSvg(self, opts, () => import('./svgcomponents/SVGLinearGenomeView.js'));
         },
     }))
         .actions(self => {
@@ -1499,25 +1571,26 @@ export function stateModelFactory(pluginManager) {
          * #getter
          * an ideogram only reads correctly against an entire chromosome: on a
          * sub-region it is a meaningless slice of bands, and the centromere shows
-         * up as a lone half-triangle
+         * up as a lone half-triangle. The chromosome needs bands of its own too:
+         * a cytoband file often lists only the main chromosomes, not chrM or the
+         * unplaced scaffolds
          */
         get canShowCytobands() {
-            return this.showsWholeChromosome && this.anyCytobandsExist;
+            const region = self.displayedRegions[0];
+            return (this.showsWholeChromosome &&
+                !!region &&
+                getCytobands(getSession(self).assemblyManager.get(region.assemblyName), region.refName).length > 0);
         },
         /**
          * #getter
          * the `showCytobands` setting gated by whether cytobands can be shown at
-         * all (whole chromosome + data present) — i.e. actually on screen
+         * all (whole chromosome with bands of its own) and by the header
+         * overview they draw in being on, which the SVG export follows too
          */
         get effectiveShowCytobands() {
-            return this.canShowCytobands && self.showCytobands;
-        },
-        /**
-         * #getter
-         */
-        get anyCytobandsExist() {
-            const { assemblyManager } = getSession(self);
-            return self.assemblyNames.some(a => assemblyManager.get(a)?.cytobands?.length);
+            return (this.canShowCytobands &&
+                self.showCytobands &&
+                !self.hideHeaderOverview);
         },
         /**
          * #getter
@@ -1544,6 +1617,13 @@ export function stateModelFactory(pluginManager) {
         menuItems() {
             return buildMenuItems(self);
         },
+        /**
+         * #method
+         * the view menu's Highlights submenu; extend this to add a row there
+         */
+        highlightsSubMenuItems() {
+            return buildHighlightsSubMenuItems(self);
+        },
         /**
          * #method
          * what a plugin can start from the selected region — a synteny view, a
@@ -1574,7 +1654,6 @@ export function stateModelFactory(pluginManager) {
         let coverageRightPx = 0;
         let prevBpPerPx;
         let prevWidth;
-        let prevMinimumBlockWidth;
         let prevDisplayedRegions;
         return {
             /**
@@ -1586,16 +1665,13 @@ export function stateModelFactory(pluginManager) {
              * blocks to render their data for the region represented by the block
              */
             get staticBlocks() {
-                const { offsetPx, bpPerPx, width, minimumBlockWidth, displayedRegions, } = self;
+                const { offsetPx, bpPerPx, width, displayedRegions } = self;
                 // Fast path: if only offsetPx changed and viewport is still within
                 // the coverage range of existing blocks, skip the expensive
-                // calculateStaticBlocks call entirely. minimumBlockWidth is read here
-                // (not just in calculateStaticBlocks) so MobX still invalidates this
-                // computed if it changes while the viewport stays within coverage.
+                // calculateStaticBlocks call entirely.
                 if (currentlyCalculatedStaticBlocks !== undefined &&
                     bpPerPx === prevBpPerPx &&
                     width === prevWidth &&
-                    minimumBlockWidth === prevMinimumBlockWidth &&
                     displayedRegions === prevDisplayedRegions &&
                     offsetPx >= coverageLeftPx &&
                     offsetPx + width <= coverageRightPx) {
@@ -1604,16 +1680,13 @@ export function stateModelFactory(pluginManager) {
                 const newBlocks = calculateStaticBlocks(self);
                 // Hand back the previous BlockSet when the recompute produced the same
                 // blocks, so a sideways scroll past the coverage edge doesn't re-render
-                // every track. minimumBlockWidth is part of the guard because block
-                // keys don't encode ContentBlock-vs-ElidedBlock, so a region can flip
-                // type with an unchanged key. Geometry is compared first: on a zoom it
-                // always differs, which skips the key walk entirely — the whole-genome
-                // view has one block per refName, so joining those keys into a string
-                // (as this used to) allocated an array and a string per zoom frame.
+                // every track. Geometry is compared first: on a zoom it always
+                // differs, which skips the key walk entirely — the whole-genome view
+                // has one block per refName, so joining those keys into a string (as
+                // this used to) allocated an array and a string per zoom frame.
                 if (currentlyCalculatedStaticBlocks === undefined ||
                     bpPerPx !== prevBpPerPx ||
                     width !== prevWidth ||
-                    minimumBlockWidth !== prevMinimumBlockWidth ||
                     !sameBlockKeys(currentlyCalculatedStaticBlocks, newBlocks)) {
                     currentlyCalculatedStaticBlocks = newBlocks;
                 }
@@ -1629,7 +1702,6 @@ export function stateModelFactory(pluginManager) {
                 }
                 prevBpPerPx = bpPerPx;
                 prevWidth = width;
-                prevMinimumBlockWidth = minimumBlockWidth;
                 prevDisplayedRegions = displayedRegions;
                 return currentlyCalculatedStaticBlocks;
             },
@@ -1758,7 +1830,7 @@ export function stateModelFactory(pluginManager) {
                 for (const [i, run] of runs.entries()) {
                     const runLeft = run.offsetPx - firstBlockOffset;
                     const runLabels = [];
-                    for (const { base, x } of makeBlockTicks(run, bpPerPx, true, false)) {
+                    for (const { base, x } of makeBlockTicks(run, bpPerPx, false)) {
                         const label = getTickDisplayStr(base + 1, bpPerPx);
                         const w = tickLabelWidth(label);
                         // the bold refName label pinned at the run's left edge takes
@@ -1817,8 +1889,9 @@ export function stateModelFactory(pluginManager) {
              * into that through `scalebarDisplayPrefix`) and whether it is flipped.
              * A ` [rev]` there is a fact about the ROW; the same marker on a
              * chromosome name means that one region, which only happens under mixed
-             * orientation. `captionSpanPx` is the width it takes, which the
-             * coordinate numbers stay out from under. The SVG export deliberately
+             * orientation. `captionSpanPx` is the width it takes: the sticky label
+             * pins to its right edge rather than the viewport's, and the coordinate
+             * numbers stay out from under it. The SVG export deliberately
              * calls `getScalebarRefNameLabels` itself with no prefix rather than
              * reading this, since it draws its own assembly name above the ruler.
              */
@@ -1835,37 +1908,42 @@ export function stateModelFactory(pluginManager) {
              * Every span along the row that is not track data, as plain geometry in
              * the staticBlocks frame — the same frame as gridlineTicks and
              * scalebarLabels, so one `translateX(staticBlocksTranslateX)` places all
-             * three. Three kinds, and a host drawing its own chrome needs all of
-             * them:
+             * three. A host drawing its own chrome needs all three kinds:
              *
              * - `seam`: the 3px bar at a region's right edge. Displayed regions are
-             *   laid out **contiguously** — calculateStaticBlocks emits boundary
-             *   padding only before the first region and after the last — so this
+             *   laid out **contiguously** (calculateStaticBlocks emits boundary
+             *   padding only before the first region and after the last), so this
              *   bar is the only thing separating two of them. Without it a
-             *   two-region view reads as a one-region view scrolled somewhere
-             *   strange. `isRightEndOfDisplayedRegion` is what marks it, and the
-             *   right edge of the blocks currently *loaded* — which is what block
-             *   geometry hands you — is not the same filter.
+             *   two-region view looks like a single region.
+             *   `isRightEndOfDisplayedRegion` marks it; the right edge of the
+             *   currently *loaded* blocks, which block geometry gives you, is a
+             *   different set.
              * - `elided`: a region too narrow to draw at this zoom. Whole-genome on
-             *   a real assembly is mostly these — hg38 has 455 sequences and all
-             *   but the 24 chromosomes land sub-pixel — so a host that skips them
-             *   renders that tail as nothing at all.
+             *   a real assembly is mostly these (hg38 has 455 sequences, and all
+             *   but the 24 chromosomes are under a pixel wide), so a host that
+             *   skips them leaves that part of the row empty.
              * - `boundary`: past the start of the first region or the end of the
-             *   last. Greying it is what makes the last region's seam read as the
-             *   edge of a filled area rather than a rule floating in the track.
+             *   last. Greying it shows the last region's seam as the edge of a
+             *   filled area, where it would otherwise look like a line in the
+             *   middle of the track.
              *
              * Elided blocks get no seam even though they carry the flag: at the
-             * zoom where regions elide, one bar per region is a solid grey wall.
+             * zoom where regions elide, one bar per region would fill the row solid
+             * grey.
              *
-             * PaddingBlocks is the in-tree consumer. The SVG export is deliberately
-             * NOT one: `SVGRegionSeparators` walks dynamicBlocks itself and draws
-             * only the seam, because `elided` and `boundary` are chrome for an
-             * interactive row rather than information a figure carries — striped
-             * grey saying "regions here are too narrow to draw" is noise in a
-             * static image, and at whole-genome zoom it would be most of the row.
-             * The seam is the one that must survive: regions lay out contiguously,
-             * so it is all that separates two of them.
+             * PaddingBlocks is the in-tree consumer. The SVG export does not use
+             * it: `SVGRegionSeparators` walks dynamicBlocks itself and draws only
+             * the seam, because `elided` and `boundary` mark state for an
+             * interactive row. In a static figure the striped grey would cover most
+             * of the row at whole-genome zoom. The export keeps the seam because
+             * regions lay out contiguously and the seam is all that separates two
+             * of them.
              */
+            // Annotated with the shape spelled out rather than as `PaddingSpan`,
+            // because the API doc's type column is where a host drawing its own
+            // chrome reads the field names, and a named type prints as its name.
+            // `spans` and NO_PADDING_SPANS are both `PaddingSpan[]`, so the two
+            // cannot drift without failing here.
             get paddingSpans() {
                 const { blocks, offsetPx: firstBlockOffset } = this.staticBlocks;
                 const spans = [];
@@ -1892,7 +1970,14 @@ export function stateModelFactory(pluginManager) {
                         });
                     }
                 }
-                return spans;
+                // One shared array when there is nothing to draw, so the computed's
+                // value repeats and MobX's `===` stops the chain here. This is the
+                // COMMON case, not an edge one: a view sitting inside one contig has
+                // no region seam, no elision and no boundary, and that is where a
+                // reader spends nearly all of a session. A fresh `[]` each frame
+                // instead re-rendered a PaddingBlocks per track plus one for the
+                // container, every frame of every gesture, to draw nothing.
+                return spans.length > 0 ? spans : NO_PADDING_SPANS;
             },
             /**
              * #getter
@@ -1924,8 +2009,8 @@ export function stateModelFactory(pluginManager) {
              * viewport. False both when the view holds no regions at all and when
              * it holds some but is scrolled entirely off them; either way there is
              * no visible span for the scalebar, ruler and refName labels to
-             * describe, which is what the SVG export's header checks before drawing
-             * one. Distinct from `hasDisplayedRegions`, which only asks whether the
+             * describe. The SVG export checks it before drawing its header.
+             * Distinct from `hasDisplayedRegions`, which only asks whether the
              * view has been given regions, not whether any are on screen.
              */
             get hasVisibleContent() {
@@ -1962,6 +2047,32 @@ export function stateModelFactory(pluginManager) {
                     };
                 });
             },
+            /**
+             * #getter
+             * Right edge (px, viewport-relative) of the on-screen content, clamped
+             * to the track — where a right-pinned overlay such as a wiggle's colour
+             * or score legend belongs, rather than out in the empty gutter the
+             * regions can leave at whole-genome zoom. `@jbrowse/display-kit`'s
+             * `contentRightEdgePx` states the rule; an SVG export applies the same
+             * one against the export's canvas width instead of this track's.
+             *
+             * Published as a SCALAR on purpose. `visibleRegions` rebuilds a fresh
+             * array of fresh objects on every pan and zoom frame, so a component
+             * that derived this number itself re-rendered on every frame of every
+             * gesture — to produce, whenever content fills the track, the unchanged
+             * `trackWidthPx`. Reading the scalar lets MobX's `===` stop the chain at
+             * this computed instead. Measured over 20 zoom frames: the wiggle
+             * family's three body instances fell from 66 renders to 7.
+             */
+            get contentRightEdgePx() {
+                // The `trackWidthPx` rule sends a DISPLAY to `model.canvasWidthPx`
+                // so it cannot pick the wrong one of four view getters. This is the
+                // view, publishing its own geometry, and `canvasWidthPx` is defined
+                // as exactly this host's `trackWidthPx` (MultiRegionDisplayMixin) —
+                // the same source of truth, read from the side that owns it.
+                // eslint-disable-next-line no-restricted-syntax
+                return contentRightEdgePx(this.visibleRegions, self.trackWidthPx);
+            },
             /**
              * #getter
              * visibleRegions expanded by a half-screen buffer on each side,
@@ -2001,23 +2112,22 @@ export function stateModelFactory(pluginManager) {
             },
             /**
              * #getter
-             * **What a debounced consumer clips to**: the coarse blocks once the
-             * view has settled at least once, the live ones before that.
+             * **The blocks a debounced consumer clips to**: the coarse blocks once
+             * the view has settled at least once, the live ones before that.
              *
-             * The coarse blocks exist so a per-bp scan does not recompute on every
-             * animation frame during a pan or zoom — wiggle's autoscale domain, the
-             * alignments coverage scale and MAF's coverage band are the three — and
-             * while they are stale
-             * the answer is merely a frame or two old, which is what the debounce
-             * means. **Empty is different in kind.** A scan over no blocks yields no
-             * entries, and no entries is not a stale domain, it is the fallback one:
-             * `[0,1]`, which draws a line plot blank and a density plot saturated.
-             * That window is the 500ms between a view initializing and the coarse
-             * autorun's first run, and data can now land inside it — the per-region
-             * fetch used to be trailing-edge at 600ms, so it never did.
+             * The coarse blocks stop a per-bp scan from recomputing on every
+             * animation frame during a pan or zoom. Wiggle's autoscale domain, the
+             * alignments coverage scale and MAF's coverage band use them. While the
+             * coarse blocks are stale the result is a frame or two old, as the
+             * debounce intends. **Empty coarse blocks are a different case.** A scan
+             * over no blocks yields no entries, and the consumer falls back to the
+             * domain `[0,1]`, which draws a line plot blank and a density plot
+             * saturated. The coarse blocks are empty for the 500ms between a view
+             * initializing and the coarse autorun's first run, and data can load
+             * within that window.
              *
-             * One recompute at that transition, against N per frame, which is the
-             * trade the guard was making anyway.
+             * Falling back to the live blocks costs one extra recompute at that
+             * transition, compared with N per frame without the debounce.
              */
             get settledDynamicBlocks() {
                 return self.coarseDynamicBlocks.length
@@ -2041,7 +2151,7 @@ export function stateModelFactory(pluginManager) {
              * #getter
              */
             get effectiveTotalBp() {
-                return self.bpPerPx * self.width;
+                return self.windowWidthBp;
             },
             /**
              * #getter
@@ -2128,7 +2238,7 @@ export function stateModelFactory(pluginManager) {
          * as. Prefer `setWindow`: pixels mean nothing without the width they were
          * measured at, so a round trip through here is only exact while the width
          * holds still. Kept for callers that genuinely have pixels — a wheel
-         * gesture, a rubberband — and for reading old snapshots.
+         * gesture, a rubberband.
          */
         setNewView(bpPerPx, offsetPx) {
             self.zoomTo(bpPerPx);
@@ -2280,14 +2390,6 @@ export function stateModelFactory(pluginManager) {
         clearView() {
             self.setDisplayedRegions([]);
             self.tracks.clear();
-            // it is necessary to run these after setting displayed regions empty
-            // or else model.offsetPx gets set to Infinity and breaks
-            // @jbrowse/mobx-state-tree snapshot
-            self.scrollTo(0);
-            self.zoomTo(10);
-            // after them, not through setDisplayedRegions, whose own settle ran at
-            // the intermediate viewport these two lines exist to leave
-            self.settleCoarseBlocks();
         },
         /**
          * #action
@@ -2386,13 +2488,15 @@ export function stateModelFactory(pluginManager) {
          * navigating to the locstring
          * @param grow - optional multiplier to expand the region by (e.g., 0.2
          * adds 20% padding on each side)
+         * @param opts - `showHitTrack: false` keeps a text-search hit from also
+         * showing the track its index was built from
          * @returns whether the view moved. A multi-hit search raises the picker
          * instead of navigating, and both resolve — see `handleSelectedRegion`.
          */
         // annotated, not inferred: the same type cycle `showTrack` names. Left to
         // infer, the `boolean` reaches this model's type through `self` and 180
         // unrelated files lose their parameter types to it.
-        async navToLocString(input, optAssemblyName, grow) {
+        async navToLocString(input, optAssemblyName, grow, opts) {
             const { assemblyNames } = self;
             const session = getSession(self);
             const { assemblyManager } = session;
@@ -2407,6 +2511,7 @@ export function stateModelFactory(pluginManager) {
                 input,
                 assemblyName,
                 grow,
+                showHitTrack: opts?.showHitTrack,
                 model: self,
             });
         },
@@ -2429,7 +2534,18 @@ export function stateModelFactory(pluginManager) {
                 return;
             }
             const { assemblyManager } = getSession(self);
-            await when(() => self.volatileWidth !== undefined);
+            // A one-sided `volatileWidth !== undefined` parks forever on a view
+            // that never mounts, and `navToMultiLevelBreak` awaits a Promise.all of
+            // these one line before the `whenViewSettled` that was written to cure
+            // exactly that hang. `isAlive` is the second terminal state and the
+            // guard below is what it means. NOT `self.error`, which is a transient
+            // truth (`assembliesNotFound` while a session assembly is registering)
+            // independent of mounting, so it would return without navigating where
+            // waiting would have navigated correctly.
+            await when(() => self.volatileWidth !== undefined || !isAlive(self));
+            if (!isAlive(self) || self.volatileWidth === undefined) {
+                return;
+            }
             // Generate locations from the parsed regions
             const locations = await generateLocations({
                 regions,
@@ -2492,6 +2608,31 @@ export function stateModelFactory(pluginManager) {
         async navToLocation(parsedLocString, assemblyName, grow) {
             return self.navToLocations([parsedLocString], assemblyName, grow);
         },
+        /**
+         * #action
+         * adds the region in view to the session's highlights
+         */
+        highlightCurrentRegion() {
+            const [region] = self.visibleWholeBaseRegions;
+            if (region) {
+                getSession(self).addHighlight(region);
+            }
+        },
+        /**
+         * #action
+         * navigates to the most recently added highlight on this view's
+         * assemblies, zoomed out a little for context
+         */
+        async navigateNewestHighlight() {
+            const newest = self.highlights.at(-1);
+            if (newest) {
+                const { assemblyName, ...region } = newest;
+                await self.navToLocString(assembleLocString(region), assemblyName, 0.2);
+            }
+            else {
+                getSession(self).notify('There are no highlights to navigate to.', 'info');
+            }
+        },
     }))
         .views(self => ({
         /**
@@ -2508,14 +2649,28 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #method
-         * Map a highlight or bookmark region to its pixel position+width inside
+         * Map a highlight region to its pixel position+width inside
          * the tracks container. Falls back to the raw refName if the region's
          * assemblyName is missing or unknown so highlights authored without an
          * assembly still render in single-assembly views.
          */
         getHighlightCoords(region) {
-            const refName = resolveCanonicalRefName(self, region);
-            return getLayoutHighlightCoords(self, { ...region, refName });
+            return getLayoutHighlightCoords(self, canonicalHighlight(self, region));
+        },
+        /**
+         * #method
+         * y ranges, from the top of the highlight bands, of tracks whose display
+         * sets `drawsGenomicCoordinates` to false; the bands skip them
+         */
+        nonGenomicTrackBands() {
+            const y0 = self.headerHeight + self.scalebarHeight;
+            return [...self.pinnedTracks, ...self.unpinnedTracks].flatMap(track => {
+                const display = track.activeDisplay;
+                const top = self.getTrackYOffset(track.configuration.trackId);
+                return display.drawsGenomicCoordinates === false && top !== undefined
+                    ? [{ top: top - y0, height: self.trackHeight(track) }]
+                    : [];
+            });
         },
         /**
          * #method
@@ -2523,11 +2678,7 @@ export function stateModelFactory(pluginManager) {
          * shifted by the cytoband offset
          */
         getOverviewHighlightCoords(region) {
-            const refName = resolveCanonicalRefName(self, region);
-            const coords = getLayoutHighlightCoords(self.overviewLayout, {
-                ...region,
-                refName,
-            });
+            const coords = getLayoutHighlightCoords(self.overviewLayout, canonicalHighlight(self, region));
             return coords
                 ? { ...coords, left: coords.left + self.cytobandOffset }
                 : undefined;
@@ -2566,6 +2717,17 @@ export function stateModelFactory(pluginManager) {
                 ? this.pxToBp(self.width / 2)
                 : undefined;
         },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * a region edit from the ruler's menu as one action, which a synteny
+         * stack's follow reads as the reader's gesture on this row; see
+         * `setDisplayedRegionsKeepingCenter`
+         */
+        editDisplayedRegions(edit) {
+            setDisplayedRegionsKeepingCenter(self, edit);
+        },
     }))
         .views(self => ({
         /**
@@ -2594,21 +2756,21 @@ export function stateModelFactory(pluginManager) {
         let heading;
         /**
          * #action
-         * Travel to a window rather than appear in it: the Van Wijk arc from
-         * where the view is to where it is going, played over its own duration.
+         * Animate to a window along the Van Wijk arc from the current window to
+         * the target, over a duration derived from the arc.
          *
-         * WHAT LANDS IS WHAT `setWindow` WOULD HAVE LANDED — only the path in
-         * between is new. That is what lets a caller offer an Undo, a snackbar or
-         * a follow anchor around this exactly as it did around the instant move.
+         * The final state is the one `setWindow` would produce; only the path in
+         * between differs. A caller can therefore offer an Undo, a snackbar or a
+         * follow anchor around this exactly as around the instant move.
          *
-         * It YIELDS to anything else that moves the view, by reading back what it
-         * wrote and stopping the moment the view holds something else: a wheel
-         * zoom, a drag, a locstring nav, or the Undo on the very snackbar the
-         * flight was launched with. Compared against what was WRITTEN rather than
-         * what was asked for, because the write clamps — an arc that pulls back
-         * past `maxBpPerPx` reads its own clamped result back, and treating that
-         * as interference would end the flight one frame in. `springAnimate`
-         * defends the same value the same way.
+         * The flight stops when anything else moves the view: it reads back what
+         * it wrote and stops as soon as the view holds something else, such as a
+         * wheel zoom, a drag, a locstring nav, or the Undo on the snackbar the
+         * flight was launched with. It compares against the written value, not
+         * the requested one, because the write clamps: an arc that pulls back
+         * past `maxBpPerPx` reads back its clamped result, and treating that as
+         * interference would end the flight after one frame. `springAnimate`
+         * handles the same value the same way.
          */
         function flyTo(centerBp, windowWidthBp) {
             cancelLastFlight();
@@ -2675,7 +2837,7 @@ export function stateModelFactory(pluginManager) {
              * `centerAt`'s animated twin: the same destination, reached along the
              * arc instead of jumped to, at the zoom the view is already on.
              */
-            flyToCenter(coord, refName) {
+            flyToCenter(coord, refName, displayedRegionIndex) {
                 // `bpToLinearBp` rather than `bpToPx`, which rounds to a whole pixel
                 // at the current zoom: mid-flight that zoom is a point on somebody
                 // else's arc, and a destination quantized against it moves with it.
@@ -2683,11 +2845,22 @@ export function stateModelFactory(pluginManager) {
                     refName,
                     coord,
                     displayedRegions: self.displayedRegions,
+                    displayedRegionIndex,
                 });
                 if (centerBp !== undefined) {
                     flyTo(centerBp, heading ? heading.windowWidthBp : self.windowWidthBp);
                 }
             },
+            /**
+             * #action
+             * A flight to a linear bp centre at the zoom the view is on, or is
+             * already flying to, widened where that is narrower than `fitWidthBp`.
+             * The current width mid-flight is a point on the arc, so a second
+             * flight read from it would land pulled back.
+             */
+            flyToFit(centerBp, fitWidthBp) {
+                flyTo(centerBp, Math.max(heading ? heading.windowWidthBp : self.windowWidthBp, fitWidthBp));
+            },
         };
     })
         .actions(self => ({
@@ -2697,22 +2870,21 @@ export function stateModelFactory(pluginManager) {
         afterAttach() {
             doAfterAttach(self);
         },
-    }))
+    }));
+    return withLaunchInput(model, lgvLaunchKeys, {
+        registry: pluginManager,
+        materialized: snap => !!snap.displayedRegions?.length,
+    })
         .preProcessSnapshot((snap) => {
         if (!snap) {
             return snap;
         }
-        // The cytobands setting has been `showCytobandsSetting` and (briefly)
-        // `cytobandsVisible`; both now persist as the bare `showCytobands` prop
+        // v4's `showCytobandsSetting` persists as the bare `showCytobands` prop
         // (the capability-gated getter is `effectiveShowCytobands`).
-        const { highlight, showCytobandsSetting, cytobandsVisible, offsetPx, bpPerPx, ...rest } = snap;
-        const legacyShowCytobands = showCytobandsSetting ?? cytobandsVisible;
+        const { showCytobandsSetting, offsetPx, bpPerPx, ...rest } = snap;
         return {
-            highlight: Array.isArray(highlight) || highlight === undefined
-                ? highlight
-                : [highlight],
-            ...(legacyShowCytobands !== undefined
-                ? { showCytobands: legacyShowCytobands }
+            ...(showCytobandsSetting !== undefined
+                ? { showCytobands: showCytobandsSetting }
                 : {}),
             // The viewport used to persist as pixels. Half of that converts
             // exactly and needs no width — the left edge in bp is offsetPx *
@@ -2739,23 +2911,16 @@ export function stateModelFactory(pluginManager) {
         };
     })
         .postProcessSnapshot(snap => {
-        // init is transient launch state, never persisted. showCenterLine is
-        // purely a localStorage-backed preference (see setupLocalStorageAutorun
-        // in afterAttach.ts) and is never persisted into session snapshots. The
-        // remaining fields are also localStorage-backed, but still persist when
-        // non-default: their strip baseline is the universal default (hardcoded
-        // here), not the localStorage-derived creation default, so a
-        // localStorage-set value stays portable across browsers.
-        const { init, showCenterLine, showCytobands, trackLabels, colorByCDS, showAminoAcids, showTrackOutlines, ...rest } = snap;
+        // showCenterLine is purely a localStorage-backed preference (see
+        // setupLocalStorageAutorun in afterAttach.ts) and is never persisted
+        // into session snapshots. The remaining fields are also
+        // localStorage-backed, but still persist when non-default: their strip
+        // baseline is the universal default (hardcoded here), not the
+        // localStorage-derived creation default, so a localStorage-set value
+        // stays portable across browsers.
+        const { showCenterLine, showCytobands, trackLabels, colorByCDS, showAminoAcids, showTrackOutlines, ...rest } = snap;
         return {
             ...rest,
-            // keep init until displayedRegions exist, so a snapshot taken before the
-            // launch autorun navigates (e.g. autosave firing mid-load) can still
-            // rebuild the view instead of dropping to the import form.
-            // displayedRegions is stripDefault, so it's absent (not []) when empty —
-            // the optional chain is runtime-necessary despite the non-nullish type.
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            ...(init && !snap.displayedRegions?.length ? { init } : {}),
             ...(!showCytobands ? { showCytobands } : {}),
             ...(trackLabels ? { trackLabels } : {}),
             ...(colorByCDS ? { colorByCDS } : {}),