@jbrowse/plugin-linear-genome-view 5.0.0-beta.8 → 5.0.0-beta.9

package/esm/LinearGenomeView/model.js

@@ -1,8 +1,9 @@
 import { lazy } from 'react';
 import { getConf } from '@jbrowse/core/configuration';
-import { BaseViewModel, HighlightsMixin, } from '@jbrowse/core/pluggableElementTypes/models';
+import { BaseViewModel } from '@jbrowse/core/pluggableElementTypes/models';
+import { exportViewSvg } from '@jbrowse/core/svg/exportViewSvg';
 import { VIEW_HEADER_HEIGHT } from '@jbrowse/core/ui';
-import { assembleLocString, clamp, getBpDisplayStr, getDialogHost, getSession, getTickDisplayStr, isSessionModelWithWidgets, localStorageGetBoolean, localStorageGetItem, springAnimate, sum, } from '@jbrowse/core/util';
+import { assembleLocString, clamp, getBpDisplayStr, getDialogHost, getSession, getTickDisplayStr, isSessionModelWithWidgets, localStorageGetBoolean, localStorageGetItem, scheduleDetachedDestroy, springAnimate, sum, } from '@jbrowse/core/util';
 import { bpToLinearBp, bpToPx, computeMoveToLayout, createOverviewLayout, getLayoutHighlightCoords, getOverviewRegionPxSpan, moveTo, pxToBp, } from '@jbrowse/core/util/Base1DUtils';
 import { wholeBaseRegions } from '@jbrowse/core/util/blockTypes';
 import calculateDynamicBlocks from '@jbrowse/core/util/calculateDynamicBlocks';
@@ -10,15 +11,17 @@ import calculateStaticBlocks from '@jbrowse/core/util/calculateStaticBlocks';
 import { tickLabelsWorthDrawing } from '@jbrowse/core/util/tickLabels';
 import { hideTrackGeneric, launchToggleTrackGeneric, launchTrackGeneric, showTrackGeneric, toggleTrackGeneric, } from '@jbrowse/core/util/tracks';
 import { ElementId } from '@jbrowse/core/util/types/mst';
