react-msaview 9.1.0 → 9.2.0

package/src/model.ts

@@ -1,12 +1,10 @@
 import { clamp, groupBy, notEmpty, sum } from '@jbrowse/core/util'
-import { openLocation } from '@jbrowse/core/util/io'
 import { ElementId, FileLocation } from '@jbrowse/core/util/types/mst'
 import {
   addDisposer,
   applySnapshot,
   cast,
   getSnapshot,
-  isAlive,
   types,
 } from '@jbrowse/mobx-state-tree'
 import {
@@ -19,10 +17,8 @@ import {
 import {
   generateNodeIds,
   gffToAnnotations,
-  parseEmfTree,
   parseGFF,
   parseMSA,
-  parseNewick,
 } from 'msa-parsers'
 
 import { blockFasta } from './blockFasta.ts'
@@ -36,14 +32,11 @@ import { visibleColRange } from './components/msa/visibleColRange.ts'
 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,
@@ -72,35 +65,37 @@ import {
   scrollZoomAxes,
   segmentFeatureTypes,
   segmentShades,
+  settingsPanelWidth,
   treeScaleBarHeight,
 } from './constants.ts'
 import { createPaletteMap } from './createPaletteMap.ts'
 import { exportFileName } from './exportFileName.ts'
-import { featureField, featureName } from './featureFields.ts'
+import { featureName } from './featureFields.ts'
+import {
+  colorByRow,
+  featureColorMap,
+  featureLabelMap,
+  featurePanelSpans,
+  resolveFeatureScale,
+  rowPanelWidth,
+  stringFields,
+} from './featurePanels.ts'
 import { featuresToAnnotations } from './featuresLayer.ts'
-import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
-import { flatToTree } from './flatToTree.ts'
+import { installFilehandleLoader } from './filehandleLoader.ts'
 import {
-  collapse,
   find,
-  forEachDescendant,
   hierarchy,
   layoutTree,
-  leafIndex,
   leaves,
-  mrca,
   nodeCoveringRows,
-  sort,
-  sum as hierarchySum,
 } from './hierarchy.ts'
 import { DataModelF } from './model/DataModel.ts'
 import { DialogQueueSessionMixin } from './model/DialogQueue.ts'
 import { MSAModelF } from './model/msaModel.ts'
 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 { preorder } from './rerootTree.ts'
 import {
   globalColToVisibleCol,
   seqPosOfGlobalCol,
@@ -110,33 +105,43 @@ import {
 import { resolveScale } from './scales.ts'
 import { buildSeqPosIndex } from './seqPosToGlobalCol.ts'
 import { maxBitsFor } from './sequenceLogo.ts'
+import {
+  blosum62ColumnColors,
+  identityColumnColors,
+} from './similarityColors.ts'
 import { stripDefault } from './stripDefault.ts'
 import { treeTips, widestLabel } from './tipLabels.ts'
+import {
+  buildTreeRoot,
+  outgroupNode,
+  parseTreeText,
+  resolveClades,
+  rootTree,
+  tipRange,
+} from './treeDisplay.ts'
 import {
   computeRowInsertions,
   dropBlanks,
   len,
-  outlineColor,
+  readComputed,
   skipBlanks,
   withAlpha,
 } from './util.ts'
 import { saveAs } from './vendor/fileSaver.ts'
 import { writeNewick } from './writeNewick.ts'
 import { parseWuss } from './wuss.ts'
+import { takeZoomSnapshot, zoomSnapshotCovers } from './zoomSnapshot.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,
   Arc,
   BasicTrack,
   Cell,
   Clade,
-  CladeMark,
   ResidueMappingProblem,
   ColumnTrackSpec,
   DomainBand,
@@ -154,14 +159,11 @@ import type {
   ResolvedClade,
   ResolvedEncoding,
   ResolvedFeaturePanel,
+  ResolvedStripPanel,
   ResolvedHighlight,
   ResolvedSelection,
-  TreeOrder,
   TreeRoot,
   ResolvedRowPanel,
-  ResolvedStripPanel,
-  RowFeaturesSpec,
-  RowPanelSpan,
   RowDataInput,
   RowPanelSpec,
   RowResidue,
@@ -170,17 +172,11 @@ import type {
   UnshareableData,
   Viewport,
 } from './types.ts'
+import type { ZoomSnapshot } from './zoomSnapshot.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
 import type { Instance } from '@jbrowse/mobx-state-tree'
 import type { IComputedValue } from 'mobx'
 
-function parseTreeText(text: string) {
-  if (text.startsWith('BioTreeContainer')) {
-    return flatToTree(parseAsn1(text))
-  }
-  return parseNewick(text.startsWith('SEQ') ? parseEmfTree(text).tree : text)
-}
-
 // 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.
@@ -209,262 +205,6 @@ const ownHeightKey = (id: string) => `own:${id}`
 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. 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 : view.rowHeight)
-  )
-}
-
-// one row of the row table as the channels read it. A number or a boolean
-// reads as its string, the way a GFF value does, and null or an object drops
-function stringFields(row: unknown) {
-  if (typeof row !== 'object' || row === null) {
-    return undefined
-  }
-  const fields: Record<string, string> = {}
-  for (const [field, value] of Object.entries(row)) {
-    if (typeof value === 'string') {
-      fields[field] = value
-    } else if (typeof value === 'number' || typeof value === 'boolean') {
-      fields[field] = String(value)
-    }
-  }
-  return fields
-}
-
-// 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
-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
-}
-
-/** what `packDomainLanes` needs to lay a row out, before it has its lane */
-type Unlaned = Omit<RowPanelSpan, 'lane' | 'laneCount'> & {
-  startCol: number
-  endCol: number
-}
-
-/**
- * Lanes for `position: "strandpile"`, gggenomes' `position_strandpile`: the
- * forward features stack above the line and the reverse below it, each strand
- * packing on its own. The deepest row on each side sets the grid every row lays
- * out on, so the line between the strands sits at one height down the panel and
- * a reader can scan it. A feature with no strand piles with the forward ones.
- */
-function strandpileLanes(
-  rows: [string, Unlaned[]][],
-): Map<string, RowPanelSpan[]> {
-  const piled = rows.map(([name, bands]) => {
-    const reverse = packDomainLanes(
-      bands.filter(b => b.annotation.strand === -1),
-    )
-    const forward = packDomainLanes(
-      bands.filter(b => b.annotation.strand !== -1),
-    )
-    return { name, forward, reverse }
-  })
-  const up = Math.max(0, ...piled.map(p => p.forward[0]?.laneCount ?? 0))
-  const down = Math.max(0, ...piled.map(p => p.reverse[0]?.laneCount ?? 0))
-  const laneCount = up + down
-  return new Map(
-    piled.map(({ name, forward, reverse }) => [
-      name,
-      [
-        // forward level 0 is the lane just above the line, stacking upward
-        ...forward.map(b => ({ ...b, lane: up - 1 - b.lane, laneCount })),
-        ...reverse.map(b => ({ ...b, lane: up + b.lane, laneCount })),
-      ],
-    ]),
-  )
-}
-
-/** one row's spans laid out by the panel's `position` */
-function panelLanes(
-  panel: RowFeaturesSpec,
-  rows: [string, Unlaned[]][],
-): Map<string, RowPanelSpan[]> {
-  return panel.position === 'strandpile'
-    ? strandpileLanes(rows)
-    : new Map(rows.map(([name, bands]) => [name, packDomainLanes(bands)]))
-}
-
-/**
- * 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,
-  colWidth,
-  domainBands,
-  annotationsByRow,
-  shifts,
-}: {
-  panel: RowFeaturesSpec
-  width: number
-  colWidth: number
-  domainBands: Map<string, DomainBand[]>
-  annotationsByRow: Record<string, Annotation[]>
-  shifts: Map<string, number> | undefined
-}): Map<string, RowPanelSpan[]> {
-  if (panel.x === 'column') {
-    return panelLanes(
-      panel,
-      [...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)
-    }
-  }
-  // a gene arrow ends where its feature does, so the extent maps onto the whole
-  // panel less the pixel the rightmost stroke needs
-  const drawable = Math.max(1, width - 1)
-  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 panelLanes(
-    panel,
-    shifted.map(([name, features]) => [
-      name,
-      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 every feature loaded, so hiding
-// a type in the filter dialog leaves the rest in their colors, and a legend of
-// the values the features drawn carry
-function resolveFeatureScale(
-  field: string,
-  scale: ScaleSpec | undefined,
-  annotations: Annotation[],
-  drawn: Annotation[],
-) {
-  const valuesOf = (list: Annotation[]) =>
-    list.map(a => featureField(a, field)).filter(notEmpty)
-  const resolved = resolveScale(scale, valuesOf(annotations))
-  const shown = new Set(valuesOf(drawn))
-  return {
-    field,
-    ...resolved,
-    legend: resolved.legend.filter(entry => shown.has(entry.id)),
-  }
-}
-
 const columnTrackBytes = new WeakMap<ColumnTrackSpec, number>()
 
 function columnTrackSize(track: ColumnTrackSpec) {
@@ -524,6 +264,7 @@ export const preservedOnReset = new Set([
   'drawNodeBubbles',
   'drawNodeLabels',
   'showTreeOverview',
+  'showTreeScaleBar',
   'overviewHeight',
   'turnedOffTracks',
   'trackHeights',
@@ -531,266 +272,23 @@ export const preservedOnReset = new Set([
   'allowedGappyness',
   'subFeatureRows',
   'showDomainLegend',
+  'domainFill',
+  'embeddedMode',
 ])
 
 // `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.
+// track writes nothing into the snapshot
 function trackIsOff(
   turnedOffTracks: { get: (id: string) => boolean | undefined },
   id: string,
-  defaultOff?: boolean,
 ) {
-  return turnedOffTracks.get(id) ?? (defaultOff || defaultOffTracks.has(id))
+  return turnedOffTracks.get(id) ?? 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[] = []
 
-/**
- * Each tip of the full tree in the order the tree draws it, with the on-screen
- * row that shows it: its own, or the row of the collapsed node standing for it
- */
-function tipRows(root: HierarchyNode<NodeWithIds>) {
-  const rows = new Map<string, { order: number; row: number }>()
-  let row = 0
-  const pushReversed = (
-    stack: HierarchyNode<NodeWithIds>[],
-    nodes: HierarchyNode<NodeWithIds>[],
-  ) => {
-    for (let i = nodes.length - 1; i >= 0; i--) {
-      stack.push(nodes[i]!)
-    }
-  }
-  const stack = [root]
-  while (stack.length > 0) {
-    const node = stack.pop()!
-    if (node.children?.length) {
-      pushReversed(stack, node.children)
-    } else {
-      const hidden = [node]
-      while (hidden.length > 0) {
-        const tip = hidden.pop()!
-        const kids = tip.children ?? tip._children
-        if (kids?.length) {
-          pushReversed(hidden, kids)
-        } else {
-          rows.set(tip.data.name, { order: rows.size, row })
-        }
-      }
-      row++
-    }
-  }
-  return rows
-}
-
-/**
- * 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. A `range` counts its tips in the order
- * `tips` gives them, so a collapsed clade inside it counts every leaf it
- * stands for. `index` is the memoized leaf pass over the tree.
- */
-function cladeRows(
-  clade: Clade,
-  root: HierarchyNode<NodeWithIds>,
-  index: Map<string, HierarchyNode<NodeWithIds> | undefined>,
-  tips: Map<string, { order: number; row: number }>,
-): { rows: [number, number]; nodeId?: string } | undefined {
-  if (clade.range) {
-    const [a, b] = clade.range.map(name =>
-      index.get(name) ? tips.get(name) : undefined,
-    )
-    if (a === undefined || b === undefined) {
-      return undefined
-    }
-    const [first, last] = a.order <= b.order ? [a, b] : [b, a]
-    return last.order - first.order + 1 === clade.tips
-      ? { rows: [first.row, last.row] }
-      : undefined
-  }
-  const node = clade.mrca ? mrca(root, clade.mrca, index) : undefined
-  if (!node) {
-    return undefined
-  }
-  const nodeTips = leaves(node)
-  if (nodeTips.length !== clade.tips) {
-    return undefined
-  }
-  let first = Infinity
-  let last = -Infinity
-  for (const tip of nodeTips) {
-    const row = tips.get(tip.data.name)?.row
-    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 rows of
- * `displayed`, the tree as drawn. 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 the seeding marks, which need one,
- * drop it.
- */
-function resolveClades(
-  clades: Clade[],
-  root: HierarchyNode<NodeWithIds>,
-  displayed: HierarchyNode<NodeWithIds>,
-): ResolvedClade[] {
-  const index = leafIndex(root)
-  const tips = tipRows(displayed)
-  return clades.flatMap(clade => {
-    const resolved = cladeRows(clade, root, index, tips)
-    const seeding = seedingMarks.has(clade.mark)
-    return resolved && !(seeding && resolved.nodeId === undefined)
-      ? [
-          {
-            ...resolved,
-            mark: clade.mark,
-            color: withAlpha(
-              clade.color ?? cladeHighlightColor,
-              cladeHighlightAlpha,
-            ),
-            markColor: clade.color,
-            label: clade.label,
-          },
-        ]
-      : []
-  })
-}
-
-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
- * 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,
-    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))
-  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)
-    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 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 its xMin/xMax in a layout one
-// row per tip
-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',
@@ -821,6 +319,31 @@ function sameLength(segment: ResidueSegment) {
   )
 }
 
