archaeopteryx 3.15.0 → 3.16.0

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.15.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.15.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';
@@ -2966,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);
@@ -3048,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;
                 });
@@ -3062,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
@@ -3130,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) {
@@ -3162,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')
@@ -3361,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');
@@ -3374,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) {
@@ -3397,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)) {
@@ -3870,8 +3859,8 @@ function (root, d3, forester, phyloXml) {
     // 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 decimates TIP labels
-    // and had never touched branch data.
+    // 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
@@ -3903,11 +3892,29 @@ function (root, d3, forester, phyloXml) {
     // 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 _branchFontCache = null;
+    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) {
-        if (_branchFontCache && _branchFontCache.px === fontPx) {
-            return _branchFontCache;
+        // 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;
@@ -3924,9 +3931,10 @@ function (root, d3, forester, phyloXml) {
         if (!(descent >= 0)) {
             descent = fontPx * (2 / 9);
         }
-        _branchFontCache = {px: fontPx, ascent: ascent, descent: descent,
+        let metrics = {px: fontPx, ascent: ascent, descent: descent,
             height: ascent + descent};
-        return _branchFontCache;
+        _fontMetricsCache.set(fontPx, metrics);
+        return metrics;
     }
 
     // Where a branch mark sits on its branch, read off the rendered elements
@@ -4018,6 +4026,238 @@ function (root, d3, forester, phyloXml) {
         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;
@@ -4034,7 +4274,12 @@ 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)) : '';
@@ -4044,7 +4289,13 @@ function (root, d3, forester, phyloXml) {
         // 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 !== ''
@@ -4070,8 +4321,9 @@ function (root, d3, forester, phyloXml) {
     // 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 is still skipped in unrooted: that one needs even row spacing
-    // to decimate against, and there is none.)
+    // 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;
@@ -4082,6 +4334,24 @@ function (root, d3, forester, phyloXml) {
         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) {
@@ -4093,6 +4363,33 @@ function (root, d3, forester, phyloXml) {
         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
@@ -4102,12 +4399,18 @@ function (root, d3, forester, phyloXml) {
                 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
@@ -4119,6 +4422,9 @@ function (root, d3, forester, phyloXml) {
                 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) {
@@ -4132,6 +4438,7 @@ function (root, d3, forester, phyloXml) {
                     : [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;
                 }
             }
         }
@@ -5165,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
@@ -9913,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();
             }
@@ -10017,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');
@@ -10353,7 +10934,27 @@ function (root, d3, forester, phyloXml) {
             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;
@@ -11519,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)
@@ -12315,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);
     }
@@ -12356,19 +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;
+            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 tip-label decimation it governs does not run --
-        // but it also governs the crowded branch-data rule, which does run
-        // there, so greying it out left the user unable to switch off something
-        // that was happening.
+        // 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();
@@ -12585,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) {
@@ -12594,10 +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, and branch data that would overlap'
+            ? item.dataset.baseTitle + ', hiding now: ' + parts.join(', and ')
             : item.dataset.baseTitle;
     }
 
@@ -13236,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) {
@@ -13304,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);
@@ -13502,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; }'
@@ -13573,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; }'
@@ -13824,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;
@@ -13895,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
@@ -14683,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');
@@ -14697,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];
@@ -15273,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;
         }
@@ -15424,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,
@@ -15514,7 +16224,7 @@ 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, and branch values that would overprint each other, where 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 a branch with support of at least ' + _settings.supportDotMinimum + '% with a dot at its midpoint, where there is room to draw it'));
@@ -15594,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>');
             }
@@ -15744,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 + '">');
@@ -15952,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());
@@ -15975,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) {