archaeopteryx 3.26.0 → 3.27.0

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.26.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.26.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() {
@@ -440,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';
@@ -1938,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');
             }
@@ -1968,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'));
@@ -5825,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];
         });
@@ -6078,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');
             }
         }
@@ -6111,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');
             }
         }
@@ -6347,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)) {
@@ -6640,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
@@ -6715,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();
@@ -6767,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
@@ -6977,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;
     }
 
@@ -10370,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));
         }
     }
 
@@ -15904,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 {
@@ -16817,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;'
@@ -16974,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
@@ -17255,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';
@@ -18088,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');
 
@@ -18123,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');
@@ -18138,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();
@@ -18149,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);
@@ -18720,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;
         }
@@ -19397,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);
@@ -20139,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;
@@ -20188,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);
         });
     }
 
@@ -20234,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);
         });
     }
 
@@ -20252,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;
@@ -20313,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');
         });
     }
@@ -20480,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'
@@ -20508,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);
-    };
+    }
 
 
 // --------------------------------------------------------------