react-msaview 8.1.0 → 8.3.0

package/src/model.ts

@@ -9,7 +9,13 @@ import {
   isAlive,
   types,
 } from '@jbrowse/mobx-state-tree'
-import { autorun, computed, transaction } from 'mobx'
+import {
+  autorun,
+  compareStructural,
+  computed,
+  reaction,
+  transaction,
+} from 'mobx'
 import {
   generateNodeIds,
   gffToAnnotations,
@@ -74,10 +80,10 @@ import {
   calcDepthToLeaf,
   clusterLayout,
   collapse,
-  collapsedSubtreeMaxLength,
   find,
   forEachDescendant,
   hierarchy,
+  layoutTree,
   leafIndex,
   leaves,
   maxLength,
@@ -95,6 +101,7 @@ import { TreeModelF } from './model/treeModel.ts'
 import { calculateNeighborJoiningTree } from './neighborJoining.ts'
 import { parseAsn1 } from './parseAsn1.ts'
 import { calculatePropertyConservation } from './propertyConservation.ts'
+import { midpointRoot, rerootTree } from './rerootTree.ts'
 import {
   globalColToVisibleCol,
   seqPosOfGlobalCol,
@@ -114,12 +121,14 @@ import {
   withAlpha,
 } from './util.ts'
 import { saveAs } from './vendor/fileSaver.ts'
+import { writeNewick } from './writeNewick.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 { TreeNode } from './rerootTree.ts'
 import type { ScaleSpec } from './scales.ts'
 import type {
   Annotation,
@@ -127,6 +136,7 @@ import type {
   BasicTrack,
   Cell,
   Clade,
+  CladeMark,
   ResidueMappingProblem,
   ColumnTrackSpec,
   DomainBand,
@@ -136,14 +146,17 @@ import type {
   Legend,
   LegendEntry,
   NodeWithIds,
-  NodeWithIdsAndLength,
   Region,
   ResidueMapping,
   ResidueSegment,
   ResolvedClade,
   ResolvedEncoding,
+  ResolvedFeaturePanel,
   ResolvedHighlight,
+  TreeOrder,
+  TreeRoot,
   ResolvedRowPanel,
+  ResolvedStripPanel,
   RowFeaturesSpec,
   RowPanelSpan,
   RowPanelSpec,
@@ -202,14 +215,39 @@ const UNSCALED_FEATURE = '#d9d9d9'
 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) {
+// cell square, and a gene neighborhood's width for a features panel. The row
+// height is read only when used, so a panel with a width of its own does not
+// recompute on a vertical zoom
+function rowPanelWidth(panel: RowPanelSpec, view: { rowHeight: number }) {
   return (
     panel.width ??
-    (panel.kind === 'features' ? defaultFeaturePanelWidth : rowHeight)
+    (panel.kind === 'features' ? defaultFeaturePanelWidth : view.rowHeight)
   )
 }
 
+// the color each row takes from a field of the row table under a scale
+function colorByRow(
+  rowData: Record<string, Record<string, string> | undefined>,
+  field: string,
+  colorOf: (value: string) => string | undefined,
+) {
+  const colors = new Map<string, string>()
+  for (const [name, row] of Object.entries(rowData)) {
+    const value = row?.[field]
+    const color = value === undefined ? undefined : colorOf(value)
+    if (color) {
+      colors.set(name, color)
+    }
+  }
+  return colors
+}
+
+type StripPanelScale = Omit<ResolvedStripPanel, 'id' | 'width' | 'offsetX'>
+type FeaturePanelScale = Omit<
+  ResolvedFeaturePanel,
+  'id' | 'width' | 'offsetX' | 'spans'
+>
+
 // 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
@@ -402,10 +440,21 @@ function resolveFeatureScale(
   }
 }
 
+const columnTrackBytes = new WeakMap<ColumnTrackSpec, number>()
+
+function columnTrackSize(track: ColumnTrackSpec) {
+  let bytes = columnTrackBytes.get(track)
+  if (bytes === undefined) {
+    bytes = JSON.stringify(track).length
+    columnTrackBytes.set(track, bytes)
+  }
+  return bytes
+}
+
 // a data track over this size stays in the live model but leaves the snapshot,
 // the same rule DataModel applies to an inline document
 function columnTrackSizes(tracks?: readonly ColumnTrackSpec[]) {
-  return (tracks ?? []).map(t => JSON.stringify(t).length)
+  return (tracks ?? []).map(columnTrackSize)
 }
 
 function smallColumnTracks(tracks?: ColumnTrackSpec[]) {
@@ -441,6 +490,7 @@ export const preservedOnReset = new Set([
   'treeAreaWidth',
   'treeWidth',
   'showBranchLen',
+  'treeOrder',
   'drawTree',
   'drawNodeBubbles',
   'drawNodeLabels',
@@ -467,6 +517,9 @@ function trackIsOff(
   return turnedOffTracks.get(id) ?? (defaultOff || defaultOffTracks.has(id))
 }
 
+// the marks that set tree state from a node rather than drawing
+const seedingMarks = new Set<CladeMark>(['collapse', 'focus', 'rotate'])
+
 // shared empty results, so observers don't see a fresh [] as a change
 const noDomains: Annotation[] = []
 const noClades: ResolvedClade[] = []
@@ -519,8 +572,7 @@ function cladeRows(
  * 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.
+ * `range` record names no node, so the seeding marks, which need one, drop it.
  */
 function resolveClades(
   clades: Clade[],
@@ -530,7 +582,7 @@ function resolveClades(
   const index = leafIndex(root)
   return clades.flatMap(clade => {
     const resolved = cladeRows(clade, root, index, rowNamesSet)
-    const seeding = clade.mark === 'collapse' || clade.mark === 'focus'
+    const seeding = seedingMarks.has(clade.mark)
     return resolved && !(seeding && resolved.nodeId === undefined)
       ? [
           {
@@ -548,20 +600,50 @@ function resolveClades(
   })
 }
 
+const childOrders: Record<
+  TreeOrder,
+  ((a: HierarchyNode, b: HierarchyNode) => number) | undefined
+> = {
+  input: undefined,
+  branchLength: (a, b) => (a.data.length ?? 1) - (b.data.length ?? 1),
+  ladderize: (a, b) => a.value! - b.value!,
+  ladderizeReverse: (a, b) => b.value! - a.value!,
+}
+
 /**
  * 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.
+ * put in `order` and each `rotated` node's reversed, `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,
+  {
+    collapsed,
+    rotated,
+    order,
+    showOnly,
+  }: {
+    collapsed: readonly string[]
+    rotated: readonly string[]
+    order: TreeOrder
+    showOnly?: string
+  },
 ) {
   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))
+  const compare = childOrders[order]
+  if (compare) {
+    sort(hier, compare)
+  }
+  if (rotated.length > 0) {
+    const flip = new Set(rotated)
+    forEachDescendant(hier, n => {
+      if (flip.has(n.data.id)) {
+        n.children?.reverse()
+      }
+    })
+  }
 
   if (showOnly) {
     const res = find(hier, n => n.data.id === showOnly)
@@ -586,6 +668,53 @@ function buildTreeRoot(
   return hier
 }
 
+/**
+ * The node whose branch an outgroup roots the tree on: the outgroup's most
+ * recent common ancestor, or the rest of the tips' where that ancestor is the
+ * root, since the outgroup then straddles the root and the branch above the
+ * other side is the same branch of the unrooted tree.
+ */
+function outgroupNode(root: HierarchyNode, outgroup: string[]) {
+  const index = leafIndex(root)
+  const node = mrca(root, outgroup, index)
+  if (node !== root) {
+    return node
+  }
+  const out = new Set(outgroup)
+  const rest = leaves(root)
+    .map(n => n.data.name)
+    .filter(name => !out.has(name))
+  const other = mrca(root, rest, index)
+  return other === root ? undefined : other
+}
+
+/**
+ * `tree` rerooted as `treeRoot` asks, with fresh path ids. The ids of the tree
+ * as written become names on unnamed nodes, and a rerooting would carry them
+ * along as labels, so they come off first.
+ */
+function rootTree(tree: NodeWithIds, treeRoot: TreeRoot) {
+  const plain = new Map<NodeWithIds, TreeNode>()
+  for (const node of preorder(tree).reverse()) {
+    plain.set(node, {
+      name: node.name === node.id ? undefined : node.name,
+      length: node.length,
+      children: node.children.map(c => plain.get(c)!),
+    })
+  }
+  const input = plain.get(tree)!
+  if (treeRoot === 'midpoint') {
+    return generateNodeIds(midpointRoot(input))
+  }
+  const target = outgroupNode(
+    hierarchy(tree, d => d.children),
+    treeRoot.outgroup,
+  )
+  return target
+    ? generateNodeIds(rerootTree(input, plain.get(target.data)!))
+    : tree
+}
+
 // 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] {
@@ -796,6 +925,22 @@ function stateModelFactory() {
          */
         collapsed: stripDefault(types.array(types.string), []),
 
+        /**
+         * #property
+         * tree nodes whose children draw in reverse order, which is ggtree's
+         * `rotate`: the same tree, with the clades on either side of the node
+         * swapped
+         */
+        rotated: stripDefault(types.array(types.string), []),
+
+        /**
+         * #property
+         * where the tree is rooted: `midpoint` roots it halfway along the
+         * longest path between two tips, `{outgroup}` on the branch above
+         * the tips named, and undefined keeps the file's root
+         */
+        treeRoot: types.frozen<TreeRoot | undefined>(),
+
         /**
          * #property
          * focus on particular subtree
@@ -877,12 +1022,21 @@ function stateModelFactory() {
          * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen<Highlight>()), []),
+        /**
+         * #property
+         * where the view opens, in `highlights` coordinates: `{row, start,
+         * end}` zooms onto residues of that row, `{start, end}` onto alignment
+         * columns. Applied once the alignment and any tree file have loaded,
+         * then cleared, so a reloaded session keeps the reader's own scroll.
+         */
+        region: types.frozen<Region | undefined>(),
         /**
          * #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`.
+         * measured. `mark` is `highlight`, `bracket`, `collapse`, `focus` or
+         * `rotate`.
          * See docs/layers.md
          */
         clades: stripDefault(types.array(types.frozen<Clade>()), []),
@@ -1015,9 +1169,16 @@ function stateModelFactory() {
        * #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
+       * alignment itself. `warnings` adds the ones derived from the data
+       */
+      loadWarnings: [] as string[],
+
+      /**
+       * #volatile
+       * derived warnings the user dismissed, which stay hidden while the data
+       * behind them holds
        */
-      warnings: [] as string[],
+      dismissedWarnings: [] as string[],
 
       /**
        * #volatile
@@ -1111,18 +1272,11 @@ function stateModelFactory() {
        * that failed to parse. A message already on the list is not added again
        */
       addWarning(warning: string) {
-        if (!self.warnings.includes(warning)) {
-          self.warnings = [...self.warnings, warning]
+        if (!self.loadWarnings.includes(warning)) {
+          self.loadWarnings = [...self.loadWarnings, warning]
         }
       },
 
-      /**
-       * #action
-       */
-      clearWarnings() {
-        self.warnings = []
-      },
-
       /**
        * #action
        * declare that this host restores the loaded documents itself, which
@@ -1156,6 +1310,12 @@ function stateModelFactory() {
       setHighlightedColumns(columns?: number[]) {
         self.highlightedColumns = columns
       },
+      /**
+       * #action
+       */
+      setRegion(region?: Region) {
+        self.region = region
+      },
       /**
        * #action
        */
@@ -1239,8 +1399,9 @@ 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
+       * Clears the collapsed and rotated node ids, the subtree in focus, the
+       * reference row and the scroll position, which all refer to the
+       * previous alignment
        */
       setCurrentAlignment(n: number) {
         if (n === self.currentAlignment) {
@@ -1249,6 +1410,7 @@ function stateModelFactory() {
         transaction(() => {
           self.currentAlignment = n
           self.collapsed.clear()
+          self.rotated.clear()
           this.setShowOnly(undefined)
           this.drawRelativeTo(undefined)
           self.scrollX = 0
@@ -1268,6 +1430,42 @@ function stateModelFactory() {
         }
       },
 
+      /**
+       * #action
+       * reverse the order of the given node's children, or restore it
+       */
+      toggleRotated(node: string) {
+        if (self.rotated.includes(node)) {
+          self.rotated.remove(node)
+        } else {
+          self.rotated.push(node)
+        }
+      },
+
+      /**
+       * #action
+       */
+      clearRotated() {
+        self.rotated.clear()
+      },
+
+      /**
+       * #action
+       * reroot the tree. Clears `collapsed`, `rotated` and `showOnly`, whose
+       * path-derived node ids name other nodes in the rerooted tree
+       */
+      setTreeRoot(treeRoot?: TreeRoot) {
+        if (compareStructural(self.treeRoot, treeRoot)) {
+          return
+        }
+        transaction(() => {
+          self.treeRoot = treeRoot
+          self.collapsed.clear()
+          self.rotated.clear()
+          this.setShowOnly(undefined)
+        })
+      },
+
       /**
        * #action
        * show only the subtree rooted at the given node id (pass undefined to
@@ -1444,12 +1642,13 @@ function stateModelFactory() {
        * 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.
+       * The header lists these, and the standalone app drops `?data=` from
+       * the address bar while the list is non-empty or the encoded link would
+       * pass 8,000 characters, so a copied link never opens an empty viewer
+       * unannounced. A document fetched from a URL never appears here, since
+       * the snapshot keeps its filehandle.
        *
-       * Empty when `hostRestoresData` is true.
+       * Empty when `hostCarriesData` is true.
        */
       get unshareableData(): UnshareableData[] {
         if (self.hostRestoresData) {
@@ -1546,8 +1745,9 @@ function stateModelFactory() {
 
       /**
        * #getter
+       * the tree the file or the alignment gives, before `treeRoot`
        */
-      get tree(): NodeWithIds {
+      get inputTree(): NodeWithIds {
         const text = self.data.tree
         return text
           ? generateNodeIds(parseTreeText(text))
@@ -1559,6 +1759,19 @@ function stateModelFactory() {
             })
       },
 
+      /**
+       * #getter
+       * the tree as the file or the alignment gives it, rerooted where
+       * `treeRoot` asks. Every node id, and so `collapsed`, `rotated` and
+       * `showOnly`, refers to this tree.
+       */
+      get tree(): NodeWithIds {
+        const tree = this.inputTree
+        return self.treeRoot && !tree.noTree
+          ? rootTree(tree, self.treeRoot)
+          : tree
+      },
+
       /**
        * #getter
        * Returns the list of row (sequence) names in display order.
@@ -1580,8 +1793,8 @@ function stateModelFactory() {
        * `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.
+       * clade. A `range` record names no node, so `collapse`, `focus` and
+       * `rotate`, which need one, drop it.
        */
       get resolvedClades(): ResolvedClade[] {
         if (self.clades.length === 0) {
@@ -1639,7 +1852,27 @@ function stateModelFactory() {
        * #getter
        */
       get root() {
-        return buildTreeRoot(this.tree, self.collapsed, self.showOnly)
+        return buildTreeRoot(this.tree, {
+          collapsed: self.collapsed,
+          rotated: self.rotated,
+          order: self.treeOrder,
+          showOnly: self.showOnly,
+        })
+      },
+
+      /**
+       * #getter
+       * the tree as Newick in the order and with the root it is drawn, with
+       * every clade, collapsed or out of focus
+       */
+      get treeNewick() {
+        return writeNewick(
+          buildTreeRoot(this.tree, {
+            collapsed: [],
+            rotated: self.rotated,
+            order: self.treeOrder,
+          }),
+        )
       },
 
       /**
@@ -1663,7 +1896,11 @@ function stateModelFactory() {
         if (!self.showTreeOverview) {
           return undefined
         }
-        const root = buildTreeRoot(this.tree, self.collapsed)
+        const root = buildTreeRoot(this.tree, {
+          collapsed: self.collapsed,
+          rotated: self.rotated,
+          order: self.treeOrder,
+        })
         const numTips = leaves(root).length
         clusterLayout(root, numTips, 1)
         const rootLen = Math.max(root.data.length || 0, 0)
@@ -1745,7 +1982,7 @@ function stateModelFactory() {
        * alignment, the sum of each record's width
        */
       get rowPanelsWidth() {
-        return sum(self.rowPanels.map(p => rowPanelWidth(p, self.rowHeight)))
+        return sum(self.rowPanels.map(p => rowPanelWidth(p, self)))
       },
       /**
        * #getter
@@ -1792,9 +2029,10 @@ function stateModelFactory() {
           return []
         }
         // ragged input (a3m, hand-edited fasta) can have rows shorter than the
-        // alignment; the widest row defines the column count and a row that
-        // stops early counts as gapped for the remainder
-        const numCols = strs.reduce((max, str) => Math.max(max, str.length), 0)
+        // alignment; the widest row of the whole alignment, collapsed rows
+        // included, defines the column count as it does for numColumns, and a
+        // row that stops early counts as gapped for the remainder
+        const numCols = this.MSA?.getWidth() ?? 0
         const numRows = strs.length
         const threshold = Math.ceil((realAllowedGappyness / 100) * numRows)
         const blankCounts = new Uint32Array(numCols)
@@ -1925,7 +2163,7 @@ function stateModelFactory() {
        * #getter
        */
       get colStats() {
-        return columnCountsFromRows(this.columns2d)
+        return columnCountsFromRows(this.columns2d, this.numColumns)
       },
 
       /**
@@ -2024,40 +2262,42 @@ function stateModelFactory() {
       },
       /**
        * #getter
-       * generates a new tree that is clustered with x,y positions
-       */
-      get hierarchy(): HierarchyNode<NodeWithIdsAndLength> {
-        const r = this.root
-        clusterLayout(r, this.totalHeight, self.treeWidth)
-        const max = this.rootToTipLength
-        const k = max ? self.treeWidth / max : 0
-        // 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
-        forEachDescendant(r, node => {
-          if (node._children) {
-            node.collapsedTipXFar =
-              (node.len ?? 0) + collapsedSubtreeMaxLength(node) * k
-          }
+       * `root` laid out on new nodes in row and branch-length units, read in
+       * pixels through `rowHeight` and `treeWidth`. A zoom leaves it and every
+       * node in it as they are, and an observer reading a node's `x` or `len`
+       * observes the size it scales by.
+       */
+      get treeLayout() {
+        return layoutTree(this.root, {
+          get rowHeight() {
+            return self.rowHeight
+          },
+          get treeWidth() {
+            return self.treeWidth
+          },
         })
-        return r as HierarchyNode<NodeWithIdsAndLength>
+      },
+
+      /**
+       * #getter
+       * the laid-out tree, with pixel positions on every node
+       */
+      get hierarchy(): HierarchyNode<NodeWithIds> {
+        return this.treeLayout.root
       },
 
       /**
        * #getter
        */
       get totalHeight() {
-        return leaves(this.root).length * self.rowHeight
+        return this.leaves.length * self.rowHeight
       },
 
       /**
        * #getter
        */
-      get leaves() {
-        return leaves(this.hierarchy)
+      get leaves(): HierarchyNode<NodeWithIds>[] {
+        return this.treeLayout.leaves
       },
 
       /**
@@ -2066,8 +2306,7 @@ function stateModelFactory() {
        * the tree's own units
        */
       get rootToTipLength() {
-        const r = this.root
-        return maxLength(r) - Math.max(r.data.length || 0, 0)
+        return this.treeLayout.rootToTipLength
       },
 
       /**
@@ -2094,7 +2333,7 @@ function stateModelFactory() {
        * max topological depth to a tip, used to scale cladogram x-positions
        */
       get maxDepthToLeaf() {
-        return calcDepthToLeaf(this.hierarchy)
+        return this.treeLayout.root.depthToLeaf
       },
 
       /**
@@ -2329,13 +2568,6 @@ function stateModelFactory() {
         return self.MSA?.secondaryStructureConsensus
       },
 
-      /**
-       * #getter
-       */
-      get seqConsensus() {
-        return self.MSA?.seqConsensus
-      },
-
       /**
        * #getter
        * the base pairs of the consensus secondary structure, as arcs, in
@@ -2480,11 +2712,13 @@ function stateModelFactory() {
 
       /**
        * #method
-       * Return a row-specific letter at a visible column, or undefined if gap.
+       * Return the character a row holds at a visible column: a residue, or
+       * the gap character (`-` or `.`) on a gap. Undefined for a row name the
+       * alignment does not have or a column past the row's end.
        *
        * @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
+       * @returns The character at that position
        */
       visibleColToRowLetter(rowName: string, visibleCol: number) {
         return self.rowMap.get(rowName)?.[
@@ -2582,6 +2816,22 @@ function stateModelFactory() {
         return col ?? (seqPos === 0 ? 0 : seq.length)
       },
 
+      /**
+       * #method
+       * the global column of a span's last residue, clamping a position past
+       * the end of the row to its last residue. Undefined for a row name the
+       * alignment does not have, or a row with no residues.
+       *
+       * @param rowName - The name of the row
+       * @param seqPos - The sequence position (0-based, ungapped)
+       */
+      seqEndToGlobalCol(rowName: string, seqPos: number) {
+        const index = self.seqPosIndex(rowName)
+        return index && index.length > 0
+          ? index[Math.min(seqPos, index.length - 1)]
+          : undefined
+      },
+
       /**
        * #method
        * Convert a sequence position (ungapped) directly to a visible column index.
@@ -2611,10 +2861,10 @@ function stateModelFactory() {
         const start = Math.max(1, Math.floor(rawStart))
         const end = Math.ceil(rawEnd)
         let startGlobal = start - 1
-        let endGlobal = end - 1
+        let endGlobal = Math.min(end, self.MSA?.getWidth() ?? end) - 1
         if (row !== undefined) {
           const rowStart = this.seqPosToGlobalCol(row, start - 1)
-          const rowEnd = this.seqPosToGlobalCol(row, end - 1)
+          const rowEnd = this.seqEndToGlobalCol(row, end - 1)
           if (rowStart === undefined || rowEnd === undefined) {
             return undefined
           }
@@ -2908,6 +3158,28 @@ function stateModelFactory() {
       },
     }))
     .views(self => ({
+      /**
+       * #getter
+       */
+      get verticalScrollbarWidth() {
+        return self.showVerticalScrollbar ? 20 : 0
+      },
+      /**
+       * #getter
+       * 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
+      },
+      /**
+       * #getter
+       * most-negative allowed scrollX, which keeps the last column in view
+       */
+      get maxScrollX() {
+        return Math.min(-self.totalWidth + this.msaCanvasWidth, 0)
+      },
       /**
        * #getter
        */
@@ -2925,9 +3197,29 @@ function stateModelFactory() {
       },
       /**
        * #getter
+       * warnings that follow from the loaded data and clear when it changes. A
+       * GFF whose first column names rows of some other alignment parses
+       * without error and draws nothing
+       */
+      get dataWarnings(): string[] {
+        const { annotations, rowNamesSet } = self
+        return self.dataInitialized &&
+          annotations.length > 0 &&
+          !annotations.some(a => rowNamesSet.has(a.id))
+          ? [
+              `0 of ${annotations.length} annotations name a row in this alignment`,
+            ]
+          : []
+      },
+      /**
+       * #getter
+       * the load warnings and the undismissed data warnings, for the header
        */
-      get maxScrollX() {
-        return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0)
+      get warnings(): string[] {
+        return [
+          ...self.loadWarnings,
+          ...this.dataWarnings.filter(w => !self.dismissedWarnings.includes(w)),
+        ]
       },
       /**
        * #getter
@@ -2954,6 +3246,14 @@ function stateModelFactory() {
         self.drawMsaLetters = arg
       },
 
+      /**
+       * #action
+       */
+      clearWarnings() {
+        self.loadWarnings = []
+        self.dismissedWarnings = self.dataWarnings
+      },
+
       /**
        * #action
        */
@@ -3014,13 +3314,43 @@ function stateModelFactory() {
 
       /**
        * #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
+       * root the tree on the branch above the given node. The node's tips are
+       * a split of the unrooted tree, and the side of it that is a clade in
+       * the tree as written stands for it as an outgroup, by its first and
+       * last tip, so the root survives the path ids changing under it
+       */
+      rerootAt(nodeId: string) {
+        const shown = find(
+          hierarchy(self.tree, d => d.children),
+          n => n.data.id === nodeId,
+        )
+        if (!shown?.parent) {
+          return
+        }
+        const node = outgroupNode(
+          hierarchy(self.inputTree, d => d.children),
+          leaves(shown).map(n => n.data.name),
+        )
+        if (node) {
+          const tips = leaves(node)
+          self.setTreeRoot({
+            outgroup: [
+              ...new Set([tips[0]!.data.name, tips.at(-1)!.data.name]),
+            ],
+          })
+        }
+      },
+
+      /**
+       * #action
+       * swap in a different tree over the same alignment. Clears `collapsed`,
+       * `rotated` 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.rotated.clear()
           self.setShowOnly(undefined)
           self.setTree(newick)
         })
@@ -3034,52 +3364,53 @@ function stateModelFactory() {
         self.setColWidth(defaultColWidth)
         self.setRowHeight(defaultRowHeight)
       },
+      /**
+       * #action
+       * zoom by `scaleFactor` about the center of the alignment area
+       */
+      zoomAtCenter(scaleFactor: number, axis: ScrollZoomAxis = 'both') {
+        this.zoomToPos(
+          scaleFactor,
+          self.msaCanvasWidth / 2,
+          self.msaAreaHeight / 2,
+          axis,
+        )
+      },
       /**
        * #action
        */
       zoomOutHorizontal() {
-        self.colWidth = Math.max(minColWidth, Math.floor(self.colWidth * 0.75))
-        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+        this.zoomAtCenter(0.75, 'horizontal')
       },
       /**
        * #action
        */
       zoomInHorizontal() {
-        self.colWidth = Math.min(maxCellSize, Math.ceil(self.colWidth * 1.5))
-        self.scrollX = clamp(self.scrollX, self.maxScrollX, 0)
+        this.zoomAtCenter(1.5, 'horizontal')
       },
       /**
        * #action
        */
       zoomInVertical() {
-        self.rowHeight = Math.min(maxCellSize, Math.ceil(self.rowHeight * 1.5))
+        this.zoomAtCenter(1.5, 'vertical')
       },
       /**
        * #action
        */
       zoomOutVertical() {
-        self.rowHeight = Math.max(
-          minRowHeight,
-          Math.floor(self.rowHeight * 0.75),
-        )
+        this.zoomAtCenter(0.75, 'vertical')
       },
       /**
        * #action
        */
       zoomIn() {
-        transaction(() => {
-          this.zoomInHorizontal()
-          this.zoomInVertical()
-        })
+        this.zoomAtCenter(1.5)
       },
       /**
        * #action
        */
       zoomOut() {
-        transaction(() => {
-          this.zoomOutHorizontal()
-          this.zoomOutVertical()
-        })
+        this.zoomAtCenter(0.75)
       },
       /**
        * #action
@@ -3242,25 +3573,11 @@ function stateModelFactory() {
       },
     }))
     .views(self => ({
-      /**
-       * #getter
-       */
-      get verticalScrollbarWidth() {
-        return self.showVerticalScrollbar ? 20 : 0
-      },
-      /**
-       * #getter
-       * 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
+       * writes highlights in. On a gap `residue` is undefined and `letter` is
+       * the gap character
        */
       cellAt(visibleCol: number, rowIndex?: number): Cell {
         const column = self.visibleColToGlobalCol(visibleCol)
@@ -3308,7 +3625,7 @@ function stateModelFactory() {
         }
         const { xStart, xEnd } = visibleColRange({
           offsetX: -scrollX,
-          blockWidth: this.msaCanvasWidth,
+          blockWidth: self.msaCanvasWidth,
           colWidth,
         })
         const last = Math.max(0, Math.min(xEnd, numColumns) - 1)
@@ -3471,7 +3788,7 @@ function stateModelFactory() {
             add(field, legend)
           }
         }
-        for (const { legendTitle, legend } of this.resolvedRowPanels) {
+        for (const { legendTitle, legend } of this.rowPanelScales) {
           add(legendTitle, legend)
         }
         return [...byKey.values()]
@@ -3519,7 +3836,7 @@ function stateModelFactory() {
               // 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)
+              const end = self.seqEndToGlobalCol(name, annotation.end - 1)
               if (start === undefined || end === undefined) {
                 return undefined
               }
@@ -3621,6 +3938,26 @@ function stateModelFactory() {
         return runs
       },
 
+      /**
+       * #method
+       * a highlight label with `{residue}` and `{position}` filled in from the
+       * row's letter at `start`, which is how the `175` shorthand draws "R175"
+       */
+      fillHighlightLabel(label: string, row?: string, start?: number) {
+        if (!label.includes('{')) {
+          return label
+        }
+        const col =
+          row && start !== undefined
+            ? self.seqPosIndex(row)?.[start - 1]
+            : undefined
+        const residue =
+          row && col !== undefined ? (self.MSA?.getRow(row)[col] ?? '') : ''
+        return label
+          .replaceAll('{residue}', residue)
+          .replaceAll('{position}', start === undefined ? '' : String(start))
+      },
+
       /**
        * #getter
        * `highlights` projected onto what is on screen: residue spans go
@@ -3636,7 +3973,10 @@ function stateModelFactory() {
           ...Object.values(transientHighlights).flat(),
         ]
         return all.flatMap(({ row, rows, start, end, label, color }) => {
-          const base = { label, color }
+          const base = {
+            label: label && this.fillHighlightLabel(label, row, start),
+            color,
+          }
           if (rows) {
             const rowIndices = rows
               .map(name => rowNamesSet.get(name))
@@ -3703,45 +4043,30 @@ function stateModelFactory() {
 
       /**
        * #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.
+       * each row panel's scale resolved against the values its field takes,
+       * giving the colors, labels and legend entries. Reads no cell size, so
+       * a zoom reuses it and the legends built from it.
        */
-      get resolvedRowPanels(): ResolvedRowPanel[] {
-        const rows = Object.entries(self.rowData)
+      get rowPanelScales(): (StripPanelScale | FeaturePanelScale)[] {
+        const { rowData } = self
         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
+        return self.rowPanels.map(panel => {
           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,
-                colWidth: self.colWidth,
-                domainBands: this.domainBands,
-                annotationsByRow: self.annotationsByRow,
-                shifts: align
-                  ? this.featureAlignShifts.get(align.on)
-                  : undefined,
-              }),
-              colors: featureColorMap(annotations, encoding, fillPalette),
+              colors: color
+                ? featureColorMap(annotations, encoding, fillPalette)
+                : this.featureColors,
               labels: label
                 ? featureLabelMap(annotations, label)
                 : featureLabels,
@@ -3756,28 +4081,56 @@ function stateModelFactory() {
           }
           const { colorOf, legend } = resolveScale(
             panel.scale,
-            rows.map(([, row]) => row?.[panel.field]).filter(notEmpty),
+            Object.values(rowData)
+              .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)
-            }
-          }
           return {
-            ...base,
             kind: panel.kind,
             field: panel.field,
             header: panel.header ?? panel.field,
             legendTitle: panel.legend ?? panel.field,
-            colors,
+            colors: colorByRow(rowData, panel.field, colorOf),
             legend,
           }
         })
       },
 
+      /**
+       * #getter
+       * each row panel with its scale from `rowPanelScales` and its geometry:
+       * the pixel column it draws in and, for a features panel, the spans per
+       * row. Resolved once per change of those inputs, never per block per
+       * frame.
+       */
+      get resolvedRowPanels(): ResolvedRowPanel[] {
+        const scales = this.rowPanelScales
+        let offsetX = 0
+        return self.rowPanels.map((panel, index) => {
+          const width = rowPanelWidth(panel, self)
+          const base = { id: `rowpanel-${index}`, width, offsetX }
+          offsetX += width
+          if (panel.kind === 'features') {
+            const align = panel.transform?.find(t => t.type === 'align')
+            return {
+              ...base,
+              ...(scales[index] as FeaturePanelScale),
+              spans: featurePanelSpans({
+                panel,
+                width,
+                colWidth: self.colWidth,
+                domainBands: this.domainBands,
+                annotationsByRow: self.annotationsByRow,
+                shifts: align
+                  ? this.featureAlignShifts.get(align.on)
+                  : undefined,
+              }),
+            }
+          }
+          return { ...base, ...(scales[index] as StripPanelScale) }
+        })
+      },
+
       /**
        * #getter
        * the shift an `align` transform gives each row, keyed by the feature
@@ -3820,19 +4173,9 @@ function stateModelFactory() {
         const encoding = this.resolvedEncodings.find(
           e => e.channel === 'tipLabel',
         )
-        if (!encoding) {
-          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)
-          }
-        }
-        return colors
+        return encoding
+          ? colorByRow(self.rowData, encoding.field, encoding.colorOf)
+          : undefined
       },
 
       /**
@@ -3848,14 +4191,14 @@ function stateModelFactory() {
         if (!encoding) {
           return undefined
         }
+        const colors = colorByRow(
+          self.rowData,
+          encoding.field,
+          encoding.colorOf,
+        )
         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)
+          const color = colors.get(name)
+          return color && withAlpha(color, rowTintAlpha)
         })
       },
 
@@ -3937,7 +4280,8 @@ function stateModelFactory() {
        */
       reset() {
         self.resetCount++
-        self.clearWarnings()
+        self.loadWarnings = []
+        self.dismissedWarnings = []
         self.setStatus(undefined)
         applySnapshot(
           self,
@@ -3964,6 +4308,21 @@ function stateModelFactory() {
         const blob = new Blob([html], { type: 'image/svg+xml' })
         saveAs(blob, exportFileName(self.msaFilehandle, 'svg'))
       },
+      /**
+       * #action
+       * save `treeNewick` as a file
+       */
+      exportNewick() {
+        const blob = new Blob([self.treeNewick], { type: 'text/plain' })
+        saveAs(
+          blob,
+          exportFileName(
+            self.treeFilehandle ?? self.msaFilehandle,
+            'nwk',
+            'tree',
+          ),
+        )
+      },
       /**
        * #action
        * show or hide an annotation type. Only hidden types are recorded; see
@@ -4047,36 +4406,62 @@ function stateModelFactory() {
           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. `dataInitialized` is true once the MSA alone
-        // has loaded, when the tree is still the flat stub, so a tree
-        // filehandle holds the seeding until its text lands.
-        let cladesSeeded = false
+        // The `collapse`, `focus` and `rotate` clade marks seed the collapsed
+        // list, the subtree in focus and the rotated nodes, 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 per data load, per change of
+        // `clades` and per reroot, which clears the node ids the seeding
+        // wrote: expanding a seeded clade sticks until one of those changes.
+        // `dataInitialized` is true once the MSA alone has loaded, when the
+        // tree is still the flat stub, so a tree filehandle holds the seeding
+        // until its text lands.
+        addDisposer(
+          self,
+          reaction(
+            () =>
+              self.dataInitialized && !(self.treeFilehandle && !self.data.tree)
+                ? { clades: getSnapshot(self.clades), treeRoot: self.treeRoot }
+                : undefined,
+            seed => {
+              if (!seed?.clades.length) {
+                return
+              }
+              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)
+                } else if (
+                  mark === 'rotate' &&
+                  !self.rotated.includes(nodeId)
+                ) {
+                  self.toggleRotated(nodeId)
+                }
+              }
+            },
+            { fireImmediately: true, equals: compareStructural },
+          ),
+        )
+
+        // zoomToRegion needs a width and resolves residues through the visible
+        // columns, so this waits for both, and for a tree file whose collapsed
+        // clades would hide columns and move the target after the zoom
         addDisposer(
           self,
           autorun(() => {
+            const { region } = self
             if (
-              cladesSeeded ||
-              !self.dataInitialized ||
-              (self.treeFilehandle && !self.data.tree) ||
-              self.clades.length === 0
+              region &&
+              self.viewInitialized &&
+              self.numColumns > 0 &&
+              !(self.treeFilehandle && !self.data.tree)
             ) {
-              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)
-              }
+              this.zoomToRegion(region)
+              self.setRegion(undefined)
             }
           }),
         )
@@ -4246,24 +4631,6 @@ function stateModelFactory() {
           }),
         )
 
-        // a GFF whose first column names rows of some other alignment parses
-        // without error and draws nothing
-        addDisposer(
-          self,
-          autorun(() => {
-            const { annotations, rowNamesSet } = self
-            if (
-              annotations.length > 0 &&
-              rowNamesSet.size > 0 &&
-              !annotations.some(a => rowNamesSet.has(a.id))
-            ) {
-              self.addWarning(
-                `0 of ${annotations.length} annotations name a row in this alignment`,
-              )
-            }
-          }),
-        )
-
         // gffFilehandle loads into data.gff, which the autorun above parses
         loadOnFilehandleChange({
           what: 'annotations',