archaeopteryx 3.9.0 → 3.11.0

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.9.0
+// v 3.11.0
 // 2026-09-17
 //
 // Archaeopteryx.js is a software tool for the visualization and
@@ -103,7 +103,7 @@ function (root, d3, forester, phyloXml) {
     // IIFE's own function name -- a plain object says what it is.)
     let archaeopteryx = {};
 
-    const VERSION = '3.9.0';
+    const VERSION = '3.11.0';
     const WEBSITE = 'https://cmzmasek.github.io/archaeopteryx-js/';
     const DESKTOP_WEBSITE = 'https://cmzmasek.github.io/archaeopteryx/';
     const SOURCE_WEBSITE = 'https://github.com/cmzmasek/archaeopteryx-js';
@@ -363,6 +363,11 @@ function (root, d3, forester, phyloXml) {
     const DOWNLOAD_BUTTON = 'dl_b';
     const DYNAHIDE_CB = 'dynahide_cb';
     const MSA_CB = 'msa_cb';
+    const HEATMAP_CB = 'heatmap_cb';
+    const HEATMAP_CONTROLS = 'heatmap_controls';
+    const HEATMAP_ORDER_SELECT = 'heatmap_order';
+    const HEATMAP_REORDER_BUTTON = 'heatmap_reorder';
+    const HEATMAP_REORDER_DIALOG = 'heatmap_reorder_dialog';
     const DOMAINS_CB = 'domains_cb';
     const DOMAIN_CONTROLS = 'domain_controls';
     const DOMAIN_WIDTH_DEC = 'domain_width_dec';
@@ -404,6 +409,9 @@ function (root, d3, forester, phyloXml) {
     const PHYLOGRAM_ALIGNED_BUTTON = 'phya_b';
     const PHYLOGRAM_BUTTON = 'phy_b';
     const PHYLOGRAM_CLADOGRAM_CONTROLGROUP = 'phy_cla_g';
+    const BRANCH_SCALE_CONTROLGROUP = 'branch_scale_g';
+    const BRANCH_SCALE_TIME_BUTTON = 'branch_scale_time_b';
+    const BRANCH_SCALE_DIV_BUTTON = 'branch_scale_div_b';
     const ABOUT_DIALOG = 'aptx_about';
     const PROG_NAME = 'progname';
     const PROGNAMELINK = 'prognamelink';
@@ -569,14 +577,51 @@ function (root, d3, forester, phyloXml) {
     const DOMAIN_LABEL_MODES = ['none', 'domains', 'legend'];
     let _domain = null;                   // {width, palette, next, legendFrac}, set per launch
     let _domainReserve = 0;               // horizontal px reserved for the tracks, set with _w
+    // ------ heat map (the desktop's MATRIX annotation columns) ------
+    const HEATMAP_TRACK_GAP = 8;          // px between what is left of the tree and the matrix
+    const HEATMAP_PREF_COL_W = 14;        // a column never grows past this
+    const HEATMAP_MIN_COL_W = 3;          // ... nor shrinks below it: past that the matrix is windowed
+    const HEATMAP_MIN_BAND_PX = 60;       // the window never shrinks below this
+    const HEATMAP_MAX_VIEWPORT_FRACTION = 0.45;  // nor grows past this share of the display
+    const HEATMAP_MIN_TREE_PX = 220;      // the tree itself never shrinks below this
+    const HEATMAP_MIN_COLUMNS = 2;        // one column is a stripe, not a matrix: the toggle is not offered
+    const HEATMAP_LABEL_MAX_PX = 96;      // a turned column label is clipped to this
+    const HEATMAP_LABEL_MIN_COL_W = 7;    // ... and dropped where the columns are thinner than this
+    const HEATMAP_SCALE_BAR_W = 148;      // the gradient in the legend
+    const HEATMAP_SCALE_BAR_H = 8;
+    const HEATMAP_SCALE_RESERVE = 30;     // vertical room for that legend and its numbers
+    const HEATMAP_HEAD_GAP = 5;           // between the last row and the turned labels
+    const HEATMAP_NOT_ASSESSED = 'not assessed';   // what a blank cell says -- it does NOT say zero
+    const HEATMAP_RADIAL_GAP = 7;         // px from the label ring to the first column ring
+    const HEATMAP_RADIAL_END_GAP = 8;     // ... and kept free past the last one
+    const HEATMAP_RADIAL_MAX_FRACTION = 1.2;      // the ring stack, against the tree's own radius
+    const HEATMAP_RADIAL_MIN_RING = 1;            // a ring never thinner than this
+    const HEATMAP_RADIAL_MIN_NAMED_RING = 7;      // ... nor named when it is thinner than this
+    // Neighbouring sectors OVERLAP by this much rather than meeting exactly.
+    // Two antialiased edges that share a coordinate each cover about half the
+    // boundary pixel, and a half over a half does not composite back to a
+    // solid edge -- it leaves the background showing through as a dotted
+    // line all round the rings. Measured on the sparse demo: 6987 pixels
+    // within 1.2px of a ring boundary came out background-coloured.
+    const HEATMAP_RING_BLEED = 1.2;
+    const HEATMAP_BLANK = 'blank';        // the run-merger's stand-in for a cell nobody filled in
+    const HEATMAP_DENDRO_GAP = 5;         // px between the dendrogram's leaves and the first row
+    const HEATMAP_DENDRO_MIN_BAND = 24;   // the band it is drawn in, from the label font
+    const HEATMAP_DENDRO_MAX_BAND = 72;
+    let _heatmapReserve = 0;              // horizontal px reserved for the matrix, set with _w
+    let _heatmapModel = null;             // forester.heatmapColumns of the WHOLE tree, cached per launch
+    let _heatmapColor = null;             // the one scale every column is painted on
+    let _heatmapColOffset = 0;            // first shown column, while the matrix is windowed
+    let _heatmapGeom = null;              // the last draw's geometry, for the hover readout
     // ------ time axis (the desktop's geologic / calendar overlays) ------
     const TIME_GEO_RESERVE = 52;          // two ICS band rows + the Ma ruler
     const TIME_CAL_RESERVE = 26;          // the calendar year ruler
     const TIME_BAND_ROW_H = 13;
-    const HPD_BAR_COLOR = 'rgba(70,130,220,0.35)';    // translucent blue, FigTree-like
+    const HPD_BAR_COLOR = 'rgba(70,130,220,0.35)';    // translucent blue, the usual HPD tint
     const FOSSIL_BAR_COLOR = 'rgba(150,100,55,0.86)'; // opaque-ish sepia
     let _timeInfo = null;                 // forester.timeAxisInfo, recomputed per render
     let _timeTree = false;                // forester.isTimeTree: never re-rooted
+    let _branchScaleAvailable = false;    // the tree states time AND divergence, so the switch is offered
     let _clusterH = 0;                    // the cluster layout's vertical extent, set per render
     let _docListenersBound = false;       // page-level key/wheel handlers bind once, not per launch
     let _docListeners = [];               // ...and destroy() can take every one of them down again
@@ -1098,6 +1143,7 @@ function (root, d3, forester, phyloXml) {
         // view=[-254,-10 1497x800] with rootOffset=254, so "does it fit" said
         // no by precisely 254px and the overview appeared after every Fit.
         maxX += calcMaxTreeLengthForDisplay() - _settings.rootOffset + _domainReserve;
+        minY -= heatmapTopReserve();   // the dendrogram band stands above the first row
         if (scaleBarShown()) {
             maxY += SCALE_BAR_RESERVE;   // the bar sits under the last row
         }
@@ -1422,6 +1468,30 @@ function (root, d3, forester, phyloXml) {
             .style('opacity', 0.95); // only the fade -- the rest is set at creation
     }
 
+    // Puts a hover readout beside the pointer -- to its right and below --
+    // flipping to the other side when that would leave the window. The readout's
+    // OWN measured size decides, because .aptx-tip is width:max-content and so
+    // is as wide as whatever it happens to be saying. Guessing instead, with a
+    // fixed shift, left a 181px readout floating a hundred pixels clear of the
+    // cell it described; a matrix that hugs the right edge flips on every cell,
+    // so the guess was what the reader saw every time.
+    const HOVER_READOUT_GAP = 14;
+
+    function placeHoverReadout(el, event) {
+        let w = el.offsetWidth;
+        let h = el.offsetHeight;
+        let left = event.pageX + HOVER_READOUT_GAP;
+        if ((left + w) > (window.scrollX + window.innerWidth)) {
+            left = Math.max(window.scrollX + 2, event.pageX - HOVER_READOUT_GAP - w);
+        }
+        let top = event.pageY + HOVER_READOUT_GAP;
+        if ((top + h) > (window.scrollY + window.innerHeight)) {
+            top = Math.max(window.scrollY + 2, event.pageY - HOVER_READOUT_GAP - h);
+        }
+        el.style.left = left + 'px';
+        el.style.top = top + 'px';
+    }
+
     function mousemove(event, d) {
 
         let mo_text = nodeDataText(d);
@@ -1432,10 +1502,8 @@ function (root, d3, forester, phyloXml) {
         if (_panelTheme) {
             tip.classList.add('aptx-' + _panelTheme);
         }
-        _node_mouseover_div
-            .html(markUpDataLabels(escapeHtmlKeepBreaks(mo_text)))
-            .style('left', (event.pageX + 14) + 'px')
-            .style('top', (event.pageY + 14) + 'px');
+        _node_mouseover_div.html(markUpDataLabels(escapeHtmlKeepBreaks(mo_text)));
+        placeHoverReadout(tip, event);   // this one used to run off the edge instead
     }
 
     // ----------------------------
@@ -2727,6 +2795,22 @@ function (root, d3, forester, phyloXml) {
             _msaReserve = 0;
             // and the domain tracks reserve their column past the labels
             _domainReserve = domainReserve();
+            // The heat map is budgeted FIRST of the two right-hand tracks: it
+            // wants a fixed, finite width (its columns at their preferred size
+            // and no more), while the alignment's band is a WINDOW that scrolls
+            // and so can give way without losing anything. Budgeting the
+            // alignment first left an 18-column matrix a 60px sliver.
+            _heatmapReserve = 0;
+            if (heatmapShown() && !radialDisplay()) {
+                let cols = heatmapModel().refs.length;
+                let vp0 = svgSize();
+                let vw0 = Math.min(_displayWidth, (vp0 && vp0.w) ? vp0.w : _displayWidth);
+                let hband = Math.max(HEATMAP_MIN_BAND_PX, Math.round(vw0 * HEATMAP_MAX_VIEWPORT_FRACTION));
+                let hmax = _displayWidth - calcMaxTreeLengthForDisplay() - _domainReserve
+                    - HEATMAP_TRACK_GAP - HEATMAP_MIN_TREE_PX;
+                hband = Math.max(HEATMAP_MIN_BAND_PX, Math.min(hband, hmax));
+                _heatmapReserve = HEATMAP_TRACK_GAP + Math.min(cols * HEATMAP_PREF_COL_W, hband);
+            }
             if (msaShown()) {
                 let fullPx = _basicTreeProperties.maxMolSeqLength * MSA_COL_WIDTH;
                 // budgeted from the VIEWPORT: sizing it from the zoomed layout
@@ -2737,11 +2821,12 @@ function (root, d3, forester, phyloXml) {
                 let band = Math.max(MSA_MIN_BAND_PX, Math.round(vw * MSA_MAX_VIEWPORT_FRACTION));
                 // a wide alignment must not squeeze the tree itself away: the
                 // band yields until the tree keeps its minimum share
-                let maxBand = _displayWidth - calcMaxTreeLengthForDisplay() - _domainReserve - MSA_TRACK_GAP - MSA_MIN_TREE_PX;
+                let maxBand = _displayWidth - calcMaxTreeLengthForDisplay() - _domainReserve
+                    - _heatmapReserve - MSA_TRACK_GAP - MSA_MIN_TREE_PX;
                 band = Math.max(MSA_MIN_BAND_PX, Math.min(band, maxBand));
                 _msaReserve = MSA_TRACK_GAP + Math.min(fullPx, band);
             }
-            _w = _displayWidth - calcMaxTreeLengthForDisplay() - _msaReserve - _domainReserve;
+            _w = _displayWidth - calcMaxTreeLengthForDisplay() - _msaReserve - _domainReserve - _heatmapReserve;
             if (_w < 1) {
                 _w = 1;
             }
@@ -2753,7 +2838,8 @@ function (root, d3, forester, phyloXml) {
 
         _clusterH = Math.max(40, _displayHeight - (2 * TOP_AND_BOTTOM_BORDER_HEIGHT)
             - bottomOverlayReserve());
-        _treeFn = _treeFn.size([_clusterH, _w]);
+        let _topReserve = topOverlayReserve();
+        _treeFn = _treeFn.size([Math.max(20, _clusterH - _topReserve), _w]);
 
         // A collapsed clade is a leaf that asks for more than one row: the
         // separation between neighbouring leaves is the mean of their
@@ -2776,7 +2862,7 @@ function (root, d3, forester, phyloXml) {
         });
         _treeFn(hierarchy);
         hierarchy.each(function (hn) {
-            hn.data.x = hn.x;
+            hn.data.x = hn.x + _topReserve;
             hn.data.y = hn.y;
             hn.data.depth = hn.depth;
         });
@@ -3266,7 +3352,7 @@ function (root, d3, forester, phyloXml) {
         }
 
         // circular: a thin dashed connector from each external node out to the
-        // common label ring (so labels line up like iTOL's aligned display).
+        // common label ring, so every label lines up at the same radius.
         _svgGroup.selectAll('g.aptx-radial-conn').remove();
         if (_state.circularDisplay) {
             // tips while their labels show; a collapsed clade always (its label
@@ -3312,6 +3398,7 @@ function (root, d3, forester, phyloXml) {
         drawDomainArchitectures();
         drawDomainLegend();
         drawMsaTrack();
+        drawHeatmapTrack();
         drawTimeOverlays();
         rebuildOverview(); // measured AFTER the overlays, so the bbox is this frame's
         updateSearchHitNavigation();
@@ -4840,6 +4927,9 @@ function (root, d3, forester, phyloXml) {
     const STATE_KEYS = [
         'layout',
         'showMsa',
+        'showHeatmap',
+        'heatmapColumnOrder',
+        'heatmapManualOrder',
         'showDomainArchitectures',
         'domainLabels',
         'domainGlow',
@@ -5072,6 +5162,39 @@ function (root, d3, forester, phyloXml) {
             _state.showMsa = _basicTreeProperties.alignedMolSeqs === true
                 && _basicTreeProperties.maxMolSeqLength > 0;
         }
+        // The heat map is offered whenever the tree carries two or more
+        // numeric per-tip fields, which is common enough that turning it on
+        // by itself would be an opinion about the tree rather than a service
+        // -- the alignment track, by contrast, is on when there IS one.
+        if (_state.showHeatmap === undefined) {
+            _state.showHeatmap = false;
+        }
+        // The columns' order. Left unset it is resolved from the data on first
+        // use (heatmapMode / forester.heatmapDefaultOrder): a clustered order,
+        // because reading block structure is what a heat map beside a tree is
+        // FOR, with the distance chosen by what the values are. An explicit
+        // value always wins and is never re-derived -- including 'document',
+        // which keeps the order the producer wrote the fields in.
+        if (_state.heatmapColumnOrder === undefined) {
+            _state.heatmapColumnOrder = null;
+        } else if (_state.heatmapColumnOrder !== null
+            && forester.HEATMAP_ORDER_MODES.indexOf(_state.heatmapColumnOrder) < 0) {
+            throw new Error(ERROR + '"heatmapColumnOrder" must be one of '
+                + forester.HEATMAP_ORDER_MODES.join(', '));
+        }
+        // The reader's own arrangement, as a list of refs. It is only read
+        // while the order is 'manual', and a ref it names that the tree has
+        // not got is ignored rather than fatal -- an order outliving one of
+        // its columns is ordinary (see forester.heatmapManualOrder).
+        if (_state.heatmapManualOrder === undefined) {
+            _state.heatmapManualOrder = null;
+        } else if (_state.heatmapManualOrder !== null
+            && !(Array.isArray(_state.heatmapManualOrder)
+                && _state.heatmapManualOrder.every(function (r) {
+                    return typeof r === 'string';
+                }))) {
+            throw new Error(ERROR + '"heatmapManualOrder" must be an array of property refs');
+        }
         // A tree with protein domain architectures on its tips draws them
         // from the start (the desktop switches its toggle on at load), again
         // unless the caller decided. The track width is set at the first
@@ -5111,6 +5234,12 @@ function (root, d3, forester, phyloXml) {
         // showTimeAxis explicitly.
         _timeInfo = _treeData ? forester.timeAxisInfo(forester.getTreeRoot(_treeData)) : null;
         _timeTree = _treeData ? forester.isTimeTree(_treeData) : false;
+        // Whether this tree says two different things -- when its nodes sit in
+        // time AND its branches measure something else -- and which of the two
+        // it arrived showing. An Auspice build arrives in the time view; a
+        // BEAST or Newick file arrives stating its own branch lengths.
+        _branchScaleAvailable = _treeData ? forester.hasTimeAndDivergence(_treeData) : false;
+        _state.branchScale = _treeData ? forester.branchLengthScale(_treeData) : 'divergence';
         if (_state.showTimeAxis === undefined) {
             _state.showTimeAxis = !!(_timeInfo && _timeInfo.type);
         }
@@ -5651,6 +5780,14 @@ function (root, d3, forester, phyloXml) {
         // and a tree whose dates carry a unit is never touched. The desktop
         // converts at the same point, next to its internal-label policy
         // (their HeightDateConverter, 0.11.151).
+        // Each node's cumulative divergence is recorded from the branch
+        // lengths AS LOADED, before anything rewrites them, so the time <->
+        // divergence switch is reversible rather than one-way. Auspice states
+        // divergence outright (nextstrain:div) and is unaffected; every other
+        // tree states it as its branch lengths, which the time view overwrites.
+        trees.forEach(function (t) {
+            forester.captureDivergence(t);
+        });
         forester.convertLoadedHeightsToDates(trees);
         // the two view keys are checked up here with the other arguments,
         // before anything is touched (and where Node can test it)
@@ -5711,6 +5848,10 @@ function (root, d3, forester, phyloXml) {
         _radialRotation = 0;
         _radialLabelsHorizontal = false;
         _msaColOffset = 0;
+        _heatmapColOffset = 0;
+        _heatmapModel = null;   // the columns and the scale belong to THIS tree
+        _heatmapColor = null;
+        _heatmapGeom = null;
         // ---- synchronous: everything that can throw, and the cheap setup --
         //
         // initializeSettings validates values and throws on a bad one, so it
@@ -6445,6 +6586,10 @@ function (root, d3, forester, phyloXml) {
         if (edited && _domain) {
             _domain.palette = null;   // the tree changed: the domain names are dealt their colours again
         }
+        if (edited) {
+            _heatmapModel = null;     // ... and the heat map's columns and scale are derived from it again
+            _heatmapColor = null;
+        }
         if (!_vis) {
             return;
         }
@@ -6483,8 +6628,10 @@ function (root, d3, forester, phyloXml) {
         // part of the real spans (an anchor ratio taken from anything else
         // once flung the whole tree off-screen after three X+ presses).
         return {
-            horizontal: Math.max(1, _displayWidth - calcMaxTreeLengthForDisplay() - _msaReserve - _domainReserve),
-            vertical: Math.max(40, _displayHeight - (2 * TOP_AND_BOTTOM_BORDER_HEIGHT) - bottomOverlayReserve())
+            horizontal: Math.max(1, _displayWidth - calcMaxTreeLengthForDisplay() - _msaReserve
+                - _domainReserve - _heatmapReserve),
+            vertical: Math.max(40, _displayHeight - (2 * TOP_AND_BOTTOM_BORDER_HEIGHT)
+                - bottomOverlayReserve() - topOverlayReserve())
         };
     }
 
@@ -7196,13 +7343,8 @@ function (root, d3, forester, phyloXml) {
         if (_panelTheme) {
             tip_el.classList.add('aptx-' + _panelTheme);
         }
-        // the track hugs the right edge, so the readout flips to the left
-        // of the pointer when it would otherwise run off the window
-        let left = (event.pageX + 290) > window.innerWidth ? (event.pageX - 280) : (event.pageX + 14);
-        _node_mouseover_div
-            .html(markUpDataLabels(escapeHtmlKeepBreaks(txt)))
-            .style('left', left + 'px')
-            .style('top', (event.pageY + 14) + 'px');
+        _node_mouseover_div.html(markUpDataLabels(escapeHtmlKeepBreaks(txt)));
+        placeHoverReadout(tip_el, event);
         _node_mouseover_div.transition().duration(100).style('opacity', 0.95);
     }
 
@@ -7215,6 +7357,1084 @@ function (root, d3, forester, phyloXml) {
         scheduleUpdate(null, 0);
     }
 
+    // ===================== Heat map =====================
+    // The desktop's MATRIX annotation columns: one cell per (tip, numeric
+    // per-tip property) to the right of the labels, every column painted on
+    // ONE colour scale so that a cell can be read across columns -- the
+    // matrix half of a clustergram.
+    //
+    // Which refs are columns, the order they take and what the scale spans
+    // are forester.heatmapColumns, derived once over the WHOLE tree:
+    // candidacy is decided on the tree, never per view, so diving into a
+    // subtree narrows the rows and leaves the columns and the scale alone.
+    // A colour therefore means the same number in every view.
+    //
+    // A cell nobody filled in is never painted as the scale's low end: on a
+    // presence/absence matrix that would state the opposite of what the file
+    // says. It is drawn as an OUTLINED empty box, with a key beside the scale
+    // -- leaving it bare is not enough, see the measurement at the draw.
+    //
+    // Rectangular and CIRCULAR: the columns stand on the tips' common edge,
+    // which a circular fan has as a ring (drawHeatmapRings) and an unrooted one
+    // has not got at all -- every tip there ends at its own radius.
+
+    function heatmapModel() {
+        if (!_heatmapModel && _treeData) {
+            _heatmapModel = forester.heatmapColumns(_treeData);
+        }
+        return _heatmapModel;
+    }
+
+    // Offered when the tree holds at least two numeric per-tip refs that
+    // actually carry values: one column is a stripe rather than a matrix,
+    // and a scale needs something to span.
+    function heatmapAvailable() {
+        let m = heatmapModel();
+        return !!m && m.refs.length >= HEATMAP_MIN_COLUMNS && m.min !== null && m.max !== null;
+    }
+
+    // Circular draws the columns as RINGS (drawHeatmapRings); unrooted cannot,
+    // because its tips end at different radii so a column has no ring to be.
+    function heatmapShown() {
+        return _state.showHeatmap === true && _state.unrootedDisplay !== true && heatmapAvailable();
+    }
+
+    // The one scale, spanning the whole tree's values. Built lazily and kept
+    // with the model, so every redraw and every view paints the same colours.
+    function heatmapColorOf(v) {
+        let m = heatmapModel();
+        if (!m || v === null) {
+            return null;
+        }
+        if (!_heatmapColor) {
+            _heatmapColor = (m.max > m.min)
+                ? d3.scaleLinear().range(VIS_COLOR_RAMP).domain([m.min, (m.min + m.max) / 2, m.max])
+                : function () {
+                    // one value everywhere: a flat matrix, not a gradient
+                    // over a zero-width domain (which d3 maps to its last stop)
+                    return VIS_COLOR_RAMP[1];
+                };
+        }
+        return _heatmapColor(v);
+    }
+
+    // Enough digits to tell two cells apart, without a tail of noise on data
+    // that is plainly integral.
+    function heatmapNum(v) {
+        if (v === null || v === undefined) {
+            return '';
+        }
+        if (v !== 0 && (Math.abs(v) >= 100000 || Math.abs(v) < 0.001)) {
+            return v.toExponential(2);
+        }
+        return String(Math.round(v * 1000) / 1000);
+    }
+
+    // A column is as wide as the band allows, never wider than is useful and
+    // never thinner than is legible -- past that the matrix is windowed and
+    // scrolled, as a long alignment is.
+    function heatmapColWidth() {
+        let m = heatmapModel();
+        if (!m || m.refs.length < 1) {
+            return HEATMAP_PREF_COL_W;
+        }
+        let band = Math.max(1, _heatmapReserve - HEATMAP_TRACK_GAP);
+        return Math.max(HEATMAP_MIN_COL_W, Math.min(HEATMAP_PREF_COL_W, band / m.refs.length));
+    }
+
+    function heatmapLabelsFit() {
+        return heatmapColWidth() >= HEATMAP_LABEL_MIN_COL_W;
+    }
+
+    function heatmapLabelFont() {
+        return Math.max(7, Math.min(11, Math.round(heatmapColWidth()))) + 'px ' + FONT_DEFAULTS;
+    }
+
+    // The turned column labels' band: the longest label, clipped. Asked for
+    // before the draw (bottomOverlayReserve sizes the layout with it), so it
+    // is derived from the model and the reserve, never from the drawing.
+    function heatmapHeadHeight() {
+        if (!heatmapLabelsFit()) {
+            return 0;
+        }
+        let font = heatmapLabelFont();
+        let w = 0;
+        heatmapModel().refs.forEach(function (r) {
+            w = Math.max(w, legendTextWidth(r.label, font));
+        });
+        return Math.ceil(Math.min(w, HEATMAP_LABEL_MAX_PX));
+    }
+
+    // What the strip actually paints: the turned names and the scale.
+    function heatmapStripHeight() {
+        return HEATMAP_HEAD_GAP + heatmapHeadHeight() + HEATMAP_SCALE_RESERVE;
+    }
+
+    // What the layout keeps clear for it. The alignment's navigation bar is
+    // fixed at the viewport bottom and would cover whatever ends under it, so
+    // when that bar is out the strip has to end above it -- as the alignment's
+    // own strip does (MSA_NAV_RESERVE).
+    function heatmapBottomReserve() {
+        if (!heatmapShown() || radialDisplay()) {
+            return 0;   // the rings carry their own names and legend
+        }
+        return heatmapStripHeight() + (msaShown() ? MSA_NAV_RESERVE : 0);
+    }
+
+    // The mode in force: what the caller or the reader chose, else the one the
+    // data asks for.
+    //
+    // The resolved choice is cached on the MODEL, which is where it belongs --
+    // it is a fact about this tree's values and it dies with them. It is not
+    // written back into _state, but not because _state would leak it: every
+    // launch AND every tree switch rebuilds _state from the original config
+    // (switchToTree -> launchInto -> initializeState), so a write-back could
+    // not reach the next tree. Checked, because the comment that used to sit
+    // here claimed exactly that protection and it would have been fiction.
+    function heatmapMode() {
+        if (_state.heatmapColumnOrder) {
+            return _state.heatmapColumnOrder;
+        }
+        let m = heatmapModel();
+        if (!m) {
+            return 'document';
+        }
+        if (!m._autoMode) {
+            m._autoMode = forester.heatmapDefaultOrder(_treeData, m.refs);
+        }
+        return m._autoMode;
+    }
+
+    // How far this tree's own tips agree about the column order (cached with
+    // the model, since it is a fact about the same values).
+    function heatmapInputAgreement() {
+        let m = heatmapModel();
+        if (!m) {
+            return null;
+        }
+        if (!m._agreement) {
+            m._agreement = forester.heatmapInputOrderAgreement(_treeData, m.refs);
+        }
+        return m._agreement;
+    }
+
+    // The columns in the order the reader asked for, with the dendrogram
+    // behind that order when the order came from a clustering.
+    function heatmapOrdered() {
+        let m = heatmapModel();
+        if (!m) {
+            return null;
+        }
+        let mode = heatmapMode();
+        // The order is kept ON the model, not in a cache beside it. The
+        // desktop's equivalent was keyed on (refs, mode) and a subtree, an
+        // edit or a re-import changes the VALUES while leaving both alone, so
+        // a hit handed back an order of the old data and a dendrogram drawn
+        // over the new -- found by code review, fixed there by invalidating at
+        // the one place every such path goes through. Hanging it on the model
+        // makes that structural instead: whatever drops the model drops this
+        // with it, and there is no second thing to remember to clear.
+        // the manual list is part of the key: it changes while the mode
+        // stays 'manual', and a cache blind to that would redraw the old
+        // arrangement after every move
+        let manual = _state.heatmapManualOrder;
+        if (!m._order || m._order.mode !== mode || m._order.manual !== manual) {
+            let o = forester.heatmapOrder(_treeData, m.refs, mode, manual);
+            m._order = {mode: mode, manual: manual, columns: o.columns, dendrogram: o.dendrogram};
+        }
+        return m._order;
+    }
+
+    // How many columns the band can hold: every column when they fit, a window
+    // otherwise. Derived from the reserve, which update() sets before it asks
+    // for either overlay reserve, so the draw and the layout agree.
+    function heatmapVisibleColumns() {
+        let m = heatmapModel();
+        if (!m || m.refs.length < 1) {
+            return 0;
+        }
+        let bandPx = Math.max(1, _heatmapReserve - HEATMAP_TRACK_GAP);
+        let visible = Math.max(1, Math.min(m.refs.length, Math.floor(bandPx / heatmapColWidth())));
+        return isFinite(visible) ? visible : 0;
+    }
+
+    // The dendrogram to draw, or null. A WINDOWED matrix gets none: the tree
+    // describes every column, and drawn over some of them its merges would
+    // reach columns that are not on screen -- a picture asserting a grouping
+    // the reader cannot see.
+    function heatmapDendrogram() {
+        if (!heatmapShown() || radialDisplay()) {
+            return null;   // a dendrogram over a ring would have to bend; it earns nothing
+        }
+        let o = heatmapOrdered();
+        if (!o || !o.dendrogram || o.columns.length < 3) {
+            return null;
+        }
+        return (heatmapVisibleColumns() === o.columns.length) ? o.dendrogram : null;
+    }
+
+    // Deliberately short: a shape to read a grouping off, not a scale anyone
+    // reads a number from.
+    function heatmapDendroBand() {
+        return Math.max(HEATMAP_DENDRO_MIN_BAND,
+            Math.min(HEATMAP_DENDRO_MAX_BAND, 3 * (_state.externalNodeFontSize + 2)));
+    }
+
+    // Vertical room kept ABOVE the first row for the dendrogram. The band is
+    // drawn at negative y, with the tree's own group, so it zooms and pans
+    // with the cells it belongs to; the layout just has to leave it the space
+    // and the fit has to start below it.
+    function heatmapTopReserve() {
+        return heatmapDendrogram() ? (heatmapDendroBand() + HEATMAP_DENDRO_GAP) : 0;
+    }
+
+    function topOverlayReserve() {
+        return heatmapTopReserve();
+    }
+
+    function drawHeatmapTrack() {
+        if (!_svgGroup) {
+            return;
+        }
+        _svgGroup.selectAll('g.aptx-heatmap').remove();
+        if (_baseSvg) {
+            _baseSvg.selectAll('g.aptx-heatmap-ringlegend').remove();
+        }
+        if (_floatGroup) {
+            _floatGroup.selectAll('g.aptx-heatmap-strip').remove();
+            delete _floatStrips['aptx-heatmap-strip'];
+        }
+        if (!heatmapShown() || !_root) {
+            _heatmapGeom = null;
+            return;
+        }
+        if (heatmapCircular()) {
+            drawHeatmapRings();
+            drawHeatmapRingLegend();
+            return;
+        }
+        let model = heatmapModel();
+        let ordered = heatmapOrdered();
+        let columns = ordered ? ordered.columns : model.refs;
+        let tips = displayedTips().filter(function (d) {
+            return d.x !== undefined;
+        }).sort(function (p, q) {
+            return p.x - q.x;
+        });
+        let total = columns.length;
+        if (tips.length < 1 || total < 1) {
+            _heatmapGeom = null;
+            return;
+        }
+        let cw = heatmapColWidth();
+        let bandPx = Math.max(1, _heatmapReserve - HEATMAP_TRACK_GAP);
+        let visible = Math.max(1, Math.min(total, Math.floor(bandPx / cw)));
+        if (!isFinite(visible)) {
+            // half-initialized globals (mid-launch) can make the window NaN;
+            // draw nothing rather than feeding it downstream
+            _heatmapGeom = null;
+            return;
+        }
+        let maxOffset = Math.max(0, total - visible);
+        if (_heatmapColOffset > maxOffset) {
+            _heatmapColOffset = maxOffset;
+        }
+        if (_heatmapColOffset < 0) {
+            _heatmapColOffset = 0;
+        }
+        let offset = _heatmapColOffset;
+        // The matrix ends where the alignment track begins, or at the canvas
+        // edge when there is none: the fitted view has shifted the layout
+        // right by rootOffset, and both reserves were taken off _w already.
+        let originX = _displayWidth - _settings.rootOffset - _msaReserve - _heatmapReserve + HEATMAP_TRACK_GAP;
+        let g = _svgGroup.append('g').attr('class', 'aptx-heatmap');
+        let ink = _state.branchColorDefault;
+
+        // Row bands: each shared boundary derived ONCE, as the midpoint
+        // between adjacent tip rows -- deriving it per row from y +- half a
+        // row height rounds a pixel apart and paints a seam across the grid.
+        let n = tips.length;
+        let pad = n > 1 ? ((tips[n - 1].x - tips[0].x) / (n - 1)) / 2
+            : Math.max(4, _state.externalNodeFontSize / 2);
+        let bounds = new Array(n + 1);
+        bounds[0] = Math.max(0, tips[0].x - pad);
+        for (let r = 1; r < n; ++r) {
+            bounds[r] = (tips[r - 1].x + tips[r].x) / 2;
+        }
+        bounds[n] = Math.min(_clusterH, tips[n - 1].x + pad);
+
+        // A cell nobody filled in is drawn in the background colour and OUTLINED.
+        // Leaving it bare is not enough: measured on the sparse demo, a bare
+        // blank stands at a contrast ratio of 13.4 against the scale's low end
+        // in the light theme but 1.08 in the dark one -- that is to say, in the
+        // dark theme "not assessed" and "zero" were the same picture, which is
+        // the one confusion this whole design exists to prevent.
+        let blanks = 0;
+        // Blanks merge into one outlined band only where a cell is too narrow
+        // to outline anyway: at a readable column width a run of them must stay
+        // a run of CELLS, or its top and bottom edges read as a drawn rule
+        // across the matrix rather than as missing data.
+        let mergeBlanks = cw < HEATMAP_LABEL_MIN_COL_W;
+        for (let r = 0; r < n; ++r) {
+            let d = tips[r];
+            let cy = Math.round(bounds[r]);
+            let rh = Math.max(1, Math.round(bounds[r + 1]) - cy);
+            // consecutive cells of the SAME colour merge into one rect: on a
+            // presence/absence matrix that is most of them, and it is what
+            // keeps a wide matrix drawable
+            let runStart = -1;
+            let runFill = null;
+            let flush = function (endI) {
+                if (runStart < 0) {
+                    return;
+                }
+                let x0 = Math.round(originX + (runStart * cw));
+                let x1 = Math.round(originX + (endI * cw));
+                let rect = g.append('rect').attr('x', x0).attr('y', cy)
+                    .attr('width', Math.max(1, x1 - x0)).attr('height', rh);
+                if (runFill === HEATMAP_BLANK) {
+                    rect.attr('fill', _state.backgroundColorDefault)
+                        .attr('stroke', ink).attr('stroke-opacity', 0.45).attr('stroke-width', 1);
+                } else {
+                    rect.attr('fill', runFill);
+                }
+                runStart = -1;
+                runFill = null;
+            };
+            for (let i = 0; i < visible; ++i) {
+                let v = forester.heatmapValue(d, columns[offset + i].ref);
+                let fill = (v === null) ? HEATMAP_BLANK : heatmapColorOf(v);
+                if (fill === HEATMAP_BLANK) {
+                    blanks++;
+                }
+                if (runFill === fill && (mergeBlanks || fill !== HEATMAP_BLANK)) {
+                    continue;   // the run extends
+                }
+                flush(i);
+                runStart = i;
+                runFill = fill;
+            }
+            flush(visible);
+        }
+
+        let rowsTop = Math.round(bounds[0]);
+        let rowsBottom = Math.round(bounds[n]);
+        let trackW = Math.round(originX + (visible * cw)) - Math.round(originX);
+        // The frame: without it a blank cell is indistinguishable from the
+        // space beside the matrix, and "not assessed" stops being visible.
+        g.append('rect')
+            .attr('x', Math.round(originX)).attr('y', rowsTop)
+            .attr('width', trackW).attr('height', Math.max(1, rowsBottom - rowsTop))
+            .attr('fill', 'none')
+            .attr('stroke', ink).attr('stroke-opacity', 0.55).attr('stroke-width', 1);
+
+        // ---- the clustering behind the column order, above the grid ----
+        // Drawn with the cells, in the tree's own group, so it zooms, pans and
+        // exports with them. Heights are LINEAR in the merge distance, so a
+        // block that joins low really is drawn tighter than one that joins
+        // high; spacing merges evenly by rank would read more clearly and
+        // would say something false.
+        let dendro = heatmapDendrogram();
+        if (dendro && dendro.height.length >= 1 && dendro.order.length === visible && offset === 0) {
+            let band = heatmapDendroBand();
+            let baseline = rowsTop - HEATMAP_DENDRO_GAP;
+            let maxH = 0;
+            dendro.height.forEach(function (h) {
+                if (isFinite(h) && h > maxH) {
+                    maxH = h;
+                }
+            });
+            let slot = new Array(dendro.order.length);
+            dendro.order.forEach(function (leaf, k) {
+                slot[leaf] = k;
+            });
+            let clusterX = new Array(dendro.height.length);
+            let clusterY = new Array(dendro.height.length);
+            // R's node-id convention: negative = the singleton of that index,
+            // positive = the cluster formed at that stage
+            let nodeX = function (id) {
+                return (id < 0) ? (originX + ((slot[-id - 1] + 0.5) * cw)) : clusterX[id - 1];
+            };
+            let nodeY = function (id) {
+                return (id < 0) ? baseline : clusterY[id - 1];
+            };
+            let path = '';
+            for (let s = 0; s < dendro.height.length; ++s) {
+                let h = dendro.height[s];
+                // a merge with no finite height -- two columns that share no
+                // assessed tip, so no distance was ever computed -- goes to the
+                // top of the band, above every measurable merge, which is where
+                // it belongs: it joined last
+                let ym = (!isFinite(h) || !(maxH > 0)) ? (baseline - band) : (baseline - ((h / maxH) * band));
+                let x1 = nodeX(dendro.left[s]);
+                let y1 = nodeY(dendro.left[s]);
+                let x2 = nodeX(dendro.right[s]);
+                let y2 = nodeY(dendro.right[s]);
+                path += 'M' + x1.toFixed(1) + ',' + y1.toFixed(1)
+                    + 'L' + x1.toFixed(1) + ',' + ym.toFixed(1)
+                    + 'L' + x2.toFixed(1) + ',' + ym.toFixed(1)
+                    + 'L' + x2.toFixed(1) + ',' + y2.toFixed(1);
+                clusterX[s] = (x1 + x2) / 2;
+                clusterY[s] = ym;
+            }
+            g.append('path').attr('class', 'aptx-heatmap-dendro')
+                .attr('d', path)
+                .attr('fill', 'none')
+                .attr('stroke', ink)
+                .attr('stroke-width', Math.max(1, _state.branchWidthDefault))
+                .style('pointer-events', 'none');
+        }
+
+        // A faint dashed guide from each tip across to its row, as the
+        // alignment track draws -- skipped when the domain tracks are in
+        // between, where it would run straight through their boxes.
+        if (_domainReserve === 0) {
+            let guideFont = _state.externalNodeFontSize + 'px ' + _state.defaultFont;
+            let guideGap = _state.nodeLabelGap;
+            let guideEnd = originX - 3;
+            for (let r = 0; r < n; ++r) {
+                let d = tips[r];
+                let label = d._extLabelText || '';
+                let from;
+                if (label) {
+                    let labelX = (_state.phylogram && _state.alignPhylogram && _yScale)
+                        ? d.y - _yScale(d.distToRoot) + _w + guideGap
+                        : d.y + guideGap;
+                    from = labelX + legendTextWidth(label, guideFont) + 5;
+                } else {
+                    from = d.y + makeNodeSize(d) + 4;
+                }
+                if (guideEnd - from < 6) {
+                    continue;
+                }
+                g.append('line')
+                    .attr('x1', from).attr('x2', guideEnd)
+                    .attr('y1', d.x).attr('y2', d.x)
+                    .attr('stroke', ink)
+                    .attr('stroke-width', 1)
+                    .attr('stroke-dasharray', '2,3')
+                    .style('stroke-opacity', 0.35)
+                    .style('pointer-events', 'none');
+            }
+        }
+
+        // ---- column names and the shared scale: a FLOATING strip ----
+        // the strip is placed against its FULL reserve, so that a stuck strip
+        // clears the alignment's navigation bar, but paints only its content
+        let strip = floatStripGroup('aptx-heatmap-strip', _clusterH, heatmapBottomReserve());
+        strip.append('rect').attr('x', Math.round(originX) - 2).attr('y', _clusterH)
+            .attr('width', trackW + 4).attr('height', heatmapStripHeight())
+            .attr('fill', _state.backgroundColorDefault);
+        let labelTop = _clusterH + HEATMAP_HEAD_GAP;
+        let headH = heatmapHeadHeight();
+        if (headH > 0) {
+            let font = heatmapLabelFont();
+            for (let i = 0; i < visible; ++i) {
+                let col = columns[offset + i];
+                strip.append('text')
+                    .attr('transform', 'translate(' + (originX + (i * cw) + (cw / 2)) + ','
+                        + labelTop + ') rotate(-90)')
+                    .attr('dy', '0.32em')
+                    .attr('text-anchor', 'end')
+                    .style('font', font)
+                    .style('fill', _state.labelColorDefault)
+                    .text(clipTextToWidth(col.label, font, HEATMAP_LABEL_MAX_PX));
+            }
+        }
+
+        // the scale itself: the ramp the cells were painted from, its two
+        // ends named, and the blank cell shown for what it is
+        let scaleTop = labelTop + headH + 6;
+        let barW = Math.round(Math.max(40, Math.min(HEATMAP_SCALE_BAR_W, trackW * 0.45)));
+        let gradId = 'aptx-heatmap-ramp';
+        let grad = strip.append('defs').append('linearGradient').attr('id', gradId)
+            .attr('x1', 0).attr('y1', 0).attr('x2', 1).attr('y2', 0);
+        VIS_COLOR_RAMP.forEach(function (c, i) {
+            grad.append('stop')
+                .attr('offset', ((i * 100) / (VIS_COLOR_RAMP.length - 1)) + '%')
+                .attr('stop-color', c);
+        });
+        strip.append('rect')
+            .attr('x', Math.round(originX)).attr('y', scaleTop)
+            .attr('width', barW).attr('height', HEATMAP_SCALE_BAR_H)
+            .attr('fill', 'url(#' + gradId + ')')
+            .attr('stroke', ink).attr('stroke-opacity', 0.5).attr('stroke-width', 1);
+        let numY = scaleTop + HEATMAP_SCALE_BAR_H + 10;
+        strip.append('text').attr('x', Math.round(originX)).attr('y', numY)
+            .attr('text-anchor', 'start')
+            .style('font-size', '9px').style('fill', ink)
+            .text(heatmapNum(model.min));
+        strip.append('text').attr('x', Math.round(originX) + barW).attr('y', numY)
+            .attr('text-anchor', 'end')
+            .style('font-size', '9px').style('fill', ink)
+            .text(heatmapNum(model.max));
+        // the caption: what the matrix is showing, and -- when it is windowed
+        // -- that there is more of it than this
+        let caption = (visible < total)
+            ? 'Columns ' + (offset + 1) + '–' + (offset + visible) + ' of ' + total + ', one scale (scroll over the matrix)'
+            : total + ' columns, one scale';
+        let capFont = '9px ' + FONT_DEFAULTS;
+        let cursor = Math.round(originX) + barW + 10;
+        let rightEdge = Math.round(originX) + trackW;
+        // the blank's own key comes FIRST: it names a convention the reader
+        // cannot guess, where the caption only repeats what is on screen
+        if (blanks > 0) {
+            let keyW = HEATMAP_SCALE_BAR_H + 4 + legendTextWidth(HEATMAP_NOT_ASSESSED, capFont);
+            if ((rightEdge - cursor) >= keyW) {
+                strip.append('rect').attr('x', cursor).attr('y', scaleTop)
+                    .attr('width', HEATMAP_SCALE_BAR_H).attr('height', HEATMAP_SCALE_BAR_H)
+                    .attr('fill', _state.backgroundColorDefault)
+                    .attr('stroke', ink).attr('stroke-opacity', 0.45).attr('stroke-width', 1);
+                strip.append('text').attr('x', cursor + HEATMAP_SCALE_BAR_H + 4)
+                    .attr('y', scaleTop + HEATMAP_SCALE_BAR_H)
+                    .attr('text-anchor', 'start')
+                    .style('font', capFont).style('fill', ink).style('fill-opacity', 0.85)
+                    .text(HEATMAP_NOT_ASSESSED);
+                cursor += keyW + 10;
+            }
+        }
+        if ((rightEdge - cursor) > 60) {
+            strip.append('text').attr('x', cursor).attr('y', scaleTop + HEATMAP_SCALE_BAR_H)
+                .attr('text-anchor', 'start')
+                .style('font', capFont).style('fill', ink).style('fill-opacity', 0.85)
+                .text(clipTextToWidth(caption, capFont, rightEdge - cursor));
+        }
+
+        // hover + wheel surface over the rows
+        g.append('rect').attr('class', 'aptx-heatmap-hover')
+            .attr('x', Math.round(originX)).attr('y', rowsTop)
+            .attr('width', trackW).attr('height', Math.max(1, rowsBottom - rowsTop))
+            .attr('fill', 'transparent')
+            .on('mousemove', heatmapHoverMove)
+            .on('mouseout', heatmapHoverOut)
+            .on('wheel', function (event) {
+                if (visible >= total) {
+                    return;   // nothing to scroll: leave the wheel to the page
+                }
+                event.preventDefault();
+                event.stopPropagation();
+                let delta = Math.abs(event.deltaY) >= Math.abs(event.deltaX) ? event.deltaY : event.deltaX;
+                if (delta === 0) {
+                    return;
+                }
+                let step = Math.max(1, Math.round(visible / 10));
+                heatmapScrollTo(_heatmapColOffset + (delta > 0 ? step : -step));
+            });
+        _heatmapGeom = {
+            originX: originX, cw: cw, offset: offset, visible: visible, total: total,
+            bounds: bounds, tips: tips, refs: columns, min: model.min, max: model.max
+        };
+        placeFloatingOverlays();
+    }
+
+
+    // ===================== the matrix, as rings =====================
+    // The circular layout's analogue of the track: one concentric RING per
+    // column, just past the tips and their labels, each tip's cell an arc over
+    // that tip's own angular slice. The desktop's paintAnnotationColumnsCircular,
+    // in polar coordinates rather than along an axis.
+    //
+    // Circular only, never unrooted: a column has to be a ring, and an unrooted
+    // fan ends every tip at a different radius, so there is no ring for one to
+    // sit on. (The domain tracks ride each tip's own spoke there, which works
+    // for a bar and not for a matrix.)
+
+    // _radial is set by the circular layout and nulled by every other, so it
+    // IS the test; heatmapShown() has already refused the unrooted one. A
+    // separate circularDisplay check here looked like a third lock and could
+    // not fire -- sabotaging it away changed nothing anywhere.
+    function heatmapCircular() {
+        return heatmapShown() && !!_radial;
+    }
+
+    // A ring is as thick as the others, and the stack is capped against the
+    // tree's own radius: a wide matrix must not turn the tree into a dot at
+    // the middle of a dartboard.
+    function heatmapRingWidth() {
+        let m = heatmapModel();
+        if (!m || m.refs.length < 1 || !_radial) {
+            return HEATMAP_PREF_COL_W;
+        }
+        let budget = _radial.maxRad * HEATMAP_RADIAL_MAX_FRACTION;
+        return Math.max(HEATMAP_RADIAL_MIN_RING,
+            Math.min(HEATMAP_PREF_COL_W, budget / m.refs.length));
+    }
+
+    // How far past the tip ring the matrix reaches, for the fit to allow for.
+    function heatmapRadialExtent() {
+        if (!heatmapCircular()) {
+            return 0;
+        }
+        return HEATMAP_RADIAL_GAP + (heatmapModel().refs.length * heatmapRingWidth())
+            + HEATMAP_RADIAL_END_GAP;
+    }
+
+    // one cell: the ring between r0 and r1, over the angles a0 to a1
+    function heatmapSector(a0, a1, r0, r1) {
+        let p = function (a, r) {
+            let xy = polarXY(a, r);
+            return xy[0].toFixed(1) + ',' + xy[1].toFixed(1);
+        };
+        let large = (a1 - a0) > Math.PI ? 1 : 0;
+        return 'M' + p(a0, r0)
+            + 'A' + r0.toFixed(1) + ',' + r0.toFixed(1) + ' 0 ' + large + ' 1 ' + p(a1, r0)
+            + 'L' + p(a1, r1)
+            + 'A' + r1.toFixed(1) + ',' + r1.toFixed(1) + ' 0 ' + large + ' 0 ' + p(a0, r1)
+            + 'Z';
+    }
+
+    function drawHeatmapRings() {
+        let model = heatmapModel();
+        let ordered = heatmapOrdered();
+        let columns = ordered ? ordered.columns : model.refs;
+        let tips = displayedTips().filter(function (d) {
+            return d.x !== undefined;
+        }).sort(function (p, q) {
+            return p.x - q.x;
+        });
+        let n = tips.length;
+        if (n < 1 || columns.length < 1) {
+            _heatmapGeom = null;
+            return;
+        }
+        let g = _svgGroup.append('g').attr('class', 'aptx-heatmap');
+        let ink = _state.branchColorDefault;
+        let ringW = heatmapRingWidth();
+        let start = _radial.maxRad + tipLabelSpace() + HEATMAP_RADIAL_GAP;
+
+        // Angular boundaries, derived ONCE between neighbours, exactly as the
+        // rectangular rows are: a per-tip half-step would round apart and leave
+        // hairline seams all round the ring.
+        let ang = tips.map(function (d) {
+            return radialAngle(d.x);
+        });
+        let pad = n > 1 ? (ang[n - 1] - ang[0]) / (n - 1) / 2 : Math.PI / 8;
+        let edge = new Array(n + 1);
+        edge[0] = ang[0] - pad;
+        for (let i = 1; i < n; ++i) {
+            edge[i] = (ang[i - 1] + ang[i]) / 2;
+        }
+        edge[n] = ang[n - 1] + pad;
+
+        let blanks = 0;
+        for (let c = 0; c < columns.length; ++c) {
+            let r0 = start + (c * ringW);
+            let r1 = r0 + ringW;
+            let ref = columns[c].ref;
+            // consecutive tips of the same colour merge into one sector, which
+            // is what keeps a big circular tree drawable
+            let runStart = -1;
+            let runFill = null;
+            let flush = function (endI) {
+                if (runStart < 0) {
+                    return;
+                }
+                // Bled outward and clockwise only: the rings are drawn inner to
+                // outer and each ring's cells in tip order, so the neighbour
+                // that covers the overlap is always the one drawn next.
+                // A BLANK is not bled -- it is background-coloured, so a seam
+                // beside it shows nothing, and bleeding it would push its
+                // outward OUTLINE under the next ring and cost it an edge.
+                let bleed = (runFill === HEATMAP_BLANK) ? 0 : HEATMAP_RING_BLEED;
+                let a1 = edge[endI] + (bleed / Math.max(1, r1));
+                let path = g.append('path')
+                    .attr('d', heatmapSector(edge[runStart], a1, r0, r1 + bleed));
+                if (runFill === HEATMAP_BLANK) {
+                    path.attr('fill', _state.backgroundColorDefault)
+                        .attr('stroke', ink).attr('stroke-opacity', 0.45).attr('stroke-width', 1);
+                } else {
+                    path.attr('fill', runFill);
+                }
+                runStart = -1;
+                runFill = null;
+            };
+            for (let i = 0; i < n; ++i) {
+                let v = forester.heatmapValue(tips[i], ref);
+                let fill = (v === null) ? HEATMAP_BLANK : heatmapColorOf(v);
+                if (fill === HEATMAP_BLANK) {
+                    blanks++;
+                }
+                if (runFill === fill && (ringW < HEATMAP_LABEL_MIN_COL_W || fill !== HEATMAP_BLANK)) {
+                    continue;
+                }
+                flush(i);
+                runStart = i;
+                runFill = fill;
+            }
+            flush(n);
+        }
+
+        // the stack's own edges, so a blank reads as a hole in a grid rather
+        // than as a gap in the drawing
+        [start, start + (columns.length * ringW)].forEach(function (r) {
+            g.append('path')
+                .attr('d', heatmapSector(edge[0], edge[n], r - 0.5, r + 0.5))
+                .attr('fill', ink).attr('fill-opacity', 0.5);
+        });
+
+        // Each ring's name, laid along the ring at the fan's seam -- the gap
+        // the layout already leaves between the last tip and the first. It is
+        // the one place a label can sit without covering a cell.
+        if (ringW >= HEATMAP_RADIAL_MIN_NAMED_RING) {
+            let seam = edge[n] + ((2 * Math.PI) - (edge[n] - edge[0])) / 2;
+            let font = Math.max(7, Math.min(10, Math.round(ringW))) + 'px ' + FONT_DEFAULTS;
+            columns.forEach(function (col, c) {
+                let r = start + (c * ringW) + (ringW / 2);
+                let xy = polarXY(seam, r);
+                // TANGENTIAL: along the ring, not out along the spoke. polarXY
+                // puts angle a at screen direction a - 90, so the tangent is a
+                // itself -- rotating by a - 90 instead laid every name out
+                // along the seam, where rings are one ring-width apart and the
+                // names are several times that: measured, 44 overlapping pairs
+                // out of 18 names. Flipped where it would otherwise read
+                // upside down.
+                let deg = ((seam * 180 / Math.PI) % 360 + 360) % 360;
+                let flip = (deg > 90 && deg < 270);
+                g.append('text')
+                    .attr('transform', 'translate(' + xy[0].toFixed(1) + ',' + xy[1].toFixed(1) + ') '
+                        + 'rotate(' + (deg + (flip ? 180 : 0)).toFixed(1) + ')')
+                    .attr('text-anchor', 'middle')
+                    .attr('dy', '0.32em')
+                    .style('font', font)
+                    .style('fill', _state.labelColorDefault)
+                    .text(clipTextToWidth(col.label, font, HEATMAP_LABEL_MAX_PX));
+            });
+        }
+
+        // the hover surface: the whole annulus, hit-tested in polar coordinates
+        g.append('path')
+            .attr('class', 'aptx-heatmap-hover')
+            .attr('d', heatmapSector(edge[0], edge[n], start, start + (columns.length * ringW)))
+            .attr('fill', 'transparent')
+            .on('mousemove', heatmapHoverMove)
+            .on('mouseout', heatmapHoverOut);
+
+        _heatmapGeom = {
+            circular: true, start: start, ringW: ringW, edge: edge, tips: tips,
+            refs: columns, min: model.min, max: model.max, blanks: blanks
+        };
+    }
+
+
+    // The scale, for the circular layout. The rectangular track hangs its
+    // legend under the matrix, which a ring has no "under": this is the same
+    // content -- the ramp, its two ends, the blank key, the column count -- as
+    // a card in the corner the tree leaves free. Drawn in screen coordinates
+    // like the domain legend, so it neither turns nor scales with the fan.
+    function drawHeatmapRingLegend() {
+        if (!_baseSvg) {
+            return;
+        }
+        _baseSvg.selectAll('g.aptx-heatmap-ringlegend').remove();
+        let size = svgSize();
+        let m = heatmapModel();
+        if (!heatmapCircular() || !size || !m) {
+            return;
+        }
+        const PAD = 9;
+        const BAR_W = 128;
+        const FS = 9;
+        let ink = _state.labelColorDefault;
+        let frame = _state.branchColorDefault;
+        let capFont = FS + 'px ' + FONT_DEFAULTS;
+        let blanks = _heatmapGeom && _heatmapGeom.blanks > 0;
+        let caption = m.refs.length + ' columns, one scale';
+        let width = (2 * PAD) + Math.max(BAR_W, legendTextWidth(caption, capFont),
+            blanks ? (HEATMAP_SCALE_BAR_H + 4 + legendTextWidth(HEATMAP_NOT_ASSESSED, capFont)) : 0);
+        let rows = 2 + (blanks ? 1 : 0);
+        let height = (2 * PAD) + HEATMAP_SCALE_BAR_H + (rows * (FS + 4));
+        let x = PAD;
+        let y = size.h - height - PAD;   // bottom-left: the overview box lives bottom-right
+
+        let g = _baseSvg.append('g').attr('class', 'aptx-heatmap-ringlegend')
+            .style('pointer-events', 'none');
+        g.append('rect').attr('x', x).attr('y', y).attr('width', width).attr('height', height)
+            .attr('rx', 5)
+            .style('fill', _state.backgroundColorDefault).style('fill-opacity', 0.92)
+            .style('stroke', frame).style('stroke-opacity', 0.5);
+
+        let gradId = 'aptx-heatmap-ringramp';
+        let grad = g.append('defs').append('linearGradient').attr('id', gradId)
+            .attr('x1', 0).attr('y1', 0).attr('x2', 1).attr('y2', 0);
+        VIS_COLOR_RAMP.forEach(function (c, i) {
+            grad.append('stop')
+                .attr('offset', ((i * 100) / (VIS_COLOR_RAMP.length - 1)) + '%')
+                .attr('stop-color', c);
+        });
+        let barY = y + PAD;
+        g.append('rect').attr('x', x + PAD).attr('y', barY)
+            .attr('width', BAR_W).attr('height', HEATMAP_SCALE_BAR_H)
+            .attr('fill', 'url(#' + gradId + ')')
+            .attr('stroke', frame).attr('stroke-opacity', 0.5).attr('stroke-width', 1);
+        let line = barY + HEATMAP_SCALE_BAR_H + FS + 2;
+        g.append('text').attr('x', x + PAD).attr('y', line).attr('text-anchor', 'start')
+            .style('font', capFont).style('fill', ink).text(heatmapNum(m.min));
+        g.append('text').attr('x', x + PAD + BAR_W).attr('y', line).attr('text-anchor', 'end')
+            .style('font', capFont).style('fill', ink).text(heatmapNum(m.max));
+        if (blanks) {
+            line += FS + 4;
+            g.append('rect').attr('x', x + PAD).attr('y', line - HEATMAP_SCALE_BAR_H)
+                .attr('width', HEATMAP_SCALE_BAR_H).attr('height', HEATMAP_SCALE_BAR_H)
+                .attr('fill', _state.backgroundColorDefault)
+                .attr('stroke', frame).attr('stroke-opacity', 0.45).attr('stroke-width', 1);
+            g.append('text').attr('x', x + PAD + HEATMAP_SCALE_BAR_H + 4).attr('y', line)
+                .attr('text-anchor', 'start')
+                .style('font', capFont).style('fill', ink).style('fill-opacity', 0.85)
+                .text(HEATMAP_NOT_ASSESSED);
+        }
+        line += FS + 4;
+        g.append('text').attr('x', x + PAD).attr('y', line).attr('text-anchor', 'start')
+            .style('font', capFont).style('fill', ink).style('fill-opacity', 0.85)
+            .text(caption);
+    }
+
+    function heatmapScrollTo(offset) {
+        if (!_heatmapGeom) {
+            return;
+        }
+        let max = Math.max(0, _heatmapGeom.total - _heatmapGeom.visible);
+        let next = Math.max(0, Math.min(max, Math.round(offset)));
+        if (next !== _heatmapColOffset) {
+            _heatmapColOffset = next;
+            drawHeatmapTrack();
+        }
+    }
+
+    // The hover readout, as on the desktop: the tip, the column and its
+    // value, and the scale the colour was taken from -- so a colour can be
+    // turned back into a number without reading the legend off the bottom.
+    function heatmapHoverMove(event) {
+        if (!_heatmapGeom) {
+            return;
+        }
+        let p = d3.pointer(event, _svgGroup.node());
+        let i;
+        let r = -1;
+        if (_heatmapGeom.circular) {
+            // the same two questions in polar form: which ring, and which slice
+            let rad = Math.sqrt((p[0] * p[0]) + (p[1] * p[1]));
+            i = Math.floor((rad - _heatmapGeom.start) / _heatmapGeom.ringW);
+            if (i < 0 || i >= _heatmapGeom.refs.length) {
+                heatmapHoverOut();
+                return;
+            }
+            // polarXY turns an angle a into (cos(a - pi/2), sin(a - pi/2)),
+            // so the angle comes back the same way round
+            let a = Math.atan2(p[1], p[0]) + (Math.PI / 2);
+            let edge = _heatmapGeom.edge;
+            let n = _heatmapGeom.tips.length;
+            for (let k = 0; k < n; ++k) {
+                // the fan can be laid anywhere on the circle (it rotates), so
+                // the comparison is made modulo a full turn rather than on the
+                // raw angle, which need not lie in the same period
+                let lo = edge[k];
+                let hi = edge[k + 1];
+                let d = ((a - lo) % (2 * Math.PI) + (2 * Math.PI)) % (2 * Math.PI);
+                if (d < (hi - lo)) {
+                    r = k;
+                    break;
+                }
+            }
+        } else {
+            i = Math.floor((p[0] - _heatmapGeom.originX) / _heatmapGeom.cw);
+            if (i < 0 || i >= _heatmapGeom.visible) {
+                heatmapHoverOut();
+                return;
+            }
+            for (let k = 0; k < _heatmapGeom.tips.length; ++k) {
+                if (p[1] >= _heatmapGeom.bounds[k] && p[1] < _heatmapGeom.bounds[k + 1]) {
+                    r = k;
+                    break;
+                }
+            }
+        }
+        if (r < 0) {
+            heatmapHoverOut();
+            return;
+        }
+        let tip = _heatmapGeom.tips[r];
+        let col = _heatmapGeom.refs[(_heatmapGeom.offset || 0) + i];
+        let v = forester.heatmapValue(tip, col.ref);
+        let txt = 'Tip: ' + (displayNodeName(tip) || '?') + '<br>'
+            + col.label + ': ' + (v === null ? HEATMAP_NOT_ASSESSED : heatmapNum(v)) + '<br>'
+            + 'Scale: ' + heatmapNum(_heatmapGeom.min) + ' – ' + heatmapNum(_heatmapGeom.max);
+        let tip_el = _node_mouseover_div.node();
+        tip_el.classList.remove('aptx-light', 'aptx-dark');
+        if (_panelTheme) {
+            tip_el.classList.add('aptx-' + _panelTheme);
+        }
+        _node_mouseover_div.html(markUpDataLabels(escapeHtmlKeepBreaks(txt)));
+        placeHoverReadout(tip_el, event);
+        _node_mouseover_div.transition().duration(100).style('opacity', 0.95);
+    }
+
+    function heatmapHoverOut() {
+        _node_mouseover_div.transition().duration(300).style('opacity', 1e-6);
+    }
+
+
+    // The reader's own column order, as the desktop's Annotation Fields arrows
+    // set it. Theirs also chooses WHICH fields are columns and of what type;
+    // ours takes every numeric field automatically, so this dialog is about
+    // order and nothing else.
+    //
+    // Moving anything here makes the order Manual, and Manual never re-sorts --
+    // a sorting mode that quietly undid a move would make the move pointless.
+    // The same rule as the desktop's resolveEdited, minus its "did the order
+    // actually change" test, which it needs only because its dialog does other
+    // things too.
+    function showHeatmapReorderDialog() {
+        let ordered = heatmapOrdered();
+        if (!ordered || ordered.columns.length < 2) {
+            return;
+        }
+        let shell = makeDialogShell(HEATMAP_REORDER_DIALOG, 'Order columns', 320);
+        let body = shell.body;
+        repsElement(body, 'div', 'aptx-reps-lead',
+            'Drag a column, or use the arrows. Your order is kept until you choose another.');
+        let list = repsElement(body, 'div', 'aptx-reorder');
+        let working = ordered.columns.slice();
+
+        function rowAt(y) {
+            let rows = Array.prototype.slice.call(list.children);
+            for (let i = 0; i < rows.length; ++i) {
+                let b = rows[i].getBoundingClientRect();
+                if (y < b.top + (b.height / 2)) {
+                    return i;
+                }
+            }
+            return rows.length;
+        }
+
+        function move(from, to) {
+            if (to < 0 || to >= working.length || from === to) {
+                return false;
+            }
+            working.splice(to, 0, working.splice(from, 1)[0]);
+            draw();
+            return true;
+        }
+
+        function draw() {
+            list.textContent = '';
+            working.forEach(function (col, i) {
+                let row = repsElement(list, 'div', 'aptx-reorder-row');
+                row.tabIndex = 0;
+                repsElement(row, 'span', 'aptx-reorder-grip', '≡');
+                repsElement(row, 'span', 'aptx-reorder-name', col.label || col.ref).title = col.ref;
+                let up = repsElement(row, 'button', 'aptx-reorder-move', '↑');
+                let down = repsElement(row, 'button', 'aptx-reorder-move', '↓');
+                up.type = 'button';
+                down.type = 'button';
+                up.title = 'Move up';
+                down.title = 'Move down';
+                up.disabled = (i === 0);
+                down.disabled = (i === working.length - 1);
+                up.addEventListener('click', function () {
+                    if (move(i, i - 1)) {
+                        list.children[i - 1].focus();
+                    }
+                });
+                down.addEventListener('click', function () {
+                    if (move(i, i + 1)) {
+                        list.children[i + 1].focus();
+                    }
+                });
+                // the arrows reach the same places from the keyboard, so a row
+                // can be moved without a pointer at all
+                row.addEventListener('keydown', function (event) {
+                    let d = (event.key === 'ArrowUp') ? -1 : ((event.key === 'ArrowDown') ? 1 : 0);
+                    if (d === 0) {
+                        return;
+                    }
+                    event.preventDefault();
+                    if (move(i, i + d)) {
+                        list.children[i + d].focus();
+                    }
+                });
+                row.addEventListener('pointerdown', function (event) {
+                    if (event.target.classList.contains('aptx-reorder-move')) {
+                        return;   // the arrows are not a drag handle
+                    }
+                    event.preventDefault();
+                    row.classList.add('aptx-reorder-dragging');
+                    // The LIVE node is moved rather than the list redrawn: a
+                    // redraw would replace the element this drag is following.
+                    // Its position is read back from the DOM each time instead
+                    // of being tracked in a variable -- the first cut kept an
+                    // index, updated it, and then used it to work out where to
+                    // insert, by which point it no longer meant what the
+                    // calculation assumed.
+                    let onMove = function (ev) {
+                        let kids = Array.prototype.slice.call(list.children);
+                        let from = kids.indexOf(row);
+                        let to = rowAt(ev.clientY);
+                        if (to > from) {
+                            to -= 1;   // taking the row out shifts everything after it up one
+                        }
+                        if (to === from || to < 0 || to >= kids.length) {
+                            return;
+                        }
+                        working.splice(to, 0, working.splice(from, 1)[0]);
+                        let others = kids.filter(function (k) {
+                            return k !== row;
+                        });
+                        list.insertBefore(row, others[to] || null);
+                        Array.prototype.slice.call(list.children).forEach(function (r, k) {
+                            let btns = r.querySelectorAll('.aptx-reorder-move');
+                            btns[0].disabled = (k === 0);
+                            btns[1].disabled = (k === list.children.length - 1);
+                        });
+                    };
+                    let onUp = function () {
+                        row.classList.remove('aptx-reorder-dragging');
+                        window.removeEventListener('pointermove', onMove);
+                        window.removeEventListener('pointerup', onUp);
+                        draw();
+                    };
+                    window.addEventListener('pointermove', onMove);
+                    window.addEventListener('pointerup', onUp);
+                });
+            });
+        }
+        draw();
+
+        let actions = repsElement(body, 'div', 'aptx-reps-actions');
+        repsButton(actions, 'Automatic', false, function () {
+            // back to whatever the data asks for: the arrangement is dropped,
+            // not merely overridden
+            _state.heatmapManualOrder = null;
+            _state.heatmapColumnOrder = null;
+            shell.dialog.close();
+            syncHeatmapControls();
+            scheduleUpdate(null, 0);
+        });
+        repsButton(actions, 'Cancel', false, function () {
+            shell.dialog.close();
+        });
+        repsButton(actions, 'Apply', true, function () {
+            _state.heatmapManualOrder = working.map(function (c) {
+                return c.ref;
+            });
+            _state.heatmapColumnOrder = 'manual';
+            shell.dialog.close();
+            syncHeatmapControls();
+            scheduleUpdate(null, 0);
+        });
+        shell.dialog.showModal();
+        // showModal() would otherwise land on the close button: focus belongs
+        // on the list, where the arrow keys already move a row
+        if (list.firstChild) {
+            list.firstChild.focus();
+        }
+    }
+
+    function heatmapCbClicked() {
+        _state.showHeatmap = getCheckboxValue(HEATMAP_CB);
+        syncHeatmapControls();
+        scheduleUpdate(null, 0);
+    }
+
     // ===================== Collapsed clades =====================
     // Collapsing is DISPLAY state on the node (d.collapsed) and nothing
     // else: forester never sees it, the writers never see it, and the data
@@ -7468,7 +8688,7 @@ function (root, d3, forester, phyloXml) {
     // The wedge's reach: the clade's nearest and farthest tips, in the
     // layout's x. One edge runs to the nearest tip and the other to the
     // farthest, so the shape itself shows how uneven the clade's branch
-    // lengths are (as iTOL draws it). Christian chose this over the
+    // lengths are. Christian chose this over the
     // desktop's symmetric triangle on an average base (2026-09-14). A
     // phylogram measures the tips; a cladogram, where every leaf sits on
     // the tip column, gives the wedge one depth step.
@@ -7711,6 +8931,13 @@ function (root, d3, forester, phyloXml) {
         if (_basicTreeProperties.alignedMolSeqs === true && _basicTreeProperties.maxMolSeqLength > 0) {
             s.msa = _state.showMsa === true;
         }
+        if (heatmapAvailable()) {
+            s.heatmap = _state.showHeatmap === true;
+            s.heatmapOrder = heatmapMode();
+            if (_state.heatmapManualOrder) {
+                s.heatmapManual = _state.heatmapManualOrder.slice();
+            }
+        }
         if (_basicTreeProperties.domainArchitectures === true) {
             s.domains = _state.showDomainArchitectures === true;
             s.domainLabels = _state.domainLabels;
@@ -7831,6 +9058,17 @@ function (root, d3, forester, phyloXml) {
         if (typeof s.msa === 'boolean') {
             _state.showMsa = s.msa;
         }
+        if (typeof s.heatmap === 'boolean') {
+            _state.showHeatmap = s.heatmap;
+        }
+        if (Array.isArray(s.heatmapManual) && s.heatmapManual.every(function (r) {
+            return typeof r === 'string';
+        })) {
+            _state.heatmapManualOrder = s.heatmapManual.slice();
+        }
+        if (forester.HEATMAP_ORDER_MODES.indexOf(s.heatmapOrder) >= 0) {
+            _state.heatmapColumnOrder = s.heatmapOrder;
+        }
         if (typeof s.domains === 'boolean') {
             _state.showDomainArchitectures = s.domains;
         }
@@ -7930,6 +9168,8 @@ function (root, d3, forester, phyloXml) {
             }
         });
         setCheckboxValue(MSA_CB, _state.showMsa === true);
+        setCheckboxValue(HEATMAP_CB, _state.showHeatmap === true);
+        syncHeatmapControls();
         setCheckboxValue(TIME_AXIS_CB, _state.showTimeAxis === true);
         setCheckboxValue(TIME_GRID_CB, _state.timeAxisGrid === true);
         setCheckboxValue(DOMAIN_GLOW_CB, _state.domainGlow === true);
@@ -8152,7 +9392,7 @@ function (root, d3, forester, phyloXml) {
         {key: 'e', label: 'E', shift: true, what: 'Expand vertically until the labels fit', run: function () { zoomToExpandY(); }},
         {key: 'l', label: 'L', shift: true, what: 'Next layout: rectangular, circular, unrooted', run: cycleLayout},
         {key: 'd', label: 'D', shift: true, what: 'Next display type: phylogram, aligned, cladogram', run: cycleDisplayType},
-        {key: 'x', label: 'X', shift: true, what: 'Time axis on / off', run: toggleTimeAxis},
+        {key: 'x', label: 'X', shift: true, what: 'Time / divergence scale, or the time axis', run: toggleTimeAxis},
         {key: 'o', label: 'O', shift: true, what: 'Ladderize (order the tree)', run: function () { ladderizeButtonPressed(); }},
         {key: 'u', label: 'U', shift: true, what: 'Uncollapse every clade', run: function () { uncollapseAll(); }},
         {key: 'f', label: 'F', what: 'Go to the search box', run: focusSearch, typing: true},
@@ -8222,9 +9462,45 @@ function (root, d3, forester, phyloXml) {
         }
     }
 
-    // The Time Axis checkbox's toggle; when the distance / time tree switch
-    // arrives it takes over this key.
+    /**
+     * Redraws the tree with its branch lengths taken from the chosen metric:
+     * TIME (the gaps between the nodes' dates) or DIVERGENCE (what the file's
+     * own branch lengths measured, recorded at load). Both metrics stay on the
+     * tree, so this is reversible and lossless -- a round trip restores the
+     * loaded branch lengths exactly.
+     *
+     * @param scale 'time' or 'divergence'
+     */
+    function setBranchScale(scale) {
+        if (!_branchScaleAvailable || !_treeData || _state.branchScale === scale) {
+            return;
+        }
+        _state.branchScale = scale;
+        if (scale === 'time') {
+            forester.applyTimeBranchLengths(_treeData);
+        } else {
+            forester.applyDivergenceBranchLengths(_treeData);
+        }
+        // the branch lengths ARE the layout, so everything measured from them
+        // has to be measured again
+        _basicTreeProperties = forester.collectBasicTreeProperties(_treeData);
+        setCheckboxValue(BRANCH_SCALE_TIME_BUTTON, scale === 'time');
+        setCheckboxValue(BRANCH_SCALE_DIV_BUTTON, scale !== 'time');
+        zoomToFit();
+    }
+
+    function branchScaleButtonClicked() {
+        setBranchScale(getCheckboxValue(BRANCH_SCALE_TIME_BUTTON) ? 'time' : 'divergence');
+    }
+
+    // Shift+X. The switch takes this key over where the tree offers it, as was
+    // always intended; on every other tree it still works the Time Axis
+    // checkbox, so the key never does nothing.
     function toggleTimeAxis() {
+        if (_branchScaleAvailable) {
+            setBranchScale(_state.branchScale === 'time' ? 'divergence' : 'time');
+            return;
+        }
         let cb = byId(TIME_AXIS_CB);
         if (!cb || cb.disabled) {
             return;
@@ -8385,8 +9661,10 @@ function (root, d3, forester, phyloXml) {
     }
 
     // The room the longest tip label takes: the same estimate the layout is
-    // sized against (there are no font metrics in the model).
-    function domainLabelSpace() {
+    // sized against (there are no font metrics in the model). Used by the
+    // domain tracks and by the heat map's rings, which both start past it --
+    // hence the name, which used to say "domain".
+    function tipLabelSpace() {
         return (_maxLabelLength * _state.externalNodeFontSize * LABEL_SIZE_CALC_FACTOR) + LABEL_SIZE_CALC_ADDITION;
     }
 
@@ -8550,7 +9828,7 @@ function (root, d3, forester, phyloXml) {
         // Where each tip's architecture goes: its start along the track, the
         // top and height of its boxes, and in the radial layouts the
         // transform that turns (and for unrooted moves) it onto its spoke.
-        let labelSpace = domainLabelSpace();
+        let labelSpace = tipLabelSpace();
         let rows = [];
         if (_state.circularDisplay) {
             // every bar starts on one ring past the labels and rides its
@@ -8856,6 +10134,60 @@ function (root, d3, forester, phyloXml) {
         setCheckboxValue(DOMAIN_GLOW_CB, _state.domainGlow === true);
     }
 
+    // The control follows the toggle: hidden without it, and hidden in the
+    // radial layouts, where no matrix is drawn to order.
+    function syncHeatmapControls() {
+        let fs = byId(HEATMAP_CONTROLS);
+        if (!fs) {
+            return;
+        }
+        fs.style.display = heatmapShown() ? '' : 'none';
+        if (!heatmapAvailable()) {
+            return;
+        }
+        setValue(HEATMAP_ORDER_SELECT, heatmapMode());
+        let reorder = byId(HEATMAP_REORDER_BUTTON);
+        if (reorder) {
+            // two columns can only be in one order up to a flip, which the
+            // arrows would make look like a choice
+            reorder.disabled = !heatmapShown() || heatmapModel().refs.length < 2;
+        }
+        // phyloXML gives every node its own property list, so tips CAN list the
+        // same columns in different orders -- and then "as in the input" is a
+        // consensus rather than a transcription. Say which, for THIS tree:
+        // nobody can tell by looking at the matrix.
+        let sel = byId(HEATMAP_ORDER_SELECT);
+        let opt = sel ? sel.querySelector('option[value="document"]') : null;
+        if (opt) {
+            let a = heatmapInputAgreement();
+            opt.title = 'the order the input lists the columns in'
+                + ((!a || a.tips < 1) ? ''
+                    : (a.conflicting === 0)
+                        ? ' \u2014 every tip here lists them the same way, so this is exactly that order'
+                        : ' \u2014 ' + a.conflicting + ' of ' + a.tips
+                            + ' tips here list them in a different order, so this is the order most of them agree on');
+        }
+    }
+
+    function heatmapOrderChanged() {
+        let v = getValue(HEATMAP_ORDER_SELECT);
+        if (forester.HEATMAP_ORDER_MODES.indexOf(v) < 0 || v === heatmapMode()) {
+            return;
+        }
+        if (v === 'manual' && !_state.heatmapManualOrder) {
+            // Manual with nothing arranged yet freezes what is on screen. The
+            // alternative -- an empty list, which means "no opinion" -- would
+            // silently re-derive the order the reader just asked to keep.
+            let o = heatmapOrdered();
+            _state.heatmapManualOrder = o ? o.columns.map(function (c) {
+                return c.ref;
+            }) : null;
+        }
+        _state.heatmapColumnOrder = v;
+        _heatmapColOffset = 0;   // a different order: the old window means nothing
+        scheduleUpdate(null, 0);
+    }
+
     function domainsCbClicked() {
         _state.showDomainArchitectures = getCheckboxValue(DOMAINS_CB);
         if (_state.showDomainArchitectures && radialDisplay()) {
@@ -8966,7 +10298,15 @@ function (root, d3, forester, phyloXml) {
         return _state.showTimeAxis === true && !radialDisplay()
             && _state.phylogram === true
             && _timeInfo !== null && _timeInfo.type !== null
-            && _basicTreeProperties.branchLengths === true;
+            && _basicTreeProperties.branchLengths === true
+            // The axis is an overlay calibrated to the tree's own branch scale,
+            // so it must be hidden when the branches are showing DIVERGENCE
+            // and divergence is a different measure -- calendar years against
+            // substitutions reads as a confident lie. Only then: where the two
+            // metrics agree (a BEAST time tree, whose branch lengths ARE time)
+            // there is no switch and the axis is calibrated correctly, which
+            // is what makes a converted BEAST tree show its years at all.
+            && !(_branchScaleAvailable && _state.branchScale === 'divergence');
     }
 
     function timeAxisBottomReserve() {
@@ -8985,6 +10325,7 @@ function (root, d3, forester, phyloXml) {
         // or the bar covers them -- the old bare slider did exactly that.
         // The scale bar sits in the same band, under the tree's last row.
         return Math.max(msaShown() ? MSA_BOTTOM_RESERVE + MSA_NAV_RESERVE : 0, timeAxisBottomReserve(),
+            heatmapBottomReserve(),
             scaleBarShown() && !radialDisplay() ? SCALE_BAR_RESERVE : 0);
     }
 
@@ -9368,7 +10709,7 @@ function (root, d3, forester, phyloXml) {
             return;
         }
         let labelSpace = (_maxLabelLength * _state.externalNodeFontSize * LABEL_SIZE_CALC_FACTOR) + LABEL_SIZE_CALC_ADDITION;
-        let outer = maxRad + labelSpace + domainRadialExtent();
+        let outer = maxRad + labelSpace + domainRadialExtent() + heatmapRadialExtent();
         let W = +_baseSvg.attr('width'), H = +_baseSvg.attr('height');
         let scale = 0.9 * (Math.min(W, H) / (2 * outer));
         if (!isFinite(scale) || scale <= 0) {
@@ -9885,6 +11226,7 @@ function (root, d3, forester, phyloXml) {
         _radialRotation = 0;
         _radialLabelsHorizontal = false;
         _msaColOffset = 0;
+        _heatmapColOffset = 0;
         syncZoomRowButtons();
         refreshVisualizations(false);
         // Esc resets to the launch state -- the auto-applied colour, when its
@@ -10451,6 +11793,12 @@ function (root, d3, forester, phyloXml) {
         if (msaCb) {
             msaCb.disabled = radialDisplay();
         }
+        let heatCb = byId(HEATMAP_CB);
+        if (heatCb) {
+            // circular draws the columns as rings; only unrooted cannot
+            heatCb.disabled = _state.unrootedDisplay === true;
+        }
+        syncHeatmapControls();
         let timeCb = byId(TIME_AXIS_CB);
         if (timeCb) {
             timeCb.disabled = radialDisplay();
@@ -11557,6 +12905,30 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-reps-error:empty { display:none; }'
             + '.aptx-reps-line { padding:1px 0; }'
             + '.aptx-reps-question { margin-top:9px; font-weight:600; }'
+            + '.aptx-reorder { margin-top:8px; max-height:300px; overflow:auto; border:1px solid var(--p-line);'
+            + '  border-radius:7px; padding:3px; background:var(--p-surface2); touch-action:none; }'
+            // the panel's own scrollbar treatment: a native one comes out bright
+            // white inside a dark dialog
+            + '.aptx-reorder::-webkit-scrollbar { width:9px; }'
+            + '.aptx-reorder::-webkit-scrollbar-thumb { background:var(--p-line-strong); border-radius:9px;'
+            + '  border:2px solid var(--p-surface2); }'
+            + '.aptx-reorder::-webkit-scrollbar-track { background:transparent; }'
+            + '.aptx-reorder-row { display:flex; align-items:center; gap:7px; padding:3px 5px; border-radius:5px;'
+            + '  cursor:grab; user-select:none; border:1px solid transparent; }'
+            + '.aptx-reorder-row:hover { background:var(--p-accent-weak); }'
+            + '.aptx-reorder-row:focus-visible { outline:none; border-color:var(--p-accent);'
+            + '  box-shadow:0 0 0 2px var(--p-accent-weak); }'
+            + '.aptx-reorder-dragging { cursor:grabbing; background:var(--p-accent-weak);'
+            + '  border-color:var(--p-accent); opacity:0.9; }'
+            + '.aptx-reorder-grip { flex:none; color:var(--p-faint); font-size:12px; line-height:1; }'
+            + '.aptx-reorder-name { flex:1 1 auto; min-width:0; overflow:hidden; text-overflow:ellipsis;'
+            + '  white-space:nowrap; font-size:11px; color:var(--p-ink); }'
+            + '.aptx-reorder-move { flex:none; width:20px; height:20px; padding:0; line-height:1; font:inherit;'
+            + '  font-size:11px; color:var(--p-muted); background:transparent; border:1px solid transparent;'
+            + '  border-radius:5px; cursor:pointer; }'
+            + '.aptx-reorder-move:hover:not(:disabled) { background:var(--p-surface); color:var(--p-accent-ink);'
+            + '  border-color:var(--p-accent); }'
+            + '.aptx-reorder-move:disabled { opacity:0.3; cursor:default; }'
             + '.aptx-reps-actions { display:flex; justify-content:flex-end; gap:8px; margin-top:12px; }'
             + '.aptx-reps-button { font:inherit; font-size:11px; height:26px; padding:0 12px; color:var(--p-ink);'
             + '  background:var(--p-surface2); border:1px solid var(--p-line-strong); border-radius:6px; cursor:pointer;'
@@ -11720,6 +13092,10 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-panel .aptx-domrow { display:flex; align-items:center; gap:4px; margin:3px 0; }'
             + '.aptx-panel .aptx-domrow .aptx-domlabel { flex:0 0 64px; font-size:10px; color:var(--p-muted); }'
             + '.aptx-panel .aptx-domrow input[type=button] { width:30px; padding:0; margin:0; }'
+            // ... except one that has a WORD on it: the rule above sizes the
+            // domain track's tiny plus and minus, and it clipped this to "Reorc"
+            + '.aptx-panel .aptx-domrow input[type=button].aptx-widebtn { width:auto; flex:1 1 auto;'
+            + '  min-width:0; padding:0 8px; }'
             + '.aptx-panel .aptx-domrow select { flex:1 1 auto; min-width:0; }'
             + '.aptx-panel .aptx-domreadout { flex:1 1 auto; text-align:center; font-size:12px; font-variant-numeric:tabular-nums; color:var(--p-ink); }'
             + '.aptx-panel .aptx-glyph { height:14px; width:auto; display:block; overflow:visible; }'
@@ -12602,6 +13978,8 @@ function (root, d3, forester, phyloXml) {
 
             c0.insertAdjacentHTML('beforeend',makeDomainControls());
 
+            c0.insertAdjacentHTML('beforeend',makeHeatmapControls());
+
             c0.insertAdjacentHTML('beforeend',makeZoomControl());
 
 
@@ -12715,6 +14093,9 @@ function (root, d3, forester, phyloXml) {
 
         on(DYNAHIDE_CB, 'click', dynaHideCbClicked);
         on(MSA_CB, 'click', msaCbClicked);
+        on(HEATMAP_CB, 'click', heatmapCbClicked);
+        on(HEATMAP_ORDER_SELECT, 'change', heatmapOrderChanged);
+        on(HEATMAP_REORDER_BUTTON, 'click', showHeatmapReorderDialog);
         on(DOMAINS_CB, 'click', domainsCbClicked);
         on(UNCOLLAPSE_ALL_BUTTON, 'click', uncollapseAll);
         on(TREE_PREV_BUTTON, 'click', function () {
@@ -12736,6 +14117,8 @@ function (root, d3, forester, phyloXml) {
         on(TIME_GRID_CB, 'click', timeGridCbClicked);
 
         on(LAYOUT_RECT_BUTTON, 'click', layoutButtonClicked);
+        on(BRANCH_SCALE_TIME_BUTTON, 'click', branchScaleButtonClicked);
+        on(BRANCH_SCALE_DIV_BUTTON, 'click', branchScaleButtonClicked);
 
         on(LAYOUT_CIRC_BUTTON, 'click', layoutButtonClicked);
         on(LAYOUT_UNROOTED_BUTTON, 'click', layoutButtonClicked);
@@ -13156,6 +14539,15 @@ function (root, d3, forester, phyloXml) {
             h = h.concat(makeSegment(makeGlyph('aligned_phylogram'), PHYLOGRAM_ALIGNED_BUTTON, radioGroup, 'phylogram display (uses branch length values) with aligned labels'));
             h = h.concat(makeSegment(makeGlyph('cladogram'), CLADOGRAM_BUTTON, radioGroup, ' cladogram display (ignores branch length values)'));
             h = h.concat('</div>');
+            // The branch SCALE, when the tree states two different things: its
+            // nodes' dates, and its branches' divergence. Hidden otherwise,
+            // which is most trees.
+            h = h.concat('<div class="' + BRANCH_SCALE_CONTROLGROUP + ' aptx-segmented">');
+            h = h.concat(makeSegment('Time', BRANCH_SCALE_TIME_BUTTON, 'branch_scale_radio',
+                'branch lengths measure TIME (the nodes\' dates)'));
+            h = h.concat(makeSegment('Div', BRANCH_SCALE_DIV_BUTTON, 'branch_scale_radio',
+                'branch lengths measure DIVERGENCE (substitutions, as the file states them)'));
+            h = h.concat('</div>');
             h = h.concat('</div>');
             h = h.concat('</fieldset>');
             return h;
@@ -13249,6 +14641,9 @@ function (root, d3, forester, phyloXml) {
             if (_basicTreeProperties.domainArchitectures) {
                 opts.push(makeCheckboxItem('Domain Architectures', DOMAINS_CB, 'to show/hide the protein domain architectures beside the tips', true));
             }
+            if (heatmapAvailable()) {
+                opts.push(makeCheckboxItem('Heat Map', HEATMAP_CB, 'to show/hide a cell per tip and numeric field beside the tree, every column on one color scale; concentric rings in the circular layout (not in the unrooted one, where a column has no ring to be)'));
+            }
             if (_timeInfo && _timeInfo.type) {
                 opts.push(makeCheckboxItem('Time Axis', TIME_AXIS_CB, 'to show/hide the '
                     + (_timeInfo.type === 'geologic' ? 'geologic (ICS) time axis' : 'calendar time axis')
@@ -13357,6 +14752,45 @@ function (root, d3, forester, phyloXml) {
             return h;
         }
 
+        // Shown only while the Heat Map toggle is on (syncHeatmapControls).
+        // The desktop's View > Order Matrix Columns, minus its Manual mode --
+        // that one means "the order you dragged the rows into", and there is
+        // no drag-to-reorder dialog here to drag them in.
+        function makeHeatmapControls() {
+            let h = '<fieldset id="' + HEATMAP_CONTROLS + '" style="display:none">';
+            h = h.concat('<legend>Heat Map</legend>');
+            h = h.concat('<div class="aptx-domrow"><label class="aptx-domlabel" for="' + HEATMAP_ORDER_SELECT
+                + '">Order columns</label>');
+            h = h.concat('<select name="' + HEATMAP_ORDER_SELECT + '" id="' + HEATMAP_ORDER_SELECT
+                + '" title="how the matrix columns are ordered; a clustered order also draws the clustering above the matrix">');
+            // "input", not "file": the columns can come from a pasted tree or
+            // a joined table as easily as from a file, and a reader looking at
+            // a tree they dropped in would fairly ask "what file?". The title
+            // is filled in per tree by syncHeatmapControls, because whether
+            // this really IS the input's order depends on the input.
+            h = h.concat('<option value="document">As in the input</option>');
+            h = h.concat('<option value="clustered" title="columns whose values agree across the tips sit together:'
+                + ' complete-linkage clustering on Euclidean distance, the default of R\'s heat maps. A tip missing'
+                + ' either value is left out of that pair, never read as 0.">Clustered (co-occurrence)</option>');
+            h = h.concat('<option value="clustered-presence" title="columns found in the same tips sit together: a tip'
+                + ' where BOTH columns are 0 is left out of that pair, so two rare genes no longer look alike merely'
+                + ' for being rare. Complete-linkage clustering on the Bray-Curtis dissimilarity. For values that are'
+                + ' 0 or more.">Clustered (ignoring shared absence)</option>');
+            h = h.concat('<option value="alphabetical" title="by column name, ignoring case">Alphabetical</option>');
+            h = h.concat('<option value="frequency" title="highest mean value first, over the tips that have a value'
+                + ' -- on 0/1 data, the fraction of tips carrying it">Frequency</option>');
+            h = h.concat('<option value="manual" title="your own order, set with Reorder columns below. Nothing'
+                + ' re-sorts it.">Manual</option>');
+            h = h.concat('</select></div>');
+            h = h.concat('<div class="aptx-domrow"><span class="aptx-domlabel"></span>');
+            h = h.concat('<input type="button" class="aptx-widebtn" value="Reorder columns…" name="'
+                + HEATMAP_REORDER_BUTTON + '" id="' + HEATMAP_REORDER_BUTTON
+                + '" title="drag the columns into the order you want; doing so sets Manual">');
+            h = h.concat('</div>');
+            h = h.concat('</fieldset>');
+            return h;
+        }
+
         function makeSliders() {
             let h = "";
             h = h.concat('<fieldset>');
@@ -13537,7 +14971,9 @@ function (root, d3, forester, phyloXml) {
         setCheckboxValue(VIS_CB, _state.showVisualizations);
         setCheckboxValue(DYNAHIDE_CB, _state.dynahide);
         setCheckboxValue(MSA_CB, _state.showMsa);
+        setCheckboxValue(HEATMAP_CB, _state.showHeatmap);
         syncDomainControls();
+        syncHeatmapControls();
         setCheckboxValue(TIME_AXIS_CB, _state.showTimeAxis);
         setCheckboxValue(TIME_GRID_CB, _state.timeAxisGrid);
         setCheckboxValue(SHORTEN_NODE_NAME_CB, _state.shortenNodeNames);
@@ -13631,6 +15067,14 @@ function (root, d3, forester, phyloXml) {
             disableCheckbox('#' + PHYLOGRAM_BUTTON);
             disableCheckbox('#' + PHYLOGRAM_ALIGNED_BUTTON);
         }
+        setCheckboxValue(BRANCH_SCALE_TIME_BUTTON, _state.branchScale === 'time');
+        setCheckboxValue(BRANCH_SCALE_DIV_BUTTON, _state.branchScale !== 'time');
+        // most trees state only one thing, and a control offering a choice
+        // that does not exist is worse than no control
+        let scaleGroup = document.querySelector('.' + BRANCH_SCALE_CONTROLGROUP);
+        if (scaleGroup) {
+            scaleGroup.style.display = _branchScaleAvailable ? '' : 'none';
+        }
     }