+// A zoom that passes the default cell size stops on it, and one that starts on
+// it holds there until the wheel has gathered `zoomDetent` worth of scale, so
+// a zoom in or out finds its way back to the default
+const zoomDetent = Math.log(1.3)
+
+function detentZoom(
+  value: number,
+  scale: number,
+  home: number,
+  held: number,
+  min: number,
+  canHold: boolean,
+) {
+  if (value === home && canHold) {
+    const total = held + Math.log(scale)
+    return Math.abs(total) < zoomDetent
+      ? { value, held: total }
+      : { value: clamp(home * Math.exp(total), min, maxCellSize), held: 0 }
+  }
+  const next = clamp(value * scale, min, maxCellSize)
+  return (value - home) * (next - home) < 0
+    ? { value: home, held: 0 }
+    : { value: next, held: 0 }
+}
+
 // 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.
@@ -855,19 +378,11 @@ function sharedValue(values: (string | undefined)[]) {
     : 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
-}
+type StripPanelScale = Omit<ResolvedStripPanel, 'id' | 'width' | 'offsetX'>
+type FeaturePanelScale = Omit<
+  ResolvedFeaturePanel,
+  'id' | 'width' | 'offsetX' | 'spans'
+>
 
 /**
  * #stateModel MsaView
@@ -913,6 +428,13 @@ function stateModelFactory({
          * #property
          */
         showDomains: stripDefault(types.boolean, defaultShowDomains),
