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

package/esm/LinearGenomeView/model.js

@@ -8,22 +8,29 @@ 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 { assemblyErrorMessage, computeViewStatus, } 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 { when } from 'mobx';
+import { observable, when } from 'mobx';
 import { handleSelectedRegion } 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 { planFlight } from './flyTo.js';
 import { setupKeyboardHandler } from './keyboardHandler.js';
+import { lgvLaunchKeys } from './launchKeys.js';
 import { 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';
 // 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).
@@ -141,30 +148,28 @@ 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`, `trackLabels` and
+ * `showHighlightChips` 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,7 +180,7 @@ function isTrackSelectorVisible(self) {
  * ```
  */
 export function stateModelFactory(pluginManager) {
-    return types
+    const model = types
         .compose('LinearGenomeView', BaseViewModel, HighlightsMixin(), types.model({
         /**
          * #property
@@ -321,27 +326,29 @@ 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.
+             */
+            trackLabelBands: observable.map(),
             /**
              * #volatile
              */
@@ -362,10 +369,6 @@ export function stateModelFactory(pluginManager) {
              * #volatile
              */
             volatileError,
-            /**
-             * #volatile
-             */
-            trackRefs,
             /**
              * #volatile
              */
@@ -377,14 +380,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
              */
@@ -413,6 +412,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.
@@ -522,6 +529,14 @@ export function stateModelFactory(pluginManager) {
         },
     }))
         .views(self => ({
+        /**
+         * #getter
+         * The census entry for this view: the tracks it holds itself. Declared
+         * rather than derived — see `BaseViewModel.ownTracks`.
+         */
+        get ownTracks() {
+            return [...self.tracks];
+        },
         /**
          * #getter
          * Assembly-name prefix for the scalebar refName labels, or undefined for
@@ -555,10 +570,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,8 +587,8 @@ export function stateModelFactory(pluginManager) {
          * and error checks resolve it directly through here.
          */
         get initAssembly() {
-            return self.init
-                ? getSession(self).assemblyManager.get(self.init.assembly)
+            return self.pendingLaunch
+                ? getSession(self).assemblyManager.get(self.pendingLaunch.assembly)
                 : undefined;
         },
         /**
@@ -587,7 +599,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,7 +618,7 @@ 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);
         },
@@ -646,7 +658,7 @@ export function stateModelFactory(pluginManager) {
          * #getter
          */
         get hasSomethingToShow() {
-            return this.hasDisplayedRegions || !!self.init;
+            return this.hasDisplayedRegions || !!self.pendingLaunch;
         },
         /**
          * #getter
@@ -656,7 +668,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 +678,7 @@ export function stateModelFactory(pluginManager) {
          * theirs.
          */
         get awaitingInitNavigation() {
-            return !!self.init && !this.hasDisplayedRegions;
+            return !!self.pendingLaunch && !this.hasDisplayedRegions;
         },
         /**
          * #getter
@@ -754,14 +766,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;
@@ -812,6 +820,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 +838,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
@@ -840,14 +858,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;
                 }
@@ -935,17 +954,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 (!self.pendingLaunch.assembly) {
                     return 'LinearGenomeView init needs an "assembly"';
                 }
                 const asm = this.initAssembly;
                 if (!asm) {
-                    return `Assembly ${self.init.assembly} not found`;
+                    return `Assembly ${self.pendingLaunch.assembly} not found`;
                 }
                 if (asm.error) {
                     return asm.error;
@@ -1058,7 +1077,16 @@ export function stateModelFactory(pluginManager) {
         // 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);
+            }
+        },
         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 +1097,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
@@ -1221,6 +1254,16 @@ export function stateModelFactory(pluginManager) {
         hideTrack(trackId) {
             return hideTrackGeneric(self, trackId);
         },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * showTrack for a track whose display state model may be lazily
+         * loaded: loads it, then shows
+         */
+        async launchTrack(trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
+            return launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
+        },
     }))
         .actions(self => ({
         /**
@@ -1289,6 +1332,13 @@ export function stateModelFactory(pluginManager) {
         toggleTrack(trackId) {
             return toggleTrackGeneric(self, trackId);
         },
+        /**
+         * #action
+         * toggleTrack with launchTrack's loading behavior
+         */
+        async launchToggleTrack(trackId) {
+            return launchToggleTrackGeneric(self, trackId);
+        },
         /**
          * #action
          */
@@ -1402,18 +1452,25 @@ 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, 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).
         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);
+            if (opts.save !== false) {
+                const { saveSvgAsImage } = await import('@jbrowse/core/svg/saveSvgAsImage');
+                await saveSvgAsImage(html, opts);
+            }
+            return html;
         },
     }))
         .actions(self => {
@@ -1866,6 +1923,11 @@ export function stateModelFactory(pluginManager) {
              * The seam is the one that must survive: regions lay out contiguously,
              * so it 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 +1954,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
@@ -1962,6 +2031,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,
@@ -2386,13 +2481,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 +2504,7 @@ export function stateModelFactory(pluginManager) {
                 input,
                 assemblyName,
                 grow,
+                showHitTrack: opts?.showHitTrack,
                 model: self,
             });
         },
@@ -2675,7 +2773,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,6 +2781,7 @@ export function stateModelFactory(pluginManager) {
                     refName,
                     coord,
                     displayedRegions: self.displayedRegions,
+                    displayedRegionIndex,
                 });
                 if (centerBp !== undefined) {
                     flyTo(centerBp, heading ? heading.windowWidthBp : self.windowWidthBp);
@@ -2697,7 +2796,11 @@ export function stateModelFactory(pluginManager) {
         afterAttach() {
             doAfterAttach(self);
         },
-    }))
+    }));
+    return withLaunchInput(model, lgvLaunchKeys, {
+        registry: pluginManager,
+        materialized: snap => !!snap.displayedRegions?.length,
+    })
         .preProcessSnapshot((snap) => {
         if (!snap) {
             return snap;
@@ -2739,23 +2842,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 } : {}),

package/esm/LinearGenomeView/svgcomponents/figureContract.js

@@ -1,25 +1,25 @@
 import { useEffect, useRef } from 'react';
 import { svgNodeId } from '@jbrowse/core/svg/svgId';
+import { contractReportsOn, reportContractViolation, } from '@jbrowse/render-core/contractReports';
 /**
- * Dev-only checks that a live SVG figure is being used the way it can work.
- * No-ops in production.
+ * Checks that a live SVG figure is being used the way it can work.
  *
  * `useViewSvgFigure` publishes a figure whose two halves are drawn at different
  * moments and only agree by construction, and both ways of breaking that are
  * invisible in the output: the drawing is still a plausible picture of
  * somewhere, just not of one moment or not with its own clips. So the run
  * reports instead, through the `[jbrowse <family> contract]` channel every
- * dev-only check in the tree uses — `config/jest/contractGate.js` fails the test
- * that collects one, and ARCHITECTURAL_LIMITS.md §"Ordering is the contract" is
- * the register. `figure` rather than `svg-figure` because the gate's family
- * pattern is `\w+`, which a hyphen is not.
+ * check in the tree uses — `config/jest/contractGate.js` fails the test that
+ * collects one, and ARCHITECTURAL_LIMITS.md §"Ordering is the contract" is the
+ * register. `figure` rather than `svg-figure` because the gate's family pattern
+ * is `\w+`, which a hyphen is not.
  *
- * `console.error` and never a throw, as the rest of that family: a figure is
- * chrome a host renders beside its own, and taking the host's tree down over a
- * drawing is worse than the drawing being wrong.
+ * Reported and never thrown, as the rest of that family: a figure is chrome a
+ * host renders beside its own, and taking the host's tree down over a drawing
+ * is worse than the drawing being wrong.
  */
 function report(message) {
-    console.error(`[jbrowse figure contract] ${message}`);
+    reportContractViolation('figure', message);
 }
 // Live figures per view, keyed the way their SVG ids are. A count rather than a
 // flag: the report belongs on the second mount, and the first has to survive the
@@ -43,9 +43,6 @@ const figuresPerView = new Map();
  */
 export function useOneFigurePerView(view) {
     useEffect(() => {
-        if (process.env.NODE_ENV === 'production') {
-            return undefined;
-        }
         // captured, not re-derived on cleanup: by then the view may have left the
         // tree, and `svgNodeId` walks it
         const key = svgNodeId(view);
@@ -99,7 +96,10 @@ export function useFrozenFigureContract(ref, snapshot) {
     rendered.current = snapshot;
     useEffect(() => {
         const el = ref.current;
-        if (process.env.NODE_ENV === 'production' || !el) {
+        // the one check here with a cost of its own — a `MutationObserver` over the
+        // whole figure subtree — so unlike its neighbour it asks whether the
+        // channel is armed rather than running and reporting into it
+        if (!contractReportsOn() || !el) {
             return undefined;
         }
         const observer = new MutationObserver(() => {

package/esm/LinearGenomeView/svgcomponents/useViewSvgFigure.js

@@ -101,8 +101,8 @@ async function renderFigure(view, opts) {
  */
 const FrozenSvgFigure = memo(function FrozenSvgFigure({ view, snapshot, }) {
     const { width, height, margin, theme } = snapshot;
-    // dev-only, and it watches for the one thing this component cannot enforce:
-    // an observer INSIDE the tree, which the memo above is not between
+    // it watches for the one thing this component cannot enforce: an observer
+    // INSIDE the tree, which the memo above is not between
     const ref = useRef(null);
     useFrozenFigureContract(ref, snapshot);
     return (_jsx(ThemeProvider, { theme: createJBrowseTheme(theme), children: _jsx(StyleThemeProvider, { theme: resolveStyleTheme({ configTheme: theme }), children: _jsx("svg", { ref: ref, width: width, height: height, viewBox: `0 0 ${width} ${height}`, 

package/esm/LinearGenomeView/types.d.ts

@@ -41,4 +41,4 @@ export interface InitState {
     nav?: boolean;
     highlight?: (string | HighlightType)[];
 }
-export type LinearGenomeViewLaunchProps = Partial<Omit<SnapshotIn<LinearGenomeViewStateModel>, keyof InitState | 'id' | 'type' | 'init'>>;
+export type LinearGenomeViewLaunchProps = Partial<Omit<SnapshotIn<LinearGenomeViewStateModel>, keyof InitState | 'id' | 'type' | 'launch'>>;