archaeopteryx 3.8.0 → 3.10.0

package/archaeopteryx.js

@@ -20,8 +20,8 @@
  *
  */
 
-// v 3.8.0
-// 2026-09-10
+// v 3.10.0
+// 2026-09-17
 //
 // Archaeopteryx.js is a software tool for the visualization and
 // analysis of highly annotated phylogenetic trees.
@@ -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.8.0';
+    const VERSION = '3.10.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';
@@ -404,6 +404,9 @@ function (root, d3, forester, phyloXml) {
     const PHYLOGRAM_ALIGNED_BUTTON = 'phya_b';
     const PHYLOGRAM_BUTTON = 'phy_b';
     const PHYLOGRAM_CLADOGRAM_CONTROLGROUP = 'phy_cla_g';
+    const BRANCH_SCALE_CONTROLGROUP = 'branch_scale_g';
+    const BRANCH_SCALE_TIME_BUTTON = 'branch_scale_time_b';
+    const BRANCH_SCALE_DIV_BUTTON = 'branch_scale_div_b';
     const ABOUT_DIALOG = 'aptx_about';
     const PROG_NAME = 'progname';
     const PROGNAMELINK = 'prognamelink';
@@ -577,6 +580,7 @@ function (root, d3, forester, phyloXml) {
     const FOSSIL_BAR_COLOR = 'rgba(150,100,55,0.86)'; // opaque-ish sepia
     let _timeInfo = null;                 // forester.timeAxisInfo, recomputed per render
     let _timeTree = false;                // forester.isTimeTree: never re-rooted
+    let _branchScaleAvailable = false;    // the tree states time AND divergence, so the switch is offered
     let _clusterH = 0;                    // the cluster layout's vertical extent, set per render
     let _docListenersBound = false;       // page-level key/wheel handlers bind once, not per launch
     let _docListeners = [];               // ...and destroy() can take every one of them down again
@@ -5111,6 +5115,12 @@ function (root, d3, forester, phyloXml) {
         // showTimeAxis explicitly.
         _timeInfo = _treeData ? forester.timeAxisInfo(forester.getTreeRoot(_treeData)) : null;
         _timeTree = _treeData ? forester.isTimeTree(_treeData) : false;
+        // Whether this tree says two different things -- when its nodes sit in
+        // time AND its branches measure something else -- and which of the two
+        // it arrived showing. An Auspice build arrives in the time view; a
+        // BEAST or Newick file arrives stating its own branch lengths.
+        _branchScaleAvailable = _treeData ? forester.hasTimeAndDivergence(_treeData) : false;
+        _state.branchScale = _treeData ? forester.branchLengthScale(_treeData) : 'divergence';
         if (_state.showTimeAxis === undefined) {
             _state.showTimeAxis = !!(_timeInfo && _timeInfo.type);
         }
@@ -5642,6 +5652,24 @@ function (root, d3, forester, phyloXml) {
                     + ' is empty or illegally formatted');
             }
         });