+        /**
+         * #property
+         * whether shown domains fill the cells they cover. Off, the residue
+         * scheme keeps the cells and each domain draws as a bar under its
+         * row. See `cellFill`.
+         */
+        domainFill: stripDefault(types.boolean, true),
         /**
          * #property
          * whether the domain legend is expanded. The legend floats over the
@@ -944,6 +466,13 @@ function stateModelFactory({
          */
         drawMsaLetters: stripDefault(types.boolean, defaultDrawMsaLetters),
 
+        /**
+         * #property
+         * draws the toolbar's menus and Settings as icons without text, for a
+         * host with little room, such as a JBrowse view
+         */
+        embeddedMode: stripDefault(types.boolean, false),
+
         /**
          * #property
          * zoom in/out on plain mouse-wheel without holding ctrl
@@ -1096,10 +625,10 @@ 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
+         * the user's departures from each annotation accession's default,
+         * keyed by accession with the value meaning "off", like
+         * `turnedOffTracks`. An untouched accession is absent and takes its
+         * default, so the shared URL grows only with the user's filters
          */
         turnedOffFeatures: stripDefault(types.map(types.boolean), {}),
         /**
@@ -1180,6 +709,18 @@ function stateModelFactory({
        * #volatile
        */
       headerHeight: 0,
