react-msaview 6.4.2 → 7.0.0

package/src/model.ts

@@ -6,6 +6,7 @@ import {
   applySnapshot,
   cast,
   getSnapshot,
+  isAlive,
   types,
 } from '@jbrowse/mobx-state-tree'
 import { colord } from 'colord'
@@ -40,8 +41,11 @@ import {
   defaultShowDomainLegend,
   defaultShowDomains,
   defaultSubFeatureRows,
+  defaultTreeWidth,
   labelReferenceFontSize,
   maxCellSize,
+  maxInlineSnapshotBytes,
+  maxNeighborJoiningRows,
   minColWidth,
   minLetterColWidth,
   minLetterRowHeight,
@@ -59,11 +63,9 @@ import {
   collapse,
   collapsedSubtreeMaxLength,
   find,
-  findMaxBranchLen,
   forEachDescendant,
   hierarchy,
   leaves,
-  links,
   maxLength,
   setBrLength,
   sort,
@@ -79,8 +81,8 @@ import { parseAsn1 } from './parseAsn1.ts'
 import { calculatePropertyConservation } from './propertyConservation.ts'
 import {
   globalColToVisibleCol,
+  seqPosOfGlobalCol,
   visibleColToGlobalCol,
-  visibleColToSeqPosForRow,
   visibleColsBefore,
 } from './rowCoordinateCalculations.ts'
 import { buildSeqPosIndex } from './seqPosToGlobalCol.ts'
@@ -94,18 +96,26 @@ import {
   transform,
 } from './util.ts'
 import { saveAs } from './vendor/fileSaver.ts'
+import { parseWuss } from './wuss.ts'
 
 import type { HierarchyNode } from './hierarchy.ts'
 import type { ExportSvgOptions } from './renderToSvg.tsx'
 import type {
   Annotation,
+  Arc,
   BasicTrack,
+  ResidueMappingProblem,
   ColumnTrackSpec,
   DomainBand,
   Highlight,
   NodeWithIds,
   NodeWithIdsAndLength,
+  ResidueMapping,
+  ResidueSegment,
   ResolvedHighlight,
+  RowResidue,
+  StructureResidue,
+  UnshareableData,
 } from './types.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
 import type { Instance } from '@jbrowse/mobx-state-tree'
@@ -121,16 +131,22 @@ function parseTreeText(text: string) {
 // Tracks that start hidden. The sequence logo answers a narrower question than
 // conservation does and costs three times the vertical space, so it waits to be
 // asked for.
-const defaultOffTracks = new Set(['sequence-logo'])
+const defaultOffTracks = new Set(['sequence-logo', 'position-ruler'])
+
+// base-pair arcs: one color for the nested helices, one for a pseudoknot, whose
+// whole point is that it crosses them
+const HELIX_ARC = '#4e79a7'
+const PSEUDOKNOT_ARC = '#e15759'
 
 // a data track over this size stays in the live model but leaves the snapshot,
 // the same rule DataModel applies to an inline document
-const maxColumnTrackSnapshotBytes = 50_000
+function columnTrackSizes(tracks?: readonly ColumnTrackSpec[]) {
+  return (tracks ?? []).map(t => JSON.stringify(t).length)
+}
 
 function smallColumnTracks(tracks?: ColumnTrackSpec[]) {
-  const kept = tracks?.filter(
-    t => JSON.stringify(t).length <= maxColumnTrackSnapshotBytes,
-  )
+  const sizes = columnTrackSizes(tracks)
+  const kept = tracks?.filter((_t, i) => sizes[i]! <= maxInlineSnapshotBytes)
   return kept?.length ? { columnTracks: kept } : {}
 }
 
@@ -178,11 +194,49 @@ export const preservedOnReset = new Set([
 // until they touch that track, and then its value is whether the track is OFF.
 // Reading the default through this is what lets a track ship hidden without
 // writing an entry into every snapshot and shared URL.
+// A track the file itself supplies says whether it starts hidden, since only
+// the file knows how many of them there are: a Pfam seed carries a couple of
+// #=GR lines, an Rfam family one per row.
 function trackIsOff(
   turnedOffTracks: { get: (id: string) => boolean | undefined },
   id: string,
+  defaultOff?: boolean,
 ) {
-  return turnedOffTracks.get(id) ?? defaultOffTracks.has(id)
+  return turnedOffTracks.get(id) ?? (defaultOff || defaultOffTracks.has(id))
+}
+
+// one array for every "nothing under the pointer", since a fresh [] is a fresh
+// value to every observer of it
+const noDomains: Annotation[] = []
+
+// seqPos -> column indexes, per row, hung off the parse the rows came from so
+// they are collected with it. A computed would rebuild every row's index on
+// each miss, and rebuild all of them again whenever it was read outside a
+// reactive context.
+const seqPosIndexCache = new WeakMap<object, Map<string, Int32Array>>()
+
+// A segment asserts a 1:1 run, so its two sides have to be the same length.
+// One that is not is malformed data, and the arithmetic below would answer
+// anyway -- with a residue that is off by however much the sides disagree. Skip
+// it, the same refusal an uncovered position gets.
+function sameLength(segment: ResidueSegment) {
+  return (
+    segment.rowEnd - segment.rowStart ===
+    segment.structEnd - segment.structStart
+  )
+}
+
+// Does the content need a scrollbar? fit() divides the viewport by the row or
+// column count and multiplies it back, so an exact fit lands a fraction of a
+// pixel over -- enough for a `>` to answer yes and hand the reader a minimap or
+// a scrollbar for half a pixel of nothing, which then shrinks the viewport and
+// leaves a gap.
+function overflows(content: number, viewport: number) {
+  return content - viewport > 0.5
+}
+
+function inRanges(ranges: [number, number][] | undefined, position: number) {
+  return !!ranges?.some(([start, end]) => position >= start && position <= end)
 }
 
 /**
@@ -352,6 +406,19 @@ function stateModelFactory() {
           [],
         ),
 
+        /**
+         * #property
+         * which residue of which structure each row's residues are, as data.
+         * The viewer cannot infer this -- matching a row to a structure by
+         * sequence equality fails for a tagged construct, a truncation or a
+         * subsequence row, and fails in the direction that looks like it
+         * worked -- so it arrives computed. See docs/layers.md
+         */
+        residueMappings: stripDefault(
+          types.array(types.frozen<ResidueMapping>()),
+          [],
+        ),
+
         /**
          * #property
          * data from the loaded tree/msa/treeMetadata, generally loaded by
@@ -365,8 +432,13 @@ function stateModelFactory() {
 
         /**
          * #property
+         * the user's explicit hide choices per annotation accession, keyed by
+         * accession with the value meaning "off", the same shape as
+         * `turnedOffTracks`. An accession the user has never touched is absent
+         * and drawn, so a file of two hundred domain types adds nothing to the
+         * shared URL until someone filters one out
          */
-        featureFilters: stripDefault(types.map(types.boolean), {}),
+        turnedOffFeatures: stripDefault(types.map(types.boolean), {}),
         /**
          * #property
          */
@@ -398,9 +470,7 @@ function stateModelFactory() {
       /**
        * #volatile
        */
-      status: undefined as
-        | { msg: string; url?: string; onCancel?: () => void }
-        | undefined,
+      status: undefined as { msg: string; onCancel?: () => void } | undefined,
       /**
        * #volatile
        * high resolution scale factor, helps make canvas look better on hi-dpi
@@ -472,6 +542,16 @@ function stateModelFactory() {
        */
       highlightedColumns: undefined as number[] | undefined,
 
+      /**
+       * #volatile
+       * transient highlights keyed by who asked for them. One slot cannot hold
+       * two sources -- a structure viewer's hover and a genome view's hover
+       * both want to point at a column, and with one slot whoever clears last
+       * erases the other's. Keyed by owner, each source adds and removes only
+       * its own. Not persisted: a hover is not part of the document.
+       */
+      transientHighlights: {} as Record<string, Highlight[]>,
+
       /**
        * #volatile
        */
@@ -482,6 +562,15 @@ function stateModelFactory() {
        */
       conservationTrackHeight: 40,
 
+      /**
+       * #volatile
+       * heights of individual `columnTracks`, by track id. A data track is
+       * resized on its own: the shared per-kind heights below belong to the
+       * tracks the viewer computes, and dragging a data track's handle used to
+       * resize those instead.
+       */
+      columnTrackHeights: {} as Record<string, number>,
+
       /**
        * #volatile
        * taller than the conservation track by default: the logo spends its
@@ -490,6 +579,11 @@ function stateModelFactory() {
        */
       sequenceLogoTrackHeight: 80,
 
+      /**
+       * #volatile
+       */
+      arcTrackHeight: 50,
+
       /**
        * #volatile
        */
@@ -501,6 +595,32 @@ function stateModelFactory() {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
       error: undefined as unknown,
 
+      /**
+       * #volatile
+       * load problems the view carried on through: an optional layer that did
+       * not arrive, an overlay that did not parse. `error` is the other kind --
+       * it replaces the view, which is right for the alignment and wrong for a
+       * decorative file
+       */
+      warnings: [] as string[],
+
+      /**
+       * #volatile
+       * bumped by reset(). The React error boundary above the view keeps its
+       * caught error until it is remounted, so "Return to import form" did
+       * nothing after a render error until this became its key
+       */
+      resetCount: 0,
+
+      /**
+       * #volatile
+       * set by a host that restores the loaded documents by its own means --
+       * a jbrowse session that holds them, a page that refetches them on load.
+       * `unshareableData` then reports nothing, since what it warns about is a
+       * link that opens empty, and under such a host the link does not
+       */
+      hostCarriesData: false,
+
       /**
        * #volatile
        * overlay annotations drawn on the alignment, whatever their source.
@@ -574,13 +694,38 @@ function stateModelFactory() {
         self.error = error
       },
 
+      /**
+       * #action
+       * report something the view survived: a layer that failed to load, a
+       * file that failed to parse
+       */
+      addWarning(warning: string) {
+        self.warnings = [...self.warnings, warning]
+      },
+
+      /**
+       * #action
+       */
+      clearWarnings() {
+        self.warnings = []
+      },
+
+      /**
+       * #action
+       * declare that this host restores the loaded documents itself, which
+       * takes down the "Not in the link" warning. See `hostCarriesData`
+       */
+      setHostCarriesData(arg: boolean) {
+        self.hostCarriesData = arg
+      },
+
       /**
        * #action
        * set mouse position (row, column) in the MSA
        *
-       * CROSS-REPO CONTRACT: jbrowse-plugin-protein3d calls this (and reads the
-       * `mouseCol` volatile) to sync MSA<->3D-structure hover. Keep the name and
-       * signature stable; see that repo's ProteinToMsaHoverSync.tsx.
+       * PUBLIC API: a host drives this (and reads the `mouseCol` volatile) to
+       * sync the alignment's hover with a view of its own -- a genome view, a
+       * 3D structure. Keep the name and signature stable.
        */
       setMousePos(col?: number, row?: number) {
         self.mouseCol = col
@@ -591,9 +736,9 @@ function stateModelFactory() {
        * #action
        * set highlighted columns
        *
-       * CROSS-REPO CONTRACT: called by jbrowse-plugin-msaview
-       * (afterCreateAutoruns.ts) to highlight alignment columns. It has no
-       * in-repo caller, so do not flag it as dead code — it is public API.
+       * PUBLIC API: jbrowse-plugin-msaview calls this from its
+       * afterCreateAutoruns to highlight alignment columns, and MSAViewer
+       * passes its `highlightColumns` prop through it. Not dead code.
        */
       setHighlightedColumns(columns?: number[]) {
         self.highlightedColumns = columns
@@ -604,6 +749,29 @@ function stateModelFactory() {
       setHighlights(highlights: Highlight[]) {
         self.highlights.replace(highlights)
       },
+      /**
+       * #action
+       * show `highlights` on behalf of `owner`, replacing whatever that owner
+       * showed before and leaving every other owner's alone. The object is
+       * replaced rather than mutated so one assignment is the observable
+       * change.
+       */
+      applyHighlight(owner: string, highlights: Highlight[]) {
+        self.transientHighlights = {
+          ...self.transientHighlights,
+          [owner]: highlights,
+        }
+      },
+      /**
+       * #action
+       * drop what `owner` was showing, leaving every other owner's in place
+       */
+      clearHighlight(owner: string) {
+        if (owner in self.transientHighlights) {
+          const { [owner]: _dropped, ...rest } = self.transientHighlights
+          self.transientHighlights = rest
+        }
+      },
       /**
        * #action
        * toggle the annotation overlay on the alignment
@@ -651,10 +819,23 @@ function stateModelFactory() {
 
       /**
        * #action
-       *
+       * switch to another alignment of a multi-alignment file (Stockholm). The
+       * new alignment has its own rows and its own tree, so everything naming
+       * the old one's -- the collapsed node ids, the subtree in focus, the
+       * reference row, the scroll position -- goes with it
        */
       setCurrentAlignment(n: number) {
-        self.currentAlignment = n
+        if (n === self.currentAlignment) {
+          return
+        }
+        transaction(() => {
+          self.currentAlignment = n
+          self.collapsed.clear()
+          this.setShowOnly(undefined)
+          this.drawRelativeTo(undefined)
+          self.scrollX = 0
+          self.scrollY = 0
+        })
       },
 
       /**
@@ -740,6 +921,18 @@ function stateModelFactory() {
       setTreeMetadata(result: string) {
         self.data.setTreeMetadata(result)
       },
+
+      /**
+       * #action
+       * keep the GFF text the way the alignment and the tree are kept, rather
+       * than only its parsed annotations. The annotations are volatile, so a
+       * file opened from disk used to leave no trace in the snapshot at all --
+       * not the text, and not the filehandle, which is cleared once a blob is
+       * read. An autorun parses this back into annotations.
+       */
+      setGFF(result: string) {
+        self.data.setGFF(result)
+      },
     }))
 
     .views(self => ({
@@ -765,6 +958,22 @@ function stateModelFactory() {
       get actuallyShowDomains() {
         return self.showDomains && self.annotations.length > 0
       },
+      /**
+       * #getter
+       * whether this host brings the loaded documents back by means the
+       * snapshot cannot see, which is what decides whether `unshareableData`
+       * has anything to warn about.
+       *
+       * A simple host flips the `hostCarriesData` volatile. A host whose
+       * answer depends on how the view was opened overrides this getter in a
+       * `.views` block of its own composed model -- jbrowse-plugin-msaview's
+       * indexed-location views refetch from a URL the session holds, while its
+       * data-store views really are absent from a link someone pastes
+       * elsewhere. `unshareableData` reads it off `self`, so an override wins.
+       */
+      get hostRestoresData() {
+        return self.hostCarriesData
+      },
       get viewInitialized() {
         return self.volatileWidth !== undefined
       },
@@ -779,13 +988,6 @@ function stateModelFactory() {
       },
     }))
     .views(self => ({
-      /**
-       * #method
-       * unused here, but can be used by derived classes to add extra items
-       */
-      extraViewMenuItems() {
-        return []
-      },
       /**
        * #getter
        */
@@ -820,6 +1022,53 @@ function stateModelFactory() {
       get noDomains() {
         return self.annotations.length === 0
       },
+
+      /**
+       * #getter
+       * the loaded documents this view's own snapshot cannot carry, largest
+       * first. A file opened from disk or pasted in becomes inline text, and
+       * DataModel drops an inline document past `maxInlineSnapshotBytes`
+       * rather than put megabytes of sequence into a session or a URL.
+       *
+       * Dropping it is right. Dropping it silently is what makes a copied link
+       * open an empty viewer, so the header says so and the standalone app
+       * stops rewriting the address bar while this is non-empty. A document
+       * fetched from a URL never appears here whatever its size: the snapshot
+       * keeps the filehandle and refetches through it.
+       *
+       * Nothing is unshareable when the host restores the data by its own
+       * means (see `hostRestoresData`) -- inside a session that reloads these
+       * documents from somewhere the snapshot does not show, the warning is
+       * simply wrong.
+       */
+      get unshareableData(): UnshareableData[] {
+        if (self.hostRestoresData) {
+          return []
+        }
+        const { data } = self
+        // a data track past the limit leaves the snapshot the same way an
+        // inline document does, and left unreported the same way too
+        const trackBytes = columnTrackSizes(self.columnTracks)
+          .filter(bytes => bytes > maxInlineSnapshotBytes)
+          .reduce((a, b) => a + b, 0)
+        return (
+          [
+            ['alignment', data.msa, self.msaFilehandle],
+            ['tree', data.tree, self.treeFilehandle],
+            ['annotations', data.gff, self.gffFilehandle],
+            ['row metadata', data.treeMetadata, self.treeMetadataFilehandle],
+          ] as const
+        )
+          .flatMap<UnshareableData>(([what, text, filehandle]) =>
+            !filehandle && text && text.length > maxInlineSnapshotBytes
+              ? [{ what, bytes: text.length }]
+              : [],
+          )
+          .concat(
+            trackBytes ? [{ what: 'data tracks', bytes: trackBytes }] : [],
+          )
+          .sort((a, b) => b.bytes - a.bytes)
+      },
       menuItems() {
         return []
       },
@@ -1047,24 +1296,51 @@ function stateModelFactory() {
       },
 
       /**
-       * #getter
-       * per-row index of the global column holding each ungapped sequence
-       * position, so seqPos -> column is a lookup rather than a scan of the row.
-       * The domain overlay resolves thousands of these per redraw.
+       * #method
+       * index of the global column holding each ungapped sequence position of a
+       * row, so seqPos -> column is a lookup rather than a scan. The domain
+       * overlay resolves thousands of these per redraw.
+       *
+       * Built per row, on the row asked for: the first lookup used to index
+       * every row in the alignment. The cache is keyed on the parse the rows
+       * came from, so a new alignment brings a new one.
        */
-      get seqPosGlobalColIndex() {
-        return new Map(
-          this.rows.map(
-            ([name, seq]) => [name, buildSeqPosIndex(seq)] as const,
-          ),
-        )
+      seqPosIndex(rowName: string): Int32Array | undefined {
+        const MSA = this.MSA
+        if (!MSA) {
+          return undefined
+        }
+        let cache = seqPosIndexCache.get(MSA)
+        if (!cache) {
+          cache = new Map()
+          seqPosIndexCache.set(MSA, cache)
+        }
+        let index = cache.get(rowName)
+        if (!index) {
+          const seq = MSA.getRow(rowName)
+          if (!seq) {
+            return undefined
+          }
+          index = buildSeqPosIndex(seq)
+          cache.set(rowName, index)
+        }
+        return index
       },
 
       /**
        * #getter
+       * every sequence the alignment holds, keyed by row name, whatever the
+       * tree currently shows. `rows` is the rows on screen; this is the rows
+       * that exist, and every lookup about a named row goes through it --
+       * collapsing a clade hides rows, it does not delete their sequence
        */
       get rowMap() {
-        return new Map(this.rows)
+        const MSA = this.MSA
+        return new Map(
+          MSA?.getNames()
+            .map(name => [name, MSA.getRow(name)] as const)
+            .filter(([, seq]) => !!seq),
+        )
       },
       /**
        * #getter
@@ -1201,10 +1477,13 @@ function stateModelFactory() {
       get hierarchy(): HierarchyNode<NodeWithIdsAndLength> {
         const r = this.root
         clusterLayout(r, this.totalHeight, self.treeWidth)
-        r.data.length = 0
-        const max = maxLength(r)
+        const max = this.rootToTipLength
         const k = max ? self.treeWidth / max : 0
-        setBrLength(r, 0, k)
+        // the displayed root starts at x=0 whatever branch length it carries,
+        // so its own length is subtracted here rather than zeroed on the parsed
+        // node -- `root` hands out the cached parse, and writing to it made
+        // showOnly shorten that branch for good
+        setBrLength(r, -Math.max(r.data.length || 0, 0), k)
         // for each collapsed clade, record the pixel x-position of its farthest
         // tip so the renderer can draw a triangle spanning the branch-length
         // extent of the hidden subtree
@@ -1233,10 +1512,34 @@ function stateModelFactory() {
 
       /**
        * #getter
-       * max branch length across the tree, used to scale phylogram x-positions
+       * branch-length extent of the displayed tree, root to farthest tip, in
+       * the tree's own units
+       */
+      get rootToTipLength() {
+        const r = this.root
+        return maxLength(r) - Math.max(r.data.length || 0, 0)
+      },
+
+      /**
+       * #getter
+       * x-position of the farthest tip in a phylogram, px. The layout scales
+       * the longest root-to-tip path onto treeWidth, so that is where it lands
+       * -- and 0 for a tree carrying no lengths at all, which draws as a
+       * cladogram instead
        */
       get maxBranchLength() {
-        return findMaxBranchLen(this.hierarchy)
+        return this.rootToTipLength ? self.treeWidth : 0
+      },
+
+      /**
+       * #getter
+       * pixels per unit of branch length in the current phylogram layout, and 0
+       * in cladogram mode, where the x-positions carry no length at all. The
+       * scale bar over the tree is drawn from it.
+       */
+      get pxPerBranchLength() {
+        const max = maxLength(this.root)
+        return this.showBranchLenEffective && max ? self.treeWidth / max : 0
       },
 
       /**
@@ -1251,7 +1554,7 @@ function stateModelFactory() {
        * #getter
        */
       get allBranchesLength0() {
-        return links(this.hierarchy).every(s => !s.source.data.length)
+        return this.rootToTipLength === 0
       },
 
       /**
@@ -1275,673 +1578,1018 @@ function stateModelFactory() {
       /**
        * #getter
        */
-      get dataInitialized() {
-        // truthiness, not `!== ''`: these are types.maybe, and DataModel's
-        // postProcessSnapshot drops a document over 50kb, so a restored session
-        // that inlined a large alignment comes back `undefined` here -- which
-        // `!== ''` reads as initialized and renders an empty view instead of
-        // the import form
-        return !!(self.data.msa || self.data.tree) && !self.error
-      },
-      /**
-       * #getter
-       */
-      get blocksX() {
-        return calculateBlocks({
-          viewportSize: self.msaAreaWidth,
-          viewportPos: -self.scrollX,
-          blockSize: self.blockSize,
-          mapSize: self.totalWidth,
-        })
-      },
-      /**
-       * #getter
-       */
-      get blocksY() {
-        return calculateBlocks({
-          viewportSize: this.visibleMsaHeight,
-          viewportPos: -self.scrollY,
-          blockSize: self.blockSize,
-          mapSize: self.totalHeight,
-        })
+      get showMsaLetters() {
+        return (
+          self.drawMsaLetters &&
+          self.rowHeight >= minLetterRowHeight &&
+          self.colWidth >= minLetterColWidth &&
+          self.colWidth > self.rowHeight / 2
+        )
       },
       /**
        * #getter
-       * height of the alignment viewport, px. The same subtraction as
-       * msaAreaHeight, which is defined later in the views chain
        */
-      get visibleMsaHeight() {
-        return (
-          self.height -
-          self.headerHeight -
-          (self.msaAreaWidth < self.totalWidth ? self.minimapHeight : 0)
-        )
+      get showTreeText() {
+        return self.drawLabels && self.rowHeight >= minLetterRowHeight
       },
     }))
     .views(self => ({
       /**
        * #getter
        */
-      get blocks2d() {
-        return self.blocksY.flatMap(by =>
-          self.blocksX.map(bx => [bx, by] as const),
-        )
+      get labelWidthMap() {
+        const { showTreeText, leaves, treeMetadata } = self
+        // gated on the same condition the renderer draws labels under, so the
+        // gutter labelsWidth reserves and the labels actually drawn cannot
+        // disagree -- and so turning labels off hands their space to the tree.
+        // Measured at a fixed reference size and scaled by labelWidthScale:
+        // re-measuring every leaf on every vertical-zoom frame cost ~200ms on a
+        // 50k-leaf tree
+        return showTreeText
+          ? new Map(
+              leaves.map(node => {
+                const { name } = node.data
+                // `||`, matching renderTreeLabels: an empty genome falls back
+                // to the row name, and measuring '' would size the gutter (and
+                // the label's click target) to nothing
+                const displayName = treeMetadata[name]?.genome || name
+                return [
+                  name,
+                  measureTextCanvas(displayName, labelReferenceFontSize),
+                ] as const
+              }),
+            )
+          : new Map<string, number>()
       },
 
       /**
        * #getter
+       * factor turning a labelWidthMap entry into its width at the current
+       * font size
        */
-      get isLoading() {
-        return self.loadingMSA || self.loadingTree
+      get labelWidthScale() {
+        return self.fontSize / labelReferenceFontSize
+      },
+
+      get labelsWidth() {
+        // a loop, not Math.max(...widths.values()): spreading a map of every
+        // leaf passes one argument per row, and the argument limit is somewhere
+        // around 125k -- so the bundled 230k-tip COVID tree threw
+        // "RangeError: Maximum call stack size exceeded" out of a getter the
+        // treeWidth autorun reads on load
+        let max = 0
+        for (const width of this.labelWidthMap.values()) {
+          if (width > max) {
+            max = width
+          }
+        }
+        return max * this.labelWidthScale
       },
+
       /**
        * #getter
        */
-      get maxScrollX() {
-        return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0)
+      get secondaryStructureConsensus() {
+        return self.MSA?.secondaryStructureConsensus
       },
+
       /**
        * #getter
-       * most-negative allowed scrollY, keeping the last row in view rather than
-       * letting the whole alignment scroll off the top.
        */
-      get maxScrollY() {
-        return Math.min(-self.totalHeight + self.visibleMsaHeight, 0)
+      get seqConsensus() {
+        return self.MSA?.seqConsensus
       },
+
       /**
        * #getter
+       * the base pairs of the consensus secondary structure, as arcs. The WUSS
+       * string is collapsed through the hidden columns before it is parsed, so
+       * the pairs land in the same visible column space the text track does
        */
-      get showMsaLetters() {
-        return (
-          self.drawMsaLetters &&
-          self.rowHeight >= minLetterRowHeight &&
-          self.colWidth >= minLetterColWidth &&
-          self.colWidth > self.rowHeight / 2
+      get secondaryStructureArcs(): Arc[] | undefined {
+        const { blanks, hideGapsEffective } = self
+        const ss = this.secondaryStructureConsensus
+        if (!ss) {
+          return undefined
+        }
+        return parseWuss(hideGapsEffective ? skipBlanks(blanks, ss) : ss).map(
+          ({ start, end, pseudoknot }) => ({
+            start,
+            end,
+            color: pseudoknot ? PSEUDOKNOT_ARC : HELIX_ARC,
+          }),
         )
       },
+
       /**
        * #getter
        */
-      get showTreeText() {
-        return self.drawLabels && self.rowHeight >= minLetterRowHeight
-      },
-    }))
-    .actions(self => ({
-      /**
-       * #action
-       */
-      setDrawMsaLetters(arg: boolean) {
-        self.drawMsaLetters = arg
+      get adapterTrackModels(): BasicTrack[] {
+        const { MSA, hideGapsEffective, blanks } = self
+        const tracks = (MSA?.tracks ?? []).filter(t => !!t.data)
+        if (tracks.length === 0) {
+          // reading rowHeight up front made every zoom frame rebuild the track
+          // list, and the canvases redraw on the track object they are handed
+          // changing
+          return []
+        }
+        const { rowHeight } = self
+        return tracks.map(t => ({
+          model: {
+            ...t,
+            kind: 'text' as const,
+            data: hideGapsEffective ? skipBlanks(blanks, t.data!) : t.data,
+            height: rowHeight,
+          },
+          ReactComponent: TrackBlocks,
+        }))
       },
 
       /**
-       * #action
-       */
-      setScrollZoom(arg: boolean) {
-        self.scrollZoom = arg
-      },
-
-      /**
-       * #action
-       * set hovered tree node and its descendants
+       * #getter
+       * a data track's values or string, projected from its row's residues
+       * onto alignment columns when it names a row
        */
-      setHoveredTreeNode(nodeId?: string) {
-        // the tree's mousemove handler calls this on every event, and both the
-        // lookup and the write are expensive: `find` walks the whole hierarchy,
-        // and a fresh object here invalidates hoveredRowIndices and redraws the
-        // tree and MSA overlays. Re-hovering the same node is the common case
-        if (nodeId === self.hoveredTreeNode?.nodeId) {
-          return
+      get columnTrackContent() {
+        const { MSA, blanks, hideGapsEffective } = self
+        const width = MSA?.getWidth() ?? 0
+        const project = <T>(track: ColumnTrackSpec, items: T[], fill: T) => {
+          if (!track.row) {
+            return items
+          }
+          const out = Array.from({ length: width }, () => fill)
+          const index = self.seqPosIndex(track.row)
+          items.forEach((item, seqPos) => {
+            const col = index?.[seqPos]
+            if (col !== undefined) {
+              out[col] = item
+            }
+          })
+          return out
         }
-        if (!nodeId) {
-          self.hoveredTreeNode = undefined
-          return
+        const skip = <T>(items: T[]) =>
+          hideGapsEffective ? dropBlanks(blanks, items) : items
+        // an arc names two positions rather than one per column, so it takes
+        // the same two steps the arrays take -- a row's residues onto columns,
+        // then columns onto the visible ones -- as a lookup. visibleColsBefore,
+        // not globalColToVisibleCol: an endpoint in a hidden column collapses
+        // to where that column went instead of taking the whole arc with it
+        const resolve = (track: ColumnTrackSpec, pos: number) => {
+          const col = track.row
+            ? self.seqPosIndex(track.row)?.[pos - 1]
+            : pos - 1
+          if (col === undefined || col < 0 || col >= width) {
+            return undefined
+          }
+          return hideGapsEffective ? visibleColsBefore(blanks, col) : col
         }
-        const node = find(self.hierarchy, n => n.data.id === nodeId)
-        self.hoveredTreeNode = node
-          ? {
-              nodeId,
-              descendantNames: leaves(node).map(leaf => leaf.data.name),
+        return new Map<
+          string,
+          { values?: number[]; data?: string; arcs?: Arc[] }
+        >(
+          self.columnTracks.map(track => {
+            if (track.kind === 'arc') {
+              const arcs = (track.arcs ?? [])
+                .map(arc => {
+                  const start = resolve(track, Math.min(arc.start, arc.end))
+                  const end = resolve(track, Math.max(arc.start, arc.end))
+                  return start !== undefined && end !== undefined && start < end
+                    ? { start, end, color: arc.color }
+                    : undefined
+                })
+                .filter(notEmpty)
+              return [track.id, { arcs }] as const
             }
-          : undefined
+            if (track.kind === 'bar') {
+              const max = track.max ?? 1
+              const values = skip(project(track, track.values ?? [], 0)).map(
+                v => Math.min(1, Math.max(0, v / max)),
+              )
+              return [track.id, { values }] as const
+            }
+            const data = skip(project(track, (track.data ?? '').split(''), ' '))
+            return [track.id, { data: data.join('') }] as const
+          }),
+        )
       },
-
       /**
-       * #action
-       * Calculate a neighbor joining tree from the current MSA using BLOSUM62 distances
+       * #getter
        */
-      calculateNeighborJoiningTreeFromMSA() {
-        if (self.rows.length < 2) {
-          throw new Error('Need at least 2 sequences to build a tree')
-        }
-        const newickTree = calculateNeighborJoiningTree(self.rows)
-        self.setTree(newickTree)
+      get columnTrackModels(): BasicTrack[] {
+        // read per kind, not up front: a text track is the only kind sized by
+        // the row height, and reading it here rebuilt every data track on every
+        // vertical zoom step
+        const defaultHeight = (kind: ColumnTrackSpec['kind']) =>
+          kind === 'bar'
+            ? self.conservationTrackHeight
+            : kind === 'arc'
+              ? self.arcTrackHeight
+              : self.rowHeight
+        return self.columnTracks.map(track => ({
+          model: {
+            id: track.id,
+            name: track.name,
+            kind: track.kind,
+            height:
+              self.columnTrackHeights[track.id] ??
+              track.height ??
+              defaultHeight(track.kind),
+            // the spec has one `color`; bar and arc are separate track models
+            // that read it under their own name
+            barColor: track.color,
+            arcColor: track.color,
+            customColorScheme: track.colors,
+            data: this.columnTrackContent.get(track.id)?.data,
+            arcs: this.columnTrackContent.get(track.id)?.arcs,
+          },
+          ReactComponent: TrackBlocks,
+        }))
+      },
+      /**
+       * #getter
+       */
+      /**
+       * #getter
+       * the consensus secondary structure as a track, when there is one. Its
+       * own getter so the object keeps its identity across a zoom: the canvas
+       * redraws on the track it is handed changing, and rebuilding these
+       * alongside everything else made every zoom frame redraw every track
+       */
+      get basePairTrackModels(): BasicTrack[] {
+        const arcs = this.secondaryStructureArcs
+        return arcs?.length
+          ? [
+              {
+                model: {
+                  id: 'base-pairs',
+                  name: 'Base pairs',
+                  kind: 'arc' as const,
+                  height: self.arcTrackHeight,
+                  arcs,
+                },
+                ReactComponent: TrackBlocks,
+              },
+            ]
+          : []
       },
 
       /**
-       * #action
-       * restore the default column width and row height
+       * #getter
+       * the tracks computed from the alignment itself, which depend on their
+       * own heights and on the alphabet -- and on nothing zoom changes
        */
-      resetZoom() {
-        self.setColWidth(defaultColWidth)
-        self.setRowHeight(defaultRowHeight)
+      get computedTrackModels(): BasicTrack[] {
+        return [
+          {
+            id: 'conservation',
+            name: 'Conservation',
+            kind: 'bar' as const,
+            height: self.conservationTrackHeight,
+            barColor: 'gray',
+          },
+          ...(self.sequenceType === 'amino'
+            ? [
+                {
+                  id: 'property-conservation',
+                  name: 'Property conservation',
+                  kind: 'bar' as const,
+                  height: self.conservationTrackHeight,
+                  barColor: '#6a51a3',
+                },
+              ]
+            : []),
+          {
+            id: 'sequence-logo',
+            name: 'Sequence logo',
+            kind: 'logo' as const,
+            height: self.sequenceLogoTrackHeight,
+          },
+          // last, so it sits against the alignment it numbers
+          {
+            id: 'position-ruler',
+            name: 'Position',
+            kind: 'ruler' as const,
+            height: 20,
+          },
+        ].map(model => ({ model, ReactComponent: TrackBlocks }))
       },
+
+      get tracks(): BasicTrack[] {
+        return [
+          ...this.adapterTrackModels,
+          ...this.basePairTrackModels,
+          ...this.columnTrackModels,
+          ...this.computedTrackModels,
+        ]
+      },
+
       /**
-       * #action
+       * #getter
        */
-      zoomOutHorizontal() {
-        self.colWidth = Math.max(minColWidth, Math.floor(self.colWidth * 0.75))
-        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+      get turnedOnTracks() {
+        return this.tracks.filter(
+          f =>
+            !trackIsOff(self.turnedOffTracks, f.model.id, f.model.defaultOff),
+        )
       },
+
       /**
-       * #action
+       * #getter
        */
-      zoomInHorizontal() {
-        self.colWidth = Math.min(maxCellSize, Math.ceil(self.colWidth * 1.5))
-        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+      get showHorizontalScrollbar() {
+        return overflows(self.totalWidth, self.msaAreaWidth)
       },
+
       /**
-       * #action
+       * #method
+       * Return a row-specific letter at a visible column, or undefined if gap.
+       *
+       * @param rowName - The name of the row
+       * @param visibleCol - The visible column index (what the user sees on screen)
+       * @returns The letter at that position, or undefined if it's a gap
        */
-      zoomInVertical() {
-        self.rowHeight = Math.min(maxCellSize, Math.ceil(self.rowHeight * 1.5))
+      visibleColToRowLetter(rowName: string, visibleCol: number) {
+        return self.rowMap.get(rowName)?.[
+          this.visibleColToGlobalCol(visibleCol)
+        ]
       },
+
       /**
-       * #action
+       * #method
+       * Convert a visible column to a row-specific sequence position (0-based).
+       * Returns undefined if the position is a gap in the sequence.
+       *
+       * PUBLIC API: this and the sibling coordinate converters
+       * (visibleColToGlobalCol, seqPosToVisibleCol, globalColToVisibleCol,
+       * seqPosToGlobalCol) are how a host translates between alignment columns
+       * and a row's residue positions across gaps. Keep them stable.
+       *
+       * @param rowName - The name of the row
+       * @param visibleCol - The visible column index
+       * @returns The sequence position (0-based), or undefined if it's a gap
        */
-      zoomOutVertical() {
-        self.rowHeight = Math.max(
-          minRowHeight,
-          Math.floor(self.rowHeight * 0.75),
+      visibleColToSeqPos(rowName: string, visibleCol: number) {
+        // a binary search of the row's index, not a scan of the row: this
+        // answers on every mouse move, and a 30k-column row scanned per event
+        // is the whole frame
+        return seqPosOfGlobalCol(
+          self.seqPosIndex(rowName),
+          this.visibleColToGlobalCol(visibleCol),
         )
       },
+
       /**
-       * #action
+       * #method
+       * Convert a visible column to a row-specific sequence position (1-based).
+       * Returns undefined if the position is a gap in the sequence.
+       *
+       * @param rowName - The name of the row
+       * @param visibleCol - The visible column index
+       * @returns The sequence position (1-based), or undefined if it's a gap
        */
-      zoomIn() {
-        transaction(() => {
-          this.zoomInHorizontal()
-          this.zoomInVertical()
-        })
+      visibleColToSeqPosOneBased(rowName: string, visibleCol: number) {
+        const val = this.visibleColToSeqPos(rowName, visibleCol)
+        return val !== undefined ? val + 1 : undefined
       },
+
       /**
-       * #action
+       * #method
+       * Convert a global column index to a visible column index.
+       * Returns undefined if the column is hidden (in blanks).
+       * This is the inverse of visibleColToGlobalCol.
+       *
+       * @param globalCol - The global column index in the full MSA
+       * @returns The visible column index, or undefined if the column is hidden
        */
-      zoomOut() {
-        transaction(() => {
-          this.zoomOutHorizontal()
-          this.zoomOutVertical()
-        })
+      globalColToVisibleCol(globalCol: number) {
+        const { blanks, hideGapsEffective } = self
+        if (!hideGapsEffective) {
+          return globalCol
+        }
+        return globalColToVisibleCol(blanks, globalCol)
       },
+
       /**
-       * #action
-       * Smoothly zoom by a continuous scaleFactor. The column under the cursor
-       * (offsetX/offsetY, px relative to the MSA area) stays anchored
-       * horizontally. Vertically the anchor is biased toward the top: when the
-       * alignment nearly fits the viewport, snap to y=0 rather than pinning a
-       * random row under the cursor, with the bias fading out as the alignment
-       * grows taller than the viewport (where cursor-anchoring is useful).
-       * Drives wheel/trackpad-pinch zoom.
+       * #method
+       * Convert a visible column index (what a mouse handler reports) back to a
+       * column of the full alignment. Hidden columns shift everything to their
+       * right, so a host that holds per-column data of its own has to make this
+       * hop before indexing it.
+       *
+       * @param visibleCol - The visible column index
+       * @returns The global column index in the full MSA
        */
-      zoomToPos(scaleFactor: number, offsetX: number, offsetY: number) {
-        transaction(() => {
-          const colInView = (-self.scrollX + offsetX) / self.colWidth
-          const rowInView = (-self.scrollY + offsetY) / self.rowHeight
-          self.colWidth = clamp(
-            self.colWidth * scaleFactor,
-            minColWidth,
-            maxCellSize,
-          )
-          self.rowHeight = clamp(
-            self.rowHeight * scaleFactor,
-            minRowHeight,
-            maxCellSize,
+      visibleColToGlobalCol(visibleCol: number) {
+        const { blanks, hideGapsEffective } = self
+        return hideGapsEffective
+          ? visibleColToGlobalCol(blanks, visibleCol)
+          : visibleCol
+      },
+
+      /**
+       * #method
+       * Convert a sequence position (ungapped) to a global column index.
+       * Returns undefined for a row the alignment does not have -- answering
+       * anyway is how a mistyped or stale row name came to highlight column 0.
+       *
+       * @param rowName - The name of the row
+       * @param seqPos - The sequence position (0-based, ungapped)
+       * @returns The global column index in the full MSA, or undefined
+       */
+      seqPosToGlobalCol(rowName: string, seqPos: number) {
+        const seq = self.rowMap.get(rowName)
+        if (seq === undefined) {
+          return undefined
+        }
+        const col = self.seqPosIndex(rowName)?.[seqPos]
+        // past the end of the ungapped sequence: 0 for the degenerate all-gap
+        // row, otherwise one past the last column
+        return col ?? (seqPos === 0 ? 0 : seq.length)
+      },
+
+      /**
+       * #method
+       * Convert a sequence position (ungapped) directly to a visible column index.
+       * This combines seqPosToGlobalCol and globalColToVisibleCol.
+       *
+       * @param rowName - The name of the row
+       * @param seqPos - The sequence position (0-based, ungapped)
+       * @returns The visible column index, or undefined if the column is hidden
+       */
+      seqPosToVisibleCol(rowName: string, seqPos: number) {
+        const globalCol = this.seqPosToGlobalCol(rowName, seqPos)
+        return globalCol === undefined
+          ? undefined
+          : this.globalColToVisibleCol(globalCol)
+      },
+
+      /**
+       * #getter
+       * every reason a mapping is being ignored, so a host can say which. A
+       * mapping outlives the alignment it was computed for; when the two no
+       * longer agree the lookups have to refuse, and refusing invisibly is how
+       * "there is no structure here" gets confused with "this data is stale".
+       */
+      get residueMappingProblems(): ResidueMappingProblem[] {
+        const problems: ResidueMappingProblem[] = []
+        for (const mapping of self.residueMappings) {
+          const where = { row: mapping.row, structureId: mapping.structure.id }
+          const residues = self.seqPosIndex(mapping.row)?.length
+          if (residues === undefined) {
+            problems.push({
+              ...where,
+              scope: 'mapping',
+              reason: 'no such row in the alignment',
+            })
+            continue
+          }
+          if (
+            mapping.rowLength !== undefined &&
+            mapping.rowLength !== residues
+          ) {
+            problems.push({
+              ...where,
+              scope: 'mapping',
+              reason: `computed against a ${mapping.rowLength}-residue row; this one has ${residues}`,
+            })
+            continue
+          }
+          const overrun = mapping.segments.find(
+            segment => segment.rowEnd > residues || segment.rowStart < 1,
           )
-          self.scrollX = clamp(
-            offsetX - colInView * self.colWidth,
-            self.maxScrollX,
-            0,
+          if (overrun) {
+            problems.push({
+              ...where,
+              scope: 'mapping',
+              reason: `segment ${overrun.rowStart}-${overrun.rowEnd} does not fit a ${residues}-residue row`,
+            })
+            continue
+          }
+          for (const segment of mapping.segments) {
+            if (!sameLength(segment)) {
+              problems.push({
+                ...where,
+                scope: 'segment',
+                reason: `segment ${segment.rowStart}-${segment.rowEnd} maps to ${segment.structStart}-${segment.structEnd}, which is a different length`,
+              })
+            }
+          }
+        }
+        return problems
+      },
+
+      /**
+       * #getter
+       * the mappings that still fit the loaded alignment. A row-level problem
+       * takes the whole mapping out; a single malformed segment takes only
+       * itself, since the rest of the mapping is still a claim about residues
+       * that exist.
+       */
+      get usableResidueMappings(): ResidueMapping[] {
+        const unusable = new Set(
+          this.residueMappingProblems
+            .filter(problem => problem.scope === 'mapping')
+            .map(problem => `${problem.row}\u0000${problem.structureId}`),
+        )
+        return self.residueMappings
+          .filter(m => !unusable.has(`${m.row}\u0000${m.structure.id}`))
+          .map(m => ({
+            ...m,
+            segments: m.segments.filter(sameLength),
+          }))
+      },
+
+      /**
+       * #getter
+       * the structures the loaded alignment has usable mappings onto. A row can
+       * have several -- an experimental entry and a predicted model, say -- so
+       * a host that means a particular one has to name it.
+       */
+      get mappedStructures() {
+        return this.usableResidueMappings.map(m => ({
+          row: m.row,
+          structure: m.structure,
+        }))
+      },
+
+      /**
+       * #method
+       * The structure residue a row residue is, or undefined. Refusing is the
+       * point: the guess this replaces answered every query, with a wrong
+       * residue when it did not know.
+       *
+       * It also refuses when the answer is not unique. A row commonly maps onto
+       * several structures -- an experimental entry and two predicted models --
+       * and returning whichever came first would be the same class of wrong,
+       * quieter. Name one with `structureId`, or use `mappedStructures` to see
+       * what there is.
+       *
+       * Positions are 1-based, as `residueMappings` and `highlights` are --
+       * note that the column helpers above take 0-based ones.
+       *
+       * @param rowName - The alignment row
+       * @param seqPos - Residue of that row, 1-based
+       * @param structureId - Which structure, when the row maps onto several
+       */
+      structureResidue(
+        rowName: string,
+        seqPos: number,
+        structureId?: string,
+      ): StructureResidue | undefined {
+        const hits: StructureResidue[] = []
+        for (const mapping of this.usableResidueMappings) {
+          if (mapping.row !== rowName) {
+            continue
+          }
+          if (
+            structureId !== undefined &&
+            mapping.structure.id !== structureId
+          ) {
+            continue
+          }
+          const segment = mapping.segments.find(
+            seg => seqPos >= seg.rowStart && seqPos <= seg.rowEnd,
           )
+          if (segment) {
+            const position = segment.structStart + (seqPos - segment.rowStart)
+            hits.push({
+              structure: mapping.structure,
+              position,
+              observed: !inRanges(mapping.unobserved, position),
+            })
+          }
+        }
+        return hits.length === 1 ? hits[0] : undefined
+      },
 
-          const anchoredScrollY = offsetY - rowInView * self.rowHeight
-          // maxScrollY is -(totalHeight - visibleMsaHeight) when the alignment
-          // overflows, so -maxScrollY is exactly that overflow past the
-          // scrollable MSA viewport (0 when it fits)
-          const overflow = Math.max(0, -self.maxScrollY)
-          const visibleHeight = self.totalHeight - overflow
-          const topBias =
-            visibleHeight > 0 ? clamp(1 - overflow / visibleHeight, 0, 1) : 1
-          self.scrollY = clamp(
-            anchoredScrollY * (1 - topBias),
-            self.maxScrollY,
-            0,
+      /**
+       * #method
+       * The row residue a structure residue is, the same lookup backwards, and
+       * refusing on the same terms. `asymId` picks between mappings onto the
+       * same entry, which a homodimer -- two rows, two chains, one id -- always
+       * needs; without it such a lookup is ambiguous and gets nothing.
+       *
+       * @param structureId - The structure's id, as the mapping names it
+       * @param position - Residue of that structure, 1-based label_seq_id
+       * @param asymId - Which chain, when the id alone is ambiguous
+       */
+      rowResidue(
+        structureId: string,
+        position: number,
+        asymId?: string,
+      ): RowResidue | undefined {
+        const hits: RowResidue[] = []
+        for (const mapping of this.usableResidueMappings) {
+          if (mapping.structure.id !== structureId) {
+            continue
+          }
+          if (asymId !== undefined && mapping.structure.asymId !== asymId) {
+            continue
+          }
+          const segment = mapping.segments.find(
+            seg => position >= seg.structStart && position <= seg.structEnd,
           )
-        })
+          if (segment) {
+            hits.push({
+              rowName: mapping.row,
+              seqPos: segment.rowStart + (position - segment.structStart),
+            })
+          }
+        }
+        return hits.length === 1 ? hits[0] : undefined
+      },
+    }))
+
+    .views(self => ({
+      /**
+       * #getter
+       * the vertical space the alignment rows actually get: the widget height
+       * less everything stacked above and below them -- the header, the tracks,
+       * and the minimap when the columns overflow. Every consumer wants this
+       * same subtraction, so there is one of it: blocksY, maxScrollY, the
+       * vertical scrollbar and fitVertically all read it, and a second getter
+       * that forgot the tracks is what put the last rows out of reach.
+       */
+      get msaAreaHeight() {
+        return (
+          self.height -
+          (self.showHorizontalScrollbar ? self.minimapHeight : 0) -
+          self.headerHeight -
+          this.totalTrackAreaHeight
+        )
+      },
+      /**
+       * #getter
+       * total height of track area (px)
+       */
+      get totalTrackAreaHeight() {
+        return sum(self.turnedOnTracks.map(r => r.model.height))
+      },
+      /**
+       * one representative annotation per accession, which is what the legend,
+       * the filter dialog and the palettes key off
+       */
+      get annotationTypes() {
+        // first occurrence wins. The representative supplies only the name,
+        // description and -- for ordinal segments -- the start that orders
+        // them, and those agree across an accession's instances
+        const types = new Map<string, Annotation>()
+        for (const annot of self.annotations) {
+          if (!types.has(annot.accession)) {
+            types.set(annot.accession, annot)
+          }
+        }
+        return types
+      },
+      get filteredAnnotations() {
+        return self.annotations.filter(
+          r => !self.turnedOffFeatures.get(r.accession),
+        )
+      },
+      get annotationsByRow() {
+        return groupBy(this.filteredAnnotations, r => r.id)
       },
+    }))
+    .views(self => ({
       /**
-       * #action
+       * #getter
        */
-      doScrollY(deltaY: number) {
-        this.setScrollY(self.scrollY + deltaY)
+      get showVerticalScrollbar() {
+        return overflows(self.totalHeight, self.msaAreaHeight)
       },
-
+    }))
+    .views(self => ({
       /**
-       * #action
-       * set scroll Y-offset (px), clamped to keep the alignment in view
+       * #getter
        */
-      setScrollY(n: number) {
-        self.scrollY = clamp(n, self.maxScrollY, 0)
+      get dataInitialized() {
+        // truthiness, not `!== ''`: these are types.maybe, and DataModel's
+        // postProcessSnapshot drops a document over 50kb, so a restored session
+        // that inlined a large alignment comes back `undefined` here -- which
+        // `!== ''` reads as initialized and renders an empty view instead of
+        // the import form
+        return !!(self.data.msa || self.data.tree) && !self.error
       },
-
       /**
-       * #action
-       * Set the overlay annotations and reveal the overlay in a single step (an
-       * empty list clears both). Every source funnels through here after its
-       * own adapter has flattened it: InterProScan, GFF, user uploads, NCBI CDD.
+       * #getter
        */
-      setAnnotations(annotations: Annotation[]) {
-        self.annotations = annotations
-        self.setShowDomains(annotations.length > 0)
+      get blocksX() {
+        return calculateBlocks({
+          viewportSize: self.msaAreaWidth,
+          viewportPos: -self.scrollX,
+          blockSize: self.blockSize,
+          mapSize: self.totalWidth,
+        })
       },
-
       /**
-       * #action
-       * set the overlay from raw InterProScan results keyed by row name. Kept
-       * for downstream plugins that hold the EBI wire format; new code should
-       * adapt to Annotation[] and call setAnnotations.
+       * #getter
        */
-      setDomains(data?: Record<string, InterProScanResults>) {
-        this.setAnnotations(data ? interProScanToAnnotations(data) : [])
-      },
-
-      applyGFFText(gffText: string) {
-        this.setAnnotations(gffToAnnotations(parseGFF(gffText)))
+      get blocksY() {
+        return calculateBlocks({
+          viewportSize: self.msaAreaHeight,
+          viewportPos: -self.scrollY,
+          blockSize: self.blockSize,
+          mapSize: self.totalHeight,
+        })
       },
-
+    }))
+    .views(self => ({
       /**
-       * #action
+       * #getter
        */
-      doScrollX(deltaX: number) {
-        this.setScrollX(self.scrollX + deltaX)
+      get blocks2d() {
+        return self.blocksY.flatMap(by =>
+          self.blocksX.map(bx => [bx, by] as const),
+        )
       },
 
       /**
-       * #action
+       * #getter
        */
-      setScrollX(n: number) {
-        self.scrollX = clamp(n, self.maxScrollX, 0)
+      get isLoading() {
+        return self.loadingMSA || self.loadingTree
       },
-
       /**
-       * #action
+       * #getter
        */
-      setColumnTracks(tracks: ColumnTrackSpec[]) {
-        self.columnTracks.replace(tracks)
+      get maxScrollX() {
+        return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0)
       },
       /**
-       * #action
+       * #getter
+       * most-negative allowed scrollY, keeping the last row in view rather than
+       * letting the whole alignment scroll off the top.
        */
-      toggleTrack(id: string) {
-        // the stored value is "is off", so the current shown state is exactly
-        // what the flipped entry should hold
-        self.turnedOffTracks.set(id, !trackIsOff(self.turnedOffTracks, id))
+      get maxScrollY() {
+        return Math.min(-self.totalHeight + self.msaAreaHeight, 0)
       },
+    }))
+    .actions(self => ({
       /**
        * #action
        */
-      setStatus(status?: { msg: string; url?: string; onCancel?: () => void }) {
-        self.status = status
+      setDrawMsaLetters(arg: boolean) {
+        self.drawMsaLetters = arg
       },
-    }))
-    .views(self => ({
+
       /**
-       * #getter
+       * #action
        */
-      get labelWidthMap() {
-        const { showTreeText, leaves, treeMetadata } = self
-        // gated on the same condition the renderer draws labels under, so the
-        // gutter labelsWidth reserves and the labels actually drawn cannot
-        // disagree -- and so turning labels off hands their space to the tree.
-        // Measured at a fixed reference size and scaled by labelWidthScale:
-        // re-measuring every leaf on every vertical-zoom frame cost ~200ms on a
-        // 50k-leaf tree
-        return showTreeText
-          ? new Map(
-              leaves.map(node => {
-                const { name } = node.data
-                // `||`, matching renderTreeLabels: an empty genome falls back
-                // to the row name, and measuring '' would size the gutter (and
-                // the label's click target) to nothing
-                const displayName = treeMetadata[name]?.genome || name
-                return [
-                  name,
-                  measureTextCanvas(displayName, labelReferenceFontSize),
-                ] as const
-              }),
-            )
-          : new Map<string, number>()
+      setScrollZoom(arg: boolean) {
+        self.scrollZoom = arg
       },
 
       /**
-       * #getter
-       * factor turning a labelWidthMap entry into its width at the current
-       * font size
+       * #action
+       * set hovered tree node and its descendants
        */
-      get labelWidthScale() {
-        return self.fontSize / labelReferenceFontSize
+      setHoveredTreeNode(nodeId?: string) {
+        // the tree's mousemove handler calls this on every event, and both the
+        // lookup and the write are expensive: `find` walks the whole hierarchy,
+        // and a fresh object here invalidates hoveredRowIndices and redraws the
+        // tree and MSA overlays. Re-hovering the same node is the common case
+        if (nodeId === self.hoveredTreeNode?.nodeId) {
+          return
+        }
+        if (!nodeId) {
+          self.hoveredTreeNode = undefined
+          return
+        }
+        const node = find(self.hierarchy, n => n.data.id === nodeId)
+        self.hoveredTreeNode = node
+          ? {
+              nodeId,
+              descendantNames: leaves(node).map(leaf => leaf.data.name),
+            }
+          : undefined
       },
 
-      get labelsWidth() {
-        // a loop, not Math.max(...widths.values()): spreading a map of every
-        // leaf passes one argument per row, and the argument limit is somewhere
-        // around 125k -- so the bundled 230k-tip COVID tree threw
-        // "RangeError: Maximum call stack size exceeded" out of a getter the
-        // treeWidth autorun reads on load
-        let max = 0
-        for (const width of this.labelWidthMap.values()) {
-          if (width > max) {
-            max = width
-          }
+      /**
+       * #action
+       * Calculate a neighbor joining tree from the current MSA using BLOSUM62
+       * distances. Refuses above `maxNeighborJoiningRows`: the join loop is
+       * cubic and runs on the main thread, so 800 rows is a ten-second freeze
+       * with no progress and no cancel, and a tree that size wants a tool built
+       * for it anyway.
+       */
+      calculateNeighborJoiningTreeFromMSA() {
+        // every sequence in the alignment, not the rows on screen: a collapsed
+        // clade is a display state, and building the tree from what it leaves
+        // showing drops the sequences it hides out of the result
+        const rows = [...self.rowMap]
+        if (rows.length < 2) {
+          throw new Error('Need at least 2 sequences to build a tree')
         }
-        return max * this.labelWidthScale
+        if (rows.length > maxNeighborJoiningRows) {
+          throw new Error(
+            `Neighbor joining here is capped at ${maxNeighborJoiningRows} sequences and this alignment has ${rows.length}. Build the tree with FastTree or IQ-TREE and open it alongside the alignment: https://gmod.org/JBrowseMSA/tutorials/protein_family`,
+          )
+        }
+        this.replaceTree(calculateNeighborJoiningTree(rows))
       },
 
       /**
-       * #getter
+       * #action
+       * swap in a different tree over the same alignment. Node ids are derived
+       * from the path (node-0-0-1), so a `collapsed` or `showOnly` id held over
+       * from the old tree matches a real node in the new one and folds whatever
+       * happens to sit there -- the ids go with the tree they name.
        */
-      get secondaryStructureConsensus() {
-        return self.MSA?.secondaryStructureConsensus
+      replaceTree(newick: string) {
+        transaction(() => {
+          self.collapsed.clear()
+          self.setShowOnly(undefined)
+          self.setTree(newick)
+        })
       },
 
       /**
-       * #getter
+       * #action
+       * restore the default column width and row height
        */
-      get seqConsensus() {
-        return self.MSA?.seqConsensus
+      resetZoom() {
+        self.setColWidth(defaultColWidth)
+        self.setRowHeight(defaultRowHeight)
       },
-
       /**
-       * #getter
+       * #action
        */
-      get adapterTrackModels(): BasicTrack[] {
-        const { rowHeight, MSA, hideGapsEffective, blanks } = self
-        const tracks = MSA?.tracks ?? []
-        return tracks
-          .filter(t => !!t.data)
-          .map(t => ({
-            model: {
-              ...t,
-              kind: 'text' as const,
-              data: hideGapsEffective ? skipBlanks(blanks, t.data!) : t.data,
-              height: rowHeight,
-            },
-            ReactComponent: TrackBlocks,
-          }))
+      zoomOutHorizontal() {
+        self.colWidth = Math.max(minColWidth, Math.floor(self.colWidth * 0.75))
+        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
       },
-
       /**
-       * #getter
-       * a data track's values or string, projected from its row's residues
-       * onto alignment columns when it names a row
+       * #action
        */
-      get columnTrackContent() {
-        const { MSA, blanks, hideGapsEffective } = self
-        const width = MSA?.getWidth() ?? 0
-        const project = <T>(track: ColumnTrackSpec, items: T[], fill: T) => {
-          if (!track.row) {
-            return items
-          }
-          const out = Array.from({ length: width }, () => fill)
-          const index = self.seqPosGlobalColIndex.get(track.row)
-          items.forEach((item, seqPos) => {
-            const col = index?.[seqPos]
-            if (col !== undefined) {
-              out[col] = item
-            }
-          })
-          return out
-        }
-        const skip = <T>(items: T[]) =>
-          hideGapsEffective ? dropBlanks(blanks, items) : items
-        return new Map<string, { values?: number[]; data?: string }>(
-          self.columnTracks.map(track => {
-            if (track.kind === 'bar') {
-              const max = track.max ?? 1
-              const values = skip(project(track, track.values ?? [], 0)).map(
-                v => Math.min(1, Math.max(0, v / max)),
-              )
-              return [track.id, { values }] as const
-            }
-            const data = skip(project(track, (track.data ?? '').split(''), ' '))
-            return [track.id, { data: data.join('') }] as const
-          }),
-        )
+      zoomInHorizontal() {
+        self.colWidth = Math.min(maxCellSize, Math.ceil(self.colWidth * 1.5))
+        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
       },
       /**
-       * #getter
+       * #action
        */
-      get columnTrackModels(): BasicTrack[] {
-        return self.columnTracks.map(track => ({
-          model: {
-            id: track.id,
-            name: track.name,
-            kind: track.kind,
-            height:
-              track.height ??
-              (track.kind === 'bar'
-                ? self.conservationTrackHeight
-                : self.rowHeight),
-            barColor: track.color,
-            customColorScheme: track.colors,
-            data: this.columnTrackContent.get(track.id)?.data,
-          },
-          ReactComponent: TrackBlocks,
-        }))
+      zoomInVertical() {
+        self.rowHeight = Math.min(maxCellSize, Math.ceil(self.rowHeight * 1.5))
+      },
+      /**
+       * #action
+       */
+      zoomOutVertical() {
+        self.rowHeight = Math.max(
+          minRowHeight,
+          Math.floor(self.rowHeight * 0.75),
+        )
       },
       /**
-       * #getter
+       * #action
        */
-      get tracks(): BasicTrack[] {
-        const conservationTrack = {
-          id: 'conservation',
-          name: 'Conservation',
-          kind: 'bar' as const,
-          height: self.conservationTrackHeight,
-          barColor: 'gray',
-        }
-        const propertyConservationTrack = {
-          id: 'property-conservation',
-          name: 'Property conservation',
-          kind: 'bar' as const,
-          height: self.conservationTrackHeight,
-          barColor: '#6a51a3',
-        }
-        const sequenceLogoTrack = {
-          id: 'sequence-logo',
-          name: 'Sequence logo',
-          kind: 'logo' as const,
-          height: self.sequenceLogoTrackHeight,
-        }
-        return [
-          ...this.adapterTrackModels,
-          ...this.columnTrackModels,
-          ...[
-            conservationTrack,
-            ...(self.sequenceType === 'amino'
-              ? [propertyConservationTrack]
-              : []),
-            sequenceLogoTrack,
-          ].map(model => ({ model, ReactComponent: TrackBlocks })),
-        ]
+      zoomIn() {
+        transaction(() => {
+          this.zoomInHorizontal()
+          this.zoomInVertical()
+        })
       },
-
       /**
-       * #getter
+       * #action
        */
-      get turnedOnTracks() {
-        return this.tracks.filter(
-          f => !trackIsOff(self.turnedOffTracks, f.model.id),
-        )
+      zoomOut() {
+        transaction(() => {
+          this.zoomOutHorizontal()
+          this.zoomOutVertical()
+        })
       },
-
       /**
-       * #getter
+       * #action
+       * Smoothly zoom by a continuous scaleFactor. The column under the cursor
+       * (offsetX/offsetY, px relative to the MSA area) stays anchored
+       * horizontally. Vertically the anchor is biased toward the top: when the
+       * alignment nearly fits the viewport, snap to y=0 rather than pinning a
+       * random row under the cursor, with the bias fading out as the alignment
+       * grows taller than the viewport (where cursor-anchoring is useful).
+       * Drives wheel/trackpad-pinch zoom.
        */
-      get showHorizontalScrollbar() {
-        return self.msaAreaWidth < self.totalWidth
-      },
+      zoomToPos(scaleFactor: number, offsetX: number, offsetY: number) {
+        transaction(() => {
+          const colInView = (-self.scrollX + offsetX) / self.colWidth
+          const rowInView = (-self.scrollY + offsetY) / self.rowHeight
+          self.colWidth = clamp(
+            self.colWidth * scaleFactor,
+            minColWidth,
+            maxCellSize,
+          )
+          self.rowHeight = clamp(
+            self.rowHeight * scaleFactor,
+            minRowHeight,
+            maxCellSize,
+          )
+          self.scrollX = clamp(
+            offsetX - colInView * self.colWidth,
+            self.maxScrollX,
+            0,
+          )
 
+          const anchoredScrollY = offsetY - rowInView * self.rowHeight
+          // maxScrollY is -(totalHeight - visibleMsaHeight) when the alignment
+          // overflows, so -maxScrollY is exactly that overflow past the
+          // scrollable MSA viewport (0 when it fits)
+          const overflow = Math.max(0, -self.maxScrollY)
+          const visibleHeight = self.totalHeight - overflow
+          const topBias =
+            visibleHeight > 0 ? clamp(1 - overflow / visibleHeight, 0, 1) : 1
+          self.scrollY = clamp(
+            anchoredScrollY * (1 - topBias),
+            self.maxScrollY,
+            0,
+          )
+        })
+      },
       /**
-       * #method
-       * Return a row-specific letter at a visible column, or undefined if gap.
-       *
-       * @param rowName - The name of the row
-       * @param visibleCol - The visible column index (what the user sees on screen)
-       * @returns The letter at that position, or undefined if it's a gap
+       * #action
        */
-      visibleColToRowLetter(rowName: string, visibleCol: number) {
-        const { rowMap, blanks } = self
-        return rowMap.get(rowName)?.[visibleColToGlobalCol(blanks, visibleCol)]
+      doScrollY(deltaY: number) {
+        this.setScrollY(self.scrollY + deltaY)
       },
 
       /**
-       * #method
-       * Convert a visible column to a row-specific sequence position (0-based).
-       * Returns undefined if the position is a gap in the sequence.
-       *
-       * CROSS-REPO CONTRACT: this and the sibling coordinate converters
-       * (seqPosToVisibleCol, globalColToVisibleCol, seqPosToGlobalCol) are used
-       * by jbrowse-plugin-protein3d to translate between alignment columns and
-       * structure/sequence residue positions across gaps. Keep them stable.
-       *
-       * @param rowName - The name of the row
-       * @param visibleCol - The visible column index
-       * @returns The sequence position (0-based), or undefined if it's a gap
+       * #action
+       * set scroll Y-offset (px), clamped to keep the alignment in view
        */
-      visibleColToSeqPos(rowName: string, visibleCol: number) {
-        return visibleColToSeqPosForRow({
-          rowName,
-          visibleCol,
-          rowMap: self.rowMap,
-          blanks: self.blanks,
-        })
+      setScrollY(n: number) {
+        self.scrollY = clamp(n, self.maxScrollY, 0)
       },
 
       /**
-       * #method
-       * Convert a visible column to a row-specific sequence position (1-based).
-       * Returns undefined if the position is a gap in the sequence.
+       * #action
+       * Set the overlay annotations (an empty list clears them). Every source
+       * funnels through here after its own adapter has flattened it:
+       * InterProScan, GFF, user uploads, NCBI CDD.
        *
-       * @param rowName - The name of the row
-       * @param visibleCol - The visible column index
-       * @returns The sequence position (1-based), or undefined if it's a gap
+       * It does not touch `showDomains`. Loading used to force the overlay on,
+       * and since a restored snapshot loads its GFF again on the way in, a link
+       * shared with the overlay hidden reopened with it drawn.
        */
-      visibleColToSeqPosOneBased(rowName: string, visibleCol: number) {
-        const val = this.visibleColToSeqPos(rowName, visibleCol)
-        return val !== undefined ? val + 1 : undefined
+      setAnnotations(annotations: Annotation[]) {
+        self.annotations = annotations
       },
 
       /**
-       * #method
-       * Convert a global column index to a visible column index.
-       * Returns undefined if the column is hidden (in blanks).
-       * This is the inverse of visibleColToGlobalCol.
-       *
-       * @param globalCol - The global column index in the full MSA
-       * @returns The visible column index, or undefined if the column is hidden
+       * #action
+       * set the overlay from raw InterProScan results keyed by row name. Kept
+       * for downstream plugins that hold the EBI wire format; new code should
+       * adapt to Annotation[] and call setAnnotations.
        */
-      globalColToVisibleCol(globalCol: number) {
-        const { blanks, hideGapsEffective } = self
-        if (!hideGapsEffective) {
-          return globalCol
-        }
-        return globalColToVisibleCol(blanks, globalCol)
+      setDomains(data?: Record<string, InterProScanResults>) {
+        this.setAnnotations(data ? interProScanToAnnotations(data) : [])
+      },
+
+      applyGFFText(gffText: string) {
+        this.setAnnotations(gffToAnnotations(parseGFF(gffText)))
       },
 
       /**
-       * #method
-       * Convert a sequence position (ungapped) to a global column index.
-       *
-       * @param rowName - The name of the row
-       * @param seqPos - The sequence position (0-based, ungapped)
-       * @returns The global column index in the full MSA
+       * #action
        */
-      seqPosToGlobalCol(rowName: string, seqPos: number) {
-        const seq = self.rowMap.get(rowName)
-        if (seq === undefined) {
-          return 0
-        }
-        const col = self.seqPosGlobalColIndex.get(rowName)?.[seqPos]
-        // past the end of the ungapped sequence: 0 for the degenerate all-gap
-        // row, otherwise one past the last column
-        return col ?? (seqPos === 0 ? 0 : seq.length)
+      doScrollX(deltaX: number) {
+        this.setScrollX(self.scrollX + deltaX)
       },
 
       /**
-       * #method
-       * Convert a sequence position (ungapped) directly to a visible column index.
-       * This combines seqPosToGlobalCol and globalColToVisibleCol.
-       *
-       * @param rowName - The name of the row
-       * @param seqPos - The sequence position (0-based, ungapped)
-       * @returns The visible column index, or undefined if the column is hidden
+       * #action
        */
-      seqPosToVisibleCol(rowName: string, seqPos: number) {
-        const globalCol = this.seqPosToGlobalCol(rowName, seqPos)
-        return this.globalColToVisibleCol(globalCol)
+      setScrollX(n: number) {
+        self.scrollX = clamp(n, self.maxScrollX, 0)
       },
-    }))
 
-    .views(self => ({
       /**
-       * #getter
-       * widget width minus the tree area gives the space for the MSA
+       * #action
        */
-      get msaAreaHeight() {
-        return (
-          self.height -
-          (self.showHorizontalScrollbar ? self.minimapHeight : 0) -
-          self.headerHeight
-        )
+      setColumnTracks(tracks: ColumnTrackSpec[]) {
+        self.columnTracks.replace(tracks)
       },
       /**
-       * #getter
-       * total height of track area (px)
+       * #action
+       * replace the alignment<->structure correspondence (see docs/layers.md)
        */
-      get totalTrackAreaHeight() {
-        return sum(self.turnedOnTracks.map(r => r.model.height))
+      setResidueMappings(mappings: ResidueMapping[]) {
+        self.residueMappings.replace(mappings)
       },
       /**
-       * one representative annotation per accession, which is what the legend,
-       * the filter dialog and the palettes key off
+       * #action
        */
-      get annotationTypes() {
-        // first occurrence wins. The representative supplies only the name,
-        // description and -- for ordinal segments -- the start that orders
-        // them, and those agree across an accession's instances
-        const types = new Map<string, Annotation>()
-        for (const annot of self.annotations) {
-          if (!types.has(annot.accession)) {
-            types.set(annot.accession, annot)
-          }
-        }
-        return types
-      },
-      get filteredAnnotations() {
-        return self.annotations.filter(r =>
-          self.featureFilters.get(r.accession),
+      toggleTrack(id: string) {
+        // the stored value is "is off", so the current shown state is exactly
+        // what the flipped entry should hold
+        const defaultOff = self.MSA?.tracks.find(t => t.id === id)?.defaultOff
+        self.turnedOffTracks.set(
+          id,
+          !trackIsOff(self.turnedOffTracks, id, defaultOff),
         )
       },
-      get annotationsByRow() {
-        return groupBy(this.filteredAnnotations, r => r.id)
-      },
-    }))
-    .views(self => ({
       /**
-       * #getter
+       * #action
        */
-      get showVerticalScrollbar() {
-        return self.msaAreaHeight < self.totalHeight
+      setStatus(status?: { msg: string; onCancel?: () => void }) {
+        self.status = status
       },
     }))
     .views(self => ({
@@ -2023,7 +2671,7 @@ function stateModelFactory() {
        */
       get visibleDomainTypes() {
         return this.categoricalDomainTypes
-          .filter(d => self.featureFilters.get(d.accession))
+          .filter(d => !self.turnedOffFeatures.get(d.accession))
           .toSorted((a, b) => a.start - b.start)
       },
 
@@ -2053,15 +2701,14 @@ function stateModelFactory() {
               // gap run -- and a residue whose column is itself hidden
               // collapses onto the neighbouring boundary instead of dropping
               // the band. A band whose every column is hidden spans nothing
-              // and is left out.
-              const startCol = visibleColsBefore(
-                blanks,
-                self.seqPosToGlobalCol(name, annotation.start - 1),
-              )
-              const endCol = visibleColsBefore(
-                blanks,
-                self.seqPosToGlobalCol(name, annotation.end - 1) + 1,
-              )
+              // and is left out, as is one naming a row the alignment lacks.
+              const start = self.seqPosToGlobalCol(name, annotation.start - 1)
+              const end = self.seqPosToGlobalCol(name, annotation.end - 1)
+              if (start === undefined || end === undefined) {
+                return undefined
+              }
+              const startCol = visibleColsBefore(blanks, start)
+              const endCol = visibleColsBefore(blanks, end + 1)
               return endCol > startCol
                 ? { annotation, startCol, endCol }
                 : undefined
@@ -2099,14 +2746,19 @@ function stateModelFactory() {
        * domain annotations under the mouse, hit-tested against the exact visible
        * column span each box is drawn at (so it matches the overlay across gaps)
        */
-      get mouseOverDomains() {
+      get mouseOverDomains(): Annotation[] {
         const { mouseCol } = self
         const name = self.mouseOverRowName
-        return name !== undefined && mouseCol !== undefined
-          ? (this.domainBands.get(name) ?? [])
-              .filter(b => mouseCol >= b.startCol && mouseCol < b.endCol)
-              .map(b => b.annotation)
-          : []
+        if (name === undefined || mouseCol === undefined) {
+          return noDomains
+        }
+        const hits = (this.domainBands.get(name) ?? [])
+          .filter(b => mouseCol >= b.startCol && mouseCol < b.endCol)
+          .map(b => b.annotation)
+        // the shared empty array, so moving the mouse across an alignment with
+        // no annotations does not hand every canvas block a new value to
+        // re-render on
+        return hits.length > 0 ? hits : noDomains
       },
 
       /**
@@ -2166,41 +2818,46 @@ function stateModelFactory() {
        * is dropped. Row names that match no row are ignored.
        */
       get resolvedHighlights(): ResolvedHighlight[] {
-        const { blanks, rowNamesSet, rowMap } = self
+        const { blanks, rowNamesSet, transientHighlights } = self
         const toVisible = (globalCol: number) => {
           const visible = self.globalColToVisibleCol(globalCol)
           return visible ?? visibleColsBefore(blanks, globalCol)
         }
-        return self.highlights.flatMap(
-          ({ row, rows, start, end, label, color }) => {
-            const base = { label, color }
-            if (rows) {
-              const rowIndices = rows
-                .map(name => rowNamesSet.get(name))
-                .filter(notEmpty)
-              return rowIndices.length ? [{ ...base, rowIndices }] : []
-            }
-            if (start === undefined || end === undefined) {
+        // the document's own highlights first, then what each owner is showing
+        // right now, so a hover draws over a persisted band rather than under it
+        const all = [
+          ...self.highlights,
+          ...Object.values(transientHighlights).flat(),
+        ]
+        return all.flatMap(({ row, rows, start, end, label, color }) => {
+          const base = { label, color }
+          if (rows) {
+            const rowIndices = rows
+              .map(name => rowNamesSet.get(name))
+              .filter(notEmpty)
+            return rowIndices.length ? [{ ...base, rowIndices }] : []
+          }
+          if (start === undefined || end === undefined) {
+            return []
+          }
+          let startGlobal = start - 1
+          let endGlobal = end - 1
+          if (row !== undefined) {
+            const rowStart = self.seqPosToGlobalCol(row, start - 1)
+            const rowEnd = self.seqPosToGlobalCol(row, end - 1)
+            if (rowStart === undefined || rowEnd === undefined) {
               return []
             }
-            let startGlobal = start - 1
-            let endGlobal = end - 1
-            if (row !== undefined) {
-              if (!rowMap.has(row)) {
-                return []
-              }
-              startGlobal = self.seqPosToGlobalCol(row, start - 1)
-              endGlobal = self.seqPosToGlobalCol(row, end - 1)
-            }
-            const startCol = toVisible(startGlobal)
-            const endVisible = self.globalColToVisibleCol(endGlobal)
-            const endCol =
-              endVisible ?? visibleColsBefore(blanks, endGlobal) - 1
-            return startCol <= endCol
-              ? [{ ...base, startCol, endCol, rowIndices: [] }]
-              : []
-          },
-        )
+            startGlobal = rowStart
+            endGlobal = rowEnd
+          }
+          const startCol = toVisible(startGlobal)
+          const endVisible = self.globalColToVisibleCol(endGlobal)
+          const endCol = endVisible ?? visibleColsBefore(blanks, endGlobal) - 1
+          return startCol <= endCol
+            ? [{ ...base, startCol, endCol, rowIndices: [] }]
+            : []
+        })
       },
 
       /**
@@ -2264,12 +2921,24 @@ function stateModelFactory() {
       setConservationTrackHeight(arg: number) {
         self.conservationTrackHeight = arg
       },
+      /**
+       * #action
+       */
+      setColumnTrackHeight(id: string, height: number) {
+        self.columnTrackHeights = { ...self.columnTrackHeights, [id]: height }
+      },
       /**
        * #action
        */
       setSequenceLogoTrackHeight(arg: number) {
         self.sequenceLogoTrackHeight = arg
       },
+      /**
+       * #action
+       */
+      setArcTrackHeight(arg: number) {
+        self.arcTrackHeight = arg
+      },
       /**
        * #action
        * Return to the import form: every property off `preservedOnReset`
@@ -2278,6 +2947,9 @@ function stateModelFactory() {
        * reach are cleared by hand.
        */
       reset() {
+        self.resetCount++
+        self.clearWarnings()
+        self.setStatus(undefined)
         applySnapshot(
           self,
           Object.fromEntries(
@@ -2289,6 +2961,7 @@ function stateModelFactory() {
         self.setError(undefined)
         self.setAnnotations([])
         self.setHighlightedColumns(undefined)
+        self.transientHighlights = {}
         self.setMousePos(undefined, undefined)
         self.setMouseClickPos(undefined, undefined)
         self.setHoveredTreeNode(undefined)
@@ -2302,21 +2975,35 @@ function stateModelFactory() {
         const blob = new Blob([html], { type: 'image/svg+xml' })
         saveAs(blob, exportFileName(self.msaFilehandle, 'svg'))
       },
-      initFilter(arg: string) {
-        if (!self.featureFilters.has(arg)) {
-          self.featureFilters.set(arg, true)
+      /**
+       * #action
+       * draw this annotation type, or stop drawing it. Only the "stop" is
+       * recorded -- see `turnedOffFeatures`
+       */
+      setFilter(accession: string, shown: boolean) {
+        if (shown) {
+          self.turnedOffFeatures.delete(accession)
+        } else {
+          self.turnedOffFeatures.set(accession, true)
         }
       },
-      setFilter(arg: string, flag: boolean) {
-        self.featureFilters.set(arg, flag)
-      },
 
       /**
        * #action
        */
       fit() {
-        this.fitVertically()
-        this.fitHorizontally()
+        // Each direction's viewport depends on the other's result: fitting the
+        // rows while the columns still overflow measures against a height the
+        // minimap is taking, and fitting the columns while the rows still
+        // overflow measures against a width the vertical scrollbar is taking.
+        // A second pass measures against the geometry the first pass produced,
+        // which is the one the reader ends up looking at.
+        transaction(() => {
+          for (let pass = 0; pass < 2; pass++) {
+            this.fitHorizontally()
+            this.fitVertically()
+          }
+        })
       },
       /**
        * #action
@@ -2356,15 +3043,6 @@ function stateModelFactory() {
           self.setHighlightedColumns(self.highlightColumns)
         }
 
-        addDisposer(
-          self,
-          autorun(() => {
-            for (const key of self.annotationTypes.keys()) {
-              this.initFilter(key)
-            }
-          }),
-        )
-
         // track the live device pixel ratio so canvas backing stores re-scale
         // when the window moves between monitors or the browser zooms. The
         // matchMedia query is pinned to the current ratio, so each change
@@ -2395,41 +3073,62 @@ function stateModelFactory() {
          * Every loader carries a generation guard: the filehandle can change
          * mid-fetch (a second file picked while the first is still in flight),
          * and the slower earlier request must not clobber the data, status, or
-         * loading flag belonging to the newer one.
+         * loading flag belonging to the newer one. A superseded or cleared
+         * request is also aborted, rather than left downloading a file nothing
+         * is waiting for, and it gives back the status line it was writing --
+         * a reset() mid-download used to leave "Downloading file" and a Cancel
+         * button behind on the import form.
          *
          * `clearFilehandle` serves two purposes for the loaders that pass it.
          * A local file has no URL to refetch from, so the handle is dropped
          * once its bytes are in the model; and a fetch the user cancels drops
          * it too, returning the view to the import form rather than leaving a
          * stuck spinner.
+         *
+         * `what` names the layer in a failure message. An optional layer
+         * (annotations, row metadata) that fails to load is a warning: it is
+         * not worth replacing an alignment the reader is looking at with an
+         * error screen over a decorative file.
          */
         const loadOnFilehandleChange = ({
+          what,
           getFilehandle,
           onLoad,
           setLoading,
           clearFilehandle,
+          optional = false,
         }: {
+          what: string
           getFilehandle: () => FileLocationType | undefined
           onLoad: (text: string) => void
           setLoading?: (arg: boolean) => void
           clearFilehandle?: () => void
+          optional?: boolean
         }) => {
           let generation = 0
+          let cancelInFlight: (() => void) | undefined
+          addDisposer(self, () => {
+            cancelInFlight?.()
+          })
           addDisposer(
             self,
             autorun(async () => {
               const filehandle = getFilehandle()
-              // a cleared filehandle bumps the generation too, so a reset()
-              // mid-download invalidates the in-flight fetch instead of letting
-              // its onLoad land on the emptied model. That also orphans the
-              // invalidated run's `finally`, so the loading flag is cleared
-              // here on its behalf
               const current = ++generation
+              cancelInFlight?.()
+              cancelInFlight = undefined
               if (!filehandle) {
                 setLoading?.(false)
                 return
               }
-              const isCurrent = () => current === generation
+              const isCurrent = () => current === generation && isAlive(self)
+              const controller = new AbortController()
+              cancelInFlight = () => {
+                controller.abort()
+                if (isAlive(self)) {
+                  self.setStatus(undefined)
+                }
+              }
               try {
                 setLoading?.(true)
                 self.setError(undefined)
@@ -2440,6 +3139,7 @@ function stateModelFactory() {
                       self.setStatus(status)
                     }
                   },
+                  { controller },
                 )
                 if (isCurrent()) {
                   transaction(() => {
@@ -2455,11 +3155,16 @@ function stateModelFactory() {
                     clearFilehandle?.()
                   } else {
                     console.error(e)
-                    self.setError(e)
+                    if (optional) {
+                      self.addWarning(`The ${what} did not load: ${e}`)
+                    } else {
+                      self.setError(e)
+                    }
                   }
                 }
               } finally {
                 if (isCurrent()) {
+                  cancelInFlight = undefined
                   setLoading?.(false)
                 }
               }
@@ -2468,6 +3173,7 @@ function stateModelFactory() {
         }
 
         loadOnFilehandleChange({
+          what: 'tree',
           getFilehandle: () => self.treeFilehandle,
           onLoad: text => {
             self.setTree(text)
@@ -2483,13 +3189,20 @@ function stateModelFactory() {
         // treeMetadata is decorative and has no import-form step of its own, so
         // it keeps no loading flag and nothing to return to on cancel
         loadOnFilehandleChange({
+          what: 'row metadata',
+          optional: true,
           getFilehandle: () => self.treeMetadataFilehandle,
           onLoad: text => {
             self.setTreeMetadata(text)
           },
         })
 
-        // autorun parses inline gff text from data.gff
+        // autorun parses inline gff text from data.gff. Text that goes away
+        // takes its annotations with it -- setData with a new alignment and no
+        // gff used to leave the previous file's annotations drawn over it --
+        // while annotations a host set directly are left alone, which is why
+        // this tracks what it applied instead of reading the current list
+        let appliedGFF = false
         addDisposer(
           self,
           autorun(() => {
@@ -2497,19 +3210,29 @@ function stateModelFactory() {
             if (gffText) {
               try {
                 self.applyGFFText(gffText)
+                appliedGFF = true
               } catch (e) {
+                // a malformed overlay is not worth replacing the alignment
+                // with an error screen
                 console.error(e)
-                self.setError(e)
+                self.addWarning(`The annotations did not parse: ${e}`)
               }
+            } else if (appliedGFF) {
+              appliedGFF = false
+              self.setAnnotations([])
             }
           }),
         )
 
-        // gffFilehandle carries overlay annotations
+        // gffFilehandle carries overlay annotations. It loads into data.gff and
+        // the autorun above parses it, so there is one parse path whether the
+        // text arrived from a file or from a snapshot
         loadOnFilehandleChange({
+          what: 'annotations',
+          optional: true,
           getFilehandle: () => self.gffFilehandle,
           onLoad: text => {
-            self.applyGFFText(text)
+            self.setGFF(text)
           },
           clearFilehandle: () => {
             self.setGFFFilehandle(undefined)
@@ -2517,6 +3240,7 @@ function stateModelFactory() {
         })
 
         loadOnFilehandleChange({
+          what: 'alignment',
           getFilehandle: () => self.msaFilehandle,
           onLoad: text => {
             self.setMSA(text)
@@ -2580,15 +3304,27 @@ function stateModelFactory() {
           }),
         )
 
-        // autorun synchronizes treeWidth with treeAreaWidth
+        // treeWidth trails the tree area, less whatever the labels take out of
+        // it. A width that arrived with the snapshot is left alone until the
+        // tree area itself moves: a host that opens a view with a narrow tree
+        // beside wide labels -- jbrowse-plugin-msaview does, at treeWidth 100
+        // in a 200px area -- had its value overwritten on the first frame, and
+        // a restored session came back re-derived rather than as it was left.
+        // A getter cannot do this: labelsWidth is measured off the leaves,
+        // which are laid out against treeWidth.
+        let pinnedAreaWidth =
+          self.treeWidth === defaultTreeWidth ? undefined : self.treeAreaWidth
         addDisposer(
           self,
           autorun(() => {
+            const areaWidth = self.treeAreaWidth
+            const labelsWidth = self.labelsWidth
+            if (pinnedAreaWidth === areaWidth) {
+              return
+            }
+            pinnedAreaWidth = undefined
             self.setTreeWidth(
-              Math.max(
-                50,
-                self.treeAreaWidth - self.labelsWidth - 10 - self.marginLeft,
-              ),
+              Math.max(50, areaWidth - labelsWidth - 10 - self.marginLeft),
             )
           }),
         )