archaeopteryx 3.7.0 → 3.9.0

package/forester.js

@@ -20,8 +20,8 @@
  *
  */
 
-// v 3.7.0
-// 2026-09-10
+// v 3.9.0
+// 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
 // 
@@ -3077,6 +3077,57 @@
     // starting with '&' (a [95] confidence) is left untouched, as is any
     // bracket inside a quoted label. Quotes and nested brackets inside an
     // annotation are honoured when finding its end.
+    //
+    // A QUOTE CHARACTER INSIDE A BLOB IS DATA unless it opens a quoted VALUE.
+    // Auspice writes values bare -- country=Côte d'Ivoire -- and treating that
+    // apostrophe as the start of a quoted string was a real bug, in both of
+    // its forms: one such tip and the quote never closed, so the file was
+    // refused over its "unbalanced parentheses"; two and the apostrophes
+    // paired up ACROSS the tips, no error at all, the second tip gone and the
+    // first one's country reading "Côte d'Ivoire],B:1[&country=Côte d'Ivoire".
+    // (Real file: nextstrain_chikv_global_timetree.nexus, 16 apostrophes, all
+    // of them that one country.) Matches the desktop's scanner rule.
+    //
+    // So a quote opens a run only where a value can START -- straight after
+    // '=', or after '{', '[' or ',' inside a set -- and only if it is closed
+    // by the same character standing where a value can END: before ',', '}',
+    // ']' or the end. Anything else is a character like any other.
+    function opensBlobQuote(s, p, from) {
+        let m = p - 1;
+        while (m >= from && /\s/.test(s.charAt(m))) {
+            --m;
+        }
+        return m >= from && '={[,'.indexOf(s.charAt(m)) >= 0;
+    }
+
+    // The index of the quote closing the run opened at p, or -1. `bounded` is
+    // for the extraction pass, which does not yet know where the blob ends:
+    // there the search gives up at a ']' that is followed by Newick structure,
+    // so a bare value that merely BEGINS with an apostrophe ('s-Hertogenbosch)
+    // cannot reach into the next node's blob for its partner.
+    function blobQuoteClose(s, p, bounded) {
+        let q = s.charAt(p);
+        for (let k = p + 1; k < s.length; ++k) {
+            let c = s.charAt(k);
+            if (c !== q && !(bounded && c === ']')) {
+                continue;
+            }
+            let m = k + 1;
+            while (m < s.length && /\s/.test(s.charAt(m))) {
+                ++m;
+            }
+            let next = m < s.length ? s.charAt(m) : '';
+            if (c === q) {
+                if (next === '' || ',}]'.indexOf(next) >= 0) {
+                    return k;
+                }
+            } else if (next === '' || ',):;(['.indexOf(next) >= 0) {
+                return -1;
+            }
+        }
+        return -1;
+    }
+
     function extractBracketAnnotations(str) {
         if (str.indexOf('[') < 0) {
             return {text: str, blobs: []};
@@ -3102,16 +3153,16 @@
             } else if (c === '[') {
                 let j = i + 1;
                 let depth = 1;
-                let q = null;
                 while (j < str.length && depth > 0) {
                     let cj = str.charAt(j);
-                    if (q) {
-                        if (cj === q) {
-                            q = null;
+                    if ((cj === "'" || cj === '"') && opensBlobQuote(str, j, i + 1)) {
+                        let close = blobQuoteClose(str, j, true);
+                        if (close > -1) {
+                            j = close + 1;   // a quoted value: its brackets are data
+                            continue;
                         }
-                    } else if (cj === "'" || cj === '"') {
-                        q = cj;
-                    } else if (cj === '[') {
+                    }
+                    if (cj === '[') {
                         ++depth;
                     } else if (cj === ']') {
                         --depth;
@@ -3161,21 +3212,37 @@
     }
 
     // Split on TOP-LEVEL commas only: a comma inside {...}/[...] sets or
-    // inside quotes is data, not a separator (height_95%_HPD={1.4,1.5} must
-    // stay one token).
-    function splitTopLevelCommas(s) {
+    // inside a quoted VALUE is data, not a separator (height_95%_HPD={1.4,1.5}
+    // must stay one token). A quote that does not open a value is itself data
+    // (opensBlobQuote): country=Côte d'Ivoire,region=Africa is two fields.
+    //
+    // TWO quoting rules live here, because two grammars do. In a Nexus
+    // TRANSLATE table the things between the commas are LABELS, and a quote
+    // opens one wherever it stands (1 'Korea, Republic of'). In a [&...] blob
+    // they are key=value fields, and a quote opens only a VALUE. Giving the
+    // table the blob's rule split 'Korea, Republic of' in two, which a test
+    // caught the moment it was tried; `blob` says which grammar this is.
+    function splitTopLevelCommas(s, blob) {
         let out = [];
         let depth = 0;
         let q = null;
         let cur = '';
         for (let i = 0; i < s.length; ++i) {
             let c = s.charAt(i);
+            if (blob && (c === "'" || c === '"') && opensBlobQuote(s, i, 0)) {
+                let close = blobQuoteClose(s, i, false);
+                if (close > -1) {
+                    cur += s.substring(i, close + 1);   // a quoted value, its commas data
+                    i = close;
+                    continue;
+                }
+            }
             if (q) {
                 if (c === q) {
                     q = null;
                 }
                 cur += c;
-            } else if (c === "'" || c === '"') {
+            } else if (!blob && (c === "'" || c === '"')) {
                 q = c;
                 cur += c;
             } else if (c === '{' || c === '[') {
@@ -3199,9 +3266,44 @@
         return out;
     }
 
+    // A NUMBER is a plain decimal with an optional exponent, and nothing else
+    // -- the desktop's grammar (Christian, 2026-09-16). The test used to be
+    // "parseFloat is finite AND Number is finite", and the two read different
+    // languages: Number() understands 0x1A, 0b101 and 0o17, parseFloat() stops
+    // at the letter and answers 0. So a trait that merely LOOKED like a hex
+    // literal was typed numeric, and a height written that way dated its node
+    // at 0 -- a wrong answer where a refusal was due. One pattern now decides,
+    // for a value read as a number and for a property's datatype alike.
+    const PLAIN_DECIMAL_RE = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+
     function parseBeastNumber(v) {
-        let d = parseFloat(v);
-        return (isFinite(d) && isFinite(Number(v))) ? d : null;
+        let t = String(v).trim();
+        if (!PLAIN_DECIMAL_RE.test(t)) {
+            return null;
+        }
+        let d = parseFloat(t);
+        return isFinite(d) ? d : null;   // 1e400 is well-formed and still not a number we can use
+    }
+
+    // FigTree's !color value: #rrggbb, or Java's SIGNED Color.getRGB() int,
+    // which FigTree writes whenever the colour came from AWT (real files: every
+    // tag in test_trees/influenza.tree is #-8381639, never hex). Each '>>>'
+    // coerces to an unsigned 32-bit value first, so the low three bytes come
+    // out as RGB regardless of sign; the alpha byte is discarded. Null when it
+    // is neither.
+    function parseFigTreeColor(value) {
+        if (/^#[0-9a-f]{6}$/i.test(value)) {
+            return {
+                red: parseInt(value.substring(1, 3), 16),
+                green: parseInt(value.substring(3, 5), 16),
+                blue: parseInt(value.substring(5, 7), 16)
+            };
+        }
+        if (/^#-?[0-9]{1,10}$/.test(value)) {
+            let argb = Number(value.substring(1));
+            return {red: (argb >>> 16) & 0xff, green: (argb >>> 8) & 0xff, blue: argb & 0xff};
+        }
+        return null;
     }
 
     // A two-value BEAST set {lo,hi} (or [lo,hi]) as [lo,hi] numbers, or null.
@@ -3210,7 +3312,7 @@
         if (s.length < 3 || (s.charAt(0) !== '{' && s.charAt(0) !== '[')) {
             return null;
         }
-        let parts = splitTopLevelCommas(s.substring(1, s.length - 1));
+        let parts = splitTopLevelCommas(s.substring(1, s.length - 1), true);
         if (parts.length !== 2) {
             return null;
         }
@@ -3272,6 +3374,15 @@
     //  - node age height/height_mean/height_median + height_95%_HPD (or
     //    height_range) + date -> node.date value/min/max/desc (the node-age
     //    HPD bars draw the interval);
+    //  - Auspice's "download Nexus" vocabulary lands exactly where
+    //    parseAuspiceJson puts the same dataset, so one Nextstrain build opens
+    //    the same way whichever format it was saved in: num_date -> the date
+    //    VALUE with unit "year", plus a nextstrain:num_date property;
+    //    num_date_CI={lo,hi} -> that date's minimum/maximum, on a tip too
+    //    (there it is the sampling-date uncertainty); div -> a
+    //    nextstrain:div property. A num_date outranks every height* (it is a
+    //    calendar year, a height is an age before present), it alone carries
+    //    the unit, and it never borrows the height's HPD as its interval;
     //  - FigTree !color=#rrggbb -> the branch color;
     //  - every other field (rate, length_*, traits, location, ...) -> a
     //    beast:<key> node property (numeric -> xsd:decimal, so Color-by
@@ -3285,9 +3396,14 @@
         let hpd = null;
         let range = null;
         let dateDesc = null;
+        let hpdText = null;
+        let rangeText = null;
+        let numDate = null;
+        let numDateCi = null;
+        let numDateCiKey = null;
         let prob = null;
         let probSd = null;
-        splitTopLevelCommas(blob).forEach(function (token) {
+        splitTopLevelCommas(blob, true).forEach(function (token) {
             let eq = token.indexOf('=');
             if (eq <= 0) {
                 return;
@@ -3312,13 +3428,8 @@
                 if (b !== null) {
                     pushConfidence(node, b, 'bootstrap');
                 }
-            } else if ((kl === '!color' || kl === '!colour')
-                && /^#[0-9a-f]{6}$/i.test(value)) {
-                node.color = {
-                    red: parseInt(value.substring(1, 3), 16),
-                    green: parseInt(value.substring(3, 5), 16),
-                    blue: parseInt(value.substring(5, 7), 16)
-                };
+            } else if ((kl === '!color' || kl === '!colour') && parseFigTreeColor(value) !== null) {
+                node.color = parseFigTreeColor(value);   // in the tree string it is the BRANCH colour
             } else if (kl === 'height_median') {
                 heightMedian = value;
             } else if (kl === 'height_mean') {
@@ -3327,10 +3438,37 @@
                 height = value;
             } else if (kl === 'height_95%_hpd') {
                 hpd = parseBeastInterval(value);
+                hpdText = value;
             } else if (kl === 'height_range') {
                 range = parseBeastInterval(value);
+                rangeText = value;
             } else if (kl === 'date') {
                 dateDesc = value;
+            } else if (kl === 'num_date') {
+                numDate = value;
+            } else if (kl === 'num_date_ci') {
+                numDateCi = value;
+                numDateCiKey = beastRefKey(key);
+            } else if (kl === 'div' && parseBeastNumber(value) !== null) {
+                addNodeProperty(node, NEXTSTRAIN_PREFIX + 'div', value);
+            } else if (key.charAt(0) === '!') {
+                // A key that starts with '!' is one of FigTree's display
+                // DIRECTIVES -- !color, !rotate, !collapse, !hilight, !name --
+                // never a measurement, so it is never typed numeric. It
+                // matters for the forms we refuse as a colour: !color=-8381639
+                // (no '#') used to land as beast:_color typed xsd:decimal, and
+                // Color-by offered FigTree's paint as a gradient. It is still
+                // KEPT -- nothing in this reader throws data away -- under the
+                // same ref, as text. A user's own trait called "color" has no
+                // '!' and stays an ordinary trait. (The desktop's rule;
+                // Christian, 2026-09-17: "do the same".)
+                addNodeProperty(node, 'beast:' + beastRefKey(key), value, 'xsd:string');
+            } else if (kl === 'mutations' || kl === 'mcc') {
+                // TEXT, whatever it looks like (the desktop forces the same):
+                // a list of mutations that happens to hold one number, or a
+                // clade label that happens to be "3", is not a measurement,
+                // and typing it decimal offers it to Color-by as a gradient
+                addNodeProperty(node, 'beast:' + beastRefKey(key), value, 'xsd:string');
             } else {
                 addNodeProperty(node, 'beast:' + beastRefKey(key), value);
             }
@@ -3338,28 +3476,60 @@
         if (prob !== null) {
             pushConfidence(node, prob, 'posterior probability', probSd);
         }
-        // age preference: median, then mean, then height -- and each piece
-        // parsed independently, so an unparseable point value never discards
-        // a valid {lo,hi} interval
-        let v = heightMedian !== null ? heightMedian
-            : (heightMean !== null ? heightMean : height);
-        let dv = (v !== null) ? parseBeastNumber(v) : null;
-        let interval = hpd || range;
-        if (dv === null && !interval && dateDesc === null) {
-            return;
+        // A num_date that parses is the node's date, and nothing about a
+        // height may touch it. One that does not parse is just a field: it and
+        // its interval fall back to plain text, as any unknown key does.
+        let year = (numDate !== null) ? parseBeastNumber(numDate) : null;
+        let yearCi = (numDateCi !== null) ? parseBeastInterval(numDateCi) : null;
+        if (numDate !== null) {
+            addNodeProperty(node, (year !== null ? NEXTSTRAIN_PREFIX : 'beast:') + 'num_date', numDate);
         }
-        let date = {};
-        if (dv !== null) {
-            date.value = dv;
+        if (numDateCi !== null && (year === null || yearCi === null)) {
+            // an interval with no date to bracket, or not an interval at all
+            addNodeProperty(node, (yearCi !== null ? NEXTSTRAIN_PREFIX : 'beast:') + numDateCiKey, numDateCi);
         }
-        if (interval) {
-            date.minimum = interval[0];
-            date.maximum = interval[1];
+        let date = {};
+        if (year !== null) {
+            date.value = year;
+            date.unit = 'year';
+            if (yearCi !== null) {
+                date.minimum = yearCi[0];
+                date.maximum = yearCi[1];
+            }
+            // provisional until the whole tree has been read: settleNumDates
+            // decides whether this tree is time-scaled at all
+            node._numDate = {ciKey: numDateCiKey, ciText: yearCi !== null ? numDateCi : null};
+            // the heights it outranked are kept as what they were written as,
+            // rather than dropped: no real file carries both, so nothing here
+            // is lost to a guess
+            [['height_median', heightMedian], ['height_mean', heightMean], ['height', height],
+                ['height_95_HPD', hpdText], ['height_range', rangeText]].forEach(function (h) {
+                if (h[1] !== null) {
+                    addNodeProperty(node, 'beast:' + h[0], h[1]);
+                }
+            });
+        } else {
+            // age preference: median, then mean, then height -- and each piece
+            // parsed independently, so an unparseable point value never
+            // discards a valid {lo,hi} interval
+            let v = heightMedian !== null ? heightMedian
+                : (heightMean !== null ? heightMean : height);
+            let dv = (v !== null) ? parseBeastNumber(v) : null;
+            let interval = hpd || range;
+            if (dv !== null) {
+                date.value = dv;
+            }
+            if (interval) {
+                date.minimum = interval[0];
+                date.maximum = interval[1];
+            }
         }
         if (dateDesc !== null) {
             date.desc = dateDesc;
         }
-        node.date = date;
+        if (Object.keys(date).length > 0) {
+            node.date = date;
+        }
     }
 
     // The classic NHX tag set, as the desktop maps it: S= taxonomy
@@ -3367,8 +3537,8 @@
     // duplication (Y/T) / speciation (N/F) / undecided (?) event, GN=
     // sequence name, AC= sequence accession, C= an nh:comment property.
     // Unknown tags (and DS= domain structures) are ignored.
-    function applyNhxTags(node, content) {
-        content.split(':').forEach(function (tag) {
+    function applyNhxTags(node, fields) {
+        fields.forEach(function (tag) {
             let t = tag.trim();
             if (t.length < 3) {
                 return;
@@ -3401,14 +3571,327 @@
         });
     }
 
+    // Inside a legacy [&&NHX:...] tag the desktop reads by its LABEL rule, and
+    // so do we (Christian, 2026-09-16: "do what desktop does"):
+    //  - UNQUOTED whitespace is formatting noise and is squeezed out -- its
+    //    Test.testNHXParsingQuotes pins "[\t&\t&\n N\tH\tX:S=mo\tnkey !]" as
+    //    S=monkey!, and S=Homo sapiens reads as Homosapiens;
+    //  - a QUOTED run, either style, keeps what is inside it -- S="homo sapiens"
+    //    is homo sapiens, the one way to put a two-word species into an NHX tag
+    //    -- with a run of whitespace collapsed to one space, and may carry the
+    //    ':' that would otherwise end the tag (S="a:b c":D=Y);
+    //  - the quote characters themselves are never part of the value.
+    // My first version squeezed quotes and ALL whitespace out of the blob, from
+    // an inference off that one pinned case; the desktop then MEASURED its own
+    // behaviour and the quoted forms differed (homosapiens here, homo sapiens
+    // there). The opposite of a single-& blob, where quotes and spaces are
+    // data -- so none of this runs until the blob has shown itself to be NHX.
+    function nhxFields(blob) {
+        let out = [];
+        let cur = '';
+        let q = null;
+        let spaced = false;
+        for (let i = 0; i < blob.length; ++i) {
+            let c = blob.charAt(i);
+            if (q) {
+                if (c === q) {
+                    q = null;
+                } else if (/\s/.test(c)) {
+                    if (!spaced) {
+                        cur += ' ';
+                        spaced = true;
+                    }
+                } else {
+                    cur += c;
+                    spaced = false;
+                }
+            } else if (c === "'" || c === '"') {
+                q = c;
+                spaced = false;
+            } else if (c === ':') {
+                out.push(cur);
+                cur = '';
+            } else if (!/\s/.test(c)) {
+                cur += c;
+            }
+        }
+        out.push(cur);
+        return out;
+    }
+
     function applyExtendedAnnotations(node, blob) {
-        if (/^&&NHX:/i.test(blob)) {
-            applyNhxTags(node, blob.substring(6));
+        let fields = nhxFields(blob);
+        if (/^&&NHX$/i.test(fields[0])) {
+            applyNhxTags(node, fields.slice(1));
         } else {
             applyBeastAnnotations(node, blob.replace(/^&/, ''));
         }
     }
 
+    // ---------------------------------------------------------------
+    // A bare numeric date= as a node date VALUE (TreeTime)
+    // ---------------------------------------------------------------
+    //
+    // applyBeastAnnotations files date= as a date DESC and nothing else, which
+    // is what the desktop's BeastAnnotationParser does and stays that way --
+    // in BEAST output the age lives in height*, and date= is a decoration.
+    //
+    // TreeTime has no height at all: it writes "[&mutations=...,date=2003.84]"
+    // and the decimal year IS the node's position in time. Left as a desc the
+    // tree carries no date value, so isTimeTree is false and the calendar axis
+    // never appears -- a time tree that does not look like one.
+    //
+    // The catch is that TreeTime writes that SAME comment on both trees it
+    // emits: timetree.nexus, whose branch lengths are years, and
+    // divergence_tree.nexus, whose branch lengths are substitutions. No single
+    // annotation says which file it came from, and promoting blindly would put
+    // a calendar axis (which maps one branch-length unit to one year) on a
+    // divergence tree and silently disable re-rooting for it.
+    //
+    // So the TREE is asked rather than the annotation sniffed: a numeric date
+    // becomes a value only where the parent-to-child date differences actually
+    // reproduce the branch lengths. That needs no format detection, it is
+    // self-validating on any input, and it separates TreeTime's two files
+    // exactly. The desc is left in place either way, so nothing is lost.
+    const NUMERIC_DATE_ABS_TOL = 0.02;  // date= is written to 2 decimals, so a
+    const NUMERIC_DATE_REL_TOL = 0.01;  // difference of two carries ~0.01 error
+
+    function numericDateDesc(n) {
+        if (!n.date || n.date.value !== undefined || typeof n.date.desc !== 'string') {
+            return null;
+        }
+        return parseBeastNumber(n.date.desc);
+    }
+
+    // THE PAIR COUNT, shared by the date= promotion below and by
+    // settleNumDates, so the two can never drift: a PAIR is a dated node, its
+    // dated DIRECT parent and a branch length between them, and it AGREES
+    // when the year difference reproduces that length within the tolerances.
+    //
+    // A pair must also be INFORMATIVE: max(|dYear|, |length|) > the absolute
+    // tolerance. One that is not cannot tell years from substitutions at all
+    // -- both numbers sit inside the tolerance, so it "agrees" whatever the
+    // tree is measured in -- and it is left out of BOTH counts. That is not a
+    // nicety. The 0.02 tolerance is larger than a dense tree's substitution
+    // lengths, so on a densely sampled DIVERGENCE tree such pairs pile up as
+    // agreement. Measured by rebuilding real Auspice time-tree exports as
+    // their divergence trees (length = the div difference, same num_dates):
+    //                 agreeing, every pair       informative pairs only
+    //   H5N1 (2 y)    3620 of 9205  (39.3%)      1 of 5586
+    //   chikungunya    672 of 2645  (25.4%)      0 of 1973
+    //   measles        915 of 5388  (17.0%)      0 of 4473
+    // while every time tree stays at 100% either way (H5N1 5586 of 5586).
+    // 39% is under the majority, so nothing visible changed on those files;
+    // it is headroom -- a denser build would have crossed it and been dated
+    // on substitutions. Found by a review on the desktop, reproduced here to
+    // the pair, and a JOINT RULE (Christian, 2026-09-17, both sessions). The
+    // burden of proof is untouched: with no informative pair at all a date=
+    // is still not promoted and a num_date still stands.
+    function countDatePairs(root, yearOf) {
+        let dated = [];
+        let agree = 0;
+        let pairs = 0;
+        let stack = [[root, null]];
+        while (stack.length > 0) {
+            let top = stack.pop();
+            let n = top[0];
+            let year = yearOf(n);
+            if (year !== null) {
+                dated.push([n, year]);
+                let parentYear = top[1];
+                if (parentYear !== null && typeof n.branch_length === 'number'
+                    && isFinite(n.branch_length)) {
+                    let dYear = year - parentYear;
+                    if (Math.max(Math.abs(dYear), Math.abs(n.branch_length)) > NUMERIC_DATE_ABS_TOL) {
+                        ++pairs;
+                        let tol = NUMERIC_DATE_ABS_TOL
+                            + NUMERIC_DATE_REL_TOL * Math.abs(n.branch_length);
+                        if (Math.abs(dYear - n.branch_length) <= tol) {
+                            ++agree;
+                        }
+                    }
+                }
+            }
+            if (n.children) {
+                for (let i = 0; i < n.children.length; ++i) {
+                    stack.push([n.children[i], year]);
+                }
+            }
+        }
+        return {dated: dated, pairs: pairs, agree: agree};
+    }
+
+    function promoteTimeScaledDates(phy) {
+        let root = forester.getTreeRoot(phy);
+        if (!root) {
+            return;
+        }
+        let counted = countDatePairs(root, numericDateDesc);
+        let dated = counted.dated;
+        let pairs = counted.pairs;
+        let agree = counted.agree;
+        if (pairs < 2 || agree * 2 <= pairs) {
+            return;
+        }
+        dated.forEach(function (d) {
+            d[0].date.value = d[1];
+            d[0].date.unit = 'year';
+        });
+    }
+
+    // ---------------------------------------------------------------
+    // An Auspice num_date is a date VALUE only on a time-scaled tree
+    // ---------------------------------------------------------------
+    //
+    // Auspice's "download Nexus" offers the SAME annotations on two trees: the
+    // time tree (…_timetree.nexus, branch lengths in years) and the divergence
+    // tree (…_tree.nexus, branch lengths in substitutions). A date value is
+    // what makes a tree a time tree here -- isTimeTree counts them -- and the
+    // calendar axis maps one branch-length unit to one year, so dating the
+    // divergence export would hang that axis on a tree measured in
+    // substitutions and refuse its re-rooting. Measured on real exports, the
+    // parent-to-child num_date differences reproduce the branch lengths on
+    //   measles timetree   5388 of 5388 pairs
+    //   chikv timetree     2645 of 2645 pairs
+    //   lassa_gpc tree      169 of 2295 pairs (7.4%)
+    // so this is the question promoteTimeScaledDates already asks of a
+    // TreeTime date=, with the same pinned tolerances, put to the tree rather
+    // than guessed from a file name. The difference is the burden of proof: a
+    // date= may not be a value at all, so it needs evidence FOR; a num_date is
+    // a date by its very name, so it stands unless there is evidence AGAINST
+    // -- two comparable pairs or more, and no strict majority agreeing. A tree
+    // too small to say anything keeps its dates.
+    //
+    // A JOINT RULE with the desktop (Christian, 2026-09-16), chosen over
+    // keeping it here alone, over dating unconditionally, and over moving the
+    // question up into isTimeTree -- which would have changed that answer for
+    // every dated input, phyloXML and BEAST included. Do not retune it alone.
+    //
+    // Where the tree is not time-scaled nothing is lost: the year stays on
+    // the node as nextstrain:num_date (numeric, so Color-by and search have
+    // it) and its interval as nextstrain:num_date_CI, exactly what an
+    // interval with no date to bracket becomes anyway.
+    function settleNumDates(phy) {
+        let root = forester.getTreeRoot(phy);
+        if (!root) {
+            return;
+        }
+        let counted = countDatePairs(root, function (n) {
+            return n._numDate ? n.date.value : null;
+        });
+        let marked = counted.dated.map(function (d) {
+            return d[0];
+        });
+        let pairs = counted.pairs;
+        let agree = counted.agree;
+        let notTimeScaled = pairs >= 2 && agree * 2 <= pairs;
+        marked.forEach(function (n) {
+            let m = n._numDate;
+            delete n._numDate;
+            if (!notTimeScaled) {
+                // A TIP keeps its interval too. It used to be dropped here
+                // and in parseAuspiceJson, for a DISPLAY reason -- a bar on a
+                // tip read as a fossil range -- and that threw real data away:
+                // a sample dated only to its month or year. Counted on real
+                // exports: dengue 2347 of 3863 tips carry a genuine interval
+                // (median 0.78 y), measles 1390 of 2985, enterovirus 715 of
+                // 1600. The display now tells a sampled tip from a fossil
+                // instead (drawTimeAxis); Christian, 2026-09-17, both programs.
+                return;
+            }
+            delete n.date.value;
+            delete n.date.unit;
+            delete n.date.minimum;
+            delete n.date.maximum;
+            if (Object.keys(n.date).length === 0) {
+                delete n.date;
+            }
+            if (m.ciText !== null) {
+                addNodeProperty(n, NEXTSTRAIN_PREFIX + m.ciKey, m.ciText);
+            }
+        });
+    }
+
+    // ---------------------------------------------------------------
+    // TreeTime's own namespace
+    // ---------------------------------------------------------------
+    //
+    // TreeTime's annotations arrive through the BEAST path, so they were
+    // landing as beast:<key> -- accurate about the syntax, wrong about the
+    // producer, and confusing next to a real BEAST run. Christian asked for a
+    // namespace of their own (2026-09-16).
+    //
+    // The producer is recognised on the TREE, not the file: a TreeTime tree
+    // carries mutations= and no node age at all, where every BEAST/MrBayes
+    // run states an age (height, height_mean, height_median, and the
+    // height_95%_HPD / height_range intervals). So the test is "mutations
+    // present, age absent", which cannot fire on a BEAST file and leaves that
+    // shared contract with the desktop untouched.
+    //
+    // TreeTime's mugration output is a bare user-named trait -- [&region="x"]
+    // and nothing else -- which no rule could attribute to any producer. It
+    // keeps the generic namespace, correctly.
+    const TREETIME_PREFIX = 'treetime:';
+    const BEAST_PREFIX = 'beast:';
+
+    // Must run BEFORE promoteTimeScaledDates: until then a date VALUE can
+    // only have come from a BEAST height field or an Auspice num_date, and
+    // either one says this is not TreeTime's own Nexus.
+    function renameTreeTimeProperties(phy) {
+        let nodes = forester.getAllNodes(phy);
+        let mutations = false;
+        for (let i = 0; i < nodes.length; ++i) {
+            let d = nodes[i].date;
+            if (d && (d.value !== undefined || d.minimum !== undefined
+                || d.maximum !== undefined)) {
+                return;
+            }
+            if (!mutations && nodes[i].properties) {
+                mutations = nodes[i].properties.some(function (p) {
+                    return p.ref === BEAST_PREFIX + 'mutations';
+                });
+            }
+        }
+        if (!mutations) {
+            return;
+        }
+        nodes.forEach(function (n) {
+            if (n.properties) {
+                n.properties.forEach(function (p) {
+                    if (typeof p.ref === 'string' && p.ref.indexOf(BEAST_PREFIX) === 0) {
+                        p.ref = TREETIME_PREFIX + p.ref.substring(BEAST_PREFIX.length);
+                    }
+                });
+            }
+        });
+    }
+
+    // The namespace this tree's bracket annotations ended up in, for anything
+    // added to it AFTER the pass above has run -- the Nexus reader hangs a
+    // taxon's refused colour on its tip once the tree string is parsed, and
+    // filed it under beast: on a tree the pass had just renamed: one tree, two
+    // namespaces. The rename is all-or-nothing, so the tree already says which
+    // it took; and asking it, rather than running the pass a second time, is
+    // deliberate -- after promoteTimeScaledDates a TreeTime tree HAS date
+    // values, and a second run would read that as "not TreeTime's own".
+    // (Sound only while nothing read from a taxon can sway the decision; we
+    // read !color alone there. The desktop reads the whole blob, and so has to
+    // run its pass after the taxlabels instead.)
+    function annotationPrefix(phy) {
+        let nodes = forester.getAllNodes(phy);
+        for (let i = 0; i < nodes.length; ++i) {
+            let props = nodes[i].properties;
+            if (props) {
+                for (let j = 0; j < props.length; ++j) {
+                    if (typeof props[j].ref === 'string' && props[j].ref.indexOf(TREETIME_PREFIX) === 0) {
+                        return TREETIME_PREFIX;
+                    }
+                }
+            }
+        }
+        return BEAST_PREFIX;
+    }
+
     forester.parseNewHampshire = function (nhStr, confidenceValuesInBrackets, confidenceValuesAsInternalNames) {
 
         let NH_FORMAT_ERR_OPEN_PARENS = NH_FORMAT_ERR + 'likely cause: number of open parentheses is larger than number of close parentheses';
@@ -3638,6 +4121,10 @@
             moveInternalNodeNamesToConfidenceValues(phy);
         }
 
+        renameTreeTimeProperties(phy);   // first: a provisional num_date still says "not TreeTime's own"
+        settleNumDates(phy);
+        promoteTimeScaledDates(phy);
+
         return phy;
 
         function addConfidence(x, element) {
@@ -3773,6 +4260,11 @@
 
         let trees = [];
         let taxlabels = [];
+        let taxlabelColors = Object.create(null);   // label -> #rrggbb, from 'name'[&!color=...]
+        let taxlabelColorsByKey = Object.create(null);   // the same, under the Nexus join key
+        let taxlabelRefused = Object.create(null);   // label -> a !color value we could not read, kept as text
+        let taxlabelRefusedByKey = Object.create(null);
+        let taxlabelKeyCount = Object.create(null);   // join key -> how many taxlabels share it, annotated or not
         // null-prototype maps: a taxon named "__proto__" must stay data
         let translateMap = Object.create(null);
         let seqs = Object.create(null);
@@ -3937,6 +4429,7 @@
                 seqsByKey[joinKey(id)] = seqs[id];
             }
             let externals = forester.getAllExternalNodes(phy);
+            let annotationNs = null;
             // A bare integer tip name counts as a TAXLABELS index only when
             // the WHOLE tree reads as index references: every tip a bare
             // integer AND every one of them in range. All-or-nothing, because
@@ -3969,6 +4462,41 @@
                     // un-doubling and drop the apostrophe a second time.
                     node.name = taxlabels[parseInt(node.name, 10) - 1];
                 }
+                // A colour FigTree gave the TAXON is the colour of its LABEL
+                // -- FigTree's own meaning, and the desktop's (Christian,
+                // 2026-09-16) -- where a !color in the tree string is the
+                // BRANCH's. It lands as the desktop's style:font_color
+                // property, which is what Visual Styles already draws and what
+                // phyloXML already carries, so nothing downstream is new.
+                // The taxon is found by its exact name, else by the Nexus join
+                // key (case-insensitive, '_' for ' ') -- but by the key ONLY
+                // when it names exactly ONE taxlabel, counting every taxlabel,
+                // annotated or not. Without that, Taxon_A[&!color=red] beside a
+                // plain taxon_a coloured BOTH tips: taxon_a has no annotation
+                // of its own, so it fell through to a key it shares. And a tip
+                // matching two labels by key alone is ambiguous: no colour,
+                // rather than whichever was written last. (Found by a review on
+                // the desktop, which had the same fallback; its rule.)
+                let loneKey = !!node.name && taxlabelKeyCount[joinKey(node.name)] === 1;
+                let labelColor = !node.name ? undefined
+                    : (taxlabelColors[node.name] !== undefined ? taxlabelColors[node.name]
+                        : (loneKey ? taxlabelColorsByKey[joinKey(node.name)] : undefined));
+                if (labelColor !== undefined) {
+                    if (!node.properties) {
+                        node.properties = [];
+                    }
+                    node.properties.push({ref: 'style:font_color', value: labelColor,
+                        datatype: 'xsd:token', applies_to: 'node'});
+                }
+                let refusedColor = !node.name ? undefined
+                    : (taxlabelRefused[node.name] !== undefined ? taxlabelRefused[node.name]
+                        : (loneKey ? taxlabelRefusedByKey[joinKey(node.name)] : undefined));
+                if (refusedColor !== undefined) {
+                    if (annotationNs === null) {
+                        annotationNs = annotationPrefix(phy);   // once per tree, and only if needed
+                    }
+                    addNodeProperty(node, annotationNs + '_color', refusedColor, 'xsd:string');
+                }
                 if (node.name) {
                     let s = seqsByKey[joinKey(node.name)];
                     if (s) {
@@ -4091,6 +4619,7 @@
                     let push = function () {
                         if (tok.length > 0 && tok.toLowerCase() !== 'taxlabels') {
                             taxlabels.push(tok);
+                            taxlabelKeyCount[joinKey(tok)] = (taxlabelKeyCount[joinKey(tok)] || 0) + 1;
                         }
                         tok = '';
                         closed = false;
@@ -4128,6 +4657,48 @@
                                 // divergence, not a fix.
                                 void ch;
                             }
+                        } else if (ch === '[') {
+                            // A bracket after a label is not part of it. FigTree
+                            // hangs the taxon's colour here --
+                            // 'NewYork_454_1999.05'[&!color=#-8381639] -- and it
+                            // used to be glued onto the label, which then named
+                            // no tip (invisible while a tree spells its tips
+                            // out, wrong as soon as it refers to them by number).
+                            // A [&...] belongs to the label just read; any other
+                            // bracket is an ordinary Nexus comment.
+                            //
+                            // Only !color is read from it, and that is DECIDED
+                            // (Christian, 2026-09-17: "keep it as it is"), a named
+                            // difference from the desktop, which keeps every field
+                            // of a taxon's annotation. No producer we know writes
+                            // anything else here. Widening it is not a small edit:
+                            // a posterior, a height or mutations arriving by this
+                            // road could sway the per-tree pass, which would then
+                            // have to run after the taxlabels (see annotationPrefix).
+                            let end = line.indexOf(']', ci);
+                            let inside = line.substring(ci + 1, end < 0 ? line.length : end).trim();
+                            if (inside.charAt(0) === '&' && tok.length > 0) {
+                                splitTopLevelCommas(inside.substring(1), true).forEach(function (field) {
+                                    let eq = field.indexOf('=');
+                                    let key = eq > 0 ? field.substring(0, eq).trim().toLowerCase() : '';
+                                    let isColor = key === '!color' || key === '!colour';
+                                    let raw = isColor ? stripValueQuotes(field.substring(eq + 1).trim()) : '';
+                                    let rgb = isColor ? parseFigTreeColor(raw) : null;
+                                    if (isColor && !rgb && raw.length > 0) {
+                                        // not a colour we read (no '#', say): kept as
+                                        // text on the tip, as in the tree string
+                                        taxlabelRefused[tok] = raw;
+                                        taxlabelRefusedByKey[joinKey(tok)] = raw;
+                                    }
+                                    if (rgb) {
+                                        taxlabelColors[tok] = '#' + [rgb.red, rgb.green, rgb.blue].map(function (c) {
+                                            return (c < 16 ? '0' : '') + c.toString(16);
+                                        }).join('');
+                                        taxlabelColorsByKey[joinKey(tok)] = taxlabelColors[tok];
+                                    }
+                                });
+                            }
+                            ci = end < 0 ? line.length : end;
                         } else if (ch === ' ') {
                             push();
                         } else if (ch === ';') {
@@ -4240,7 +4811,9 @@
         return d.toFixed(20).replace(/0+$/, '').replace(/\.$/, '');
     }
 
-    function addNodeProperty(node, ref, value) {
+    // `datatype` is for the few values whose type is decided by what they ARE
+    // rather than by what they look like (see mutations / mcc).
+    function addNodeProperty(node, ref, value, datatype) {
         if (value === undefined || value === null || String(value).length === 0) {
             return;
         }
@@ -4251,7 +4824,7 @@
         node.properties.push({
             ref: ref,
             value: v,
-            datatype: isFinite(parseFloat(v)) && isFinite(Number(v)) ? 'xsd:decimal' : 'xsd:string',
+            datatype: datatype || (parseBeastNumber(v) !== null ? 'xsd:decimal' : 'xsd:string'),
             applies_to: 'node'
         });
     }
@@ -4259,7 +4832,8 @@
     // Parses an Auspice / Nextstrain v2 dataset.json (string or already-parsed
     // object) into ONE tree object, mapping its per-node data onto the native
     // phyloXML shape so the existing overlays light it up -- ported from the
-    // desktop's AuspiceJsonParser:
+    // desktop's AuspiceJsonParser. TreeTime's own auspice_tree.json is read
+    // here too (see the version check below):
     //  - node_attrs.num_date.value -> node.date value (decimal year) -> the
     //    calendar time axis; its .confidence [lo,hi] -> date minimum/maximum
     //    -> the node-age (HPD) bars;
@@ -4278,8 +4852,21 @@
         if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
             throw new Error('not an Auspice dataset (the JSON root is not an object)');
         }
-        if (doc.version !== 'v2' || !doc.tree || typeof doc.tree !== 'object'
-            || Array.isArray(doc.tree)) {
+        if (!doc.tree || typeof doc.tree !== 'object' || Array.isArray(doc.tree)) {
+            throw new Error('not an Auspice v2 dataset (expected "version":"v2" and a "tree" object)');
+        }
+        // The version stamp is taken as PRESENT-OR-IMPLIED: TreeTime writes a
+        // fully valid v2 dataset ({meta, tree} with node_attrs.num_date,
+        // branch_attrs, children) and simply never writes "version":"v2", so
+        // demanding the stamp rejected the richest file TreeTime produces --
+        // the only one carrying full-precision dates (its .nexus rounds them
+        // to two decimals). The shape is still checked, so arbitrary JSON
+        // keeps getting the clear error rather than a confusing parse.
+        if (doc.version !== 'v2'
+            && !(doc.meta && typeof doc.meta === 'object' && !Array.isArray(doc.meta)
+                && (typeof doc.tree.name === 'string'
+                    || (doc.tree.node_attrs && typeof doc.tree.node_attrs === 'object')
+                    || Array.isArray(doc.tree.children)))) {
             throw new Error('not an Auspice v2 dataset (expected "version":"v2" and a "tree" object)');
         }
 
@@ -4387,16 +4974,11 @@
             // keep the layout meaningful instead of a cladogram
             setDeltaBranchLengths(root, null, auspiceNodeDiv);
         }
-        // A TIP is a dated sample: keep its point date (the calendar axis)
-        // but drop the date INTERVAL -- the divergence-time uncertainty (the
-        // node-age bars) belongs to the INTERNAL nodes, and a tip interval
-        // would read as a fossil-style observed range on a viral tree.
-        forester.preOrderTraversalAll(root, function (n) {
-            if (!n.children && n.date
-                && (n.date.minimum !== undefined || n.date.maximum !== undefined)) {
-                n.date = {value: n.date.value, unit: n.date.unit};
-            }
-        });
+        // A tip keeps its date INTERVAL: on a Nextstrain build it is the
+        // sampling-date uncertainty of a sample dated only to its month or
+        // year, which is data. (It was dropped here until 2026-09-17 because
+        // the time axis drew every tip interval as a fossil range; the axis
+        // now tells the two apart -- see settleNumDates and drawTimeAxis.)
         forester.addParents(phy);
         return phy;
     };
@@ -5937,9 +6519,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
@@ -5949,6 +6539,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
@@ -5981,9 +6605,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;
@@ -6003,7 +6626,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;
@@ -6014,13 +6637,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 {
@@ -6036,25 +6656,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,
@@ -6065,6 +6676,540 @@
         };
     };
 
+    // ---- 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;
+        ranges.forEach(function (r) {
+            if (heightDateAllows(r, mid)) {
+                agreeingTips.push(r);
+                latestStart = Math.max(latestStart, r[0]);
+                earliestEnd = Math.min(earliestEnd, r[1]);
+            }
+        });
+        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
+        }
+        let present = Math.max(best[0], Math.min(best[1], heightDatePrecisestMedian(agreeingTips)));
+        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) {