+      /**
+       * #volatile
+       * whether the settings panel docks beside the alignment, taking
+       * `settingsPanelWidth` out of the width the view lays out in
+       */
+      settingsOpen: false,
+      /**
+       * #volatile
+       * the log scale a wheel zoom has gathered against the detent at the
+       * default column width and row height, per axis
+       */
+      zoomHeld: { col: 0, row: 0 },
       /**
        * #volatile
        * leaves the toolbar out, for a host drawing its own controls. Kept out
@@ -1203,6 +744,13 @@ function stateModelFactory({
       highResScaleFactor:
         typeof window === 'undefined' ? 1 : window.devicePixelRatio,
 
+      /**
+       * #volatile
+       * the cell size and block grid the alignment last drew at, held from a
+       * wheel-zoom frame until the gesture settles. MSACanvas stretches those
+       * blocks to the current cell size with one CSS transform
+       */
+      zoomSnapshot: undefined as ZoomSnapshot | undefined,
       /**
        * #volatile
        */
@@ -1365,6 +913,12 @@ function stateModelFactory({
       setWidth(arg: number) {
         self.volatileWidth = arg
       },
+      /**
+       * #action
+       */
+      setSettingsOpen(arg: boolean) {
+        self.settingsOpen = arg
+      },
       /**
        * #action
        * update the canvas scale factor when the device pixel ratio changes
@@ -1508,6 +1062,23 @@ function stateModelFactory({
       setShowDomains(arg: boolean) {
         self.showDomains = arg
       },
+      /**
+       * #action
+       */
+      setDomainFill(arg: boolean) {
+        self.domainFill = arg
+      },
+      /**
+       * #action
+       * hand the cell fill to the residue scheme, the domains, or neither,
+       * which colors the letters instead
+       */
+      setCellFill(mode: 'residue' | 'domain' | 'none') {
+        self.setBgColor(mode !== 'none')
+        if (mode !== 'none') {
+          self.domainFill = mode === 'domain'
+        }
+      },
       /**
        * #action
        * expand or collapse the domain legend that floats over the alignment
@@ -1536,6 +1107,7 @@ function stateModelFactory({
        */
       setRowHeight(n: number) {
         self.rowHeight = n
+        self.zoomHeld = { ...self.zoomHeld, row: 0 }
       },
 
       /**
@@ -1544,6 +1116,7 @@ function stateModelFactory({
        */
       setColWidth(n: number) {
         self.colWidth = n
+        self.zoomHeld = { ...self.zoomHeld, col: 0 }
       },
 
       /**
@@ -1715,22 +1288,7 @@ function stateModelFactory({
             self.allowedGappyness < 100)
         )
       },
-      /**
-       * #getter
-       * the annotations the overlay, the legend and the encodings draw: the
-       * GFF's, then the `features` layer's
-       */
-      get allAnnotations(): Annotation[] {
-        return self.features.length > 0
-          ? [...self.annotations, ...featuresToAnnotations(self.features)]
-          : self.annotations
-      },
-      /**
-       * #getter
-       */
-      get actuallyShowDomains() {
-        return self.showDomains && this.allAnnotations.length > 0
-      },
+
       /**
        * #getter
        * whether the host restores the loaded documents outside the snapshot.
@@ -1755,7 +1313,7 @@ function stateModelFactory({
         if (self.volatileWidth === undefined) {
           throw new Error('not initialized')
         }
-        return self.volatileWidth
+        return self.volatileWidth - (self.settingsOpen ? settingsPanelWidth : 0)
       },
     }))
     .views(self => ({
@@ -1805,7 +1363,7 @@ function stateModelFactory({
         return !!this.tree.noTree
       },
       get noDomains() {
-        return self.allAnnotations.length === 0
+        return this.allAnnotations.length === 0
       },
 
       /**
@@ -1914,6 +1472,27 @@ function stateModelFactory({
           ? parseMSA(text, self.currentAlignment, self.msaFormat)
           : null
       },
+      /**
+       * #getter
+       * the annotations the overlay, the legend and the encodings draw: the
+       * GFF's, the `features` layer's, then the file's own per-row lines
+       */
+      get allAnnotations(): Annotation[] {
+        const inline = this.MSA?.annotations ?? []
+        return self.features.length > 0 || inline.length > 0
+          ? [
+              ...self.annotations,
+              ...featuresToAnnotations(self.features),
+              ...inline,
+            ]
+          : self.annotations
+      },
+      /**
+       * #getter
+       */
+      get actuallyShowDomains() {
+        return self.showDomains && this.allAnnotations.length > 0
+      },
       /**
        * #getter
        */
@@ -2507,6 +2086,22 @@ function stateModelFactory({
         )
       },
 
+      /**
+       * #getter
+       * Pre-computed similarity shades per column, for blosum62_dynamic.
+       * Returns a map of letter -> color for each column. Amino acids shade by
+       * BLOSUM62 similarity to the rest of the column, and an alignment of
+       * nucleotides by identity, since the matrix names amino acids.
+       */
+      get colSimilarity() {
+        const { colStats, sequenceType } = this
+        const columnColors =
+          sequenceType === 'amino' ? blosum62ColumnColors : identityColumnColors
+        return Array.from({ length: colStats.numColumns }, (_, col) =>
+          columnColors(colStats, col),
+        )
+      },
+
       /**
        * #getter
        * Conservation score per column using Shannon entropy (biojs-msa style).
@@ -2903,6 +2498,30 @@ function stateModelFactory({
         }))
       },
 
+      /**
+       * #getter
+       * the reference row (`relativeTo`) repeated above the alignment, so it
+       * stays in view while the rows compared against it scroll
+       */
+      get referenceTrackModels(): BasicTrack[] {
+        const { relativeTo } = self
+        const data =
+          relativeTo === undefined ? undefined : self.columns.get(relativeTo)
+        return relativeTo === undefined || data === undefined
+          ? []
+          : [
+              {
+                model: {
+                  id: 'reference-row',
+                  name: relativeTo,
+                  kind: 'reference' as const,
+                  data,
+                  height: self.rowHeight,
+                },
+              },
+            ]
+      },
+
       get tracks(): BasicTrack[] {
         return [
           ...this.adapterTrackModels,
@@ -2911,6 +2530,7 @@ function stateModelFactory({
           // 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 : []),
+          ...this.referenceTrackModels,
         ]
       },
 
@@ -2919,8 +2539,7 @@ function stateModelFactory({
        */
       get turnedOnTracks() {
         return this.tracks.filter(
-          f =>
-            !trackIsOff(self.turnedOffTracks, f.model.id, f.model.defaultOff),
+          f => !trackIsOff(self.turnedOffTracks, f.model.id),
         )
       },
 
@@ -3250,7 +2869,11 @@ function stateModelFactory({
           if (mapping.structure.id !== structureId) {
             continue
           }
-          if (asymId !== undefined && mapping.structure.asymId !== asymId) {
+          if (
+            asymId !== undefined &&
+            mapping.structure.asymId !== undefined &&
+            mapping.structure.asymId !== asymId
+          ) {
             continue
           }
           const segment = mapping.segments.find(
@@ -3270,10 +2893,14 @@ function stateModelFactory({
     .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
+       * the branch-length scale bar over the tree, undefined while
+       * `showTreeScaleBar` is off, in cladogram mode, or when the tree area is
+       * too narrow for one
        */
       get treeScaleBar() {
+        if (!self.showTreeScaleBar) {
+          return undefined
+        }
         return scaleBarLength(
           self.pxPerBranchLength,
           self.effectiveTreeAreaWidth - self.marginLeft * 2,
@@ -3329,11 +2956,43 @@ function stateModelFactory({
         }
         return types
       },
-      get filteredAnnotations() {
-        return self.allAnnotations.filter(
-          r => !self.turnedOffFeatures.get(r.accession),
+      /**
+       * accessions hidden until the user turns them on, such as a Stockholm
+       * file's #=GR lines
+       */
+      get defaultOffAccessions() {
+        return new Set(
+          self.allAnnotations.filter(a => a.defaultOff).map(a => a.accession),
+        )
+      },
+      /**
+       * #method
+       */
+      featureOff(accession: string) {
+        return (
+          self.turnedOffFeatures.get(accession) ??
+          this.defaultOffAccessions.has(accession)
         )
       },
+      get filteredAnnotations() {
+        return self.allAnnotations.filter(r => !this.featureOff(r.accession))
+      },
+      /**
+       * #getter
+       * what colors the alignment's cells: the residue scheme, the domains
+       * covering them, or nothing, which leaves the scheme to the letters.
+       * Domains own the fill only while some are drawn, so a file whose
+       * annotations all start hidden keeps its residue colors
+       */
+      get cellFill(): 'residue' | 'domain' | 'none' {
+        return !self.bgColor
+          ? 'none'
+          : self.actuallyShowDomains &&
+              self.domainFill &&
+              this.filteredAnnotations.length > 0
+            ? 'domain'
+            : 'residue'
+      },
       get annotationsByRow() {
         const { rowNamesSet } = self
         return groupBy(this.filteredAnnotations, r =>
@@ -3412,6 +3071,12 @@ function stateModelFactory({
           self.blocksX.map(bx => [bx, by] as const),
         )
       },
+      /**
+       * #getter
+       */
+      get wheelZooming() {
+        return self.zoomSnapshot !== undefined
+      },
 
       /**
        * #getter
@@ -3637,19 +3302,35 @@ function stateModelFactory({
         transaction(() => {
           const colInView = (-self.scrollX + offsetX) / self.colWidth
           const rowInView = (-self.scrollY + offsetY) / self.rowHeight
+          // zooming both axes, an axis holds at the default only while the
+          // other sits there too, or one would hold while the other grows
+          const canHold =
+            axis !== 'both' ||
+            (self.colWidth === defaultColWidth &&
+              self.rowHeight === defaultRowHeight)
           if (axis !== 'vertical') {
-            self.colWidth = clamp(
-              self.colWidth * scaleFactor,
+            const { value, held } = detentZoom(
+              self.colWidth,
+              scaleFactor,
+              defaultColWidth,
+              self.zoomHeld.col,
               minColWidth,
-              maxCellSize,
+              canHold,
             )
+            self.colWidth = value
+            self.zoomHeld = { ...self.zoomHeld, col: held }
           }
           if (axis !== 'horizontal') {
-            self.rowHeight = clamp(
-              self.rowHeight * scaleFactor,
+            const { value, held } = detentZoom(
+              self.rowHeight,
+              scaleFactor,
+              defaultRowHeight,
+              self.zoomHeld.row,
               minRowHeight,
-              maxCellSize,
+              canHold,
             )
+            self.rowHeight = value
+            self.zoomHeld = { ...self.zoomHeld, row: held }
           }
           self.scrollX = clamp(
             offsetX - colInView * self.colWidth,
@@ -3670,6 +3351,25 @@ function stateModelFactory({
           )
         })
       },
+      /**
+       * #action
+       * zoomToPos for one wheel or pinch frame. The alignment keeps the blocks
+       * it drew at the start of the gesture, scaled, and redraws them only once
+       * they stop covering the viewport; endWheelZoom redraws them sharp
+       */
+      wheelZoomToPos(scaleFactor: number, offsetX: number, offsetY: number) {
+        self.zoomSnapshot ??= takeZoomSnapshot(self, false)
+        this.zoomToPos(scaleFactor, offsetX, offsetY, self.wheelZoomAxis)
+        if (!zoomSnapshotCovers(self, self.zoomSnapshot)) {
+          self.zoomSnapshot = takeZoomSnapshot(self, true)
+        }
+      },
+      /**
+       * #action
+       */
+      endWheelZoom() {
+        self.zoomSnapshot = undefined
+      },
       /**
        * #action
        */
@@ -3754,11 +3454,22 @@ function stateModelFactory({
        * #action
        */
       toggleTrack(id: string) {
-        const defaultOff = self.MSA?.tracks.find(t => t.id === id)?.defaultOff
-        self.turnedOffTracks.set(
-          id,
-          !trackIsOff(self.turnedOffTracks, id, defaultOff),
-        )
+        self.turnedOffTracks.set(id, !trackIsOff(self.turnedOffTracks, id))
+      },
+      /**
+       * #action
+       * show or hide several tracks at once, as the track selector's Show all
+       * and Hide all do. A choice matching the track's default is dropped, so
+       * it stays out of the shared URL
+       */
+      setTracksShown(ids: string[], shown: boolean) {
+        for (const id of ids) {
+          if (defaultOffTracks.has(id) === !shown) {
+            self.turnedOffTracks.delete(id)
+          } else {
+            self.turnedOffTracks.set(id, !shown)
+          }
+        }
       },
       /**
        * #action
@@ -3923,7 +3634,7 @@ function stateModelFactory({
        */
       get visibleDomainTypes() {
         return this.categoricalDomainTypes
-          .filter(d => !self.turnedOffFeatures.get(d.accession))
+          .filter(d => !self.featureOff(d.accession))
           .toSorted((a, b) => a.start - b.start)
       },
 
@@ -3992,16 +3703,16 @@ function stateModelFactory({
       /**
        * #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
+       * of filling the row behind the letters: whenever the domains do not own
+       * the cell fill (`cellFill`), a filled box would paint over the residue
+       * colors the user picked. 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.cellFill !== 'domain' &&
           !self.subFeatureRows &&
           self.showMsaLetters
         )
@@ -4523,6 +4234,12 @@ function stateModelFactory({
       setHideHeader(arg: boolean) {
         self.hideHeader = arg
       },
+      /**
+       * #action
+       */
+      setEmbeddedMode(arg: boolean) {
+        self.embeddedMode = arg
+      },
       /**
        * #action
        */
@@ -4602,14 +4319,15 @@ function stateModelFactory({
       },
       /**
        * #action
-       * show or hide an annotation type. Only hidden types are recorded; see
-       * `turnedOffFeatures`
+       * show or hide an annotation type. Only a choice that differs from the
+       * type's default is recorded; see `turnedOffFeatures`
        */
       setFilter(accession: string, shown: boolean) {
-        if (shown) {
-          self.turnedOffFeatures.delete(accession)
+        // only a departure from the accession's default is recorded
+        if (shown === self.defaultOffAccessions.has(accession)) {
+          self.turnedOffFeatures.set(accession, !shown)
         } else {
-          self.turnedOffFeatures.set(accession, true)
+          self.turnedOffFeatures.delete(accession)
         }
       },
 
@@ -4618,23 +4336,28 @@ function stateModelFactory({
        */
       fit() {
         // two passes: each direction's viewport depends on whether the other
-        // overflows (the minimap takes height, the vertical scrollbar width)
+        // overflows (the minimap takes height, the vertical scrollbar width).
+        // Fit shrinks an alignment into the window but never grows one past
+        // the default cell size, which would stretch a small alignment's rows
+        // and columns out of proportion
         transaction(() => {
           for (let pass = 0; pass < 2; pass++) {
-            this.fitHorizontally()
-            this.fitVertically()
+            this.fitHorizontally(defaultColWidth)
+            this.fitVertically(defaultRowHeight)
           }
         })
       },
       /**
        * #action
        */
-      fitVertically() {
+      fitVertically(maxRowHeight = maxCellSize) {
         if (self.numRows > 0) {
-          self.rowHeight = clamp(
-            self.msaAreaHeight / self.numRows,
-            minRowHeight,
-            maxCellSize,
+          self.setRowHeight(
+            clamp(
+              self.msaAreaHeight / self.numRows,
+              minRowHeight,
+              maxRowHeight,
+            ),
           )
         }
         self.scrollY = 0
@@ -4651,10 +4374,12 @@ function stateModelFactory({
           return
         }
         transaction(() => {
-          self.colWidth = clamp(
-            self.msaCanvasWidth / (span.endCol - span.startCol + 1),
-            minColWidth,
-            maxCellSize,
+          self.setColWidth(
+            clamp(
+              self.msaCanvasWidth / (span.endCol - span.startCol + 1),
+              minColWidth,
+              maxCellSize,
+            ),
           )
           self.scrollX = clamp(
             -span.startCol * self.colWidth,
@@ -4700,10 +4425,12 @@ function stateModelFactory({
             const { rowRuns } = resolvedSelection
             const first = rowRuns[0]![0]
             const last = rowRuns.at(-1)![1]
-            self.rowHeight = clamp(
-              self.msaAreaHeight / (last - first + 1),
-              minRowHeight,
-              maxCellSize,
+            self.setRowHeight(
+              clamp(
+                self.msaAreaHeight / (last - first + 1),
+                minRowHeight,
+                maxCellSize,
+              ),
             )
             self.scrollY = clamp(-first * self.rowHeight, self.maxScrollY, 0)
           }
@@ -4744,13 +4471,15 @@ function stateModelFactory({
       /**
        * #action
        */
-      fitHorizontally() {
+      fitHorizontally(maxColWidth = maxCellSize) {
         if (self.numColumns > 0) {
           // msaCanvasWidth excludes the vertical scrollbar's 20px
-          self.colWidth = clamp(
-            self.msaCanvasWidth / self.numColumns,
-            minColWidth,
-            maxCellSize,
+          self.setColWidth(
+            clamp(
+              self.msaCanvasWidth / self.numColumns,
+              minColWidth,
+              maxColWidth,
+            ),
           )
         }
         self.scrollX = 0
@@ -4761,21 +4490,18 @@ function stateModelFactory({
           self.setHighlightedColumns(self.highlightColumns)
         }
 
-        // 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.
+        const awaitingTree = () => !!self.treeFilehandle && !self.data.tree
+
+        // `collapse`, `focus` and `rotate` marks seed `collapsed`, `showOnly`
+        // and `rotated`. Seeding runs once per data load, `clades` change and
+        // reroot, so expanding a seeded clade sticks until one of those. A tree
+        // filehandle holds it back, since `dataInitialized` is true while the
+        // tree is still the flat stub.
         addDisposer(
           self,
           reaction(
             () =>
-              self.dataInitialized && !(self.treeFilehandle && !self.data.tree)
+              self.dataInitialized && !awaitingTree()
                 ? { clades: getSnapshot(self.clades), treeRoot: self.treeRoot }
                 : undefined,
             seed => {
@@ -4813,7 +4539,7 @@ function stateModelFactory({
               region &&
               self.viewInitialized &&
               self.numColumns > 0 &&
-              !(self.treeFilehandle && !self.data.tree)
+              !awaitingTree()
             ) {
               this.revealRegion(region)
               self.setRegion(undefined)
@@ -4842,107 +4568,7 @@ function stateModelFactory({
           })
         }
 
-        /**
-         * Fetch a filehandle whenever it changes, and hand the text to
-         * `onLoad`.
-         *
-         * 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` 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()
-              const current = ++generation
-              cancelInFlight?.()
-              cancelInFlight = undefined
-              if (!filehandle) {
-                setLoading?.(false)
-                return
-              }
-              const isCurrent = () => current === generation && isAlive(self)
-              const controller = new AbortController()
-              cancelInFlight = () => {
-                controller.abort()
-                if (isAlive(self)) {
-                  self.setStatus(undefined)
-                }
-              }
-              try {
-                setLoading?.(true)
-                if (!optional) {
-                  self.setError(undefined)
-                }
-                const text = await fetchTextWithProgress(
-                  openLocation(filehandle),
-                  status => {
-                    if (isCurrent()) {
-                      self.setStatus(status)
-                    }
-                  },
-                  { controller },
-                )
-                if (isCurrent()) {
-                  transaction(() => {
-                    onLoad(text)
-                    if (filehandle.locationType === 'BlobLocation') {
-                      clearFilehandle?.()
-                    }
-                  })
-                }
-              } catch (e) {
-                if (isCurrent()) {
-                  if (isAbortError(e)) {
-                    clearFilehandle?.()
-                  } else {
-                    console.error(e)
-                    if (optional) {
-                      self.addWarning(`The ${what} did not load: ${e}`)
-                    } else {
-                      self.setError(e)
-                    }
-                  }
-                }
-              } finally {
-                if (isCurrent()) {
-                  cancelInFlight = undefined
-                  setLoading?.(false)
-                }
-              }
-            }),
-          )
-        }
-
-        loadOnFilehandleChange({
+        installFilehandleLoader(self, {
           what: 'tree',
           getFilehandle: () => self.treeFilehandle,
           onLoad: text => {
@@ -4957,7 +4583,7 @@ function stateModelFactory({
         })
 
         // treeMetadata has no import-form step, so no loading flag or cancel
-        loadOnFilehandleChange({
+        installFilehandleLoader(self, {
           what: 'row metadata',
           optional: true,
           getFilehandle: () => self.treeMetadataFilehandle,
@@ -4989,7 +4615,7 @@ function stateModelFactory({
         )
 
         // gffFilehandle loads into data.gff, which the autorun above parses
-        loadOnFilehandleChange({
+        installFilehandleLoader(self, {
           what: 'annotations',
           optional: true,
           getFilehandle: () => self.gffFilehandle,
@@ -5001,7 +4627,7 @@ function stateModelFactory({
           },
         })
 
-        loadOnFilehandleChange({
+        installFilehandleLoader(self, {
           what: 'alignment',
           getFilehandle: () => self.msaFilehandle,
           onLoad: text => {
@@ -5025,20 +4651,16 @@ function stateModelFactory({
           self,
           autorun(() => {
             if (self.dynamicColorSchemeName) {
-              // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
-              self.colStats
+              readComputed(self.colStats)
             }
             if (self.showColumnStats) {
-              // everything the hover tooltip reads per column
-              // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
-              self.colStats
-              // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
-              self.conservation
-              // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
-              self.propertyConservation
+              readComputed(
+                self.colStats,
+                self.conservation,
+                self.propertyConservation,
+              )
             }
-            // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
-            self.columns
+            readComputed(self.columns)
           }),
         )
       },