react-msaview 6.5.0 → 8.0.0

package/dist/model.js

@@ -1,21 +1,26 @@
 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, types, } from '@jbrowse/mobx-state-tree';
-import { colord } from 'colord';
+import { addDisposer, applySnapshot, cast, getSnapshot, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import { autorun, transaction } from 'mobx';
 import { generateNodeIds, gffToAnnotations, interProScanToAnnotations, parseEmfTree, parseGFF, parseMSA, parseNewick, } from 'msa-parsers';
 import { calculateBlocks } from './calculateBlocks.js';
 import { clustalXColumnColors } from './clustalX.js';
 import colorSchemes from './colorSchemes.js';
 import { columnCountsFromRows, letterOfResidueSlot } from './columnCounts.js';
+import { columnStats } from './columnStats.js';
+import { packDomainLanes } from './components/msa/packDomainLanes.js';
+import { visibleColRange } from './components/msa/visibleColRange.js';
 import TrackBlocks from './components/tracks/TrackBlocks.js';
-import { defaultAllowedGappyness, defaultColWidth, defaultColorSchemeName, defaultCurrentAlignment, defaultDrawMsaLetters, defaultHeight, defaultHideGaps, defaultRowHeight, defaultScrollX, defaultScrollY, defaultScrollZoom, defaultShowDomainLegend, defaultShowDomains, defaultSubFeatureRows, labelReferenceFontSize, maxCellSize, minColWidth, minLetterColWidth, minLetterRowHeight, minRowHeight, segmentFeatureTypes, segmentShades, } from './constants.js';
+import { cladeGutterWidth } from './components/tree/cladeBrackets.js';
+import { scaleBarLength } from './components/tree/scaleBar.js';
+import { cladeHighlightAlpha, cladeHighlightColor, defaultAllowedGappyness, defaultColWidth, defaultColorSchemeName, defaultCurrentAlignment, defaultDrawMsaLetters, defaultFeaturePanelWidth, defaultHeight, defaultHideGaps, defaultRowHeight, defaultScrollX, defaultScrollY, defaultScrollZoom, defaultScrollZoomAxis, defaultShowDomainLegend, defaultShowDomains, defaultSubFeatureRows, defaultTreeWidth, labelReferenceFontSize, maxCellSize, maxInlineSnapshotBytes, maxNeighborJoiningRows, minColWidth, minLetterColWidth, minLetterRowHeight, minRowHeight, rowPanelHeaderHeight, rowTintAlpha, scrollZoomAxes, segmentFeatureTypes, segmentShades, treeScaleBarHeight, } from './constants.js';
 import { createPaletteMap } from './createPaletteMap.js';
 import { exportFileName } from './exportFileName.js';
+import { featureField, featureName } from './featureFields.js';
 import { fetchTextWithProgress, isAbortError } from './fetchUtils.js';
 import { flatToTree } from './flatToTree.js';
-import { calcDepthToLeaf, clusterLayout, collapse, collapsedSubtreeMaxLength, find, findMaxBranchLen, forEachDescendant, hierarchy, leaves, links, maxLength, setBrLength, sort, sum as hierarchySum, } from './hierarchy.js';
+import { calcDepthToLeaf, clusterLayout, collapse, collapsedSubtreeMaxLength, find, forEachDescendant, hierarchy, leafIndex, leaves, maxLength, mrca, nodeCoveringRows, setBrLength, sort, sum as hierarchySum, } from './hierarchy.js';
 import { measureTextCanvas } from './measureTextCanvas.js';
 import { DataModelF } from './model/DataModel.js';
 import { DialogQueueSessionMixin } from './model/DialogQueue.js';
@@ -24,44 +29,176 @@ import { TreeModelF } from './model/treeModel.js';
 import { calculateNeighborJoiningTree } from './neighborJoining.js';
 import { parseAsn1 } from './parseAsn1.js';
 import { calculatePropertyConservation } from './propertyConservation.js';
-import { globalColToVisibleCol, visibleColToGlobalCol, visibleColToSeqPosForRow, visibleColsBefore, } from './rowCoordinateCalculations.js';
+import { globalColToVisibleCol, seqPosOfGlobalCol, visibleColToGlobalCol, visibleColsBefore, } from './rowCoordinateCalculations.js';
+import { resolveScale } from './scales.js';
 import { buildSeqPosIndex } from './seqPosToGlobalCol.js';
 import { maxBitsFor } from './sequenceLogo.js';
 import { stripDefault } from './stripDefault.js';
-import { computeRowInsertions, dropBlanks, len, skipBlanks, transform, } from './util.js';
+import { computeRowInsertions, dropBlanks, len, outlineColor, skipBlanks, transform, withAlpha, } from './util.js';
 import { saveAs } from './vendor/fileSaver.js';
+import { parseWuss } from './wuss.js';
 function parseTreeText(text) {
     if (text.startsWith('BioTreeContainer')) {
         return flatToTree(parseAsn1(text));
     }
     return parseNewick(text.startsWith('SEQ') ? parseEmfTree(text).tree : text);
 }
-// Tracks that start hidden. The sequence logo answers a narrower question than
-// conservation does and costs three times the vertical space, so it waits to be
-// asked for.
-const defaultOffTracks = new Set(['sequence-logo']);
+// The height each kind draws at before the user drags a divider. A text track
+// is absent: it is one alignment row tall and follows rowHeight, so the zoom
+// controls already size it.
+export const defaultTrackHeights = {
+    bar: 40,
+    // taller than a bar track: in a 40px stack of four residues each glyph is
+    // too short to identify. Twice the height of the tracks above it, so it
+    // starts hidden
+    logo: 80,
+    arc: 50,
+    ruler: 20,
+};
+// the kinds a divider resizes. The ruler is a fixed scale, and a text track
+// follows the vertical zoom.
+const resizableKinds = new Set(['bar', 'logo', 'arc']);
+const defaultOffTracks = new Set(['sequence-logo', 'position-ruler']);
+// a data track carries its own height rather than its kind's, so its divider
+// resizes it alone
+const ownHeightKey = (id) => `own:${id}`;
+// base-pair arcs: one color for nested helices, one for pseudoknots, which cross
+// them
+const HELIX_ARC = '#4e79a7';
+const PSEUDOKNOT_ARC = '#e15759';
+// the fill of a span under a scale that gives its value no color, such as a
+// gene a `map` over gene names leaves out
+const UNSCALED_FEATURE = '#d9d9d9';
+// the fraction of a span a following one may cover before it takes a lane of
+// its own in a `features` panel
+const laneOverlap = 0.1;
+// a row panel's own width, or a default: the row height, which makes a strip
+// cell square, and a gene neighborhood's width for a features panel
+function rowPanelWidth(panel, rowHeight) {
+    return (panel.width ??
+        (panel.kind === 'features' ? defaultFeaturePanelWidth : rowHeight));
+}
+// the fill and outline of every feature in a list: its own GFF `color=` first,
+// then the scale an encoding resolves over one of its fields, then the
+// accession palette
+function featureColorMap(annotations, encoding, fillPalette) {
+    const strokes = new Map();
+    const strokeOf = (fill) => {
+        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, field) {
+    const labels = new Map();
+    for (const annotation of annotations) {
+        const value = featureField(annotation, field);
+        if (value !== undefined) {
+            labels.set(annotation, value);
+        }
+    }
+    return labels;
+}
+/**
+ * The spans a `features` panel draws, keyed by row name and measured in the
+ * panel's own pixels. `column` takes the bands the overlay draws, at the
+ * alignment's column width. `position` packs each row's features in its own
+ * residue positions, shifted by an `align` transform, and maps the extent they
+ * cover across every row onto the panel width, so a row with no alignment
+ * still has an x.
+ */
+function featurePanelSpans({ panel, width, rowHeight, colWidth, domainBands, annotationsByRow, shifts, }) {
+    if (panel.x === 'column') {
+        return new Map([...domainBands].map(([name, bands]) => [
+            name,
+            bands.map(band => ({
+                ...band,
+                xStart: band.startCol * colWidth,
+                xEnd: band.endCol * colWidth,
+            })),
+        ]));
+    }
+    const shifted = Object.entries(annotationsByRow).map(([name, annotations]) => {
+        const shift = shifts?.get(name) ?? 0;
+        return [
+            name,
+            annotations.map(annotation => ({
+                annotation,
+                start: annotation.start - 1 + shift,
+                end: annotation.end + shift,
+            })),
+        ];
+    });
+    let min = Infinity;
+    let max = -Infinity;
+    for (const [, features] of shifted) {
+        for (const { start, end } of features) {
+            min = Math.min(min, start);
+            max = Math.max(max, end);
+        }
+    }
+    // the arrowhead on the rightmost feature reaches a row height past its end,
+    // so the extent maps onto the panel less that much
+    const drawable = Math.max(1, width - rowHeight);
+    const scale = max > min ? drawable / (max - min) : 0;
+    // a lane opens where a span covers more than a tenth of the one before it,
+    // which keeps the genes of an operon on one lane: adjacent genes commonly
+    // share a few bases, and a stop codon overlapping the next start reads as a
+    // second lane over the whole row
+    return new Map(shifted.map(([name, features]) => [
+        name,
+        packDomainLanes(features.map(({ annotation, start, end }) => ({
+            annotation,
+            xStart: (start - min) * scale,
+            xEnd: (end - min) * scale,
+            startCol: start,
+            endCol: end - (end - start) * laneOverlap,
+        }))),
+    ]));
+}
+// a scale over the values a field takes across the features drawn
+function resolveFeatureScale(field, scale, annotations) {
+    return {
+        field,
+        ...resolveScale(scale, annotations.map(a => featureField(a, field)).filter(notEmpty)),
+    };
+}
 // a data track over this size stays in the live model but leaves the snapshot,
 // the same rule DataModel applies to an inline document
-const maxColumnTrackSnapshotBytes = 50_000;
+function columnTrackSizes(tracks) {
+    return (tracks ?? []).map(t => JSON.stringify(t).length);
+}
 function smallColumnTracks(tracks) {
-    const kept = tracks?.filter(t => JSON.stringify(t).length <= maxColumnTrackSnapshotBytes);
+    const sizes = columnTrackSizes(tracks);
+    const kept = tracks?.filter((_t, i) => sizes[i] <= maxInlineSnapshotBytes);
     return kept?.length ? { columnTracks: kept } : {};
 }
 /**
  * The snapshot properties reset() carries across a return to the import form:
  * display preferences and layout, nothing derived from the loaded file.
  *
- * reset() applies a default snapshot filtered to this list, so the list is the
- * whole decision: a property left off it resets to its default, a visible and
- * benign failure. The previous shape — a hand-maintained list of things to
- * CLEAR — failed in the dangerous direction: a forgotten property silently
- * carried the previous file's state into the next one, and because node ids
- * are path-derived (node-0-0-1), a stale `collapsed` or `showOnly` id matched
- * a real node in the new tree and folded it. Downstream composed properties
- * (e.g. the jbrowse plugin's) are not on the list, so they reset too.
+ * reset() applies a default snapshot filtered to this list, so any property
+ * left off it resets, including downstream composed ones (e.g. the jbrowse
+ * plugin's). Node ids are path-derived (node-0-0-1), so a carried-over
+ * `collapsed` or `showOnly` id would match a real node in the next tree and
+ * fold it.
  *
- * Exported for modelReset.test.ts, which checks that everything off this list
- * matches a freshly created model after reset().
+ * Exported for modelReset.test.ts.
  */
 export const preservedOnReset = new Set([
     'id',
@@ -69,6 +206,7 @@ export const preservedOnReset = new Set([
     'height',
     'drawMsaLetters',
     'scrollZoom',
+    'scrollZoomAxis',
     'bgColor',
     'colorSchemeName',
     'showColumnStats',
@@ -79,19 +217,166 @@ export const preservedOnReset = new Set([
     'showBranchLen',
     'drawTree',
     'drawNodeBubbles',
+    'drawNodeLabels',
+    'showTreeOverview',
+    'overviewHeight',
     'autoTreeAreaWidth',
     'turnedOffTracks',
+    'trackHeights',
     'hideGaps',
     'allowedGappyness',
     'subFeatureRows',
     'showDomainLegend',
 ]);
-// `turnedOffTracks` records the user's explicit choices only: an id is absent
-// until they touch that track, and then its value is whether the track is OFF.
-// Reading the default through this is what lets a track ship hidden without
-// writing an entry into every snapshot and shared URL.
-function trackIsOff(turnedOffTracks, id) {
-    return turnedOffTracks.get(id) ?? defaultOffTracks.has(id);
+// `turnedOffTracks` holds only the user's explicit choices, so a hidden-by-default
+// track writes nothing into the snapshot. A file-supplied track passes its own
+// `defaultOff`, since the count varies by file: a Pfam seed has a couple of #=GR
+// lines, an Rfam family one per row.
+function trackIsOff(turnedOffTracks, id, defaultOff) {
+    return turnedOffTracks.get(id) ?? (defaultOff || defaultOffTracks.has(id));
+}
+// shared empty results, so observers don't see a fresh [] as a change
+const noDomains = [];
+const noClades = [];
+/**
+ * The rows a clade covers and the node an `mrca` names, or undefined when the
+ * clade does not resolve: a tip name the tree does not have or has twice, or a
+ * leaf count `tips` disagrees with. `index` and `rowNamesSet` are the memoized
+ * passes over the tree.
+ */
+function cladeRows(clade, root, index, rowNamesSet) {
+    if (clade.range) {
+        const [a, b] = clade.range.map(name => index.get(name) ? rowNamesSet.get(name) : undefined);
+        if (a === undefined || b === undefined) {
+            return undefined;
+        }
+        const rows = a <= b ? [a, b] : [b, a];
+        return rows[1] - rows[0] + 1 === clade.tips ? { rows } : undefined;
+    }
+    const node = clade.mrca ? mrca(root, clade.mrca, index) : undefined;
+    if (!node) {
+        return undefined;
+    }
+    const tips = leaves(node);
+    if (tips.length !== clade.tips) {
+        return undefined;
+    }
+    let first = Infinity;
+    let last = -Infinity;
+    for (const tip of tips) {
+        const row = rowNamesSet.get(tip.data.name);
+        if (row !== undefined) {
+            first = Math.min(first, row);
+            last = Math.max(last, row);
+        }
+    }
+    return first <= last
+        ? { rows: [first, last], nodeId: node.data.id }
+        : undefined;
+}
+/**
+ * Every clade that resolves, with its fill color settled, against the leaf
+ * order `rowNamesSet` gives. The tree panel resolves against the displayed
+ * rows and the overview against its own, so both take the tree they draw. A
+ * `range` record names no node, so `collapse` and `focus`, which need one,
+ * drop it.
+ */
+function resolveClades(clades, root, rowNamesSet) {
+    const index = leafIndex(root);
+    return clades.flatMap(clade => {
+        const resolved = cladeRows(clade, root, index, rowNamesSet);
+        const seeding = clade.mark === 'collapse' || clade.mark === 'focus';
+        return resolved && !(seeding && resolved.nodeId === undefined)
+            ? [
+                {
+                    ...resolved,
+                    mark: clade.mark,
+                    color: withAlpha(clade.color ?? cladeHighlightColor, cladeHighlightAlpha),
+                    markColor: clade.color,
+                    label: clade.label,
+                },
+            ]
+            : [];
+    });
+}
+/**
+ * The tree with the display transforms applied: leaf counts summed, children
+ * sorted by branch length, `showOnly` taken as the new root, and each
+ * `collapsed` clade folded. The overview builds the same tree without the
+ * focus, so it shows the focused subtree inside the whole.
+ */
+function buildTreeRoot(tree, collapsed, showOnly) {
+    let hier = hierarchy(tree, d => d.children);
+    hierarchySum(hier, d => (d.children.length > 0 ? 0 : 1));
+    sort(hier, (a, b) => (a.data.length ?? 1) - (b.data.length ?? 1));
+    if (showOnly) {
+        const res = find(hier, n => n.data.id === showOnly);
+        if (res) {
+            hier = res;
+        }
+    }
+    for (const collapsedId of collapsed) {
+        const node = find(hier, n => n.data.id === collapsedId);
+        if (node) {
+            if (node.children) {
+                collapse(node);
+            }
+            else if (node.parent?.children) {
+                node.parent.children = node.parent.children.filter(c => c.data.id !== collapsedId);
+            }
+        }
+    }
+    return hier;
+}
+// the inclusive tip indices a node covers, from the row-space extent
+// clusterLayout writes to xMin/xMax as tip centers
+function tipRange(node) {
+    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([
+    'featureFill',
+    'featureLabel',
+]);
+// seqPos -> column indexes per row, keyed on the parse so they are garbage
+// collected with it. A computed would rebuild every row's index when read
+// outside a reactive context.
+const seqPosIndexCache = new WeakMap();
+// A segment is a 1:1 run. A segment whose sides differ in length is malformed,
+// and the lookups treat it like an uncovered position.
+function sameLength(segment) {
+    return (segment.rowEnd - segment.rowStart ===
+        segment.structEnd - segment.structStart);
+}
+// fit() divides the viewport by the row or column count and multiplies back, so
+// an exact fit can land a fraction of a pixel over. A plain `>` would then show
+// a scrollbar that shrinks the viewport and leaves a gap.
+function overflows(content, viewport) {
+    return content - viewport > 0.5;
+}
+function inRanges(ranges, position) {
+    return !!ranges?.some(([start, end]) => position >= start && position <= end);
+}
+// the value every one of a node's children reports, or undefined where one of
+// them has no value or they disagree
+function sharedValue(values) {
+    const [first] = values;
+    return first !== undefined && values.every(v => v === first)
+        ? first
+        : undefined;
+}
+// preorder, so reversing the list puts every node after its descendants
+function preorder(tree) {
+    const order = [];
+    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;
 }
 /**
  * #stateModel MsaView
@@ -128,10 +413,8 @@ function stateModelFactory() {
         /**
          * #property
          * whether the domain legend is expanded. The legend floats over the
-         * top-right of the alignment, so on a tall panel it covers real
-         * residues -- persisting the state is what lets a reader collapse it
-         * and keep it collapsed, and what lets a session or a figure open with
-         * it already out of the way.
+         * top-right of the alignment and covers residues, so a session or
+         * figure can open with it collapsed.
          */
         showDomainLegend: stripDefault(types.boolean, defaultShowDomainLegend),
         /**
@@ -160,6 +443,11 @@ function stateModelFactory() {
          * zoom in/out on plain mouse-wheel without holding ctrl
          */
         scrollZoom: stripDefault(types.boolean, defaultScrollZoom),
+        /**
+         * #property
+         * which cell dimensions a wheel zoom scales, while `scrollZoom` is on
+         */
+        scrollZoomAxis: stripDefault(types.enumeration('ScrollZoomAxis', [...scrollZoomAxes]), defaultScrollZoomAxis),
         /**
          * #property
          * height of the div containing the view, px
@@ -231,11 +519,27 @@ function stateModelFactory() {
         turnedOffTracks: stripDefault(types.map(types.boolean), {}),
         /**
          * #property
-         * tracks supplied as data rather than computed from the alignment:
-         * per-column values drawn as bars, or a per-column string drawn as a
-         * text track. See docs/layers.md
+         * the height of every track one divider resizes, keyed by `heightKey`:
+         * the `kind` for the computed tracks, `own:<id>` for a data track. A
+         * key is absent until the user drags that divider, and
+         * `defaultTrackHeights` answers for it until then, so an untouched
+         * viewer adds nothing to the shared URL.
+         */
+        trackHeights: stripDefault(types.map(types.number), {}),
+        /**
+         * #property
+         * tracks supplied as data: per-column values drawn as bars, or a
+         * per-column string drawn as a text track. See docs/layers.md
          */
         columnTracks: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * row-to-structure residue correspondence, computed outside the viewer
+         * (e.g. from SIFTS). Matching by sequence equality places a tagged
+         * construct, a truncation or a subsequence row on the wrong residue.
+         * See docs/layers.md
+         */
+        residueMappings: stripDefault(types.array(types.frozen()), []),
         /**
          * #property
          * data from the loaded tree/msa/treeMetadata, generally loaded by
@@ -248,8 +552,12 @@ function stateModelFactory() {
         }),
         /**
          * #property
+         * the user's explicit hide choices per annotation accession, keyed by
+         * accession with the value meaning "off", like `turnedOffTracks`. An
+         * untouched accession is absent and drawn, so the shared URL grows
+         * only with the user's filters
          */
-        featureFilters: stripDefault(types.map(types.boolean), {}),
+        turnedOffFeatures: stripDefault(types.map(types.boolean), {}),
         /**
          * #property
          */
@@ -268,24 +576,53 @@ function stateModelFactory() {
          * labeled highlights in 1-based inclusive coordinates: a column span
          * `{start, end}`, a residue span `{row, start, end}` of a named row,
          * or a row set `{rows}`, each with an optional `label` and `color`.
-         * Persists in the snapshot, so a computed answer travels in the URL.
+         * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * clades of the tree with a mark drawn over them. `mrca` names tips
+         * whose common ancestor is the clade, or `range` its first and last
+         * tip in display order, and `tips` is the leaf count the producer
+         * measured. `mark` is `highlight`, `bracket`, `collapse` or `focus`.
+         * See docs/layers.md
+         */
+        clades: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * what the viewer's own marks read from `rowData`:
+         * `{channel, field, scale?}` per channel, where `channel` is
+         * `tipLabel` or `rowTint`. See docs/layers.md
+         */
+        encodings: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * panels drawn between the tree and the alignment:
+         * `{kind: "strip", field, scale?, width?, header?}` colors one cell
+         * per row from a `rowData` field, and
+         * `{kind: "features", x, encoding?, transform?, width?, header?}`
+         * draws the spans the GFF carries. See docs/layers.md
+         */
+        rowPanels: stripDefault(types.array(types.frozen()), []),
     }))
         .volatile(() => ({
         /**
          * #volatile
          */
         headerHeight: 0,
+        /**
+         * #volatile
+         * leaves the toolbar out, for a host drawing its own controls. Kept out
+         * of the snapshot so a link opened in the full app shows the toolbar.
+         */
+        hideHeader: false,
         /**
          * #volatile
          */
         status: undefined,
         /**
          * #volatile
-         * high resolution scale factor, helps make canvas look better on hi-dpi
-         * screens. derived from the device pixel ratio so canvases are crisp on
-         * retina/4k displays and not needlessly oversized on standard ones
+         * canvas scale factor, from the device pixel ratio
          */
         highResScaleFactor: typeof window === 'undefined' ? 1 : window.devicePixelRatio,
         /**
@@ -340,6 +677,12 @@ function stateModelFactory() {
          * array of column indices to highlight
          */
         highlightedColumns: undefined,
+        /**
+         * #volatile
+         * transient highlights keyed by owner, so a structure viewer's hover and
+         * a genome view's hover each clear only their own. Not persisted.
+         */
+        transientHighlights: {},
         /**
          * #volatile
          */
@@ -347,29 +690,36 @@ function stateModelFactory() {
         /**
          * #volatile
          */
-        conservationTrackHeight: 40,
+        marginLeft: 20,
+        /**
+         * #volatile
+         */
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+        error: undefined,
         /**
          * #volatile
-         * taller than the conservation track by default: the logo spends its
-         * height on stacked glyphs, and a 40px stack of four residues leaves each
-         * one too short to identify
+         * 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
          */
-        sequenceLogoTrackHeight: 80,
+        warnings: [],
         /**
          * #volatile
+         * bumped by reset(). The error boundary above the view uses it as its key,
+         * since the boundary keeps its caught error until remounted
          */
-        marginLeft: 20,
+        resetCount: 0,
         /**
          * #volatile
+         * set by a host that restores the loaded documents itself, such as a
+         * jbrowse session or a page that refetches them. `unshareableData` then
+         * reports nothing
          */
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-        error: undefined,
+        hostCarriesData: false,
         /**
          * #volatile
-         * overlay annotations drawn on the alignment, whatever their source.
-         * Every source -- InterProScan, GFF, a user upload -- converts to this
-         * flat list before it reaches the model, so nothing downstream of here
-         * knows which one it came from
+         * overlay annotations drawn on the alignment. InterProScan JSON, GFF and
+         * user uploads all convert to this flat list
          */
         annotations: [],
     }))
@@ -415,8 +765,8 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * high-res scale factor, tracks the device pixel ratio so canvases stay
-         * crisp when the window moves between monitors or the browser zooms
+         * update the canvas scale factor when the device pixel ratio changes
+         * (moving between monitors, browser zoom)
          */
         setHighResScaleFactor(arg) {
             self.highResScaleFactor = arg;
@@ -435,13 +785,35 @@ function stateModelFactory() {
         setError(error) {
             self.error = error;
         },
+        /**
+         * #action
+         * record a non-fatal load problem: a layer that failed to load, a file
+         * that failed to parse
+         */
+        addWarning(warning) {
+            self.warnings = [...self.warnings, warning];
+        },
+        /**
+         * #action
+         */
+        clearWarnings() {
+            self.warnings = [];
+        },
+        /**
+         * #action
+         * declare that this host restores the loaded documents itself, which
+         * hides the "Not in the link" warning. See `hostCarriesData`
+         */
+        setHostCarriesData(arg) {
+            self.hostCarriesData = arg;
+        },
         /**
          * #action
          * set mouse position (row, column) in the MSA
          *
-         * CROSS-REPO CONTRACT: jbrowse-plugin-protein3d calls this (and reads the
-         * `mouseCol` volatile) to sync MSA<->3D-structure hover. Keep the name and
-         * signature stable; see that repo's ProteinToMsaHoverSync.tsx.
+         * Public API: a host calls this (and reads `mouseCol`) to sync hover with
+         * its own view, such as a genome view or 3D structure. Keep the name and
+         * signature stable.
          */
         setMousePos(col, row) {
             self.mouseCol = col;
@@ -451,9 +823,9 @@ function stateModelFactory() {
          * #action
          * set highlighted columns
          *
-         * CROSS-REPO CONTRACT: called by jbrowse-plugin-msaview
-         * (afterCreateAutoruns.ts) to highlight alignment columns. It has no
-         * in-repo caller, so do not flag it as dead code — it is public API.
+         * Public API: jbrowse-plugin-msaview calls this from its
+         * afterCreateAutoruns, and MSAViewer passes its `highlightColumns` prop
+         * through it.
          */
         setHighlightedColumns(columns) {
             self.highlightedColumns = columns;
@@ -464,6 +836,34 @@ function stateModelFactory() {
         setHighlights(highlights) {
             self.highlights.replace(highlights);
         },
+        /**
+         * #action
+         * replace the clades the viewer marks (see docs/layers.md)
+         */
+        setClades(clades) {
+            self.clades.replace(clades);
+        },
+        /**
+         * #action
+         * show `highlights` for `owner`, replacing that owner's previous ones and
+         * leaving other owners' in place
+         */
+        applyHighlight(owner, highlights) {
+            self.transientHighlights = {
+                ...self.transientHighlights,
+                [owner]: highlights,
+            };
+        },
+        /**
+         * #action
+         * remove `owner`'s highlights, leaving other owners' in place
+         */
+        clearHighlight(owner) {
+            if (owner in self.transientHighlights) {
+                const { [owner]: _dropped, ...rest } = self.transientHighlights;
+                self.transientHighlights = rest;
+            }
+        },
         /**
          * #action
          * toggle the annotation overlay on the alignment
@@ -508,10 +908,22 @@ function stateModelFactory() {
         },
         /**
          * #action
-         *
+         * switch to another alignment of a multi-alignment file (Stockholm).
+         * Clears the collapsed node ids, the subtree in focus, the reference row
+         * and the scroll position, which all refer to the previous alignment
          */
         setCurrentAlignment(n) {
-            self.currentAlignment = n;
+            if (n === self.currentAlignment) {
+                return;
+            }
+            transaction(() => {
+                self.currentAlignment = n;
+                self.collapsed.clear();
+                this.setShowOnly(undefined);
+                this.drawRelativeTo(undefined);
+                self.scrollX = 0;
+                self.scrollY = 0;
+            });
         },
         /**
          * #action
@@ -583,6 +995,16 @@ function stateModelFactory() {
         setTreeMetadata(result) {
             self.data.setTreeMetadata(result);
         },
+        /**
+         * #action
+         * store the GFF text in the snapshot like the alignment and tree. The
+         * parsed annotations are volatile and a blob filehandle is cleared once
+         * read, so the text is the only persisted copy. An autorun parses it
+         * into annotations.
+         */
+        setGFF(result) {
+            self.data.setGFF(result);
+        },
     }))
         .views(self => ({
         /**
@@ -605,6 +1027,20 @@ function stateModelFactory() {
         get actuallyShowDomains() {
             return self.showDomains && self.annotations.length > 0;
         },
+        /**
+         * #getter
+         * whether the host restores the loaded documents outside the snapshot.
+         * When true, `unshareableData` is empty.
+         *
+         * A simple host sets `hostCarriesData`. A host where this depends on how
+         * the view was opened overrides the getter in its own composed model's
+         * `.views` block; jbrowse-plugin-msaview's indexed-location views refetch
+         * from a URL the session holds, while its data-store views do not.
+         * `unshareableData` reads it off `self`, so an override takes effect.
+         */
+        get hostRestoresData() {
+            return self.hostCarriesData;
+        },
         get viewInitialized() {
             return self.volatileWidth !== undefined;
         },
@@ -619,19 +1055,12 @@ function stateModelFactory() {
         },
     }))
         .views(self => ({
-        /**
-         * #method
-         * unused here, but can be used by derived classes to add extra items
-         */
-        extraViewMenuItems() {
-            return [];
-        },
         /**
          * #getter
          */
         get colorScheme() {
-            // colorSchemeName is a free string (menus, snapshots, URL params); fall
-            // back to the default rather than returning undefined on a stale name
+            // colorSchemeName is a free string (menus, snapshots, URL params), so a
+            // stale name falls back to the default
             return (colorSchemes[self.colorSchemeName] ??
                 colorSchemes[defaultColorSchemeName]);
         },
@@ -656,18 +1085,53 @@ function stateModelFactory() {
         get noDomains() {
             return self.annotations.length === 0;
         },
+        /**
+         * #getter
+         * loaded documents left out of the snapshot, largest first. A file opened
+         * from disk or pasted in becomes inline text, and DataModel drops an
+         * inline document past `maxInlineSnapshotBytes`.
+         *
+         * The header lists these, and the standalone app stops rewriting the
+         * address bar while the list is non-empty, so a copied link does not
+         * open an empty viewer unannounced. A document fetched from a URL never
+         * appears here, since the snapshot keeps its filehandle.
+         *
+         * Empty when `hostRestoresData` is true.
+         */
+        get unshareableData() {
+            if (self.hostRestoresData) {
+                return [];
+            }
+            const { data } = self;
+            // data tracks past the limit also leave the snapshot
+            const trackBytes = columnTrackSizes(self.columnTracks)
+                .filter(bytes => bytes > maxInlineSnapshotBytes)
+                .reduce((a, b) => a + b, 0);
+            return [
+                ['alignment', data.msa, self.msaFilehandle],
+                ['tree', data.tree, self.treeFilehandle],
+                ['annotations', data.gff, self.gffFilehandle],
+                ['row metadata', data.treeMetadata, self.treeMetadataFilehandle],
+            ]
+                .flatMap(([what, text, filehandle]) => !filehandle && text && text.length > maxInlineSnapshotBytes
+                ? [{ what, bytes: text.length }]
+                : [])
+                .concat(trackBytes ? [{ what: 'data tracks', bytes: trackBytes }] : [])
+                .sort((a, b) => b.bytes - a.bytes);
+        },
         menuItems() {
             return [];
         },
         /**
          * #getter
-         * extra per-row attributes, keyed by row name. Parsed defensively: the
-         * source is a user-supplied document (treeMetadataFilehandle, or a
-         * session snapshot), and this computed is read by labelWidthMap on every
-         * layout, so a malformed file would otherwise throw out of rendering and
-         * take the whole view down over a decorative field.
+         * the row table: extra fields per row, keyed by row name, which the
+         * `encodings` channels read. It is stored as the JSON string
+         * `data.treeMetadata`, the name that travels in existing links, so the
+         * inline size limit and `treeMetadataFilehandle` cover it. labelWidthMap
+         * reads it on every layout, so a malformed user-supplied file returns {}
+         * instead of throwing out of rendering.
          */
-        get treeMetadata() {
+        get rowData() {
             const text = self.data.treeMetadata;
             if (!text) {
                 return {};
@@ -679,10 +1143,31 @@ function stateModelFactory() {
                     : {};
             }
             catch (e) {
-                console.error('failed to parse treeMetadata', e);
+                console.error('failed to parse rowData', e);
                 return {};
             }
         },
+        /**
+         * #method
+         * one row's fields, the single reader of the row table
+         */
+        rowDataOf(name) {
+            return this.rowData[name];
+        },
+        /**
+         * #getter
+         * the field names the row table carries, sorted, for a producer or a UI
+         * choosing one to encode
+         */
+        get rowFields() {
+            const fields = new Set();
+            for (const row of Object.values(this.rowData)) {
+                for (const field of Object.keys(row ?? {})) {
+                    fields.add(field);
+                }
+            }
+            return [...fields].sort((a, b) => a.localeCompare(b));
+        },
         /**
          * #getter
          */
@@ -728,6 +1213,33 @@ function stateModelFactory() {
         get rowNamesSet() {
             return new Map(this.leaves.map((leaf, index) => [leaf.data.name, index]));
         },
+        /**
+         * #getter
+         * `clades` resolved to the rows each one covers. The tip names resolve
+         * against `tree` rather than `root`, so a clade whose ancestor the user
+         * collapsed keeps its rows. One leaf pass over the tree serves every
+         * clade. A `range` record names no node, so `collapse` and `focus`, which
+         * need one, drop it.
+         */
+        get resolvedClades() {
+            if (self.clades.length === 0) {
+                return noClades;
+            }
+            return resolveClades(self.clades, hierarchy(this.tree, d => d.children), this.rowNamesSet);
+        },
+        /**
+         * #getter
+         * the pixel column reserved at the right of the tree area for the bracket
+         * mark, which the tip labels and the tree itself stay clear of. Zero
+         * where no clade draws a bar or a label.
+         */
+        get cladeGutterWidth() {
+            return cladeGutterWidth({
+                clades: this.resolvedClades,
+                rowHeight: self.rowHeight,
+                fontSize: this.fontSize,
+            });
+        },
         /**
          * #getter
          */
@@ -760,40 +1272,128 @@ function stateModelFactory() {
          * #getter
          */
         get root() {
-            let hier = hierarchy(this.tree, d => d.children);
-            hierarchySum(hier, d => (d.children.length > 0 ? 0 : 1));
-            sort(hier, (a, b) => (a.data.length ?? 1) - (b.data.length ?? 1));
-            if (self.showOnly) {
-                const res = find(hier, n => n.data.id === self.showOnly);
-                if (res) {
-                    hier = res;
-                }
+            return buildTreeRoot(this.tree, self.collapsed, self.showOnly);
+        },
+        /**
+         * #getter
+         * height of the band the tree overview draws in, zero when it is off
+         */
+        get treeOverviewHeight() {
+            return self.showTreeOverview ? self.overviewHeight : 0;
+        },
+        /**
+         * #getter
+         * the whole tree laid out for the overview, or undefined when the
+         * overview is off. The focus is left out, so the focused subtree draws
+         * inside the whole tree, and the collapsed clades are folded, since
+         * those are rows the view no longer has. `x` is in tip-index space and
+         * `len` is a fraction of the root-to-tip length, so one layout serves
+         * any band size.
+         */
+        get treeOverviewLayout() {
+            if (!self.showTreeOverview) {
+                return undefined;
             }
-            for (const collapsedId of self.collapsed) {
-                const node = find(hier, n => n.data.id === collapsedId);
-                if (node) {
-                    if (node.children) {
-                        collapse(node);
-                    }
-                    else if (node.parent?.children) {
-                        node.parent.children = node.parent.children.filter(c => c.data.id !== collapsedId);
-                    }
-                }
+            const root = buildTreeRoot(this.tree, self.collapsed);
+            const numTips = leaves(root).length;
+            clusterLayout(root, numTips, 1);
+            const rootLen = Math.max(root.data.length || 0, 0);
+            const extent = maxLength(root) - rootLen;
+            setBrLength(root, -rootLen, extent ? 1 / extent : 0);
+            return {
+                root,
+                numTips,
+                maxDepthToLeaf: calcDepthToLeaf(root),
+                showBranchLen: self.showBranchLen && extent > 0,
+            };
+        },
+        /**
+         * #getter
+         * the `clades` highlights in the overview's own row space, which the
+         * focus does not narrow
+         */
+        get treeOverviewClades() {
+            const layout = this.treeOverviewLayout;
+            if (!layout || self.clades.length === 0) {
+                return noClades;
+            }
+            const rowNames = new Map(leaves(layout.root).map((leaf, index) => [leaf.data.name, index]));
+            return resolveClades(self.clades, layout.root, rowNames);
+        },
+        /**
+         * #getter
+         * the inclusive tip rows the focused subtree covers in the overview,
+         * which is the box drawn on it. undefined with no focus
+         */
+        get treeOverviewFocusRows() {
+            const layout = this.treeOverviewLayout;
+            if (!layout || !self.showOnly) {
+                return undefined;
+            }
+            const node = find(layout.root, n => n.data.id === self.showOnly);
+            return node ? tipRange(node) : undefined;
+        },
+        /**
+         * #method
+         * the subtree a point `y` pixels down the tree overview picks: the
+         * deepest one whose tip range covers every row under that pixel, with
+         * the rows it covers. A pixel stands for several tips on a large tree,
+         * which is what keeps the pick off the individual tips. undefined when
+         * the overview is off or the point picks the whole tree.
+         */
+        treeOverviewHit(y) {
+            const layout = this.treeOverviewLayout;
+            if (!layout) {
+                return undefined;
             }
-            return hier;
+            const { root, numTips } = layout;
+            const perPixel = numTips / self.overviewHeight;
+            const first = clamp(Math.floor(y * perPixel), 0, numTips - 1);
+            const last = clamp(Math.ceil((y + 1) * perPixel) - 1, first, numTips - 1);
+            let node = nodeCoveringRows(root, first + 0.5, last + 0.5);
+            // focusing one tip leaves a single row on screen, so the pick lifts to
+            // the subtree that tip sits in
+            while (!node.children && node.parent) {
+                node = node.parent;
+            }
+            return node === root
+                ? undefined
+                : { id: node.data.id, rows: tipRange(node) };
+        },
+        /**
+         * #getter
+         * the pixel column the row panels occupy between the tree and the
+         * alignment, the sum of each record's width
+         */
+        get rowPanelsWidth() {
+            return sum(self.rowPanels.map(p => rowPanelWidth(p, self.rowHeight)));
+        },
+        /**
+         * #getter
+         * height of the band the row panel headers draw in, which is zero with
+         * no row panels and leaves the top area as it was
+         */
+        get rowPanelsHeaderHeight() {
+            return self.rowPanels.length > 0 ? rowPanelHeaderHeight : 0;
         },
         /**
          * #getter
-         * widget width minus the tree area gives the space for the MSA
+         * widget width minus the tree area and the row panels gives the space
+         * for the MSA
          */
         get msaAreaWidth() {
-            return self.width - self.treeAreaWidth - self.resizeHandleWidth;
+            return (self.width -
+                self.treeAreaWidth -
+                this.rowPanelsWidth -
+                self.resizeHandleWidth);
         },
         /**
          * #getter
+         * the right edge the tip labels end at, which is the tree area less the
+         * margin and the bracket gutter
          */
         get treeAreaWidthMinusMargin() {
-            return self.treeAreaWidth - self.marginLeft;
+            return self.treeAreaWidth - self.marginLeft - this.cladeGutterWidth;
         },
         /**
          * #getter
@@ -863,28 +1463,50 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * number of rows the alignment occupies on screen. This is the leaf count,
-         * not `rows.length`: a tree leaf with no matching MSA row still takes up a
-         * row of vertical space (drawn blank), so row hit-testing and fit-to-height
-         * must count it.
+         * number of rows on screen: the leaf count, which includes tree leaves
+         * with no matching MSA row (drawn blank), unlike `rows.length`.
          */
         get numRows() {
             return this.leaves.length;
         },
         /**
-         * #getter
-         * per-row index of the global column holding each ungapped sequence
-         * position, so seqPos -> column is a lookup rather than a scan of the row.
-         * The domain overlay resolves thousands of these per redraw.
+         * #method
+         * index of the global column holding each ungapped sequence position of a
+         * row. The domain overlay resolves thousands of these per redraw. Built
+         * lazily per row and cached on the parse.
          */
-        get seqPosGlobalColIndex() {
-            return new Map(this.rows.map(([name, seq]) => [name, buildSeqPosIndex(seq)]));
+        seqPosIndex(rowName) {
+            const MSA = this.MSA;
+            if (!MSA) {
+                return undefined;
+            }
+            let cache = seqPosIndexCache.get(MSA);
+            if (!cache) {
+                cache = new Map();
+                seqPosIndexCache.set(MSA, cache);
+            }
+            let index = cache.get(rowName);
+            if (!index) {
+                const seq = MSA.getRow(rowName);
+                if (!seq) {
+                    return undefined;
+                }
+                index = buildSeqPosIndex(seq);
+                cache.set(rowName, index);
+            }
+            return index;
         },
         /**
          * #getter
+         * every sequence in the alignment, keyed by row name, including rows a
+         * collapsed clade hides. `rows` holds only the rows on screen; lookups
+         * by row name use this
          */
         get rowMap() {
-            return new Map(this.rows);
+            const MSA = this.MSA;
+            return new Map(MSA?.getNames()
+                .map(name => [name, MSA.getRow(name)])
+                .filter(([, seq]) => !!seq));
         },
         /**
          * #getter
@@ -1009,10 +1631,11 @@ function stateModelFactory() {
         get hierarchy() {
             const r = this.root;
             clusterLayout(r, this.totalHeight, self.treeWidth);
-            r.data.length = 0;
-            const max = maxLength(r);
+            const max = this.rootToTipLength;
             const k = max ? self.treeWidth / max : 0;
-            setBrLength(r, 0, k);
+            // the displayed root starts at x=0, so subtract its length here; `root`
+            // returns the cached parse, which must not be mutated
+            setBrLength(r, -Math.max(r.data.length || 0, 0), k);
             // for each collapsed clade, record the pixel x-position of its farthest
             // tip so the renderer can draw a triangle spanning the branch-length
             // extent of the hidden subtree
@@ -1038,10 +1661,29 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * max branch length across the tree, used to scale phylogram x-positions
+         * branch-length extent of the displayed tree, root to farthest tip, in
+         * the tree's own units
+         */
+        get rootToTipLength() {
+            const r = this.root;
+            return maxLength(r) - Math.max(r.data.length || 0, 0);
+        },
+        /**
+         * #getter
+         * x-position of the farthest tip in a phylogram, px: treeWidth, or 0 for
+         * a tree with no branch lengths (drawn as a cladogram)
          */
         get maxBranchLength() {
-            return findMaxBranchLen(this.hierarchy);
+            return this.rootToTipLength ? self.treeWidth : 0;
+        },
+        /**
+         * #getter
+         * pixels per unit of branch length in the phylogram layout, 0 in
+         * cladogram mode. The tree's scale bar uses it.
+         */
+        get pxPerBranchLength() {
+            const max = maxLength(this.root);
+            return this.showBranchLenEffective && max ? self.treeWidth / max : 0;
         },
         /**
          * #getter
@@ -1054,7 +1696,7 @@ function stateModelFactory() {
          * #getter
          */
         get allBranchesLength0() {
-            return links(this.hierarchy).every(s => !s.source.data.length);
+            return this.rootToTipLength === 0;
         },
         /**
          * #getter
@@ -1076,88 +1718,711 @@ function stateModelFactory() {
         /**
          * #getter
          */
-        get dataInitialized() {
-            // truthiness, not `!== ''`: these are types.maybe, and DataModel's
-            // postProcessSnapshot drops a document over 50kb, so a restored session
-            // that inlined a large alignment comes back `undefined` here -- which
-            // `!== ''` reads as initialized and renders an empty view instead of
-            // the import form
-            return !!(self.data.msa || self.data.tree) && !self.error;
-        },
-        /**
-         * #getter
-         */
-        get blocksX() {
-            return calculateBlocks({
-                viewportSize: self.msaAreaWidth,
-                viewportPos: -self.scrollX,
-                blockSize: self.blockSize,
-                mapSize: self.totalWidth,
-            });
-        },
-        /**
-         * #getter
-         */
-        get blocksY() {
-            return calculateBlocks({
-                viewportSize: this.visibleMsaHeight,
-                viewportPos: -self.scrollY,
-                blockSize: self.blockSize,
-                mapSize: self.totalHeight,
-            });
+        get showMsaLetters() {
+            return (self.drawMsaLetters &&
+                self.rowHeight >= minLetterRowHeight &&
+                self.colWidth >= minLetterColWidth &&
+                self.colWidth > self.rowHeight / 2);
         },
         /**
          * #getter
-         * height of the alignment viewport, px. The same subtraction as
-         * msaAreaHeight, which is defined later in the views chain
          */
-        get visibleMsaHeight() {
-            return (self.height -
-                self.headerHeight -
-                (self.msaAreaWidth < self.totalWidth ? self.minimapHeight : 0));
+        get showTreeText() {
+            return self.drawLabels && self.rowHeight >= minLetterRowHeight;
         },
     }))
         .views(self => ({
         /**
          * #getter
          */
-        get blocks2d() {
-            return self.blocksY.flatMap(by => self.blocksX.map(bx => [bx, by]));
+        get labelWidthMap() {
+            const { showTreeText, leaves } = self;
+            // gated on the renderer's label condition, so hidden labels reserve no
+            // gutter. Measured once at a reference size and scaled by
+            // labelWidthScale: re-measuring per vertical-zoom frame cost ~200ms on a
+            // 50k-leaf tree
+            return showTreeText
+                ? new Map(leaves.map(node => {
+                    const { name } = node.data;
+                    // `||`, matching renderTreeLabels: an empty genome falls back
+                    // to the row name
+                    const displayName = self.rowDataOf(name)?.genome || name;
+                    return [
+                        name,
+                        measureTextCanvas(displayName, labelReferenceFontSize),
+                    ];
+                }))
+                : new Map();
         },
         /**
          * #getter
+         * factor turning a labelWidthMap entry into its width at the current
+         * font size
          */
-        get isLoading() {
-            return self.loadingMSA || self.loadingTree;
+        get labelWidthScale() {
+            return self.fontSize / labelReferenceFontSize;
+        },
+        get labelsWidth() {
+            // a loop, not Math.max(...): spreading passes one argument per leaf,
+            // and the ~125k argument limit throws RangeError on the 230k-tip COVID
+            // tree
+            let max = 0;
+            for (const width of this.labelWidthMap.values()) {
+                if (width > max) {
+                    max = width;
+                }
+            }
+            return max * this.labelWidthScale;
         },
         /**
          * #getter
          */
-        get maxScrollX() {
-            return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0);
+        get secondaryStructureConsensus() {
+            return self.MSA?.secondaryStructureConsensus;
         },
         /**
          * #getter
-         * most-negative allowed scrollY, keeping the last row in view rather than
-         * letting the whole alignment scroll off the top.
          */
-        get maxScrollY() {
-            return Math.min(-self.totalHeight + self.visibleMsaHeight, 0);
+        get seqConsensus() {
+            return self.MSA?.seqConsensus;
         },
         /**
          * #getter
+         * the base pairs of the consensus secondary structure, as arcs, in
+         * visible column space (hidden columns are removed before parsing)
          */
-        get showMsaLetters() {
-            return (self.drawMsaLetters &&
-                self.rowHeight >= minLetterRowHeight &&
-                self.colWidth >= minLetterColWidth &&
-                self.colWidth > self.rowHeight / 2);
+        get secondaryStructureArcs() {
+            const { blanks, hideGapsEffective } = self;
+            const ss = this.secondaryStructureConsensus;
+            if (!ss) {
+                return undefined;
+            }
+            return parseWuss(hideGapsEffective ? skipBlanks(blanks, ss) : ss).map(({ start, end, pseudoknot }) => ({
+                start,
+                end,
+                color: pseudoknot ? PSEUDOKNOT_ARC : HELIX_ARC,
+            }));
         },
         /**
          * #getter
          */
-        get showTreeText() {
-            return self.drawLabels && self.rowHeight >= minLetterRowHeight;
+        get adapterTrackModels() {
+            const { MSA, hideGapsEffective, blanks } = self;
+            const tracks = (MSA?.tracks ?? []).filter(t => !!t.data);
+            if (tracks.length === 0) {
+                // return before reading rowHeight, so zooming does not rebuild the
+                // list and redraw every track canvas
+                return [];
+            }
+            const { rowHeight } = self;
+            return tracks.map(t => ({
+                model: {
+                    ...t,
+                    kind: 'text',
+                    data: hideGapsEffective ? skipBlanks(blanks, t.data) : t.data,
+                    height: rowHeight,
+                },
+                ReactComponent: TrackBlocks,
+            }));
+        },
+        /**
+         * #getter
+         * a data track's values or string, projected from its row's residues
+         * onto alignment columns when it names a row
+         */
+        get columnTrackContent() {
+            const { MSA, blanks, hideGapsEffective } = self;
+            const width = MSA?.getWidth() ?? 0;
+            const project = (track, items, fill) => {
+                if (!track.row) {
+                    return items;
+                }
+                const out = Array.from({ length: width }, () => fill);
+                const index = self.seqPosIndex(track.row);
+                items.forEach((item, seqPos) => {
+                    const col = index?.[seqPos];
+                    if (col !== undefined) {
+                        out[col] = item;
+                    }
+                });
+                return out;
+            };
+            const skip = (items) => hideGapsEffective ? dropBlanks(blanks, items) : items;
+            // an arc endpoint maps row residue -> column -> visible column.
+            // visibleColsBefore, not globalColToVisibleCol, so an endpoint in a
+            // hidden column moves to the neighboring visible one and the arc stays
+            const resolve = (track, pos) => {
+                const col = track.row
+                    ? self.seqPosIndex(track.row)?.[pos - 1]
+                    : pos - 1;
+                if (col === undefined || col < 0 || col >= width) {
+                    return undefined;
+                }
+                return hideGapsEffective ? visibleColsBefore(blanks, col) : col;
+            };
+            return new Map(self.columnTracks.map(track => {
+                if (track.kind === 'arc') {
+                    const arcs = (track.arcs ?? [])
+                        .map(arc => {
+                        const start = resolve(track, Math.min(arc.start, arc.end));
+                        const end = resolve(track, Math.max(arc.start, arc.end));
+                        return start !== undefined && end !== undefined && start < end
+                            ? { start, end, color: arc.color }
+                            : undefined;
+                    })
+                        .filter(notEmpty);
+                    return [track.id, { arcs }];
+                }
+                if (track.kind === 'bar') {
+                    const max = track.max ?? 1;
+                    const values = skip(project(track, track.values ?? [], 0)).map(v => Math.min(1, Math.max(0, v / max)));
+                    return [track.id, { values }];
+                }
+                const data = skip(project(track, (track.data ?? '').split(''), ' '));
+                return [track.id, { data: data.join('') }];
+            }));
+        },
+        /**
+         * #method
+         * the height a track draws at: what the user dragged its divider to,
+         * then the height its snapshot asked for, then its kind's default. Only
+         * a text track falls through to rowHeight, and `??` short-circuits
+         * before reading it, so vertical zoom does not rebuild the other tracks
+         */
+        trackHeight(kind, heightKey = kind, given) {
+            return (self.trackHeights.get(heightKey) ??
+                given ??
+                defaultTrackHeights[kind] ??
+                self.rowHeight);
+        },
+        /**
+         * #getter
+         */
+        get columnTrackModels() {
+            return self.columnTracks.map(track => {
+                const heightKey = resizableKinds.has(track.kind)
+                    ? ownHeightKey(track.id)
+                    : undefined;
+                return {
+                    model: {
+                        id: track.id,
+                        name: track.name,
+                        kind: track.kind,
+                        heightKey,
+                        height: this.trackHeight(track.kind, heightKey, track.height),
+                        barColor: track.color,
+                        arcColor: track.color,
+                        customColorScheme: track.colors,
+                        data: this.columnTrackContent.get(track.id)?.data,
+                        arcs: this.columnTrackContent.get(track.id)?.arcs,
+                    },
+                    ReactComponent: TrackBlocks,
+                };
+            });
+        },
+        /**
+         * #getter
+         * the consensus secondary structure as a track, when there is one. A
+         * separate getter keeps the object stable across zoom, so its canvas
+         * does not redraw
+         */
+        get basePairTrackModels() {
+            const arcs = this.secondaryStructureArcs;
+            return arcs?.length
+                ? [
+                    {
+                        model: {
+                            id: 'base-pairs',
+                            name: 'Base pairs',
+                            kind: 'arc',
+                            heightKey: 'arc',
+                            height: this.trackHeight('arc'),
+                            arcs,
+                        },
+                        ReactComponent: TrackBlocks,
+                    },
+                ]
+                : [];
+        },
+        /**
+         * #getter
+         * the tracks computed from the alignment; they depend on their heights
+         * and the alphabet, not on zoom
+         */
+        get computedTrackModels() {
+            return [
+                {
+                    id: 'conservation',
+                    name: 'Conservation',
+                    kind: 'bar',
+                    barColor: 'gray',
+                },
+                ...(self.sequenceType === 'amino'
+                    ? [
+                        {
+                            id: 'property-conservation',
+                            name: 'Property conservation',
+                            kind: 'bar',
+                            barColor: '#6a51a3',
+                        },
+                    ]
+                    : []),
+                {
+                    id: 'sequence-logo',
+                    name: 'Sequence logo',
+                    kind: 'logo',
+                },
+                // last, so it sits against the alignment it numbers
+                {
+                    id: 'position-ruler',
+                    name: 'Position',
+                    kind: 'ruler',
+                },
+            ].map(model => ({
+                // every computed track of a kind shares that kind's height, so the
+                // kind is its key
+                model: {
+                    ...model,
+                    heightKey: resizableKinds.has(model.kind) ? model.kind : undefined,
+                    height: this.trackHeight(model.kind),
+                },
+                ReactComponent: TrackBlocks,
+            }));
+        },
+        get tracks() {
+            return [
+                ...this.adapterTrackModels,
+                ...this.basePairTrackModels,
+                ...this.columnTrackModels,
+                // every computed track reads the alignment's columns, and a tree, a
+                // GFF and a features panel draw a figure with none
+                ...(self.numColumns > 0 ? this.computedTrackModels : []),
+            ];
+        },
+        /**
+         * #getter
+         */
+        get turnedOnTracks() {
+            return this.tracks.filter(f => !trackIsOff(self.turnedOffTracks, f.model.id, f.model.defaultOff));
+        },
+        /**
+         * #getter
+         */
+        get showHorizontalScrollbar() {
+            return overflows(self.totalWidth, self.msaAreaWidth);
+        },
+        /**
+         * #method
+         * Return a row-specific letter at a visible column, or undefined if gap.
+         *
+         * @param rowName - The name of the row
+         * @param visibleCol - The visible column index (what the user sees on screen)
+         * @returns The letter at that position, or undefined if it's a gap
+         */
+        visibleColToRowLetter(rowName, visibleCol) {
+            return self.rowMap.get(rowName)?.[this.visibleColToGlobalCol(visibleCol)];
+        },
+        /**
+         * #method
+         * Convert a visible column to a row-specific sequence position (0-based).
+         * Returns undefined if the position is a gap in the sequence.
+         *
+         * Public API, like the sibling converters (visibleColToGlobalCol,
+         * seqPosToVisibleCol, globalColToVisibleCol, seqPosToGlobalCol) hosts
+         * use to translate between columns and residue positions. Keep them
+         * stable.
+         *
+         * @param rowName - The name of the row
+         * @param visibleCol - The visible column index
+         * @returns The sequence position (0-based), or undefined if it's a gap
+         */
+        visibleColToSeqPos(rowName, visibleCol) {
+            // binary search: this runs on every mouse move, and scanning a
+            // 30k-column row per event takes the whole frame
+            return seqPosOfGlobalCol(self.seqPosIndex(rowName), this.visibleColToGlobalCol(visibleCol));
+        },
+        /**
+         * #method
+         * Convert a visible column to a row-specific sequence position (1-based).
+         * Returns undefined if the position is a gap in the sequence.
+         *
+         * @param rowName - The name of the row
+         * @param visibleCol - The visible column index
+         * @returns The sequence position (1-based), or undefined if it's a gap
+         */
+        visibleColToSeqPosOneBased(rowName, visibleCol) {
+            const val = this.visibleColToSeqPos(rowName, visibleCol);
+            return val !== undefined ? val + 1 : undefined;
+        },
+        /**
+         * #method
+         * Convert a global column index to a visible column index.
+         * Returns undefined if the column is hidden (in blanks).
+         * This is the inverse of visibleColToGlobalCol.
+         *
+         * @param globalCol - The global column index in the full MSA
+         * @returns The visible column index, or undefined if the column is hidden
+         */
+        globalColToVisibleCol(globalCol) {
+            const { blanks, hideGapsEffective } = self;
+            if (!hideGapsEffective) {
+                return globalCol;
+            }
+            return globalColToVisibleCol(blanks, globalCol);
+        },
+        /**
+         * #method
+         * Convert a visible column index (what a mouse handler reports) to a
+         * column of the full alignment. A host indexing its own per-column data
+         * needs this when columns are hidden.
+         *
+         * @param visibleCol - The visible column index
+         * @returns The global column index in the full MSA
+         */
+        visibleColToGlobalCol(visibleCol) {
+            const { blanks, hideGapsEffective } = self;
+            return hideGapsEffective
+                ? visibleColToGlobalCol(blanks, visibleCol)
+                : visibleCol;
+        },
+        /**
+         * #method
+         * Convert a sequence position (ungapped) to a global column index.
+         * Returns undefined for a row name the alignment does not have.
+         *
+         * @param rowName - The name of the row
+         * @param seqPos - The sequence position (0-based, ungapped)
+         * @returns The global column index in the full MSA, or undefined
+         */
+        seqPosToGlobalCol(rowName, seqPos) {
+            const seq = self.rowMap.get(rowName);
+            if (seq === undefined) {
+                return undefined;
+            }
+            const col = self.seqPosIndex(rowName)?.[seqPos];
+            // past the end of the ungapped sequence: 0 for the degenerate all-gap
+            // row, otherwise one past the last column
+            return col ?? (seqPos === 0 ? 0 : seq.length);
+        },
+        /**
+         * #method
+         * Convert a sequence position (ungapped) directly to a visible column index.
+         * This combines seqPosToGlobalCol and globalColToVisibleCol.
+         *
+         * @param rowName - The name of the row
+         * @param seqPos - The sequence position (0-based, ungapped)
+         * @returns The visible column index, or undefined if the column is hidden
+         */
+        seqPosToVisibleCol(rowName, seqPos) {
+            const globalCol = this.seqPosToGlobalCol(rowName, seqPos);
+            return globalCol === undefined
+                ? undefined
+                : this.globalColToVisibleCol(globalCol);
+        },
+        /**
+         * #method
+         * the visible columns a span covers, in highlight coordinates: `start`
+         * and `end` are 1-based residues of `row`, or columns of the file
+         * without it. A fractional position, as a zoom gesture reports one,
+         * widens to the whole residue or column it falls in. A span entirely on
+         * hidden columns, or naming a row the alignment lacks, gives undefined.
+         */
+        visibleSpan({ row, start: rawStart, end: rawEnd }) {
+            const { blanks } = self;
+            const start = Math.max(1, Math.floor(rawStart));
+            const end = Math.ceil(rawEnd);
+            let startGlobal = start - 1;
+            let endGlobal = end - 1;
+            if (row !== undefined) {
+                const rowStart = this.seqPosToGlobalCol(row, start - 1);
+                const rowEnd = this.seqPosToGlobalCol(row, end - 1);
+                if (rowStart === undefined || rowEnd === undefined) {
+                    return undefined;
+                }
+                startGlobal = rowStart;
+                endGlobal = rowEnd;
+            }
+            const startCol = this.globalColToVisibleCol(startGlobal) ??
+                visibleColsBefore(blanks, startGlobal);
+            const endCol = this.globalColToVisibleCol(endGlobal) ??
+                visibleColsBefore(blanks, endGlobal) - 1;
+            return startCol <= endCol ? { startCol, endCol } : undefined;
+        },
+        /**
+         * #getter
+         * why each ignored residue mapping is ignored, so a host can tell a
+         * missing structure from a mapping made against a different alignment.
+         */
+        get residueMappingProblems() {
+            const problems = [];
+            for (const mapping of self.residueMappings) {
+                const where = { row: mapping.row, structureId: mapping.structure.id };
+                const residues = self.seqPosIndex(mapping.row)?.length;
+                if (residues === undefined) {
+                    problems.push({
+                        ...where,
+                        scope: 'mapping',
+                        reason: 'no such row in the alignment',
+                    });
+                    continue;
+                }
+                if (mapping.rowLength !== undefined &&
+                    mapping.rowLength !== residues) {
+                    problems.push({
+                        ...where,
+                        scope: 'mapping',
+                        reason: `computed against a ${mapping.rowLength}-residue row; this one has ${residues}`,
+                    });
+                    continue;
+                }
+                const overrun = mapping.segments.find(segment => segment.rowEnd > residues || segment.rowStart < 1);
+                if (overrun) {
+                    problems.push({
+                        ...where,
+                        scope: 'mapping',
+                        reason: `segment ${overrun.rowStart}-${overrun.rowEnd} does not fit a ${residues}-residue row`,
+                    });
+                    continue;
+                }
+                for (const segment of mapping.segments) {
+                    if (!sameLength(segment)) {
+                        problems.push({
+                            ...where,
+                            scope: 'segment',
+                            reason: `segment ${segment.rowStart}-${segment.rowEnd} maps to ${segment.structStart}-${segment.structEnd}, which is a different length`,
+                        });
+                    }
+                }
+            }
+            return problems;
+        },
+        /**
+         * #getter
+         * the mappings that fit the loaded alignment. A row-level problem drops
+         * the whole mapping; a malformed segment drops only that segment.
+         */
+        get usableResidueMappings() {
+            const unusable = new Set(this.residueMappingProblems
+                .filter(problem => problem.scope === 'mapping')
+                .map(problem => `${problem.row}\u0000${problem.structureId}`));
+            return self.residueMappings
+                .filter(m => !unusable.has(`${m.row}\u0000${m.structure.id}`))
+                .map(m => ({
+                ...m,
+                segments: m.segments.filter(sameLength),
+            }));
+        },
+        /**
+         * #getter
+         * the structures with usable mappings. A row can map onto several, such
+         * as an experimental entry and a predicted model.
+         */
+        get mappedStructures() {
+            return this.usableResidueMappings.map(m => ({
+                row: m.row,
+                structure: m.structure,
+            }));
+        },
+        /**
+         * #method
+         * The structure residue for a row residue. Returns undefined when no
+         * segment covers `seqPos`, or when the row maps onto several structures
+         * and `structureId` does not pick one (see `mappedStructures`).
+         *
+         * Positions are 1-based, like `residueMappings` and `highlights`; the
+         * column helpers above are 0-based.
+         *
+         * @param rowName - The alignment row
+         * @param seqPos - Residue of that row, 1-based
+         * @param structureId - Which structure, when the row maps onto several
+         */
+        structureResidue(rowName, seqPos, structureId) {
+            const hits = [];
+            for (const mapping of this.usableResidueMappings) {
+                if (mapping.row !== rowName) {
+                    continue;
+                }
+                if (structureId !== undefined &&
+                    mapping.structure.id !== structureId) {
+                    continue;
+                }
+                const segment = mapping.segments.find(seg => seqPos >= seg.rowStart && seqPos <= seg.rowEnd);
+                if (segment) {
+                    const position = segment.structStart + (seqPos - segment.rowStart);
+                    hits.push({
+                        structure: mapping.structure,
+                        position,
+                        observed: !inRanges(mapping.unobserved, position),
+                    });
+                }
+            }
+            return hits.length === 1 ? hits[0] : undefined;
+        },
+        /**
+         * #method
+         * The row residue for a structure residue; the inverse of
+         * `structureResidue`, returning undefined in the same cases. `asymId`
+         * picks a chain when several mappings share an entry id, as in a
+         * homodimer.
+         *
+         * @param structureId - The structure's id, as the mapping names it
+         * @param position - Residue of that structure, 1-based label_seq_id
+         * @param asymId - Which chain, when the id alone is ambiguous
+         */
+        rowResidue(structureId, position, asymId) {
+            const hits = [];
+            for (const mapping of this.usableResidueMappings) {
+                if (mapping.structure.id !== structureId) {
+                    continue;
+                }
+                if (asymId !== undefined && mapping.structure.asymId !== asymId) {
+                    continue;
+                }
+                const segment = mapping.segments.find(seg => position >= seg.structStart && position <= seg.structEnd);
+                if (segment) {
+                    hits.push({
+                        rowName: mapping.row,
+                        seqPos: segment.rowStart + (position - segment.structStart),
+                    });
+                }
+            }
+            return hits.length === 1 ? hits[0] : undefined;
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * the branch-length scale bar over the tree, undefined in cladogram mode
+         * or when the tree area is too narrow for one
+         */
+        get treeScaleBar() {
+            return scaleBarLength(self.pxPerBranchLength, self.treeAreaWidth - self.marginLeft * 2);
+        },
+        /**
+         * #getter
+         * the band across the top: the minimap over the alignment, the row panel
+         * headers, and the tree overview stacked on the scale bar, as tall as the
+         * tallest of the three
+         */
+        get topBandHeight() {
+            return Math.max(self.showHorizontalScrollbar ? self.minimapHeight : 0, self.rowPanelsHeaderHeight, self.treeOverviewHeight +
+                (this.treeScaleBar ? treeScaleBarHeight : 0));
+        },
+        /**
+         * #getter
+         * the vertical space for alignment rows: the widget height less the
+         * header, the top band and the tracks. Shared by blocksY, maxScrollY, the
+         * vertical scrollbar and fitVertically.
+         */
+        get msaAreaHeight() {
+            return (self.height -
+                this.topBandHeight -
+                self.headerHeight -
+                this.totalTrackAreaHeight);
+        },
+        /**
+         * #getter
+         * total height of track area (px)
+         */
+        get totalTrackAreaHeight() {
+            return sum(self.turnedOnTracks.map(r => r.model.height));
+        },
+        /**
+         * one representative annotation per accession, for the legend, the
+         * filter dialog and the palettes
+         */
+        get annotationTypes() {
+            // first occurrence wins; only name, description and segment start are
+            // read from it
+            const types = new Map();
+            for (const annot of self.annotations) {
+                if (!types.has(annot.accession)) {
+                    types.set(annot.accession, annot);
+                }
+            }
+            return types;
+        },
+        get filteredAnnotations() {
+            return self.annotations.filter(r => !self.turnedOffFeatures.get(r.accession));
+        },
+        get annotationsByRow() {
+            return groupBy(this.filteredAnnotations, r => r.id);
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         */
+        get showVerticalScrollbar() {
+            return overflows(self.totalHeight, self.msaAreaHeight);
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         */
+        get dataInitialized() {
+            // truthiness, not `!== ''`: DataModel drops an inline document over
+            // 50kb from the snapshot, so a restored session can hold `undefined`
+            return !!(self.data.msa || self.data.tree) && !self.error;
+        },
+        /**
+         * #getter
+         */
+        get blocksX() {
+            return calculateBlocks({
+                viewportSize: self.msaAreaWidth,
+                viewportPos: -self.scrollX,
+                blockSize: self.blockSize,
+                mapSize: self.totalWidth,
+            });
+        },
+        /**
+         * #getter
+         */
+        get blocksY() {
+            return calculateBlocks({
+                viewportSize: self.msaAreaHeight,
+                viewportPos: -self.scrollY,
+                blockSize: self.blockSize,
+                mapSize: self.totalHeight,
+            });
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         */
+        get blocks2d() {
+            return self.blocksY.flatMap(by => self.blocksX.map(bx => [bx, by]));
+        },
+        /**
+         * #getter
+         */
+        get isLoading() {
+            return self.loadingMSA || self.loadingTree;
+        },
+        /**
+         * #getter
+         */
+        get maxScrollX() {
+            return Math.min(-self.totalWidth + (self.msaAreaWidth - 100), 0);
+        },
+        /**
+         * #getter
+         * most-negative allowed scrollY, which keeps the last row in view
+         */
+        get maxScrollY() {
+            return Math.min(-self.totalHeight + self.msaAreaHeight, 0);
+        },
+        /**
+         * #getter
+         * axis a wheel zoom scales, for ctrl+wheel as much as for scroll-zoom.
+         * With scroll-zoom off the toolbar shows no axis, so ctrl+wheel takes
+         * both.
+         */
+        get wheelZoomAxis() {
+            return self.scrollZoom ? self.scrollZoomAxis : 'both';
         },
     }))
         .actions(self => ({
@@ -1173,15 +2438,19 @@ function stateModelFactory() {
         setScrollZoom(arg) {
             self.scrollZoom = arg;
         },
+        /**
+         * #action
+         */
+        setScrollZoomAxis(arg) {
+            self.scrollZoomAxis = arg;
+        },
         /**
          * #action
          * set hovered tree node and its descendants
          */
         setHoveredTreeNode(nodeId) {
-            // the tree's mousemove handler calls this on every event, and both the
-            // lookup and the write are expensive: `find` walks the whole hierarchy,
-            // and a fresh object here invalidates hoveredRowIndices and redraws the
-            // tree and MSA overlays. Re-hovering the same node is the common case
+            // called on every tree mousemove; `find` walks the whole hierarchy and a
+            // new object redraws the tree and MSA overlays
             if (nodeId === self.hoveredTreeNode?.nodeId) {
                 return;
             }
@@ -1199,14 +2468,34 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * Calculate a neighbor joining tree from the current MSA using BLOSUM62 distances
+         * Calculate a neighbor joining tree from the current MSA using BLOSUM62
+         * distances. Throws above `maxNeighborJoiningRows`: the join loop is
+         * cubic and runs on the main thread, and 800 rows freeze the tab for ten
+         * seconds with no cancel.
          */
         calculateNeighborJoiningTreeFromMSA() {
-            if (self.rows.length < 2) {
+            // every sequence, including rows in collapsed clades
+            const rows = [...self.rowMap];
+            if (rows.length < 2) {
                 throw new Error('Need at least 2 sequences to build a tree');
             }
-            const newickTree = calculateNeighborJoiningTree(self.rows);
-            self.setTree(newickTree);
+            if (rows.length > maxNeighborJoiningRows) {
+                throw new Error(`Neighbor joining here is capped at ${maxNeighborJoiningRows} sequences and this alignment has ${rows.length}. Build the tree with FastTree or IQ-TREE and open it alongside the alignment: https://gmod.org/JBrowseMSA/tutorials/protein_family`);
+            }
+            this.replaceTree(calculateNeighborJoiningTree(rows));
+        },
+        /**
+         * #action
+         * swap in a different tree over the same alignment. Clears `collapsed`
+         * and `showOnly`, since path-derived node ids (node-0-0-1) from the old
+         * tree would match unrelated nodes in the new one.
+         */
+        replaceTree(newick) {
+            transaction(() => {
+                self.collapsed.clear();
+                self.setShowOnly(undefined);
+                self.setTree(newick);
+            });
         },
         /**
          * #action
@@ -1264,23 +2553,26 @@ function stateModelFactory() {
          * #action
          * Smoothly zoom by a continuous scaleFactor. The column under the cursor
          * (offsetX/offsetY, px relative to the MSA area) stays anchored
-         * horizontally. Vertically the anchor is biased toward the top: when the
-         * alignment nearly fits the viewport, snap to y=0 rather than pinning a
-         * random row under the cursor, with the bias fading out as the alignment
-         * grows taller than the viewport (where cursor-anchoring is useful).
-         * Drives wheel/trackpad-pinch zoom.
-         */
-        zoomToPos(scaleFactor, offsetX, offsetY) {
+         * horizontally. Vertically the anchor is biased toward y=0 when the
+         * alignment nearly fits the viewport, fading to cursor-anchoring as the
+         * alignment grows taller than the viewport.
+         * Drives wheel/trackpad-pinch zoom. `axis` holds one cell dimension
+         * fixed; the held axis still re-anchors its scroll offset, since the
+         * other one can change how much of the alignment fits.
+         */
+        zoomToPos(scaleFactor, offsetX, offsetY, axis = 'both') {
             transaction(() => {
                 const colInView = (-self.scrollX + offsetX) / self.colWidth;
                 const rowInView = (-self.scrollY + offsetY) / self.rowHeight;
-                self.colWidth = clamp(self.colWidth * scaleFactor, minColWidth, maxCellSize);
-                self.rowHeight = clamp(self.rowHeight * scaleFactor, minRowHeight, maxCellSize);
+                if (axis !== 'vertical') {
+                    self.colWidth = clamp(self.colWidth * scaleFactor, minColWidth, maxCellSize);
+                }
+                if (axis !== 'horizontal') {
+                    self.rowHeight = clamp(self.rowHeight * scaleFactor, minRowHeight, maxCellSize);
+                }
                 self.scrollX = clamp(offsetX - colInView * self.colWidth, self.maxScrollX, 0);
                 const anchoredScrollY = offsetY - rowInView * self.rowHeight;
-                // maxScrollY is -(totalHeight - visibleMsaHeight) when the alignment
-                // overflows, so -maxScrollY is exactly that overflow past the
-                // scrollable MSA viewport (0 when it fits)
+                // -maxScrollY is the overflow past the viewport, 0 when it fits
                 const overflow = Math.max(0, -self.maxScrollY);
                 const visibleHeight = self.totalHeight - overflow;
                 const topBias = visibleHeight > 0 ? clamp(1 - overflow / visibleHeight, 0, 1) : 1;
@@ -1302,13 +2594,14 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * Set the overlay annotations and reveal the overlay in a single step (an
-         * empty list clears both). Every source funnels through here after its
-         * own adapter has flattened it: InterProScan, GFF, user uploads, NCBI CDD.
+         * Set the overlay annotations (an empty list clears them). InterProScan,
+         * GFF, user uploads and NCBI CDD all arrive here as Annotation[].
+         *
+         * Leaves `showDomains` alone, because a restored snapshot reloads its
+         * GFF and must keep a hidden overlay hidden.
          */
         setAnnotations(annotations) {
             self.annotations = annotations;
-            self.setShowDomains(annotations.length > 0);
         },
         /**
          * #action
@@ -1322,382 +2615,147 @@ function stateModelFactory() {
         applyGFFText(gffText) {
             this.setAnnotations(gffToAnnotations(parseGFF(gffText)));
         },
-        /**
-         * #action
-         */
-        doScrollX(deltaX) {
-            this.setScrollX(self.scrollX + deltaX);
-        },
-        /**
-         * #action
-         */
-        setScrollX(n) {
-            self.scrollX = clamp(n, self.maxScrollX, 0);
-        },
-        /**
-         * #action
-         */
-        setColumnTracks(tracks) {
-            self.columnTracks.replace(tracks);
-        },
-        /**
-         * #action
-         */
-        toggleTrack(id) {
-            // the stored value is "is off", so the current shown state is exactly
-            // what the flipped entry should hold
-            self.turnedOffTracks.set(id, !trackIsOff(self.turnedOffTracks, id));
-        },
-        /**
-         * #action
-         */
-        setStatus(status) {
-            self.status = status;
-        },
-    }))
-        .views(self => ({
-        /**
-         * #getter
-         */
-        get labelWidthMap() {
-            const { showTreeText, leaves, treeMetadata } = self;
-            // gated on the same condition the renderer draws labels under, so the
-            // gutter labelsWidth reserves and the labels actually drawn cannot
-            // disagree -- and so turning labels off hands their space to the tree.
-            // Measured at a fixed reference size and scaled by labelWidthScale:
-            // re-measuring every leaf on every vertical-zoom frame cost ~200ms on a
-            // 50k-leaf tree
-            return showTreeText
-                ? new Map(leaves.map(node => {
-                    const { name } = node.data;
-                    // `||`, matching renderTreeLabels: an empty genome falls back
-                    // to the row name, and measuring '' would size the gutter (and
-                    // the label's click target) to nothing
-                    const displayName = treeMetadata[name]?.genome || name;
-                    return [
-                        name,
-                        measureTextCanvas(displayName, labelReferenceFontSize),
-                    ];
-                }))
-                : new Map();
-        },
-        /**
-         * #getter
-         * factor turning a labelWidthMap entry into its width at the current
-         * font size
-         */
-        get labelWidthScale() {
-            return self.fontSize / labelReferenceFontSize;
-        },
-        get labelsWidth() {
-            // a loop, not Math.max(...widths.values()): spreading a map of every
-            // leaf passes one argument per row, and the argument limit is somewhere
-            // around 125k -- so the bundled 230k-tip COVID tree threw
-            // "RangeError: Maximum call stack size exceeded" out of a getter the
-            // treeWidth autorun reads on load
-            let max = 0;
-            for (const width of this.labelWidthMap.values()) {
-                if (width > max) {
-                    max = width;
-                }
-            }
-            return max * this.labelWidthScale;
-        },
-        /**
-         * #getter
-         */
-        get secondaryStructureConsensus() {
-            return self.MSA?.secondaryStructureConsensus;
-        },
-        /**
-         * #getter
-         */
-        get seqConsensus() {
-            return self.MSA?.seqConsensus;
-        },
-        /**
-         * #getter
-         */
-        get adapterTrackModels() {
-            const { rowHeight, MSA, hideGapsEffective, blanks } = self;
-            const tracks = MSA?.tracks ?? [];
-            return tracks
-                .filter(t => !!t.data)
-                .map(t => ({
-                model: {
-                    ...t,
-                    kind: 'text',
-                    data: hideGapsEffective ? skipBlanks(blanks, t.data) : t.data,
-                    height: rowHeight,
-                },
-                ReactComponent: TrackBlocks,
-            }));
-        },
-        /**
-         * #getter
-         * a data track's values or string, projected from its row's residues
-         * onto alignment columns when it names a row
-         */
-        get columnTrackContent() {
-            const { MSA, blanks, hideGapsEffective } = self;
-            const width = MSA?.getWidth() ?? 0;
-            const project = (track, items, fill) => {
-                if (!track.row) {
-                    return items;
-                }
-                const out = Array.from({ length: width }, () => fill);
-                const index = self.seqPosGlobalColIndex.get(track.row);
-                items.forEach((item, seqPos) => {
-                    const col = index?.[seqPos];
-                    if (col !== undefined) {
-                        out[col] = item;
-                    }
-                });
-                return out;
-            };
-            const skip = (items) => hideGapsEffective ? dropBlanks(blanks, items) : items;
-            return new Map(self.columnTracks.map(track => {
-                if (track.kind === 'bar') {
-                    const max = track.max ?? 1;
-                    const values = skip(project(track, track.values ?? [], 0)).map(v => Math.min(1, Math.max(0, v / max)));
-                    return [track.id, { values }];
-                }
-                const data = skip(project(track, (track.data ?? '').split(''), ' '));
-                return [track.id, { data: data.join('') }];
-            }));
-        },
-        /**
-         * #getter
-         */
-        get columnTrackModels() {
-            return self.columnTracks.map(track => ({
-                model: {
-                    id: track.id,
-                    name: track.name,
-                    kind: track.kind,
-                    height: track.height ??
-                        (track.kind === 'bar'
-                            ? self.conservationTrackHeight
-                            : self.rowHeight),
-                    barColor: track.color,
-                    customColorScheme: track.colors,
-                    data: this.columnTrackContent.get(track.id)?.data,
-                },
-                ReactComponent: TrackBlocks,
-            }));
-        },
-        /**
-         * #getter
-         */
-        get tracks() {
-            const conservationTrack = {
-                id: 'conservation',
-                name: 'Conservation',
-                kind: 'bar',
-                height: self.conservationTrackHeight,
-                barColor: 'gray',
-            };
-            const propertyConservationTrack = {
-                id: 'property-conservation',
-                name: 'Property conservation',
-                kind: 'bar',
-                height: self.conservationTrackHeight,
-                barColor: '#6a51a3',
-            };
-            const sequenceLogoTrack = {
-                id: 'sequence-logo',
-                name: 'Sequence logo',
-                kind: 'logo',
-                height: self.sequenceLogoTrackHeight,
-            };
-            return [
-                ...this.adapterTrackModels,
-                ...this.columnTrackModels,
-                ...[
-                    conservationTrack,
-                    ...(self.sequenceType === 'amino'
-                        ? [propertyConservationTrack]
-                        : []),
-                    sequenceLogoTrack,
-                ].map(model => ({ model, ReactComponent: TrackBlocks })),
-            ];
+        /**
+         * #action
+         */
+        doScrollX(deltaX) {
+            this.setScrollX(self.scrollX + deltaX);
         },
         /**
-         * #getter
+         * #action
          */
-        get turnedOnTracks() {
-            return this.tracks.filter(f => !trackIsOff(self.turnedOffTracks, f.model.id));
+        setScrollX(n) {
+            self.scrollX = clamp(n, self.maxScrollX, 0);
         },
         /**
-         * #getter
+         * #action
          */
-        get showHorizontalScrollbar() {
-            return self.msaAreaWidth < self.totalWidth;
+        setColumnTracks(tracks) {
+            self.columnTracks.replace(tracks);
         },
         /**
-         * #method
-         * Return a row-specific letter at a visible column, or undefined if gap.
-         *
-         * @param rowName - The name of the row
-         * @param visibleCol - The visible column index (what the user sees on screen)
-         * @returns The letter at that position, or undefined if it's a gap
+         * #action
+         * replace the row table, which the model keeps as the JSON string
+         * `data.treeMetadata` (see docs/layers.md)
          */
-        visibleColToRowLetter(rowName, visibleCol) {
-            const { rowMap, blanks } = self;
-            return rowMap.get(rowName)?.[visibleColToGlobalCol(blanks, visibleCol)];
+        setRowData(rowData) {
+            self.data.setTreeMetadata(JSON.stringify(rowData));
         },
         /**
-         * #method
-         * Convert a visible column to a row-specific sequence position (0-based).
-         * Returns undefined if the position is a gap in the sequence.
-         *
-         * CROSS-REPO CONTRACT: this and the sibling coordinate converters
-         * (seqPosToVisibleCol, globalColToVisibleCol, seqPosToGlobalCol) are used
-         * by jbrowse-plugin-protein3d to translate between alignment columns and
-         * structure/sequence residue positions across gaps. Keep them stable.
-         *
-         * @param rowName - The name of the row
-         * @param visibleCol - The visible column index
-         * @returns The sequence position (0-based), or undefined if it's a gap
+         * #action
+         * replace what the viewer's marks read from the row table
          */
-        visibleColToSeqPos(rowName, visibleCol) {
-            return visibleColToSeqPosForRow({
-                rowName,
-                visibleCol,
-                rowMap: self.rowMap,
-                blanks: self.blanks,
-            });
+        setEncodings(encodings) {
+            self.encodings.replace(encodings);
         },
         /**
-         * #method
-         * Convert a visible column to a row-specific sequence position (1-based).
-         * Returns undefined if the position is a gap in the sequence.
-         *
-         * @param rowName - The name of the row
-         * @param visibleCol - The visible column index
-         * @returns The sequence position (1-based), or undefined if it's a gap
+         * #action
+         * replace the panels drawn between the tree and the alignment
          */
-        visibleColToSeqPosOneBased(rowName, visibleCol) {
-            const val = this.visibleColToSeqPos(rowName, visibleCol);
-            return val !== undefined ? val + 1 : undefined;
+        setRowPanels(panels) {
+            self.rowPanels.replace(panels);
         },
         /**
-         * #method
-         * Convert a global column index to a visible column index.
-         * Returns undefined if the column is hidden (in blanks).
-         * This is the inverse of visibleColToGlobalCol.
-         *
-         * @param globalCol - The global column index in the full MSA
-         * @returns The visible column index, or undefined if the column is hidden
+         * #action
+         * replace the alignment<->structure correspondence (see docs/layers.md)
          */
-        globalColToVisibleCol(globalCol) {
-            const { blanks, hideGapsEffective } = self;
-            if (!hideGapsEffective) {
-                return globalCol;
-            }
-            return globalColToVisibleCol(blanks, globalCol);
+        setResidueMappings(mappings) {
+            self.residueMappings.replace(mappings);
         },
         /**
-         * #method
-         * Convert a sequence position (ungapped) to a global column index.
-         *
-         * @param rowName - The name of the row
-         * @param seqPos - The sequence position (0-based, ungapped)
-         * @returns The global column index in the full MSA
+         * #action
          */
-        seqPosToGlobalCol(rowName, seqPos) {
-            const seq = self.rowMap.get(rowName);
-            if (seq === undefined) {
-                return 0;
-            }
-            const col = self.seqPosGlobalColIndex.get(rowName)?.[seqPos];
-            // past the end of the ungapped sequence: 0 for the degenerate all-gap
-            // row, otherwise one past the last column
-            return col ?? (seqPos === 0 ? 0 : seq.length);
+        toggleTrack(id) {
+            const defaultOff = self.MSA?.tracks.find(t => t.id === id)?.defaultOff;
+            self.turnedOffTracks.set(id, !trackIsOff(self.turnedOffTracks, id, defaultOff));
         },
         /**
-         * #method
-         * Convert a sequence position (ungapped) directly to a visible column index.
-         * This combines seqPosToGlobalCol and globalColToVisibleCol.
-         *
-         * @param rowName - The name of the row
-         * @param seqPos - The sequence position (0-based, ungapped)
-         * @returns The visible column index, or undefined if the column is hidden
+         * #action
          */
-        seqPosToVisibleCol(rowName, seqPos) {
-            const globalCol = this.seqPosToGlobalCol(rowName, seqPos);
-            return this.globalColToVisibleCol(globalCol);
+        setStatus(status) {
+            self.status = status;
         },
     }))
         .views(self => ({
         /**
          * #getter
-         * widget width minus the tree area gives the space for the MSA
          */
-        get msaAreaHeight() {
-            return (self.height -
-                (self.showHorizontalScrollbar ? self.minimapHeight : 0) -
-                self.headerHeight);
+        get verticalScrollbarWidth() {
+            return self.showVerticalScrollbar ? 20 : 0;
         },
         /**
          * #getter
-         * total height of track area (px)
+         * 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 totalTrackAreaHeight() {
-            return sum(self.turnedOnTracks.map(r => r.model.height));
+        get msaCanvasWidth() {
+            return self.msaAreaWidth - this.verticalScrollbarWidth;
         },
         /**
-         * one representative annotation per accession, which is what the legend,
-         * the filter dialog and the palettes key off
-         */
-        get annotationTypes() {
-            // first occurrence wins. The representative supplies only the name,
-            // description and -- for ordinal segments -- the start that orders
-            // them, and those agree across an accession's instances
-            const types = new Map();
-            for (const annot of self.annotations) {
-                if (!types.has(annot.accession)) {
-                    types.set(annot.accession, annot);
-                }
-            }
-            return types;
-        },
-        get filteredAnnotations() {
-            return self.annotations.filter(r => self.featureFilters.get(r.accession));
-        },
-        get annotationsByRow() {
-            return groupBy(this.filteredAnnotations, r => r.id);
+         * #method
+         * the cell at a visible column and row index, in the coordinates a host
+         * writes highlights in
+         */
+        cellAt(visibleCol, rowIndex) {
+            const column = self.visibleColToGlobalCol(visibleCol);
+            const row = rowIndex === undefined ? undefined : self.leaves[rowIndex]?.data.name;
+            return row === undefined
+                ? { column: column + 1 }
+                : {
+                    column: column + 1,
+                    row,
+                    residue: self.visibleColToSeqPosOneBased(row, visibleCol),
+                    letter: self.rowMap.get(row)?.[column],
+                };
         },
-    }))
-        .views(self => ({
         /**
          * #getter
+         * the cell under the pointer. Public API: MSAViewer's onCellHover
+         * reports it.
          */
-        get showVerticalScrollbar() {
-            return self.msaAreaHeight < self.totalHeight;
+        get hoveredCell() {
+            const { mouseCol, mouseRow } = self;
+            return mouseCol === undefined
+                ? undefined
+                : this.cellAt(mouseCol, mouseRow);
         },
-    }))
-        .views(self => ({
         /**
          * #getter
+         * the cell a click pinned. Public API: MSAViewer's onCellClick reports it.
          */
-        get verticalScrollbarWidth() {
-            return self.showVerticalScrollbar ? 20 : 0;
+        get clickedCell() {
+            const { mouseClickCol, mouseClickRow } = self;
+            return mouseClickCol === undefined
+                ? undefined
+                : this.cellAt(mouseClickCol, mouseClickRow);
         },
         /**
          * #getter
-         * width of the alignment canvas itself: the msa area less the vertical
-         * scrollbar sitting in it. Not usable from showHorizontalScrollbar, which
-         * feeds msaAreaHeight -> showVerticalScrollbar and would close a cycle
+         * the columns on screen. Public API: MSAViewer's onViewportChange reports
+         * it.
          */
-        get msaCanvasWidth() {
-            return self.msaAreaWidth - this.verticalScrollbarWidth;
+        get viewport() {
+            const { scrollX, colWidth, numColumns, viewInitialized } = self;
+            if (numColumns === 0 || !viewInitialized) {
+                return undefined;
+            }
+            const { xStart, xEnd } = visibleColRange({
+                offsetX: -scrollX,
+                blockWidth: this.msaCanvasWidth,
+                colWidth,
+            });
+            const last = Math.max(0, Math.min(xEnd, numColumns) - 1);
+            return {
+                startColumn: self.visibleColToGlobalCol(Math.min(xStart, last)) + 1,
+                endColumn: self.visibleColToGlobalCol(last) + 1,
+            };
         },
         /**
          * #getter
          * ordinal segment types (exons etc.), ordered by sequence position so
-         * exon-1..exon-14 read left-to-right; colored by alternating shade and
-         * labeled by number rather than each getting a distinct hue + legend row
+         * exon-1..exon-14 run left-to-right; colored by alternating shade and
+         * labeled by number, with no legend row
          */
         get segmentDomainTypes() {
             return [...self.annotationTypes.values()]
@@ -1723,9 +2781,38 @@ function stateModelFactory() {
         get strokePalette() {
             return transform(this.fillPalette, ([key, val]) => [
                 key,
-                colord(val).darken(0.1).toHex(),
+                outlineColor(val),
             ]);
         },
+        /**
+         * #getter
+         * the encoding coloring the overlay's spans, undefined when none does,
+         * which leaves each span the color its accession takes in `fillPalette`
+         */
+        get featureFillEncoding() {
+            return this.resolvedEncodings.find(e => e.channel === 'featureFill');
+        },
+        /**
+         * #getter
+         * the fill and outline of every feature's span: its own GFF `color=`
+         * first, then the `featureFill` scale, then the accession palette.
+         * Computed once per change of the features, the encodings or the palette
+         */
+        get featureColors() {
+            return featureColorMap(self.filteredAnnotations, this.featureFillEncoding, this.fillPalette);
+        },
+        /**
+         * #getter
+         * the text the `featureLabel` channel draws inside each span, undefined
+         * when no encoding names the channel. A data channel, so it draws
+         * whether or not the residue letters do
+         */
+        get featureLabels() {
+            const encoding = this.resolvedEncodings.find(e => e.channel === 'featureLabel');
+            return encoding
+                ? featureLabelMap(self.filteredAnnotations, encoding.field)
+                : undefined;
+        },
         /**
          * #getter
          * accession -> number drawn on each segment band: the trailing number of
@@ -1740,24 +2827,92 @@ function stateModelFactory() {
         /**
          * #getter
          * the domain types currently drawn on the alignment (filtered-on), shared
-         * by the on-screen legend and the SVG export legend. Ordinal segments
-         * (exons) are excluded — they read as a numbered gene model, not a color
-         * key — so this is the categorical types ordered by sequence position
+         * by the on-screen legend and the SVG export legend: the categorical types
+         * ordered by sequence position. Ordinal segments (exons) are numbered on
+         * the band instead
          */
         get visibleDomainTypes() {
             return this.categoricalDomainTypes
-                .filter(d => self.featureFilters.get(d.accession))
+                .filter(d => !self.turnedOffFeatures.get(d.accession))
                 .toSorted((a, b) => a.start - b.start);
         },
+        /**
+         * #getter
+         * the categorical color keys drawn for this view, shared by the on-screen
+         * legend overlay and the SVG export's reserved column. The domain overlay
+         * produces the first, listing the `featureFill` scale where an encoding
+         * names one. Every field a row-table encoding or a row panel reads
+         * produces one more, so two channels over one field, or two strips over
+         * it, list that field once. A strip's `legend` names the title it lists
+         * under, so strips over eight fields with one set of colors list one
+         * legend between them
+         */
+        get legends() {
+            const { featureFillEncoding, fillPalette, visibleDomainTypes } = this;
+            const byKey = new Map();
+            // the accession palette keys on no field, so it takes a key of its own
+            const add = (field, entries, id) => {
+                if (entries.length === 0) {
+                    return;
+                }
+                const key = field === undefined ? 'domains' : `field:${field}`;
+                const legend = byKey.get(key);
+                if (legend) {
+                    const seen = new Set(legend.entries.map(e => e.id));
+                    legend.entries.push(...entries.filter(e => !seen.has(e.id)));
+                }
+                else {
+                    byKey.set(key, {
+                        id: id ?? (field === undefined ? 'domains' : `rowData-${field}`),
+                        title: field ?? 'Domains',
+                        entries: [...entries],
+                    });
+                }
+            };
+            // the overlay draws the domain key; with no columns it draws nothing,
+            // and a features panel taking the same colors lists them instead
+            if (self.actuallyShowDomains && self.numColumns > 0) {
+                add(featureFillEncoding?.field, featureFillEncoding
+                    ? featureFillEncoding.legend
+                    : visibleDomainTypes.map(d => ({
+                        id: d.accession,
+                        label: d.name,
+                        color: fillPalette[d.accession],
+                    })), 'domains');
+            }
+            for (const { channel, field, legend } of this.resolvedEncodings) {
+                if (!featureChannels.has(channel)) {
+                    add(field, legend);
+                }
+            }
+            for (const { legendTitle, legend } of this.resolvedRowPanels) {
+                add(legendTitle, legend);
+            }
+            return [...byKey.values()];
+        },
+        /**
+         * #getter
+         * whether the overlay marks each domain with a bar under its row instead
+         * of filling the row behind the letters. Letter-color mode hands the
+         * background to the color scheme, so a filled box would paint over it and
+         * leave the setting with nothing to show. Sub-row layout already stacks
+         * the boxes clear of the letters, and with the letters too small to draw
+         * the filled box is the only thing left to read.
+         */
+        get domainUnderline() {
+            return (self.actuallyShowDomains &&
+                !self.bgColor &&
+                !self.subFeatureRows &&
+                self.showMsaLetters);
+        },
         /**
          * #getter
          * every filtered-on annotation resolved to the visible column span it is
          * drawn across, keyed by row name. Each row is ordered longest-first so a
-         * short domain nested inside a long one draws on top of it rather than
-         * under it. Resolving these once here rather than inside each canvas
-         * block removes a per-feature, per-block sequence position conversion
-         * from every redraw, and gives the letter renderer the band colors it
-         * needs to keep residues readable on top of the boxes.
+         * nested short domain draws on top, and each band carries the lane the
+         * sub-row layout puts it in. Resolved once here instead of per canvas
+         * block per redraw; the letter renderer also reads the band colors to
+         * pick legible letter colors.
          */
         get domainBands() {
             const { blanks } = self;
@@ -1766,26 +2921,27 @@ function stateModelFactory() {
                 const rowBands = annotations
                     .toSorted((a, b) => len(b) - len(a))
                     .map(annotation => {
-                    // annotation positions are 1-based and inclusive. Both ends count
-                    // the visible columns in front of a global column, so endCol is
-                    // the exclusive column after the last residue's own column --
-                    // the band stops there rather than stretching across a following
-                    // gap run -- and a residue whose column is itself hidden
-                    // collapses onto the neighbouring boundary instead of dropping
-                    // the band. A band whose every column is hidden spans nothing
-                    // and is left out.
-                    const startCol = visibleColsBefore(blanks, self.seqPosToGlobalCol(name, annotation.start - 1));
-                    const endCol = visibleColsBefore(blanks, self.seqPosToGlobalCol(name, annotation.end - 1) + 1);
+                    // annotation positions are 1-based and inclusive. endCol is
+                    // exclusive, one past the last residue's column, so the band does
+                    // not extend over a following gap run. An endpoint in a hidden
+                    // column moves to the neighboring boundary. Bands with no visible
+                    // columns, or naming a missing row, are dropped.
+                    const start = self.seqPosToGlobalCol(name, annotation.start - 1);
+                    const end = self.seqPosToGlobalCol(name, annotation.end - 1);
+                    if (start === undefined || end === undefined) {
+                        return undefined;
+                    }
+                    const startCol = visibleColsBefore(blanks, start);
+                    const endCol = visibleColsBefore(blanks, end + 1);
                     return endCol > startCol
                         ? { annotation, startCol, endCol }
                         : undefined;
                 })
                     .filter(notEmpty)
-                    // numbered after the drop, so a band that resolved to nothing does
-                    // not leave an empty sub-row behind it
+                    // numbered after filtering, so a dropped band leaves no gap
                     .map((band, stackIndex) => ({ ...band, stackIndex }));
                 if (rowBands.length > 0) {
-                    bands.set(name, rowBands);
+                    bands.set(name, packDomainLanes(rowBands));
                 }
             }
             return bands;
@@ -1809,11 +2965,13 @@ function stateModelFactory() {
         get mouseOverDomains() {
             const { mouseCol } = self;
             const name = self.mouseOverRowName;
-            return name !== undefined && mouseCol !== undefined
-                ? (this.domainBands.get(name) ?? [])
-                    .filter(b => mouseCol >= b.startCol && mouseCol < b.endCol)
-                    .map(b => b.annotation)
-                : [];
+            if (name === undefined || mouseCol === undefined) {
+                return noDomains;
+            }
+            const hits = (this.domainBands.get(name) ?? [])
+                .filter(b => mouseCol >= b.startCol && mouseCol < b.endCol)
+                .map(b => b.annotation);
+            return hits.length > 0 ? hits : noDomains;
         },
         /**
          * #getter
@@ -1829,8 +2987,7 @@ function stateModelFactory() {
          * #getter
          * row indices highlighted by the current tree hover (a hovered internal
          * node highlights every tip below it). Shared by the tree and MSA overlay
-         * canvases so they cannot disagree, and resolved through the memoized
-         * name->index map rather than rebuilding a lookup on each mouse move.
+         * canvases, via the memoized name->index map.
          */
         get hoveredRowIndices() {
             const { hoveredTreeNode, rowNamesSet } = self;
@@ -1843,8 +3000,8 @@ function stateModelFactory() {
         /**
          * #getter
          * contiguous runs of `highlightedColumns`, so a run of highlighted columns
-         * draws as one bordered band. Computed here because the overlay canvas
-         * redraws on every mouse move while the highlight itself rarely changes.
+         * draws as one bordered band. Memoized because the overlay canvas redraws
+         * on every mouse move.
          */
         get highlightedColumnRuns() {
             const { highlightedColumns } = self;
@@ -1868,12 +3025,13 @@ function stateModelFactory() {
          * is dropped. Row names that match no row are ignored.
          */
         get resolvedHighlights() {
-            const { blanks, rowNamesSet, rowMap } = self;
-            const toVisible = (globalCol) => {
-                const visible = self.globalColToVisibleCol(globalCol);
-                return visible ?? visibleColsBefore(blanks, globalCol);
-            };
-            return self.highlights.flatMap(({ row, rows, start, end, label, color }) => {
+            const { rowNamesSet, transientHighlights } = self;
+            // persisted highlights first, so transient ones draw on top
+            const all = [
+                ...self.highlights,
+                ...Object.values(transientHighlights).flat(),
+            ];
+            return all.flatMap(({ row, rows, start, end, label, color }) => {
                 const base = { label, color };
                 if (rows) {
                     const rowIndices = rows
@@ -1884,68 +3042,238 @@ function stateModelFactory() {
                 if (start === undefined || end === undefined) {
                     return [];
                 }
-                let startGlobal = start - 1;
-                let endGlobal = end - 1;
-                if (row !== undefined) {
-                    if (!rowMap.has(row)) {
-                        return [];
+                const span = self.visibleSpan({ row, start, end });
+                return span ? [{ ...base, ...span, rowIndices: [] }] : [];
+            });
+        },
+        /**
+         * #method
+         * per-column summary statistics: consensus residue and its identity
+         * fraction, both conservation scores, gap fraction, and the sorted non-gap
+         * residue distribution. undefined past the end of the alignment or for an
+         * all-gap column.
+         */
+        columnStatsAt(col) {
+            const { colStats, conservation, propertyConservation } = self;
+            return columnStats({
+                col,
+                colStats,
+                conservation,
+                propertyConservation,
+            });
+        },
+        /**
+         * #getter
+         * `columnStatsAt` for the hovered column, undefined when nothing is
+         * hovered
+         */
+        get mouseOverColumnStats() {
+            const { mouseCol, colStats, conservation, propertyConservation } = self;
+            return mouseCol === undefined
+                ? undefined
+                : columnStats({
+                    col: mouseCol,
+                    colStats,
+                    conservation,
+                    propertyConservation,
+                });
+        },
+        /**
+         * #method
+         */
+        getRowData(name) {
+            return {
+                data: self.MSA?.getRowData(name),
+                rowData: self.rowDataOf(name),
+            };
+        },
+        /**
+         * #getter
+         * each encoding with its scale resolved against the values its field
+         * takes: a feature channel reads them across the features drawn, every
+         * other channel across the row table. Resolved once per change of that
+         * table or the encodings, never per row per frame.
+         */
+        get resolvedEncodings() {
+            const rows = Object.values(self.rowData);
+            const features = self.filteredAnnotations;
+            return self.encodings.map(encoding => ({
+                ...encoding,
+                ...resolveScale(encoding.scale, featureChannels.has(encoding.channel)
+                    ? features
+                        .map(a => featureField(a, encoding.field))
+                        .filter(notEmpty)
+                    : rows.map(row => row?.[encoding.field]).filter(notEmpty)),
+            }));
+        },
+        /**
+         * #getter
+         * each row panel with its scale resolved against the values its field
+         * takes across the row table, giving the color per row name, the pixel
+         * column it draws in, and the entries its legend lists. Resolved once
+         * per change of that table or the panels, never per block per frame.
+         */
+        get resolvedRowPanels() {
+            const rows = Object.entries(self.rowData);
+            const { fillPalette, featureFillEncoding, featureLabels } = this;
+            const annotations = self.filteredAnnotations;
+            let offsetX = 0;
+            return self.rowPanels.map((panel, index) => {
+                const width = rowPanelWidth(panel, self.rowHeight);
+                const base = { id: `rowpanel-${index}`, width, offsetX };
+                offsetX += width;
+                if (panel.kind === 'features') {
+                    const color = panel.encoding?.color;
+                    const encoding = color
+                        ? resolveFeatureScale(color.field, color.scale, annotations)
+                        : featureFillEncoding;
+                    const label = panel.encoding?.label;
+                    const align = panel.transform?.find(t => t.type === 'align');
+                    return {
+                        ...base,
+                        kind: panel.kind,
+                        x: panel.x,
+                        header: panel.header ?? '',
+                        field: encoding?.field,
+                        legendTitle: encoding?.field,
+                        spans: featurePanelSpans({
+                            panel,
+                            width,
+                            rowHeight: self.rowHeight,
+                            colWidth: self.colWidth,
+                            domainBands: this.domainBands,
+                            annotationsByRow: self.annotationsByRow,
+                            shifts: align
+                                ? this.featureAlignShifts.get(align.on)
+                                : undefined,
+                        }),
+                        colors: featureColorMap(annotations, encoding, fillPalette),
+                        labels: label
+                            ? featureLabelMap(annotations, label)
+                            : featureLabels,
+                        legend: encoding?.legend ??
+                            this.visibleDomainTypes.map(d => ({
+                                id: d.accession,
+                                label: d.name,
+                                color: fillPalette[d.accession],
+                            })),
+                    };
+                }
+                const { colorOf, legend } = resolveScale(panel.scale, rows.map(([, row]) => row?.[panel.field]).filter(notEmpty));
+                const colors = new Map();
+                for (const [name, row] of rows) {
+                    const value = row?.[panel.field];
+                    const color = value === undefined ? undefined : colorOf(value);
+                    if (color) {
+                        colors.set(name, color);
                     }
-                    startGlobal = self.seqPosToGlobalCol(row, start - 1);
-                    endGlobal = self.seqPosToGlobalCol(row, end - 1);
                 }
-                const startCol = toVisible(startGlobal);
-                const endVisible = self.globalColToVisibleCol(endGlobal);
-                const endCol = endVisible ?? visibleColsBefore(blanks, endGlobal) - 1;
-                return startCol <= endCol
-                    ? [{ ...base, startCol, endCol, rowIndices: [] }]
-                    : [];
+                return {
+                    ...base,
+                    kind: panel.kind,
+                    field: panel.field,
+                    header: panel.header ?? panel.field,
+                    legendTitle: panel.legend ?? panel.field,
+                    colors,
+                    legend,
+                };
             });
         },
         /**
          * #getter
-         * per-column summary statistics for the hovered column: consensus residue
-         * and its identity fraction, conservation score, gap fraction, and the
-         * sorted non-gap residue distribution. undefined when nothing is hovered.
+         * the shift an `align` transform gives each row, keyed by the feature
+         * name it aligns on: the offset putting the first feature of that name
+         * at zero. A row carrying no such feature is absent, and keeps its own
+         * origin.
+         */
+        get featureAlignShifts() {
+            const names = new Set(self.rowPanels.flatMap(panel => panel.kind === 'features' && panel.x === 'position'
+                ? (panel.transform ?? [])
+                    .filter(t => t.type === 'align')
+                    .map(t => t.on)
+                : []));
+            return new Map([...names].map(on => [
+                on,
+                new Map(Object.entries(self.annotationsByRow)
+                    .map(([name, annotations]) => {
+                    const hit = annotations.find(a => featureName(a) === on);
+                    return hit ? [name, 1 - hit.start] : undefined;
+                })
+                    .filter(notEmpty)),
+            ]));
+        },
+        /**
+         * #getter
+         * the color the `tipLabel` channel gives each row, by row name. Undefined
+         * when no encoding names the channel, which leaves the labels the theme's
+         * text color.
          */
-        get mouseOverColumnStats() {
-            const { mouseCol } = self;
-            if (mouseCol === undefined) {
+        get tipLabelColors() {
+            const encoding = this.resolvedEncodings.find(e => e.channel === 'tipLabel');
+            if (!encoding) {
                 return undefined;
             }
-            const { colStats } = self;
-            if (mouseCol >= colStats.numColumns) {
-                return undefined;
+            const colors = new Map();
+            for (const [name, row] of Object.entries(self.rowData)) {
+                const value = row?.[encoding.field];
+                const color = value === undefined ? undefined : encoding.colorOf(value);
+                if (color) {
+                    colors.set(name, color);
+                }
             }
-            const total = colStats.total(mouseCol);
-            if (!total) {
+            return colors;
+        },
+        /**
+         * #getter
+         * the wash the `rowTint` channel draws over each row, indexed by row, or
+         * undefined when no encoding names the channel. The overlay draws these,
+         * so a tint stays out of the raster tile cache and its keys.
+         */
+        get rowTints() {
+            const encoding = this.resolvedEncodings.find(e => e.channel === 'rowTint');
+            if (!encoding) {
                 return undefined;
             }
-            const gaps = colStats.gapCount(mouseCol);
-            const distribution = colStats
-                .residueEntries(mouseCol)
-                .sort((a, b) => b[1] - a[1]);
-            const consensus = distribution[0];
-            return {
-                col: mouseCol,
-                total,
-                gaps,
-                gapFraction: gaps / total,
-                conservation: self.conservation[mouseCol] ?? 0,
-                propertyConservation: self.propertyConservation[mouseCol],
-                consensusLetter: consensus?.[0] ?? '',
-                consensusCount: consensus?.[1] ?? 0,
-                consensusFraction: consensus ? consensus[1] / total : 0,
-                distribution,
-            };
+            return self.rowNames.map(name => {
+                const value = self.rowDataOf(name)?.[encoding.field];
+                const color = value === undefined ? undefined : encoding.colorOf(value);
+                if (!color) {
+                    return undefined;
+                }
+                return withAlpha(color, rowTintAlpha);
+            });
         },
         /**
-         * #method
+         * #getter
+         * the color the `branch` channel gives each tree edge, by the node id at
+         * the edge's far end, or undefined when no encoding names the channel. A
+         * node takes the field value its tips agree on, so a clade of one value
+         * colors down from where it splits off, and a node whose tips disagree or
+         * whose value has no color is absent and draws in the default color.
+         *
+         * The pass runs over the whole tree, never `root`, so a collapsed or
+         * focused clade keeps the color the full tree gives it.
          */
-        getRowData(name) {
-            return {
-                data: self.MSA?.getRowData(name),
-                treeMetadata: self.treeMetadata[name],
-            };
+        get branchColors() {
+            const encoding = this.resolvedEncodings.find(e => e.channel === 'branch');
+            if (!encoding) {
+                return undefined;
+            }
+            const order = preorder(self.tree);
+            const values = new Map();
+            const colors = new Map();
+            for (let i = order.length - 1; i >= 0; i--) {
+                const node = order[i];
+                const value = node.children.length > 0
+                    ? sharedValue(node.children.map(child => values.get(child)))
+                    : self.rowDataOf(node.name)?.[encoding.field];
+                values.set(node, value);
+                const color = value === undefined ? undefined : encoding.colorOf(value);
+                if (color) {
+                    colors.set(node.id, color);
+                }
+            }
+            return colors;
         },
     }))
         .actions(self => ({
@@ -1958,27 +3286,43 @@ function stateModelFactory() {
         /**
          * #action
          */
-        setConservationTrackHeight(arg) {
-            self.conservationTrackHeight = arg;
+        setHideHeader(arg) {
+            self.hideHeader = arg;
+        },
+        /**
+         * #action
+         * focus the subtree a click `y` pixels down the tree overview lands on.
+         * A click inside the box already drawn there clears the focus, the way
+         * clicking the focused branch again does.
+         */
+        treeOverviewClick(y) {
+            const hit = self.treeOverviewHit(y);
+            const focus = self.treeOverviewFocusRows;
+            const inside = !!focus && !!hit && hit.rows[0] >= focus[0] && hit.rows[1] <= focus[1];
+            self.setShowOnly(inside || !hit ? undefined : hit.id);
         },
         /**
          * #action
+         * resize every track sharing a `heightKey`; see `trackHeights`
          */
-        setSequenceLogoTrackHeight(arg) {
-            self.sequenceLogoTrackHeight = arg;
+        setTrackHeight(heightKey, height) {
+            self.trackHeights.set(heightKey, height);
         },
         /**
          * #action
-         * Return to the import form: every property off `preservedOnReset`
-         * (data, filehandles, collapsed/showOnly, zoom, scroll, ...) goes back
-         * to its default, then the file-derived volatiles applySnapshot cannot
-         * reach are cleared by hand.
+         * Return to the import form: reset every property not in
+         * `preservedOnReset` to its default, then clear the file-derived
+         * volatiles applySnapshot does not touch.
          */
         reset() {
+            self.resetCount++;
+            self.clearWarnings();
+            self.setStatus(undefined);
             applySnapshot(self, Object.fromEntries(Object.entries(getSnapshot(self)).filter(([key]) => preservedOnReset.has(key))));
             self.setError(undefined);
             self.setAnnotations([]);
             self.setHighlightedColumns(undefined);
+            self.transientHighlights = {};
             self.setMousePos(undefined, undefined);
             self.setMouseClickPos(undefined, undefined);
             self.setHoveredTreeNode(undefined);
@@ -1992,20 +3336,31 @@ function stateModelFactory() {
             const blob = new Blob([html], { type: 'image/svg+xml' });
             saveAs(blob, exportFileName(self.msaFilehandle, 'svg'));
         },
-        initFilter(arg) {
-            if (!self.featureFilters.has(arg)) {
-                self.featureFilters.set(arg, true);
+        /**
+         * #action
+         * show or hide an annotation type. Only hidden types are recorded; see
+         * `turnedOffFeatures`
+         */
+        setFilter(accession, shown) {
+            if (shown) {
+                self.turnedOffFeatures.delete(accession);
+            }
+            else {
+                self.turnedOffFeatures.set(accession, true);
             }
-        },
-        setFilter(arg, flag) {
-            self.featureFilters.set(arg, flag);
         },
         /**
          * #action
          */
         fit() {
-            this.fitVertically();
-            this.fitHorizontally();
+            // two passes: each direction's viewport depends on whether the other
+            // overflows (the minimap takes height, the vertical scrollbar width)
+            transaction(() => {
+                for (let pass = 0; pass < 2; pass++) {
+                    this.fitHorizontally();
+                    this.fitVertically();
+                }
+            });
         },
         /**
          * #action
@@ -2016,34 +3371,64 @@ function stateModelFactory() {
             }
             self.scrollY = 0;
         },
+        /**
+         * #action
+         * zoom and scroll so a span fills the alignment's width, in highlight
+         * coordinates (see visibleSpan). Does nothing before the viewer knows
+         * its width, or for a span that resolves to no visible column.
+         */
+        zoomToRegion(region) {
+            const span = self.visibleSpan(region);
+            if (!span || !self.viewInitialized) {
+                return;
+            }
+            transaction(() => {
+                self.colWidth = clamp(self.msaCanvasWidth / (span.endCol - span.startCol + 1), minColWidth, maxCellSize);
+                self.scrollX = clamp(-span.startCol * self.colWidth, self.maxScrollX, 0);
+            });
+        },
         /**
          * #action
          */
         fitHorizontally() {
             if (self.numColumns > 0) {
-                // fitting to msaAreaWidth instead left the last ~20px of columns off
-                // the right edge -- and short of the width that shows a minimap, so
-                // nothing on screen said they were there
+                // msaCanvasWidth excludes the vertical scrollbar's 20px
                 self.colWidth = clamp(self.msaCanvasWidth / self.numColumns, minColWidth, maxCellSize);
             }
             self.scrollX = 0;
         },
         afterCreate() {
-            // seed the highlighted-columns overlay from the declarative property so
-            // a shared snapshot/URL opens with those columns highlighted (the
-            // volatile highlightedColumns can later be driven by genome-hover sync)
             if (self.highlightColumns?.length) {
                 self.setHighlightedColumns(self.highlightColumns);
             }
+            // The `collapse` and `focus` clade marks seed the collapsed list and
+            // the subtree in focus, which the tree, `hideGapsEffective` and the
+            // alignment all read. The tree arrives with the model for inline data
+            // and later for a filehandle, so the seeding waits for it and then runs
+            // once: expanding a seeded clade sticks, and the record collapses it
+            // again only on reload.
+            let cladesSeeded = false;
             addDisposer(self, autorun(() => {
-                for (const key of self.annotationTypes.keys()) {
-                    this.initFilter(key);
+                if (cladesSeeded ||
+                    !self.dataInitialized ||
+                    self.clades.length === 0) {
+                    return;
+                }
+                cladesSeeded = true;
+                for (const { mark, nodeId } of self.resolvedClades) {
+                    if (nodeId === undefined) {
+                        continue;
+                    }
+                    if (mark === 'collapse' && !self.collapsed.includes(nodeId)) {
+                        self.toggleCollapsed(nodeId);
+                    }
+                    else if (mark === 'focus') {
+                        self.setShowOnly(nodeId);
+                    }
                 }
             }));
-            // track the live device pixel ratio so canvas backing stores re-scale
-            // when the window moves between monitors or the browser zooms. The
-            // matchMedia query is pinned to the current ratio, so each change
-            // re-registers against the new one to keep tracking further moves.
+            // the matchMedia query is pinned to the current device pixel ratio, so
+            // each change re-registers against the new one
             if (typeof window !== 'undefined' &&
                 typeof window.matchMedia === 'function') {
                 const query = () => window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
@@ -2063,32 +3448,41 @@ function stateModelFactory() {
              * Fetch a filehandle whenever it changes, and hand the text to
              * `onLoad`.
              *
-             * Every loader carries a generation guard: the filehandle can change
-             * mid-fetch (a second file picked while the first is still in flight),
-             * and the slower earlier request must not clobber the data, status, or
-             * loading flag belonging to the newer one.
+             * A generation guard keeps a slower superseded request from overwriting
+             * the newer one's data, status or loading flag. A superseded or cleared
+             * request is aborted and clears its status line.
+             *
+             * `clearFilehandle` 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.
              *
-             * `clearFilehandle` serves two purposes for the loaders that pass it.
-             * A local file has no URL to refetch from, so the handle is dropped
-             * once its bytes are in the model; and a fetch the user cancels drops
-             * it too, returning the view to the import form rather than leaving a
-             * stuck spinner.
+             * `what` names the layer in a failure message. An `optional` layer
+             * (annotations, row metadata) that fails adds a warning instead of an
+             * error.
              */
-            const loadOnFilehandleChange = ({ getFilehandle, onLoad, setLoading, clearFilehandle, }) => {
+            const loadOnFilehandleChange = ({ what, getFilehandle, onLoad, setLoading, clearFilehandle, optional = false, }) => {
                 let generation = 0;
+                let cancelInFlight;
+                addDisposer(self, () => {
+                    cancelInFlight?.();
+                });
                 addDisposer(self, autorun(async () => {
                     const filehandle = getFilehandle();
-                    // a cleared filehandle bumps the generation too, so a reset()
-                    // mid-download invalidates the in-flight fetch instead of letting
-                    // its onLoad land on the emptied model. That also orphans the
-                    // invalidated run's `finally`, so the loading flag is cleared
-                    // here on its behalf
                     const current = ++generation;
+                    cancelInFlight?.();
+                    cancelInFlight = undefined;
                     if (!filehandle) {
                         setLoading?.(false);
                         return;
                     }
-                    const isCurrent = () => current === generation;
+                    const isCurrent = () => current === generation && isAlive(self);
+                    const controller = new AbortController();
+                    cancelInFlight = () => {
+                        controller.abort();
+                        if (isAlive(self)) {
+                            self.setStatus(undefined);
+                        }
+                    };
                     try {
                         setLoading?.(true);
                         self.setError(undefined);
@@ -2096,7 +3490,7 @@ function stateModelFactory() {
                             if (isCurrent()) {
                                 self.setStatus(status);
                             }
-                        });
+                        }, { controller });
                         if (isCurrent()) {
                             transaction(() => {
                                 onLoad(text);
@@ -2113,18 +3507,25 @@ function stateModelFactory() {
                             }
                             else {
                                 console.error(e);
-                                self.setError(e);
+                                if (optional) {
+                                    self.addWarning(`The ${what} did not load: ${e}`);
+                                }
+                                else {
+                                    self.setError(e);
+                                }
                             }
                         }
                     }
                     finally {
                         if (isCurrent()) {
+                            cancelInFlight = undefined;
                             setLoading?.(false);
                         }
                     }
                 }));
             };
             loadOnFilehandleChange({
+                what: 'tree',
                 getFilehandle: () => self.treeFilehandle,
                 onLoad: text => {
                     self.setTree(text);
@@ -2136,38 +3537,49 @@ function stateModelFactory() {
                     self.setTreeFilehandle(undefined);
                 },
             });
-            // treeMetadata is decorative and has no import-form step of its own, so
-            // it keeps no loading flag and nothing to return to on cancel
+            // treeMetadata has no import-form step, so no loading flag or cancel
             loadOnFilehandleChange({
+                what: 'row metadata',
+                optional: true,
                 getFilehandle: () => self.treeMetadataFilehandle,
                 onLoad: text => {
                     self.setTreeMetadata(text);
                 },
             });
-            // autorun parses inline gff text from data.gff
+            // parses data.gff into annotations. Clearing the text clears only the
+            // annotations this autorun applied, not ones a host set directly
+            let appliedGFF = false;
             addDisposer(self, autorun(() => {
                 const gffText = self.data.gff;
                 if (gffText) {
                     try {
                         self.applyGFFText(gffText);
+                        appliedGFF = true;
                     }
                     catch (e) {
                         console.error(e);
-                        self.setError(e);
+                        self.addWarning(`The annotations did not parse: ${e}`);
                     }
                 }
+                else if (appliedGFF) {
+                    appliedGFF = false;
+                    self.setAnnotations([]);
+                }
             }));
-            // gffFilehandle carries overlay annotations
+            // gffFilehandle loads into data.gff, which the autorun above parses
             loadOnFilehandleChange({
+                what: 'annotations',
+                optional: true,
                 getFilehandle: () => self.gffFilehandle,
                 onLoad: text => {
-                    self.applyGFFText(text);
+                    self.setGFF(text);
                 },
                 clearFilehandle: () => {
                     self.setGFFFilehandle(undefined);
                 },
             });
             loadOnFilehandleChange({
+                what: 'alignment',
                 getFilehandle: () => self.msaFilehandle,
                 onLoad: text => {
                     self.setMSA(text);
@@ -2179,19 +3591,12 @@ function stateModelFactory() {
                     self.setMSAFilehandle(undefined);
                 },
             });
-            // Keep the parse chain warm: reading self.columns transitively holds
-            // self.MSA (parseMSA) computed alive, so it is parsed once per data
-            // change rather than re-parsed on every non-reactive access. Do not
-            // remove.
+            // Keep computeds alive that are read outside reactions, so they are not
+            // recomputed on every access: self.columns (and through it the
+            // parseMSA result), and the column statistics that dynamic color
+            // schemes and the mousemove-driven hover tooltip read.
             // xref solution https://github.com/mobxjs/mobx/issues/266#issuecomment-222007278
             // xref problem https://github.com/GMOD/react-msaview/issues/75
-            //
-            // The column statistics are held for the same reason whenever something
-            // reads them off the reactive path: dynamic color schemes, and the hover
-            // tooltip, which is read from a mousemove handler. Without this the
-            // tooltip's cost depends on whether some visible track happens to be
-            // observing them, so closing the conservation track would silently turn
-            // every mouse move into a full-alignment recount.
             addDisposer(self, autorun(() => {
                 if (self.colorSchemeName.includes('dynamic')) {
                     // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
@@ -2209,27 +3614,39 @@ function stateModelFactory() {
                 // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
                 self.columns;
             }));
-            // autorun: when autoTreeAreaWidth is set and no tree is drawn, shrink the
-            // tree area to fit the row labels rather than padding it to the fixed
-            // default. Gated on noTree/!drawTree so it never fights the treeWidth sync
-            // below (treeAreaWidth here depends only on labelsWidth, not treeWidth).
+            // with autoTreeAreaWidth and no tree drawn, size the tree area to the
+            // labels. Gated on noTree/!drawTree so it does not loop with the
+            // treeWidth autorun below
             addDisposer(self, autorun(() => {
                 if (self.autoTreeAreaWidth &&
                     (self.noTree || !self.drawTree) &&
                     self.labelsWidth) {
-                    self.setTreeAreaWidth(self.labelsWidth + self.marginLeft + 12);
+                    self.setTreeAreaWidth(self.labelsWidth + self.marginLeft + 12 + self.cladeGutterWidth);
                 }
             }));
-            // autorun synchronizes treeWidth with treeAreaWidth
+            // treeWidth follows the tree area less the labels. A non-default
+            // snapshot treeWidth (jbrowse-plugin-msaview opens at 100 in a 200px
+            // area) is kept until the tree area changes. Not a getter, because
+            // labelsWidth is measured off leaves laid out against treeWidth.
+            let pinnedAreaWidth = self.treeWidth === defaultTreeWidth ? undefined : self.treeAreaWidth;
             addDisposer(self, autorun(() => {
-                self.setTreeWidth(Math.max(50, self.treeAreaWidth - self.labelsWidth - 10 - self.marginLeft));
+                const areaWidth = self.treeAreaWidth;
+                const labelsWidth = self.labelsWidth;
+                if (pinnedAreaWidth === areaWidth) {
+                    return;
+                }
+                pinnedAreaWidth = undefined;
+                self.setTreeWidth(Math.max(50, areaWidth -
+                    labelsWidth -
+                    10 -
+                    self.marginLeft -
+                    self.cladeGutterWidth));
             }));
         },
     }))
         .postProcessSnapshot(({ data, columnTracks, ...rest }) => ({
-        // per-property defaults are stripped by the stripDefault helper; the only thing
-        // it can't express is this cross-field rule: drop inline tree/msa/metadata
-        // when a sibling filehandle can refetch them, keeping sessions/URLs small
+        // stripDefault handles per-property defaults; this drops inline documents
+        // whose filehandle can refetch them
         ...rest,
         ...smallColumnTracks(columnTracks),
         data: {