archaeopteryx 3.25.0 → 3.27.0

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.25.0
+// v 3.27.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.25.0';
+    const VERSION = '3.27.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';
@@ -303,6 +303,52 @@ function (root, d3, forester, phyloXml) {
     const MESSAGE = 'ArchaeopteryxJS: ';
     const ERROR = 'ArchaeopteryxJS: ERROR: ';
 
+    // What this launch had to say, kept as well as printed. The console is
+    // where a warning goes and where nobody embedding the viewer looks: a
+    // site passed a retired key for a month and a forced visualization for
+    // longer (BV-BRC, 2026-10-08), each announced on every page load. The
+    // Diagnostics report (archaeopteryx.doctor, further down) reads this
+    // list; 'problem' entries are somebody's mistake and light the dot on
+    // the program name, 'note' entries are only stated. The same line twice
+    // is one entry with a count.
+    //
+    // The list belongs to the tree on view. It starts afresh whenever the
+    // launch proper (launchInto) begins for a tree -- a new launch, or
+    // showTree() moving to another tree of the file, whose config warnings
+    // are then said again and whose per-tree ones are its own. A launch that
+    // is REJECTED while an earlier viewer is still on the page gives that
+    // viewer its list back and adds one line saying what failed (the shell
+    // round launch()): the page still shows the earlier tree, and the report
+    // describes the page.
+    const DIAGNOSTICS_MAX = 40;
+    let _diagnostics = [];
+    // What is on view, noted at the moment a launch takes the page over (it
+    // clears the container): the report's "launch" section and the dot read
+    // this, never the module's working state, which a launch writes to
+    // before the checks that can still reject it.
+    let _onView = null;
+    let _tookOver = false;
+    let _recordedErrors = (typeof WeakSet === 'function') ? new WeakSet() : null;
+    function recordDiagnostic(level, line) {
+        let text = String(line).replace(/^ArchaeopteryxJS: (WARNING: |ERROR: )?/, '');
+        let seen = _diagnostics.find(function (d) {
+            return d.level === level && d.text === text;
+        });
+        if (seen) {
+            seen.count += 1;
+        } else if (_diagnostics.length < DIAGNOSTICS_MAX) {
+            _diagnostics.push({level: level, text: text, count: 1});
+        }
+        if (level === 'problem') {
+            syncDoctorDot();
+        }
+    }
+    // Print as before (same console method, same line) and keep it.
+    function say(level, method, line) {
+        console[method](line);
+        recordDiagnostic(level, line);
+    }
+
     // Call-time dependency guards (the UMD header explains why they are not
     // load-time): each failure names exactly what is missing.
     function requireD3() {
@@ -390,6 +436,7 @@ function (root, d3, forester, phyloXml) {
     const GENE_LABELS_SELECT = 'gene_labels';
     const SCALE_AXIS_CB = 'scaleaxis_cb';
     const SCALE_GRID_CB = 'scalegrid_cb';
+    const SCALE_BAR_CB = 'scalebar_cb';
     const MSA_SCROLL_ID = 'aptxmsascroll';
     const FONT_SIZE_SLIDER = 'fs_sl';
     const EXTERNAL_LABEL_CB = 'extl_cb';
@@ -439,6 +486,7 @@ function (root, d3, forester, phyloXml) {
     const CLOCK_PLOT_BUTTON = 'clock_plot_b';
     const CLOCK_PLOT_DIALOG = 'aptx_clock_plot';
     const ABOUT_DIALOG = 'aptx_about';
+    const DOCTOR_DIALOG = 'aptx_doctor';
     const TREE_PROPERTIES_DIALOG = 'aptx_tree_props';
     const PROG_NAME = 'progname';
     const PROGNAMELINK = 'prognamelink';
@@ -1447,8 +1495,9 @@ function (root, d3, forester, phyloXml) {
     // a node coloured by Host Group glows in its host colour -- and the UI
     // accent otherwise. As on the desktop (TreePanel.hoverGlowColor). The
     // precedence is the one the node itself is painted by: the Color-by
-    // value, then a per-node visual style, then an event colour, then a
-    // colourised clade's branch colour. NEVER the found/search colour: a
+    // value, then a per-node visual style (not while a Color-by is active,
+    // see nodeStyleColor), then an event colour, then a colourised clade's
+    // branch colour. NEVER the found/search colour: a
     // focus ring must not read as a selection state.
     //
     // The glow is a 13-23% alpha wash, so a dark or a pale colour would
@@ -1462,10 +1511,7 @@ function (root, d3, forester, phyloXml) {
             c = vis;
         }
         if (!c) {
-            let style = nodeStyle(d);
-            if (style && (style.nodeColor || style.fontColor)) {
-                c = style.nodeColor || style.fontColor;
-            }
+            c = nodeStyleColor(d);
         }
         if (!c && _state.showNodeEvents && d.events && d.children) {
             c = makeNodeEventsDependentColor(d.events);
@@ -1939,7 +1985,7 @@ function (root, d3, forester, phyloXml) {
                     || (c.label && String(c.label).toLowerCase() === want);
             }) || null;
             if (!requested) {
-                console.warn(WARNING + ': initialVisualization "'
+                say('problem', 'warn', WARNING + ': initialVisualization "'
                     + _settings.initialVisualization
                     + '" names no visualization of this tree; using the automatic choice');
             }
@@ -1969,7 +2015,7 @@ function (root, d3, forester, phyloXml) {
                     ? requested.values.length + ' distinct values on this tree, more than the '
                         + LEGEND_MAX_ROWS + ' the legend lists'
                     : 'a value on ' + requested.coverage + ' of the tree\'s ' + requested.total + ' tips';
-                console.warn(WARNING + ': initialVisualization "' + _settings.initialVisualization
+                say('problem', 'warn', WARNING + ': initialVisualization "' + _settings.initialVisualization
                     + '" names a field with ' + why + '; left to itself the viewer would '
                     + (auto ? 'open with "' + auto.label + '" (' + auto.values.length + ' values)'
                         : 'open uncoloured'));
@@ -2430,6 +2476,36 @@ function (root, d3, forester, phyloXml) {
         return ((_vis && _vis.colorId) ? _vis.byId[_vis.colorId] : null) || null;
     }
 
+    // A Color visualization is on screen: it owns every node's colour, and the
+    // file's style colours wait until the Color menu is cleared (the desktop's
+    // rule; see makeLabelColor and makeNodeFillColor).
+    function colorVisActive() {
+        return !!_state.showVisualizations && !!currentColorVis();
+    }
+
+    // The colour a node's style gives it, or null: style:node_color (else
+    // style:font_color) for the node's mark, style:font_color for its label.
+    // Null while a Color visualization is active -- the desktop's rule
+    // (TreePanel.setColor): the visualization owns every node's colour and
+    // its legend explains them; a node without a value takes the default ink
+    // and no dot rather than the file's colour. Until 2026-10-08 the valueless
+    // nodes fell through to the file's colour on their dots, so BV-BRC's
+    // trees -- style:font_color on every tip, following Genus -- showed two
+    // palettes under Color by Host (Christian: adopt the desktop's rule).
+    // EVERY reader of a style colour goes through here, so none can forget
+    // the rule: the label, the dot, its outline, the hover glow, the clock
+    // plot's points (which a first version of the rule missed).
+    function nodeStyleColor(node, forLabel) {
+        if (colorVisActive()) {
+            return null;
+        }
+        let style = nodeStyle(node);
+        if (!style) {
+            return null;
+        }
+        return (forLabel ? style.fontColor : (style.nodeColor || style.fontColor)) || null;
+    }
+
     function currentShapeVis() {
         return ((_vis && _vis.shapeId) ? _vis.byId[_vis.shapeId] : null) || null;
     }
@@ -3676,11 +3752,9 @@ function (root, d3, forester, phyloXml) {
         if (visColor !== _state.backgroundColorDefault) {
             return visColor;
         }
-        let style = nodeStyle(phynode);
-        if (style && (style.nodeColor || style.fontColor)) {
-            return style.nodeColor || style.fontColor;
-        }
-        return visColor;
+        // the style colour, or the background -- which, under an active Color
+        // visualization, drawTreeGeometry turns into no dot at all
+        return nodeStyleColor(phynode) || visColor;
     };
 
     // A darker shade of a node's found/selected highlight color, used as a thin
@@ -3713,10 +3787,11 @@ function (root, d3, forester, phyloXml) {
                 return v;
             }
         }
-        let style = nodeStyle(phynode);
-        if (style && (style.nodeColor || style.fontColor)) {
-            return style.nodeColor || style.fontColor;
+        let styleColor = nodeStyleColor(phynode);
+        if (styleColor) {
+            return styleColor;
         }
+        // the branch colour, unlike a style colour, holds under a Color-by (desktop)
         if (_state.useVisualStyles && phynode.color) {
             let c = phynode.color;
             return "rgb(" + c.red + "," + c.green + "," + c.blue + ")";
@@ -3729,17 +3804,15 @@ function (root, d3, forester, phyloXml) {
         if (foundColor) {
             return foundColor;
         }
-        if (_state.showVisualizations && currentColorVis()) {
-            let color = makeVisLabelColor(phynode);
-            if (color) {
-                return color;
-            }
+        // an active Color visualization owns the colours: its colour where
+        // the node has a value, the default ink where it has none (and
+        // nodeStyleColor is null meanwhile, see there)
+        if (colorVisActive()) {
+            return makeVisLabelColor(phynode);
         }
-        // an active Color visualization outranks style:font_color, as on the
-        // desktop; clear the Color menu to see the tree as its file styled it
-        let style = nodeStyle(phynode);
-        if (style && style.fontColor) {
-            return style.fontColor;
+        let fontColor = nodeStyleColor(phynode, true);
+        if (fontColor) {
+            return fontColor;
         }
         if (_state.useVisualStyles && phynode.color) {
             let c = phynode.color;
@@ -5747,6 +5820,7 @@ function (root, d3, forester, phyloXml) {
         'geneFamily',
         'geneLabels',
         'showScaleAxis',
+        'showScaleBar',
         'showScaleGrid',
         'showSupportDots',
         'searchAinitialValue',
@@ -5798,14 +5872,14 @@ function (root, d3, forester, phyloXml) {
                 return;
             }
             if (dep.to) {
-                console.warn(WARNING + ': "' + k + '" was replaced by "' + dep.to
+                say('problem', 'warn', WARNING + ': "' + k + '" was replaced by "' + dep.to
                     + '": ' + dep.note);
                 // An explicit new key always wins over the old alias.
                 if (given[dep.to] === undefined) {
                     given[dep.to] = dep.map(given[k]);
                 }
             } else {
-                console.warn(WARNING + ': "' + k + '" is retired and has no effect: ' + dep.note);
+                say('problem', 'warn', WARNING + ': "' + k + '" is retired and has no effect: ' + dep.note);
             }
             delete given[k];
         });
@@ -6051,7 +6125,7 @@ function (root, d3, forester, phyloXml) {
             // malformed domains are skipped, never fatal -- said once, here
             let ignored = forester.domainArchitectureStats(_treeData).ignored;
             if (ignored > 0) {
-                console.warn(MESSAGE + ignored + ' protein domain' + (ignored === 1 ? '' : 's')
+                say('note', 'warn', MESSAGE + ignored + ' protein domain' + (ignored === 1 ? '' : 's')
                     + ' with a missing or impossible from / to / E-value ignored');
             }
         }
@@ -6084,11 +6158,11 @@ function (root, d3, forester, phyloXml) {
             // are left out, never fatal -- said once, here
             let gs = forester.geneRegionStats(_treeData);
             if (gs.ignored > 0) {
-                console.warn(MESSAGE + gs.ignored + ' sequence location' + (gs.ignored === 1 ? '' : 's')
+                say('note', 'warn', MESSAGE + gs.ignored + ' sequence location' + (gs.ignored === 1 ? '' : 's')
                     + ' not in the form contig:start-end(+) ignored');
             }
             if (gs.otherContigs > 0) {
-                console.warn(MESSAGE + gs.otherContigs + ' gene' + (gs.otherContigs === 1 ? '' : 's')
+                say('note', 'warn', MESSAGE + gs.otherContigs + ' gene' + (gs.otherContigs === 1 ? '' : 's')
                     + ' on a genome\'s other contigs not drawn: the gene track shows one contig per genome');
             }
         }
@@ -6113,6 +6187,8 @@ function (root, d3, forester, phyloXml) {
             _state.showScaleAxis = !!(_timeInfo && _timeInfo.type) && !branchesShowDivergence();
         }
         _state.showScaleGrid = _state.showScaleGrid === true; // desktop default: off
+        // the scale bar is on unless the caller says no; it gives way to the axis anyway
+        _state.showScaleBar = _state.showScaleBar !== false;
         _state.showSupportDots = _state.showSupportDots === true;
         _state.showNodeEvents = _basicTreeProperties.nodeEvents === true;
         _state.showBranchEvents = _basicTreeProperties.branchEvents === true;
@@ -6318,11 +6394,11 @@ function (root, d3, forester, phyloXml) {
             _settings.enableDynamicSizing = true;
         }
         if (_settings.displayWidth && _settings.enableDynamicSizing === true) {
-            console.log(WARNING + ': dynamic sizing is turned on, will ignore displayWidth setting');
+            say('note', 'log', WARNING + ': dynamic sizing is turned on, will ignore displayWidth setting');
             _settings.displayWidth = 0;
         }
         if (_settings.displayHeight && _settings.enableDynamicSizing === true) {
-            console.log(WARNING + ': dynamic sizing is turned on, will ignore displayHeight setting');
+            say('note', 'log', WARNING + ': dynamic sizing is turned on, will ignore displayHeight setting');
             _settings.displayHeight = 0;
         }
         if ((!_settings.displayWidth) && (!_settings.enableDynamicSizing)) {
@@ -6611,7 +6687,40 @@ function (root, d3, forester, phyloXml) {
 
     // launch(container, tree, config) -> a viewer handle {getSelectedNodes,
     // destroy}. Exactly three arguments; config is THE one config object.
-    archaeopteryx.launch = function (container, phylo, config) {
+    // launch() proper is launchChecked below. This shell keeps what a
+    // rejected launch said: the thrown message reaches whoever called, which
+    // on an embedding site is often a catch block nobody reads, and
+    // archaeopteryx.doctor() can still tell. (launchArchaeopteryx has its own
+    // failures -- a file that does not parse -- and reports them through the
+    // same function; an error is recorded once, whoever catches it first.)
+    function recordLaunchFailure(e) {
+        if (_recordedErrors && e && typeof e === 'object') {
+            if (_recordedErrors.has(e)) {
+                return;
+            }
+            _recordedErrors.add(e);
+        }
+        recordDiagnostic('problem', 'launch failed: '
+            + String(e && e.message ? e.message : e).replace(/^ArchaeopteryxJS: ERROR: /, ''));
+    }
+    archaeopteryx.launch = function () {
+        let before = _diagnostics;
+        let wasOnView = _onView;
+        _tookOver = false;
+        try {
+            return launchChecked.apply(null, arguments);
+        } catch (e) {
+            if (wasOnView && !_tookOver) {
+                // rejected before it touched the page: the earlier viewer is
+                // still there, and so is everything said about it
+                _diagnostics = before;
+            }
+            recordLaunchFailure(e);
+            throw e;
+        }
+    };
+
+    function launchChecked(container, phylo, config) {
 
         // Bad input is the caller's bug, so it is thrown at the caller. It used
         // to pop a browser alert and return, which blocks the whole tab and
@@ -6686,12 +6795,14 @@ function (root, d3, forester, phyloXml) {
         let view = config && config.view;
         let start = (view && Number.isInteger(view.tree) && view.tree > 0 && view.tree < trees.length) ? view.tree : 0;
         return launchInto(container, trees, start, config);
-    };
+    }
 
     // The launch proper, for one tree of the list: launch() validates and
     // starts at the first, showTree() re-enters here for another.
     function launchInto(container, trees, index, config) {
         let phylo = trees[index];
+        // what is said from here on is said about THIS tree (see _diagnostics)
+        _diagnostics = [];
         let cfg = readConfig(config);
         requireForester();
         requireD3();
@@ -6738,6 +6849,11 @@ function (root, d3, forester, phyloXml) {
         checkLayoutValue(cfg.state ? cfg.state.layout : undefined);
         initializeSettings(cfg.settings);
 
+        // From here the page is this launch's: nothing below is expected to
+        // throw, and what a previous one drew goes now.
+        _tookOver = true;
+        _onView = {config: config, container: containerEl, tips: _basicTreeProperties.externalNodesCount,
+            tree: index + 1, trees: trees.length};
         // whatever a previous launch left in this container (or in the
         // container before it) goes now, so the old tree does not sit under
         // the card while the new one is prepared
@@ -6948,6 +7064,11 @@ function (root, d3, forester, phyloXml) {
         cfg.view = view || viewForTree(_trees[index]);
         let handle = launchInto(_container, _trees, index, cfg);
         _launchConfig = launchConfig;
+        // the report shows the config the SITE passed, not this copy with
+        // the tree's own view added
+        if (_onView) {
+            _onView.config = launchConfig;
+        }
         return handle;
     }
 
@@ -10018,6 +10139,7 @@ function (root, d3, forester, phyloXml) {
         if (_basicTreeProperties.branchLengths === true) {
             s.scaleAxis = _state.showScaleAxis === true;
             s.scaleGrid = _state.showScaleGrid === true;
+            s.scaleBar = _state.showScaleBar === true;
         }
         if (_branchScaleAvailable) {
             s.scale = _state.branchScale;   // time or divergence: which layout the branches show
@@ -10199,6 +10321,9 @@ function (root, d3, forester, phyloXml) {
         if (typeof grid === 'boolean') {
             _state.showScaleGrid = grid;
         }
+        if (typeof s.scaleBar === 'boolean') {
+            _state.showScaleBar = s.scaleBar;
+        }
         if (!radialDisplay()) {
             _radialLabelsHorizontal = false;
         } else if ((_state.showDomainArchitectures && _basicTreeProperties.domainArchitectures)
@@ -10275,6 +10400,7 @@ function (root, d3, forester, phyloXml) {
         syncHeatmapControls();
         setCheckboxValue(SCALE_AXIS_CB, _state.showScaleAxis === true);
         setCheckboxValue(SCALE_GRID_CB, _state.showScaleGrid === true);
+        setCheckboxValue(SCALE_BAR_CB, _state.showScaleBar === true);
         setCheckboxValue(DOMAIN_GLOW_CB, _state.domainGlow === true);
         setValue(DOMAIN_LABELS_SELECT, _state.domainLabels);
         syncDomainControls();
@@ -10336,7 +10462,7 @@ function (root, d3, forester, phyloXml) {
         try {
             _settings.onViewChange(state, encoded);
         } catch (e) {
-            console.error(ERROR + 'onViewChange threw: ' + (e && e.message ? e.message : e));
+            say('problem', 'error', ERROR + 'onViewChange threw: ' + (e && e.message ? e.message : e));
         }
     }
 
@@ -10355,7 +10481,7 @@ function (root, d3, forester, phyloXml) {
     const VIEW_INT_KEYS = ['tree', 'subtree', 'rotation', 'domainEvalue'];
     const VIEW_NUMBER_KEYS = ['font', 'node', 'branch'];
     const VIEW_BOOL_KEYS = ['horizontalLabels', 'msa', 'msaLogo', 'heatmap', 'domains', 'domainGlow', 'genes',
-        'scaleAxis', 'scaleGrid', 'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
+        'scaleAxis', 'scaleGrid', 'scaleBar', 'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
     // Lists of strings, comma-joined. A property ref carries ':' but never a
     // comma, and encodeViewValue leaves both readable in a hash.
     const VIEW_LIST_KEYS = ['heatmapManual', 'labelFields'];
@@ -11350,9 +11476,9 @@ function (root, d3, forester, phyloXml) {
         if (vis) {
             return vis;
         }
-        let style = nodeStyle(node);
-        if (style && (style.nodeColor || style.fontColor)) {
-            return style.nodeColor || style.fontColor;
+        let styleColor = nodeStyleColor(node);   // null under an active Color-by, as in the tree
+        if (styleColor) {
+            return styleColor;
         }
         if (_state.useVisualStyles && node.color) {
             return 'rgb(' + node.color.red + ',' + node.color.green + ',' + node.color.blue + ')';
@@ -13501,7 +13627,8 @@ function (root, d3, forester, phyloXml) {
     const SCALE_BAR_RESERVE = 30;
 
     function scaleBarShown() {
-        return _state.phylogram === true && _basicTreeProperties.branchLengths === true && !scaleAxisShown();
+        return _state.phylogram === true && _basicTreeProperties.branchLengths === true && !scaleAxisShown()
+            && _state.showScaleBar !== false;
     }
 
     // pixels per branch-length unit in the current layout's own coordinates
@@ -13527,7 +13654,9 @@ function (root, d3, forester, phyloXml) {
         if (!scaleBarShown()) {
             return;
         }
-        let bar = forester.scaleBarLength(branchLengthPixelsPerUnit(), SCALE_BAR_TARGET_PX);
+        // the unit the file states, as the distance axis prints it; none when it states none
+        let unit = _treeData && typeof _treeData.branch_length_unit === 'string' ? _treeData.branch_length_unit.trim() : '';
+        let bar = forester.scaleBarLength(branchLengthPixelsPerUnit(), SCALE_BAR_TARGET_PX, unit);
         if (!bar) {
             return;
         }
@@ -14161,6 +14290,11 @@ function (root, d3, forester, phyloXml) {
         scheduleUpdate(null, 0);
     }
 
+    function scaleBarCbClicked() {
+        _state.showScaleBar = getCheckboxValue(SCALE_BAR_CB);
+        scheduleUpdate(null, 0);
+    }
+
     // Fit the circular tree into the viewport, centred. The root is at the
     // group origin (0,0), so we place that at the viewport centre and scale so
     // the outer label ring fits. Computed from the known radial extent rather
@@ -15319,6 +15453,12 @@ function (root, d3, forester, phyloXml) {
             gridCb.disabled = _state.unrootedDisplay === true || _state.phylogram !== true
                 || _state.showScaleAxis !== true;
         }
+        let barCb = byId(SCALE_BAR_CB);
+        if (barCb) {
+            // a cladogram has nothing to measure, and under the axis the bar
+            // has given way; every layout can carry it otherwise
+            barCb.disabled = _state.phylogram !== true || scaleAxisShown();
+        }
         let minus = byId(ZOOM_OUT_X);
         let plus = byId(ZOOM_IN_X);
         let expandV = byId(ZOOM_TO_EXPAND_Y);
@@ -15856,14 +15996,17 @@ function (root, d3, forester, phyloXml) {
     // The async clipboard API where the page allows it (a secure context);
     // otherwise the old select-and-copy, so a page served over plain http
     // still copies. Resolves to whether the text made it.
-    function copyText(text) {
+    //
+    // `host` is the open modal dialog the copy is made from, if any: under a
+    // modal everything outside it is inert, a textarea on the body included.
+    function copyText(text, host) {
         let legacy = function () {
             let ta = document.createElement('textarea');
             ta.value = text;
             ta.setAttribute('readonly', '');
             ta.style.position = 'fixed';
             ta.style.left = '-10000px';
-            document.body.appendChild(ta);
+            (host || document.body).appendChild(ta);
             ta.select();
             let ok = false;
             try {
@@ -16769,6 +16912,11 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-dialog-close:hover { background:var(--p-accent-weak); color:var(--p-accent-ink);'
             + '  border-color:var(--p-accent); }'
             + '.aptx-dialog-body { padding:10px 13px 12px; overflow:auto; }'
+            // a dialog that scrolls gets the panel's own scrollbar: the
+            // browser's default track is white in the dark theme too
+            + '.aptx-dialog-body::-webkit-scrollbar { width:9px; height:9px; }'
+            + '.aptx-dialog-body::-webkit-scrollbar-thumb { background:var(--p-line-strong); border-radius:9px; border:2px solid var(--p-bg); }'
+            + '.aptx-dialog-body::-webkit-scrollbar-track, .aptx-dialog-body::-webkit-scrollbar-corner { background:transparent; }'
             + '.aptx-cp-sv { position:relative; width:100%; box-sizing:border-box; height:104px; border-radius:7px;'
             + '  border:1px solid var(--p-line-strong); cursor:crosshair; touch-action:none; }'
             + '.aptx-cp-hue { position:relative; width:100%; box-sizing:border-box; height:13px; margin-top:9px;'
@@ -16926,6 +17074,23 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-panel .' + PROGNAMELINK + ' { background:none; padding:0; margin:0; cursor:pointer;'
             + '  font-family:inherit; font-weight:inherit; letter-spacing:inherit; }'
             + '.aptx-panel .' + PROGNAMELINK + ':hover { text-decoration:underline; }'
+            + '.aptx-doctor-dot { display:inline-block; width:6px; height:6px; border-radius:50%; background:var(--p-muted); vertical-align:middle; }'
+            + '.aptx-doctor-dot[hidden] { display:none; }'
+            + '.aptx-panel .' + PROGNAMELINK + ' .aptx-doctor-dot { margin-left:6px; }'
+            + '.aptx-about .aptx-doctor-dot { margin-right:6px; }'
+            + '.aptx-dialog-body.aptx-doctor { max-height:min(70vh,560px); }'
+            + '.aptx-doctor .aptx-dialog-key { flex-basis:34%; }'
+            + '.aptx-doctor-head { display:flex; align-items:center; gap:10px; margin-bottom:6px; }'
+            + '.aptx-doctor-status { flex:1 1 auto; min-width:0; font-weight:650; }'
+            + '.aptx-doctor-status.aptx-doctor-bad { box-shadow:inset 3px 0 0 var(--p-warn); padding-left:9px; }'
+            + '.aptx-doctor-item { position:relative; padding:2px 0 2px 14px; line-height:1.35; overflow-wrap:anywhere; }'
+            + '.aptx-doctor-item::before { content:""; position:absolute; left:2px; top:0.62em; width:6px; height:6px; border-radius:50%; background:var(--p-faint); }'
+            + '.aptx-doctor-item.aptx-doctor-bad::before { background:var(--p-warn); }'
+            + '.aptx-doctor-item.aptx-doctor-note { color:var(--p-muted); }'
+            + '.aptx-doctor-section { margin:11px 0 3px; font-size:10.5px; font-weight:650; letter-spacing:0.05em; text-transform:uppercase; color:var(--p-muted); }'
+            + '.aptx-doctor-detail { display:block; color:var(--p-muted); line-height:1.35; }'
+            + '.aptx-doctor .aptx-dialog-line.aptx-doctor-bad .aptx-doctor-value { color:var(--p-warn); font-weight:600; }'
+            + '.aptx-doctor-copy { flex:none; }'
             + '.aptx-dialog-body.aptx-about { padding-top:13px; }'
             // the label column is narrower here than for node data: these values
             // are URLs, and they should not have to wrap mid-word
@@ -17207,6 +17372,16 @@ function (root, d3, forester, phyloXml) {
                     e.stopPropagation();
                     showAboutDialog();
                 });
+                // config warnings are recorded before this header exists
+                syncDoctorDot();
+                // ... and a library can arrive after it (see syncDoctorDot)
+                let panel = header.closest('.aptx-panel');
+                if (panel) {
+                    panel.addEventListener('pointerenter', syncDoctorDot);
+                }
+                if (document.readyState !== 'complete') {
+                    window.addEventListener('load', syncDoctorDot, {once: true});
+                }
 
                 let themeBtn = document.createElement('button');
                 themeBtn.type = 'button';
@@ -18040,10 +18215,693 @@ function (root, d3, forester, phyloXml) {
         shell.dialog.showModal();
     }
 
+    // ===================== Diagnostics =====================
+    // "Dependencies are checked when used, never at load time" makes the
+    // viewer hard to break and easy to run half-equipped without knowing: on
+    // BV-BRC it ran for weeks with no PDF or PNG export, a retired config key
+    // and a forced visualization, and every one of those was found by reading
+    // the site's source (Christian, 2026-10-09: a "check engine light" and a
+    // doctor behind it). This is the one place that says what is loaded, what
+    // that switches off, and what the launch complained about.
+    //
+    // Two rules decide what is a PROBLEM (lights the dot) and what is only
+    // stated:
+    //   * an optional library that is simply absent is a site's choice, and
+    //     is stated ("PDF export: off"), never flagged;
+    //   * something nobody chooses is a problem: half of a pair (jspdf
+    //     without svg2pdf.js), a library from the 2.x days under its old
+    //     global, a d3 that is not 7, forester.js from another release, a
+    //     phyloxml that no longer writes what this release expects, and every
+    //     warning or error the launch printed about its config.
+    // Only d3, jsPDF and forester state a version, so everything else is
+    // judged by what it can do.
+    //
+    // Nothing in here may throw: every check runs in its own try, and a check
+    // that fails says so in its own row.
+
+    // phyloxml states no version, so a small tree goes through it and what
+    // comes back is read for what an OLDER release is known to do. Each of
+    // these is a named fault, and each published release before 1.1.7 shows
+    // at least one (measured on 1.0.2, 1.1.3, 1.1.4, 1.1.5 and 1.1.6):
+    //   * it drops the domain architecture, or a <phylogeny>'s own property
+    //     (before 1.1.5 / 1.1.3): a saved tree LOSES data;
+    //   * it writes a style colour as it came, or the style property before
+    //     the node's other properties (before 1.1.7): the saved file differs
+    //     from the desktop program's.
+    // Whether the output is byte for byte what 1.1.7 writes is looked at too,
+    // but a difference there alone is only a NOTE. package.json admits any
+    // 1.1.x from 1.1.7 up, a release of this viewer cannot be corrected
+    // after it is published, and a newer phyloxml that lays a file out
+    // differently must not light a dot on every page that has it. (A first
+    // version demanded the bytes and called every difference "an older
+    // copy".)
+    const PHYLOXML_PROBE_IN = '<phyloxml xmlns="http://www.phyloxml.org"><phylogeny rooted="true"><clade>'
+        + '<clade><name>a</name><branch_length>1</branch_length>'
+        + '<sequence><domain_architecture length="9"><domain from="1" to="5" confidence="0.1">D</domain>'
+        + '</domain_architecture></sequence>'
+        + '<property ref="style:font_color" datatype="xsd:token" applies_to="node">#CE1616</property>'
+        + '<property ref="x:y" datatype="xsd:string" applies_to="node">v</property></clade>'
+        + '<clade><name>b</name><branch_length>2</branch_length></clade></clade>'
+        + '<property ref="p:q" datatype="xsd:string" applies_to="phylogeny">w</property></phylogeny></phyloxml>';
+    const PHYLOXML_PROBE_OUT = ['<?xml version="1.0" encoding="UTF-8"?>',
+        '<phyloxml xmlns="http://www.phyloxml.org">',
+        '<phylogeny rooted="true" rerootable="true">',
+        '  <clade>',
+        '    <clade>',
+        '      <name>a</name>',
+        '      <branch_length>1</branch_length>',
+        '      <sequence>',
+        '        <domain_architecture length="9">',
+        '          <domain from="1" to="5" confidence="0.1">D</domain>',
+        '        </domain_architecture>',
+        '      </sequence>',
+        '      <property ref="x:y" datatype="xsd:string" applies_to="node">v</property>',
+        '      <property ref="style:font_color" datatype="xsd:token" applies_to="node">#ce1616</property>',
+        '    </clade>',
+        '    <clade>',
+        '      <name>b</name>',
+        '      <branch_length>2</branch_length>',
+        '    </clade>',
+        '  </clade>',
+        '  <property ref="p:q" datatype="xsd:string" applies_to="phylogeny">w</property>',
+        '</phylogeny>',
+        '</phyloxml>'].join('\n');
+    const PHYLOXML_EXPECTED = '1.1.7';
+    const D3_TESTED_MINOR = 9;       // package.json: d3 ^7.9.0
+    const JSPDF_TESTED_MAJOR = 4;    // package.json: jspdf ^4.2.1
+
+    // The probe's answer for the library object it was asked about: the
+    // dot asks often, and the answer cannot change.
+    //   threw / stage   reading ('read') or writing ('write') failed, with the message
+    //   lost            what a saved tree no longer has
+    //   old             what is written as releases before 1.1.7 wrote it
+    //   same            the output is byte for byte 1.1.7's
+    let _phyloXmlProbe = null;
+    function probePhyloXml(px) {
+        if (_phyloXmlProbe && _phyloXmlProbe.lib === px) {
+            return _phyloXmlProbe.result;
+        }
+        let result = {threw: null, stage: null, lost: [], old: [], same: false};
+        let message = function (e) {
+            return String(e && e.message ? e.message : e);
+        };
+        let tree = null;
+        try {
+            tree = px.parse(PHYLOXML_PROBE_IN, {trim: true, normalize: true})[0];
+        } catch (e) {
+            result.threw = message(e);
+            result.stage = 'read';
+        }
+        let written = null;
+        if (!result.threw) {
+            try {
+                written = String(px.toPhyloXML(tree, 9));
+            } catch (e) {
+                result.threw = message(e);
+                result.stage = 'write';
+            }
+        }
+        if (written !== null) {
+            result.same = written === PHYLOXML_PROBE_OUT;
+            if (!/<domain from="1" to="5"[^>]*>D<\/domain>/.test(written)) {
+                result.lost.push('protein domains');
+            }
+            if (written.indexOf('ref="p:q"') < 0) {
+                result.lost.push('a tree\'s own properties');
+            }
+            if (written.indexOf('ref="x:y"') < 0) {
+                result.lost.push('node properties');
+            }
+            let style = written.indexOf('ref="style:font_color"');
+            if (style < 0) {
+                result.lost.push('node styles');
+            } else {
+                if (written.indexOf('>#ce1616<') < 0) {
+                    result.old.push('a style colour as it came, not in lower case');
+                }
+                if (written.indexOf('ref="x:y"') > style) {
+                    result.old.push('a node\'s style before its other properties');
+                }
+            }
+        }
+        _phyloXmlProbe = {lib: px, result: result};
+        return result;
+    }
+
+    // One library's row. `judge` returns {loaded, version, status, detail};
+    // status is 'ok', 'absent' (optional and not there: stated), 'note' or
+    // 'problem'.
+    function doctorLibrary(name, role, judge) {
+        let row = {name: name, role: role, loaded: false, version: null, status: 'problem', detail: ''};
+        try {
+            let j = judge();
+            row.loaded = !!j.loaded;
+            row.version = j.version || null;
+            row.status = j.status;
+            row.detail = j.detail || '';
+        } catch (e) {
+            row.detail = 'this check failed: ' + (e && e.message ? e.message : e);
+        }
+        return row;
+    }
+
+    function doctorLibraries() {
+        let g = root || {};
+        // without a document there is nothing to launch into: the parsers
+        // work with no d3 at all, so its absence there is not a fault
+        let inBrowser = typeof g.document !== 'undefined';
+        let libs = [];
+
+        libs.push(doctorLibrary('forester.js', 'required', function () {
+            let f = forester || g.forester;
+            if (!f) {
+                return {loaded: false, status: 'problem', detail: 'not loaded: nothing can be read or drawn'};
+            }
+            if (f.VERSION === VERSION) {
+                return {loaded: true, version: f.VERSION, status: 'ok'};
+            }
+            return {loaded: true, version: f.VERSION || null, status: 'problem',
+                detail: (f.VERSION ? 'forester.js is ' + f.VERSION : 'forester.js states no version, so it is an older file')
+                    + ', archaeopteryx.js is ' + VERSION + ': the two must come from the same release'};
+        }));
+
+        libs.push(doctorLibrary('d3', 'required', function () {
+            // THE d3 THE VIEWER USES, chosen as requireD3 chooses it: the one
+            // it was handed at load, and the page's global only where that
+            // one is missing or unusable. (A first version looked at the
+            // global first and could report on a d3 nothing was drawn with.)
+            let d = (g.d3 && (!d3 || typeof d3.zoom !== 'function')) ? g.d3 : d3;
+            if (!d) {
+                return inBrowser
+                    ? {loaded: false, status: 'problem', detail: 'not loaded: launch() fails without d3 version 7'}
+                    : {loaded: false, status: 'absent', detail: 'not loaded: only launch() needs it'};
+            }
+            let usable = typeof d.zoom === 'function' && typeof d.cluster === 'function';
+            let version = typeof d.version === 'string' ? d.version : null;
+            if (version === null) {
+                // d3's ES-module build exports no `version`: a bundler's
+                // `import * as d3`, jsdelivr's +esm, Node's require('d3'). It
+                // is judged by what only d3 7 has -- InternMap arrived with
+                // d3-array 3, which is d3 7.0.0 -- and never called outdated
+                // for not saying its number.
+                if (usable && typeof d.InternMap === 'function') {
+                    return {loaded: true, status: 'ok', detail: 'states no version (an ES-module build); has what d3 7 has'};
+                }
+                return {loaded: true, status: inBrowser ? 'problem' : 'absent',
+                    detail: inBrowser ? 'states no version and lacks what d3 7 has: Archaeopteryx.js needs d3 version 7'
+                        : 'not usable here as d3 version 7: only launch() needs it'};
+            }
+            let parts = version.split('.').map(Number);
+            if (parts[0] !== 7 || !usable) {
+                return {loaded: true, version: version, status: inBrowser ? 'problem' : 'absent',
+                    detail: inBrowser ? 'Archaeopteryx.js needs d3 version 7'
+                        : 'not usable here as d3 version 7: only launch() needs it'};
+            }
+            if (parts[1] < D3_TESTED_MINOR) {
+                return {loaded: true, version: version, status: 'note',
+                    detail: 'older than the 7.' + D3_TESTED_MINOR + ' this release is tested with'};
+            }
+            return {loaded: true, version: version, status: 'ok'};
+        }));
+
+        let px = null;
+        let probe = null;
+        libs.push(doctorLibrary('phyloxml', 'required', function () {
+            px = phyloXml || g.phyloXml;
+            probe = px ? probePhyloXml(px) : null;
+            if (!px) {
+                return {loaded: false, status: 'problem',
+                    detail: 'not loaded: phyloXML cannot be read, and the phyloXML download fails'};
+            }
+            if (probe.threw) {
+                // on a page phyloxml takes sax from the global, and a missing
+                // one is the usual reason reading fails; anywhere else, and
+                // for any other failure, the message itself is the finding
+                return {loaded: true, status: 'problem', detail: (probe.stage === 'read' && inBrowser && !g.sax)
+                    ? 'cannot read phyloXML: sax.js is not loaded'
+                    : (probe.stage === 'read' ? 'reading' : 'writing') + ' a small tree failed: ' + probe.threw};
+            }
+            if (probe.lost.length > 0) {
+                return {loaded: true, status: 'problem', detail: 'an older copy: saving a tree as phyloXML drops '
+                    + probe.lost.join(', ') + ' (phyloxml ' + PHYLOXML_EXPECTED + ' keeps them)'};
+            }
+            if (probe.old.length > 0) {
+                return {loaded: true, status: 'problem', detail: 'an older copy: it writes ' + probe.old.join(', and ')
+                    + ', so a saved tree differs from the desktop program\'s file (phyloxml ' + PHYLOXML_EXPECTED
+                    + ' does not)'};
+            }
+            if (!probe.same) {
+                return {loaded: true, status: 'note', detail: 'writes a small tree differently from phyloxml '
+                    + PHYLOXML_EXPECTED + ', losing nothing: a newer release, or an altered copy'};
+            }
+            return {loaded: true, status: 'ok', detail: 'writes phyloXML as ' + PHYLOXML_EXPECTED + ' does'};
+        }));
+        libs.push(doctorLibrary('sax', 'required', function () {
+            // A page hands sax over as a global. Anywhere else (Node, a
+            // bundler) phyloxml gets it by require() when it loads, so a
+            // phyloxml that loaded has it, and a tree it read proves it.
+            if (g.sax || (probe && probe.stage !== 'read')) {
+                return {loaded: true, status: 'ok'};
+            }
+            if (!inBrowser && px) {
+                return {loaded: true, status: 'ok', detail: 'taken by phyloxml when it loaded'};
+            }
+            return {loaded: false, status: 'problem', detail: 'not loaded: phyloxml needs it to read phyloXML'};
+        }));
+
+        libs.push(doctorLibrary('canvg', 'optional', function () {
+            if (g.Canvg && typeof g.Canvg.fromString === 'function') {
+                return {loaded: true, status: 'ok'};
+            }
+            if (g.Canvg) {
+                return {loaded: true, status: 'problem',
+                    detail: 'window.Canvg has no fromString: not canvg 4, so PNG export is off'};
+            }
+            if (g.canvg) {
+                return {loaded: true, status: 'problem', detail: 'loaded under its old global "canvg" (canvg 1 to 3);'
+                    + ' PNG export needs canvg 4 as window.Canvg, so it is off'};
+            }
+            return {loaded: false, status: 'absent', detail: 'not loaded: PNG export and Copy PNG are off'};
+        }));
+
+        // The pair is read inside each row's own guard: whatever a page has
+        // put under these names, a lookup that throws costs its row and no
+        // other.
+        let pdfPair = function () {
+            let J = g.jspdf && g.jspdf.jsPDF;
+            return {J: J, attached: !!(J && J.API && J.API.svg), svg2pdf: !!g.svg2pdf};
+        };
+        libs.push(doctorLibrary('jspdf', 'optional', function () {
+            let pair = pdfPair();
+            let J = pair.J;
+            let attached = pair.attached;
+            if (J) {
+                let version = typeof J.version === 'string' ? J.version : null;
+                if (!attached && !g.svg2pdf) {
+                    return {loaded: true, version: version, status: 'problem',
+                        detail: 'loaded without svg2pdf.js: PDF export needs both, so it is off'};
+                }
+                if (version && Number(version.split('.')[0]) !== JSPDF_TESTED_MAJOR) {
+                    return {loaded: true, version: version, status: 'note',
+                        detail: 'this release is tested with jspdf ' + JSPDF_TESTED_MAJOR};
+                }
+                return {loaded: true, version: version, status: 'ok'};
+            }
+            if (g.jsPDF) {
+                return {loaded: true, status: 'problem', detail: 'loaded under its old global "jsPDF" (jsPDF 1);'
+                    + ' PDF export needs jspdf ' + JSPDF_TESTED_MAJOR + ' as window.jspdf, so it is off'};
+            }
+            return {loaded: false, status: 'absent', detail: 'not loaded: PDF export is off'};
+        }));
+        libs.push(doctorLibrary('svg2pdf.js', 'optional', function () {
+            let pair = pdfPair();
+            let J = pair.J;
+            let attached = pair.attached;
+            if (attached) {
+                return {loaded: true, status: 'ok'};
+            }
+            if (g.svg2pdf && J) {
+                return {loaded: true, status: 'problem', detail: 'loaded, but not attached to jspdf (jsPDF.API.svg'
+                    + ' is missing): load jspdf first. PDF export is off'};
+            }
+            if (g.svg2pdf) {
+                return {loaded: true, status: 'problem',
+                    detail: 'loaded without jspdf: PDF export needs both, so it is off'};
+            }
+            return {loaded: false, status: 'absent',
+                detail: J ? 'not loaded' : 'not loaded: PDF export is off'};
+        }));
+        return libs;
+    }
+
+    // What the user gets or does not get, each with the reason.
+    function doctorFunctions(libs) {
+        let lib = function (name) {
+            return libs.find(function (l) {
+                return l.name === name;
+            });
+        };
+        let inBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+        let fn = function (name, test, whyNot) {
+            let available = false;
+            let detail = '';
+            try {
+                available = inBrowser && !!test();
+                detail = available ? '' : (inBrowser ? whyNot() : 'needs a browser');
+            } catch (e) {
+                detail = 'this check failed: ' + (e && e.message ? e.message : e);
+            }
+            return {name: name, available: available, detail: detail};
+        };
+        // why a function is off, in the library's name: its row's reason
+        // reads "not loaded: ..." under its own name and needs the subject here
+        let why = function (l) {
+            return l.status === 'absent' ? l.name + ' is not loaded' : l.name + ': ' + l.detail;
+        };
+        let out = [];
+        try {
+            // ON whenever phyloxml reads and writes at all -- which is what
+            // the Download menu's phyloXML entry does, and it is always
+            // offered. An older copy still works: its row above says what a
+            // saved file loses, and this row repeats it without turning off.
+            let px = lib('phyloxml');
+            let works = px.loaded && !/(cannot read phyloXML|a small tree failed|this check failed)/.test(px.detail);
+            out.push({name: 'Read and save phyloXML', available: works,
+                detail: px.status === 'ok' ? '' : (works ? px.detail : why(px))});
+        } catch (e) {
+            out.push({name: 'Read and save phyloXML', available: false,
+                detail: 'this check failed: ' + (e && e.message ? e.message : e)});
+        }
+        out.push(fn('PNG export', pngExportAvailable, function () {
+            return why(lib('canvg'));
+        }));
+        out.push(fn('Copy PNG', pngCopyAvailable, function () {
+            if (!pngExportAvailable()) {
+                return why(lib('canvg'));
+            }
+            return window.isSecureContext ? 'this browser cannot write an image to the clipboard'
+                : 'needs a secure page (https, or localhost)';
+        }));
+        out.push(fn('PDF export', pdfExportAvailable, function () {
+            let pair = [lib('jspdf'), lib('svg2pdf.js')];
+            let bad = pair.find(function (l) {
+                return l.status === 'problem';
+            });
+            if (bad) {
+                return why(bad);
+            }
+            return pair.every(function (l) {
+                return l.status === 'absent';
+            }) ? 'jspdf and svg2pdf.js are not loaded' : why(pair.find(function (l) {
+                return l.status !== 'ok';
+            }) || pair[0]);
+        }));
+        return out;
+    }
+
+    // A config value as one short word or number: enough to see what a site
+    // passed, never the value itself where that could be a tree or a callback.
+    function doctorConfigValue(v) {
+        if (v === null || typeof v === 'boolean' || typeof v === 'number') {
+            return v;
+        }
+        if (typeof v === 'string') {
+            return v.length > 80 ? v.substring(0, 77) + '...' : v;
+        }
+        if (typeof v === 'function') {
+            return '(function)';
+        }
+        if (Array.isArray(v)) {
+            return '(list of ' + v.length + ')';
+        }
+        return '(' + typeof v + ')';
+    }
+
+    // The tree on view, as noted when its launch took the page over
+    // (_onView): null until one has, so a first launch that was rejected
+    // describes no tree. The tip count is the one the launch computed.
+    function doctorLaunch() {
+        if (!_onView) {
+            return null;
+        }
+        let launch = {config: {}, tips: null, tree: _onView.tree, trees: _onView.trees, container: null};
+        try {
+            Object.keys(_onView.config || {}).sort().forEach(function (k) {
+                launch.config[k] = doctorConfigValue(_onView.config[k]);
+            });
+        } catch {
+            launch.config = {};
+        }
+        launch.tips = (typeof _onView.tips === 'number') ? _onView.tips : null;
+        try {
+            launch.container = {width: _onView.container.clientWidth, height: _onView.container.clientHeight};
+        } catch {
+            launch.container = null;
+        }
+        return launch;
+    }
+
+    function doctorText(rep) {
+        let pad = function (text, n) {
+            text = String(text);
+            return text + ' '.repeat(Math.max(1, n - text.length));
+        };
+        let lines = [NAME + ' ' + rep.version + ' diagnostics', ''];
+        lines.push('Status: ' + rep.summary);
+        rep.problems.forEach(function (p) {
+            lines.push('  ! ' + p);
+        });
+        lines.push('', 'Libraries');
+        rep.libraries.forEach(function (l) {
+            lines.push('  ' + pad(l.name, 13) + pad(l.version || (l.loaded ? 'loaded' : 'not loaded'), 12)
+                + pad(l.status === 'absent' ? l.role : l.status, 9) + l.detail);
+        });
+        lines.push('', 'Functions');
+        rep.functions.forEach(function (f) {
+            lines.push('  ' + pad(f.name, 24) + (f.available ? 'on' : 'off') + (f.detail ? '   ' + f.detail : ''));
+        });
+        if (rep.notes.length > 0) {
+            lines.push('', 'Notes');
+            rep.notes.forEach(function (n) {
+                lines.push('  - ' + n);
+            });
+        }
+        lines.push('', 'Launch');
+        if (rep.launch) {
+            lines.push('  config: ' + JSON.stringify(rep.launch.config));
+            if (rep.launch.tips !== null) {
+                lines.push('  tree: ' + rep.launch.tips + ' tips' + (rep.launch.trees > 1
+                    ? ' (tree ' + rep.launch.tree + ' of ' + rep.launch.trees + ')' : ''));
+            }
+            if (rep.launch.container) {
+                lines.push('  container: ' + rep.launch.container.width + ' x ' + rep.launch.container.height + ' px');
+            }
+        } else {
+            lines.push('  no tree is on view');
+        }
+        lines.push('', 'Environment');
+        lines.push('  ' + (rep.environment.userAgent || 'no browser'));
+        if (rep.environment.secureContext !== null) {
+            lines.push('  secure page: ' + (rep.environment.secureContext ? 'yes' : 'no'));
+        }
+        return lines.join('\n');
+    }
+
+    // The problems and the notes: the libraries' and what the launch said.
+    // This is all the dot needs, so it is kept apart from the report, which
+    // also works out the functions, the launch section and the text.
+    function doctorFindings() {
+        let libs;
+        try {
+            libs = doctorLibraries();
+        } catch (e) {
+            libs = [{name: 'libraries', role: 'required', loaded: false, version: null, status: 'problem',
+                detail: 'the checks failed: ' + (e && e.message ? e.message : e)}];
+        }
+        let problems = [];
+        let notes = [];
+        libs.forEach(function (l) {
+            if (l.status === 'problem') {
+                problems.push(l.name + ': ' + l.detail);
+            } else if (l.status === 'note') {
+                notes.push(l.name + (l.version ? ' ' + l.version : '') + ': ' + l.detail);
+            }
+        });
+        _diagnostics.forEach(function (d) {
+            (d.level === 'problem' ? problems : notes).push(d.text + (d.count > 1 ? ' (' + d.count + ' times)' : ''));
+        });
+        return {libraries: libs, problems: problems, notes: notes,
+            summary: problems.length === 0 ? 'nothing to report'
+                : problems.length + (problems.length === 1 ? ' thing' : ' things') + ' to check'};
+    }
+
+    function doctorReport() {
+        let found = doctorFindings();
+        let libs = found.libraries;
+        let problems = found.problems;
+        let notes = found.notes;
+        let functions;
+        try {
+            functions = doctorFunctions(libs);
+        } catch {
+            functions = [];
+        }
+        let launch = null;
+        try {
+            launch = doctorLaunch();
+        } catch {
+            launch = null;
+        }
+        let nav = (typeof navigator !== 'undefined') ? navigator : null;
+        let rep = {
+            program: NAME,
+            version: VERSION,
+            ok: problems.length === 0,
+            summary: found.summary,
+            problems: problems,
+            notes: notes,
+            libraries: libs,
+            functions: functions,
+            launch: launch,
+            environment: {
+                userAgent: nav && nav.userAgent ? nav.userAgent : null,
+                secureContext: (typeof window !== 'undefined' && typeof window.isSecureContext === 'boolean')
+                    ? window.isSecureContext : null
+            }
+        };
+        try {
+            rep.text = doctorText(rep);
+        } catch (e) {
+            rep.text = NAME + ' ' + VERSION + ' diagnostics: the report could not be written ('
+                + (e && e.message ? e.message : e) + ')';
+        }
+        return rep;
+    }
+
+    /**
+     * The state of the program on this page: which libraries are loaded (and
+     * their versions, where a library states one), which functions that
+     * switches off, and what the last launch() warned about. Works before a
+     * launch and after a failed one, and in Node. Never throws.
+     *
+     * @returns {{program: string, version: string, ok: boolean, summary: string,
+     *   problems: string[], notes: string[], libraries: Object[], functions: Object[],
+     *   launch: Object|null, environment: Object, text: string}} `ok` is false when
+     *   something is wrong that nobody chooses (see README "Diagnostics");
+     *   `text` is the whole report as plain text, for pasting into an issue.
+     */
+    archaeopteryx.doctor = function () {
+        let rep = doctorReport();
+        syncDoctorDot();   // whoever asks sees a dot that agrees with the answer
+        return rep;
+    };
+
+    // The "check engine light": a small dot after the program name in the
+    // panel header, there only while the report has a problem. Neutral, not
+    // a warning colour: the people who see it are mostly the site's users,
+    // who can do nothing about it, and it is for the one who can.
+    //
+    // What a page has loaded can change under a viewer that is already up (a
+    // library arriving late, a script replacing a global) and nothing
+    // announces it, so the dot is brought up to date whenever it could be
+    // looked at or asked about: when a problem is recorded, when the header
+    // is built, when the page finishes loading, when the pointer enters the
+    // panel, when the About box opens and when doctor() is called.
+    function syncDoctorDot() {
+        try {
+            let host = _onView && _onView.container;
+            if (!host || typeof host.querySelector !== 'function') {
+                return;
+            }
+            let button = host.querySelector('.aptx-panel .' + PROGNAMELINK);
+            let dot = button && button.querySelector('.aptx-doctor-dot');
+            if (!dot) {
+                return;
+            }
+            let found = doctorFindings();
+            let ok = found.problems.length === 0;
+            dot.hidden = ok;
+            button.title = 'About ' + NAME + (ok ? '' : ': ' + found.summary);
+        } catch {
+            // a light that cannot be lit must not take the viewer with it
+        }
+    }
+
+    function showDoctorDialog() {
+        let rep = doctorReport();
+        let shell = makeDialogShell(DOCTOR_DIALOG, 'Diagnostics', 500);
+        shell.body.classList.add('aptx-doctor');
+
+        // The summary and Copy report share the first line: the report is
+        // longer than a small window, and the one button must not be the
+        // thing scrolled out of sight.
+        let head = document.createElement('div');
+        head.className = 'aptx-doctor-head';
+        let status = document.createElement('div');
+        status.className = 'aptx-doctor-status' + (rep.ok ? '' : ' aptx-doctor-bad');
+        status.textContent = NAME + ' ' + rep.version + ': ' + rep.summary;
+        let copy = document.createElement('button');
+        copy.type = 'button';
+        copy.className = 'aptx-reps-button aptx-doctor-copy';
+        copy.textContent = 'Copy report';
+        copy.title = 'copy this report as text, with the launch configuration and the browser added,'
+            + ' to paste into an issue or an e-mail';
+        copy.addEventListener('click', function () {
+            copyText(rep.text, shell.dialog).then(function (ok) {
+                flashButton(copy, ok ? 'Copied \u2713' : 'Copy failed');
+            });
+        });
+        head.appendChild(status);
+        head.appendChild(copy);
+        shell.body.appendChild(head);
+
+        let list = function (items, cls) {
+            items.forEach(function (text) {
+                let item = document.createElement('div');
+                item.className = 'aptx-doctor-item ' + cls;
+                item.textContent = text;   // may quote a config value: never markup
+                shell.body.appendChild(item);
+            });
+        };
+        let section = function (title) {
+            let h = document.createElement('div');
+            h.className = 'aptx-doctor-section';
+            h.textContent = title;
+            shell.body.appendChild(h);
+        };
+        let row = function (key, value, detail, bad) {
+            let line = document.createElement('div');
+            line.className = 'aptx-dialog-line' + (bad ? ' aptx-doctor-bad' : '');
+            let k = document.createElement('span');
+            k.className = 'aptx-dialog-key';
+            k.textContent = key;
+            let v = document.createElement('span');
+            v.className = 'aptx-dialog-val';
+            let main = document.createElement('span');
+            main.className = 'aptx-doctor-value';
+            main.textContent = value;
+            v.appendChild(main);
+            if (detail) {
+                let d = document.createElement('span');
+                d.className = 'aptx-doctor-detail';
+                d.textContent = detail;
+                v.appendChild(d);
+            }
+            line.appendChild(k);
+            line.appendChild(v);
+            shell.body.appendChild(line);
+        };
+        list(rep.problems, 'aptx-doctor-bad');
+
+        section('Libraries');
+        rep.libraries.forEach(function (l) {
+            // "not loaded" is the value: a reason that opens with the same
+            // two words and a colon does not say them again. (Only that
+            // exact opening: "loaded, but not attached..." keeps its start.)
+            let value = l.version || (l.loaded ? 'loaded' : 'not loaded');
+            let detail = l.detail === value ? ''
+                : (l.detail.indexOf('not loaded: ') === 0 && value === 'not loaded' ? l.detail.substring(12) : l.detail);
+            row(l.name, value, detail, l.status === 'problem');
+        });
+        section('Functions');
+        rep.functions.forEach(function (f) {
+            row(f.name, f.available ? 'on' : 'off', f.detail, false);
+        });
+        if (rep.notes.length > 0) {
+            section('Notes');
+            list(rep.notes, 'aptx-doctor-note');
+        }
+
+        shell.dialog.showModal();
+    }
+
     // The About box behind the panel's title. Everything here is fixed text and
     // fixed URLs -- no tree data reaches it -- so the links are built as real
-    // elements rather than markup.
+    // elements rather than markup. (The Diagnostics row's text is the doctor's
+    // own summary: a count, never a value.)
     function showAboutDialog() {
+        let rep = doctorReport();
+        syncDoctorDot();
         let shell = makeDialogShell(ABOUT_DIALOG, 'About', 380);
         shell.body.classList.add('aptx-about');
 
@@ -18075,8 +18933,9 @@ 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+/') + ')'],
-            ['Control panel', null, 'what each control does']].forEach(function (row) {
+            ['Keyboard', null, 'shortcuts (' + (IS_MAC ? '\u2318 /' : 'Ctrl+/') + ')', showShortcutsDialog],
+            ['Control panel', null, 'what each control does', showCheatSheetDialog],
+            ['Diagnostics', null, rep.summary, showDoctorDialog]].forEach(function (row) {
             let line = document.createElement('div');
             line.className = 'aptx-dialog-line';
             let key = document.createElement('span');
@@ -18090,9 +18949,9 @@ function (root, d3, forester, phyloXml) {
                 a.target = '_blank';
                 a.rel = 'noopener noreferrer';
             } else {
-                // 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;
+                // the rows with no URL open another dialog in place of this
+                // one: the key list, the control-panel sheet, the diagnostics
+                let opener = row[3];
                 a.href = '#';
                 a.addEventListener('click', function (e) {
                     e.preventDefault();
@@ -18101,6 +18960,14 @@ function (root, d3, forester, phyloXml) {
                 });
             }
             a.textContent = row[2];
+            if (row[0] === 'Diagnostics') {
+                a.className = 'aptx-doctor-link';
+                if (!rep.ok) {
+                    let dot = document.createElement('span');
+                    dot.className = 'aptx-doctor-dot';
+                    val.appendChild(dot);
+                }
+            }
             val.appendChild(a);
             line.appendChild(key);
             line.appendChild(val);
@@ -18407,6 +19274,7 @@ function (root, d3, forester, phyloXml) {
         on(GENE_ANCHOR_SELECT, 'change', geneAnchorChanged);
         on(GENE_FAMILY_SELECT, 'change', geneFamilyChanged);
         on(GENE_LABELS_SELECT, 'change', geneLabelsChanged);
+        on(SCALE_BAR_CB, 'click', scaleBarCbClicked);
         on(SCALE_AXIS_CB, 'click', scaleAxisCbClicked);
         on(SCALE_GRID_CB, 'click', scaleGridCbClicked);
 
@@ -18671,7 +19539,8 @@ function (root, d3, forester, phyloXml) {
             // 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>');
+                + '" title="About ' + NAME + '">' + NAME + ' ' + VERSION
+                + '<span class="aptx-doctor-dot" hidden></span></button>');
             h = h.concat('</div>');
             return h;
         }
@@ -18944,6 +19813,9 @@ function (root, d3, forester, phyloXml) {
                 let timeAxis = _timeInfo && _timeInfo.type
                     ? (_timeInfo.type === 'geologic' ? 'the geologic (ICS) time axis' : 'the calendar time axis')
                     : null;
+                // "Scale", the desktop's label for the same switch (its Settings > Overlays > Scale & Grid)
+                opts.push(makeCheckboxItem('Scale', SCALE_BAR_CB, 'to show/hide the scale bar at the bottom left of a'
+                    + ' phylogram: a round length in the tree\'s branch-length unit (it gives way while the scale axis is on)'));
                 opts.push(makeCheckboxItem('Scale Axis', SCALE_AXIS_CB, 'to show/hide '
                     + (timeAxis ? timeAxis + ' and node-age bars (a distance axis while the branches show divergence)'
                         : 'a labeled distance axis from the root to the deepest tip')
@@ -19345,7 +20217,7 @@ function (root, d3, forester, phyloXml) {
             // 2x, 4x and 8x, and the setting is now the one it starts on
             // (Christian, 2026-09-28) -- said, not done silently
             if (_pngScale !== _settings.pngExportScale) {
-                console.warn(WARNING + ': pngExportScale ' + _settings.pngExportScale + ' is not one of '
+                say('problem', 'warn', WARNING + ': pngExportScale ' + _settings.pngExportScale + ' is not one of '
                     + DOWNLOAD_PNG_SCALES.join(', ') + ': the PNG starts at ' + _pngScale + 'x');
             }
             setRadioButtonValue(_downloadFullSize ? DOWNLOAD_FULL_SIZE_BUTTON : DOWNLOAD_AS_SHOWN_BUTTON, true);
@@ -19359,6 +20231,7 @@ function (root, d3, forester, phyloXml) {
         syncHeatmapControls();
         setCheckboxValue(SCALE_AXIS_CB, _state.showScaleAxis);
         setCheckboxValue(SCALE_GRID_CB, _state.showScaleGrid);
+        setCheckboxValue(SCALE_BAR_CB, _state.showScaleBar);
         setCheckboxValue(SHORTEN_NODE_NAME_CB, _state.shortenNodeNames);
         populateVisualizationMenus();
         initializeSearchOptions();
@@ -20086,7 +20959,7 @@ function (root, d3, forester, phyloXml) {
 
     function downloadAsPdf(graphic) {
         if (!pdfExportAvailable()) {
-            console.error(ERROR + 'PDF export needs the optional jspdf and svg2pdf.js libraries on the page');
+            say('note', 'error', ERROR + 'PDF export needs the optional jspdf and svg2pdf.js libraries on the page');
             return;
         }
         let el = new DOMParser().parseFromString(graphic.text, 'image/svg+xml').documentElement;
@@ -20135,7 +21008,7 @@ function (root, d3, forester, phyloXml) {
             holder.remove();
         }, function (err) {
             holder.remove();
-            console.error(ERROR + 'PDF export failed: ' + err);
+            say('note', 'error', ERROR + 'PDF export failed: ' + err);
         });
     }
 
@@ -20181,7 +21054,7 @@ function (root, d3, forester, phyloXml) {
         renderPng(graphic).then(function (blob) {
             saveAs(blob, downloadFileName(PNG_SUFFIX));
         }, function (err) {
-            console.error(ERROR + 'PNG export failed: ' + err);
+            say('note', 'error', ERROR + 'PNG export failed: ' + err);
         });
     }
 
@@ -20199,7 +21072,7 @@ function (root, d3, forester, phyloXml) {
             return Promise.reject(new Error('this browser cannot paint a canvas of that size'));
         }
         if (target.scale < _pngScale) {
-            console.warn(WARNING + ': PNG exported at ' + target.scale.toFixed(2) + 'x rather than ' + _pngScale
+            say('note', 'warn', WARNING + ': PNG exported at ' + target.scale.toFixed(2) + 'x rather than ' + _pngScale
                 + 'x: the largest image this browser can paint');
         }
         let canvas = target.canvas;
@@ -20260,7 +21133,7 @@ function (root, d3, forester, phyloXml) {
         written.then(function () {
             flashButton(btn, 'Copied ✓');
         }, function (err) {
-            console.error(ERROR + 'copying the PNG failed: ' + err);
+            say('note', 'error', ERROR + 'copying the PNG failed: ' + err);
             flashButton(btn, 'Copy failed');
         });
     }
@@ -20427,7 +21300,17 @@ function (root, d3, forester, phyloXml) {
         return undefined;
     }
 
-    archaeopteryx.launchArchaeopteryx = function (container, fileName, data, config) {
+    archaeopteryx.launchArchaeopteryx = function () {
+        try {
+            return parseAndLaunch.apply(null, arguments);
+        } catch (e) {
+            // its own failures -- a fifth argument, a file that does not
+            // parse -- happen before launch() and its shell are reached
+            recordLaunchFailure(e);
+            throw e;
+        }
+    };
+    function parseAndLaunch(container, fileName, data, config) {
         if (arguments.length > 4) {
             throw new Error(ERROR + 'launchArchaeopteryx() takes exactly (container, fileName,'
                 + ' data, config); the old trailing arguments were removed. The separate settings'
@@ -20455,7 +21338,7 @@ function (root, d3, forester, phyloXml) {
         // added nothing but a prefix, and swallowing them left the caller with
         // a blank page and no way to find out why.
         return archaeopteryx.launch(container, trees, config);
-    };
+    }
 
 
 // --------------------------------------------------------------