archaeopteryx 3.16.0 → 3.18.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.16.0
+// v 3.18.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -225,17 +225,89 @@
                 throw ("this should never have happened, child node index = " + cni);
             }
             let x = p.children[0];
-            let nbl = undefined;
-            if (x.branch_length || p.branch_length) {
-                nbl = (x.branch_length > 0 ? x.branch_length : 0) + (p.branch_length > 0 ? p.branch_length : 0);
+            let stated = function (v) {
+                return typeof v === 'number' && isFinite(v);
+            };
+            // What the merged branch is made of, for a clock-model tree's
+            // divergence: each piece's span in time and the rate its node
+            // stated, kept on x (see divergenceOfPieces). A removed node's
+            // rate goes on scaling its own piece, as the desktop keeps it.
+            let showsDiv = statesDivergenceUnit(phy);
+            let root = forester.getTreeRoot(phy);
+            let pieceOf = function (n) {
+                if (Array.isArray(n._pieces)) {
+                    return n._pieces;
+                }
+                let span = null;
+                if (stated(n._timeLength)) {
+                    span = n._timeLength;
+                } else if (showsDiv) {
+                    let d = auspiceNodeDate(n);
+                    let pd = auspiceNodeDate(n.parent);
+                    span = (d !== null && pd !== null) ? timeGapOf(root)(d, pd) : null;
+                } else if (stated(n.branch_length)) {
+                    span = n.branch_length;
+                }
+                return span === null ? null : [{span: span, rate: clockRateOf(n)}];
+            };
+            let xs = pieceOf(x);
+            let ps = pieceOf(p);
+            let pieces = (xs && ps) ? xs.concat(ps) : null;
+            // The two lengths add up, sign and all: a stated 0 is a length (a
+            // truthiness test once turned two zeros into no length at all),
+            // and a negative span stays a negative span, so that a node keeps
+            // its date. One length stated and one not: the one stated.
+            let nbl = (stated(x.branch_length) && stated(p.branch_length)) ? (x.branch_length + p.branch_length)
+                : (stated(x.branch_length) ? x.branch_length : (stated(p.branch_length) ? p.branch_length : undefined));
+            // The length kept for the Time | Div switch goes with the branch
+            // the same way: x now spans, in time, what it and the node removed
+            // above it spanned. Left as it was, x came back from Div short by
+            // its parent's length (0.65 years on a real Nextstrain build). A
+            // length not kept for either leaves x with none.
+            if (Object.prototype.hasOwnProperty.call(x, '_timeLength')
+                || Object.prototype.hasOwnProperty.call(p, '_timeLength')) {
+                x._timeLength = (stated(x._timeLength) && stated(p._timeLength))
+                    ? (x._timeLength + p._timeLength) : undefined;
             }
             x.parent = pp;
             pp.children[cni] = x;
             x.branch_length = nbl;
+            if (pieces) {
+                x._pieces = pieces;
+            } else {
+                delete x._pieces;
+            }
+            // On a captured clock-model tree the cumulative divergence of x,
+            // and of everything under it, moves by what the merged branch's
+            // divergence is now against what x's was.
+            if (pieces && stated(x._divergence) && stated(pp._divergence)) {
+                let own = clockRateOf(x);
+                if (own !== null) {
+                    let shift = (pp._divergence + divergenceOfPieces(pieces, own)) - x._divergence;
+                    if (shift !== 0) {
+                        forester.preOrderTraversalAll(x, function (n) {
+                            n._divergence += shift;
+                        });
+                    }
+                }
+            }
         }
 
     };
 
