react-msaview 7.0.0 → 8.0.0

package/dist/model.js

@@ -2,20 +2,25 @@ import { clamp, groupBy, notEmpty, sum } from '@jbrowse/core/util';
 import { openLocation } from '@jbrowse/core/util/io';
 import { ElementId, FileLocation } from '@jbrowse/core/util/types/mst';
 import { addDisposer, applySnapshot, cast, getSnapshot, isAlive, types, } from '@jbrowse/mobx-state-tree';
-import { colord } from 'colord';
 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, defaultTreeWidth, labelReferenceFontSize, maxCellSize, maxInlineSnapshotBytes, maxNeighborJoiningRows, 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, forEachDescendant, hierarchy, leaves, 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';
@@ -25,10 +30,11 @@ import { calculateNeighborJoiningTree } from './neighborJoining.js';
 import { parseAsn1 } from './parseAsn1.js';
 import { calculatePropertyConservation } from './propertyConservation.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) {
@@ -37,14 +43,141 @@ function parseTreeText(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.
+// 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']);
-// base-pair arcs: one color for the nested helices, one for a pseudoknot, whose
-// whole point is that it crosses them
+// 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
 function columnTrackSizes(tracks) {
@@ -59,17 +192,13 @@ function smallColumnTracks(tracks) {
  * 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',
@@ -77,6 +206,7 @@ export const preservedOnReset = new Set([
     'height',
     'drawMsaLetters',
     'scrollZoom',
+    'scrollZoomAxis',
     'bgColor',
     'colorSchemeName',
     'showColumnStats',
@@ -87,50 +217,167 @@ 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.
-// A track the file itself supplies says whether it starts hidden, since only
-// the file knows how many of them there are: a Pfam seed carries a couple of
-// #=GR lines, an Rfam family one per row.
+// `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));
 }
-// one array for every "nothing under the pointer", since a fresh [] is a fresh
-// value to every observer of it
+// shared empty results, so observers don't see a fresh [] as a change
 const noDomains = [];
-// seqPos -> column indexes, per row, hung off the parse the rows came from so
-// they are collected with it. A computed would rebuild every row's index on
-// each miss, and rebuild all of them again whenever it was read outside a
-// reactive context.
+const 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 asserts a 1:1 run, so its two sides have to be the same length.
-// One that is not is malformed data, and the arithmetic below would answer
-// anyway -- with a residue that is off by however much the sides disagree. Skip
-// it, the same refusal an uncovered position gets.
+// 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);
 }
-// Does the content need a scrollbar? fit() divides the viewport by the row or
-// column count and multiplies it back, so an exact fit lands a fraction of a
-// pixel over -- enough for a `>` to answer yes and hand the reader a minimap or
-// a scrollbar for half a pixel of nothing, which then shrinks the viewport and
-// leaves a gap.
+// 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
  *
@@ -166,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),
         /**
@@ -198,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
@@ -269,18 +519,25 @@ 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
-         * which residue of which structure each row's residues are, as data.
-         * The viewer cannot infer this -- matching a row to a structure by
-         * sequence equality fails for a tagged construct, a truncation or a
-         * subsequence row, and fails in the direction that looks like it
-         * worked -- so it arrives computed. See docs/layers.md
+         * 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()), []),
         /**
@@ -296,10 +553,9 @@ function stateModelFactory() {
         /**
          * #property
          * the user's explicit hide choices per annotation accession, keyed by
-         * accession with the value meaning "off", the same shape as
-         * `turnedOffTracks`. An accession the user has never touched is absent
-         * and drawn, so a file of two hundred domain types adds nothing to the
-         * shared URL until someone filters one out
+         * 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
          */
         turnedOffFeatures: stripDefault(types.map(types.boolean), {}),
         /**
@@ -320,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,
         /**
@@ -394,40 +679,14 @@ function stateModelFactory() {
         highlightedColumns: undefined,
         /**
          * #volatile
-         * transient highlights keyed by who asked for them. One slot cannot hold
-         * two sources -- a structure viewer's hover and a genome view's hover
-         * both want to point at a column, and with one slot whoever clears last
-         * erases the other's. Keyed by owner, each source adds and removes only
-         * its own. Not persisted: a hover is not part of the document.
+         * 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
          */
         minimapHeight: 56,
-        /**
-         * #volatile
-         */
-        conservationTrackHeight: 40,
-        /**
-         * #volatile
-         * heights of individual `columnTracks`, by track id. A data track is
-         * resized on its own: the shared per-kind heights below belong to the
-         * tracks the viewer computes, and dragging a data track's handle used to
-         * resize those instead.
-         */
-        columnTrackHeights: {},
-        /**
-         * #volatile
-         * taller than the conservation track by default: the logo spends its
-         * height on stacked glyphs, and a 40px stack of four residues leaves each
-         * one too short to identify
-         */
-        sequenceLogoTrackHeight: 80,
-        /**
-         * #volatile
-         */
-        arcTrackHeight: 50,
         /**
          * #volatile
          */
@@ -439,33 +698,28 @@ function stateModelFactory() {
         error: undefined,
         /**
          * #volatile
-         * load problems the view carried on through: an optional layer that did
-         * not arrive, an overlay that did not parse. `error` is the other kind --
-         * it replaces the view, which is right for the alignment and wrong for a
-         * decorative file
+         * 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
          */
         warnings: [],
         /**
          * #volatile
-         * bumped by reset(). The React error boundary above the view keeps its
-         * caught error until it is remounted, so "Return to import form" did
-         * nothing after a render error until this became its key
+         * bumped by reset(). The error boundary above the view uses it as its key,
+         * since the boundary keeps its caught error until remounted
          */
         resetCount: 0,
         /**
          * #volatile
-         * set by a host that restores the loaded documents by its own means --
-         * a jbrowse session that holds them, a page that refetches them on load.
-         * `unshareableData` then reports nothing, since what it warns about is a
-         * link that opens empty, and under such a host the link does not
+         * set by a host that restores the loaded documents itself, such as a
+         * jbrowse session or a page that refetches them. `unshareableData` then
+         * reports nothing
          */
         hostCarriesData: false,
         /**
          * #volatile
-         * overlay annotations drawn on the alignment, whatever their source.
-         * Every source -- InterProScan, GFF, a user upload -- converts to this
-         * flat list before it reaches the model, so nothing downstream of here
-         * knows which one it came from
+         * overlay annotations drawn on the alignment. InterProScan JSON, GFF and
+         * user uploads all convert to this flat list
          */
         annotations: [],
     }))
