react-msaview 6.5.0 → 8.0.0

package/src/model.ts

@@ -6,9 +6,9 @@ import {
   applySnapshot,
   cast,
   getSnapshot,
+  isAlive,
   types,
 } from '@jbrowse/mobx-state-tree'
-import { colord } from 'colord'
 import { autorun, transaction } from 'mobx'
 import {
   generateNodeIds,
@@ -24,33 +24,50 @@ import { calculateBlocks } from './calculateBlocks.ts'
 import { clustalXColumnColors } from './clustalX.ts'
 import colorSchemes from './colorSchemes.ts'
 import { columnCountsFromRows, letterOfResidueSlot } from './columnCounts.ts'
+import { columnStats } from './columnStats.ts'
+import { packDomainLanes } from './components/msa/packDomainLanes.ts'
+import { visibleColRange } from './components/msa/visibleColRange.ts'
 import TrackBlocks from './components/tracks/TrackBlocks.tsx'
+import { cladeGutterWidth } from './components/tree/cladeBrackets.ts'
+import { scaleBarLength } from './components/tree/scaleBar.ts'
 import {
+  cladeHighlightAlpha,
+  cladeHighlightColor,
   defaultAllowedGappyness,
   defaultColWidth,
   defaultColorSchemeName,
   defaultCurrentAlignment,
   defaultDrawMsaLetters,
+  defaultFeaturePanelWidth,
   defaultHeight,
   defaultHideGaps,
   defaultRowHeight,
   defaultScrollX,
   defaultScrollY,
   defaultScrollZoom,
+  defaultScrollZoomAxis,
   defaultShowDomainLegend,
   defaultShowDomains,
   defaultSubFeatureRows,
+  defaultTreeWidth,
   labelReferenceFontSize,
   maxCellSize,
+  maxInlineSnapshotBytes,
+  maxNeighborJoiningRows,
   minColWidth,
   minLetterColWidth,
   minLetterRowHeight,
   minRowHeight,
+  rowPanelHeaderHeight,
+  rowTintAlpha,
+  scrollZoomAxes,
   segmentFeatureTypes,
   segmentShades,
+  treeScaleBarHeight,
 } from './constants.ts'
 import { createPaletteMap } from './createPaletteMap.ts'
 import { exportFileName } from './exportFileName.ts'
+import { featureField, featureName } from './featureFields.ts'
 import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
 import { flatToTree } from './flatToTree.ts'
 import {
@@ -59,12 +76,13 @@ import {
   collapse,
   collapsedSubtreeMaxLength,
   find,
-  findMaxBranchLen,
   forEachDescendant,
   hierarchy,
+  leafIndex,
   leaves,
-  links,
   maxLength,
+  mrca,
+  nodeCoveringRows,
   setBrLength,
   sort,
   sum as hierarchySum,
@@ -79,10 +97,11 @@ import { parseAsn1 } from './parseAsn1.ts'
 import { calculatePropertyConservation } from './propertyConservation.ts'
 import {
   globalColToVisibleCol,
+  seqPosOfGlobalCol,
   visibleColToGlobalCol,
-  visibleColToSeqPosForRow,
   visibleColsBefore,
 } from './rowCoordinateCalculations.ts'
+import { resolveScale } from './scales.ts'
 import { buildSeqPosIndex } from './seqPosToGlobalCol.ts'
 import { maxBitsFor } from './sequenceLogo.ts'
 import { stripDefault } from './stripDefault.ts'
@@ -90,22 +109,50 @@ import {
   computeRowInsertions,
   dropBlanks,
   len,
+  outlineColor,
   skipBlanks,
   transform,
+  withAlpha,
 } from './util.ts'
 import { saveAs } from './vendor/fileSaver.ts'
+import { parseWuss } from './wuss.ts'
 
+import type { ColumnStats } from './columnStats.ts'
+import type { ScrollZoomAxis } from './constants.ts'
 import type { HierarchyNode } from './hierarchy.ts'
 import type { ExportSvgOptions } from './renderToSvg.tsx'
+import type { ScaleSpec } from './scales.ts'
 import type {
   Annotation,
+  Arc,
   BasicTrack,
+  Cell,
+  Clade,
+  ResidueMappingProblem,
   ColumnTrackSpec,
   DomainBand,
+  Encoding,
+  EncodingChannel,
   Highlight,
+  Legend,
+  LegendEntry,
   NodeWithIds,
   NodeWithIdsAndLength,
+  Region,
+  ResidueMapping,
+  ResidueSegment,
+  ResolvedClade,
+  ResolvedEncoding,
   ResolvedHighlight,
+  ResolvedRowPanel,
+  RowFeaturesSpec,
+  RowPanelSpan,
+  RowPanelSpec,
+  RowResidue,
+  StructureResidue,
+  TrackKind,
+  UnshareableData,
+  Viewport,
 } from './types.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
 import type { Instance } from '@jbrowse/mobx-state-tree'
@@ -118,19 +165,204 @@ function parseTreeText(text: string) {
   return parseNewick(text.startsWith('SEQ') ? parseEmfTree(text).tree : text)
 }
 
-// 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'])
+// The height each kind draws at before the user drags a divider. A text track
+// is absent: it is one alignment row tall and follows rowHeight, so the zoom
+// controls already size it.
+export const defaultTrackHeights: Partial<Record<TrackKind, number>> = {
+  bar: 40,
+  // taller than a bar track: in a 40px stack of four residues each glyph is
+  // too short to identify. Twice the height of the tracks above it, so it
+  // starts hidden
+  logo: 80,
+  arc: 50,
+  ruler: 20,
+}
+
+// the kinds a divider resizes. The ruler is a fixed scale, and a text track
+// follows the vertical zoom.
+const resizableKinds = new Set<TrackKind>(['bar', 'logo', 'arc'])
+
+const defaultOffTracks = new Set(['sequence-logo', 'position-ruler'])
+
+// a data track carries its own height rather than its kind's, so its divider
+// resizes it alone
+const ownHeightKey = (id: string) => `own:${id}`
+
+// base-pair arcs: one color for nested helices, one for pseudoknots, which cross
+// them
+const HELIX_ARC = '#4e79a7'
+const PSEUDOKNOT_ARC = '#e15759'
+
+// the fill of a span under a scale that gives its value no color, such as a
+// gene a `map` over gene names leaves out
+const UNSCALED_FEATURE = '#d9d9d9'
+
+// the fraction of a span a following one may cover before it takes a lane of
+// its own in a `features` panel
+const laneOverlap = 0.1
+
+// a row panel's own width, or a default: the row height, which makes a strip
+// cell square, and a gene neighborhood's width for a features panel
+function rowPanelWidth(panel: RowPanelSpec, rowHeight: number) {
+  return (
+    panel.width ??
+    (panel.kind === 'features' ? defaultFeaturePanelWidth : rowHeight)
+  )
+}
+
+// the fill and outline of every feature in a list: its own GFF `color=` first,
+// then the scale an encoding resolves over one of its fields, then the
+// accession palette
+function featureColorMap(
+  annotations: Annotation[],
+  encoding:
+    | { field: string; colorOf: (value: string) => string | undefined }
+    | undefined,
+  fillPalette: Record<string, string>,
+) {
+  const strokes = new Map<string, string>()
+  const strokeOf = (fill: string) => {
+    const hit = strokes.get(fill)
+    if (hit !== undefined) {
+      return hit
+    }
+    const stroke = outlineColor(fill)
+    strokes.set(fill, stroke)
+    return stroke
+  }
+  return new Map(
+    annotations.map(annotation => {
+      const value = encoding
+        ? featureField(annotation, encoding.field)
+        : undefined
+      const fill =
+        annotation.color ??
+        (value === undefined ? undefined : encoding!.colorOf(value)) ??
+        (encoding ? UNSCALED_FEATURE : fillPalette[annotation.accession]!)
+      return [annotation, { fill, stroke: strokeOf(fill) }]
+    }),
+  )
+}
+
+// the text a label channel draws inside each span, for the features carrying
+// the field it names
+function featureLabelMap(annotations: Annotation[], field: string) {
+  const labels = new Map<Annotation, string>()
+  for (const annotation of annotations) {
+    const value = featureField(annotation, field)
+    if (value !== undefined) {
+      labels.set(annotation, value)
+    }
+  }
+  return labels
+}
+
+/**
+ * The spans a `features` panel draws, keyed by row name and measured in the
+ * panel's own pixels. `column` takes the bands the overlay draws, at the
+ * alignment's column width. `position` packs each row's features in its own
+ * residue positions, shifted by an `align` transform, and maps the extent they
+ * cover across every row onto the panel width, so a row with no alignment
+ * still has an x.
+ */
+function featurePanelSpans({
+  panel,
+  width,
+  rowHeight,
+  colWidth,
+  domainBands,
+  annotationsByRow,
+  shifts,
+}: {
+  panel: RowFeaturesSpec
+  width: number
+  rowHeight: number
+  colWidth: number
+  domainBands: Map<string, DomainBand[]>
+  annotationsByRow: Record<string, Annotation[]>
+  shifts: Map<string, number> | undefined
+}): Map<string, RowPanelSpan[]> {
+  if (panel.x === 'column') {
+    return new Map(
+      [...domainBands].map(([name, bands]) => [
+        name,
+        bands.map(band => ({
+          ...band,
+          xStart: band.startCol * colWidth,
+          xEnd: band.endCol * colWidth,
+        })),
+      ]),
+    )
+  }
+  const shifted = Object.entries(annotationsByRow).map(
+    ([name, annotations]) => {
+      const shift = shifts?.get(name) ?? 0
+      return [
+        name,
+        annotations.map(annotation => ({
+          annotation,
+          start: annotation.start - 1 + shift,
+          end: annotation.end + shift,
+        })),
+      ] as const
+    },
+  )
+  let min = Infinity
+  let max = -Infinity
+  for (const [, features] of shifted) {
+    for (const { start, end } of features) {
+      min = Math.min(min, start)
+      max = Math.max(max, end)
+    }
+  }
+  // the arrowhead on the rightmost feature reaches a row height past its end,
+  // so the extent maps onto the panel less that much
+  const drawable = Math.max(1, width - rowHeight)
+  const scale = max > min ? drawable / (max - min) : 0
+  // a lane opens where a span covers more than a tenth of the one before it,
+  // which keeps the genes of an operon on one lane: adjacent genes commonly
+  // share a few bases, and a stop codon overlapping the next start reads as a
+  // second lane over the whole row
+  return new Map(
+    shifted.map(([name, features]) => [
+      name,
+      packDomainLanes(
+        features.map(({ annotation, start, end }) => ({
+          annotation,
+          xStart: (start - min) * scale,
+          xEnd: (end - min) * scale,
+          startCol: start,
+          endCol: end - (end - start) * laneOverlap,
+        })),
+      ),
+    ]),
+  )
+}
+
+// a scale over the values a field takes across the features drawn
+function resolveFeatureScale(
+  field: string,
+  scale: ScaleSpec | undefined,
+  annotations: Annotation[],
+) {
+  return {
+    field,
+    ...resolveScale(
+      scale,
+      annotations.map(a => featureField(a, field)).filter(notEmpty),
+    ),
+  }
+}
 
 // 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 } : {}
 }
 
@@ -138,17 +370,13 @@ function smallColumnTracks(tracks?: ColumnTrackSpec[]) {
  * The snapshot properties reset() carries across a return to the import form:
  * display preferences and layout, nothing derived from the loaded file.
  *
- * reset() applies a default snapshot filtered to this list, so the list is the
- * whole decision: a property left off it resets to its default, a visible and
- * benign failure. The previous shape — a hand-maintained list of things to
- * CLEAR — failed in the dangerous direction: a forgotten property silently
- * carried the previous file's state into the next one, and because node ids
- * are path-derived (node-0-0-1), a stale `collapsed` or `showOnly` id matched
- * a real node in the new tree and folded it. Downstream composed properties
- * (e.g. the jbrowse plugin's) are not on the list, so they reset too.
+ * reset() applies a default snapshot filtered to this list, so any property
+ * left off it resets, including downstream composed ones (e.g. the jbrowse
+ * plugin's). Node ids are path-derived (node-0-0-1), so a carried-over
+ * `collapsed` or `showOnly` id would match a real node in the next tree and
+ * fold it.
  *
- * Exported for modelReset.test.ts, which checks that everything off this list
- * matches a freshly created model after reset().
+ * Exported for modelReset.test.ts.
  */
 export const preservedOnReset = new Set([
   'id',
@@ -156,6 +384,7 @@ export const preservedOnReset = new Set([
   'height',
   'drawMsaLetters',
   'scrollZoom',
+  'scrollZoomAxis',
   'bgColor',
   'colorSchemeName',
   'showColumnStats',
@@ -166,23 +395,207 @@ export const preservedOnReset = new Set([
   'showBranchLen',
   'drawTree',
   'drawNodeBubbles',
+  'drawNodeLabels',
+  'showTreeOverview',
+  'overviewHeight',
   'autoTreeAreaWidth',
   'turnedOffTracks',
+  'trackHeights',
   'hideGaps',
   'allowedGappyness',
   'subFeatureRows',
   'showDomainLegend',
 ])
 
-// `turnedOffTracks` records the user's explicit choices only: an id is absent
-// 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.
+// `turnedOffTracks` holds only the user's explicit choices, so a hidden-by-default
+// track writes nothing into the snapshot. A file-supplied track passes its own
+// `defaultOff`, since the count varies by file: a Pfam seed has 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) ?? (defaultOff || defaultOffTracks.has(id))
+}
+
+// shared empty results, so observers don't see a fresh [] as a change
+const noDomains: Annotation[] = []
+const noClades: ResolvedClade[] = []
+
+/**
+ * The rows a clade covers and the node an `mrca` names, or undefined when the
+ * clade does not resolve: a tip name the tree does not have or has twice, or a
+ * leaf count `tips` disagrees with. `index` and `rowNamesSet` are the memoized
+ * passes over the tree.
+ */
+function cladeRows(
+  clade: Clade,
+  root: HierarchyNode<NodeWithIds>,
+  index: Map<string, HierarchyNode<NodeWithIds> | undefined>,
+  rowNamesSet: Map<string, number>,
+): { rows: [number, number]; nodeId?: string } | undefined {
+  if (clade.range) {
+    const [a, b] = clade.range.map(name =>
+      index.get(name) ? rowNamesSet.get(name) : undefined,
+    )
+    if (a === undefined || b === undefined) {
+      return undefined
+    }
+    const rows: [number, number] = a <= b ? [a, b] : [b, a]
+    return rows[1] - rows[0] + 1 === clade.tips ? { rows } : undefined
+  }
+  const node = clade.mrca ? mrca(root, clade.mrca, index) : undefined
+  if (!node) {
+    return undefined
+  }
+  const tips = leaves(node)
+  if (tips.length !== clade.tips) {
+    return undefined
+  }
+  let first = Infinity
+  let last = -Infinity
+  for (const tip of tips) {
+    const row = rowNamesSet.get(tip.data.name)
+    if (row !== undefined) {
+      first = Math.min(first, row)
+      last = Math.max(last, row)
+    }
+  }
+  return first <= last
+    ? { rows: [first, last], nodeId: node.data.id }
+    : undefined
+}
+
+/**
+ * Every clade that resolves, with its fill color settled, against the leaf
+ * order `rowNamesSet` gives. The tree panel resolves against the displayed
+ * rows and the overview against its own, so both take the tree they draw. A
+ * `range` record names no node, so `collapse` and `focus`, which need one,
+ * drop it.
+ */
+function resolveClades(
+  clades: Clade[],
+  root: HierarchyNode<NodeWithIds>,
+  rowNamesSet: Map<string, number>,
+): ResolvedClade[] {
+  const index = leafIndex(root)
+  return clades.flatMap(clade => {
+    const resolved = cladeRows(clade, root, index, rowNamesSet)
+    const seeding = clade.mark === 'collapse' || clade.mark === 'focus'
+    return resolved && !(seeding && resolved.nodeId === undefined)
+      ? [
+          {
+            ...resolved,
+            mark: clade.mark,
+            color: withAlpha(
+              clade.color ?? cladeHighlightColor,
+              cladeHighlightAlpha,
+            ),
+            markColor: clade.color,
+            label: clade.label,
+          },
+        ]
+      : []
+  })
+}
+
+/**
+ * The tree with the display transforms applied: leaf counts summed, children
+ * sorted by branch length, `showOnly` taken as the new root, and each
+ * `collapsed` clade folded. The overview builds the same tree without the
+ * focus, so it shows the focused subtree inside the whole.
+ */
+function buildTreeRoot(
+  tree: NodeWithIds,
+  collapsed: readonly string[],
+  showOnly?: string,
 ) {
-  return turnedOffTracks.get(id) ?? defaultOffTracks.has(id)
+  let hier = hierarchy(tree, d => d.children)
+  hierarchySum(hier, d => (d.children.length > 0 ? 0 : 1))
+  sort(hier, (a, b) => (a.data.length ?? 1) - (b.data.length ?? 1))
+
+  if (showOnly) {
+    const res = find(hier, n => n.data.id === showOnly)
+    if (res) {
+      hier = res
+    }
+  }
+
+  for (const collapsedId of collapsed) {
+    const node = find(hier, n => n.data.id === collapsedId)
+    if (node) {
+      if (node.children) {
+        collapse(node)
+      } else if (node.parent?.children) {
+        node.parent.children = node.parent.children.filter(
+          c => c.data.id !== collapsedId,
+        )
+      }
+    }
+  }
+
+  return hier
+}
+
+// the inclusive tip indices a node covers, from the row-space extent
+// clusterLayout writes to xMin/xMax as tip centers
+function tipRange(node: HierarchyNode): [number, number] {
+  return [Math.round(node.xMin! - 0.5), Math.round(node.xMax! - 0.5)]
+}
+
+// the channels reading the feature table; every other channel reads rowData
+const featureChannels = new Set<EncodingChannel>([
+  'featureFill',
+  'featureLabel',
+])
+
+// seqPos -> column indexes per row, keyed on the parse so they are garbage
+// collected with it. A computed would rebuild every row's index when read
+// outside a reactive context.
+const seqPosIndexCache = new WeakMap<object, Map<string, Int32Array>>()
+
+// A segment is a 1:1 run. A segment whose sides differ in length is malformed,
+// and the lookups treat it like an uncovered position.
+function sameLength(segment: ResidueSegment) {
+  return (
+    segment.rowEnd - segment.rowStart ===
+    segment.structEnd - segment.structStart
+  )
+}
+
+// fit() divides the viewport by the row or column count and multiplies back, so
+// an exact fit can land a fraction of a pixel over. A plain `>` would then show
+// a scrollbar that 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)
+}
+
+// the value every one of a node's children reports, or undefined where one of
+// them has no value or they disagree
+function sharedValue(values: (string | undefined)[]) {
+  const [first] = values
+  return first !== undefined && values.every(v => v === first)
+    ? first
+    : undefined
+}
+
+// preorder, so reversing the list puts every node after its descendants
+function preorder(tree: NodeWithIds) {
+  const order: NodeWithIds[] = []
+  const stack = [tree]
+  while (stack.length > 0) {
+    const node = stack.pop()!
+    order.push(node)
+    for (const child of node.children) {
+      stack.push(child)
+    }
+  }
+  return order
 }
 
 /**
@@ -225,10 +638,8 @@ function stateModelFactory() {
         /**
          * #property
          * whether the domain legend is expanded. The legend floats over the
-         * top-right of the alignment, so on a tall panel it covers real
-         * residues -- persisting the state is what lets a reader collapse it
-         * and keep it collapsed, and what lets a session or a figure open with
-         * it already out of the way.
+         * top-right of the alignment and covers residues, so a session or
+         * figure can open with it collapsed.
          */
         showDomainLegend: stripDefault(types.boolean, defaultShowDomainLegend),
         /**
@@ -261,6 +672,15 @@ function stateModelFactory() {
          */
         scrollZoom: stripDefault(types.boolean, defaultScrollZoom),
 
+        /**
+         * #property
+         * which cell dimensions a wheel zoom scales, while `scrollZoom` is on
+         */
+        scrollZoomAxis: stripDefault(
+          types.enumeration('ScrollZoomAxis', [...scrollZoomAxes]),
+          defaultScrollZoomAxis,
+        ),
+
         /**
          * #property
          * height of the div containing the view, px
@@ -341,17 +761,38 @@ function stateModelFactory() {
          * hidden-by-default track adds nothing to the shared URL.
          */
         turnedOffTracks: stripDefault(types.map(types.boolean), {}),
+
+        /**
+         * #property
+         * the height of every track one divider resizes, keyed by `heightKey`:
+         * the `kind` for the computed tracks, `own:<id>` for a data track. A
+         * key is absent until the user drags that divider, and
+         * `defaultTrackHeights` answers for it until then, so an untouched
+         * viewer adds nothing to the shared URL.
+         */
+        trackHeights: stripDefault(types.map(types.number), {}),
         /**
          * #property
-         * tracks supplied as data rather than computed from the alignment:
-         * per-column values drawn as bars, or a per-column string drawn as a
-         * text track. See docs/layers.md
+         * tracks supplied as data: per-column values drawn as bars, or a
+         * per-column string drawn as a text track. See docs/layers.md
          */
         columnTracks: stripDefault(
           types.array(types.frozen<ColumnTrackSpec>()),
           [],
         ),
 
+        /**
+         * #property
+         * row-to-structure residue correspondence, computed outside the viewer
+         * (e.g. from SIFTS). Matching by sequence equality places a tagged
+         * construct, a truncation or a subsequence row on the wrong residue.
+         * See docs/layers.md
+         */
+        residueMappings: stripDefault(
+          types.array(types.frozen<ResidueMapping>()),
+          [],
+        ),
+
         /**
          * #property
          * data from the loaded tree/msa/treeMetadata, generally loaded by
@@ -365,8 +806,12 @@ function stateModelFactory() {
 
         /**
          * #property
+         * the user's explicit hide choices per annotation accession, keyed by
+         * accession with the value meaning "off", like `turnedOffTracks`. An
+         * untouched accession is absent and drawn, so the shared URL grows
+         * only with the user's filters
          */
-        featureFilters: stripDefault(types.map(types.boolean), {}),
+        turnedOffFeatures: stripDefault(types.map(types.boolean), {}),
         /**
          * #property
          */
@@ -385,9 +830,34 @@ function stateModelFactory() {
          * labeled highlights in 1-based inclusive coordinates: a column span
          * `{start, end}`, a residue span `{row, start, end}` of a named row,
          * or a row set `{rows}`, each with an optional `label` and `color`.
-         * Persists in the snapshot, so a computed answer travels in the URL.
+         * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen<Highlight>()), []),
+        /**
+         * #property
+         * clades of the tree with a mark drawn over them. `mrca` names tips
+         * whose common ancestor is the clade, or `range` its first and last
+         * tip in display order, and `tips` is the leaf count the producer
+         * measured. `mark` is `highlight`, `bracket`, `collapse` or `focus`.
+         * See docs/layers.md
+         */
+        clades: stripDefault(types.array(types.frozen<Clade>()), []),
+        /**
+         * #property
+         * what the viewer's own marks read from `rowData`:
+         * `{channel, field, scale?}` per channel, where `channel` is
+         * `tipLabel` or `rowTint`. See docs/layers.md
+         */
+        encodings: stripDefault(types.array(types.frozen<Encoding>()), []),
+        /**
+         * #property
+         * panels drawn between the tree and the alignment:
+         * `{kind: "strip", field, scale?, width?, header?}` colors one cell
+         * per row from a `rowData` field, and
+         * `{kind: "features", x, encoding?, transform?, width?, header?}`
+         * draws the spans the GFF carries. See docs/layers.md
+         */
+        rowPanels: stripDefault(types.array(types.frozen<RowPanelSpec>()), []),
       }),
     )
     .volatile(() => ({
@@ -397,15 +867,17 @@ function stateModelFactory() {
       headerHeight: 0,
       /**
        * #volatile
+       * leaves the toolbar out, for a host drawing its own controls. Kept out
+       * of the snapshot so a link opened in the full app shows the toolbar.
        */
-      status: undefined as
-        | { msg: string; url?: string; onCancel?: () => void }
-        | undefined,
+      hideHeader: false,
+      /**
+       * #volatile
+       */
+      status: undefined as { msg: string; onCancel?: () => void } | undefined,
       /**
        * #volatile
-       * high resolution scale factor, helps make canvas look better on hi-dpi
-       * screens. derived from the device pixel ratio so canvases are crisp on
-       * retina/4k displays and not needlessly oversized on standard ones
+       * canvas scale factor, from the device pixel ratio
        */
       highResScaleFactor:
         typeof window === 'undefined' ? 1 : window.devicePixelRatio,
@@ -472,6 +944,13 @@ function stateModelFactory() {
        */
       highlightedColumns: undefined as number[] | undefined,
 
+      /**
+       * #volatile
+       * transient highlights keyed by owner, so a structure viewer's hover and
+       * a genome view's hover each clear only their own. Not persisted.
+       */
+      transientHighlights: {} as Record<string, Highlight[]>,
+
       /**
        * #volatile
        */
@@ -480,33 +959,41 @@ function stateModelFactory() {
       /**
        * #volatile
        */
-      conservationTrackHeight: 40,
+      marginLeft: 20,
 
       /**
        * #volatile
-       * taller than the conservation track by default: the logo spends its
-       * height on stacked glyphs, and a 40px stack of four residues leaves each
-       * one too short to identify
        */
-      sequenceLogoTrackHeight: 80,
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+      error: undefined as unknown,
 
       /**
        * #volatile
+       * non-fatal load problems: an optional layer that failed to load, an
+       * overlay that failed to parse. `error` replaces the view and is for the
+       * alignment itself
        */
-      marginLeft: 20,
+      warnings: [] as string[],
 
       /**
        * #volatile
+       * bumped by reset(). The error boundary above the view uses it as its key,
+       * since the boundary keeps its caught error until remounted
        */
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-      error: undefined as unknown,
+      resetCount: 0,
+
+      /**
+       * #volatile
+       * set by a host that restores the loaded documents itself, such as a
+       * jbrowse session or a page that refetches them. `unshareableData` then
+       * reports nothing
+       */
+      hostCarriesData: false,
 
       /**
        * #volatile
-       * overlay annotations drawn on the alignment, whatever their source.
-       * Every source -- InterProScan, GFF, a user upload -- converts to this
-       * flat list before it reaches the model, so nothing downstream of here
-       * knows which one it came from
+       * overlay annotations drawn on the alignment. InterProScan JSON, GFF and
+       * user uploads all convert to this flat list
        */
       annotations: [] as Annotation[],
     }))
@@ -552,8 +1039,8 @@ function stateModelFactory() {
       },
       /**
        * #action
-       * high-res scale factor, tracks the device pixel ratio so canvases stay
-       * crisp when the window moves between monitors or the browser zooms
+       * update the canvas scale factor when the device pixel ratio changes
+       * (moving between monitors, browser zoom)
        */
       setHighResScaleFactor(arg: number) {
         self.highResScaleFactor = arg
@@ -574,13 +1061,38 @@ function stateModelFactory() {
         self.error = error
       },
 
+      /**
+       * #action
+       * record a non-fatal load problem: 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
+       * hides 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 calls this (and reads `mouseCol`) to sync hover with
+       * its own view, such as a genome view or 3D structure. Keep the name and
+       * signature stable.
        */
       setMousePos(col?: number, row?: number) {
         self.mouseCol = col
@@ -591,9 +1103,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, and MSAViewer passes its `highlightColumns` prop
+       * through it.
        */
       setHighlightedColumns(columns?: number[]) {
         self.highlightedColumns = columns
@@ -604,6 +1116,35 @@ function stateModelFactory() {
       setHighlights(highlights: Highlight[]) {
         self.highlights.replace(highlights)
       },
+
+      /**
+       * #action
+       * replace the clades the viewer marks (see docs/layers.md)
+       */
+      setClades(clades: Clade[]) {
+        self.clades.replace(clades)
+      },
+      /**
+       * #action
+       * show `highlights` for `owner`, replacing that owner's previous ones and
+       * leaving other owners' in place
+       */
+      applyHighlight(owner: string, highlights: Highlight[]) {
+        self.transientHighlights = {
+          ...self.transientHighlights,
+          [owner]: highlights,
+        }
+      },
+      /**
+       * #action
+       * remove `owner`'s highlights, leaving other owners' 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 +1192,22 @@ function stateModelFactory() {
 
       /**
        * #action
-       *
+       * switch to another alignment of a multi-alignment file (Stockholm).
+       * Clears the collapsed node ids, the subtree in focus, the reference row
+       * and the scroll position, which all refer to the previous alignment
        */
       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 +1293,17 @@ function stateModelFactory() {
       setTreeMetadata(result: string) {
         self.data.setTreeMetadata(result)
       },
+
+      /**
+       * #action
+       * store the GFF text in the snapshot like the alignment and tree. The
+       * parsed annotations are volatile and a blob filehandle is cleared once
+       * read, so the text is the only persisted copy. An autorun parses it
+       * into annotations.
+       */
+      setGFF(result: string) {
+        self.data.setGFF(result)
+      },
     }))
 
     .views(self => ({
@@ -765,6 +1329,20 @@ function stateModelFactory() {
       get actuallyShowDomains() {
         return self.showDomains && self.annotations.length > 0
       },
+      /**
+       * #getter
+       * whether the host restores the loaded documents outside the snapshot.
+       * When true, `unshareableData` is empty.
+       *
+       * A simple host sets `hostCarriesData`. A host where this depends on how
+       * the view was opened overrides the getter in its own composed model's
+       * `.views` block; jbrowse-plugin-msaview's indexed-location views refetch
+       * from a URL the session holds, while its data-store views do not.
+       * `unshareableData` reads it off `self`, so an override takes effect.
+       */
+      get hostRestoresData() {
+        return self.hostCarriesData
+      },
       get viewInitialized() {
         return self.volatileWidth !== undefined
       },
@@ -779,19 +1357,12 @@ function stateModelFactory() {
       },
     }))
     .views(self => ({
-      /**
-       * #method
-       * unused here, but can be used by derived classes to add extra items
-       */
-      extraViewMenuItems() {
-        return []
-      },
       /**
        * #getter
        */
       get colorScheme() {
-        // colorSchemeName is a free string (menus, snapshots, URL params); fall
-        // back to the default rather than returning undefined on a stale name
+        // colorSchemeName is a free string (menus, snapshots, URL params), so a
+        // stale name falls back to the default
         return (
           colorSchemes[self.colorSchemeName] ??
           colorSchemes[defaultColorSchemeName]!
@@ -820,18 +1391,60 @@ function stateModelFactory() {
       get noDomains() {
         return self.annotations.length === 0
       },
+
+      /**
+       * #getter
+       * loaded documents left out of the snapshot, largest first. A file opened
+       * from disk or pasted in becomes inline text, and DataModel drops an
+       * inline document past `maxInlineSnapshotBytes`.
+       *
+       * The header lists these, and the standalone app stops rewriting the
+       * address bar while the list is non-empty, so a copied link does not
+       * open an empty viewer unannounced. A document fetched from a URL never
+       * appears here, since the snapshot keeps its filehandle.
+       *
+       * Empty when `hostRestoresData` is true.
+       */
+      get unshareableData(): UnshareableData[] {
+        if (self.hostRestoresData) {
+          return []
+        }
+        const { data } = self
+        // data tracks past the limit also leave the snapshot
+        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 []
       },
       /**
        * #getter
-       * extra per-row attributes, keyed by row name. Parsed defensively: the
-       * source is a user-supplied document (treeMetadataFilehandle, or a
-       * session snapshot), and this computed is read by labelWidthMap on every
-       * layout, so a malformed file would otherwise throw out of rendering and
-       * take the whole view down over a decorative field.
-       */
-      get treeMetadata(): Record<string, Record<string, string> | undefined> {
+       * the row table: extra fields per row, keyed by row name, which the
+       * `encodings` channels read. It is stored as the JSON string
+       * `data.treeMetadata`, the name that travels in existing links, so the
+       * inline size limit and `treeMetadataFilehandle` cover it. labelWidthMap
+       * reads it on every layout, so a malformed user-supplied file returns {}
+       * instead of throwing out of rendering.
+       */
+      get rowData(): Record<string, Record<string, string> | undefined> {
         const text = self.data.treeMetadata
         if (!text) {
           return {}
@@ -842,10 +1455,31 @@ function stateModelFactory() {
             ? (parsed as Record<string, Record<string, string> | undefined>)
             : {}
         } catch (e) {
-          console.error('failed to parse treeMetadata', e)
+          console.error('failed to parse rowData', e)
           return {}
         }
       },
+      /**
+       * #method
+       * one row's fields, the single reader of the row table
+       */
+      rowDataOf(name: string) {
+        return this.rowData[name]
+      },
+      /**
+       * #getter
+       * the field names the row table carries, sorted, for a producer or a UI
+       * choosing one to encode
+       */
+      get rowFields(): string[] {
+        const fields = new Set<string>()
+        for (const row of Object.values(this.rowData)) {
+          for (const field of Object.keys(row ?? {})) {
+            fields.add(field)
+          }
+        }
+        return [...fields].sort((a, b) => a.localeCompare(b))
+      },
       /**
        * #getter
        */
@@ -895,6 +1529,37 @@ function stateModelFactory() {
           this.leaves.map((leaf, index) => [leaf.data.name, index] as const),
         )
       },
+      /**
+       * #getter
+       * `clades` resolved to the rows each one covers. The tip names resolve
+       * against `tree` rather than `root`, so a clade whose ancestor the user
+       * collapsed keeps its rows. One leaf pass over the tree serves every
+       * clade. A `range` record names no node, so `collapse` and `focus`, which
+       * need one, drop it.
+       */
+      get resolvedClades(): ResolvedClade[] {
+        if (self.clades.length === 0) {
+          return noClades
+        }
+        return resolveClades(
+          self.clades,
+          hierarchy(this.tree, d => d.children),
+          this.rowNamesSet,
+        )
+      },
+      /**
+       * #getter
+       * the pixel column reserved at the right of the tree area for the bracket
+       * mark, which the tip labels and the tree itself stay clear of. Zero
+       * where no clade draws a bar or a label.
+       */
+      get cladeGutterWidth() {
+        return cladeGutterWidth({
+          clades: this.resolvedClades,
+          rowHeight: self.rowHeight,
+          fontSize: this.fontSize,
+        })
+      },
       /**
        * #getter
        */
@@ -928,46 +1593,143 @@ function stateModelFactory() {
        * #getter
        */
       get root() {
-        let hier = hierarchy(this.tree, d => d.children)
-        hierarchySum(hier, d => (d.children.length > 0 ? 0 : 1))
-        sort(hier, (a, b) => (a.data.length ?? 1) - (b.data.length ?? 1))
-
-        if (self.showOnly) {
-          const res = find(hier, n => n.data.id === self.showOnly)
-          if (res) {
-            hier = res
-          }
+        return buildTreeRoot(this.tree, self.collapsed, self.showOnly)
+      },
+
+      /**
+       * #getter
+       * height of the band the tree overview draws in, zero when it is off
+       */
+      get treeOverviewHeight() {
+        return self.showTreeOverview ? self.overviewHeight : 0
+      },
+
+      /**
+       * #getter
+       * the whole tree laid out for the overview, or undefined when the
+       * overview is off. The focus is left out, so the focused subtree draws
+       * inside the whole tree, and the collapsed clades are folded, since
+       * those are rows the view no longer has. `x` is in tip-index space and
+       * `len` is a fraction of the root-to-tip length, so one layout serves
+       * any band size.
+       */
+      get treeOverviewLayout() {
+        if (!self.showTreeOverview) {
+          return undefined
+        }
+        const root = buildTreeRoot(this.tree, self.collapsed)
+        const numTips = leaves(root).length
+        clusterLayout(root, numTips, 1)
+        const rootLen = Math.max(root.data.length || 0, 0)
+        const extent = maxLength(root) - rootLen
+        setBrLength(root, -rootLen, extent ? 1 / extent : 0)
+        return {
+          root,
+          numTips,
+          maxDepthToLeaf: calcDepthToLeaf(root),
+          showBranchLen: self.showBranchLen && extent > 0,
         }
+      },
 
-        for (const collapsedId of self.collapsed) {
-          const node = find(hier, n => n.data.id === collapsedId)
-          if (node) {
-            if (node.children) {
-              collapse(node)
-            } else if (node.parent?.children) {
-              node.parent.children = node.parent.children.filter(
-                c => c.data.id !== collapsedId,
-              )
-            }
-          }
+      /**
+       * #getter
+       * the `clades` highlights in the overview's own row space, which the
+       * focus does not narrow
+       */
+      get treeOverviewClades(): ResolvedClade[] {
+        const layout = this.treeOverviewLayout
+        if (!layout || self.clades.length === 0) {
+          return noClades
+        }
+        const rowNames = new Map(
+          leaves(layout.root).map((leaf, index) => [leaf.data.name, index]),
+        )
+        return resolveClades(self.clades, layout.root, rowNames)
+      },
+
+      /**
+       * #getter
+       * the inclusive tip rows the focused subtree covers in the overview,
+       * which is the box drawn on it. undefined with no focus
+       */
+      get treeOverviewFocusRows(): [number, number] | undefined {
+        const layout = this.treeOverviewLayout
+        if (!layout || !self.showOnly) {
+          return undefined
         }
+        const node = find(layout.root, n => n.data.id === self.showOnly)
+        return node ? tipRange(node) : undefined
+      },
 
-        return hier
+      /**
+       * #method
+       * the subtree a point `y` pixels down the tree overview picks: the
+       * deepest one whose tip range covers every row under that pixel, with
+       * the rows it covers. A pixel stands for several tips on a large tree,
+       * which is what keeps the pick off the individual tips. undefined when
+       * the overview is off or the point picks the whole tree.
+       */
+      treeOverviewHit(y: number) {
+        const layout = this.treeOverviewLayout
+        if (!layout) {
+          return undefined
+        }
+        const { root, numTips } = layout
+        const perPixel = numTips / self.overviewHeight
+        const first = clamp(Math.floor(y * perPixel), 0, numTips - 1)
+        const last = clamp(
+          Math.ceil((y + 1) * perPixel) - 1,
+          first,
+          numTips - 1,
+        )
+        let node = nodeCoveringRows(root, first + 0.5, last + 0.5)
+        // focusing one tip leaves a single row on screen, so the pick lifts to
+        // the subtree that tip sits in
+        while (!node.children && node.parent) {
+          node = node.parent
+        }
+        return node === root
+          ? undefined
+          : { id: node.data.id, rows: tipRange(node) }
       },
 
       /**
        * #getter
-       * widget width minus the tree area gives the space for the MSA
+       * the pixel column the row panels occupy between the tree and the
+       * alignment, the sum of each record's width
+       */
+      get rowPanelsWidth() {
+        return sum(self.rowPanels.map(p => rowPanelWidth(p, self.rowHeight)))
+      },
+      /**
+       * #getter
+       * height of the band the row panel headers draw in, which is zero with
+       * no row panels and leaves the top area as it was
+       */
+      get rowPanelsHeaderHeight() {
+        return self.rowPanels.length > 0 ? rowPanelHeaderHeight : 0
+      },
+      /**
+       * #getter
+       * widget width minus the tree area and the row panels gives the space
+       * for the MSA
        */
       get msaAreaWidth() {
-        return self.width - self.treeAreaWidth - self.resizeHandleWidth
+        return (
+          self.width -
+          self.treeAreaWidth -
+          this.rowPanelsWidth -
+          self.resizeHandleWidth
+        )
       },
 
       /**
        * #getter
+       * the right edge the tip labels end at, which is the tree area less the
+       * margin and the bracket gutter
        */
       get treeAreaWidthMinusMargin() {
-        return self.treeAreaWidth - self.marginLeft
+        return self.treeAreaWidth - self.marginLeft - this.cladeGutterWidth
       },
       /**
        * #getter
@@ -1037,34 +1799,54 @@ function stateModelFactory() {
       },
       /**
        * #getter
-       * number of rows the alignment occupies on screen. This is the leaf count,
-       * not `rows.length`: a tree leaf with no matching MSA row still takes up a
-       * row of vertical space (drawn blank), so row hit-testing and fit-to-height
-       * must count it.
+       * number of rows on screen: the leaf count, which includes tree leaves
+       * with no matching MSA row (drawn blank), unlike `rows.length`.
        */
       get numRows() {
         return this.leaves.length
       },
 
       /**
-       * #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.
-       */
-      get seqPosGlobalColIndex() {
-        return new Map(
-          this.rows.map(
-            ([name, seq]) => [name, buildSeqPosIndex(seq)] as const,
-          ),
-        )
-      },
-
-      /**
-       * #getter
+       * #method
+       * index of the global column holding each ungapped sequence position of a
+       * row. The domain overlay resolves thousands of these per redraw. Built
+       * lazily per row and cached on the parse.
+       */
+      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 in the alignment, keyed by row name, including rows a
+       * collapsed clade hides. `rows` holds only the rows on screen; lookups
+       * by row name use this
        */
       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 +1983,11 @@ 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, so subtract its length here; `root`
+        // returns the cached parse, which must not be mutated
+        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 +2016,31 @@ 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: treeWidth, or 0 for
+       * a tree with no branch lengths (drawn as a cladogram)
        */
       get maxBranchLength() {
-        return findMaxBranchLen(this.hierarchy)
+        return this.rootToTipLength ? self.treeWidth : 0
+      },
+
+      /**
+       * #getter
+       * pixels per unit of branch length in the phylogram layout, 0 in
+       * cladogram mode. The tree's scale bar uses it.
+       */
+      get pxPerBranchLength() {
+        const max = maxLength(this.root)
+        return this.showBranchLenEffective && max ? self.treeWidth / max : 0
       },
 
       /**
@@ -1251,7 +2055,7 @@ function stateModelFactory() {
        * #getter
        */
       get allBranchesLength0() {
-        return links(this.hierarchy).every(s => !s.source.data.length)
+        return this.rootToTipLength === 0
       },
 
       /**
@@ -1275,170 +2079,899 @@ 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
+      get showMsaLetters() {
+        return (
+          self.drawMsaLetters &&
+          self.rowHeight >= minLetterRowHeight &&
+          self.colWidth >= minLetterColWidth &&
+          self.colWidth > self.rowHeight / 2
+        )
       },
       /**
        * #getter
        */
-      get blocksX() {
-        return calculateBlocks({
-          viewportSize: self.msaAreaWidth,
-          viewportPos: -self.scrollX,
-          blockSize: self.blockSize,
-          mapSize: self.totalWidth,
-        })
+      get showTreeText() {
+        return self.drawLabels && self.rowHeight >= minLetterRowHeight
       },
+    }))
+    .views(self => ({
       /**
        * #getter
        */
-      get blocksY() {
-        return calculateBlocks({
-          viewportSize: this.visibleMsaHeight,
-          viewportPos: -self.scrollY,
-          blockSize: self.blockSize,
-          mapSize: self.totalHeight,
-        })
+      get labelWidthMap() {
+        const { showTreeText, leaves } = self
+        // gated on the renderer's label condition, so hidden labels reserve no
+        // gutter. Measured once at a reference size and scaled by
+        // labelWidthScale: re-measuring per 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
+                const displayName = self.rowDataOf(name)?.genome || name
+                return [
+                  name,
+                  measureTextCanvas(displayName, labelReferenceFontSize),
+                ] as const
+              }),
+            )
+          : new Map<string, number>()
       },
+
       /**
        * #getter
-       * height of the alignment viewport, px. The same subtraction as
-       * msaAreaHeight, which is defined later in the views chain
+       * factor turning a labelWidthMap entry into its width at the current
+       * font size
        */
-      get visibleMsaHeight() {
-        return (
-          self.height -
-          self.headerHeight -
-          (self.msaAreaWidth < self.totalWidth ? self.minimapHeight : 0)
-        )
+      get labelWidthScale() {
+        return self.fontSize / labelReferenceFontSize
       },
-    }))
-    .views(self => ({
+
+      get labelsWidth() {
+        // a loop, not Math.max(...): spreading passes one argument per leaf,
+        // and the ~125k argument limit throws RangeError on the 230k-tip COVID
+        // tree
+        let max = 0
+        for (const width of this.labelWidthMap.values()) {
+          if (width > max) {
+            max = width
+          }
+        }
+        return max * this.labelWidthScale
+      },
+
       /**
        * #getter
        */
-      get blocks2d() {
-        return self.blocksY.flatMap(by =>
-          self.blocksX.map(bx => [bx, by] as const),
-        )
+      get secondaryStructureConsensus() {
+        return self.MSA?.secondaryStructureConsensus
       },
 
       /**
        * #getter
        */
-      get isLoading() {
-        return self.loadingMSA || self.loadingTree
+      get seqConsensus() {
+        return self.MSA?.seqConsensus
       },
+
       /**
        * #getter
+       * the base pairs of the consensus secondary structure, as arcs, in
+       * visible column space (hidden columns are removed before parsing)
        */
-      get maxScrollX() {
-        return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0)
+      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
-       * 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 adapterTrackModels(): BasicTrack[] {
+        const { MSA, hideGapsEffective, blanks } = self
+        const tracks = (MSA?.tracks ?? []).filter(t => !!t.data)
+        if (tracks.length === 0) {
+          // return before reading rowHeight, so zooming does not rebuild the
+          // list and redraw every track canvas
+          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,
+        }))
       },
+
       /**
        * #getter
+       * a data track's values or string, projected from its row's residues
+       * onto alignment columns when it names a row
        */
-      get showMsaLetters() {
+      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
+        }
+        const skip = <T>(items: T[]) =>
+          hideGapsEffective ? dropBlanks(blanks, items) : items
+        // an arc endpoint maps row residue -> column -> visible column.
+        // visibleColsBefore, not globalColToVisibleCol, so an endpoint in a
+        // hidden column moves to the neighboring visible one and the arc stays
+        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
+        }
+        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
+            }
+            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
+          }),
+        )
+      },
+      /**
+       * #method
+       * the height a track draws at: what the user dragged its divider to,
+       * then the height its snapshot asked for, then its kind's default. Only
+       * a text track falls through to rowHeight, and `??` short-circuits
+       * before reading it, so vertical zoom does not rebuild the other tracks
+       */
+      trackHeight(kind: TrackKind, heightKey = kind as string, given?: number) {
         return (
-          self.drawMsaLetters &&
-          self.rowHeight >= minLetterRowHeight &&
-          self.colWidth >= minLetterColWidth &&
-          self.colWidth > self.rowHeight / 2
+          self.trackHeights.get(heightKey) ??
+          given ??
+          defaultTrackHeights[kind] ??
+          self.rowHeight
         )
       },
       /**
        * #getter
        */
-      get showTreeText() {
-        return self.drawLabels && self.rowHeight >= minLetterRowHeight
+      get columnTrackModels(): BasicTrack[] {
+        return self.columnTracks.map(track => {
+          const heightKey = resizableKinds.has(track.kind)
+            ? ownHeightKey(track.id)
+            : undefined
+          return {
+            model: {
+              id: track.id,
+              name: track.name,
+              kind: track.kind,
+              heightKey,
+              height: this.trackHeight(track.kind, heightKey, track.height),
+              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,
+          }
+        })
       },
-    }))
-    .actions(self => ({
       /**
-       * #action
-       */
-      setDrawMsaLetters(arg: boolean) {
-        self.drawMsaLetters = arg
+       * #getter
+       * the consensus secondary structure as a track, when there is one. A
+       * separate getter keeps the object stable across zoom, so its canvas
+       * does not redraw
+       */
+      get basePairTrackModels(): BasicTrack[] {
+        const arcs = this.secondaryStructureArcs
+        return arcs?.length
+          ? [
+              {
+                model: {
+                  id: 'base-pairs',
+                  name: 'Base pairs',
+                  kind: 'arc' as const,
+                  heightKey: 'arc',
+                  height: this.trackHeight('arc'),
+                  arcs,
+                },
+                ReactComponent: TrackBlocks,
+              },
+            ]
+          : []
       },
 
       /**
-       * #action
+       * #getter
+       * the tracks computed from the alignment; they depend on their heights
+       * and the alphabet, not on zoom
        */
-      setScrollZoom(arg: boolean) {
-        self.scrollZoom = arg
+      get computedTrackModels(): BasicTrack[] {
+        return [
+          {
+            id: 'conservation',
+            name: 'Conservation',
+            kind: 'bar' as const,
+            barColor: 'gray',
+          },
+          ...(self.sequenceType === 'amino'
+            ? [
+                {
+                  id: 'property-conservation',
+                  name: 'Property conservation',
+                  kind: 'bar' as const,
+                  barColor: '#6a51a3',
+                },
+              ]
+            : []),
+          {
+            id: 'sequence-logo',
+            name: 'Sequence logo',
+            kind: 'logo' as const,
+          },
+          // last, so it sits against the alignment it numbers
+          {
+            id: 'position-ruler',
+            name: 'Position',
+            kind: 'ruler' as const,
+          },
+        ].map(model => ({
+          // every computed track of a kind shares that kind's height, so the
+          // kind is its key
+          model: {
+            ...model,
+            heightKey: resizableKinds.has(model.kind) ? model.kind : undefined,
+            height: this.trackHeight(model.kind),
+          },
+          ReactComponent: TrackBlocks,
+        }))
       },
 
-      /**
-       * #action
-       * set hovered tree node and its descendants
-       */
-      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 tracks(): BasicTrack[] {
+        return [
+          ...this.adapterTrackModels,
+          ...this.basePairTrackModels,
+          ...this.columnTrackModels,
+          // every computed track reads the alignment's columns, and a tree, a
+          // GFF and a features panel draw a figure with none
+          ...(self.numColumns > 0 ? this.computedTrackModels : []),
+        ]
       },
 
       /**
-       * #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 turnedOnTracks() {
+        return this.tracks.filter(
+          f =>
+            !trackIsOff(self.turnedOffTracks, f.model.id, f.model.defaultOff),
+        )
       },
 
       /**
-       * #action
-       * restore the default column width and row height
+       * #getter
        */
-      resetZoom() {
-        self.setColWidth(defaultColWidth)
-        self.setRowHeight(defaultRowHeight)
+      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
        */
-      zoomOutHorizontal() {
-        self.colWidth = Math.max(minColWidth, Math.floor(self.colWidth * 0.75))
-        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+      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, like the sibling converters (visibleColToGlobalCol,
+       * seqPosToVisibleCol, globalColToVisibleCol, seqPosToGlobalCol) hosts
+       * use to translate between columns and residue positions. 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
        */
-      zoomInHorizontal() {
-        self.colWidth = Math.min(maxCellSize, Math.ceil(self.colWidth * 1.5))
-        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+      visibleColToSeqPos(rowName: string, visibleCol: number) {
+        // binary search: this runs on every mouse move, and scanning a
+        // 30k-column row per event takes the whole frame
+        return seqPosOfGlobalCol(
+          self.seqPosIndex(rowName),
+          this.visibleColToGlobalCol(visibleCol),
+        )
+      },
+
+      /**
+       * #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
+       */
+      visibleColToSeqPosOneBased(rowName: string, visibleCol: number) {
+        const val = this.visibleColToSeqPos(rowName, visibleCol)
+        return val !== undefined ? val + 1 : undefined
+      },
+
+      /**
+       * #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
+       */
+      globalColToVisibleCol(globalCol: number) {
+        const { blanks, hideGapsEffective } = self
+        if (!hideGapsEffective) {
+          return globalCol
+        }
+        return globalColToVisibleCol(blanks, globalCol)
+      },
+
+      /**
+       * #method
+       * Convert a visible column index (what a mouse handler reports) to a
+       * column of the full alignment. A host indexing its own per-column data
+       * needs this when columns are hidden.
+       *
+       * @param visibleCol - The visible column index
+       * @returns The global column index in the full MSA
+       */
+      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 name the alignment does not have.
+       *
+       * @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)
+      },
+
+      /**
+       * #method
+       * the visible columns a span covers, in highlight coordinates: `start`
+       * and `end` are 1-based residues of `row`, or columns of the file
+       * without it. A fractional position, as a zoom gesture reports one,
+       * widens to the whole residue or column it falls in. A span entirely on
+       * hidden columns, or naming a row the alignment lacks, gives undefined.
+       */
+      visibleSpan({ row, start: rawStart, end: rawEnd }: Region) {
+        const { blanks } = self
+        const start = Math.max(1, Math.floor(rawStart))
+        const end = Math.ceil(rawEnd)
+        let startGlobal = start - 1
+        let endGlobal = end - 1
+        if (row !== undefined) {
+          const rowStart = this.seqPosToGlobalCol(row, start - 1)
+          const rowEnd = this.seqPosToGlobalCol(row, end - 1)
+          if (rowStart === undefined || rowEnd === undefined) {
+            return undefined
+          }
+          startGlobal = rowStart
+          endGlobal = rowEnd
+        }
+        const startCol =
+          this.globalColToVisibleCol(startGlobal) ??
+          visibleColsBefore(blanks, startGlobal)
+        const endCol =
+          this.globalColToVisibleCol(endGlobal) ??
+          visibleColsBefore(blanks, endGlobal) - 1
+        return startCol <= endCol ? { startCol, endCol } : undefined
+      },
+
+      /**
+       * #getter
+       * why each ignored residue mapping is ignored, so a host can tell a
+       * missing structure from a mapping made against a different alignment.
+       */
+      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,
+          )
+          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 fit the loaded alignment. A row-level problem drops
+       * the whole mapping; a malformed segment drops only that segment.
+       */
+      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 with usable mappings. A row can map onto several, such
+       * as an experimental entry and a predicted model.
+       */
+      get mappedStructures() {
+        return this.usableResidueMappings.map(m => ({
+          row: m.row,
+          structure: m.structure,
+        }))
+      },
+
+      /**
+       * #method
+       * The structure residue for a row residue. Returns undefined when no
+       * segment covers `seqPos`, or when the row maps onto several structures
+       * and `structureId` does not pick one (see `mappedStructures`).
+       *
+       * Positions are 1-based, like `residueMappings` and `highlights`; the
+       * column helpers above are 0-based.
+       *
+       * @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
+      },
+
+      /**
+       * #method
+       * The row residue for a structure residue; the inverse of
+       * `structureResidue`, returning undefined in the same cases. `asymId`
+       * picks a chain when several mappings share an entry id, as in a
+       * homodimer.
+       *
+       * @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 branch-length scale bar over the tree, undefined in cladogram mode
+       * or when the tree area is too narrow for one
+       */
+      get treeScaleBar() {
+        return scaleBarLength(
+          self.pxPerBranchLength,
+          self.treeAreaWidth - self.marginLeft * 2,
+        )
+      },
+      /**
+       * #getter
+       * the band across the top: the minimap over the alignment, the row panel
+       * headers, and the tree overview stacked on the scale bar, as tall as the
+       * tallest of the three
+       */
+      get topBandHeight() {
+        return Math.max(
+          self.showHorizontalScrollbar ? self.minimapHeight : 0,
+          self.rowPanelsHeaderHeight,
+          self.treeOverviewHeight +
+            (this.treeScaleBar ? treeScaleBarHeight : 0),
+        )
+      },
+      /**
+       * #getter
+       * the vertical space for alignment rows: the widget height less the
+       * header, the top band and the tracks. Shared by blocksY, maxScrollY, the
+       * vertical scrollbar and fitVertically.
+       */
+      get msaAreaHeight() {
+        return (
+          self.height -
+          this.topBandHeight -
+          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, for the legend, the
+       * filter dialog and the palettes
+       */
+      get annotationTypes() {
+        // first occurrence wins; only name, description and segment start are
+        // read from it
+        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 => ({
+      /**
+       * #getter
+       */
+      get showVerticalScrollbar() {
+        return overflows(self.totalHeight, self.msaAreaHeight)
+      },
+    }))
+    .views(self => ({
+      /**
+       * #getter
+       */
+      get dataInitialized() {
+        // truthiness, not `!== ''`: DataModel drops an inline document over
+        // 50kb from the snapshot, so a restored session can hold `undefined`
+        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: self.msaAreaHeight,
+          viewportPos: -self.scrollY,
+          blockSize: self.blockSize,
+          mapSize: self.totalHeight,
+        })
+      },
+    }))
+    .views(self => ({
+      /**
+       * #getter
+       */
+      get blocks2d() {
+        return self.blocksY.flatMap(by =>
+          self.blocksX.map(bx => [bx, by] as const),
+        )
+      },
+
+      /**
+       * #getter
+       */
+      get isLoading() {
+        return self.loadingMSA || self.loadingTree
+      },
+      /**
+       * #getter
+       */
+      get maxScrollX() {
+        return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0)
+      },
+      /**
+       * #getter
+       * most-negative allowed scrollY, which keeps the last row in view
+       */
+      get maxScrollY() {
+        return Math.min(-self.totalHeight + self.msaAreaHeight, 0)
+      },
+      /**
+       * #getter
+       * axis a wheel zoom scales, for ctrl+wheel as much as for scroll-zoom.
+       * With scroll-zoom off the toolbar shows no axis, so ctrl+wheel takes
+       * both.
+       */
+      get wheelZoomAxis(): ScrollZoomAxis {
+        return self.scrollZoom ? self.scrollZoomAxis : 'both'
+      },
+    }))
+    .actions(self => ({
+      /**
+       * #action
+       */
+      setDrawMsaLetters(arg: boolean) {
+        self.drawMsaLetters = arg
+      },
+
+      /**
+       * #action
+       */
+      setScrollZoom(arg: boolean) {
+        self.scrollZoom = arg
+      },
+
+      /**
+       * #action
+       */
+      setScrollZoomAxis(arg: ScrollZoomAxis) {
+        self.scrollZoomAxis = arg
+      },
+
+      /**
+       * #action
+       * set hovered tree node and its descendants
+       */
+      setHoveredTreeNode(nodeId?: string) {
+        // called on every tree mousemove; `find` walks the whole hierarchy and a
+        // new object redraws the tree and MSA overlays
+        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
+      },
+
+      /**
+       * #action
+       * Calculate a neighbor joining tree from the current MSA using BLOSUM62
+       * distances. Throws above `maxNeighborJoiningRows`: the join loop is
+       * cubic and runs on the main thread, and 800 rows freeze the tab for ten
+       * seconds with no cancel.
+       */
+      calculateNeighborJoiningTreeFromMSA() {
+        // every sequence, including rows in collapsed clades
+        const rows = [...self.rowMap]
+        if (rows.length < 2) {
+          throw new Error('Need at least 2 sequences to build a tree')
+        }
+        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))
+      },
+
+      /**
+       * #action
+       * swap in a different tree over the same alignment. Clears `collapsed`
+       * and `showOnly`, since path-derived node ids (node-0-0-1) from the old
+       * tree would match unrelated nodes in the new one.
+       */
+      replaceTree(newick: string) {
+        transaction(() => {
+          self.collapsed.clear()
+          self.setShowOnly(undefined)
+          self.setTree(newick)
+        })
+      },
+
+      /**
+       * #action
+       * restore the default column width and row height
+       */
+      resetZoom() {
+        self.setColWidth(defaultColWidth)
+        self.setRowHeight(defaultRowHeight)
+      },
+      /**
+       * #action
+       */
+      zoomOutHorizontal() {
+        self.colWidth = Math.max(minColWidth, Math.floor(self.colWidth * 0.75))
+        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+      },
+      /**
+       * #action
+       */
+      zoomInHorizontal() {
+        self.colWidth = Math.min(maxCellSize, Math.ceil(self.colWidth * 1.5))
+        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
       },
       /**
        * #action
@@ -1477,26 +3010,36 @@ function stateModelFactory() {
        * #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.
-       */
-      zoomToPos(scaleFactor: number, offsetX: number, offsetY: number) {
+       * horizontally. Vertically the anchor is biased toward y=0 when the
+       * alignment nearly fits the viewport, fading to cursor-anchoring as the
+       * alignment grows taller than the viewport.
+       * Drives wheel/trackpad-pinch zoom. `axis` holds one cell dimension
+       * fixed; the held axis still re-anchors its scroll offset, since the
+       * other one can change how much of the alignment fits.
+       */
+      zoomToPos(
+        scaleFactor: number,
+        offsetX: number,
+        offsetY: number,
+        axis: ScrollZoomAxis = 'both',
+      ) {
         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,
-          )
+          if (axis !== 'vertical') {
+            self.colWidth = clamp(
+              self.colWidth * scaleFactor,
+              minColWidth,
+              maxCellSize,
+            )
+          }
+          if (axis !== 'horizontal') {
+            self.rowHeight = clamp(
+              self.rowHeight * scaleFactor,
+              minRowHeight,
+              maxCellSize,
+            )
+          }
           self.scrollX = clamp(
             offsetX - colInView * self.colWidth,
             self.maxScrollX,
@@ -1504,9 +3047,7 @@ function stateModelFactory() {
           )
 
           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)
+          // -maxScrollY is the overflow past the viewport, 0 when it fits
           const overflow = Math.max(0, -self.maxScrollY)
           const visibleHeight = self.totalHeight - overflow
           const topBias =
@@ -1535,13 +3076,14 @@ function stateModelFactory() {
 
       /**
        * #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.
+       * Set the overlay annotations (an empty list clears them). InterProScan,
+       * GFF, user uploads and NCBI CDD all arrive here as Annotation[].
+       *
+       * Leaves `showDomains` alone, because a restored snapshot reloads its
+       * GFF and must keep a hidden overlay hidden.
        */
       setAnnotations(annotations: Annotation[]) {
         self.annotations = annotations
-        self.setShowDomains(annotations.length > 0)
       },
 
       /**
@@ -1566,382 +3108,62 @@ function stateModelFactory() {
       },
 
       /**
-       * #action
-       */
-      setScrollX(n: number) {
-        self.scrollX = clamp(n, self.maxScrollX, 0)
-      },
-
-      /**
-       * #action
-       */
-      setColumnTracks(tracks: ColumnTrackSpec[]) {
-        self.columnTracks.replace(tracks)
-      },
-      /**
-       * #action
-       */
-      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))
-      },
-      /**
-       * #action
-       */
-      setStatus(status?: { msg: string; url?: string; onCancel?: () => void }) {
-        self.status = status
-      },
-    }))
-    .views(self => ({
-      /**
-       * #getter
-       */
-      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 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 secondaryStructureConsensus() {
-        return self.MSA?.secondaryStructureConsensus
-      },
-
-      /**
-       * #getter
-       */
-      get seqConsensus() {
-        return self.MSA?.seqConsensus
-      },
-
-      /**
-       * #getter
-       */
-      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,
-          }))
-      },
-
-      /**
-       * #getter
-       * a data track's values or string, projected from its row's residues
-       * onto alignment columns when it names a row
-       */
-      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
-          }),
-        )
-      },
-      /**
-       * #getter
-       */
-      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,
-        }))
-      },
-      /**
-       * #getter
-       */
-      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 })),
-        ]
-      },
-
-      /**
-       * #getter
-       */
-      get turnedOnTracks() {
-        return this.tracks.filter(
-          f => !trackIsOff(self.turnedOffTracks, f.model.id),
-        )
-      },
-
-      /**
-       * #getter
-       */
-      get showHorizontalScrollbar() {
-        return self.msaAreaWidth < self.totalWidth
-      },
-
-      /**
-       * #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
-       */
-      visibleColToRowLetter(rowName: string, visibleCol: number) {
-        const { rowMap, blanks } = self
-        return rowMap.get(rowName)?.[visibleColToGlobalCol(blanks, visibleCol)]
-      },
-
-      /**
-       * #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
-       */
-      visibleColToSeqPos(rowName: string, visibleCol: number) {
-        return visibleColToSeqPosForRow({
-          rowName,
-          visibleCol,
-          rowMap: self.rowMap,
-          blanks: self.blanks,
-        })
-      },
-
-      /**
-       * #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
-       */
-      visibleColToSeqPosOneBased(rowName: string, visibleCol: number) {
-        const val = this.visibleColToSeqPos(rowName, visibleCol)
-        return val !== undefined ? val + 1 : undefined
-      },
-
-      /**
-       * #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
-       */
-      globalColToVisibleCol(globalCol: number) {
-        const { blanks, hideGapsEffective } = self
-        if (!hideGapsEffective) {
-          return globalCol
-        }
-        return globalColToVisibleCol(blanks, globalCol)
+       * #action
+       */
+      setScrollX(n: number) {
+        self.scrollX = clamp(n, self.maxScrollX, 0)
       },
 
       /**
-       * #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)
+      setColumnTracks(tracks: ColumnTrackSpec[]) {
+        self.columnTracks.replace(tracks)
       },
-
       /**
-       * #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
+       * replace the row table, which the model keeps as the JSON string
+       * `data.treeMetadata` (see docs/layers.md)
        */
-      seqPosToVisibleCol(rowName: string, seqPos: number) {
-        const globalCol = this.seqPosToGlobalCol(rowName, seqPos)
-        return this.globalColToVisibleCol(globalCol)
+      setRowData(rowData: Record<string, Record<string, string>>) {
+        self.data.setTreeMetadata(JSON.stringify(rowData))
       },
-    }))
-
-    .views(self => ({
       /**
-       * #getter
-       * widget width minus the tree area gives the space for the MSA
+       * #action
+       * replace what the viewer's marks read from the row table
        */
-      get msaAreaHeight() {
-        return (
-          self.height -
-          (self.showHorizontalScrollbar ? self.minimapHeight : 0) -
-          self.headerHeight
-        )
+      setEncodings(encodings: Encoding[]) {
+        self.encodings.replace(encodings)
       },
       /**
-       * #getter
-       * total height of track area (px)
+       * #action
+       * replace the panels drawn between the tree and the alignment
        */
-      get totalTrackAreaHeight() {
-        return sum(self.turnedOnTracks.map(r => r.model.height))
+      setRowPanels(panels: RowPanelSpec[]) {
+        self.rowPanels.replace(panels)
       },
       /**
-       * one representative annotation per accession, which is what the legend,
-       * the filter dialog and the palettes key off
+       * #action
+       * replace the alignment<->structure correspondence (see docs/layers.md)
        */
-      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
+      setResidueMappings(mappings: ResidueMapping[]) {
+        self.residueMappings.replace(mappings)
       },
-      get filteredAnnotations() {
-        return self.annotations.filter(r =>
-          self.featureFilters.get(r.accession),
+      /**
+       * #action
+       */
+      toggleTrack(id: string) {
+        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 => ({
@@ -1953,18 +3175,78 @@ function stateModelFactory() {
       },
       /**
        * #getter
-       * width of the alignment canvas itself: the msa area less the vertical
-       * scrollbar sitting in it. Not usable from showHorizontalScrollbar, which
-       * feeds msaAreaHeight -> showVerticalScrollbar and would close a cycle
+       * width of the alignment canvas: the msa area less the vertical
+       * scrollbar. showHorizontalScrollbar must not read it, since that feeds
+       * msaAreaHeight -> showVerticalScrollbar and would form a cycle
        */
       get msaCanvasWidth() {
         return self.msaAreaWidth - this.verticalScrollbarWidth
       },
+      /**
+       * #method
+       * the cell at a visible column and row index, in the coordinates a host
+       * writes highlights in
+       */
+      cellAt(visibleCol: number, rowIndex?: number): Cell {
+        const column = self.visibleColToGlobalCol(visibleCol)
+        const row =
+          rowIndex === undefined ? undefined : self.leaves[rowIndex]?.data.name
+        return row === undefined
+          ? { column: column + 1 }
+          : {
+              column: column + 1,
+              row,
+              residue: self.visibleColToSeqPosOneBased(row, visibleCol),
+              letter: self.rowMap.get(row)?.[column],
+            }
+      },
+      /**
+       * #getter
+       * the cell under the pointer. Public API: MSAViewer's onCellHover
+       * reports it.
+       */
+      get hoveredCell() {
+        const { mouseCol, mouseRow } = self
+        return mouseCol === undefined
+          ? undefined
+          : this.cellAt(mouseCol, mouseRow)
+      },
+      /**
+       * #getter
+       * the cell a click pinned. Public API: MSAViewer's onCellClick reports it.
+       */
+      get clickedCell() {
+        const { mouseClickCol, mouseClickRow } = self
+        return mouseClickCol === undefined
+          ? undefined
+          : this.cellAt(mouseClickCol, mouseClickRow)
+      },
+      /**
+       * #getter
+       * the columns on screen. Public API: MSAViewer's onViewportChange reports
+       * it.
+       */
+      get viewport(): Viewport | undefined {
+        const { scrollX, colWidth, numColumns, viewInitialized } = self
+        if (numColumns === 0 || !viewInitialized) {
+          return undefined
+        }
+        const { xStart, xEnd } = visibleColRange({
+          offsetX: -scrollX,
+          blockWidth: this.msaCanvasWidth,
+          colWidth,
+        })
+        const last = Math.max(0, Math.min(xEnd, numColumns) - 1)
+        return {
+          startColumn: self.visibleColToGlobalCol(Math.min(xStart, last)) + 1,
+          endColumn: self.visibleColToGlobalCol(last) + 1,
+        }
+      },
       /**
        * #getter
        * ordinal segment types (exons etc.), ordered by sequence position so
-       * exon-1..exon-14 read left-to-right; colored by alternating shade and
-       * labeled by number rather than each getting a distinct hue + legend row
+       * exon-1..exon-14 run left-to-right; colored by alternating shade and
+       * labeled by number, with no legend row
        */
       get segmentDomainTypes() {
         return [...self.annotationTypes.values()]
@@ -1996,10 +3278,48 @@ function stateModelFactory() {
       get strokePalette() {
         return transform(this.fillPalette, ([key, val]) => [
           key,
-          colord(val).darken(0.1).toHex(),
+          outlineColor(val),
         ])
       },
 
+      /**
+       * #getter
+       * the encoding coloring the overlay's spans, undefined when none does,
+       * which leaves each span the color its accession takes in `fillPalette`
+       */
+      get featureFillEncoding(): ResolvedEncoding | undefined {
+        return this.resolvedEncodings.find(e => e.channel === 'featureFill')
+      },
+
+      /**
+       * #getter
+       * the fill and outline of every feature's span: its own GFF `color=`
+       * first, then the `featureFill` scale, then the accession palette.
+       * Computed once per change of the features, the encodings or the palette
+       */
+      get featureColors(): Map<Annotation, { fill: string; stroke: string }> {
+        return featureColorMap(
+          self.filteredAnnotations,
+          this.featureFillEncoding,
+          this.fillPalette,
+        )
+      },
+
+      /**
+       * #getter
+       * the text the `featureLabel` channel draws inside each span, undefined
+       * when no encoding names the channel. A data channel, so it draws
+       * whether or not the residue letters do
+       */
+      get featureLabels(): Map<Annotation, string> | undefined {
+        const encoding = this.resolvedEncodings.find(
+          e => e.channel === 'featureLabel',
+        )
+        return encoding
+          ? featureLabelMap(self.filteredAnnotations, encoding.field)
+          : undefined
+      },
+
       /**
        * #getter
        * accession -> number drawn on each segment band: the trailing number of
@@ -2017,25 +3337,104 @@ function stateModelFactory() {
       /**
        * #getter
        * the domain types currently drawn on the alignment (filtered-on), shared
-       * by the on-screen legend and the SVG export legend. Ordinal segments
-       * (exons) are excluded — they read as a numbered gene model, not a color
-       * key — so this is the categorical types ordered by sequence position
+       * by the on-screen legend and the SVG export legend: the categorical types
+       * ordered by sequence position. Ordinal segments (exons) are numbered on
+       * the band instead
        */
       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)
       },
 
+      /**
+       * #getter
+       * the categorical color keys drawn for this view, shared by the on-screen
+       * legend overlay and the SVG export's reserved column. The domain overlay
+       * produces the first, listing the `featureFill` scale where an encoding
+       * names one. Every field a row-table encoding or a row panel reads
+       * produces one more, so two channels over one field, or two strips over
+       * it, list that field once. A strip's `legend` names the title it lists
+       * under, so strips over eight fields with one set of colors list one
+       * legend between them
+       */
+      get legends(): Legend[] {
+        const { featureFillEncoding, fillPalette, visibleDomainTypes } = this
+        const byKey = new Map<string, Legend>()
+        // the accession palette keys on no field, so it takes a key of its own
+        const add = (
+          field: string | undefined,
+          entries: LegendEntry[],
+          id?: string,
+        ) => {
+          if (entries.length === 0) {
+            return
+          }
+          const key = field === undefined ? 'domains' : `field:${field}`
+          const legend = byKey.get(key)
+          if (legend) {
+            const seen = new Set(legend.entries.map(e => e.id))
+            legend.entries.push(...entries.filter(e => !seen.has(e.id)))
+          } else {
+            byKey.set(key, {
+              id: id ?? (field === undefined ? 'domains' : `rowData-${field}`),
+              title: field ?? 'Domains',
+              entries: [...entries],
+            })
+          }
+        }
+        // the overlay draws the domain key; with no columns it draws nothing,
+        // and a features panel taking the same colors lists them instead
+        if (self.actuallyShowDomains && self.numColumns > 0) {
+          add(
+            featureFillEncoding?.field,
+            featureFillEncoding
+              ? featureFillEncoding.legend
+              : visibleDomainTypes.map(d => ({
+                  id: d.accession,
+                  label: d.name,
+                  color: fillPalette[d.accession]!,
+                })),
+            'domains',
+          )
+        }
+        for (const { channel, field, legend } of this.resolvedEncodings) {
+          if (!featureChannels.has(channel)) {
+            add(field, legend)
+          }
+        }
+        for (const { legendTitle, legend } of this.resolvedRowPanels) {
+          add(legendTitle, legend)
+        }
+        return [...byKey.values()]
+      },
+
+      /**
+       * #getter
+       * whether the overlay marks each domain with a bar under its row instead
+       * of filling the row behind the letters. Letter-color mode hands the
+       * background to the color scheme, so a filled box would paint over it and
+       * leave the setting with nothing to show. Sub-row layout already stacks
+       * the boxes clear of the letters, and with the letters too small to draw
+       * the filled box is the only thing left to read.
+       */
+      get domainUnderline() {
+        return (
+          self.actuallyShowDomains &&
+          !self.bgColor &&
+          !self.subFeatureRows &&
+          self.showMsaLetters
+        )
+      },
+
       /**
        * #getter
        * every filtered-on annotation resolved to the visible column span it is
        * drawn across, keyed by row name. Each row is ordered longest-first so a
-       * short domain nested inside a long one draws on top of it rather than
-       * under it. Resolving these once here rather than inside each canvas
-       * block removes a per-feature, per-block sequence position conversion
-       * from every redraw, and gives the letter renderer the band colors it
-       * needs to keep residues readable on top of the boxes.
+       * nested short domain draws on top, and each band carries the lane the
+       * sub-row layout puts it in. Resolved once here instead of per canvas
+       * block per redraw; the letter renderer also reads the band colors to
+       * pick legible letter colors.
        */
       get domainBands() {
         const { blanks } = self
@@ -2046,32 +3445,27 @@ function stateModelFactory() {
           const rowBands = annotations
             .toSorted((a, b) => len(b) - len(a))
             .map(annotation => {
-              // annotation positions are 1-based and inclusive. Both ends count
-              // the visible columns in front of a global column, so endCol is
-              // the exclusive column after the last residue's own column --
-              // the band stops there rather than stretching across a following
-              // 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,
-              )
+              // annotation positions are 1-based and inclusive. endCol is
+              // exclusive, one past the last residue's column, so the band does
+              // not extend over a following gap run. An endpoint in a hidden
+              // column moves to the neighboring boundary. Bands with no visible
+              // columns, or naming a missing row, are dropped.
+              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
             })
             .filter(notEmpty)
-            // numbered after the drop, so a band that resolved to nothing does
-            // not leave an empty sub-row behind it
+            // numbered after filtering, so a dropped band leaves no gap
             .map((band, stackIndex) => ({ ...band, stackIndex }))
           if (rowBands.length > 0) {
-            bands.set(name, rowBands)
+            bands.set(name, packDomainLanes(rowBands))
           }
         }
         return bands
@@ -2099,14 +3493,16 @@ 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)
+        return hits.length > 0 ? hits : noDomains
       },
 
       /**
@@ -2124,8 +3520,7 @@ function stateModelFactory() {
        * #getter
        * row indices highlighted by the current tree hover (a hovered internal
        * node highlights every tip below it). Shared by the tree and MSA overlay
-       * canvases so they cannot disagree, and resolved through the memoized
-       * name->index map rather than rebuilding a lookup on each mouse move.
+       * canvases, via the memoized name->index map.
        */
       get hoveredRowIndices() {
         const { hoveredTreeNode, rowNamesSet } = self
@@ -2139,8 +3534,8 @@ function stateModelFactory() {
       /**
        * #getter
        * contiguous runs of `highlightedColumns`, so a run of highlighted columns
-       * draws as one bordered band. Computed here because the overlay canvas
-       * redraws on every mouse move while the highlight itself rarely changes.
+       * draws as one bordered band. Memoized because the overlay canvas redraws
+       * on every mouse move.
        */
       get highlightedColumnRuns() {
         const { highlightedColumns } = self
@@ -2166,89 +3561,289 @@ function stateModelFactory() {
        * is dropped. Row names that match no row are ignored.
        */
       get resolvedHighlights(): ResolvedHighlight[] {
-        const { blanks, rowNamesSet, rowMap } = 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) {
-              return []
+        const { rowNamesSet, transientHighlights } = self
+        // persisted highlights first, so transient ones draw on top
+        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 []
+          }
+          const span = self.visibleSpan({ row, start, end })
+          return span ? [{ ...base, ...span, rowIndices: [] }] : []
+        })
+      },
+
+      /**
+       * #method
+       * per-column summary statistics: consensus residue and its identity
+       * fraction, both conservation scores, gap fraction, and the sorted non-gap
+       * residue distribution. undefined past the end of the alignment or for an
+       * all-gap column.
+       */
+      columnStatsAt(col: number): ColumnStats | undefined {
+        const { colStats, conservation, propertyConservation } = self
+        return columnStats({
+          col,
+          colStats,
+          conservation,
+          propertyConservation,
+        })
+      },
+
+      /**
+       * #getter
+       * `columnStatsAt` for the hovered column, undefined when nothing is
+       * hovered
+       */
+      get mouseOverColumnStats(): ColumnStats | undefined {
+        const { mouseCol, colStats, conservation, propertyConservation } = self
+        return mouseCol === undefined
+          ? undefined
+          : columnStats({
+              col: mouseCol,
+              colStats,
+              conservation,
+              propertyConservation,
+            })
+      },
+
+      /**
+       * #method
+       */
+      getRowData(name: string) {
+        return {
+          data: self.MSA?.getRowData(name),
+          rowData: self.rowDataOf(name),
+        }
+      },
+
+      /**
+       * #getter
+       * each encoding with its scale resolved against the values its field
+       * takes: a feature channel reads them across the features drawn, every
+       * other channel across the row table. Resolved once per change of that
+       * table or the encodings, never per row per frame.
+       */
+      get resolvedEncodings(): ResolvedEncoding[] {
+        const rows = Object.values(self.rowData)
+        const features = self.filteredAnnotations
+        return self.encodings.map(encoding => ({
+          ...encoding,
+          ...resolveScale(
+            encoding.scale,
+            featureChannels.has(encoding.channel)
+              ? features
+                  .map(a => featureField(a, encoding.field))
+                  .filter(notEmpty)
+              : rows.map(row => row?.[encoding.field]).filter(notEmpty),
+          ),
+        }))
+      },
+
+      /**
+       * #getter
+       * each row panel with its scale resolved against the values its field
+       * takes across the row table, giving the color per row name, the pixel
+       * column it draws in, and the entries its legend lists. Resolved once
+       * per change of that table or the panels, never per block per frame.
+       */
+      get resolvedRowPanels(): ResolvedRowPanel[] {
+        const rows = Object.entries(self.rowData)
+        const { fillPalette, featureFillEncoding, featureLabels } = this
+        const annotations = self.filteredAnnotations
+        let offsetX = 0
+        return self.rowPanels.map((panel, index) => {
+          const width = rowPanelWidth(panel, self.rowHeight)
+          const base = { id: `rowpanel-${index}`, width, offsetX }
+          offsetX += width
+          if (panel.kind === 'features') {
+            const color = panel.encoding?.color
+            const encoding = color
+              ? resolveFeatureScale(color.field, color.scale, annotations)
+              : featureFillEncoding
+            const label = panel.encoding?.label
+            const align = panel.transform?.find(t => t.type === 'align')
+            return {
+              ...base,
+              kind: panel.kind,
+              x: panel.x,
+              header: panel.header ?? '',
+              field: encoding?.field,
+              legendTitle: encoding?.field,
+              spans: featurePanelSpans({
+                panel,
+                width,
+                rowHeight: self.rowHeight,
+                colWidth: self.colWidth,
+                domainBands: this.domainBands,
+                annotationsByRow: self.annotationsByRow,
+                shifts: align
+                  ? this.featureAlignShifts.get(align.on)
+                  : undefined,
+              }),
+              colors: featureColorMap(annotations, encoding, fillPalette),
+              labels: label
+                ? featureLabelMap(annotations, label)
+                : featureLabels,
+              legend:
+                encoding?.legend ??
+                this.visibleDomainTypes.map(d => ({
+                  id: d.accession,
+                  label: d.name,
+                  color: fillPalette[d.accession]!,
+                })),
             }
-            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 { colorOf, legend } = resolveScale(
+            panel.scale,
+            rows.map(([, row]) => row?.[panel.field]).filter(notEmpty),
+          )
+          const colors = new Map<string, string>()
+          for (const [name, row] of rows) {
+            const value = row?.[panel.field]
+            const color = value === undefined ? undefined : colorOf(value)
+            if (color) {
+              colors.set(name, color)
             }
-            const startCol = toVisible(startGlobal)
-            const endVisible = self.globalColToVisibleCol(endGlobal)
-            const endCol =
-              endVisible ?? visibleColsBefore(blanks, endGlobal) - 1
-            return startCol <= endCol
-              ? [{ ...base, startCol, endCol, rowIndices: [] }]
-              : []
-          },
+          }
+          return {
+            ...base,
+            kind: panel.kind,
+            field: panel.field,
+            header: panel.header ?? panel.field,
+            legendTitle: panel.legend ?? panel.field,
+            colors,
+            legend,
+          }
+        })
+      },
+
+      /**
+       * #getter
+       * the shift an `align` transform gives each row, keyed by the feature
+       * name it aligns on: the offset putting the first feature of that name
+       * at zero. A row carrying no such feature is absent, and keeps its own
+       * origin.
+       */
+      get featureAlignShifts(): Map<string, Map<string, number>> {
+        const names = new Set(
+          self.rowPanels.flatMap(panel =>
+            panel.kind === 'features' && panel.x === 'position'
+              ? (panel.transform ?? [])
+                  .filter(t => t.type === 'align')
+                  .map(t => t.on)
+              : [],
+          ),
+        )
+        return new Map(
+          [...names].map(on => [
+            on,
+            new Map(
+              Object.entries(self.annotationsByRow)
+                .map(([name, annotations]) => {
+                  const hit = annotations.find(a => featureName(a) === on)
+                  return hit ? ([name, 1 - hit.start] as const) : undefined
+                })
+                .filter(notEmpty),
+            ),
+          ]),
         )
       },
 
       /**
        * #getter
-       * per-column summary statistics for the hovered column: consensus residue
-       * and its identity fraction, conservation score, gap fraction, and the
-       * sorted non-gap residue distribution. undefined when nothing is hovered.
+       * the color the `tipLabel` channel gives each row, by row name. Undefined
+       * when no encoding names the channel, which leaves the labels the theme's
+       * text color.
        */
-      get mouseOverColumnStats() {
-        const { mouseCol } = self
-        if (mouseCol === undefined) {
+      get tipLabelColors(): Map<string, string> | undefined {
+        const encoding = this.resolvedEncodings.find(
+          e => e.channel === 'tipLabel',
+        )
+        if (!encoding) {
           return undefined
         }
-        const { colStats } = self
-        if (mouseCol >= colStats.numColumns) {
-          return undefined
+        const colors = new Map<string, string>()
+        for (const [name, row] of Object.entries(self.rowData)) {
+          const value = row?.[encoding.field]
+          const color =
+            value === undefined ? undefined : encoding.colorOf(value)
+          if (color) {
+            colors.set(name, color)
+          }
         }
-        const total = colStats.total(mouseCol)
-        if (!total) {
+        return colors
+      },
+
+      /**
+       * #getter
+       * the wash the `rowTint` channel draws over each row, indexed by row, or
+       * undefined when no encoding names the channel. The overlay draws these,
+       * so a tint stays out of the raster tile cache and its keys.
+       */
+      get rowTints(): (string | undefined)[] | undefined {
+        const encoding = this.resolvedEncodings.find(
+          e => e.channel === 'rowTint',
+        )
+        if (!encoding) {
           return undefined
         }
-        const gaps = colStats.gapCount(mouseCol)
-        const distribution = colStats
-          .residueEntries(mouseCol)
-          .sort((a, b) => b[1] - a[1])
-        const consensus = distribution[0]
-        return {
-          col: mouseCol,
-          total,
-          gaps,
-          gapFraction: gaps / total,
-          conservation: self.conservation[mouseCol] ?? 0,
-          propertyConservation: self.propertyConservation[mouseCol],
-          consensusLetter: consensus?.[0] ?? '',
-          consensusCount: consensus?.[1] ?? 0,
-          consensusFraction: consensus ? consensus[1] / total : 0,
-          distribution,
-        }
+        return self.rowNames.map(name => {
+          const value = self.rowDataOf(name)?.[encoding.field]
+          const color =
+            value === undefined ? undefined : encoding.colorOf(value)
+          if (!color) {
+            return undefined
+          }
+          return withAlpha(color, rowTintAlpha)
+        })
       },
 
       /**
-       * #method
+       * #getter
+       * the color the `branch` channel gives each tree edge, by the node id at
+       * the edge's far end, or undefined when no encoding names the channel. A
+       * node takes the field value its tips agree on, so a clade of one value
+       * colors down from where it splits off, and a node whose tips disagree or
+       * whose value has no color is absent and draws in the default color.
+       *
+       * The pass runs over the whole tree, never `root`, so a collapsed or
+       * focused clade keeps the color the full tree gives it.
        */
-      getRowData(name: string) {
-        return {
-          data: self.MSA?.getRowData(name),
-          treeMetadata: self.treeMetadata[name],
+      get branchColors(): Map<string, string> | undefined {
+        const encoding = this.resolvedEncodings.find(
+          e => e.channel === 'branch',
+        )
+        if (!encoding) {
+          return undefined
+        }
+        const order = preorder(self.tree)
+        const values = new Map<NodeWithIds, string | undefined>()
+        const colors = new Map<string, string>()
+        for (let i = order.length - 1; i >= 0; i--) {
+          const node = order[i]!
+          const value =
+            node.children.length > 0
+              ? sharedValue(node.children.map(child => values.get(child)))
+              : self.rowDataOf(node.name)?.[encoding.field]
+          values.set(node, value)
+          const color =
+            value === undefined ? undefined : encoding.colorOf(value)
+          if (color) {
+            colors.set(node.id, color)
+          }
         }
+        return colors
       },
     }))
     .actions(self => ({
@@ -2261,23 +3856,39 @@ function stateModelFactory() {
       /**
        * #action
        */
-      setConservationTrackHeight(arg: number) {
-        self.conservationTrackHeight = arg
+      setHideHeader(arg: boolean) {
+        self.hideHeader = arg
+      },
+      /**
+       * #action
+       * focus the subtree a click `y` pixels down the tree overview lands on.
+       * A click inside the box already drawn there clears the focus, the way
+       * clicking the focused branch again does.
+       */
+      treeOverviewClick(y: number) {
+        const hit = self.treeOverviewHit(y)
+        const focus = self.treeOverviewFocusRows
+        const inside =
+          !!focus && !!hit && hit.rows[0] >= focus[0] && hit.rows[1] <= focus[1]
+        self.setShowOnly(inside || !hit ? undefined : hit.id)
       },
       /**
        * #action
+       * resize every track sharing a `heightKey`; see `trackHeights`
        */
-      setSequenceLogoTrackHeight(arg: number) {
-        self.sequenceLogoTrackHeight = arg
+      setTrackHeight(heightKey: string, height: number) {
+        self.trackHeights.set(heightKey, height)
       },
       /**
        * #action
-       * Return to the import form: every property off `preservedOnReset`
-       * (data, filehandles, collapsed/showOnly, zoom, scroll, ...) goes back
-       * to its default, then the file-derived volatiles applySnapshot cannot
-       * reach are cleared by hand.
+       * Return to the import form: reset every property not in
+       * `preservedOnReset` to its default, then clear the file-derived
+       * volatiles applySnapshot does not touch.
        */
       reset() {
+        self.resetCount++
+        self.clearWarnings()
+        self.setStatus(undefined)
         applySnapshot(
           self,
           Object.fromEntries(
@@ -2289,6 +3900,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 +3914,31 @@ 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
+       * show or hide an annotation type. Only hidden types are 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()
+        // two passes: each direction's viewport depends on whether the other
+        // overflows (the minimap takes height, the vertical scrollbar width)
+        transaction(() => {
+          for (let pass = 0; pass < 2; pass++) {
+            this.fitHorizontally()
+            this.fitVertically()
+          }
+        })
       },
       /**
        * #action
@@ -2331,14 +3953,36 @@ function stateModelFactory() {
         }
         self.scrollY = 0
       },
+      /**
+       * #action
+       * zoom and scroll so a span fills the alignment's width, in highlight
+       * coordinates (see visibleSpan). Does nothing before the viewer knows
+       * its width, or for a span that resolves to no visible column.
+       */
+      zoomToRegion(region: Region) {
+        const span = self.visibleSpan(region)
+        if (!span || !self.viewInitialized) {
+          return
+        }
+        transaction(() => {
+          self.colWidth = clamp(
+            self.msaCanvasWidth / (span.endCol - span.startCol + 1),
+            minColWidth,
+            maxCellSize,
+          )
+          self.scrollX = clamp(
+            -span.startCol * self.colWidth,
+            self.maxScrollX,
+            0,
+          )
+        })
+      },
       /**
        * #action
        */
       fitHorizontally() {
         if (self.numColumns > 0) {
-          // fitting to msaAreaWidth instead left the last ~20px of columns off
-          // the right edge -- and short of the width that shows a minimap, so
-          // nothing on screen said they were there
+          // msaCanvasWidth excludes the vertical scrollbar's 20px
           self.colWidth = clamp(
             self.msaCanvasWidth / self.numColumns,
             minColWidth,
@@ -2349,26 +3993,43 @@ function stateModelFactory() {
       },
 
       afterCreate() {
-        // seed the highlighted-columns overlay from the declarative property so
-        // a shared snapshot/URL opens with those columns highlighted (the
-        // volatile highlightedColumns can later be driven by genome-hover sync)
         if (self.highlightColumns?.length) {
           self.setHighlightedColumns(self.highlightColumns)
         }
 
+        // The `collapse` and `focus` clade marks seed the collapsed list and
+        // the subtree in focus, which the tree, `hideGapsEffective` and the
+        // alignment all read. The tree arrives with the model for inline data
+        // and later for a filehandle, so the seeding waits for it and then runs
+        // once: expanding a seeded clade sticks, and the record collapses it
+        // again only on reload.
+        let cladesSeeded = false
         addDisposer(
           self,
           autorun(() => {
-            for (const key of self.annotationTypes.keys()) {
-              this.initFilter(key)
+            if (
+              cladesSeeded ||
+              !self.dataInitialized ||
+              self.clades.length === 0
+            ) {
+              return
+            }
+            cladesSeeded = true
+            for (const { mark, nodeId } of self.resolvedClades) {
+              if (nodeId === undefined) {
+                continue
+              }
+              if (mark === 'collapse' && !self.collapsed.includes(nodeId)) {
+                self.toggleCollapsed(nodeId)
+              } else if (mark === 'focus') {
+                self.setShowOnly(nodeId)
+              }
             }
           }),
         )
 
-        // 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
-        // re-registers against the new one to keep tracking further moves.
+        // the matchMedia query is pinned to the current device pixel ratio, so
+        // each change re-registers against the new one
         if (
           typeof window !== 'undefined' &&
           typeof window.matchMedia === 'function'
@@ -2392,44 +4053,57 @@ function stateModelFactory() {
          * Fetch a filehandle whenever it changes, and hand the text to
          * `onLoad`.
          *
-         * 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.
+         * A generation guard keeps a slower superseded request from overwriting
+         * the newer one's data, status or loading flag. A superseded or cleared
+         * request is aborted and clears its status line.
          *
-         * `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.
+         * `clearFilehandle` runs after a local file loads, since a blob has no
+         * URL to refetch, and when the user cancels, which returns the view to
+         * the import form.
+         *
+         * `what` names the layer in a failure message. An `optional` layer
+         * (annotations, row metadata) that fails adds a warning instead of an
+         * error.
          */
         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 +4114,7 @@ function stateModelFactory() {
                       self.setStatus(status)
                     }
                   },
+                  { controller },
                 )
                 if (isCurrent()) {
                   transaction(() => {
@@ -2455,11 +4130,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 +4148,7 @@ function stateModelFactory() {
         }
 
         loadOnFilehandleChange({
+          what: 'tree',
           getFilehandle: () => self.treeFilehandle,
           onLoad: text => {
             self.setTree(text)
@@ -2480,16 +4161,19 @@ 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
+        // treeMetadata has no import-form step, so no loading flag or cancel
         loadOnFilehandleChange({
+          what: 'row metadata',
+          optional: true,
           getFilehandle: () => self.treeMetadataFilehandle,
           onLoad: text => {
             self.setTreeMetadata(text)
           },
         })
 
-        // autorun parses inline gff text from data.gff
+        // parses data.gff into annotations. Clearing the text clears only the
+        // annotations this autorun applied, not ones a host set directly
+        let appliedGFF = false
         addDisposer(
           self,
           autorun(() => {
@@ -2497,19 +4181,25 @@ function stateModelFactory() {
             if (gffText) {
               try {
                 self.applyGFFText(gffText)
+                appliedGFF = true
               } catch (e) {
                 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 loads into data.gff, which the autorun above parses
         loadOnFilehandleChange({
+          what: 'annotations',
+          optional: true,
           getFilehandle: () => self.gffFilehandle,
           onLoad: text => {
-            self.applyGFFText(text)
+            self.setGFF(text)
           },
           clearFilehandle: () => {
             self.setGFFFilehandle(undefined)
@@ -2517,6 +4207,7 @@ function stateModelFactory() {
         })
 
         loadOnFilehandleChange({
+          what: 'alignment',
           getFilehandle: () => self.msaFilehandle,
           onLoad: text => {
             self.setMSA(text)
@@ -2529,19 +4220,12 @@ function stateModelFactory() {
           },
         })
 
-        // Keep the parse chain warm: reading self.columns transitively holds
-        // self.MSA (parseMSA) computed alive, so it is parsed once per data
-        // change rather than re-parsed on every non-reactive access. Do not
-        // remove.
+        // Keep computeds alive that are read outside reactions, so they are not
+        // recomputed on every access: self.columns (and through it the
+        // parseMSA result), and the column statistics that dynamic color
+        // schemes and the mousemove-driven hover tooltip read.
         // xref solution https://github.com/mobxjs/mobx/issues/266#issuecomment-222007278
         // xref problem https://github.com/GMOD/react-msaview/issues/75
-        //
-        // The column statistics are held for the same reason whenever something
-        // reads them off the reactive path: dynamic color schemes, and the hover
-        // tooltip, which is read from a mousemove handler. Without this the
-        // tooltip's cost depends on whether some visible track happens to be
-        // observing them, so closing the conservation track would silently turn
-        // every mouse move into a full-alignment recount.
         addDisposer(
           self,
           autorun(() => {
@@ -2563,10 +4247,9 @@ function stateModelFactory() {
           }),
         )
 
-        // autorun: when autoTreeAreaWidth is set and no tree is drawn, shrink the
-        // tree area to fit the row labels rather than padding it to the fixed
-        // default. Gated on noTree/!drawTree so it never fights the treeWidth sync
-        // below (treeAreaWidth here depends only on labelsWidth, not treeWidth).
+        // with autoTreeAreaWidth and no tree drawn, size the tree area to the
+        // labels. Gated on noTree/!drawTree so it does not loop with the
+        // treeWidth autorun below
         addDisposer(
           self,
           autorun(() => {
@@ -2575,19 +4258,36 @@ function stateModelFactory() {
               (self.noTree || !self.drawTree) &&
               self.labelsWidth
             ) {
-              self.setTreeAreaWidth(self.labelsWidth + self.marginLeft + 12)
+              self.setTreeAreaWidth(
+                self.labelsWidth + self.marginLeft + 12 + self.cladeGutterWidth,
+              )
             }
           }),
         )
 
-        // autorun synchronizes treeWidth with treeAreaWidth
+        // treeWidth follows the tree area less the labels. A non-default
+        // snapshot treeWidth (jbrowse-plugin-msaview opens at 100 in a 200px
+        // area) is kept until the tree area changes. Not a getter, because
+        // labelsWidth is measured off leaves 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,
+                areaWidth -
+                  labelsWidth -
+                  10 -
+                  self.marginLeft -
+                  self.cladeGutterWidth,
               ),
             )
           }),
@@ -2595,9 +4295,8 @@ function stateModelFactory() {
       },
     }))
     .postProcessSnapshot(({ data, columnTracks, ...rest }) => ({
-      // per-property defaults are stripped by the stripDefault helper; the only thing
-      // it can't express is this cross-field rule: drop inline tree/msa/metadata
-      // when a sibling filehandle can refetch them, keeping sessions/URLs small
+      // stripDefault handles per-property defaults; this drops inline documents
+      // whose filehandle can refetch them
       ...rest,
       ...smallColumnTracks(columnTracks),
       data: {