-import { assemblyErrorMessage, 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 { contentRightEdgePx } from '@jbrowse/display-kit/regionHost';
-import { cast, getParent, hasParent, isAlive, types, } from '@jbrowse/mobx-state-tree';
+import { cast, detach, getParent, hasParent, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import { observable, when } from 'mobx';
 import { handleSelectedRegion } from '../searchUtils.js';
 import { doAfterAttach } from './afterAttach.js';
+import { closeUpHost, closeUpType } from './closeUps.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 { CLOSE_UP_CONNECTOR_HEIGHT, HEADER_BAR_HEIGHT, HEADER_OVERVIEW_HEIGHT, MIN_BP_PER_PX, MIN_CLOSE_UP_CONNECTOR_HEIGHT, MINIMIZED_TRACK_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 { lgvLaunchKeys } from './launchKeys.js';
@@ -167,9 +170,8 @@ function isTrackSelectorVisible(self) {
  * ```
  * `assembly`, `loc`, `tracks`, `tracklist`, `nav` and `highlight` need
  * on-attach resolution and are captured into the `launch` property below;
- * `colorByCDS`, `showAminoAcids`, `showCenterLine`, `trackLabels` and
- * `showHighlightChips` are plain view props MST restores natively. Both are
- * written the same way.
+ * `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
@@ -181,7 +183,7 @@ function isTrackSelectorVisible(self) {
  */
 export function stateModelFactory(pluginManager) {
     const model = types
-        .compose('LinearGenomeView', BaseViewModel, HighlightsMixin(), types.model({
+        .compose('LinearGenomeView', BaseViewModel, types.model({
         /**
          * #property
          */
@@ -256,6 +258,23 @@ export function stateModelFactory(pluginManager) {
          * keep the header, drop the whole-chromosome overview strip below it
          */
         hideHeaderOverview: types.stripDefault(types.boolean, false),
+        /**
+         * #property
+         * Closer views of the same locus stacked under the tracks, widest
+         * first, so the page zooms in as it reads down. Each is a
+         * LinearGenomeView with tracks of its own whose regions, width and
+         * centre this view drives; its window width is the one thing it keeps.
+         * See `closeUps.ts`.
+         */
+        closeUps: types.stripDefault(types.array(closeUpType(pluginManager)), []),
+        /**
+         * #property
+         * Height of the bands the trapezoids between this view's close-ups
+         * are drawn in, dragged by any one of them. One number for the stack:
+         * the bands are a ladder the eye reads down, and a rung of its own
+         * height reads as a difference in the data rather than in the drawing.
+         */
+        closeUpConnectorHeight: types.stripDefault(types.number, CLOSE_UP_CONNECTOR_HEIGHT),
         /**
          * #property
          * suppress the "No tracks active" placeholder, for an embed that opens
@@ -287,7 +306,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') ?? ''),
@@ -298,7 +317,7 @@ export function stateModelFactory(pluginManager) {
         showGridlines: types.stripDefault(types.boolean, true),
         /**
          * #property
-         * controls whether highlight/bookmark chip labels are shown inline
+         * controls whether highlight chip labels are shown inline
          */
         labelsVisible: types.stripDefault(types.boolean, true),
         /**
@@ -505,6 +524,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
@@ -539,8 +566,38 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #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's close-ups, which are views in
+         * their own right.
+         */
+        get ownViews() {
+            return [...self.closeUps];
+        },
+        /**
+         * #getter
+         * The close-ups as what the host reads off them. The array element
+         * is a late type back onto this view, so this is where it gets a shape.
+         */
+        get closeUpViews() {
+            return self.closeUps;
+        },
+        /**
+         * #getter
+         * Whether this view is itself a close-up of another
+         */
+        get isCloseUp() {
+            return !!closeUpHost(self);
+        },
+        /**
+         * #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
@@ -587,10 +644,23 @@ export function stateModelFactory(pluginManager) {
          * and error checks resolve it directly through here.
          */
         get initAssembly() {
-            return self.pendingLaunch
-                ? getSession(self).assemblyManager.get(self.pendingLaunch.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
          */
@@ -624,35 +694,11 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #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)
+         * What the loading screen says while `showLoading`, read off the
+         * assembly whose load is the wait; undefined otherwise.
          */
-        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}.
-         */
-        get loadingSource() {
-            return this.showLoading ? this.loadingAssembly?.statusSource : undefined;
+        get loading() {
+            return viewLoading(this.showLoading, () => this.loadingAssembly);
         },
         /**
          * #getter
@@ -731,12 +777,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,
             });
         },
         /**
@@ -791,15 +832,15 @@ export function stateModelFactory(pluginManager) {
         /**
          * #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.
+         * stacked above it, which is the view's own title bar, where the session
+         * draws one, 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;
+            const titleBar = getSession(self).viewTitleBars === false ? 0 : VIEW_HEADER_HEIGHT;
+            return self.stickyViewHeaders ? titleBar + this.headerHeight : 0;
         },
         /**
          * #getter
@@ -906,16 +947,16 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #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);
@@ -959,12 +1000,12 @@ export function stateModelFactory(pluginManager) {
                 // 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.pendingLaunch.assembly) {
+                if (!this.launchAssemblyName) {
                     return 'LinearGenomeView init needs an "assembly"';
                 }
                 const asm = this.initAssembly;
                 if (!asm) {
-                    return `Assembly ${self.pendingLaunch.assembly} not found`;
+                    return `Assembly ${this.launchAssemblyName} not found`;
                 }
                 if (asm.error) {
                     return asm.error;
@@ -1133,6 +1174,50 @@ export function stateModelFactory(pluginManager) {
         setHideHeaderOverview(b) {
             self.hideHeaderOverview = b;
         },
+        /**
+         * #action
+         * Add a close-up showing `trackIds`, spanning `windowWidthBp` bases or a
+         * tenth of the closest close-up there is. The stack stays widest first,
+         * so a span between two existing close-ups lands between them, and one
+         * wider than this view is pulled back in to it by the sync.
+         *
+         * Answers the close-up, which is a LinearGenomeView: its own actions
+         * navigate it, name its tracks and take it away again.
+         */
+        addCloseUp({ windowWidthBp, trackIds = [], } = {}) {
+            const closest = self.closeUpViews.at(-1);
+            const width = windowWidthBp ?? (closest?.windowWidthBp ?? self.windowWidthBp) / 10;
+            const centerBp = self.windowStartBp + self.windowWidthBp / 2;
+            const at = self.closeUpViews.filter(closeUp => closeUp.windowWidthBp > width).length;
+            self.closeUps.splice(at, 0, {
+                type: 'LinearGenomeView',
+                hideHeader: true,
+                displayedRegions: self.displayedRegions,
+                windowWidthBp: width,
+                windowStartBp: centerBp - width / 2,
+            });
+            const closeUp = self.closeUpViews[at];
+            for (const trackId of trackIds) {
+                closeUp.showTrack(trackId);
+            }
+            return closeUp;
+        },
+        /**
+         * #action
+         */
+        removeCloseUp(closeUp) {
+            detach(closeUp);
+            scheduleDetachedDestroy(closeUp);
+        },
+        /**
+         * #action
+         * Set the height of every band between this view's close-ups.
+         * Floored at the drag surface's own height rather than at 0: the band IS
+         * the handle, so a band dragged shut could never be dragged open again.
+         */
+        setCloseUpConnectorHeight(height) {
+            self.closeUpConnectorHeight = Math.max(MIN_CLOSE_UP_CONNECTOR_HEIGHT, Math.round(height));
+        },
         /**
          * #action
          */
@@ -1256,6 +1341,34 @@ export function stateModelFactory(pluginManager) {
         },
     }))
         .actions(self => ({
+        /**
+         * #action
+         * Open a close-up over a rubberband selection, showing this view's
+         * tracks. The view recentres on the span first, because every close-up
+         * shares its host's centre — a close-up is a closer look at the middle of
+         * this view, and a selection off to one side would otherwise open
+         * somewhere else.
+         *
+         * The span is `computeMoveToLayout`'s, the pure half of the `moveTo` the
+         * same selection's "Zoom to region" runs, so the close-up covers exactly
+         * what zooming would have navigated to.
+         */
+        addCloseUpForSpan(start, end, { trackIds } = {}) {
+            if (!start || !end) {
+                return undefined;
+            }
+            const { bpPerPx, offsetPx } = computeMoveToLayout(self, start, end);
+            const windowWidthBp = bpPerPx * self.width;
+            const centerBp = offsetPx * bpPerPx + windowWidthBp / 2;
+            self.scrollToBp(centerBp - self.windowWidthBp / 2);
+            return self.addCloseUp({
+                windowWidthBp,
+                // the view's own tracks unless the caller named a list, so a close-up
+                // is a closer look at what is on screen by default and an empty row
+                // when someone asked for one
+                trackIds: trackIds ?? self.tracks.map(track => track.configuration.trackId),
+            });
+        },
         /**
          * #action
          * showTrack for a track whose display state model may be lazily
@@ -1264,12 +1377,26 @@ export function stateModelFactory(pluginManager) {
         async launchTrack(trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
             return launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
         },
+    }))
+        .views(self => ({
+        /**
+         * #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.
+         */
+        trackModelId(idOrTrackId) {
+            return ((self.tracks.find(t => t.id === idOrTrackId) ??
+                self.tracks.find(t => t.configuration.trackId === idOrTrackId))?.id ?? idOrTrackId);
+        },
     }))
         .actions(self => ({
         /**
          * #action
          */
-        moveTrackDown(id) {
+        moveTrackDown(idOrTrackId) {
+            const id = self.trackModelId(idOrTrackId);
             const section = self.trackSection(id);
             const idx = section.findIndex(t => t.id === id);
             if (idx !== -1 && idx < section.length - 1) {
@@ -1279,7 +1406,8 @@ export function stateModelFactory(pluginManager) {
         /**
          * #action
          */
-        moveTrackUp(id) {
+        moveTrackUp(idOrTrackId) {
+            const id = self.trackModelId(idOrTrackId);
             const section = self.trackSection(id);
             const idx = section.findIndex(t => t.id === id);
             if (idx > 0) {
@@ -1289,7 +1417,8 @@ export function stateModelFactory(pluginManager) {
         /**
          * #action
          */
-        moveTrackToTop(id) {
+        moveTrackToTop(idOrTrackId) {
+            const id = self.trackModelId(idOrTrackId);
             const section = self.trackSection(id);
             if (section.length && section[0].id !== id) {
                 this.moveTrack(id, section[0].id);
@@ -1298,7 +1427,8 @@ export function stateModelFactory(pluginManager) {
         /**
          * #action
          */
-        moveTrackToBottom(id) {
+        moveTrackToBottom(idOrTrackId) {
+            const id = self.trackModelId(idOrTrackId);
             const section = self.trackSection(id);
             const last = section[section.length - 1];
             if (last && last.id !== id) {
@@ -1307,15 +1437,19 @@ export function stateModelFactory(pluginManager) {
         },
         /**
          * #action
+         * Move one shown track to another's position; each is a track model id
+         * or a trackId.
          */
-        moveTrack(movingId, targetId) {
+        moveTrack(moving, target) {
+            const movingId = self.trackModelId(moving);
+            const targetId = self.trackModelId(target);
             const oldIndex = self.tracks.findIndex(track => track.id === movingId);
             if (oldIndex === -1) {
-                throw new Error(`Track ID ${movingId} not found`);
+                throw new Error(`No shown track has id or trackId "${moving}" — the view's tracks are ${self.tracks.map(t => t.configuration.trackId).join(', ') || 'none'}`);
             }
             const newIndex = self.tracks.findIndex(track => track.id === targetId);
             if (newIndex === -1) {
-                throw new Error(`Track ID ${targetId} not found`);
+                throw new Error(`No shown track has id or trackId "${target}" — the view's tracks are ${self.tracks.map(t => t.configuration.trackId).join(', ') || 'none'}`);
             }
             // direction-aware placement: filtering out oldIndex shifts the target
             // left by one when dragging down (oldIndex < newIndex), so splicing at
@@ -1460,17 +1594,10 @@ export function stateModelFactory(pluginManager) {
          * renders the view to SVG markup, which it returns; saves it through
          * FileSaver unless `save: false`
          */
-        // Promise<string> is stated, against the house preference for inferred
-        // return types: renderToSvg is typed against this very model, so an
-        // inferred return makes the model type reference itself (TS2456).
+        // 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);
-            if (opts.save !== false) {
-                const { saveSvgAsImage } = await import('@jbrowse/core/svg/saveSvgAsImage');
-                await saveSvgAsImage(html, opts);
-            }
-            return html;
+            return exportViewSvg(self, opts, () => import('./svgcomponents/SVGLinearGenomeView.js'));
         },
     }))
         .actions(self => {
@@ -1874,8 +2001,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.
              */
@@ -1892,36 +2020,36 @@ 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
@@ -1993,8 +2121,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() {
@@ -2096,23 +2224,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
@@ -2601,6 +2728,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 => ({
         /**
@@ -2617,7 +2769,7 @@ 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.
@@ -2703,21 +2855,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();
@@ -2798,6 +2950,16 @@ export function stateModelFactory(pluginManager) {
                     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 => ({
@@ -2819,12 +2981,9 @@ export function stateModelFactory(pluginManager) {
         // The cytobands setting has been `showCytobandsSetting` and (briefly)
         // `cytobandsVisible`; both now persist as the bare `showCytobands` prop
         // (the capability-gated getter is `effectiveShowCytobands`).
-        const { highlight, showCytobandsSetting, cytobandsVisible, offsetPx, bpPerPx, ...rest } = snap;
+        const { showCytobandsSetting, cytobandsVisible, offsetPx, bpPerPx, ...rest } = snap;
         const legacyShowCytobands = showCytobandsSetting ?? cytobandsVisible;
         return {
-            highlight: Array.isArray(highlight) || highlight === undefined
-                ? highlight
-                : [highlight],
             ...(legacyShowCytobands !== undefined
                 ? { showCytobands: legacyShowCytobands }
                 : {}),