@@ -511,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;
@@ -533,8 +787,8 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * report something the view survived: a layer that failed to load, a
-         * file that failed to parse
+         * 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];
@@ -548,7 +802,7 @@ function stateModelFactory() {
         /**
          * #action
          * declare that this host restores the loaded documents itself, which
-         * takes down the "Not in the link" warning. See `hostCarriesData`
+         * hides the "Not in the link" warning. See `hostCarriesData`
          */
         setHostCarriesData(arg) {
             self.hostCarriesData = arg;
@@ -557,9 +811,9 @@ function stateModelFactory() {
          * #action
          * set mouse position (row, column) in the MSA
          *
-         * PUBLIC API: a host drives this (and reads the `mouseCol` volatile) to
-         * sync the alignment's hover with a view of its own -- a genome view, a
-         * 3D structure. Keep the name and signature stable.
+         * 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;
@@ -569,9 +823,9 @@ function stateModelFactory() {
          * #action
          * set highlighted columns
          *
-         * PUBLIC API: jbrowse-plugin-msaview calls this from its
-         * afterCreateAutoruns to highlight alignment columns, and MSAViewer
-         * passes its `highlightColumns` prop through it. Not dead code.
+         * Public API: jbrowse-plugin-msaview calls this from its
+         * afterCreateAutoruns, and MSAViewer passes its `highlightColumns` prop
+         * through it.
          */
         setHighlightedColumns(columns) {
             self.highlightedColumns = columns;
@@ -584,10 +838,15 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * show `highlights` on behalf of `owner`, replacing whatever that owner
-         * showed before and leaving every other owner's alone. The object is
-         * replaced rather than mutated so one assignment is the observable
-         * change.
+         * 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 = {
@@ -597,7 +856,7 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * drop what `owner` was showing, leaving every other owner's in place
+         * remove `owner`'s highlights, leaving other owners' in place
          */
         clearHighlight(owner) {
             if (owner in self.transientHighlights) {
@@ -649,10 +908,9 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * switch to another alignment of a multi-alignment file (Stockholm). The
-         * new alignment has its own rows and its own tree, so everything naming
-         * the old one's -- the collapsed node ids, the subtree in focus, the
-         * reference row, the scroll position -- goes with it
+         * 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) {
             if (n === self.currentAlignment) {
@@ -739,11 +997,10 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * keep the GFF text the way the alignment and the tree are kept, rather
-         * than only its parsed annotations. The annotations are volatile, so a
-         * file opened from disk used to leave no trace in the snapshot at all --
-         * not the text, and not the filehandle, which is cleared once a blob is
-         * read. An autorun parses this back into annotations.
+         * 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);
@@ -772,16 +1029,14 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * whether this host brings the loaded documents back by means the
-         * snapshot cannot see, which is what decides whether `unshareableData`
-         * has anything to warn about.
+         * whether the host restores the loaded documents outside the snapshot.
+         * When true, `unshareableData` is empty.
          *
-         * A simple host flips the `hostCarriesData` volatile. A host whose
-         * answer depends on how the view was opened overrides this getter in a
-         * `.views` block of its own composed model -- jbrowse-plugin-msaview's
-         * indexed-location views refetch from a URL the session holds, while its
-         * data-store views really are absent from a link someone pastes
-         * elsewhere. `unshareableData` reads it off `self`, so an override wins.
+         * 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;
@@ -804,8 +1059,8 @@ function stateModelFactory() {
          * #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]);
         },
@@ -832,29 +1087,23 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * the loaded documents this view's own snapshot cannot carry, largest
-         * first. A file opened from disk or pasted in becomes inline text, and
-         * DataModel drops an inline document past `maxInlineSnapshotBytes`
-         * rather than put megabytes of sequence into a session or a URL.
+         * 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`.
          *
-         * Dropping it is right. Dropping it silently is what makes a copied link
-         * open an empty viewer, so the header says so and the standalone app
-         * stops rewriting the address bar while this is non-empty. A document
-         * fetched from a URL never appears here whatever its size: the snapshot
-         * keeps the filehandle and refetches through it.
+         * 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.
          *
-         * Nothing is unshareable when the host restores the data by its own
-         * means (see `hostRestoresData`) -- inside a session that reloads these
-         * documents from somewhere the snapshot does not show, the warning is
-         * simply wrong.
+         * Empty when `hostRestoresData` is true.
          */
         get unshareableData() {
             if (self.hostRestoresData) {
                 return [];
             }
             const { data } = self;
-            // a data track past the limit leaves the snapshot the same way an
-            // inline document does, and left unreported the same way too
+            // data tracks past the limit also leave the snapshot
             const trackBytes = columnTrackSizes(self.columnTracks)
                 .filter(bytes => bytes > maxInlineSnapshotBytes)
                 .reduce((a, b) => a + b, 0);
@@ -875,13 +1124,14 @@ function stateModelFactory() {
         },
         /**
          * #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 {};
@@ -893,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
          */
@@ -942,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
          */
@@ -974,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
-         * widget width minus the tree area gives the space for the MSA
+         * the pixel column the row panels occupy between the tree and the
+         * alignment, the sum of each record's width
+         */
+        get rowPanelsWidth() {
+            return sum(self.rowPanels.map(p => rowPanelWidth(p, self.rowHeight)));
+        },
+        /**
+         * #getter
+         * height of the band the row panel headers draw in, which is zero with
+         * no row panels and leaves the top area as it was
+         */
+        get rowPanelsHeaderHeight() {
+            return self.rowPanels.length > 0 ? rowPanelHeaderHeight : 0;
+        },
+        /**
+         * #getter
+         * widget width minus the tree area and the row panels gives the space
+         * for the MSA
          */
         get msaAreaWidth() {
-            return self.width - self.treeAreaWidth - self.resizeHandleWidth;
+            return (self.width -
+                self.treeAreaWidth -
+                this.rowPanelsWidth -
+                self.resizeHandleWidth);
         },
         /**
          * #getter
+         * the right edge the tip labels end at, which is the tree area less the
+         * margin and the bracket gutter
          */
         get treeAreaWidthMinusMargin() {
-            return self.treeAreaWidth - self.marginLeft;
+            return self.treeAreaWidth - self.marginLeft - this.cladeGutterWidth;
         },
         /**
          * #getter
@@ -1077,10 +1463,8 @@ 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;
@@ -1088,12 +1472,8 @@ function stateModelFactory() {
         /**
          * #method
          * index of the global column holding each ungapped sequence position of a
-         * row, so seqPos -> column is a lookup rather than a scan. The domain
-         * overlay resolves thousands of these per redraw.
-         *
-         * Built per row, on the row asked for: the first lookup used to index
-         * every row in the alignment. The cache is keyed on the parse the rows
-         * came from, so a new alignment brings a new one.
+         * row. The domain overlay resolves thousands of these per redraw. Built
+         * lazily per row and cached on the parse.
          */
         seqPosIndex(rowName) {
             const MSA = this.MSA;
@@ -1118,10 +1498,9 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * every sequence the alignment holds, keyed by row name, whatever the
-         * tree currently shows. `rows` is the rows on screen; this is the rows
-         * that exist, and every lookup about a named row goes through it --
-         * collapsing a clade hides rows, it does not delete their sequence
+         * 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() {
             const MSA = this.MSA;
@@ -1254,10 +1633,8 @@ function stateModelFactory() {
             clusterLayout(r, this.totalHeight, self.treeWidth);
             const max = this.rootToTipLength;
             const k = max ? self.treeWidth / max : 0;
-            // the displayed root starts at x=0 whatever branch length it carries,
-            // so its own length is subtracted here rather than zeroed on the parsed
-            // node -- `root` hands out the cached parse, and writing to it made
-            // showOnly shorten that branch for good
+            // 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
@@ -1293,19 +1670,16 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * x-position of the farthest tip in a phylogram, px. The layout scales
-         * the longest root-to-tip path onto treeWidth, so that is where it lands
-         * -- and 0 for a tree carrying no lengths at all, which draws as a
-         * cladogram instead
+         * 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 this.rootToTipLength ? self.treeWidth : 0;
         },
         /**
          * #getter
-         * pixels per unit of branch length in the current phylogram layout, and 0
-         * in cladogram mode, where the x-positions carry no length at all. The
-         * scale bar over the tree is drawn from it.
+         * 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);
@@ -1362,20 +1736,17 @@ function stateModelFactory() {
          * #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
+            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, and measuring '' would size the gutter (and
-                    // the label's click target) to nothing
-                    const displayName = treeMetadata[name]?.genome || name;
+                    // to the row name
+                    const displayName = self.rowDataOf(name)?.genome || name;
                     return [
                         name,
                         measureTextCanvas(displayName, labelReferenceFontSize),
@@ -1392,11 +1763,9 @@ function stateModelFactory() {
             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
+            // 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) {
@@ -1419,9 +1788,8 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * the base pairs of the consensus secondary structure, as arcs. The WUSS
-         * string is collapsed through the hidden columns before it is parsed, so
-         * the pairs land in the same visible column space the text track does
+         * the base pairs of the consensus secondary structure, as arcs, in
+         * visible column space (hidden columns are removed before parsing)
          */
         get secondaryStructureArcs() {
             const { blanks, hideGapsEffective } = self;
@@ -1442,9 +1810,8 @@ function stateModelFactory() {
             const { MSA, hideGapsEffective, blanks } = self;
             const tracks = (MSA?.tracks ?? []).filter(t => !!t.data);
             if (tracks.length === 0) {
-                // reading rowHeight up front made every zoom frame rebuild the track
-                // list, and the canvases redraw on the track object they are handed
-                // changing
+                // return before reading rowHeight, so zooming does not rebuild the
+                // list and redraw every track canvas
                 return [];
             }
             const { rowHeight } = self;
@@ -1481,11 +1848,9 @@ function stateModelFactory() {
                 return out;
             };
             const skip = (items) => hideGapsEffective ? dropBlanks(blanks, items) : items;
-            // an arc names two positions rather than one per column, so it takes
-            // the same two steps the arrays take -- a row's residues onto columns,
-            // then columns onto the visible ones -- as a lookup. visibleColsBefore,
-            // not globalColToVisibleCol: an endpoint in a hidden column collapses
-            // to where that column went instead of taking the whole arc with it
+            // 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]
@@ -1518,45 +1883,48 @@ function stateModelFactory() {
             }));
         },
         /**
-         * #getter
+         * #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
          */
-        get columnTrackModels() {
-            // read per kind, not up front: a text track is the only kind sized by
-            // the row height, and reading it here rebuilt every data track on every
-            // vertical zoom step
-            const defaultHeight = (kind) => kind === 'bar'
-                ? self.conservationTrackHeight
-                : kind === 'arc'
-                    ? self.arcTrackHeight
-                    : self.rowHeight;
-            return self.columnTracks.map(track => ({
-                model: {
-                    id: track.id,
-                    name: track.name,
-                    kind: track.kind,
-                    height: self.columnTrackHeights[track.id] ??
-                        track.height ??
-                        defaultHeight(track.kind),
-                    // the spec has one `color`; bar and arc are separate track models
-                    // that read it under their own name
-                    barColor: track.color,
-                    arcColor: track.color,
-                    customColorScheme: track.colors,
-                    data: this.columnTrackContent.get(track.id)?.data,
-                    arcs: this.columnTrackContent.get(track.id)?.arcs,
-                },
-                ReactComponent: TrackBlocks,
-            }));
+        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. Its
-         * own getter so the object keeps its identity across a zoom: the canvas
-         * redraws on the track it is handed changing, and rebuilding these
-         * alongside everything else made every zoom frame redraw every track
+         * 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;
@@ -1567,7 +1935,8 @@ function stateModelFactory() {
                             id: 'base-pairs',
                             name: 'Base pairs',
                             kind: 'arc',
-                            height: self.arcTrackHeight,
+                            heightKey: 'arc',
+                            height: this.trackHeight('arc'),
                             arcs,
                         },
                         ReactComponent: TrackBlocks,
@@ -1577,8 +1946,8 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * the tracks computed from the alignment itself, which depend on their
-         * own heights and on the alphabet -- and on nothing zoom changes
+         * the tracks computed from the alignment; they depend on their heights
+         * and the alphabet, not on zoom
          */
         get computedTrackModels() {
             return [
@@ -1586,7 +1955,6 @@ function stateModelFactory() {
                     id: 'conservation',
                     name: 'Conservation',
                     kind: 'bar',
-                    height: self.conservationTrackHeight,
                     barColor: 'gray',
                 },
                 ...(self.sequenceType === 'amino'
@@ -1595,7 +1963,6 @@ function stateModelFactory() {
                             id: 'property-conservation',
                             name: 'Property conservation',
                             kind: 'bar',
-                            height: self.conservationTrackHeight,
                             barColor: '#6a51a3',
                         },
                     ]
@@ -1604,23 +1971,32 @@ function stateModelFactory() {
                     id: 'sequence-logo',
                     name: 'Sequence logo',
                     kind: 'logo',
-                    height: self.sequenceLogoTrackHeight,
                 },
                 // last, so it sits against the alignment it numbers
                 {
                     id: 'position-ruler',
                     name: 'Position',
                     kind: 'ruler',
-                    height: 20,
                 },
-            ].map(model => ({ model, ReactComponent: TrackBlocks }));
+            ].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,
-                ...this.computedTrackModels,
+                // 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 : []),
             ];
         },
         /**
@@ -1651,19 +2027,18 @@ function stateModelFactory() {
          * Convert a visible column to a row-specific sequence position (0-based).
          * Returns undefined if the position is a gap in the sequence.
          *
-         * PUBLIC API: this and the sibling coordinate converters
-         * (visibleColToGlobalCol, seqPosToVisibleCol, globalColToVisibleCol,
-         * seqPosToGlobalCol) are how a host translates between alignment columns
-         * and a row's residue positions across gaps. Keep them stable.
+         * 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) {
-            // a binary search of the row's index, not a scan of the row: this
-            // answers on every mouse move, and a 30k-column row scanned per event
-            // is the whole frame
+            // 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));
         },
         /**
@@ -1697,10 +2072,9 @@ function stateModelFactory() {
         },
         /**
          * #method
-         * Convert a visible column index (what a mouse handler reports) back to a
-         * column of the full alignment. Hidden columns shift everything to their
-         * right, so a host that holds per-column data of its own has to make this
-         * hop before indexing it.
+         * 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
@@ -1714,8 +2088,7 @@ function stateModelFactory() {
         /**
          * #method
          * Convert a sequence position (ungapped) to a global column index.
-         * Returns undefined for a row the alignment does not have -- answering
-         * anyway is how a mistyped or stale row name came to highlight column 0.
+         * 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)
@@ -1746,12 +2119,39 @@ function stateModelFactory() {
                 ? 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
-         * every reason a mapping is being ignored, so a host can say which. A
-         * mapping outlives the alignment it was computed for; when the two no
-         * longer agree the lookups have to refuse, and refusing invisibly is how
-         * "there is no structure here" gets confused with "this data is stale".
+         * 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 = [];
@@ -1798,10 +2198,8 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * the mappings that still fit the loaded alignment. A row-level problem
-         * takes the whole mapping out; a single malformed segment takes only
-         * itself, since the rest of the mapping is still a claim about residues
-         * that exist.
+         * 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
@@ -1816,9 +2214,8 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * the structures the loaded alignment has usable mappings onto. A row can
-         * have several -- an experimental entry and a predicted model, say -- so
-         * a host that means a particular one has to name it.
+         * 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 => ({
@@ -1828,18 +2225,12 @@ function stateModelFactory() {
         },
         /**
          * #method
-         * The structure residue a row residue is, or undefined. Refusing is the
-         * point: the guess this replaces answered every query, with a wrong
-         * residue when it did not know.
+         * 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`).
          *
-         * It also refuses when the answer is not unique. A row commonly maps onto
-         * several structures -- an experimental entry and two predicted models --
-         * and returning whichever came first would be the same class of wrong,
-         * quieter. Name one with `structureId`, or use `mappedStructures` to see
-         * what there is.
-         *
-         * Positions are 1-based, as `residueMappings` and `highlights` are --
-         * note that the column helpers above take 0-based ones.
+         * 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
@@ -1869,10 +2260,10 @@ function stateModelFactory() {
         },
         /**
          * #method
-         * The row residue a structure residue is, the same lookup backwards, and
-         * refusing on the same terms. `asymId` picks between mappings onto the
-         * same entry, which a homodimer -- two rows, two chains, one id -- always
-         * needs; without it such a lookup is ambiguous and gets nothing.
+         * 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
@@ -1901,16 +2292,31 @@ function stateModelFactory() {
         .views(self => ({
         /**
          * #getter
-         * the vertical space the alignment rows actually get: the widget height
-         * less everything stacked above and below them -- the header, the tracks,
-         * and the minimap when the columns overflow. Every consumer wants this
-         * same subtraction, so there is one of it: blocksY, maxScrollY, the
-         * vertical scrollbar and fitVertically all read it, and a second getter
-         * that forgot the tracks is what put the last rows out of reach.
+         * 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 -
-                (self.showHorizontalScrollbar ? self.minimapHeight : 0) -
+                this.topBandHeight -
                 self.headerHeight -
                 this.totalTrackAreaHeight);
         },
@@ -1922,13 +2328,12 @@ function stateModelFactory() {
             return sum(self.turnedOnTracks.map(r => r.model.height));
         },
         /**
-         * one representative annotation per accession, which is what the legend,
-         * the filter dialog and the palettes key off
+         * one representative annotation per accession, for the legend, the
+         * filter dialog and the palettes
          */
         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
+            // 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)) {
@@ -1957,11 +2362,8 @@ 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
+            // 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;
         },
         /**
@@ -2008,12 +2410,20 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * most-negative allowed scrollY, keeping the last row in view rather than
-         * letting the whole alignment scroll off the top.
+         * 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 => ({
         /**
@@ -2028,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;
             }
@@ -2055,15 +2469,12 @@ function stateModelFactory() {
         /**
          * #action
          * Calculate a neighbor joining tree from the current MSA using BLOSUM62
-         * distances. Refuses above `maxNeighborJoiningRows`: the join loop is
-         * cubic and runs on the main thread, so 800 rows is a ten-second freeze
-         * with no progress and no cancel, and a tree that size wants a tool built
-         * for it anyway.
+         * distances. Throws above `maxNeighborJoiningRows`: the join loop is
+         * cubic and runs on the main thread, and 800 rows freeze the tab for ten
+         * seconds with no cancel.
          */
         calculateNeighborJoiningTreeFromMSA() {
-            // every sequence in the alignment, not the rows on screen: a collapsed
-            // clade is a display state, and building the tree from what it leaves
-            // showing drops the sequences it hides out of the result
+            // 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');
@@ -2075,10 +2486,9 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * swap in a different tree over the same alignment. Node ids are derived
-         * from the path (node-0-0-1), so a `collapsed` or `showOnly` id held over
-         * from the old tree matches a real node in the new one and folds whatever
-         * happens to sit there -- the ids go with the tree they name.
+         * 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(() => {
@@ -2143,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;
@@ -2181,13 +2594,11 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * Set the overlay annotations (an empty list clears them). Every source
-         * funnels through here after its own adapter has flattened it:
-         * InterProScan, GFF, user uploads, NCBI CDD.
+         * Set the overlay annotations (an empty list clears them). InterProScan,
+         * GFF, user uploads and NCBI CDD all arrive here as Annotation[].
          *
-         * It does not touch `showDomains`. Loading used to force the overlay on,
-         * and since a restored snapshot loads its GFF again on the way in, a link
-         * shared with the overlay hidden reopened with it drawn.
+         * Leaves `showDomains` alone, because a restored snapshot reloads its
+         * GFF and must keep a hidden overlay hidden.
          */
         setAnnotations(annotations) {
             self.annotations = annotations;
@@ -2222,6 +2633,28 @@ function stateModelFactory() {
         setColumnTracks(tracks) {
             self.columnTracks.replace(tracks);
         },
+        /**
+         * #action
+         * replace the row table, which the model keeps as the JSON string
+         * `data.treeMetadata` (see docs/layers.md)
+         */
+        setRowData(rowData) {
+            self.data.setTreeMetadata(JSON.stringify(rowData));
+        },
+        /**
+         * #action
+         * replace what the viewer's marks read from the row table
+         */
+        setEncodings(encodings) {
+            self.encodings.replace(encodings);
+        },
+        /**
+         * #action
+         * replace the panels drawn between the tree and the alignment
+         */
+        setRowPanels(panels) {
+            self.rowPanels.replace(panels);
+        },
         /**
          * #action
          * replace the alignment<->structure correspondence (see docs/layers.md)
@@ -2233,8 +2666,6 @@ function stateModelFactory() {
          * #action
          */
         toggleTrack(id) {
-            // the stored value is "is off", so the current shown state is exactly
-            // what the flipped entry should hold
             const defaultOff = self.MSA?.tracks.find(t => t.id === id)?.defaultOff;
             self.turnedOffTracks.set(id, !trackIsOff(self.turnedOffTracks, id, defaultOff));
         },
@@ -2254,18 +2685,77 @@ function stateModelFactory() {
         },
         /**
          * #getter
-         * width of the alignment canvas itself: the msa area less the vertical
-         * scrollbar sitting in it. Not usable from showHorizontalScrollbar, which
-         * feeds msaAreaHeight -> showVerticalScrollbar and would close a cycle
+         * width of the alignment canvas: the msa area less the vertical
+         * scrollbar. showHorizontalScrollbar must not read it, since that feeds
+         * msaAreaHeight -> showVerticalScrollbar and would form a cycle
          */
         get msaCanvasWidth() {
             return self.msaAreaWidth - this.verticalScrollbarWidth;
         },
+        /**
+         * #method
+         * the cell at a visible column and row index, in the coordinates a host
+         * writes highlights in
+         */
+        cellAt(visibleCol, 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],
+                };
+        },
+        /**
+         * #getter
+         * the cell under the pointer. Public API: MSAViewer's onCellHover
+         * reports it.
+         */
+        get hoveredCell() {
+            const { mouseCol, mouseRow } = self;
+            return mouseCol === undefined
+                ? undefined
+                : this.cellAt(mouseCol, mouseRow);
+        },
+        /**
+         * #getter
+         * the cell a click pinned. Public API: MSAViewer's onCellClick reports it.
+         */
+        get clickedCell() {
+            const { mouseClickCol, mouseClickRow } = self;
+            return mouseClickCol === undefined
+                ? undefined
+                : this.cellAt(mouseClickCol, mouseClickRow);
+        },
+        /**
+         * #getter
+         * the columns on screen. Public API: MSAViewer's onViewportChange reports
+         * it.
+         */
+        get viewport() {
+            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()]
@@ -2291,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
@@ -2308,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.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;
@@ -2334,14 +2921,11 @@ 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, as is one naming a row the alignment lacks.
+                    // 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) {
@@ -2354,11 +2938,10 @@ function stateModelFactory() {
                         : 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;
@@ -2388,9 +2971,6 @@ function stateModelFactory() {
             const hits = (this.domainBands.get(name) ?? [])
                 .filter(b => mouseCol >= b.startCol && mouseCol < b.endCol)
                 .map(b => b.annotation);
-            // the shared empty array, so moving the mouse across an alignment with
-            // no annotations does not hand every canvas block a new value to
-            // re-render on
             return hits.length > 0 ? hits : noDomains;
         },
         /**
@@ -2407,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;
@@ -2421,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;
@@ -2446,13 +3025,8 @@ function stateModelFactory() {
          * is dropped. Row names that match no row are ignored.
          */
         get resolvedHighlights() {
-            const { blanks, rowNamesSet, transientHighlights } = self;
-            const toVisible = (globalCol) => {
-                const visible = self.globalColToVisibleCol(globalCol);
-                return visible ?? visibleColsBefore(blanks, globalCol);
-            };
-            // the document's own highlights first, then what each owner is showing
-            // right now, so a hover draws over a persisted band rather than under it
+            const { rowNamesSet, transientHighlights } = self;
+            // persisted highlights first, so transient ones draw on top
             const all = [
                 ...self.highlights,
                 ...Object.values(transientHighlights).flat(),
@@ -2468,70 +3042,238 @@ function stateModelFactory() {
                 if (start === undefined || end === undefined) {
                     return [];
                 }
-                let startGlobal = start - 1;
-                let endGlobal = end - 1;
-                if (row !== undefined) {
-                    const rowStart = self.seqPosToGlobalCol(row, start - 1);
-                    const rowEnd = self.seqPosToGlobalCol(row, end - 1);
-                    if (rowStart === undefined || rowEnd === undefined) {
-                        return [];
+                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 = rowStart;
-                    endGlobal = rowEnd;
                 }
-                const startCol = toVisible(startGlobal);
-                const endVisible = self.globalColToVisibleCol(endGlobal);
-                const endCol = endVisible ?? visibleColsBefore(blanks, endGlobal) - 1;
-                return startCol <= endCol
-                    ? [{ ...base, startCol, endCol, rowIndices: [] }]
-                    : [];
+                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 => ({
@@ -2544,33 +3286,33 @@ 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.
          */
-        setColumnTrackHeight(id, height) {
-            self.columnTrackHeights = { ...self.columnTrackHeights, [id]: height };
+        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
-         */
-        setArcTrackHeight(arg) {
-            self.arcTrackHeight = arg;
-        },
-        /**
-         * #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++;
@@ -2596,8 +3338,8 @@ function stateModelFactory() {
         },
         /**
          * #action
-         * draw this annotation type, or stop drawing it. Only the "stop" is
-         * recorded -- see `turnedOffFeatures`
+         * show or hide an annotation type. Only hidden types are recorded; see
+         * `turnedOffFeatures`
          */
         setFilter(accession, shown) {
             if (shown) {
@@ -2611,12 +3353,8 @@ function stateModelFactory() {
          * #action
          */
         fit() {
-            // Each direction's viewport depends on the other's result: fitting the
-            // rows while the columns still overflow measures against a height the
-            // minimap is taking, and fitting the columns while the rows still
-            // overflow measures against a width the vertical scrollbar is taking.
-            // A second pass measures against the geometry the first pass produced,
-            // which is the one the reader ends up looking at.
+            // 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();
@@ -2633,29 +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);
             }
-            // 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 `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(() => {
+                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);
+                    }
+                }
+            }));
+            // 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)`);
@@ -2675,25 +3448,17 @@ 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 superseded or cleared
-             * request is also aborted, rather than left downloading a file nothing
-             * is waiting for, and it gives back the status line it was writing --
-             * a reset() mid-download used to leave "Downloading file" and a Cancel
-             * button behind on the import form.
+             * A generation guard keeps a slower superseded request from overwriting
+             * the newer one's data, status or loading flag. A superseded or cleared
+             * request is aborted and clears its status line.
              *
-             * `clearFilehandle` serves two purposes for the loaders that pass it.
-             * A local file has no URL to refetch from, so the handle is dropped
-             * once its bytes are in the model; and a fetch the user cancels drops
-             * it too, returning the view to the import form rather than leaving a
-             * stuck spinner.
+             * `clearFilehandle` runs after a local file loads, since a blob has no
+             * URL to refetch, and when the user cancels, which returns the view to
+             * the import form.
              *
-             * `what` names the layer in a failure message. An optional layer
-             * (annotations, row metadata) that fails to load is a warning: it is
-             * not worth replacing an alignment the reader is looking at with an
-             * error screen over a decorative file.
+             * `what` names the layer in a failure message. An `optional` layer
+             * (annotations, row metadata) that fails adds a warning instead of an
+             * error.
              */
             const loadOnFilehandleChange = ({ what, getFilehandle, onLoad, setLoading, clearFilehandle, optional = false, }) => {
                 let generation = 0;
@@ -2772,8 +3537,7 @@ 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,
@@ -2782,11 +3546,8 @@ function stateModelFactory() {
                     self.setTreeMetadata(text);
                 },
             });
-            // autorun parses inline gff text from data.gff. Text that goes away
-            // takes its annotations with it -- setData with a new alignment and no
-            // gff used to leave the previous file's annotations drawn over it --
-            // while annotations a host set directly are left alone, which is why
-            // this tracks what it applied instead of reading the current list
+            // 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;
@@ -2796,8 +3557,6 @@ function stateModelFactory() {
                         appliedGFF = true;
                     }
                     catch (e) {
-                        // a malformed overlay is not worth replacing the alignment
-                        // with an error screen
                         console.error(e);
                         self.addWarning(`The annotations did not parse: ${e}`);
                     }
@@ -2807,9 +3566,7 @@ function stateModelFactory() {
                     self.setAnnotations([]);
                 }
             }));
-            // gffFilehandle carries overlay annotations. It loads into data.gff and
-            // the autorun above parses it, so there is one parse path whether the
-            // text arrived from a file or from a snapshot
+            // gffFilehandle loads into data.gff, which the autorun above parses
             loadOnFilehandleChange({
                 what: 'annotations',
                 optional: true,
@@ -2834,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
@@ -2864,25 +3614,20 @@ 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);
                 }
             }));
-            // treeWidth trails the tree area, less whatever the labels take out of
-            // it. A width that arrived with the snapshot is left alone until the
-            // tree area itself moves: a host that opens a view with a narrow tree
-            // beside wide labels -- jbrowse-plugin-msaview does, at treeWidth 100
-            // in a 200px area -- had its value overwritten on the first frame, and
-            // a restored session came back re-derived rather than as it was left.
-            // A getter cannot do this: labelsWidth is measured off the leaves,
-            // which are laid out against treeWidth.
+            // treeWidth follows the tree area less the labels. A non-default
+            // snapshot treeWidth (jbrowse-plugin-msaview opens at 100 in a 200px
+            // area) is kept until the tree area changes. Not a getter, because
+            // labelsWidth is measured off leaves laid out against treeWidth.
             let pinnedAreaWidth = self.treeWidth === defaultTreeWidth ? undefined : self.treeAreaWidth;
             addDisposer(self, autorun(() => {
                 const areaWidth = self.treeAreaWidth;
@@ -2891,14 +3636,17 @@ function stateModelFactory() {
                     return;
                 }
                 pinnedAreaWidth = undefined;
-                self.setTreeWidth(Math.max(50, areaWidth - labelsWidth - 10 - self.marginLeft));
+                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: {