archaeopteryx 3.6.1 → 3.8.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.6.1
+// v 3.8.0
 // 2026-09-10
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -781,6 +781,557 @@
         });
     };
 
+    // ---- representative tips ------------------------------------------------
+    //
+    // Tree-based dereplication, the desktop's "Select Representative Tips"
+    // (RepresentativeTipSelector) ported step for step, the order of its sums
+    // and its 1e-9 tolerance included: test/fixtures/rep-contract.tsv holds
+    // the desktop's own results and extractions (RepContract.java), and the
+    // tests hold ours to them.
+    //
+    // Tips are grouped into the maximal clades whose diameter -- the largest
+    // patristic distance between two of their tips -- is at most a cutoff, and
+    // each group keeps one representative. A clade's diameter only grows
+    // rootward, so the groups are one cut through the tree. Without branch
+    // lengths the distance is topological, one unit per edge.
+
+    forester.REPRESENTATIVE_MEDOID = 'medoid';
+    forester.REPRESENTATIVE_LONGEST_BRANCH = 'longest_branch';
+
+    const REPRESENTATIVE_EPS = 1e-9;
+
+    function repIsTip(n) {
+        return !n.children || n.children.length === 0;
+    }
+
+    // below `top`, parents before children, children in their order
+    function repPreorder(top) {
+        let out = [];
+        let stack = [top];
+        while (stack.length > 0) {
+            let n = stack.pop();
+            out.push(n);
+            if (n.children) {
+                for (let i = n.children.length - 1; i >= 0; --i) {
+                    stack.push(n.children[i]);
+                }
+            }
+        }
+        return out;
+    }
+
+    // the branch above a node, a missing or negative length counting 0
+    function repEdge(n, topological) {
+        if (topological) {
+            return 1;
+        }
+        let d = n.branch_length;
+        return (typeof d === 'number' && d > 0) ? d : 0;
+    }
+
+    /**
+     * Whether any branch of the tree carries a length (0 included). Without
+     * one, representative tips are chosen by topological distance, and a
+     * distance cutoff means nothing.
+     *
+     * @param phy the tree
+     * @returns {boolean}
+     */
+    forester.hasUsableBranchLengths = function (phy) {
+        let root = forester.getTreeRoot(phy);
+        return repPreorder(root).some(function (n) {
+            return n !== root && typeof n.branch_length === 'number';
+        });
+    };
+
+    // every node's diameter, in one pass from the tips up
+    function repDiameters(pre, topological) {
+        let height = new Map();
+        let diameter = new Map();
+        for (let i = pre.length - 1; i >= 0; --i) {
+            let n = pre[i];
+            if (repIsTip(n)) {
+                height.set(n, 0);
+                diameter.set(n, 0);
+                continue;
+            }
+            let best1 = 0;   // the longest reach down through one child
+            let best2 = 0;   // through another
+            let maxChildDiameter = 0;
+            for (let c = 0; c < n.children.length; ++c) {
+                let child = n.children[c];
+                let reach = height.get(child) + repEdge(child, topological);
+                if (reach >= best1) {
+                    best2 = best1;
+                    best1 = reach;
+                } else if (reach > best2) {
+                    best2 = reach;
+                }
+                maxChildDiameter = Math.max(maxChildDiameter, diameter.get(child));
+            }
+            height.set(n, best1);
+            diameter.set(n, Math.max(maxChildDiameter, n.children.length >= 2 ? best1 + best2 : 0));
+        }
+        return diameter;
+    }
+
+    // the groups' clades: the highest nodes whose diameter is within the cutoff
+    function repGroupRoots(root, diameter, cutoff) {
+        let roots = [];
+        let stack = [root];
+        while (stack.length > 0) {
+            let n = stack.pop();
+            if (repIsTip(n) || diameter.get(n) <= cutoff + REPRESENTATIVE_EPS) {
+                roots.push(n);
+            } else {
+                for (let i = 0; i < n.children.length; ++i) {
+                    stack.push(n.children[i]);
+                }
+            }
+        }
+        return roots;
+    }
+
+    // The cutoff whose group count comes closest to the target: the count
+    // changes only at clade diameters and never grows with the cutoff, so a
+    // binary search finds the smallest diameter giving at most the target,
+    // and its neighbour below gives more. A tie keeps more representatives;
+    // -1 stands for "below every diameter", every tip its own group.
+    function repCutoffForTarget(pre, root, diameter, target, tipCount) {
+        let values = [];
+        pre.forEach(function (n) {
+            if (!repIsTip(n)) {
+                values.push(diameter.get(n));
+            }
+        });
+        values.sort(function (a, b) { return a - b; });
+        let cand = [];
+        values.forEach(function (v) {
+            if (cand.length === 0 || v > cand[cand.length - 1] + REPRESENTATIVE_EPS) {
+                cand.push(v);
+            }
+        });
+        let count = function (cutoff) {
+            return repGroupRoots(root, diameter, cutoff).length;
+        };
+        let lo = 0;
+        let hi = cand.length - 1;
+        let boundary = cand.length - 1;
+        while (lo <= hi) {
+            let mid = (lo + hi) >>> 1;
+            if (count(cand[mid]) <= target) {
+                boundary = mid;
+                hi = mid - 1;
+            } else {
+                lo = mid + 1;
+            }
+        }
+        let tHigh = cand[boundary];
+        let cHigh = count(tHigh);
+        let tLow = boundary > 0 ? cand[boundary - 1] : -1;
+        let cLow = boundary > 0 ? count(tLow) : tipCount;
+        return (Math.abs(cLow - target) <= Math.abs(cHigh - target)) ? tLow : tHigh;
+    }
+
+    function repLongestBranch(members, topological) {
+        let best = members[0];
+        let bestLength = repEdge(best, topological);
+        for (let i = 1; i < members.length; ++i) {
+            let length = repEdge(members[i], topological);
+            if (length > bestLength + REPRESENTATIVE_EPS) {
+                best = members[i];
+                bestLength = length;
+            }
+        }
+        return best;
+    }
+
+    // The tip with the smallest summed distance to its group-mates, by the
+    // rerooting sum-of-distances recursion (linear, never all pairs): `down`
+    // sums the distances to the tips below a node, `up` to all the others.
+    function repMedoid(pre, members, topological) {
+        let tipsBelow = new Map();
+        let down = new Map();
+        for (let i = pre.length - 1; i >= 0; --i) {
+            let n = pre[i];
+            if (repIsTip(n)) {
+                tipsBelow.set(n, 1);
+                down.set(n, 0);
+                continue;
+            }
+            let s = 0;
+            let d = 0;
+            for (let c = 0; c < n.children.length; ++c) {
+                let child = n.children[c];
+                let e = repEdge(child, topological);
+                let cs = tipsBelow.get(child);
+                s += cs;
+                d += down.get(child) + (e * cs);
+            }
+            tipsBelow.set(n, s);
+            down.set(n, d);
+        }
+        let total = tipsBelow.get(pre[0]);
+        let up = new Map();
+        up.set(pre[0], 0);
+        pre.forEach(function (n) {
+            if (repIsTip(n)) {
+                return;
+            }
+            let un = up.get(n);
+            let dn = down.get(n);
+            for (let c = 0; c < n.children.length; ++c) {
+                let child = n.children[c];
+                let e = repEdge(child, topological);
+                let cs = tipsBelow.get(child);
+                up.set(child, un + dn - down.get(child) - (e * cs) + (e * (total - cs)));
+            }
+        });
+        let best = members[0];
+        let bestTotal = up.get(best);
+        for (let i = 1; i < members.length; ++i) {
+            let t = up.get(members[i]);
+            if (t < bestTotal - REPRESENTATIVE_EPS) {
+                best = members[i];
+                bestTotal = t;
+            }
+        }
+        return best;
+    }
+
+    /**
+     * Chooses representative tips: groups the tips into the maximal clades
+     * whose members are all within a distance of each other, and keeps one
+     * tip per group -- the desktop's Select Representative Tips.
+     *
+     * By `cutoff`, no two tips of a group are farther apart than it. By
+     * `target`, the cutoff is the one whose group count comes closest to that
+     * many (a tie keeps more); the count made is reported, since only certain
+     * counts are possible. Without branch lengths the distance counts edges.
+     *
+     * A protected tip is never dropped: it stands in for its group's
+     * representative, and a group with several keeps them all -- which can
+     * keep more tips than the target.
+     *
+     * The tree is not changed.
+     *
+     * @param phy the tree
+     * @param options {cutoff: number} or {target: integer}, with
+     *        pick: forester.REPRESENTATIVE_MEDOID (default, the most central
+     *        tip) or forester.REPRESENTATIVE_LONGEST_BRANCH (the most
+     *        divergent), and protectedTips: tips (nodes) never to drop
+     * @returns {{groups: Array, keptTips: Array, keptCount: number,
+     *          protectedKeptCount: number, tipCount: number,
+     *          effectiveCutoff: number, topological: boolean, pick: string,
+     *          requestedTarget: number, summary: string}}
+     *          groups: {clade, members, kept}, in tree order of their first
+     *          kept tip; requestedTarget is -1 for a cutoff
+     */
+    forester.selectRepresentativeTips = function (phy, options) {
+        let opts = options || {};
+        let root = phy ? forester.getTreeRoot(phy) : null;
+        if (!root) {
+            throw new Error('the tree is null or empty');
+        }
+        let byCutoff = opts.cutoff !== undefined;
+        if (byCutoff === (opts.target !== undefined)) {
+            throw new Error('give either a cutoff or a target');
+        }
+        if (byCutoff && (typeof opts.cutoff !== 'number' || !isFinite(opts.cutoff) || opts.cutoff < 0)) {
+            throw new Error('cutoff must be a finite, non-negative number');
+        }
+        if (!byCutoff && !(Number.isInteger(opts.target) && opts.target >= 1)) {
+            throw new Error('target number of representatives must be at least 1');
+        }
+        let pick = opts.pick === undefined ? forester.REPRESENTATIVE_MEDOID : opts.pick;
+        if (pick !== forester.REPRESENTATIVE_MEDOID && pick !== forester.REPRESENTATIVE_LONGEST_BRANCH) {
+            throw new Error('unknown representative pick: ' + pick);
+        }
+        let protectedTips = new Set(opts.protectedTips || []);
+
+        let pre = repPreorder(root);
+        let order = new Map();
+        pre.forEach(function (n, i) {
+            order.set(n, i);
+        });
+        let tips = pre.filter(repIsTip);
+        let topological = !forester.hasUsableBranchLengths(phy);
+        let diameter = repDiameters(pre, topological);
+        let groupRoots;
+        let effectiveCutoff;
+        if (byCutoff) {
+            groupRoots = repGroupRoots(root, diameter, opts.cutoff);
+            effectiveCutoff = opts.cutoff;
+        } else if (opts.target >= tips.length) {
+            groupRoots = tips;
+            effectiveCutoff = 0;
+        } else if (opts.target <= 1) {
+            groupRoots = [root];
+            effectiveCutoff = diameter.get(root);
+        } else {
+            let cutoff = repCutoffForTarget(pre, root, diameter, opts.target, tips.length);
+            groupRoots = repGroupRoots(root, diameter, cutoff);
+            effectiveCutoff = Math.max(0, cutoff);
+        }
+
+        let protectedKeptCount = 0;
+        let groups = groupRoots.map(function (clade) {
+            let sub = repPreorder(clade);
+            let members = sub.filter(repIsTip);
+            let kept = members.filter(function (m) {
+                return protectedTips.has(m);
+            });
+            if (kept.length > 0) {
+                protectedKeptCount += kept.length;
+            } else if (members.length === 1) {
+                kept = [members[0]];
+            } else if (pick === forester.REPRESENTATIVE_LONGEST_BRANCH) {
+                kept = [repLongestBranch(members, topological)];
+            } else {
+                kept = [repMedoid(sub, members, topological)];
+            }
+            return {clade: clade, members: members, kept: kept};
+        });
+        groups.sort(function (a, b) {
+            return order.get(a.kept[0]) - order.get(b.kept[0]);
+        });
+        let keptTips = [];
+        groups.forEach(function (g) {
+            g.kept.forEach(function (k) {
+                keptTips.push(k);
+            });
+        });
+        let result = {
+            groups: groups,
+            keptTips: keptTips,
+            keptCount: keptTips.length,
+            protectedKeptCount: protectedKeptCount,
+            tipCount: tips.length,
+            effectiveCutoff: effectiveCutoff,
+            topological: topological,
+            pick: pick,
+            requestedTarget: byCutoff ? -1 : opts.target
+        };
+        result.summary = representativeSummary(result);
+        return result;
+    };
+
+    // Java's Double.toString, which the desktop's texts print numbers with:
+    // the shortest digits that read back as the number (as JS's), but always
+    // with a fraction ("1.0"), and in E notation outside [0.001, 10^7).
+    function javaDoubleText(d) {
+        if (d === 0) {
+            return (1 / d < 0) ? '-0.0' : '0.0';
+        }
+        if (!isFinite(d)) {
+            return String(d);
+        }
+        let a = Math.abs(d);
+        if (a >= 1e-3 && a < 1e7) {
+            let s = String(d);
+            return s.indexOf('.') < 0 ? s + '.0' : s;
+        }
+        let e = d.toExponential();
+        let i = e.indexOf('e');
+        let mantissa = e.slice(0, i);
+        return (mantissa.indexOf('.') < 0 ? mantissa + '.0' : mantissa) + 'E' + e.slice(i + 1).replace('+', '');
+    }
+
+    // a distance to five decimals, a whole number without its fraction
+    function representativeDistanceText(d) {
+        let r = Math.round(d * 1e5) / 1e5;
+        return (r === Math.round(r)) ? String(r) : javaDoubleText(r);
+    }
+
+    function representativeSummary(result) {
+        let groups = result.groups.length;
+        let s = 'Grouped ' + result.tipCount + (result.tipCount === 1 ? ' tip' : ' tips')
+            + ' into ' + groups + (groups === 1 ? ' group.' : ' groups.');
+        if (result.requestedTarget > 0 && groups !== result.requestedTarget) {
+            s += ' (requested ' + result.requestedTarget + ')';
+        }
+        s += '\nEach group\'s tips are within a distance of ' + representativeDistanceText(result.effectiveCutoff)
+            + ' of each other';
+        if (result.topological) {
+            s += ' (topological distance — the tree has no branch lengths)';
+        }
+        s += '.';
+        if (result.protectedKeptCount > 0) {
+            s += '\nKeeping ' + result.keptCount + (result.keptCount === 1 ? ' tip, including ' : ' tips, including ')
+                + result.protectedKeptCount
+                + (result.protectedKeptCount === 1 ? ' selected tip protected from removal.'
+                    : ' selected tips protected from removal.');
+        }
+        s += '\nRepresentative per group: '
+            + (result.pick === forester.REPRESENTATIVE_LONGEST_BRANCH ? 'most divergent (longest branch)'
+                : 'most central (medoid)') + '.';
+        return s;
+    }
+
+    // a copy of a node's own data (never its children or parent link)
+    function repCopyData(v) {
+        if (Array.isArray(v)) {
+            return v.map(repCopyData);
+        }
+        if (v !== null && typeof v === 'object') {
+            let o = {};
+            Object.keys(v).forEach(function (k) {
+                if (k !== 'parent' && k !== 'children') {
+                    o[k] = repCopyData(v[k]);
+                }
+            });
+            return o;
+        }
+        return v;
+    }
+
+    /**
+     * A copy of the tree holding only the given tips, pruned as the desktop
+     * prunes (Phylogeny.deleteSubtree): a node left with one child is
+     * replaced by that child, whose branch gains the node's length (a missing
+     * or negative length adds nothing; two of them leave the length missing);
+     * a root left with one child is replaced by it. The new root keeps the
+     * original root's own branch length (normally none), where the desktop's
+     * depends on the order it deletes in. The tree is not changed.
+     *
+     * @param phy the tree
+     * @param keep the tips to keep (nodes of phy), at least one
+     * @returns the copy, with every node's data copied
+     */
+    forester.copyTreeKeepingTips = function (phy, keep) {
+        let keepSet = new Set(keep);
+        let top = phy.children && phy.children.length === 1 && !phy.parent ? phy : {children: [phy]};
+        let copies = new Map();
+        let copyTop = repCopyData(top === phy ? phy : {});
+        copies.set(top, copyTop);
+        let stack = [top];
+        while (stack.length > 0) {
+            let n = stack.pop();
+            if (n.children) {
+                copies.get(n).children = n.children.map(function (child) {
+                    let cc = repCopyData(child);
+                    copies.set(child, cc);
+                    stack.push(child);
+                    return cc;
+                });
+            }
+        }
+        let tips = repPreorder(top).filter(function (n) {
+            return n !== top && repIsTip(n);
+        });
+        let dropped = tips.filter(function (n) {
+            return !keepSet.has(n);
+        });
+        if (dropped.length === tips.length) {
+            throw new Error('at least one tip must be kept');
+        }
+        let parentOf = new Map();
+        stack = [copyTop];
+        while (stack.length > 0) {
+            let n = stack.pop();
+            (n.children || []).forEach(function (child) {
+                parentOf.set(child, n);
+                stack.push(child);
+            });
+        }
+        let add = function (a, b) {
+            let okA = typeof a === 'number' && a >= 0;
+            let okB = typeof b === 'number' && b >= 0;
+            return (okA && okB) ? a + b : (okA ? a : (okB ? b : undefined));
+        };
+        dropped.forEach(function (tip) {
+            let t = copies.get(tip);
+            let p = parentOf.get(t);
+            let i = p.children.indexOf(t);
+            if (parentOf.get(p) === copyTop) {
+                if (p.children.length === 2) {
+                    let other = p.children[1 - i];
+                    copyTop.children[0] = other;
+                    parentOf.set(other, copyTop);
+                } else {
+                    p.children.splice(i, 1);
+                }
+            } else {
+                let pp = parentOf.get(p);
+                if (p.children.length === 2) {
+                    let other = p.children[1 - i];
+                    let length = add(p.branch_length, other.branch_length);
+                    if (length === undefined) {
+                        delete other.branch_length;
+                    } else {
+                        other.branch_length = length;
+                    }
+                    pp.children[pp.children.indexOf(p)] = other;
+                    parentOf.set(other, pp);
+                } else {
+                    p.children.splice(i, 1);
+                }
+            }
+            if (p.children.length === 0) {
+                delete p.children;
+            }
+        });
+        // The root keeps the original root's own branch length, normally
+        // none. What the desktop's pruning leaves there depends on the order
+        // it deletes tips in -- that is, on node ids -- so the same selection
+        // gave 0.05 in one session and 0.25 in another (Christian, 2026-09-15).
+        let rootLength = top.children[0].branch_length;
+        if (typeof rootLength === 'number') {
+            copyTop.children[0].branch_length = rootLength;
+        } else {
+            delete copyTop.children[0].branch_length;
+        }
+        return copyTop;
+    };
+
+    /**
+     * Strips a file-type suffix -- a dot and 1 to 5 other characters, such as
+     * .xml or .nexus -- from a tree name, as the desktop does.
+     *
+     * @param name
+     * @returns {string|null}
+     */
+    forester.stripShortExtension = function (name) {
+        return (name === null || name === undefined) ? null : String(name).replace(/\.[^.]{1,5}$/, '');
+    };
+
+    /**
+     * The desktop's name for a tree of representative tips: the parent's name
+     * without its file suffix, then the count -- mammals_233reps, _1rep --
+     * or "tree" for an unnamed parent.
+     *
+     * @param parentName
+     * @param count
+     * @returns {string}
+     */
+    forester.representativeTreeName = function (parentName, count) {
+        let stripped = forester.stripShortExtension(parentName);
+        return (stripped ? stripped : 'tree') + '_' + count + (count === 1 ? 'rep' : 'reps');
+    };
+
+    /**
+     * The desktop's provenance sentence for a tree of representative tips,
+     * which it adds to the tree's description.
+     *
+     * @param byCutoff true for a cutoff, false for a target
+     * @param cutoff
+     * @param target
+     * @param pick forester.REPRESENTATIVE_MEDOID or _LONGEST_BRANCH
+     * @param count tips kept
+     * @param parentName
+     * @param parentTipCount
+     * @returns {string}
+     */
+    forester.representativeTreeDescription = function (byCutoff, cutoff, target, pick, count, parentName, parentTipCount) {
+        let pickText = pick === forester.REPRESENTATIVE_LONGEST_BRANCH ? 'longest-branch' : 'medoid';
+        let algorithm = byCutoff
+            ? 'distance-cutoff (maximum distance ' + javaDoubleText(cutoff) + ', ' + pickText + ' representative)'
+            : 'target-count (target ' + target + ', ' + pickText + ' representative)';
+        return 'Used the ' + algorithm + ' algorithm to select ' + count + ' representative '
+            + (count === 1 ? 'tip' : 'tips') + ' from tree named "' + (parentName ? parentName : 'tree') + '" with '
+            + parentTipCount + (parentTipCount === 1 ? ' tip.' : ' tips.');
+    };
+
     /**
      * Whether a node carries data about the node itself, the kind a
      * re-rooting can take the meaning away from: a name, taxonomy, sequence
@@ -2526,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: []};
@@ -2551,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;
@@ -2610,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 === '[') {
@@ -2648,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.
@@ -2659,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;
         }
@@ -2721,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
@@ -2734,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;
@@ -2761,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') {
@@ -2776,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);
             }
@@ -2787,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
@@ -2816,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;
@@ -2850,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';
@@ -3087,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) {
@@ -3222,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);
@@ -3386,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
@@ -3418,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) {
@@ -3540,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;
@@ -3577,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 === ';') {
@@ -3689,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;
         }
@@ -3700,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'
         });
     }
@@ -3708,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;
@@ -3727,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)');
         }
 
@@ -3836,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;
     };