archaeopteryx 3.14.0 → 3.16.0

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.14.0
+// v 3.16.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.14.0';
+    const VERSION = '3.16.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';
@@ -408,6 +408,20 @@ function (root, d3, forester, phyloXml) {
     const VIS_CB = 'vis_cb';
     const LADDERIZE_BUTTON = 'ladderize_b';
     const PHYLOGRAM_ALIGNED_BUTTON = 'phya_b';
+    // What the three display types DO, in one place: the tooltip, the reason a
+    // type is greyed, and the cheat-sheet row are all this sentence. A control
+    // named only after itself ("phylogram display (uses branch length
+    // values)") tells a reader who already knows what it is.
+    // Each says WHEN it is greyed, whether or not it is greyed now: that is a
+    // property of the control, not of the view, and a reader of the sheet in
+    // one layout is owed what happens in the others.
+    const PHYLOGRAM_WHAT = 'phylogram: branch lengths drawn to scale, so the tips end ragged.'
+        + ' Greyed in the circular layout, which always carries its labels to the outer ring,'
+        + ' so there the aligned phylogram is the one drawn';
+    const PHYLOGRAM_ALIGNED_WHAT = 'aligned phylogram: branch lengths to scale, with every tip'
+        + ' carried on to a common column, or in the circular layout to the outer ring.'
+        + ' Greyed in the unrooted layout, which has no column or ring to carry them to';
+    const CLADOGRAM_WHAT = 'cladogram: topology only, branch lengths ignored, every tip flush';
     const PHYLOGRAM_BUTTON = 'phy_b';
     const PHYLOGRAM_CLADOGRAM_CONTROLGROUP = 'phy_cla_g';
     const BRANCH_SCALE_CONTROLGROUP = 'branch_scale_g';
@@ -1481,6 +1495,26 @@ function (root, d3, forester, phyloXml) {
     // so the guess was what the reader saw every time.
     const HOVER_READOUT_GAP = 14;
 
+    // One way to open an external page. There were three: window.open + a
+    // win.focus() that throws when a popup blocker hands back null and which
+    // passed no noopener, an <a target="_blank" rel="noopener noreferrer">,
+    // and a third for the domain link. Three security postures for one job,
+    // and a change to the policy would have had to find all of them.
+    //
+    // noopener: the opened page must not get a handle on this window.
+    // noreferrer with it, since a tree can come from anywhere and its URL is
+    // not the external site's business.
+    function openExternal(url) {
+        if (!url) {
+            return null;
+        }
+        let win = window.open(url, '_blank', 'noopener,noreferrer');
+        if (win) {
+            win.focus();   // a blocked popup hands back null; that is not an error
+        }
+        return win;
+    }
+
     function placeHoverReadout(el, event) {
         let w = el.offsetWidth;
         let h = el.offsetHeight;
@@ -2319,12 +2353,23 @@ function (root, d3, forester, phyloXml) {
 
     let _legendMeasureCtx = null;
 
-    function legendTextWidth(text, font) {
+    // One lazily made canvas for every text measurement: the legend's widths,
+    // the branch-data line metrics and the sequence logo's glyph boxes each
+    // used to make their own.
+    function measureCtx() {
         if (!_legendMeasureCtx) {
             _legendMeasureCtx = document.createElement('canvas').getContext('2d');
         }
-        _legendMeasureCtx.font = font;
-        return _legendMeasureCtx.measureText(text).width;
+        return _legendMeasureCtx;
+    }
+
+    function legendTextWidth(text, font) {
+        let ctx = measureCtx();
+        if (!ctx) {
+            return 0;
+        }
+        ctx.font = font;
+        return ctx.measureText(text).width;
     }
 
     // The card's row order and cap, the desktop's way: rank by count first
@@ -2935,7 +2980,6 @@ function (root, d3, forester, phyloXml) {
             return {source: link.source.data, target: link.target.data};
         });
         _overviewLinks = links;   // the overview is built from these, not from the DOM
-        let gap = _state.nodeLabelGap;
 
         if (_state.phylogram === true) {
             _yScale = branchLengthScaling(forester.getAllExternalNodes(_root), _w);
@@ -3017,9 +3061,20 @@ function (root, d3, forester, phyloXml) {
         }
 
         if (_state.dynahide) {
-            if (_state.unrootedDisplay) {
-                // as on the desktop: no label auto-hiding in unrooted (there
-                // is no even row spacing to decimate against)
+            if (radialDisplay()) {
+                // The every-k-th DECIMATION does not run in either radial
+                // layout: it thins by index against even ROW spacing, which a
+                // fan does not have. An unrooted fan has no rows at all; a
+                // circular one has a ring, whose room is set by its
+                // circumference and not by the display's height. Measured on
+                // Caliciviridae_100 at 1100x850, the index rule kept 48 of 97
+                // names in circular while all 97 fitted the ring with NOT ONE
+                // overlapping pair, and on flu_h5 it kept 59 of 354 where 118
+                // are readable. (118 is the shipped rule measured; 100 was a
+                // greedy estimate in DOM order made before it was built, and
+                // is what this comment said until a review caught it against
+                // README and CHANGELOG.) Both are now thinned by hideCrowdedTipLabels
+                // instead, on whether the names actually overprint.
                 forester.preOrderTraversal(_root, function (n) {
                     n.hide = false;
                 });
@@ -3031,8 +3086,6 @@ function (root, d3, forester, phyloXml) {
                 });
             }
         }
-        syncDynahideIndicator(_state.dynahide && !_state.unrootedDisplay && _dynahide_factor >= 2);
-
         updateButtonEnabledState();
 
         // Only the nodes with something drawn for them individually get a
@@ -3099,11 +3152,10 @@ function (root, d3, forester, phyloXml) {
                 return makeFoundOutlineColor(d) ? '0.9px' : null;
             })
             .style('paint-order', 'stroke')
+            // anchor, dy and x all come from nodeLabelPlacement, which the
+            // occupancy box is built from too
             .attr('text-anchor', function (d) {
-                if (radialDisplay()) {
-                    return labelFlip(d) ? 'end' : 'start';
-                }
-                return d.children ? 'end' : 'start';
+                return nodeLabelPlacement(d).anchor;
             })
             .attr('transform', function (d) {
                 if (_state.unrootedDisplay) {
@@ -3131,42 +3183,10 @@ function (root, d3, forester, phyloXml) {
                 return 'rotate(' + labelAngleDeg(d) + ') translate(' + off + ',0)' + (labelFlip(d) ? ' rotate(180)' : '');
             })
             .attr('dy', function (d) {
-                if (radialDisplay()) {
-                    return '0.32em';
-                }
-                if (d.children) {
-                    // the desktop's above-branch internal label: the baseline
-                    // is lifted so the glyph bottoms sit just clear of the
-                    // horizontal branch line, instead of straddling it
-                    return -(Math.round(0.2 * _state.internalNodeFontSize) + 1) + 'px';
-                }
-                return 0.3 * _state.externalNodeFontSize + 'px';
+                return nodeLabelPlacement(d).dy + 'px';
             })
             .attr('x', function (d) {
-                if (radialDisplay()) {
-                    return labelFlip(d) ? -gap : gap;
-                }
-                if (!(d.children)) {
-                    if (_state.phylogram && _state.alignPhylogram) {
-                        return (-_yScale(d.distToRoot) + _w + gap);
-                    } else {
-                        return gap;
-                    }
-                } else {
-                    // right-aligned so the label ends just left of the node
-                    // (the desktop's publication-style placement); a long
-                    // label on a node near the root shifts right so its
-                    // leading characters stay on the canvas rather than
-                    // clipping off the left edge
-                    let label = makeNodeLabel(d) || '';
-                    let est = label.length * _state.internalNodeFontSize * 0.55;
-                    let leftmost = d.y - gap - est;
-                    let minX = 2 - _settings.rootOffset;
-                    if (leftmost < minX) {
-                        return -gap + (minX - leftmost);
-                    }
-                    return -gap;
-                }
+                return nodeLabelPlacement(d).x;
             });
 
         node.select('text.bllabel')
@@ -3178,7 +3198,11 @@ function (root, d3, forester, phyloXml) {
             .attr('transform', function (d) {
                 return radialDisplay() ? branchLabelTransform(d) : null;
             })
-            .attr('dy', '-.25em')
+            // Every one of these three reads its offset from branchMarkPlacement,
+            // the same function the occupancy boxes are built from: a box that is
+            // not where the text is hides the wrong marks, and two copies of the
+            // same number drift apart the first time one of them is edited.
+            .attr('dy', branchMarkPlacement('bl', _state.branchDataFontSize).dy)
             .attr('x', function (d) {
                 if (radialDisplay()) {
                     return 0;
@@ -3199,7 +3223,7 @@ function (root, d3, forester, phyloXml) {
             .attr('transform', function (d) {
                 return radialDisplay() ? branchLabelTransform(d) : null;
             })
-            .attr('dy', _state.branchDataFontSize)
+            .attr('dy', branchMarkPlacement('conf', _state.branchDataFontSize).dy)
             .attr('x', function (d) {
                 if (radialDisplay()) {
                     return 0;
@@ -3235,7 +3259,7 @@ function (root, d3, forester, phyloXml) {
             .attr('transform', function (d) {
                 return radialDisplay() ? branchLabelTransform(d) : null;
             })
-            .attr('dy', '-.25em')
+            .attr('dy', branchMarkPlacement('event', _state.branchDataFontSize).dy)
             .attr('x', function (d) {
                 if (radialDisplay()) {
                     return 0;
@@ -3326,7 +3350,7 @@ function (root, d3, forester, phyloXml) {
         // a collapsed clade's label always shows, so its guide does too: from
         // past the wedge's farthest tip to the label column
         let collapsedGuides = alignedRect ? nodes.filter(function (d) {
-            return isCollapsed(d) && !(_state.dynahide && d.hide);
+            return isCollapsed(d) && nameDrawn(d);
         }) : [];
         if (tipGuides || collapsedGuides.length > 0) {
             let ext = _svgGroup.insert('g', 'g').attr('class', 'aptx-align-ext');
@@ -3339,7 +3363,7 @@ function (root, d3, forester, phyloXml) {
             if (tipGuides) {
                 guideStyle(ext.selectAll('path.aptx-tip-guide')
                     .data(links.filter(function (d) {
-                        return (!d.target.children && !(_state.dynahide && d.target.hide));
+                        return (!d.target.children && nameDrawn(d.target));
                     }))
                     .enter().append('path').attr('class', 'aptx-tip-guide'))
                     .attr('d', function (d) {
@@ -3362,7 +3386,7 @@ function (root, d3, forester, phyloXml) {
             // tips while their labels show; a collapsed clade always (its label
             // always shows), from its wedge's farthest reach out to the ring
             let connected = nodes.filter(function (d) {
-                if (_state.dynahide && d.hide) {
+                if (!nameDrawn(d)) {
                     return false;
                 }
                 if (isCollapsed(d)) {
@@ -3820,6 +3844,420 @@ function (root, d3, forester, phyloXml) {
     // a support dot. Returns the nodes that need a <g> -- those with any of
     // them, and every collapsed clade (its wedge and label). The rest are
     // drawn entirely by drawTreeGeometry's batched paths.
+    // ===================== Crowded branch data =====================
+    // A branch-anchored mark is drawn only when its box does not overlap one
+    // already granted in the same pass. Ported from the desktop's
+    // LabelOccupancy (0.11.161) as a JOINT rule on Christian's word,
+    // 2026-09-25: "match the desktop's new auto-hide rule for crowded branch
+    // data". Neither side retunes it alone.
+    //
+    // It exists because the obvious rule does not work. The desktop built
+    // "hide when the branch is drawn shorter than the text" first and measured
+    // it: on an 825-tip tree a third-of-text threshold hid 285 numbers of
+    // which only 51 collided, and still left 22 pile-ups. A number is
+    // unreadable when it overlaps ANOTHER number, which depends on closeness
+    // in y as much as in x, and branch length only sees x. Measured here
+    // before adopting it: with Auto-hide Labels already ON, 240 of 267 drawn
+    // support numbers overlapped another on flu_h5.xml (90%), 149 of 262 on
+    // Adenoviridae, 13 of 119 on bcl2 -- our auto-hide only thinned TIP labels
+    // then, and had never touched branch data.
+    //
+    // WHAT MUST MATCH, or the two viewers drop different marks:
+    //  - the tie-break: PREORDER, first claim wins, so the mark nearer the
+    //    root keeps its place. d3's descendants() is preorder already.
+    //  - TWO maps, numbers and symbols. The symbol sits ON the branch and the
+    //    numbers just above and below it, so one shared map would let a
+    //    branch's own symbol block its own numbers.
+    //  - a refused claim records NOTHING, so a rejected mark never blocks a
+    //    later one.
+    //  - a zero-size box is granted and not recorded.
+    //  - symbols are never shrunk to fit: in a size-scaled mode the diameter
+    //    IS the support, and a smaller dot would report weaker support.
+    //
+    // WHAT CANNOT MATCH, and is not meant to: the COUNTS. The boxes come from
+    // each program's own font metrics, so the same tree at the same size drops
+    // a similar but not identical set. The rule is the contract; the tally is
+    // not.
+    //
+    // Where a branch-anchored mark sits, in the tree group's coordinates.
+    // Mirrors the placement in syncOptionalNodeChildren exactly -- the branch
+    // length back toward the parent and above the branch, the confidence at
+    // the branch midpoint and below it -- because a box that is not where the
+    // text is would hide the wrong marks.
+    // The font's LINE box, which is what the marks are laid out with and what
+    // the desktop measures too (FontMetrics.getHeight()). Not the per-glyph
+    // ink box: two numbers collide when their lines overlap, and ink boxes
+    // would let "1" slide under "0.81".
+    //
+    // Measured from the font rather than assumed. The fallback is what this
+    // font actually reports at 9px -- ascent 9, descent 2, line 11 -- read off
+    // a rendered label's getBBox rather than guessed.
+    let _fontMetricsCache = new Map();
+
+    // how many names the radial overlap rule took on the last render, for the
+    // Auto-hide indicator: those layouts thin by overlap, not by index, so
+    // _dynahide_factor says nothing about them
+    let _radialNamesHidden = 0;
+
+    // and how many branch marks the crowding rule refused on the last render.
+    // The switch governs three things -- the every-k-th thinning, the radial
+    // overlap thinning and the branch-data rule -- and the indicator used to
+    // ask only about names, so a view where every name fitted but 201 numbers
+    // were being refused showed a dark toggle over a tree it was thinning.
+    // (Caliciviridae circular; apaf RECTANGULAR did it too, so this half was
+    // never right in any layout.)
+    let _branchMarksHidden = 0;
+
+    function branchFontMetrics(fontPx) {
+        // One cache for every size asked for, not one slot: labels and branch
+        // marks run at different sizes in the same pass, and a single slot
+        // would re-measure on every alternation.
+        let hit = _fontMetricsCache.get(fontPx);
+        if (hit) {
+            return hit;
+        }
+        let ctx = measureCtx();
+        ctx.font = fontPx + 'px ' + FONT_DEFAULTS;
+        let m = ctx.measureText('0');
+        let ascent = m.fontBoundingBoxAscent;
+        let descent = m.fontBoundingBoxDescent;
+        // Both, separately: a canvas that reports an ascent and no descent
+        // would give height = ascent + undefined = NaN, every box would be
+        // refused a claim as zero-sized, and the feature would turn itself off
+        // with no error and a green suite.
+        if (!(ascent > 0)) {
+            ascent = fontPx;
+        }
+        if (!(descent >= 0)) {
+            descent = fontPx * (2 / 9);
+        }
+        let metrics = {px: fontPx, ascent: ascent, descent: descent,
+            height: ascent + descent};
+        _fontMetricsCache.set(fontPx, metrics);
+        return metrics;
+    }
+
+    // Where a branch mark sits on its branch, read off the rendered elements
+    // rather than inferred: the horizontal anchor and the `dy` the element is
+    // drawn with. Getting either wrong is not a rounding error. A
+    // middle-anchored box modelled as left-anchored is half its own width out,
+    // which once let 44% of the granted numbers still overlap; and a branch
+    // EVENT sits a quarter em ABOVE the line like the branch length, not a
+    // font size below it like the confidence, so modelling it as a confidence
+    // put its box on the wrong side of the branch -- the one side it could
+    // never collide on.
+    function branchMarkPlacement(kind, fontPx) {
+        if (kind === 'conf') {
+            return {mid: true, dy: fontPx};
+        }
+        if (kind === 'event') {
+            // A radial layout draws every mark on ONE point, the branch's
+            // midpoint, so a branch event and a branch length -- both a quarter
+            // em above the line -- printed straight through each other. The
+            // event is lifted a whole line clear of the length. The rectangular
+            // layout already separates them along the branch (the length at the
+            // parent end, the event at the middle), so there they share a line.
+            return {mid: true, dy: radialDisplay()
+                ? ((-0.25 * fontPx) - branchFontMetrics(fontPx).height)
+                : (-0.25 * fontPx)};
+        }
+        return {mid: false, dy: -0.25 * fontPx};   // 'bl': start-anchored, a quarter em up
+    }
+
+    // The incoming branch's MIDPOINT and screen direction, in the tree group's
+    // own coordinates -- what a radial mark is actually drawn on, since
+    // branchLabelTransform rotates to the spoke and translates half a branch
+    // back along it. Circular: the leg runs along ONE spoke, so the midpoint is
+    // the mean of the two radii at the same angle (an arc's chord is not on the
+    // leg). Unrooted: the branch is a straight line, so it is the mean of the
+    // two points. Both match the desktop's two call sites of
+    // paintBranchDataRadial.
+    function radialBranchMid(d) {
+        let angle = spokeAngle(d);
+        if (_state.unrootedDisplay) {
+            if (d.ux === undefined) {
+                return null;
+            }
+            let p = (d.parent && d.parent.ux !== undefined) ? d.parent : null;
+            return p ? [0.5 * (d.ux + p.ux), 0.5 * (d.uy + p.uy), angle] : [d.ux, d.uy, angle];
+        }
+        let r = radialRadius(d.y);
+        if (d.parent) {
+            r = 0.5 * (r + radialRadius(d.parent.y));
+        }
+        let pt = polarXY(radialAngle(d.x), r);
+        return [pt[0], pt[1], angle];
+    }
+
+    function branchMarkBox(d, kind, text, fontPx) {
+        let w = legendTextWidth(text, fontPx + 'px ' + FONT_DEFAULTS);
+        let fm = branchFontMetrics(fontPx);
+        let h = fm.height;
+        let at = branchMarkPlacement(kind, fontPx);
+        if (radialDisplay()) {
+            // The mark rides the branch, so its box is the AXIS-ALIGNED bounds
+            // of the rotated rectangle, centred where the text's own centre
+            // lands: forester.rotatedLabelBox, which carries the desktop's
+            // formula and the reasons it is the conservative one.
+            let mid = radialBranchMid(d);
+            if (!mid) {
+                return null;
+            }
+            // `dy` shifts the BASELINE, so the box's centre sits half a line
+            // below it; and the 180-degree flip that keeps the far half of the
+            // fan upright carries this perpendicular offset with it.
+            let off = at.dy + (0.5 * (fm.descent - fm.ascent));
+            if (labelFlip(d)) {
+                off = -off;
+            }
+            // every radial mark is middle-anchored at x=0, so only the
+            // perpendicular offset moves its centre off the branch midpoint
+            return forester.rotatedLabelBox(mid[0] - (Math.sin(mid[2]) * off),
+                mid[1] + (Math.cos(mid[2]) * off), w, h, mid[2]);
+        }
+        // The ROOT's numbers are drawn too, at x=0 in its own group, and they
+        // used to claim nothing -- so the first child's number, landing in
+        // almost the same place, was granted and painted over them. The one
+        // place the pass could not keep its promise.
+        let span = d.parent ? (d.parent.y - d.y) : 0;
+        let x = at.mid
+            ? (d.y + (0.5 * span) - (w / 2))          // middle-anchored
+            : (d.y + span + 1);                       // start-anchored
+        return [x, (d.x + at.dy) - fm.ascent, w, h];
+    }
+
+    // ---- the node's own label: one source for drawing it and for reserving
+    // its space ----
+    //
+    // The three attributes below (text-anchor, x, dy) and the occupancy box
+    // that keeps branch numbers off the name are the same decision, so they
+    // are made once here. Modelled after branchMarkPlacement, and for the same
+    // reason: a box that is not where the text is reserves the wrong space,
+    // and two copies of the arithmetic drift the first time one is edited.
+    function nodeLabelPlacement(d) {
+        let gap = _state.nodeLabelGap;
+        if (radialDisplay()) {
+            let flip = labelFlip(d);
+            return {anchor: flip ? 'end' : 'start', x: flip ? -gap : gap,
+                dy: 0.32 * nodeLabelFontSize(d)};
+        }
+        if (!d.children) {
+            let x = (_state.phylogram && _state.alignPhylogram)
+                ? (-_yScale(d.distToRoot) + _w + gap)
+                : gap;
+            return {anchor: 'start', x: x, dy: 0.3 * _state.externalNodeFontSize};
+        }
+        // the desktop's above-branch internal label: right-aligned so it ends
+        // just left of the node, and shifted right when a long label on a node
+        // near the root would otherwise clip off the left edge
+        let label = makeNodeLabel(d) || '';
+        let est = label.length * _state.internalNodeFontSize * 0.55;
+        let leftmost = d.y - gap - est;
+        let minX = 2 - _settings.rootOffset;
+        let x = (leftmost < minX) ? (-gap + (minX - leftmost)) : -gap;
+        return {anchor: 'end', x: x,
+            dy: -(Math.round(0.2 * _state.internalNodeFontSize) + 1)};
+    }
+
+    // The size the label is actually drawn at: a per-node style overrides the
+    // internal/external default, and the box has to follow it or a styled
+    // tree reserves the wrong space.
+    function nodeLabelFontSize(d) {
+        let style = nodeStyle(d);
+        if (style && style.fontSize) {
+            return style.fontSize;
+        }
+        return d.children ? _state.internalNodeFontSize : _state.externalNodeFontSize;
+    }
+
+    // The label's rectangle in the tree group's coordinates, as a start point
+    // on the baseline, a direction the text runs in, and its extents.
+    // Returns null when there is no label drawn.
+    function nodeLabelGeometry(d) {
+        let text = d._extLabelText;
+        if (!text) {
+            return null;
+        }
+        let fontPx = nodeLabelFontSize(d);
+        let style = nodeStyle(d);
+        let bold = getFoundColor(d)
+            || (style && (style.fontStyle === 'bold' || style.fontStyle === 'bold_italic'));
+        let w = legendTextWidth(text, (bold ? 'bold ' : '') + fontPx + 'px ' + FONT_DEFAULTS);
+        let fm = branchFontMetrics(fontPx);
+        let p = nodeLabelPlacement(d);
+        let at = layoutPointXY(d);
+        if (at[0] === undefined || at[1] === undefined) {
+            return null;   // not laid out (an unrooted node the layout never reached)
+        }
+        if (!radialDisplay() || _radialLabelsHorizontal) {
+            // upright text, whatever the layout: one axis-aligned rectangle
+            let base = at;
+            if (_state.circularDisplay && _radialLabelsHorizontal && !d.children && _radial) {
+                // the label rides out to its point on the ring, in screen terms
+                base = polarXY(radialAngle(d.x), _radial.maxRad);
+            }
+            let x0 = base[0] + p.x - (p.anchor === 'end' ? w : 0);
+            return {x: x0, y: (base[1] + p.dy) - fm.ascent, w: w, h: fm.height, angle: 0};
+        }
+        // Radial: the text starts a gap beyond the node (or beyond the ring,
+        // for a circular tip) and runs OUTWARD along the spoke -- on both
+        // halves of the fan, because the 180-degree flip that keeps the far
+        // half upright also reverses which end the anchor is.
+        //
+        // Built as an offset FROM THE NODE, not as a distance from the origin.
+        // A circular node lies on the ray its label runs along, so radius
+        // arithmetic happens to work there; an unrooted one does not -- its
+        // spoke angle is the direction its own branch came in at, which has
+        // nothing to do with its bearing from the centre. Measured with the
+        // radius version: unrooted still had 7 of 12 numbers printing through
+        // a name on flu_h5, because the boxes were being reserved in places
+        // no label was.
+        let theta = spokeAngle(d);
+        let along = _state.nodeLabelGap;
+        if (_state.circularDisplay && !d.children && _radial) {
+            along += _radial.maxRad - radialRadius(d.y);   // the pull out to the ring
+        }
+        let flip = labelFlip(d);
+        // the baseline offset is perpendicular to the text, and the flip
+        // carries it across with everything else
+        let off = flip ? -p.dy : p.dy;
+        let top = flip ? (off - fm.descent) : (off - fm.ascent);
+        let cos = Math.cos(theta), sin = Math.sin(theta);
+        return {x: at[0] + (cos * along) - (sin * top),
+            y: at[1] + (sin * along) + (cos * top),
+            w: w, h: fm.height, angle: theta};
+    }
+
+    // The label's own outline, as four corners in the tree group's
+    // coordinates: what the turned-box occupancy tests against.
+    function nodeLabelQuad(g) {
+        if (!g || !(g.w > 0) || !(g.h > 0)) {
+            return null;
+        }
+        let cos = Math.cos(g.angle), sin = Math.sin(g.angle);
+        let corners = [[0, 0], [g.w, 0], [g.w, g.h], [0, g.h]];
+        let quad = [];
+        for (let i = 0; i < corners.length; ++i) {
+            quad.push([g.x + (cos * corners[i][0]) - (sin * corners[i][1]),
+                g.y + (sin * corners[i][0]) + (cos * corners[i][1])]);
+        }
+        return quad;
+    }
+
+    // ---- crowded TIP LABELS, in both radial layouts ----
+    //
+    // The desktop's rule: a tip label is drawn only if its own outline overlaps
+    // no label already drawn this pass. Both fans use it; the rectangular
+    // layout keeps the every-k-th thinning, whose row pitch is a real quantity
+    // there.
+    //
+    // Unrooted had nothing at all before this -- its labels sit wherever the
+    // equal-angle layout put the tip. Circular had the rectangular rule, which
+    // reads the display's HEIGHT against the node count and says nothing about
+    // a ring: it kept 48 of 97 names on Caliciviridae where all 97 fit with no
+    // overlap, and 59 of 354 on flu_h5 where 118 are readable.
+    //
+    // A SEARCH HIT is placed without being asked, so it can be drawn across a
+    // name already down -- intended (the hit is what is being looked for), and
+    // measured: a 3-hit search on confidences unrooted puts 3 hits across
+    // non-hits, 8.1 px deep. It is the one case where "drawn only where it
+    // overlaps nothing" does not hold, and the README says so.
+    // Measured at 1100x850 before this, overlapping pairs among the labels
+    // drawn: 172 of 97 labels on Caliciviridae_100, 71 of 42 on confidences,
+    // 10 of 31 on apaf -- clumps of a dozen names printed through each other.
+    //
+    // OUTLINES, not their axis-aligned bounds: a name lying near its spoke has
+    // bounds several times its own area, and on a 48-label ring those bounds
+    // called 28 pairs crowded where a reader sees none.
+    //
+    // Order is the tree's own, root first (forester.preorderOf), which is also
+    // what the desktop's unrooted painter does -- it reaches an internal node
+    // before its subtree -- so both programs keep the same label when two
+    // contend. A search HIT is placed without being asked, so the name being
+    // looked for is always on the screen and everything after it keeps clear
+    // of it (Christian, 2026-09-26: hits are exempt for tip labels, and for
+    // nothing else).
+    // Is this node's name on the screen? Asked by everything drawn to a label
+    // -- the aligned guides, the circular ring connectors -- and it must be
+    // ONE question. It used to be spelled `_state.dynahide && d.hide`, which
+    // is the every-k-th rule and nothing else: when the radial layouts started
+    // hiding by overlap they left `hide` false for everyone, so on flu_h5 in
+    // circular 354 dashed connectors ran out to the ring for 118 names, 236 of
+    // them ending at nothing. `_labelDropped` is set by BOTH rules.
+    function nameDrawn(d) {
+        return !d._labelDropped;
+    }
+
+    function hideCrowdedTipLabels(nodes) {
+        _radialNamesHidden = 0;
+        if (!_state.dynahide || !radialDisplay()) {
+            return;
+        }
+        // no layout, no honest outlines; bailing draws everything
+        if (_state.unrootedDisplay ? !_unroot : !_radial) {
+            return;
+        }
+        let labels = forester.orientedOccupancy(Math.max(4, _state.externalNodeFontSize));
+        let ordered = forester.preorderOf(nodes);
+        for (let i = 0, len = ordered.length; i !== len; ++i) {
+            let d = ordered[i];
+            if (d.children || d._extLabelText === '') {
+                continue;
+            }
+            let quad = nodeLabelQuad(nodeLabelGeometry(d));
+            if (!quad) {
+                continue;
+            }
+            if (getFoundColor(d)) {
+                labels.occupy(quad);
+            } else if (!labels.claim(quad)) {
+                d._extLabelText = '';
+                d._labelDropped = true;
+                ++_radialNamesHidden;
+            }
+        }
+    }
+
+    // The boxes to reserve for a label. An upright label is one rectangle. A
+    // rotated one is reserved as a RUN of short boxes along its baseline,
+    // never as one axis-aligned box around the whole thing: the bounds of a
+    // rotated rectangle grow with its LENGTH, so a 120 px name lying at 30
+    // degrees would reserve several times its own area. Stepping by the line
+    // height bounds the error at one step whatever the name is.
+    //
+    // Honestly measured: the run and the single box draw the SAME numbers on
+    // every tree tried (apaf, Caliciviridae, confidences) bar one -- flu_h5
+    // unrooted, 4 against 3 -- and a purpose-built sparse fixture with 28-
+    // character names could not separate them at all
+    // (test_trees/label_reservation.html). The views that would show the
+    // difference are already saturated, and the ones with room refuse nothing
+    // either way. It is kept for the bound, not for the count: the error of
+    // the single box grows without limit as names get longer, and this is
+    // ten lines.
+    function nodeLabelClaimBoxes(g) {
+        if (!g || !(g.w > 0) || !(g.h > 0)) {
+            return [];
+        }
+        if (g.angle === 0) {
+            return [[g.x, g.y, g.w, g.h]];
+        }
+        let cos = Math.cos(g.angle), sin = Math.sin(g.angle);
+        let step = Math.max(4, g.h);
+        let boxes = [];
+        for (let t = 0; t < g.w; t += step) {
+            let len = Math.min(step, g.w - t);
+            // the four corners of this slice, in tree coordinates
+            let xs = [], ys = [];
+            for (const [a, b] of [[t, 0], [t + len, 0], [t + len, g.h], [t, g.h]]) {
+                xs.push(g.x + (cos * a) - (sin * b));
+                ys.push(g.y + (sin * a) + (cos * b));
+            }
+            let x0 = Math.min(...xs), y0 = Math.min(...ys);
+            boxes.push([x0, y0, Math.max(...xs) - x0, Math.max(...ys) - y0]);
+        }
+        return boxes;
+    }
+
     function prepareNodeDrawing(nodes) {
         let wantBl = _state.showBranchLengthValues === true;
         let wantConf = _state.showConfidenceValues === true || _state.showMadValues === true;
@@ -3836,11 +4274,30 @@ function (root, d3, forester, phyloXml) {
             }
             // Empty is the common case on a big tree: Auto-hide Labels blanks
             // them exactly when there are most nodes to blank.
-            d._extLabelText = (!_state.dynahide || !d.hide) ? (makeNodeLabel(d) || '') : '';
+            // WHY the text is empty matters downstream: a label the crowding
+            // rule took away is a different thing from a label the user
+            // switched off, and marks that accompany a name must tell them
+            // apart (drawDomainArchitectures).
+            d._labelDropped = _state.dynahide === true && d.hide === true;
+            d._extLabelText = d._labelDropped ? '' : (makeNodeLabel(d) || '');
             d._blText = wantBl ? asText(makeBranchLengthLabel(d)) : '';
             d._confText = wantConf ? asText(makeConfidenceValuesLabel(d)) : '';
             d._eventText = wantEvent ? asText(makeBranchEventsLabel(d)) : '';
             d._suppDot = wantDot && showSupportDot(d);
+        }
+        // Before `drawn` is built, not after: a refused mark used to leave a
+        // childless <g class="node"> behind, and those are transformed on
+        // every animation frame. On the big tree that was ~18,000 empty groups
+        // per redraw, defeating the very thing the `drawn` filter is for.
+        // names first: the ones that survive then reserve their space inside
+        // hideCrowdedBranchData, and the marks are placed against what is left
+        hideCrowdedTipLabels(nodes);
+        hideCrowdedBranchData(nodes);
+        // told after the rules have run, not before: what the unrooted rule
+        // hid is only known once it has looked at the labels
+        syncDynahideIndicator();
+        for (let i = 0, len = nodes.length; i !== len; ++i) {
+            let d = nodes[i];
             if (d._extLabelText !== '' || d._blText !== '' || d._confText !== ''
                 || d._eventText !== '' || d._suppDot || isCollapsed(d)) {
                 drawn.push(d);
@@ -3849,6 +4306,144 @@ function (root, d3, forester, phyloXml) {
         return drawn;
     }
 
+    // The occupancy pass, in PREORDER -- so the mark nearer the root claims
+    // its space first and keeps it. NOT the order the layout hands out: d3's
+    // descendants() is breadth-first and the viewer reverses it for drawing,
+    // which puts the root LAST and inverts the entire tie-break. That shipped,
+    // and a review caught it; forester.preorderOf derives the right order from
+    // the nodes themselves.
+    //
+    // Runs before anything is drawn, so the decision cannot depend on the
+    // order the DOM happens to be updated in.
+    //
+    // Rides the existing Auto-hide Labels toggle: switch it off and everything
+    // is drawn. Runs in ALL THREE layouts, as the desktop does -- the boxes are
+    // built in the tree group's own coordinates, which is where every mark is
+    // actually drawn, so the circular and unrooted views are measured in their
+    // own space and not in the cluster's. (The tip-label decimation that shares
+    // the toggle runs in the rectangular layout alone; both fans have no rows
+    // to decimate against, and hideCrowdedTipLabels thins their names by
+    // overlap instead, running before this does.)
+    function hideCrowdedBranchData(nodes) {
+        if (!_state.dynahide) {
+            return;
+        }
+        // No layout state, no honest boxes. Bailing out draws everything; going
+        // on would put every mark at the origin, where they all overlap and all
+        // but the first would be hidden -- a blank tree, with no error.
+        if ((_state.circularDisplay && !_radial) || (_state.unrootedDisplay && !_unroot)) {
+            return;
+        }
+        _branchMarksHidden = 0;
+        // Each granted mark's claimed box is kept on the node, as a label's is
+        // (_labelBoxes). Names have had an ink-coverage check since the
+        // reservation went in -- every point of a drawn name must lie inside
+        // the space it claimed -- and branch MARKS never did, which is the
+        // half that failed on a Linux CI runner while the label half passed.
+        for (let i = 0; i < nodes.length; ++i) {
+            nodes[i]._markBoxes = null;
+        }
+        let stash = function (d, kind, box) {
+            if (!box) {
+                return;
+            }
+            if (!d._markBoxes) {
+                d._markBoxes = {};
+            }
+            d._markBoxes[kind] = box;
+        };
+        let fontPx = _state.branchDataFontSize;
+        let dotCell = 0;
+        for (let i = 0; i < nodes.length; ++i) {
+            if (nodes[i]._suppDot) {
+                dotCell = Math.max(dotCell, 2 * supportDotRadius(nodes[i]));
+            }
+        }
+        let cell = Math.max(fontPx, dotCell);
+        let numbers = forester.labelOccupancy(cell);
+        let symbols = forester.labelOccupancy(cell);
+        let ordered = forester.preorderOf(nodes);
+
+        // THE NAMES GO DOWN FIRST, and they are not asked: a node label is
+        // drawn whatever else is there, so it reserves its space with occupy
+        // rather than claim. Everything below is then refused against it, and
+        // names outrank numbers -- the desktop's order, and the one a reader
+        // expects, since a name is what the tree is for and a value that has
+        // printed through one is worse than a value not drawn at all.
+        //
+        // Measured before this existed, at 1100x850 with both numbers on:
+        // 44 of 93 numbers printed through a name on flu_h5 in the
+        // rectangular layout, 30 of 55 on confidences, 10 of 15 unrooted.
+        // The 3.15.0 pass kept numbers off each OTHER and off nothing else.
+        for (let i = 0, len = ordered.length; i !== len; ++i) {
+            let boxes = nodeLabelClaimBoxes(nodeLabelGeometry(ordered[i]));
+            // kept on the node, beside the other per-render drawing state, so
+            // the reservation can be compared with the ink it is supposed to
+            // cover: a box that is merely SMALL -- short by a descent, or a
+            // few per cent narrow -- still hides nothing wrongly and still
+            // shows no overlap anywhere a number does not happen to sit. The
+            // desktop pins the same property pixel by pixel.
+            ordered[i]._labelBoxes = boxes.length ? boxes : null;
+            for (let b = 0; b < boxes.length; ++b) {
+                numbers.occupy(boxes[b][0], boxes[b][1], boxes[b][2], boxes[b][3]);
+                symbols.occupy(boxes[b][0], boxes[b][1], boxes[b][2], boxes[b][3]);
+            }
+        }
+
+        for (let i = 0, len = ordered.length; i !== len; ++i) {
+            let d = ordered[i];
+            // Branch length first, then confidence: they sit on opposite sides
+            // of the branch, so they rarely contend, but the order decides
+            // which survives when they do.
+            if (d._blText !== '') {
+                let b = branchMarkBox(d, 'bl', d._blText, fontPx);
+                if (b && !numbers.claim(b[0], b[1], b[2], b[3])) {
+                    d._blText = '';
+                    ++_branchMarksHidden;
+                } else {
+                    stash(d, 'bl', b);
+                }
+            }
+            if (d._confText !== '') {
+                let b = branchMarkBox(d, 'conf', d._confText, fontPx);
+                if (b && !numbers.claim(b[0], b[1], b[2], b[3])) {
+                    d._confText = '';
+                    ++_branchMarksHidden;
+                } else {
+                    stash(d, 'conf', b);
+                }
+            }
+            // Branch EVENTS are branch-anchored too, half a branch from the
+            // branch length and on the same side of it, so they can land on
+            // the same pixels. Left out of the map, they neither refused a
+            // number nor were refused by one, and the pass reported "no
+            // overlapping marks" while the user could see two.
+            if (d._eventText !== '') {
+                let b = branchMarkBox(d, 'event', d._eventText, fontPx);
+                if (b && !numbers.claim(b[0], b[1], b[2], b[3])) {
+                    d._eventText = '';
+                    ++_branchMarksHidden;
+                } else {
+                    stash(d, 'event', b);
+                }
+            }
+            if (d._suppDot) {
+                // never shrunk to fit: in a size-scaled mode the diameter IS
+                // the support value, and a smaller dot reports weaker support
+                let r = supportDotRadius(d);
+                // showSupportDot already required a parent; a circle's bounds
+                // do not rotate, so the radial case needs only the midpoint
+                let at = radialDisplay()
+                    ? radialBranchMid(d)
+                    : [d.y + (0.5 * (d.parent.y - d.y)), d.x];
+                if (at && !symbols.claim(at[0] - r, at[1] - r, 2 * r, 2 * r)) {
+                    d._suppDot = false;
+                    ++_branchMarksHidden;
+                }
+            }
+        }
+    }
+
     function syncOptionalNodeChildren(node) {
         let wantBl = _state.showBranchLengthValues === true;
         let wantConf = _state.showConfidenceValues === true || _state.showMadValues === true;
@@ -4877,8 +5472,12 @@ function (root, d3, forester, phyloXml) {
         showTaxonomyButton: 'shown automatically when the tree has taxonomies',
         showSequenceButton: 'shown automatically when the tree has sequences',
         showBranchColorsButton: 'the Visual Styles checkbox appears when the tree has branch colours or style properties',
-        showDynahideButton: 'shown automatically once the tree has enough tips to need it',
-        showShortenNodeNamesButton: 'shown automatically when the tree has long node names',
+        // These two are ALWAYS offered, deliberately: they do nothing on a tree
+        // that needs neither, and a control that comes and goes between trees
+        // is worse than one that is simply there. (Both messages used to
+        // promise a conditional appearance the code had already rejected.)
+        showDynahideButton: 'the Auto-hide Labels checkbox is always shown',
+        showShortenNodeNamesButton: 'the Short Names checkbox is always shown; it starts on when the tree has long node names',
         showExternalLabelsButton: 'always shown',
         showInternalLabelsButton: 'shown automatically when the tree has internal node data',
         // the collapse-by-depth / rank / feature feature is gone
@@ -6379,8 +6978,7 @@ function (root, d3, forester, phyloXml) {
                 }
 
                 if (url) {
-                    let win = window.open(url, '_blank');
-                    win.focus();
+                    openExternal(url);
                 } else {
                     // Not a programming error -- the user clicked and there is
                     // simply nowhere to go -- so this one gets told in the same
@@ -6880,11 +7478,9 @@ function (root, d3, forester, phyloXml) {
         if (_logoGlyphs[ch]) {
             return _logoGlyphs[ch];
         }
-        if (!_legendMeasureCtx) {
-            _legendMeasureCtx = document.createElement('canvas').getContext('2d');
-        }
-        _legendMeasureCtx.font = MSA_LOGO_FONT_PX + 'px monospace';
-        let m = _legendMeasureCtx.measureText(ch);
+        let ctx = measureCtx();
+        ctx.font = MSA_LOGO_FONT_PX + 'px monospace';
+        let m = ctx.measureText(ch);
         let ascent = m.actualBoundingBoxAscent;
         let descent = m.actualBoundingBoxDescent;
         if (!(ascent > 0)) {
@@ -9628,7 +10224,9 @@ function (root, d3, forester, phyloXml) {
         }
         if (_state.phylogram && !_state.alignPhylogram) {
             if (_state.unrootedDisplay) {
-                toCladegram();
+                toCladegram();          // unrooted cannot align
+            } else if (_state.circularDisplay) {
+                toCladegram();          // circular is already showing the aligned type
             } else {
                 toAlignedPhylogram();
             }
@@ -9732,6 +10330,274 @@ function (root, d3, forester, phyloXml) {
     }
 
     // The cheat sheet: every combo above, then the plain keys.
+    // ===================== The control-panel cheat sheet =====================
+    //
+    // Every control the panel is SHOWING, in the order it shows them, each
+    // beside the sentence that already explains it. The desktop's
+    // ControlPanelCheatSheet, and built the same way on one principle: nothing
+    // is written twice. A row's picture is the control's own glyph, cloned;
+    // a row's words are the tooltip the control already carries. So a new
+    // control needs no edit here -- it needs a tooltip, and
+    // test_trees/panel_descriptions.html fails by name for any visible control
+    // without one.
+    //
+    // Two rules of Christian's, 2026-09-25, which the desktop follows too:
+    // name and description are separated by a COLON, never a dash; and no live
+    // VALUES appear -- a label reading "Font size: 6" is cut at the colon, so
+    // the sheet says what the control is and never what it is currently set
+    // to. "A printed 40% is wrong for every reader but the one who printed
+    // it."
+    //
+    // Modeless, and placed beside the panel rather than over it: a sheet you
+    // must close to touch the control it describes is half a sheet.
+    const CHEAT_SHEET_DIALOG = 'aptx_cheatsheet';
+    let _cheatSheetBody = null;
+
+    // this viewer's own panel, not another viewer's on the same page
+    function cheatSheetPanel() {
+        return (_container && _container.querySelector(':scope > .aptx-panel'))
+            || document.querySelector('.aptx-panel');
+    }
+
+    // The words for one control: its own title, or the title of the <label>
+    // that names it -- which is a SIBLING, not an ancestor, for the select
+    // menus (makeSelectMenu puts it there).
+    function controlDescription(el) {
+        let n = el;
+        for (let i = 0; i < 4 && n; ++i) {
+            let t = (n.getAttribute && (n.getAttribute('title') || n.getAttribute('aria-label'))) || '';
+            if (t.trim() !== '') {
+                return t.trim();
+            }
+            n = n.parentElement;
+        }
+        if (el.id) {
+            let lab = document.querySelector('label[for="' + el.id + '"]');
+            let t = lab ? (lab.getAttribute('title') || lab.getAttribute('aria-label') || '') : '';
+            if (t.trim() !== '') {
+                return t.trim();
+            }
+        }
+        return '';
+    }
+
+    // What the control is called, with any live value cut away. A checkbox is
+    // named by its own text, a menu or slider by the label beside it, a glyph
+    // button by nothing -- its picture is its name, and the row shows that.
+    function controlName(el) {
+        // ONE cut, at the end, over whatever source the name came from.
+        //
+        // It used to be applied only to the two sources that could carry a
+        // value -- a <label for> and an aria-label -- and not to a checkbox's
+        // own text or a button's value. That left "no sheet name contains a
+        // colon" meaning two different things on the two programs: on the
+        // desktop every name IS a cut label, so the rule asserts the cut ran
+        // and can never fire on correct output; here it would ALSO have
+        // constrained what a control may be called, and a checkbox legitimately
+        // labelled "Ratio 1:1" would have failed it. Cutting everywhere makes
+        // the invariant mean the same thing on both sides.
+        //
+        // What the cut is doing here, exactly: our labels read "Color by:" and
+        // "Shape:", so it removes a TRAILING colon, and removing the cut fails
+        // the sheet's value rule by name ("Color by:"). What it is NOT doing
+        // here is removing a value -- nothing follows a colon on this panel,
+        // unlike the desktop's "Font size: 6". So it is exercised but for the
+        // lesser of its two reasons. (Said precisely because the looser
+        // version of this note -- "a no-op, removing it passes every check" --
+        // was true for about an hour and then was not, once the desktop's
+        // sharper value rule was adopted here.)
+        return cutAtValue(rawControlName(el));
+    }
+
+    // "Font size: 6" -> "Font size". The colon is where a value starts, and a
+    // value on a sheet is wrong for everyone but whoever was looking when it
+    // was made.
+    function cutAtValue(name) {
+        return name ? name.split(':')[0].trim() : '';
+    }
+
+    // What the control is called, before the cut. A checkbox is named by its
+    // own text, a menu or slider by the label beside it, a glyph button by
+    // nothing -- its picture is its name, and the row shows that.
+    function rawControlName(el) {
+        if (el.type === 'checkbox' || el.type === 'radio') {
+            let span = el.parentElement ? el.parentElement.querySelector('span') : null;
+            if (span && span.textContent.trim() !== '') {
+                return span.textContent.trim();
+            }
+        }
+        if (el.tagName === 'INPUT' && el.value && (el.type === 'button' || el.type === 'submit')) {
+            return el.value.trim();
+        }
+        if (el.id) {
+            let lab = document.querySelector('label[for="' + el.id + '"]');
+            if (lab && lab.textContent.trim() !== '') {
+                return lab.textContent.trim();
+            }
+        }
+        // a menu with no visible label of its own says what it is here
+        let aria = el.getAttribute('aria-label');
+        if (aria && aria.trim() !== '') {
+            return aria.trim();
+        }
+        // and a text button -- the hide toggle, the reset chips -- is its text
+        let own = (el.textContent || '').trim();
+        if (own !== '' && el.tagName === 'BUTTON' && !el.querySelector('svg')) {
+            return own;
+        }
+        // a segmented button drawn as TEXT rather than a glyph (Time / Div) is
+        // named by its own label, which is the only thing on it
+        let seg = el.closest ? el.closest('label.aptx-seg') : null;
+        if (seg && !seg.querySelector('svg')) {
+            let segText = (seg.textContent || '').trim();
+            if (segText !== '') {
+                return segText;
+            }
+        }
+        return '';
+    }
+
+    // What the user actually sees and clicks. A segmented button's <input> is
+    // 0x0 and transparent -- the visible thing is the <label> around it, which
+    // carries the glyph and the tooltip -- so asking the input whether it is
+    // on the screen answered no for all eight of them: the three layouts, the
+    // three display types and the time/divergence pair were absent from the
+    // sheet entirely (Christian, 2026-09-28).
+    function controlSurface(el) {
+        let box = el.getBoundingClientRect();
+        if (box.width > 0 || box.height > 0) {
+            return el;
+        }
+        let label = el.closest ? el.closest('label') : null;
+        if (label) {
+            let lb = label.getBoundingClientRect();
+            if (lb.width > 0 || lb.height > 0) {
+                return label;
+            }
+        }
+        return null;
+    }
+
+    function cheatSheetRows() {
+        let panel = cheatSheetPanel();
+        if (!panel) {
+            return [];
+        }
+        let rows = [];
+        let seen = new Set();
+        let all = panel.querySelectorAll('input, button, select');
+        for (let i = 0; i < all.length; ++i) {
+            let el = all[i];
+            // what the panel is SHOWING: a control the tree gives no data for
+            // is not on the screen and does not belong on the sheet. A
+            // DISABLED one is on the screen, and saying what it is is how a
+            // reader learns why it is greyed.
+            let surface = el.disabled ? (controlSurface(el) || el) : controlSurface(el);
+            if (!surface) {
+                continue;
+            }
+            let words = controlDescription(el);
+            if (words === '' || seen.has(el)) {
+                continue;
+            }
+            seen.add(el);
+            // the glyph belongs to the surface, not to a 0x0 input inside it
+            let svg = surface.querySelector ? surface.querySelector('svg.aptx-glyph') : null;
+            rows.push({name: controlName(el), words: words, glyph: svg});
+        }
+        return rows;
+    }
+
+    function renderCheatSheet(body) {
+        // everything but the standing lead paragraph
+        let keep = body.querySelector('.aptx-cheat-lead');
+        while (body.firstChild) {
+            body.removeChild(body.firstChild);
+        }
+        if (keep) {
+            body.appendChild(keep);
+        }
+        let rows = cheatSheetRows();
+        rows.forEach(function (row) {
+            let line = document.createElement('div');
+            line.className = 'aptx-dialog-line aptx-cheat-line';
+            let key = document.createElement('span');
+            key.className = 'aptx-dialog-key aptx-cheat-key';
+            if (row.glyph) {
+                let g = row.glyph.cloneNode(true);
+                g.removeAttribute('class');
+                g.setAttribute('class', 'aptx-glyph aptx-cheat-glyph');
+                key.appendChild(g);
+            }
+            if (row.name) {
+                let n = document.createElement('span');
+                n.className = 'aptx-cheat-name';
+                n.textContent = row.name;
+                key.appendChild(n);
+            }
+            let val = document.createElement('span');
+            val.className = 'aptx-dialog-val';
+            val.textContent = row.words;
+            line.appendChild(key);
+            line.appendChild(val);
+            body.appendChild(line);
+        });
+        if (rows.length === 0) {
+            let empty = document.createElement('p');
+            empty.className = 'aptx-shortcuts-note';
+            empty.textContent = 'No controls are showing.';
+            body.appendChild(empty);
+        }
+    }
+
+    // The panel is rebuilt on every render, so an open sheet is re-read from
+    // it rather than left describing a panel that has changed underneath.
+    function refreshCheatSheet() {
+        if (_cheatSheetBody && _cheatSheetBody.isConnected) {
+            renderCheatSheet(_cheatSheetBody);
+        }
+    }
+
+    function showCheatSheetDialog() {
+        let shell = makeDialogShell(CHEAT_SHEET_DIALOG, 'Control panel', 460);
+        shell.body.classList.add('aptx-shortcuts');
+        shell.body.classList.add('aptx-cheat');
+        // says what the reader is looking at, as the desktop's sheet does
+        let lead = document.createElement('p');
+        lead.className = 'aptx-cheat-lead';
+        lead.textContent = 'Every control the panel is showing, with the icon it draws and what it does.';
+        shell.body.appendChild(lead);
+        _cheatSheetBody = shell.body;
+        renderCheatSheet(shell.body);
+        shell.dialog.addEventListener('close', function () {
+            if (_cheatSheetBody === shell.body) {
+                _cheatSheetBody = null;
+            }
+        });
+        // modeless, as the colour picker is: the point is to read a row and
+        // click the control it names without closing anything
+        shell.dialog.show();
+        placeBesidePanel(shell.dialog);
+    }
+
+    // Beside the panel, never over it, and inside the window.
+    function placeBesidePanel(dialog) {
+        let panel = cheatSheetPanel();
+        let box = panel ? panel.getBoundingClientRect() : null;
+        let w = dialog.offsetWidth;
+        let h = dialog.offsetHeight;
+        let left = box ? (box.right + 10) : 10;
+        if (left + w > window.innerWidth - 6) {
+            left = box ? (box.left - w - 10) : 6;
+        }
+        setStyles(dialog, {
+            'position': 'fixed',
+            'margin': '0',
+            'left': Math.max(6, Math.min(window.innerWidth - w - 6, left)) + 'px',
+            'top': Math.max(6, Math.min(window.innerHeight - h - 6, box ? box.top : 10)) + 'px'
+        });
+    }
+
     function showShortcutsDialog() {
         let shell = makeDialogShell(SHORTCUTS_DIALOG, 'Keyboard shortcuts', 400);
         shell.body.classList.add('aptx-shortcuts');
@@ -9955,17 +10821,146 @@ function (root, d3, forester, phyloXml) {
     // the later one's shadow and glow used to fall across the earlier body,
     // and now lie under it; overlapping shadows of one level no longer
     // darken each other.
+    // ===================== Domain hover =====================
+    // Domain architectures are what Archaeopteryx has always been best at, and
+    // until now the boxes said nothing: you could see a domain but not read
+    // its name, its E-value or where it sits, short of opening the node's data
+    // dialog and finding it in a list. Christian, 2026-09-23.
+    //
+    // The readout is the one the heat map and the alignment already use, so a
+    // hover anywhere in the viewer looks and behaves the same, and it is
+    // placed by placeHoverReadout, which measures the box rather than assuming
+    // a size.
+
+    function domainInfoAt(event) {
+        let t = event.target;
+        return (t && t.__aptxDomain) ? t.__aptxDomain : null;
+    }
+
+    let _domainHovered = null;
+
+    function domainHover(event) {
+        let info = domainInfoAt(event);
+        if (!info) {
+            domainHoverOut();
+            return;
+        }
+        // mousemove fires all the way across a box, and a wide domain is
+        // hundreds of pixels. The TEXT only changes when the box does, so
+        // re-escaping it, reparsing it as HTML and restarting the fade sixty
+        // times a second would be work for a byte-identical result -- and the
+        // restarted transition would keep opacity approaching 0.95 without
+        // ever arriving. The readout must still FOLLOW the pointer, so the
+        // placement runs either way.
+        let tip_el = _node_mouseover_div.node();
+        if (info === _domainHovered) {
+            placeHoverReadout(tip_el, event);
+            return;
+        }
+        _domainHovered = info;
+        let ref = forester.domainReference(info);
+        let txt = 'Domain: ' + (info.name || '(unnamed)') + '<br>';
+        let ev = forester.domainEvalueText(info.evalue);
+        if (ev !== null) {
+            txt += 'E-value: ' + ev + '<br>';
+        }
+        txt += 'Residues: ' + info.from + '–' + info.to
+            + ' (' + ((info.to - info.from) + 1) + ' aa'
+            + (info.proteinLength > 0 ? (' of ' + info.proteinLength) : '') + ')<br>';
+        if (info.tip) {
+            txt += 'Tip: ' + info.tip + '<br>';
+        }
+        if (info.id) {
+            txt += 'Accession: ' + info.id + '<br>';
+        }
+        if (ref) {
+            // A readout that follows the pointer cannot hold a link you could
+            // reach, so the BOX is the link and the readout says so. Written
+            // as a "label: value" row on purpose: markUpDataLabels renders a
+            // line WITHOUT a colon as a section divider (9px bold uppercase
+            // faint), which is the wrong voice entirely for a call to action.
+            txt += ref.exact ? 'Click: the Pfam entry' : 'Click: to look this domain up at InterPro';
+        }
+        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 domainHoverOut() {
+        _domainHovered = null;
+        _node_mouseover_div.transition().duration(300).style('opacity', 1e-6);
+    }
+
+    let _domainOpenedAt = 0;
+
+    function domainClicked(event) {
+        let info = domainInfoAt(event);
+        if (!info) {
+            return;
+        }
+        // A click that LANDED on a box is the box's, whether or not it has
+        // somewhere to send you; letting an unlinkable domain fall through
+        // would open the node menu for whatever node is within five units.
+        event.stopPropagation();
+        let ref = forester.domainReference(info);
+        if (!ref) {
+            return;
+        }
+        // Double-clicking is the natural gesture for "open this", and it
+        // arrives as two clicks: without this it opens two identical tabs.
+        let now = Date.now();
+        if ((now - _domainOpenedAt) < 500) {
+            return;
+        }
+        _domainOpenedAt = now;
+        openExternal(ref.url);
+    }
+
+    // The tree zooms on double click. Over a domain box the gesture means the
+    // box, so the zoom must not also happen behind the tabs that just opened.
+    function domainDblClicked(event) {
+        if (domainInfoAt(event)) {
+            event.stopPropagation();
+            event.preventDefault();
+        }
+    }
+
     function drawDomainArchitectures() {
         if (!_svgGroup) {
             return;
         }
         let existing = _svgGroup.select('g.aptx-domains');
+        // An architecture goes WITH ITS NAME, and is left out when the name
+        // is. domainsShown() already ties the whole track to external labels
+        // being on; this is the same rule per tip, and it became necessary the
+        // day unrooted started hiding crowded names -- before that every tip
+        // in every layout kept its label, so a nameless architecture could not
+        // happen. Measured on apaf when it could: 7 of 31 tips drew an
+        // architecture with no name beside it, identifiable only by which
+        // spoke it sat on. (The desktop reached the same rule from the other
+        // end: a tip IMAGE painted before its label's claim was left orphaned
+        // under a neighbour's name.)
         let tips = (domainsShown() && _root) ? displayedTips().filter(function (d) {
+            // Keyed on "the RULE hid this name", not on "there is no name".
+            // The two part company the moment the user switches the name
+            // fields off: nothing is hidden by the rule then, every label is
+            // empty, and every architecture should still be drawn. Keying on
+            // the empty text took all 31 of apaf's architectures away with the
+            // Node Name checkbox -- shipped, and caught by the desktop
+            // warning us they had met the same reading of their own fix.
+            if (d._labelDropped) {
+                return false;
+            }
             return _state.unrootedDisplay ? (d.ux !== undefined) : (d.x !== undefined);
         }) : [];
         let f = tips.length > 0 ? domainScale() : 0;
         if (tips.length === 0 || !(f > 0) || !isFinite(f)) {
             existing.remove();
+            domainHoverOut();   // the box under the pointer just stopped existing
             return;
         }
         // [defs, the batched paths, the bodies, the names], kept between
@@ -9985,6 +10980,20 @@ function (root, d3, forester, phyloXml) {
         let underLayer = g.children[1];
         let bodyLayer = g.children[2];
         let labelLayer = g.children[3];
+        // The group ignores the mouse so the tree underneath stays clickable;
+        // the BODIES alone take it back, so a hover lands on a domain and not
+        // on its shadow, its glow or its label.
+        bodyLayer.style.pointerEvents = 'auto';
+        if (!bodyLayer.__aptxWired) {
+            bodyLayer.__aptxWired = true;
+            // mousemove alone, as the heat map and the alignment do it: a
+            // mouseover is always followed by a mousemove, so binding both
+            // only built the readout twice on entry.
+            bodyLayer.addEventListener('mousemove', domainHover);
+            bodyLayer.addEventListener('mouseout', domainHoverOut);
+            bodyLayer.addEventListener('click', domainClicked);
+            bodyLayer.addEventListener('dblclick', domainDblClicked);
+        }
 
         // one vertical gradient per base colour, lighter at the top; the
         // defs ride into the SVG / PDF / PNG exports with the boxes
@@ -10087,6 +11096,10 @@ function (root, d3, forester, phyloXml) {
             }
             let set = row.transform ? pathSet() : track;
             let geo = forester.domainBoxes(da, row.start, f, _state.domainEvalueExponent);
+            // once per ROW: displayNodeName walks the node's properties when a
+            // label-ref visualization is on, and a row can hold dozens of boxes
+            let rowTip = displayNodeName(row.d) || '';
+            let rowLength = Number(da.length) || 0;
             let h = row.h;
             let y1 = row.y1;
             set.backbones.push(roundRectPath(geo.backbone.x, y1 + (h / 2) - 0.5, geo.backbone.w, 1, 0));
@@ -10110,7 +11123,13 @@ function (root, d3, forester, phyloXml) {
                     });
                 }
                 bodies.push({x: b.x, y: y1, w: b.w, h: h, r: r, transform: row.transform,
-                    fill: gradientFor(base), stroke: forester.domainDarken(base, 0.24)});
+                    fill: gradientFor(base), stroke: forester.domainDarken(base, 0.24),
+                    // what the hover readout says. Carried per BOX rather than
+                    // looked up again on hover: the boxes are pooled and
+                    // reused between redraws, so an index into the tree would
+                    // go stale the moment the tips on screen change.
+                    info: {name: b.name, from: b.from, to: b.to, evalue: b.evalue, id: b.id,
+                        tip: rowTip, proteinLength: rowLength}});
                 if (row.labelsOn && b.name && fs > 4 && legendTextWidth(b.name, font) <= b.w - 4) {
                     names.push({x: b.x + (b.w / 2), y: y1 + (h / 2), font: font,
                         fill: forester.domainLabelInk(base), text: b.name});
@@ -10134,6 +11153,11 @@ function (root, d3, forester, phyloXml) {
             paths[k].style.fill = u.fill;
             paths[k].style.fillOpacity = u.opacity;
         });
+        // A redraw can take the hovered box away without the pointer moving
+        // -- a keyboard zoom, a panel change applied with Enter, a collapse --
+        // and a removed element fires no mouseout, so the readout would stay
+        // painted over a domain that is no longer there.
+        domainHoverOut();
         let rects = sizeLayer(bodyLayer, 'rect', bodies.length);
         bodies.forEach(function (b, k) {
             let el = rects[k];
@@ -10151,6 +11175,11 @@ function (root, d3, forester, phyloXml) {
             el.style.fill = b.fill;
             el.style.stroke = b.stroke;
             el.style.strokeWidth = 1;
+            el.__aptxDomain = b.info;
+            // only where there is somewhere to go: an unnamed domain with no
+            // accession has no reference, and a hand cursor over it would
+            // promise a link that the click cannot deliver
+            el.style.cursor = forester.domainReference(b.info) ? 'pointer' : 'default';
         });
         let texts = sizeLayer(labelLayer, 'text', names.length);
         names.forEach(function (t, k) {
@@ -11091,7 +12120,8 @@ function (root, d3, forester, phyloXml) {
 
     // what the viewer writes onto a tree's nodes, left off a tree cut out of it
     const VIEW_NODE_FIELDS = ['viewId', 'collapsed', 'x', 'y', 'x0', 'y0', 'id', 'hide', 'hasVis', 'distToRoot',
-        'ux', 'uy', 'uangle', '_style', '_suppDot', '_extLabelText', '_eventText', '_confText', '_blText'];
+        'ux', 'uy', 'uangle', '_style', '_suppDot', '_extLabelText', '_eventText', '_confText', '_blText',
+        '_labelBoxes', '_labelDropped', '_markBoxes'];
 
     // the whole tree's tip count, counted again only when the tree changes
     // (every change makes new _basicTreeProperties)
@@ -11887,16 +12917,27 @@ function (root, d3, forester, phyloXml) {
         scheduleUpdate(null, 0);
     }
 
+    // In CIRCULAR these two leave the aligned/unaligned flag alone. That
+    // layout aligns whatever the flag says, so the button shown as chosen
+    // there is "aligned" regardless -- and writing the flag from it would
+    // silently change the user's choice for the layouts that CAN express it.
+    // A user who likes the plain phylogram in rectangular, steps into
+    // circular, flips to the cladogram and back, and returns, would have
+    // found the aligned one waiting.
     function toAlignedPhylogram() {
         _state.phylogram = true;
-        _state.alignPhylogram = true;
+        if (!_state.circularDisplay) {
+            _state.alignPhylogram = true;
+        }
         setDisplayTypeButtons();
         scheduleUpdate(null, 0);
     }
 
     function toCladegram() {
         _state.phylogram = false;
-        _state.alignPhylogram = false;
+        if (!_state.circularDisplay) {
+            _state.alignPhylogram = false;
+        }
         setDisplayTypeButtons();
         scheduleUpdate(null, 0);
     }
@@ -11928,18 +12969,40 @@ function (root, d3, forester, phyloXml) {
         // against; an alignment / time axis is inherently horizontal. Synced
         // BEFORE the zoom-row early return, and (via updateButtonEnabledState)
         // on every render, so subtree switches keep them honest.
+        // WHICH of the two phylogram buttons is dead depends on the layout,
+        // and it is the one the layout CANNOT do -- not the one it always
+        // does. Circular always carries its external labels out to a common
+        // ring on dashed connectors, whatever is chosen, so the circular
+        // phylogram IS the aligned one: the unavailable option there is the
+        // UNALIGNED phylogram. Unrooted is the other way round -- it has no
+        // common edge to align to, so what it cannot do is align.
+        //
+        // (Greying the aligned button in circular was the first attempt, on
+        // the grounds that picking it changed nothing. True, but backwards:
+        // it disabled the button that describes what the layout does and left
+        // live the one it cannot do, and the panel then showed "phylogram"
+        // selected over a picture whose labels are plainly aligned. Christian
+        // spotted the inconsistency, 2026-09-27.)
+        let measured = _basicTreeProperties.branchLengths === true;
         let phyBtn = byId(PHYLOGRAM_BUTTON);
         if (phyBtn) {
-            phyBtn.disabled = _basicTreeProperties.branchLengths !== true;
+            phyBtn.disabled = !measured || _state.circularDisplay;
+            phyBtn.title = PHYLOGRAM_WHAT;
         }
         let alignBtn = byId(PHYLOGRAM_ALIGNED_BUTTON);
         if (alignBtn) {
-            alignBtn.disabled = _state.unrootedDisplay || _basicTreeProperties.branchLengths !== true;
-        }
-        let dyna = byId(DYNAHIDE_CB);
-        if (dyna) {
-            dyna.disabled = _state.unrootedDisplay;
+            alignBtn.disabled = !measured || _state.unrootedDisplay;
+            alignBtn.title = PHYLOGRAM_ALIGNED_WHAT;
         }
+        // Which button is SHOWN as chosen is layout-dependent too, and this
+        // was only re-synced when the display type changed -- so switching
+        // layout left the previous layout's answer on the screen.
+        setDisplayTypeButtons();
+        // Auto-hide Labels stays live in every layout. It used to be greyed out
+        // in unrooted, where the every-k-th tip-label decimation does not run --
+        // but it also governs the crowded branch-data rule, and now the
+        // unrooted tip-label rule, both of which do run there, so greying it
+        // out left the user unable to switch off what they could see.
         let msaCb = byId(MSA_CB);
         if (msaCb) {
             msaCb.disabled = radialDisplay();
@@ -12156,7 +13219,15 @@ function (root, d3, forester, phyloXml) {
     // panel's accent: the checkbox item gets a box and its tooltip says how
     // many labels are shown. Called on every redraw, since the density
     // changes with the vertical zoom, the font size and the view.
-    function syncDynahideIndicator(active) {
+    // Lights the toggle while it is actually taking something away, and says
+    // what. The switch governs three rules, and the light has to ask all three
+    // rather than whichever one was written first: the every-k-th thinning
+    // (rectangular, by index against the row pitch), the overlap thinning
+    // (both fans, by whether names would overprint) and the crowded
+    // branch-data rule (every layout). Asking only the first two left it dark
+    // over a circular tree with 201 numbers refused and every name drawn --
+    // and over a RECTANGULAR one with 18 refused, which was never right.
+    function syncDynahideIndicator() {
         let cb = byId(DYNAHIDE_CB);
         let item = cb ? cb.closest('.aptx-check') : null;
         if (!item) {
@@ -12165,9 +13236,23 @@ function (root, d3, forester, phyloXml) {
         if (item.dataset.baseTitle === undefined) {
             item.dataset.baseTitle = item.title;
         }
-        item.classList.toggle('aptx-check-active', !!active);
+        let parts = [];
+        if (!radialDisplay() && _dynahide_factor >= 2) {
+            parts.push('1 in ' + _dynahide_factor + ' labels shown');
+        } else if (radialDisplay() && _radialNamesHidden > 0) {
+            parts.push(_radialNamesHidden + ' name' + (_radialNamesHidden === 1 ? '' : 's')
+                + ' that would overprint');
+        }
+        if (_branchMarksHidden > 0) {
+            // said only when it is happening: the clause used to be printed
+            // unconditionally, which made a promise of every render
+            parts.push(_branchMarksHidden + ' branch value' + (_branchMarksHidden === 1 ? '' : 's')
+                + ' that would overlap');
+        }
+        let active = _state.dynahide === true && parts.length > 0;
+        item.classList.toggle('aptx-check-active', active);
         item.title = active
-            ? item.dataset.baseTitle + ', hiding now: 1 in ' + _dynahide_factor + ' labels shown'
+            ? item.dataset.baseTitle + ', hiding now: ' + parts.join(', and ')
             : item.dataset.baseTitle;
     }
 
@@ -12806,6 +13891,14 @@ function (root, d3, forester, phyloXml) {
             + glyphDot(50, 29, 5.5);
     }
 
+    // a reference card: the outline, and the rows on it
+    function glyphCheatSheet() {
+        return '<rect x="18" y="12" width="64" height="76" rx="8"/>'
+            + glyphLine(32, 34, 68, 34)
+            + glyphLine(32, 50, 68, 50)
+            + glyphLine(32, 66, 56, 66);
+    }
+
     function glyphSun() {
         let s = glyphDot(50, 50, 20);
         for (let i = 0; i < 8; ++i) {
@@ -12874,6 +13967,7 @@ function (root, d3, forester, phyloXml) {
             case 'tree_prev': sw = 9; cap = 'round'; body = glyphChevron(false); break;
             case 'tree_next': sw = 9; cap = 'round'; body = glyphChevron(true); break;
             case 'info': sw = 7; cap = 'round'; body = glyphInfo(); break;
+            case 'cheat_sheet': sw = 7; cap = 'round'; body = glyphCheatSheet(); break;
             case 'sun': body = glyphSun(); break;
             case 'moon': body = glyphMoon(); break;
             default: throw new Error('unknown control-panel glyph: ' + kind);
@@ -13072,6 +14166,18 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-keys { display:inline-flex; gap:3px; flex-wrap:wrap; }'
             + '.aptx-kbd { font-family:inherit; font-size:10.5px; line-height:1; padding:3px 5px; min-width:18px; text-align:center; color:var(--p-ink); background:var(--p-surface2); border:1px solid var(--p-line-strong); border-bottom-width:2px; border-radius:4px; }'
             + '.aptx-shortcuts-note { margin:8px 0 0; font-size:10.5px; line-height:1.4; color:var(--p-muted); }'
+            // the cheat sheet: a scrolling card of glyph + name : description
+            // 31 rows is taller than a short window; the card scrolls rather
+            // than running off the bottom, and the title bar stays put
+            + '#' + CHEAT_SHEET_DIALOG + ' { max-height:min(78vh, 760px); display:flex; flex-direction:column; }'
+            + '#' + CHEAT_SHEET_DIALOG + ' .aptx-dialog-body { min-height:0; }'
+            + '.aptx-cheat-lead { margin:0 0 9px; font-size:10.5px; line-height:1.4; color:var(--p-muted); }'
+            + '.aptx-cheat .aptx-dialog-line { padding:3px 0; align-items:flex-start; }'
+            + '.aptx-cheat .aptx-cheat-key { flex:0 0 38%; display:flex; align-items:center; gap:6px; color:var(--p-ink); }'
+            + '.aptx-cheat .aptx-cheat-glyph { width:14px; height:14px; flex:none; color:var(--p-muted); }'
+            + '.aptx-cheat .aptx-cheat-name { overflow-wrap:anywhere; }'
+            + '.aptx-cheat .aptx-dialog-val { color:var(--p-muted); line-height:1.35; }'
+            + '.aptx-cheat .aptx-cheat-key:not(:empty)::after { content:":"; color:var(--p-faint); }'
             // representative tips: the input dialog and its result
             + '.aptx-reps { line-height:1.35; }'
             + '.aptx-reps-lead { margin:0 0 4px; }'
@@ -13143,7 +14249,15 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-tip .aptx-dialog-line { padding:1px 0; }'
             + '.aptx-tip .aptx-dialog-line + .aptx-dialog-line { border-top:0; }'
             + '.aptx-tip .aptx-dialog-key { flex:0 0 auto; min-width:96px; }'
-            + '.aptx-panel .' + PROG_NAME + ' { display:flex; align-items:center; gap:8px; padding:9px 12px; border-bottom:1px solid var(--p-line); font-weight:600; letter-spacing:-0.01em; }'
+            // WRAPS. The title's longest word cannot break, so on a narrow
+            // panel the buttons had nowhere to go and overflowed the padding:
+            // with four of them they ended 2.4 px past the panel's own right
+            // edge, and squeezed the title into two ragged centred lines on
+            // the way. Wrapping puts them on their own right-aligned row
+            // instead, which also gives the title back its full width -- so
+            // "Archaeopteryx.js 3.15.0" sits on ONE line where it used to
+            // break in two.
+            + '.aptx-panel .' + PROG_NAME + ' { display:flex; align-items:center; flex-wrap:wrap; gap:6px 8px; padding:9px 12px; border-bottom:1px solid var(--p-line); font-weight:600; letter-spacing:-0.01em; }'
             + '.aptx-panel .' + PROGNAMELINK + ',.aptx-panel .' + PROGNAMELINK + ':link,.aptx-panel .' + PROGNAMELINK + ':visited { color:var(--p-accent-ink); text-decoration:none; font-size:12px; border:0; }'
             + '.aptx-panel .' + PROGNAMELINK + ' { background:none; padding:0; margin:0; cursor:pointer;'
             + '  font-family:inherit; font-weight:inherit; letter-spacing:inherit; }'
@@ -13394,6 +14508,18 @@ function (root, d3, forester, phyloXml) {
             });
             actions.appendChild(infoBtn);
 
+            let sheetBtn = document.createElement('button');
+            sheetBtn.type = 'button';
+            sheetBtn.className = 'aptx-info-btn';
+            sheetBtn.title = 'Control panel: what each control does';
+            sheetBtn.setAttribute('aria-label', 'Control panel cheat sheet');
+            sheetBtn.innerHTML = makeGlyph('cheat_sheet');
+            sheetBtn.addEventListener('click', function (e) {
+                e.stopPropagation();
+                showCheatSheetDialog();
+            });
+            actions.appendChild(sheetBtn);
+
             let progName = header.querySelector('.' + PROGNAMELINK);
             if (progName) {
                 // Clicking the title used to navigate away to the project site;
@@ -13465,6 +14591,10 @@ function (root, d3, forester, phyloXml) {
                     fitPanelSections(panel, name);
                 }
                 savePanelSections();
+                // a folded section's controls are off the screen, so they
+                // leave the cheat sheet: it describes what the panel is
+                // showing, and folding does not go through a tree render
+                refreshCheatSheet();
             });
         }
         // What arrived open counts as opened, oldest at the BOTTOM: a panel is
@@ -14253,7 +15383,8 @@ function (root, d3, forester, phyloXml) {
             ['Desktop version', DESKTOP_WEBSITE, 'cmzmasek.github.io/archaeopteryx'],
             ['Source code', SOURCE_WEBSITE, 'github.com/cmzmasek/archaeopteryx-js'],
             ['License', LICENSE_WEBSITE, LICENSE_NAME],
-            ['Keyboard', null, 'shortcuts (' + (IS_MAC ? '\u2318 /' : 'Ctrl+/') + ')']].forEach(function (row) {
+            ['Keyboard', null, 'shortcuts (' + (IS_MAC ? '\u2318 /' : 'Ctrl+/') + ')'],
+            ['Control panel', null, 'what each control does']].forEach(function (row) {
             let line = document.createElement('div');
             line.className = 'aptx-dialog-line';
             let key = document.createElement('span');
@@ -14267,12 +15398,14 @@ function (root, d3, forester, phyloXml) {
                 a.target = '_blank';
                 a.rel = 'noopener noreferrer';
             } else {
-                // the shortcuts row opens the cheat sheet in place of the About box
+                // the two rows with no URL open another dialog in place of
+                // this one: the key list, and the control-panel sheet
+                let opener = row[0] === 'Control panel' ? showCheatSheetDialog : showShortcutsDialog;
                 a.href = '#';
                 a.addEventListener('click', function (e) {
                     e.preventDefault();
                     shell.dialog.close();
-                    showShortcutsDialog();
+                    opener();
                 });
             }
             a.textContent = row[2];
@@ -14843,7 +15976,11 @@ function (root, d3, forester, phyloXml) {
         function makeProgramDesc() {
             let h = "";
             h = h.concat('<div class=' + PROG_NAME + '>');
-            h = h.concat('<button type="button" class="' + PROGNAMELINK + '" title="About ' + NAME + '">' + NAME + ' ' + VERSION + '</button>');
+            // aria-label without the version: the cheat sheet names a control
+            // by this, and a version is a value -- it belongs in the About box
+            // it opens, not in a row that says what the button is
+            h = h.concat('<button type="button" class="' + PROGNAMELINK + '" aria-label="' + NAME
+                + '" title="About ' + NAME + '">' + NAME + ' ' + VERSION + '</button>');
             h = h.concat('</div>');
             return h;
         }
@@ -14994,14 +16131,17 @@ function (root, d3, forester, phyloXml) {
             // desktop
             let layoutGroup = 'layout_control_radio';
             h = h.concat('<div class="aptx-segmented">');
-            h = h.concat(makeSegment(makeGlyph('rectangular'), LAYOUT_RECT_BUTTON, layoutGroup, 'rectangular, root at left'));
-            h = h.concat(makeSegment(makeGlyph('circular'), LAYOUT_CIRC_BUTTON, layoutGroup, 'circular'));
-            h = h.concat(makeSegment(makeGlyph('unrooted'), LAYOUT_UNROOTED_BUTTON, layoutGroup, 'unrooted (equal-angle)'));
+            h = h.concat(makeSegment(makeGlyph('rectangular'), LAYOUT_RECT_BUTTON, layoutGroup,
+                'rectangular layout: the root at the left, the tips in even rows down the page'));
+            h = h.concat(makeSegment(makeGlyph('circular'), LAYOUT_CIRC_BUTTON, layoutGroup,
+                'circular layout: the tree as a fan, every tip label carried out to a common ring'));
+            h = h.concat(makeSegment(makeGlyph('unrooted'), LAYOUT_UNROOTED_BUTTON, layoutGroup,
+                'unrooted layout: equal-angle, drawing no root branch at all'));
             h = h.concat('</div>');
             h = h.concat('<div class="' + PHYLOGRAM_CLADOGRAM_CONTROLGROUP + ' aptx-segmented">');
-            h = h.concat(makeSegment(makeGlyph('phylogram'), PHYLOGRAM_BUTTON, radioGroup, 'phylogram display (uses branch length values)'));
-            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(makeSegment(makeGlyph('phylogram'), PHYLOGRAM_BUTTON, radioGroup, PHYLOGRAM_WHAT));
+            h = h.concat(makeSegment(makeGlyph('aligned_phylogram'), PHYLOGRAM_ALIGNED_BUTTON, radioGroup, PHYLOGRAM_ALIGNED_WHAT));
+            h = h.concat(makeSegment(makeGlyph('cladogram'), CLADOGRAM_BUTTON, radioGroup, CLADOGRAM_WHAT));
             h = h.concat('</div>');
             // The branch SCALE, when the tree states two different things: its
             // nodes' dates, and its branches' divergence. Hidden otherwise,
@@ -15084,10 +16224,10 @@ function (root, d3, forester, phyloXml) {
             // "Auto-hide Labels" matches the desktop, which renamed the historical
             // "Dyna Hide" because that named the mechanism rather than what the user
             // sees. The _state.dynahide field keeps its name internally.
-            opts.push(makeCheckboxItem('Auto-hide Labels', DYNAHIDE_CB, 'automatically hide external labels when the tree is too dense for them to be readable', true));
+            opts.push(makeCheckboxItem('Auto-hide Labels', DYNAHIDE_CB, 'automatically hide external labels, and branch values that would overprint a name or each other, where the tree is too dense for them to be readable', true));
             opts.push(makeCheckboxItem('Short Names', SHORTEN_NODE_NAME_CB, 'to shorten long node names'));
             if (_basicTreeProperties.confidences) {
-                opts.push(makeCheckboxItem('Support Dots', SUPPORT_DOTS_CB, 'to mark every branch with support of at least ' + _settings.supportDotMinimum + '% with a dot at its midpoint'));
+                opts.push(makeCheckboxItem('Support Dots', SUPPORT_DOTS_CB, 'to mark a branch with support of at least ' + _settings.supportDotMinimum + '% with a dot at its midpoint, where there is room to draw it'));
             }
             // Styles and visualizations sit here too, so the Nodes group only
             // appears at all on a tree carrying node/branch events
@@ -15164,7 +16304,8 @@ function (root, d3, forester, phyloXml) {
             h = h.concat('<fieldset>');
             h = h.concat('<input type="button" value="Download" name="' + DOWNLOAD_BUTTON + '" title="download/export tree in a selected format" id="' + DOWNLOAD_BUTTON + '">');
             //h = h.concat('<br>');
-            h = h.concat('<select name="' + EXPORT_FORMAT_SELECT + '" id="' + EXPORT_FORMAT_SELECT + '">');
+            h = h.concat('<select name="' + EXPORT_FORMAT_SELECT + '" id="' + EXPORT_FORMAT_SELECT
+                + '" aria-label="Download format" title="the file format the Download button writes">');
             if (pngExportAvailable()) {
                 h = h.concat('<option value="' + PNG_EXPORT_FORMAT + '">' + PNG_EXPORT_FORMAT + '</option>');
             }
@@ -15314,8 +16455,10 @@ function (root, d3, forester, phyloXml) {
             let h = "";
             h = h.concat('<label class="aptx-field-label" for="' + val + '">' + label + '</label>');
             h = h.concat('<div class="aptx-search-menus">');
-            h = h.concat('<select class="aptx-search-field" name="' + fsel + '" id="' + fsel + '" title="the field to search in"></select>');
-            h = h.concat('<select class="aptx-search-mode" name="' + msel + '" id="' + msel + '" title="how to match"></select>');
+            h = h.concat('<select class="aptx-search-field" name="' + fsel + '" id="' + fsel
+                + '" aria-label="' + label + ' field" title="the field to search in"></select>');
+            h = h.concat('<select class="aptx-search-mode" name="' + msel + '" id="' + msel
+                + '" aria-label="' + label + ' match" title="how to match"></select>');
             h = h.concat('</div>');
             h = h.concat('<div class="aptx-search-row">');
             h = h.concat('<input class="aptx-search-value" autocomplete="off" title="' + valTip + '" type="text" name="' + val + '" id="' + val + '">');
@@ -15522,9 +16665,15 @@ function (root, d3, forester, phyloXml) {
     }
 
     function setDisplayTypeButtons() {
-        setRadioButtonValue(PHYLOGRAM_BUTTON, _state.phylogram && !_state.alignPhylogram);
-        setRadioButtonValue(CLADOGRAM_BUTTON, !_state.phylogram && !_state.alignPhylogram);
-        setRadioButtonValue(PHYLOGRAM_ALIGNED_BUTTON, _state.alignPhylogram && _state.phylogram);
+        // In circular the labels ARE aligned, whatever alignPhylogram says, so
+        // that is the button shown as chosen: the panel describes the picture.
+        // The flag itself is left alone -- it is the user's choice for the
+        // layouts that can express it, and returning to rectangular restores
+        // what they picked there.
+        let alignedLook = _state.phylogram && (_state.alignPhylogram || _state.circularDisplay);
+        setRadioButtonValue(PHYLOGRAM_BUTTON, _state.phylogram && !alignedLook);
+        setRadioButtonValue(CLADOGRAM_BUTTON, !_state.phylogram);
+        setRadioButtonValue(PHYLOGRAM_ALIGNED_BUTTON, alignedLook);
         setCheckboxValue(LAYOUT_CIRC_BUTTON, _state.circularDisplay);
         setCheckboxValue(LAYOUT_UNROOTED_BUTTON, _state.unrootedDisplay);
         setCheckboxValue(LAYOUT_RECT_BUTTON, !radialDisplay());
@@ -15545,6 +16694,7 @@ function (root, d3, forester, phyloXml) {
 
     function updateButtonEnabledState() {
         syncZoomRowButtons(); // layout- and tree-dependent disables track every render
+        refreshCheatSheet();  // an open sheet describes the panel as it is now
         // the uncollapse-all button lives only while something is collapsed, as on the desktop
         ((_root && collapseAllowed() && hasCollapsedIn(_root)) ? enableButton : disableButton)(byId(UNCOLLAPSE_ALL_BUTTON));
         if (_in_subtree) {