+        // A tip-dated BEAST tree states its node ages as unitless `height`s --
+        // time before the youngest tip -- which say nothing about WHEN. Where
+        // the tip labels carry sampling dates and they agree on the date of
+        // height 0, the tree is placed in calendar time here, before anything
+        // reads a date: the axis, Color-by and the visualization candidates all
+        // depend on it. A tree that does not qualify is left exactly as it was,
+        // and a tree whose dates carry a unit is never touched. The desktop
+        // converts at the same point, next to its internal-label policy
+        // (their HeightDateConverter, 0.11.151).
+        // Each node's cumulative divergence is recorded from the branch
+        // lengths AS LOADED, before anything rewrites them, so the time <->
+        // divergence switch is reversible rather than one-way. Auspice states
+        // divergence outright (nextstrain:div) and is unaffected; every other
+        // tree states it as its branch lengths, which the time view overwrites.
+        trees.forEach(function (t) {
+            forester.captureDivergence(t);
+        });
+        forester.convertLoadedHeightsToDates(trees);
         // the two view keys are checked up here with the other arguments,
         // before anything is touched (and where Node can test it)
         if (config && config.view !== undefined && config.view !== null && typeof config.view !== 'object') {
@@ -8142,7 +8170,7 @@ function (root, d3, forester, phyloXml) {
         {key: 'e', label: 'E', shift: true, what: 'Expand vertically until the labels fit', run: function () { zoomToExpandY(); }},
         {key: 'l', label: 'L', shift: true, what: 'Next layout: rectangular, circular, unrooted', run: cycleLayout},
         {key: 'd', label: 'D', shift: true, what: 'Next display type: phylogram, aligned, cladogram', run: cycleDisplayType},
-        {key: 'x', label: 'X', shift: true, what: 'Time axis on / off', run: toggleTimeAxis},
+        {key: 'x', label: 'X', shift: true, what: 'Time / divergence scale, or the time axis', run: toggleTimeAxis},
         {key: 'o', label: 'O', shift: true, what: 'Ladderize (order the tree)', run: function () { ladderizeButtonPressed(); }},
         {key: 'u', label: 'U', shift: true, what: 'Uncollapse every clade', run: function () { uncollapseAll(); }},
         {key: 'f', label: 'F', what: 'Go to the search box', run: focusSearch, typing: true},
@@ -8212,9 +8240,45 @@ function (root, d3, forester, phyloXml) {
         }
     }
 
-    // The Time Axis checkbox's toggle; when the distance / time tree switch
-    // arrives it takes over this key.
+    /**
+     * Redraws the tree with its branch lengths taken from the chosen metric:
+     * TIME (the gaps between the nodes' dates) or DIVERGENCE (what the file's
+     * own branch lengths measured, recorded at load). Both metrics stay on the
+     * tree, so this is reversible and lossless -- a round trip restores the
+     * loaded branch lengths exactly.
+     *
+     * @param scale 'time' or 'divergence'
+     */
+    function setBranchScale(scale) {
+        if (!_branchScaleAvailable || !_treeData || _state.branchScale === scale) {
+            return;
+        }
+        _state.branchScale = scale;
+        if (scale === 'time') {
+            forester.applyTimeBranchLengths(_treeData);
+        } else {
+            forester.applyDivergenceBranchLengths(_treeData);
+        }
+        // the branch lengths ARE the layout, so everything measured from them
+        // has to be measured again
+        _basicTreeProperties = forester.collectBasicTreeProperties(_treeData);
+        setCheckboxValue(BRANCH_SCALE_TIME_BUTTON, scale === 'time');
+        setCheckboxValue(BRANCH_SCALE_DIV_BUTTON, scale !== 'time');
+        zoomToFit();
+    }
+
+    function branchScaleButtonClicked() {
+        setBranchScale(getCheckboxValue(BRANCH_SCALE_TIME_BUTTON) ? 'time' : 'divergence');
+    }
+
+    // Shift+X. The switch takes this key over where the tree offers it, as was
+    // always intended; on every other tree it still works the Time Axis
+    // checkbox, so the key never does nothing.
     function toggleTimeAxis() {
+        if (_branchScaleAvailable) {
+            setBranchScale(_state.branchScale === 'time' ? 'divergence' : 'time');
+            return;
+        }
         let cb = byId(TIME_AXIS_CB);
         if (!cb || cb.disabled) {
             return;
@@ -8956,7 +9020,15 @@ function (root, d3, forester, phyloXml) {
         return _state.showTimeAxis === true && !radialDisplay()
             && _state.phylogram === true
             && _timeInfo !== null && _timeInfo.type !== null
-            && _basicTreeProperties.branchLengths === true;
+            && _basicTreeProperties.branchLengths === true
+            // The axis is an overlay calibrated to the tree's own branch scale,
+            // so it must be hidden when the branches are showing DIVERGENCE
+            // and divergence is a different measure -- calendar years against
+            // substitutions reads as a confident lie. Only then: where the two
+            // metrics agree (a BEAST time tree, whose branch lengths ARE time)
+            // there is no switch and the axis is calibrated correctly, which
+            // is what makes a converted BEAST tree show its years at all.
+            && !(_branchScaleAvailable && _state.branchScale === 'divergence');
     }
 
     function timeAxisBottomReserve() {
@@ -9122,8 +9194,11 @@ function (root, d3, forester, phyloXml) {
 
         // ---- HPD age bars (internal) + tip bars: fossil ranges, or sampling dates ----
         forEachDisplayed(function (d) {
-            if (!d.date || typeof d.date.minimum !== 'number' || typeof d.date.maximum !== 'number'
-                || d.y === undefined) {
+            // forester.isGenuineDateInterval, not a bare min/max test: the
+            // bars are floored at 1px below, so a bound pair that differs only
+            // by floating-point noise would draw as a visible bracket. This
+            // guard is on EVERY node, tip and internal, geologic and calendar.
+            if (!forester.isGenuineDateInterval(d.date) || d.y === undefined) {
                 return;
             }
             let min = d.date.minimum;
@@ -9144,14 +9219,12 @@ function (root, d3, forester, phyloXml) {
             // as one below. On CALENDAR time it is the uncertainty of a
             // sampling date -- a virus sample dated only to its month or year
             // -- which is the same kind of thing as an internal node's age
-            // interval and is drawn the same way, slimmer, and only when it
-            // HAS a width: a tip dated to the day states {d,d}, and a capped
-            // tick on every such tip is what made the readers throw tip
-            // intervals away until 2026-09-17 (Christian; the desktop alike).
+            // interval and is drawn the same way, slimmer. Either way it is
+            // drawn only when it HAS a width: a tip dated to the day states
+            // {d,d}, and a capped tick on every such tip is what made the
+            // readers throw tip intervals away until 2026-09-17 (Christian;
+            // the desktop alike). The width test is the entry guard above.
             let sampledTip = !d.children && info.type === 'calendar';
-            if (sampledTip && !(max > min)) {
-                return;
-            }
             if (d.children) {
                 g.append('rect').attr('x', left).attr('y', y - 3.5)
                     .attr('width', w).attr('height', 7)
@@ -12191,7 +12264,10 @@ function (root, d3, forester, phyloXml) {
             return null;
         }
         let hasValue = typeof date.value === 'number';
-        let hasRange = typeof date.minimum === 'number' && typeof date.maximum === 'number';
+        // the same predicate the bars use: a bound pair that differs only by
+        // floating-point noise is one number printed twice, and reading it as a
+        // range put "[12.059999999999942 - 12.059999999999949]" in the tooltip
+        let hasRange = forester.isGenuineDateInterval(date);
         let s = hasValue ? String(date.value) : '';
         if (hasRange) {
             s += ' [' + date.minimum + ' - ' + date.maximum + ']';
@@ -12722,6 +12798,8 @@ function (root, d3, forester, phyloXml) {
         on(TIME_GRID_CB, 'click', timeGridCbClicked);
 
         on(LAYOUT_RECT_BUTTON, 'click', layoutButtonClicked);
+        on(BRANCH_SCALE_TIME_BUTTON, 'click', branchScaleButtonClicked);
+        on(BRANCH_SCALE_DIV_BUTTON, 'click', branchScaleButtonClicked);
 
         on(LAYOUT_CIRC_BUTTON, 'click', layoutButtonClicked);
         on(LAYOUT_UNROOTED_BUTTON, 'click', layoutButtonClicked);
@@ -13142,6 +13220,15 @@ function (root, d3, forester, phyloXml) {
             h = h.concat(makeSegment(makeGlyph('aligned_phylogram'), PHYLOGRAM_ALIGNED_BUTTON, radioGroup, 'phylogram display (uses branch length values) with aligned labels'));
             h = h.concat(makeSegment(makeGlyph('cladogram'), CLADOGRAM_BUTTON, radioGroup, ' cladogram display (ignores branch length values)'));
             h = h.concat('</div>');
+            // The branch SCALE, when the tree states two different things: its
+            // nodes' dates, and its branches' divergence. Hidden otherwise,
+            // which is most trees.
+            h = h.concat('<div class="' + BRANCH_SCALE_CONTROLGROUP + ' aptx-segmented">');
+            h = h.concat(makeSegment('Time', BRANCH_SCALE_TIME_BUTTON, 'branch_scale_radio',
+                'branch lengths measure TIME (the nodes\' dates)'));
+            h = h.concat(makeSegment('Div', BRANCH_SCALE_DIV_BUTTON, 'branch_scale_radio',
+                'branch lengths measure DIVERGENCE (substitutions, as the file states them)'));
+            h = h.concat('</div>');
             h = h.concat('</div>');
             h = h.concat('</fieldset>');
             return h;
@@ -13617,6 +13704,14 @@ function (root, d3, forester, phyloXml) {
             disableCheckbox('#' + PHYLOGRAM_BUTTON);
             disableCheckbox('#' + PHYLOGRAM_ALIGNED_BUTTON);
         }
+        setCheckboxValue(BRANCH_SCALE_TIME_BUTTON, _state.branchScale === 'time');
+        setCheckboxValue(BRANCH_SCALE_DIV_BUTTON, _state.branchScale !== 'time');
+        // most trees state only one thing, and a control offering a choice
+        // that does not exist is worse than no control
+        let scaleGroup = document.querySelector('.' + BRANCH_SCALE_CONTROLGROUP);
+        if (scaleGroup) {
+            scaleGroup.style.display = _branchScaleAvailable ? '' : 'none';
+        }
     }
 
 

package/forester.js

@@ -20,8 +20,8 @@
  *
  */
 
-// v 3.8.0
-// 2026-09-10
+// v 3.10.0
+// 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
 // 
@@ -4988,6 +4988,11 @@
             ? node.date.value : null;
     }
 
+    // A node's CUMULATIVE divergence from the root. Auspice states it outright
+    // as nextstrain:div; every other tree states it as branch lengths, which
+    // are the same thing in difference form, so it is summed at load and kept
+    // on the node (see forester.captureDivergence). The property wins where it
+    // exists, so an Auspice tree behaves exactly as it always did.
     function auspiceNodeDiv(node) {
         if (node.properties) {
             for (let i = 0; i < node.properties.length; ++i) {
@@ -4997,7 +5002,8 @@
                 }
             }
         }
-        return null;
+        return (typeof node._divergence === 'number' && isFinite(node._divergence))
+            ? node._divergence : null;
     }
 
     function auspiceHasAnyDate(node) {
@@ -5051,12 +5057,200 @@
         setDeltaBranchLengths(forester.getTreeRoot(phy), null, auspiceNodeDiv);
     };
 
-    // True when the tree carries BOTH a time signal (a dated node) AND a
-    // divergence signal (a nextstrain:div property), so the toggle is
-    // meaningful at all.
+    /**
+     * Records each node's cumulative divergence from the root, summed from the
+     * branch lengths AS LOADED, so the divergence view survives the time view
+     * overwriting `branch_length`. Kept in `_divergence`, which is private:
+     * no writer emits it, and a re-read of our own output re-derives it.
+     *
+     * A tree whose branch lengths ARE its dates (an Auspice time tree, say)
+     * gets the snapshot too; it is `hasTimeAndDivergence` that decides whether
+     * the two views differ enough to be worth offering.
+     *
+     * Call once per tree at load, before anything rewrites a branch length.
+     *
+     * @param phy the tree
+     */
+    forester.captureDivergence = function (phy) {
+        let root = forester.getTreeRoot(phy);
+        if (!root) {
+            return;
+        }
+        (function walk(node, cumulative) {
+            node._divergence = cumulative;
+            let children = node.children;
+            if (children) {
+                for (let i = 0; i < children.length; ++i) {
+                    let bl = children[i].branch_length;
+                    let step = (typeof bl === 'number' && isFinite(bl) && bl > 0) ? bl : 0;
+                    walk(children[i], cumulative + step);
+                }
+            }
+        }(root, 0));
+    };
+
+    // How much the tree's SHAPE would change between the two metrics, as a
+    // fraction of its width: each tip's distance from the root under each
+    // metric, normalised by the deepest tip, and the largest disagreement.
+    //
+    // Comparing branch lengths PAIR BY PAIR is the wrong question and gave the
+    // wrong answer: on influenza.tree the branch lengths differ from the date
+    // gaps by a median of 7% per branch, which looks like a separate measure,
+    // but the differences cancel along every path and all 687 tips land within
+    // 0.3% of where the other metric puts them. Its branch lengths ARE time --
+    // a BEAST time tree states time -- so a toggle would redraw one picture
+    // twice. A real Nextstrain build, where divergence is genuinely a
+    // different measurement, moves tips by 24.8% of the tree's width.
+    //
+    // Both metrics are read WITHOUT touching branch_length, so this can be
+    // asked at load without disturbing the tree.
+    function layoutShiftBetweenMetrics(root) {
+        let rootDate = auspiceNodeDate(root);
+        let time = [];
+        let div = [];
+        let ok = true;
+        (function walk(n, t, d) {
+            let nt = auspiceNodeDate(n);
+            let nd = auspiceNodeDiv(n);
+            let tHere = (nt !== null && rootDate !== null) ? Math.abs(nt - rootDate) : t;
+            let dHere = (nd !== null) ? nd : d;
+            if (!n.children || n.children.length === 0) {
+                if (nt === null || nd === null) {
+                    ok = false;
+                }
+                time.push(tHere);
+                div.push(dHere);
+                return;
+            }
+            for (let i = 0; i < n.children.length; ++i) {
+                walk(n.children[i], tHere, dHere);
+            }
+        }(root, 0, 0));
+        if (!ok || time.length === 0) {
+            return 0;
+        }
+        let tMax = Math.max.apply(null, time.length > 50000 ? time.slice(0, 50000) : time);
+        let dMax = Math.max.apply(null, div.length > 50000 ? div.slice(0, 50000) : div);
+        if (!(tMax > 0) || !(dMax > 0)) {
+            return 0;
+        }
+        let worst = 0;
+        for (let i = 0; i < time.length; ++i) {
+            worst = Math.max(worst, Math.abs((time[i] / tMax) - (div[i] / dMax)));
+        }
+        return worst;
+    }
+
+    // Below this the two views are the same picture and the switch is noise.
+    // influenza.tree measures 0.003, nextstrain-ncov.json 0.248.
+    const BRANCH_METRIC_SHIFT_MIN = 0.02;
+
+    function divergenceDiffersFromTime(root) {
+        return layoutShiftBetweenMetrics(root) > BRANCH_METRIC_SHIFT_MIN;
+    }
+
+    // Which metric the CURRENT branch lengths hold -- a different question
+    // from whether the two metrics differ, and it needs the pair-by-pair
+    // comparison: after forester.applyTimeBranchLengths every branch length is
+    // exactly its ends' date gap, and after applyDivergenceBranchLengths it is
+    // not. Asked so a switch starts from what is on screen.
+    function branchLengthsAreTime(root) {
+        let pairs = 0;
+        let same = 0;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!n.children) {
+                return;
+            }
+            let pv = auspiceNodeDate(n);
+            if (pv === null) {
+                return;
+            }
+            for (let i = 0; i < n.children.length; ++i) {
+                let c = n.children[i];
+                let cv = auspiceNodeDate(c);
+                let bl = c.branch_length;
+                if (cv === null || typeof bl !== 'number' || !isFinite(bl)) {
+                    continue;
+                }
+                ++pairs;
+                let scale = Math.max(Math.abs(bl), Math.abs(cv - pv), 1e-9);
+                if (Math.abs(Math.abs(cv - pv) - bl) <= (scale * 1e-6)) {
+                    ++same;
+                }
+            }
+        });
+        return pairs > 0 && (same * 20) >= (pairs * 19);
+    }
+
+    // Whether the dates run the way the time view needs them to: a CALENDAR
+    // date increases toward the tips, and setDeltaBranchLengths takes
+    // child - parent and clamps at 0. A BEAST height runs the other way -- it
+    // is an age, largest at the root -- so a tree still stating heights would
+    // get a branch length of 0 everywhere and collapse to a point. Measured,
+    // not assumed: forester.convertHeightsToDates turns heights into calendar
+    // dates, and a tree it REFUSED still states ages.
+    function timeIncreasesTowardTips(root) {
+        let up = 0;
+        let pairs = 0;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!n.children) {
+                return;
+            }
+            let pv = auspiceNodeDate(n);
+            if (pv === null) {
+                return;
+            }
+            for (let i = 0; i < n.children.length; ++i) {
+                let cv = auspiceNodeDate(n.children[i]);
+                if (cv === null || cv === pv) {
+                    continue;
+                }
+                ++pairs;
+                if (cv > pv) {
+                    ++up;
+                }
+            }
+        });
+        return pairs > 0 && (up * 2) > pairs;
+    }
+
+    /**
+     * Which metric the tree's branch lengths currently state. An Auspice build
+     * arrives in the time view (its parser writes date deltas); a BEAST or
+     * Newick file arrives stating whatever it was written with, which is the
+     * divergence view. Asked rather than assumed, so a toggle starts from
+     * what is actually on screen.
+     *
+     * @param phy the tree
+     * @returns {string} 'time' or 'divergence'
+     */
+    forester.branchLengthScale = function (phy) {
+        let root = forester.getTreeRoot(phy);
+        return (root && branchLengthsAreTime(root)) ? 'time' : 'divergence';
+    };
+
+    /**
+     * True when the tree carries BOTH a time signal (dated nodes, running the
+     * calendar way) and a divergence signal that says something different, so
+     * a time <-> divergence toggle is meaningful. Auspice states divergence as
+     * nextstrain:div; a BEAST tree states it as its branch lengths, which on a
+     * real one differ from the dates on nearly every branch (influenza.tree:
+     * 1344 of 1372).
+     *
+     * @param phy the tree
+     * @returns {boolean}
+     */
     forester.hasTimeAndDivergence = function (phy) {
         let root = forester.getTreeRoot(phy);
-        return auspiceHasAnyDate(root) && auspiceHasAnyDiv(root);
+        if (!root || !auspiceHasAnyDate(root) || !timeIncreasesTowardTips(root)) {
+            return false;
+        }
+        // auspiceHasAnyDiv is true for every tree once the divergence has been
+        // captured, so it cannot decide this on its own -- it only says a
+        // divergence measure EXISTS. Whether it says anything different is the
+        // shift test, and that is the question worth asking of both kinds of
+        // tree.
+        return auspiceHasAnyDiv(root) && divergenceDiffersFromTime(root);
     };
 
     // A number that is not NaN. It used to test only for null, undefined and
@@ -6519,9 +6713,17 @@
     // ---- time-tree detection -------------------------------------------
     // Two date conventions: GEOLOGIC ages (Ma before present, decreasing
     // toward the tips) and CALENDAR years (increasing toward the tips).
-    // Decided from the <date> unit attributes, with a magnitude fallback for
-    // unitless dates: values mostly in [1500, 2200] read as years; values
-    // spanning from large down toward ~0 read as ages.
+    // Decided from the <date> unit attributes and NOTHING ELSE. A unitless
+    // tree gets no axis: guessing from magnitude read every tip-dated BEAST
+    // tree as geologic, because BEAST states a node's age as a unitless
+    // `height` and an influenza tree spanning 12 years looks exactly like one
+    // spanning 12 Ma. It drew Miocene/Pliocene bands and a "Ma" ruler under
+    // tips labelled 1993..2005 -- a confident false claim across the whole
+    // figure, which is worse than no axis. Measured over every tree we ship:
+    // the guess decided 3 trees and got all 3 wrong, every other axis comes
+    // from a unit, and none relied on the old [1500, 2200] year rule. The
+    // desktop dropped the same rule on 2026-09-10 (their e9ac62ec) on the
+    // same evidence; Christian, 2026-09-17, both programs.
     const GEO_DATE_UNITS = {
         mya: 1, ma: 1, myr: 1, myrs: 1, my: 1, ga: 1, gya: 1, bya: 1, kya: 1,
         'million years': 1, 'billion years': 1
@@ -6531,6 +6733,40 @@
         'calendar year': 1, 'calendar years': 1
     };
 
+    // A date's bounds state a real interval only when they differ by more than
+    // floating-point noise. TreeAnnotator writes
+    // height_95%_HPD={9.0,9.000000000000004} on a tip it dated EXACTLY: one
+    // number printed twice through binary floating point, not a width. Read as
+    // a width it put a fossil-range bracket on 686 of influenza.tree's 687
+    // tips. The tolerance is RELATIVE because the noise is: a bound near 2000
+    // carries more of it than one near 0. Nothing real is this narrow -- a
+    // single day is 0.0027 of a calendar year, while 1e-9 of 2000 is about a
+    // minute. Both programs had this gap, on two paths each (an auto-enable
+    // predicate with no tolerance, and a painter with no width test at all).
+    const DATE_INTERVAL_REL_TOL = 1e-9;
+
+    /**
+     * Whether a date's minimum/maximum are a genuine interval rather than one
+     * value printed twice. Every reader of date bounds must ask this, drawing
+     * included: a bar floored at 1px draws noise as a visible bracket.
+     *
+     * @param date a node's date object
+     * @returns {boolean}
+     */
+    forester.isGenuineDateInterval = function (date) {
+        if (!date || typeof date.minimum !== 'number' || typeof date.maximum !== 'number'
+            || !isFinite(date.minimum) || !isFinite(date.maximum)) {
+            return false;
+        }
+        let scale = Math.max(Math.abs(date.minimum), Math.abs(date.maximum), 1);
+        // the ABSOLUTE difference: bounds handed over in the wrong order still
+        // state a width, and every painter already normalises the order before
+        // drawing. The desktop's AptxUtil.hasDateIntervalWidth reads it the
+        // same way, down to this constant -- the two programs must not draw
+        // different figures from one file (their message, 2026-09-17).
+        return Math.abs(date.maximum - date.minimum) > (scale * DATE_INTERVAL_REL_TOL);
+    };
+
     /**
      * Whether the tree's branch lengths are time: most of its internal nodes
      * carry a date, and at least two do -- BEAST node heights, Nextstrain
@@ -6563,9 +6799,8 @@
     // presentDate (calendar) are both the LARGEST date value -- the oldest
     // node for ages, the most recent tip for years.
     forester.timeAxisInfo = function (root) {
-        let values = [];
+        let valued = 0;
         let maxVal = -Infinity; // running, not Math.max.apply: 150k dated tips overflow the call stack
-        let minVal = Infinity;
         let geoUnits = 0;
         let calUnits = 0;
         let internal = 0;
@@ -6585,7 +6820,7 @@
             if (!d) {
                 return;
             }
-            let interval = (typeof d.minimum === 'number') && (typeof d.maximum === 'number');
+            let interval = forester.isGenuineDateInterval(d);
             if (interval) {
                 if (isExt) {
                     hasExternalIntervals = true;
@@ -6596,13 +6831,10 @@
             if (typeof d.value !== 'number' || !isFinite(d.value)) {
                 return; // 1e400 parses to Infinity and must never reach the tick loops
             }
-            values.push(d.value);
+            ++valued;
             if (d.value > maxVal) {
                 maxVal = d.value;
             }
-            if (d.value < minVal) {
-                minVal = d.value;
-            }
             if (isExt) {
                 ++datedExternal;
             } else {
@@ -6618,25 +6850,16 @@
             }
         });
         let type = null;
-        if (values.length > 0) {
+        if (valued > 0) {
             if (geoUnits > 0 && geoUnits >= calUnits) {
                 type = 'geologic';
             } else if (calUnits > 0) {
                 type = 'calendar';
-            } else {
-                let calendarish = values.filter(function (v) {
-                    return v >= 1500 && v <= 2200;
-                }).length;
-                if (calendarish * 2 > values.length) {
-                    type = 'calendar';
-                } else if (maxVal > 10 && minVal <= maxVal * 0.05) {
-                    type = 'geologic';
-                }
             }
         }
         let dated = (datedInternal >= 2 && (datedInternal * 2) > internal)
             || (datedExternal >= 2 && (datedExternal * 2) > external);
-        let maxValue = values.length > 0 ? maxVal : 0;
+        let maxValue = valued > 0 ? maxVal : 0;
         return {
             type: type,
             rootAge: type === 'geologic' ? maxValue : 0,
@@ -6647,6 +6870,559 @@
         };
     };
 
+    // ---- dates in a tip's LABEL, and BEAST heights ----------------------
+    // A tip-dated BEAST tree states a node's age as a unitless `height`: time
+    // before the youngest tip, in whatever unit the run happened to use. The
+    // sampling dates are usually in the tip labels themselves
+    // (A_duck_Guangdong_12_2000, NewYork_705_1994.1, EBOV|KR817226|2014-06-10).
+    // If the heights are YEARS, every tip's label date plus its height is the
+    // same calendar date -- the date of height 0. That agreement is the whole
+    // evidence: heights in months or days, or a strain number mistaken for a
+    // date, break it and the tree is left alone.
+    //
+    // Ported from the desktop's TipDateExtractor and HeightDateConverter
+    // (their 0.11.151, commit 6755ba12), whose rules and constants these are.
+    // Christian, 2026-09-17: port it, after they commit.
+
+    // A BARE year or decimal year has to look like a plausible sampling year or
+    // a 4-digit strain number would date the tip. An explicit ISO / month-name
+    // / slash date is strong evidence and gets a looser window.
+    const TIP_DATE_MIN_BARE_YEAR = 1900;
+    const TIP_DATE_MAX_BARE_YEAR = 2100;
+    const TIP_DATE_MIN_YEAR = 1000;
+    const TIP_DATE_MAX_YEAR = 2999;
+
+    // Global, so each matcher can take the RIGHTMOST match; lastIndex is reset
+    // before every use, because these are shared.
+    const TIP_DATE_ISO_FULL = /(?<![0-9])(\d{4})-(\d{1,2})-(\d{1,2})(?![0-9])/g;
+    const TIP_DATE_MONTH_FULL = /(?<![A-Za-z0-9])(\d{1,2})[-\s]([A-Za-z]{3,9})[-\s](\d{4})(?![0-9])/g;
+    const TIP_DATE_SLASH_FULL = /(?<![0-9])(\d{1,4})[/.](\d{1,2})[/.](\d{1,4})(?![0-9])/g;
+    const TIP_DATE_ISO_PARTIAL = /(?<![0-9])(\d{4})-(\d{1,2})(?![0-9-])/g;
+    const TIP_DATE_MONTH_PARTIAL = /(?<![A-Za-z0-9])([A-Za-z]{3,9})[-\s](\d{4})(?![0-9])/g;
+    const TIP_DATE_DECIMAL_YEAR = /(?<![0-9.])(\d{4}\.\d+)(?![0-9])/g;
+    const TIP_DATE_BARE_YEAR = /(?<![0-9.])(\d{4})(?![0-9.])/g;
+
+    const TIP_DATE_MONTHS_ABBR = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+    const TIP_DATE_MONTHS_FULL = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august',
+        'september', 'october', 'november', 'december'];
+
+    function tipDateYearLength(y) {
+        return (((y % 4) === 0 && (y % 100) !== 0) || (y % 400) === 0) ? 366 : 365;
+    }
+
+    function tipDateMonthLength(y, m) {
+        if (m === 2) {
+            return tipDateYearLength(y) === 366 ? 29 : 28;
+        }
+        return ((m === 4) || (m === 6) || (m === 9) || (m === 11)) ? 30 : 31;
+    }
+
+    function tipDateDayOfYear(y, m, d) {
+        let doy = d;
+        for (let i = 1; i < m; ++i) {
+            doy += tipDateMonthLength(y, i);
+        }
+        return doy;
+    }
+
+    // 1-12 for an English month name -- the EXACT 3-letter abbreviation or the
+    // full name, case-insensitively; 0 otherwise. Exact, not a prefix, is what
+    // stops "Marburg", "Junin" or "Decatur" being read as a month.
+    function tipDateMonthNumber(name) {
+        if (!name) {
+            return 0;
+        }
+        let key = String(name).toLowerCase();
+        for (let i = 0; i < 12; ++i) {
+            if (TIP_DATE_MONTHS_ABBR[i] === key || TIP_DATE_MONTHS_FULL[i] === key) {
+                return i + 1;
+            }
+        }
+        return 0;
+    }
+
+    /**
+     * The decimal year of a (year, month, day): a month or day of 0 means "not
+     * given" and maps to the middle of the interval it leaves open (a year to
+     * .5, a month to mid-month, a day to mid-day). Leap-year aware. The
+     * midpoint convention is BEAST's and TreeTime's.
+     *
+     * @param year
+     * @param month 1-12, or <= 0 for "not given"
+     * @param day 1-31, or <= 0 for "not given"
+     * @returns {number}
+     */
+    forester.tipDateToDecimalYear = function (year, month, day) {
+        if (month <= 0) {
+            return year + 0.5;
+        }
+        let len = tipDateYearLength(year);
+        if (day <= 0) {
+            let firstDoy = tipDateDayOfYear(year, month, 1);
+            return year + (((firstDoy - 1) + (tipDateMonthLength(year, month) / 2)) / len);
+        }
+        return year + ((tipDateDayOfYear(year, month, day) - 0.5) / len);
+    };
+
+    // A full date, validated (an impossible one like 2021-13-40 or Feb 30 is
+    // not a date). The RANGE is the whole day the label names.
+    function tipDateFromYmd(year, month, day, matched, format, ambiguous) {
+        if ((year < TIP_DATE_MIN_YEAR) || (year > TIP_DATE_MAX_YEAR) || (month < 1) || (month > 12)
+            || (day < 1) || (day > tipDateMonthLength(year, month))) {
+            return null;
+        }
+        let len = tipDateYearLength(year);
+        let doy = tipDateDayOfYear(year, month, day);
+        return {
+            decimalYear: forester.tipDateToDecimalYear(year, month, day),
+            matchedText: matched, precision: 'day', formatLabel: format, ambiguous: ambiguous === true,
+            rangeStart: year + ((doy - 1) / len), rangeEnd: year + (doy / len)
+        };
+    }
+
+    // A year-month date: the day is unknown, so the range is the whole month.
+    function tipDateFromYm(year, month, matched, format) {
+        if ((year < TIP_DATE_MIN_YEAR) || (year > TIP_DATE_MAX_YEAR) || (month < 1) || (month > 12)) {
+            return null;
+        }
+        let len = tipDateYearLength(year);
+        let start = year + ((tipDateDayOfYear(year, month, 1) - 1) / len);
+        return {
+            decimalYear: forester.tipDateToDecimalYear(year, month, 0),
+            matchedText: matched, precision: 'month', formatLabel: format, ambiguous: false,
+            rangeStart: start, rangeEnd: start + (tipDateMonthLength(year, month) / len)
+        };
+    }
+
+    // Every matcher keeps the LAST (rightmost) valid match in the label.
+    function tipDateEachMatch(re, s, fn) {
+        let found = null;
+        let m;
+        re.lastIndex = 0;
+        while ((m = re.exec(s)) !== null) {
+            let d = fn(m);
+            if (d) {
+                found = d;
+            }
+            if (m.index === re.lastIndex) {
+                ++re.lastIndex; // a zero-width match would spin forever
+            }
+        }
+        return found;
+    }
+
+    /**
+     * The date a tip label states, or null. The most SPECIFIC format wins
+     * (a full date before a year-month before a bare year), and within one
+     * format the rightmost match does -- a label usually ends with its date.
+     *
+     * The result carries the decimal year (midpoint convention) AND the
+     * calendar RANGE the label actually states: `2021` is all of 2021,
+     * `2021-03` all of March, a day that whole day, and a decimal year its
+     * last written digit (`1993.1` is 1993.05 to 1993.15). The range is what
+     * makes different programs' conventions comparable -- BEAST counts a day
+     * from its start, we read a label at its middle, half a day apart.
+     *
+     * @param label a tip's name
+     * @param monthFirst true to read an ambiguous numeric date (both fields
+     *        <= 12) month-first; the default is day-first, as the desktop's
+     *        converter always asks for
+     * @returns {object|null}
+     */
+    forester.parseTipLabelDate = function (label, monthFirst) {
+        if (!label) {
+            return null;
+        }
+        let s = String(label);
+        let m = tipDateEachMatch(TIP_DATE_ISO_FULL, s, function (g) {
+            return tipDateFromYmd(parseInt(g[1], 10), parseInt(g[2], 10), parseInt(g[3], 10), g[0],
+                'ISO date (YYYY-MM-DD)', false);
+        });
+        if (m) {
+            return m;
+        }
+        m = tipDateEachMatch(TIP_DATE_MONTH_FULL, s, function (g) {
+            let mon = tipDateMonthNumber(g[2]);
+            return mon > 0
+                ? tipDateFromYmd(parseInt(g[3], 10), mon, parseInt(g[1], 10), g[0], 'month-name date', false)
+                : null;
+        });
+        if (m) {
+            return m;
+        }
+        m = tipDateEachMatch(TIP_DATE_SLASH_FULL, s, function (g) {
+            let a = parseInt(g[1], 10);
+            let b = parseInt(g[2], 10);
+            let c = parseInt(g[3], 10);
+            let year = -1;
+            let month = -1;
+            let day = -1;
+            let ambiguous = false;
+            if (g[1].length === 4) {          // YYYY/MM/DD -- unambiguous
+                year = a;
+                month = b;
+                day = c;
+            } else if (g[3].length === 4) {   // D/M/YYYY or M/D/YYYY
+                year = c;
+                if (a > 12) {
+                    day = a;
+                    month = b;
+                } else if (b > 12) {
+                    month = a;
+                    day = b;
+                } else {                      // both <= 12: genuinely ambiguous
+                    ambiguous = true;
+                    if (monthFirst === true) {
+                        month = a;
+                        day = b;
+                    } else {
+                        day = a;
+                        month = b;
+                    }
+                }
+            }
+            return year > 0 ? tipDateFromYmd(year, month, day, g[0], 'numeric date', ambiguous) : null;
+        });
+        if (m) {
+            return m;
+        }
+        m = tipDateEachMatch(TIP_DATE_ISO_PARTIAL, s, function (g) {
+            return tipDateFromYm(parseInt(g[1], 10), parseInt(g[2], 10), g[0], 'ISO year-month (YYYY-MM)');
+        });
+        if (m) {
+            return m;
+        }
+        m = tipDateEachMatch(TIP_DATE_MONTH_PARTIAL, s, function (g) {
+            let mon = tipDateMonthNumber(g[1]);
+            return mon > 0 ? tipDateFromYm(parseInt(g[2], 10), mon, g[0], 'month-name year') : null;
+        });
+        if (m) {
+            return m;
+        }
+        m = tipDateEachMatch(TIP_DATE_DECIMAL_YEAR, s, function (g) {
+            let v = parseFloat(g[1]);
+            let y = Math.floor(v);
+            if ((y < TIP_DATE_MIN_BARE_YEAR) || (y > TIP_DATE_MAX_BARE_YEAR)) {
+                return null;
+            }
+            // the range is the last digit the label actually wrote
+            let half = 0.5 * Math.pow(10, -(g[1].length - g[1].indexOf('.') - 1));
+            return {
+                decimalYear: v, matchedText: g[1], precision: 'day', formatLabel: 'decimal year',
+                ambiguous: false, rangeStart: v - half, rangeEnd: v + half
+            };
+        });
+        if (m) {
+            return m;
+        }
+        return tipDateEachMatch(TIP_DATE_BARE_YEAR, s, function (g) {
+            let y = parseInt(g[1], 10);
+            if ((y < TIP_DATE_MIN_BARE_YEAR) || (y > TIP_DATE_MAX_BARE_YEAR)) {
+                return null;
+            }
+            return {
+                decimalYear: y + 0.5, matchedText: g[1], precision: 'year', formatLabel: 'year',
+                ambiguous: false, rangeStart: y, rangeEnd: y + 1
+            };
+        });
+    };
+
+    // ---- unitless BEAST heights -> calendar dates -----------------------
+    // How far a tip's label date plus its height may miss, in years: enough for
+    // the one-day differences between programs' decimal-year conventions, and
+    // far below the gaps that heights in months or days open up.
+    const HEIGHT_DATE_TOLERANCE_YEARS = 0.01;
+    // at least 19 of every 20 compared tips must agree on the date of height 0
+    const HEIGHT_DATE_MIN_AGREEING_NUM = 19;
+    const HEIGHT_DATE_MIN_AGREEING_DEN = 20;
+
+    // 5 decimals, HALF_UP -- away from zero, which Math.round is not for a
+    // negative half (it takes -0.5 to -0). The desktop rounds with BigDecimal
+    // HALF_UP, and the anchor has to land on the same digits or every date on
+    // the tree shifts.
+    function heightDateRound5(x) {
+        let s = x < 0 ? -1 : 1;
+        return (s * Math.round(Math.abs(x) * 100000)) / 100000;
+    }
+
+    // Whether a compared tip allows height 0 at calendar date x. The tip's
+    // allowed stretch is its LABEL RANGE plus its height, widened by the
+    // tolerance at each end.
+    function heightDateAllows(r, x) {
+        return (x >= ((r[0] + r[2]) - HEIGHT_DATE_TOLERANCE_YEARS))
+            && (x <= (r[1] + r[2] + HEIGHT_DATE_TOLERANCE_YEARS));
+    }
+
+    // The stretch of calendar dates allowed by the MOST tips, as [start, end],
+    // or null when a separate stretch is allowed by as many -- then which date
+    // height 0 is, is undecided, and a tree we cannot place we leave alone. A
+    // sweep over the tips' allowed intervals, closed at both ends.
+    //
+    // The `tied` refusal is LIVE, and a test pins it. I first argued it was
+    // unreachable -- two disjoint stretches would each need 19 tips in 20, so
+    // 18 in 20 would allow both, and since a tip's allowed dates are one
+    // interval those 18 allow everything between, making it one stretch. That
+    // last step is wrong, and the desktop caught it: the 18 do cover the gap,
+    // but a stretch is the MAXIMUM coverage, which is 19, and 18 < 19, so the
+    // gap joins neither maximum and the two stay separate. The shape is
+    // 19 / 18 / 19.
+    //
+    // It is reached by an ordinary curation error: a mostly year-labelled tree
+    // (a bare year is ~1 year wide, so those tips span both candidates) with
+    // two tips at height 0 whose day labels disagree -- a file cannot have two
+    // different youngest tips. Remove this check and such a tree converts at a
+    // fabricated anchor, silently. My own fixture had all its year tips in ONE
+    // year, which made the different-sampling-times rule fire first and hide
+    // the whole thing.
+    function heightDateMostAllowed(ranges) {
+        let events = [];
+        ranges.forEach(function (r) {
+            events.push([(r[0] + r[2]) - HEIGHT_DATE_TOLERANCE_YEARS, 1]);
+            events.push([r[1] + r[2] + HEIGHT_DATE_TOLERANCE_YEARS, -1]);
+        });
+        // a start sorts before an end at the same x, so intervals that merely
+        // touch do overlap
+        events.sort(function (a, b) {
+            return a[0] !== b[0] ? (a[0] - b[0]) : (b[1] - a[1]);
+        });
+        let depth = 0;
+        let best = 0;
+        let start = 0;
+        let end = 0;
+        let open = false;
+        let tied = false;
+        events.forEach(function (e) {
+            if (e[1] > 0) {
+                ++depth;
+                if (depth > best) {
+                    best = depth;
+                    start = e[0];
+                    open = true;
+                    tied = false;
+                } else if ((depth === best) && !open) {
+                    tied = true;
+                }
+            } else {
+                if (open) {
+                    end = e[0];
+                    open = false;
+                }
+                --depth;
+            }
+        });
+        return ((best === 0) || tied) ? null : [start, end];
+    }
+
+    // Where the most precisely dated tips put height 0: the median of
+    // (label date + height) over the tips whose label RANGE is at most twice
+    // the narrowest. The middle of the allowed stretch would be pulled about by
+    // the coarse labels -- influenza.tree mixes `1993.11` with `1997` (meaning
+    // the whole of 1997), and that middle, 2005.2525, showed the tip labelled
+    // 1994.1 as 1994.1025.
+    function heightDatePrecisestMedian(tips) {
+        let narrowest = Infinity;
+        tips.forEach(function (r) {
+            narrowest = Math.min(narrowest, r[1] - r[0]);
+        });
+        let values = [];
+        tips.forEach(function (r) {
+            if ((r[1] - r[0]) <= (2 * narrowest)) {
+                values.push(r[3] + r[2]);
+            }
+        });
+        values.sort(function (a, b) {
+            return a - b;
+        });
+        let n = values.length;
+        return ((n % 2) === 1) ? values[(n - 1) / 2] : ((values[(n / 2) - 1] + values[n / 2]) / 2);
+    }
+
+    /**
+     * The calendar date (decimal year) of height 0 for a tip-dated BEAST tree,
+     * or null when the tree does not qualify and must be left alone. Pure.
+     *
+     * Every condition has to hold: no node's date carries a unit (a unit says
+     * what the numbers already are, and this never overrides one); the tree is
+     * a time tree; a strict majority of tips carry both a height and a date in
+     * the label; the date allowed by the most of those tips is allowed by at
+     * least 19 in 20 of them and no separate stretch of dates is allowed by as
+     * many; and the agreeing tips were sampled at different times -- tips all
+     * from one year agree with heights in ANY unit and so prove nothing.
+     *
+     * @param phy a tree
+     * @returns {{present: number, agreeing: number, compared: number}|null}
+     */
+    forester.inferHeightDateAnchor = function (phy) {
+        if (!phy) {
+            return null;
+        }
+        let root = forester.getTreeRoot(phy);
+        if (!root) {
+            return null;
+        }
+        let united = false;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (n.date && n.date.unit && String(n.date.unit).trim().length > 0) {
+                united = true;
+            }
+        });
+        if (united || !forester.isTimeTree(phy)) {
+            return null;
+        }
+        let tips = 0;
+        let ranges = []; // per compared tip: [label start, label end, height, label date]
+        forester.preOrderTraversalAll(root, function (n) {
+            if (n.children && n.children.length > 0) {
+                return;
+            }
+            ++tips;
+            // not "has a date": a value of 0 -- the youngest tip's height -- is
+            // a height, not an absence
+            if (!n.date || typeof n.date.value !== 'number' || !isFinite(n.date.value)) {
+                return;
+            }
+            let m = forester.parseTipLabelDate(n.name);
+            if (m) {
+                ranges.push([m.rangeStart, m.rangeEnd, n.date.value, m.decimalYear]);
+            }
+        });
+        let compared = ranges.length;
+        if ((compared * 2) <= tips) {
+            return null;
+        }
+        let best = heightDateMostAllowed(ranges);
+        if (best === null) {
+            return null;
+        }
+        let mid = (best[0] + best[1]) / 2;
+        let agreeingTips = [];
+        let latestStart = -Infinity;
+        let earliestEnd = Infinity;
+        // the dates the agreeing tips actually STATE, un-widened: their labels
+        // plus their heights, with no tolerance added
+        let offerLo = -Infinity;
+        let offerHi = Infinity;
+        ranges.forEach(function (r) {
+            if (heightDateAllows(r, mid)) {
+                agreeingTips.push(r);
+                latestStart = Math.max(latestStart, r[0]);
+                earliestEnd = Math.min(earliestEnd, r[1]);
+                offerLo = Math.max(offerLo, r[0] + r[2]);
+                offerHi = Math.min(offerHi, r[1] + r[2]);
+            }
+        });
+        let agreeing = agreeingTips.length;
+        if ((agreeing * HEIGHT_DATE_MIN_AGREEING_DEN) < (compared * HEIGHT_DATE_MIN_AGREEING_NUM)) {
+            return null;
+        }
+        if (latestStart <= earliestEnd) {
+            return null; // every agreeing label range overlaps every other
+        }
+        // The anchor is clamped into what the agreeing tips actually STATE,
+        // not into the stretch the tolerance opened up. The tolerance decides
+        // AGREEMENT -- how far a tip may miss and still count -- and must not
+        // then place the date: clamping into the widened stretch let the answer
+        // drift by up to the tolerance, about four days. Found by the desktop
+        // on ground truth: three Nextstrain .nwk trees whose .nexus siblings
+        // carry the real dates were out by 4.15, 3.96 and 2.92 days, and land
+        // within half a day after this (2026-09-17).
+        //
+        // Where the agreeing tips overlap only BECAUSE of the tolerance and
+        // state nothing in common, there is nothing to clamp into and the
+        // precise-label median stands.
+        let median = heightDatePrecisestMedian(agreeingTips);
+        let present = (offerLo <= offerHi) ? Math.max(offerLo, Math.min(offerHi, median)) : median;
+        return {present: heightDateRound5(present), agreeing: agreeing, compared: compared};
+    };
+
+    /**
+     * Rewrites every node's date as `present - height`, in years, with the
+     * interval bounds SWAPPED: the older height bound is the earlier date.
+     *
+     * @param phy a tree
+     * @param present the date of height 0, from forester.inferHeightDateAnchor
+     */
+    forester.convertHeightsToDates = function (phy, present) {
+        forester.preOrderTraversalAll(forester.getTreeRoot(phy), function (n) {
+            let d = n.date;
+            if (!d) {
+                return;
+            }
+            let hasValue = typeof d.value === 'number' && isFinite(d.value);
+            let value = hasValue ? heightDateRound5(present - d.value) : undefined;
+            // the swap: a LARGER height is further back, so it becomes the
+            // SMALLER (earlier) date
+            let min = (typeof d.maximum === 'number' && isFinite(d.maximum))
+                ? heightDateRound5(present - d.maximum) : undefined;
+            let max = (typeof d.minimum === 'number' && isFinite(d.minimum))
+                ? heightDateRound5(present - d.minimum) : undefined;
+            let next = {};
+            if (d.desc !== undefined) {
+                next.desc = d.desc;
+            }
+            if (value !== undefined) {
+                next.value = value;
+            }
+            if (min !== undefined) {
+                next.minimum = min;
+            }
+            if (max !== undefined) {
+                next.maximum = max;
+            }
+            // a date with no point value keeps an empty unit, as the reader
+            // writes it
+            next.unit = hasValue ? 'year' : '';
+            n.date = next;
+        });
+    };
+
+    /**
+     * The desktop's provenance sentence for a converted tree, which it appends
+     * to the tree's description.
+     *
+     * @param anchor from forester.inferHeightDateAnchor
+     * @param treeName
+     * @param tipCount
+     * @returns {string}
+     */
+    forester.heightDateDescription = function (anchor, treeName, tipCount) {
+        let phrase = treeName ? ('tree named "' + treeName + '" with ') : 'a tree with ';
+        let present = String(anchor.present);
+        return 'Converted the node heights of ' + phrase + tipCount + (tipCount === 1 ? ' tip' : ' tips')
+            + ' to calendar dates: the sampling dates in ' + anchor.agreeing + ' of ' + anchor.compared
+            + ' tip labels put height 0 at ' + present + ', so each date is ' + present + ' minus the height.';
+    };
+
+    /**
+     * Converts every tree of a load whose unitless heights can be placed in
+     * calendar time, appending the provenance sentence to each converted
+     * tree's description. A tree that does not qualify is left exactly as it
+     * was. Returns the number of trees converted.
+     *
+     * @param phys one tree or an array of them
+     * @returns {number}
+     */
+    forester.convertLoadedHeightsToDates = function (phys) {
+        if (!phys) {
+            return 0;
+        }
+        let list = Array.isArray(phys) ? phys : [phys];
+        let converted = 0;
+        list.forEach(function (phy) {
+            let anchor = forester.inferHeightDateAnchor(phy);
+            if (anchor === null) {
+                return;
+            }
+            forester.convertHeightsToDates(phy, anchor.present);
+            let prov = forester.heightDateDescription(anchor, phy.name,
+                forester.getAllExternalNodes(forester.getTreeRoot(phy)).length);
+            phy.description = (phy.description && String(phy.description).trim().length > 0)
+                ? (phy.description + ' ' + prov) : prov;
+            ++converted;
+        });
+        return converted;
+    };
+
     // ---- axis tick mathematics -----------------------------------------
     // The smallest 1/2/5 x 10^k (k may be negative) step >= target.
     forester.niceAxisStep = function (target) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "description": "Archaeopteryx.js is a software tool for the visualization and analysis of highly annotated phylogenetic trees.",
   "main": "archaeopteryx.js",
   "types": "archaeopteryx.d.ts",
@@ -32,7 +32,7 @@
     "url": "git+https://github.com/cmzmasek/archaeopteryx-js.git"
   },
   "dependencies": {
-    "phyloxml": "^1.0.2",
+    "phyloxml": "^1.1.0",
     "d3": "^7.9.0"
   },
   "devDependencies": {