+    // The divergence along a branch made of pieces (see forester.deleteSubtree):
+    // each piece's span, where it is positive, times the rate its node stated,
+    // or the surviving node's where it stated none. Clamped piece by piece,
+    // as each was when it was a branch of its own, so that deleting a node
+    // moves nobody in Div.
+    function divergenceOfPieces(pieces, ownRate) {
+        let sum = 0;
+        for (let i = 0; i < pieces.length; ++i) {
+            let r = (pieces[i].rate === null || pieces[i].rate === undefined) ? ownRate : pieces[i].rate;
+            sum += Math.max(0, pieces[i].span) * r;
+        }
+        return sum;
+    }
 
     /**
      * To re-root a tree object.
@@ -6388,13 +6460,22 @@
         if (typeof title === 'string' && title.trim().length > 0) {
             phy.name = title.trim();
         }
-        if (auspiceHasAnyDate(root)) {
-            setDeltaBranchLengths(root, null, auspiceNodeDate); // default view = time
+        // A build has no branch lengths of its own, so it opens in the metric
+        // it states COMPLETELY: time when every node states num_date, else
+        // divergence when every node states div, else as it always did (time
+        // if any node is dated, divergence if none is). Joint with the
+        // desktop, 2026-09-29. A num_date is a calendar year, so the gap is
+        // child minus parent, and it keeps its sign.
+        let opensInTime = everyNodeStates(root, auspiceNodeDate)
+            || (!everyNodeStates(root, recordedDiv) && auspiceHasAnyDate(root));
+        if (opensInTime) {
+            setDeltaBranchLengths(root, null, auspiceNodeDate, calendarGap);
         } else {
-            // a divergence-only build carries no num_date anywhere; div deltas
-            // keep the layout meaningful instead of a cladogram
-            setDeltaBranchLengths(root, null, auspiceNodeDiv);
+            setDeltaBranchLengths(root, null, recordedDiv, divergenceGap);
         }
+        // ...and says which, as the desktop's reader does: a saved copy then
+        // states what its branch lengths measure
+        phy.branch_length_unit = opensInTime ? CALENDAR_LENGTH_UNIT : DIVERGENCE_LENGTH_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
@@ -6409,38 +6490,57 @@
             ? node.date.value : null;
     }
 
-    // A node's CUMULATIVE divergence from the root. Auspice states it outright
-    // as nextstrain:div; every other tree states it as branch lengths, which
-    // are the same thing in difference form, so it is summed at load and kept
-    // on the node (see forester.captureDivergence). The property wins where it
-    // exists, so an Auspice tree behaves exactly as it always did.
-    function auspiceNodeDiv(node) {
+    // The divergence a node RECORDS (nextstrain:div), or null. A plain decimal
+    // number and nothing else (parseBeastNumber), as a clock rate is: every
+    // number the switch reads is read one way, on both programs. parseFloat
+    // read one out of the front of "0.005abc", "1,5" and "0x10" -- which the
+    // Nexus reader had never let through, so the same value was a divergence
+    // in a phyloXML file and none in a Nexus one. A NEGATIVE one is a value;
+    // the branch along which it falls is drawn at 0 (divergenceGap).
+    // Christian, 2026-09-29.
+    function recordedDiv(node) {
         if (node.properties) {
             for (let i = 0; i < node.properties.length; ++i) {
                 if (node.properties[i].ref === NEXTSTRAIN_PREFIX + 'div') {
-                    let d = parseFloat(node.properties[i].value);
-                    return isFinite(d) ? d : null;
+                    return parseBeastNumber(node.properties[i].value);
                 }
             }
         }
-        return (typeof node._divergence === 'number' && isFinite(node._divergence))
-            ? node._divergence : null;
+        return null;
     }
 
-    function auspiceHasAnyDate(node) {
+    function recordsDivergence(root) {
         let found = false;
-        forester.preOrderTraversalAll(node, function (n) {
-            if (auspiceNodeDate(n) !== null) {
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!found && recordedDiv(n) !== null) {
                 found = true;
             }
         });
         return found;
     }
 
-    function auspiceHasAnyDiv(node) {
+    // A node's CUMULATIVE divergence from the root. Auspice states it outright
+    // as nextstrain:div; a BEAST clock-model tree states it as branch length
+    // x rate, summed at load and kept on the node (see forester.
+    // captureDivergence). A tree states it ONE way: where any node records a
+    // divergence nothing is captured, so a node that records none has none.
+    // Until 2026-09-29 such a node fell back to the sum of the loaded lengths,
+    // which on an Auspice tree are YEARS -- a tip whose div of 0.0008 was
+    // missing drew its branch at 0.2794, where the file's own numbers said
+    // 0.0002.
+    function auspiceNodeDiv(node) {
+        let d = recordedDiv(node);
+        if (d !== null) {
+            return d;
+        }
+        return (typeof node._divergence === 'number' && isFinite(node._divergence))
+            ? node._divergence : null;
+    }
+
+    function auspiceHasAnyDate(node) {
         let found = false;
         forester.preOrderTraversalAll(node, function (n) {
-            if (auspiceNodeDiv(n) !== null) {
+            if (auspiceNodeDate(n) !== null) {
                 found = true;
             }
         });
@@ -6451,42 +6551,209 @@
     // (num_date -> the time view; nextstrain:div -> the divergence view).
     // The root's length is 0, and a node missing the metric (or whose parent
     // misses it) gets 0 -- so a time<->divergence toggle can never leave a
-    // stale cross-scale length behind. A (spurious) negative delta clamps to 0.
-    function setDeltaBranchLengths(node, parentValue, metricOf) {
+    // stale cross-scale length behind.
+    function setDeltaBranchLengths(node, parentValue, metricOf, gapOf) {
         let v = metricOf(node);
-        node.branch_length = (parentValue !== null && v !== null)
-            ? Math.max(0, v - parentValue) : 0;
+        node.branch_length = (parentValue !== null && v !== null) ? gapOf(v, parentValue) : 0;
         let children = node.children;
         if (children) {
             for (let i = 0; i < children.length; ++i) {
-                setDeltaBranchLengths(children[i], v, metricOf);
+                setDeltaBranchLengths(children[i], v, metricOf, gapOf);
             }
         }
     }
 
+    // A TIME gap keeps its sign. A child dated before its parent is what the
+    // file states -- real Nextstrain builds state it (42 branches in 4 of 11,
+    // one of them by 4.09 years) -- so the length is negative and every node
+    // keeps its own date. Clamped at 0 until 2026-09-29, which also made the
+    // switch lossy: a time tree stating negative lengths came back from Div
+    // with 0 in their place. (A negative length is DRAWN at 0, as it always
+    // was and as the desktop draws it; this is about the value.)
+    function calendarGap(v, parentValue) {
+        return v - parentValue;
+    }
+
+    function ageGap(v, parentValue) {
+        return parentValue - v;
+    }
+
+    // In the direction the tree's dates run: calendar dates increase toward
+    // the tips, ages (a height) toward the root. As the desktop measures it.
+    function timeGapOf(root) {
+        return timeIncreasesTowardTips(root) ? calendarGap : ageGap;
+    }
+
+    // Divergence accumulates: a node recording less than its parent is noise,
+    // not a branch running backwards, and draws at 0.
+    function divergenceGap(v, parentValue) {
+        return Math.max(0, v - parentValue);
+    }
+
     // The time<->divergence plumbing: both metrics are RETAINED on a parsed
     // Auspice tree (the date values + the nextstrain:div properties), so a
     // future display toggle can rewrite the branch lengths from EITHER at any
     // time -- lossless and reversible, and reusing the exact recompute the
     // parser itself used, so the toggle can never drift from the loaded view.
 
+    // Both leave the tree exactly as it was, and answer false, when their
+    // layout cannot state every branch: a branch drawn at 0 because a datum is
+    // MISSING says "nothing happened along this branch", which the file never
+    // said. A datum that is stated is stated, whether zero or negative.
+
+    // What a tree's branch lengths MEASURE is stated on the tree (phyloXML's
+    // branch_length_unit), and each layout stamps its own: the scale bar, the
+    // tree's properties and a saved file then all say the same. Divergence is
+    // in substitutions per site; time is in the unit of the tree's own dates,
+    // or plainly "time" where they state none (BEAST heights). The desktop's
+    // words, byte for byte (BranchLengthLayout.distanceUnit).
+    //
+    // It is also how a clock-model tree saved from the Div view is known for
+    // what it is when it is opened again (see captureDivergence).
+    const DIVERGENCE_LENGTH_UNIT = 'subs/site';
+    const CALENDAR_LENGTH_UNIT = 'year';
+    const PLAIN_TIME_LENGTH_UNIT = 'time';
+
+    // The unit of the first dated node that states one, in preorder, children
+    // in file order; null where none does.
+    function dateUnitOf(root) {
+        let unit = null;
+        (function walk(n) {
+            if (unit !== null) {
+                return;
+            }
+            if (n.date && typeof n.date.unit === 'string' && n.date.unit.trim().length > 0) {
+                unit = n.date.unit.trim();
+                return;
+            }
+            let children = n.children;
+            if (children) {
+                for (let i = 0; i < children.length; ++i) {
+                    walk(children[i]);
+                }
+            }
+        }(root));
+        return unit;
+    }
+
+    // `phy` may be the tree or its root; only the tree carries a unit.
+    function stampLengthUnit(phy, root, unit) {
+        if (phy && phy !== root && typeof phy === 'object') {
+            phy.branch_length_unit = unit;
+        }
+    }
+
+    function statesDivergenceUnit(phy) {
+        return !!phy && typeof phy.branch_length_unit === 'string'
+            && phy.branch_length_unit.trim() === DIVERGENCE_LENGTH_UNIT;
+    }
+
+    // Back in TIME a tree gets the lengths it had in time: the ones it
+    // arrived with, kept at load (see captureDivergence). So a file's own
+    // lengths are what is shown, to the digit, where they and its node dates
+    // disagree (carnivore.tree: 1.407 stated on a branch whose two heights are
+    // 1.098 apart). Joint with the desktop (Christian, 2026-09-29). A tree that
+    // kept none -- it did not arrive in time -- is laid out by its date gaps.
     forester.applyTimeBranchLengths = function (phy) {
-        setDeltaBranchLengths(forester.getTreeRoot(phy), null, auspiceNodeDate);
+        let root = forester.getTreeRoot(phy);
+        if (root && root._timeLengthsKept === true) {
+            if (!everyLengthWasStated(root)) {
+                return false;    // a branch with no kept length: nothing to give back
+            }
+            forester.preOrderTraversalAll(root, function (n) {
+                if (n !== root) {    // the root has no branch, and no layout touches what it states
+                    n.branch_length = n._timeLength;
+                }
+            });
+            stampLengthUnit(phy, root, dateUnitOf(root) || PLAIN_TIME_LENGTH_UNIT);
+            return true;
+        }
+        if (!root || !everyNodeStates(root, auspiceNodeDate)) {
+            return false;
+        }
+        layOutBelowRoot(root, auspiceNodeDate, timeGapOf(root));
+        stampLengthUnit(phy, root, dateUnitOf(root) || PLAIN_TIME_LENGTH_UNIT);
+        return true;
     };
 
     forester.applyDivergenceBranchLengths = function (phy) {
-        setDeltaBranchLengths(forester.getTreeRoot(phy), null, auspiceNodeDiv);
+        let root = forester.getTreeRoot(phy);
+        if (!root || !divergenceStatesEveryBranch(root)) {
+            return false;
+        }
+        layOutBelowRoot(root, auspiceNodeDiv, divergenceGap);
+        stampLengthUnit(phy, root, DIVERGENCE_LENGTH_UNIT);
+        return true;
     };
 
+    // The root has no branch to lay out: it keeps the length it has, or none.
+    // Given a length of 0 by the switch, a tree saved from Div stated a root
+    // branch its file never had, and the desktop's copy of it did not.
+    function layOutBelowRoot(root, metricOf, gapOf) {
+        let had = Object.prototype.hasOwnProperty.call(root, 'branch_length');
+        let length = root.branch_length;
+        setDeltaBranchLengths(root, null, metricOf, gapOf);
+        if (had) {
+            root.branch_length = length;
+        } else {
+            delete root.branch_length;
+        }
+    }
+
+    function everyNodeStates(root, metricOf) {
+        let every = true;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (every && metricOf(n) === null) {
+                every = false;
+            }
+        });
+        return every;
+    }
+
+    // Recorded on every node (the root too: it is the parent its children are
+    // measured from), or derived from a clock rate on every branch and a
+    // length every one of which the file stated. A tree with neither has no
+    // divergence to lay out: its branch lengths are what they are.
+    function divergenceStatesEveryBranch(root) {
+        if (recordsDivergence(root)) {
+            return everyNodeStates(root, recordedDiv);
+        }
+        return root._divergenceFromRates === true && root._everyLengthStated === true;
+    }
+
+    // Asked at load where it was (captureDivergence): once the switch has been
+    // pressed every branch has a length, whatever the file stated.
+    function everyLengthWasStated(root) {
+        return (root._everyLengthStated === undefined) ? everyBranchStatesLength(root)
+            : (root._everyLengthStated === true);
+    }
+
     /**
-     * Records each node's cumulative divergence from the root, summed from the
-     * branch lengths AS LOADED, so the divergence view survives the time view
-     * overwriting `branch_length`. Kept in `_divergence`, which is private:
-     * no writer emits it, and a re-read of our own output re-derives it.
+     * Keeps, at load, what the Time | Div switch needs to be lossless:
+     *
+     * - the branch lengths the tree ARRIVED with, where they are its time
+     *   (`_timeLength`): on a BEAST clock-model tree always, and on a tree
+     *   recording its divergence when its lengths are its date gaps. Back in
+     *   Time the tree gets exactly these;
+     * - on a clock-model tree -- a clock rate on every branch -- each node's
+     *   cumulative divergence from the root (`_divergence`), summed from
+     *   those lengths times each branch's rate.
+     *
+     * Both are private: no writer emits them, and a re-read of our own output
+     * re-derives them. Nothing is kept on a tree with neither a recorded
+     * divergence nor rates: it has no second layout, and the switch is never
+     * offered on it.
      *
-     * A tree whose branch lengths ARE its dates (an Auspice time tree, say)
-     * gets the snapshot too; it is `hasTimeAndDivergence` that decides whether
-     * the two views differ enough to be worth offering.
+     * A tree may ARRIVE showing divergence: it was saved while Div was on
+     * screen. One that records its divergence is known by its lengths, which
+     * are not its date gaps. A clock-model tree is known by what it states --
+     * the unit of its branch lengths is the one the divergence layout stamps
+     * -- since its lengths are not its date gaps even in time. Such a tree
+     * keeps no time lengths (it carries none): its time is laid out from its
+     * dates, and its divergence is each rate times that. Until 2026-09-29 a
+     * clock-model tree's lengths were taken for its time whatever they were,
+     * and one saved from Div came back labelled Time, with a Div of rate x
+     * divergence. Joint with the desktop.
      *
      * Call once per tree at load, before anything rewrites a branch length.
      *
@@ -6497,77 +6764,152 @@
         if (!root) {
             return;
         }
+        root._divergenceFromRates = false;
+        root._timeLengthsKept = false;
+        root._everyLengthStated = everyBranchStatesLength(root);
+        // A tree that RECORDS its divergence states it that way and no other:
+        // none is derived beside it, so a node that records none has none (see
+        // auspiceNodeDiv).
+        let recorded = recordsDivergence(root);
+        // A BEAST clock-model tree states its branch lengths in TIME and each
+        // branch's clock rate beside it, so its divergence is length x rate
+        // (substitutions per site). Only when EVERY branch states a rate: a
+        // partial one would mix substitutions with years along a path.
+        let rates = recorded ? null : everyBranchClockRate(root);
+        if (!recorded && rates === null) {
+            return;
+        }
+        let showsDivergence = rates !== null && statesDivergenceUnit(phy);
+        let keep = (rates !== null && !showsDivergence) || (recorded && branchLengthsAreTime(root));
+        let gapOf = showsDivergence ? timeGapOf(root) : null;
         (function walk(node, cumulative) {
-            node._divergence = cumulative;
+            if (keep) {
+                node._timeLength = node.branch_length;
+            }
+            if (rates) {
+                node._divergence = cumulative;
+            }
             let children = node.children;
             if (children) {
                 for (let i = 0; i < children.length; ++i) {
-                    let bl = children[i].branch_length;
-                    let step = (typeof bl === 'number' && isFinite(bl) && bl > 0) ? bl : 0;
+                    // the branch's time: the length it arrived with, or, on
+                    // a tree that arrived showing divergence, its date gap
+                    let span = children[i].branch_length;
+                    if (gapOf) {
+                        let d = auspiceNodeDate(children[i]);
+                        let pd = auspiceNodeDate(node);
+                        span = (d !== null && pd !== null) ? gapOf(d, pd) : 0;
+                    }
+                    // a span of 0, or a negative one, adds no divergence; a
+                    // branch made of pieces (a node deleted above it) adds
+                    // each piece's
+                    let step = 0;
+                    if (rates && Array.isArray(children[i]._pieces)) {
+                        step = divergenceOfPieces(children[i]._pieces, rates.get(children[i]));
+                    } else if (rates && typeof span === 'number' && isFinite(span) && span > 0) {
+                        step = span * rates.get(children[i]);
+                    }
                     walk(children[i], cumulative + step);
                 }
             }
         }(root, 0));
+        root._divergenceFromRates = rates !== null;
+        root._timeLengthsKept = keep;
     };
 
-    // How much the tree's SHAPE would change between the two metrics, as a
-    // fraction of its width: each tip's distance from the root under each
-    // metric, normalised by the deepest tip, and the largest disagreement.
+    // A length of 0, or a negative one, is a length the file stated; one that
+    // is not there is not.
+    function everyBranchStatesLength(root) {
+        let every = true;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (every && n !== root && !(typeof n.branch_length === 'number' && isFinite(n.branch_length))) {
+                every = false;
+            }
+        });
+        return every;
+    }
+
+    // A node's BEAST clock rate (the `rate` annotation) as everyBranchClockRate
+    // reads it: a plain decimal, not negative; else null.
+    function clockRateOf(n) {
+        if (n.properties) {
+            for (let i = 0; i < n.properties.length; ++i) {
+                if (n.properties[i].ref === BEAST_PREFIX + 'rate') {
+                    let r = parseBeastNumber(n.properties[i].value);
+                    return (r === null || r < 0) ? null : r;
+                }
+            }
+        }
+        return null;
+    }
+
+    // Each non-root node's BEAST clock rate (the `rate` annotation), or null
+    // unless every branch states a finite, non-negative one. A rate is a plain
+    // decimal number and nothing else (parseBeastNumber): parseFloat reads a
+    // number out of the front of "0.01abc" or "1,5", and a rate nobody wrote
+    // would then scale a branch.
+    function everyBranchClockRate(root) {
+        let rates = new Map();
+        let ok = true;
+        let branches = 0;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!ok || n === root) {
+                return;
+            }
+            ++branches;
+            let r = null;
+            if (n.properties) {
+                for (let i = 0; i < n.properties.length; ++i) {
+                    if (n.properties[i].ref === BEAST_PREFIX + 'rate') {
+                        r = parseBeastNumber(n.properties[i].value);
+                        break;
+                    }
+                }
+            }
+            if (r === null || r < 0) {
+                ok = false;
+                return;
+            }
+            rates.set(n, r);
+        });
+        return (ok && branches > 0) ? rates : null;
+    }
+
+    // Whether each picture has any DEPTH: some tip away from the root, in
+    // time and in divergence. A tree whose tips all carry the root's date has
+    // no time picture, and one whose divergence is 0 on every branch (every
+    // rate 0, say) has no divergence picture: a switch to a tree drawn as a
+    // point is not offered. Joint with the desktop (Christian, 2026-09-29:
+    // "Always offer; refuse only zero").
     //
-    // Comparing branch lengths PAIR BY PAIR is the wrong question and gave the
-    // wrong answer: on influenza.tree the branch lengths differ from the date
-    // gaps by a median of 7% per branch, which looks like a separate measure,
-    // but the differences cancel along every path and all 687 tips land within
-    // 0.3% of where the other metric puts them. Its branch lengths ARE time --
-    // a BEAST time tree states time -- so a toggle would redraw one picture
-    // twice. A real Nextstrain build, where divergence is genuinely a
-    // different measurement, moves tips by 24.8% of the tree's width.
+    // Until then the switch was offered only where the two pictures differed
+    // by more than 2% of the tree's width at some tip, which refused a strict
+    // clock, whose divergence is its time rescaled. One rule for both
+    // programs replaced a threshold both would have had to justify.
     //
     // Both metrics are read WITHOUT touching branch_length, so this can be
-    // asked at load without disturbing the tree.
-    function layoutShiftBetweenMetrics(root) {
+    // asked at load without disturbing the tree. Depth is taken at the tips,
+    // summed along the path as the layout would draw it.
+    function bothPicturesHaveDepth(root) {
         let rootDate = auspiceNodeDate(root);
-        let time = [];
-        let div = [];
-        let ok = true;
-        (function walk(n, t, d) {
-            let nt = auspiceNodeDate(n);
+        let timeDepth = 0;
+        let divDepth = 0;
+        (function walk(n, parentDiv, d) {
             let nd = auspiceNodeDiv(n);
-            let tHere = (nt !== null && rootDate !== null) ? Math.abs(nt - rootDate) : t;
-            let dHere = (nd !== null) ? nd : d;
+            let dHere = (n === root || nd === null || parentDiv === null) ? d : (d + divergenceGap(nd, parentDiv));
             if (!n.children || n.children.length === 0) {
-                if (nt === null || nd === null) {
-                    ok = false;
+                let nt = auspiceNodeDate(n);
+                if (nt !== null && rootDate !== null) {
+                    timeDepth = Math.max(timeDepth, Math.abs(nt - rootDate));
                 }
-                time.push(tHere);
-                div.push(dHere);
+                divDepth = Math.max(divDepth, dHere);
                 return;
             }
             for (let i = 0; i < n.children.length; ++i) {
-                walk(n.children[i], tHere, dHere);
+                walk(n.children[i], nd, dHere);
             }
-        }(root, 0, 0));
-        if (!ok || time.length === 0) {
-            return 0;
-        }
-        let tMax = Math.max.apply(null, time.length > 50000 ? time.slice(0, 50000) : time);
-        let dMax = Math.max.apply(null, div.length > 50000 ? div.slice(0, 50000) : div);
-        if (!(tMax > 0) || !(dMax > 0)) {
-            return 0;
-        }
-        let worst = 0;
-        for (let i = 0; i < time.length; ++i) {
-            worst = Math.max(worst, Math.abs((time[i] / tMax) - (div[i] / dMax)));
-        }
-        return worst;
-    }
-
-    // Below this the two views are the same picture and the switch is noise.
-    // influenza.tree measures 0.003, nextstrain-ncov.json 0.248.
-    const BRANCH_METRIC_SHIFT_MIN = 0.02;
-
-    function divergenceDiffersFromTime(root) {
-        return layoutShiftBetweenMetrics(root) > BRANCH_METRIC_SHIFT_MIN;
+        }(root, null, 0));
+        return timeDepth > 0 && divDepth > 0;
     }
 
     // Which metric the CURRENT branch lengths hold -- a different question
@@ -6578,6 +6920,7 @@
     function branchLengthsAreTime(root) {
         let pairs = 0;
         let same = 0;
+        let gapOf = timeGapOf(root);
         forester.preOrderTraversalAll(root, function (n) {
             if (!n.children) {
                 return;
@@ -6594,8 +6937,11 @@
                     continue;
                 }
                 ++pairs;
-                let scale = Math.max(Math.abs(bl), Math.abs(cv - pv), 1e-9);
-                if (Math.abs(Math.abs(cv - pv) - bl) <= (scale * 1e-6)) {
+                // signed, as the time view writes it: a length the file
+                // states negative is its date gap too
+                let gap = gapOf(cv, pv);
+                let scale = Math.max(Math.abs(bl), Math.abs(gap), 1e-9);
+                if (Math.abs(gap - bl) <= (scale * 1e-6)) {
                     ++same;
                 }
             }
@@ -6603,13 +6949,14 @@
         return pairs > 0 && (same * 20) >= (pairs * 19);
     }
 
-    // Whether the dates run the way the time view needs them to: a CALENDAR
-    // date increases toward the tips, and setDeltaBranchLengths takes
-    // child - parent and clamps at 0. A BEAST height runs the other way -- it
-    // is an age, largest at the root -- so a tree still stating heights would
-    // get a branch length of 0 everywhere and collapse to a point. Measured,
-    // not assumed: forester.convertHeightsToDates turns heights into calendar
-    // dates, and a tree it REFUSED still states ages.
+    // Which way the tree's dates run: a CALENDAR date increases toward the
+    // tips; a BEAST height runs the other way -- it is an age, largest at the
+    // root. Measured, not assumed, by the majority of the parent-child pairs
+    // that differ (a tie, or none, reads as ages): forester.
+    // convertHeightsToDates turns heights into calendar dates, and a tree it
+    // REFUSED still states ages. The time view takes its gaps in this
+    // direction (timeGapOf), so the few pairs that run AGAINST it come out
+    // negative.
     function timeIncreasesTowardTips(root) {
         let up = 0;
         let pairs = 0;
@@ -6647,31 +6994,52 @@
      */
     forester.branchLengthScale = function (phy) {
         let root = forester.getTreeRoot(phy);
-        return (root && branchLengthsAreTime(root)) ? 'time' : 'divergence';
+        if (!root) {
+            return 'divergence';
+        }
+        // A tree that kept the lengths it arrived with is in time exactly
+        // while they are the ones on it (the switch back restores them).
+        if (root._timeLengthsKept === true) {
+            let kept = true;
+            forester.preOrderTraversalAll(root, function (n) {
+                if (n !== root && n.branch_length !== n._timeLength) {
+                    kept = false;
+                }
+            });
+            return kept ? 'time' : 'divergence';
+        }
+        return branchLengthsAreTime(root) ? 'time' : 'divergence';
     };
 
     /**
-     * True when the tree carries BOTH a time signal (dated nodes, running the
-     * calendar way) and a divergence signal that says something different, so
-     * a time <-> divergence toggle is meaningful. Auspice states divergence as
-     * nextstrain:div; a BEAST tree states it as its branch lengths, which on a
-     * real one differ from the dates on nearly every branch (influenza.tree:
-     * 1344 of 1372).
+     * True when the tree can be laid out by TIME and by DIVERGENCE. The rule
+     * is joint with the desktop (Christian, 2026-09-29):
+     *
+     * - it states a divergence: recorded on its nodes (nextstrain:div), or a
+     *   clock rate on every branch (BEAST; divergence is length x rate, and
+     *   the lengths are its time). A tree with neither is never offered the
+     *   switch, whatever its dates say;
+     * - BOTH layouts can state EVERY branch: every node is dated, every
+     *   branch states a length, and every node records its divergence (the
+     *   root too) or every branch states a rate. A value that is stated is
+     *   stated, whether zero or negative; only an absent one is missing. A
+     *   branch is never drawn at 0 because a datum is missing;
+     * - each picture has some depth (bothPicturesHaveDepth).
+     *
+     * Otherwise the switch is not offered and the tree stays in the layout it
+     * arrived in. Whether the two pictures DIFFER is not asked, nor which way
+     * the dates run.
      *
      * @param phy the tree
      * @returns {boolean}
      */
     forester.hasTimeAndDivergence = function (phy) {
         let root = forester.getTreeRoot(phy);
-        if (!root || !auspiceHasAnyDate(root) || !timeIncreasesTowardTips(root)) {
+        if (!root || !everyNodeStates(root, auspiceNodeDate) || !everyLengthWasStated(root)
+            || !divergenceStatesEveryBranch(root)) {
             return false;
         }
-        // auspiceHasAnyDiv is true for every tree once the divergence has been
-        // captured, so it cannot decide this on its own -- it only says a
-        // divergence measure EXISTS. Whether it says anything different is the
-        // shift test, and that is the question worth asking of both kinds of
-        // tree.
-        return auspiceHasAnyDiv(root) && divergenceDiffersFromTime(root);
+        return bothPicturesHaveDepth(root);
     };
 
     // A number that is not NaN. It used to test only for null, undefined and