archaeopteryx 3.7.0 → 3.8.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.7.0
+// v 3.8.0
 // 2026-09-10
 //
 // 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;
     };