archaeopteryx 3.2.1 → 3.4.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.2.1
+// v 3.4.0
 // 2026-09-10
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -35,6 +35,34 @@
 //
 // Dependencies: none
 //
+// REMOVED FROM THE PUBLIC API (2026-09-11). Each was exported, called by
+// nothing -- not this library, not Archaeopteryx.js, not the test suite --
+// and is recorded here so that a later "forester used to have X" can be
+// matched to a decision instead of investigated from scratch:
+//
+//   collapse, unCollapse          the subtree-collapse feature they served was
+//                                 removed from the viewer; they were the only
+//                                 writers of node._children, whose handling
+//                                 went with them
+//   getChildren                   returned _children in preference to children,
+//                                 so it only ever meant anything while collapse
+//                                 existed
+//   findByTaxonomyCode            superseded by the search machinery
+//   findByTaxonomyScientificName  (searchWithSpec and friends)
+//   calcAverageTreeHeight         never used by any caller
+//   calcMaxDepth
+//   calcBranchLengthSimpleStatistics
+//   collectPropertyRefs           superseded by visualizationCandidates
+//   isHasNodeData
+//   removeMaxBranchLength
+//   getOneDistinctTaxonomy
+//
+// forester.js ships inside the archaeopteryx npm package, so an outside caller
+// could in principle have used any of these. That is the cost that was weighed
+// and accepted: 12 of 80 exports earned nothing here, and dead code is not free
+// -- it has to keep working, keep linting clean, and be considered in every
+// refactor.
+//
 //
 // In the following is a basic example shows how to parse a New Hampshire formatted String
 // into to a object representing a phylogenetic tree.
@@ -75,7 +103,6 @@
     const NUMBERS_ONLY_PATTERN = /^[-+]?[0-9\\.]+$/;
 
 
-
     /**
      * Sets links to parent nodes for all nodes in a
      * phyloXML-based tree object
@@ -134,17 +161,12 @@
      * @param node - The root of the subtree to traverse.
      * @param fn - The function to apply.
      */
+    // Kept as a distinct name because callers use both, but it IS
+    // preOrderTraversal now: the two differed only in that this one also
+    // descended into a collapsed node's hidden _children, and nothing can
+    // collapse a node any more. See the removed-API note at the top.
     forester.preOrderTraversalAll = function (node, fn) {
-        fn(node);
-        if (node.children) {
-            for (let i = node.children.length - 1; i >= 0; --i) {
-                forester.preOrderTraversalAll(node.children[i], fn);
-            }
-        } else if (node._children) {
-            for (let ii = node._children.length - 1; ii >= 0; --ii) {
-                forester.preOrderTraversalAll(node._children[ii], fn);
-            }
-        }
+        forester.preOrderTraversal(node, fn);
     };
 
     forester.postOrderTraversalAll = function (node, fn) {
@@ -153,11 +175,6 @@
             for (let i = 0; i < l; ++i) {
                 forester.postOrderTraversalAll(node.children[i], fn);
             }
-        } else if (node._children) {
-            let ll = node._children.length;
-            for (let ii = 0; ii < ll; ++ii) {
-                forester.postOrderTraversalAll(node._children[ii], fn);
-            }
         }
         fn(node);
     };
@@ -173,27 +190,6 @@
         return found;
     };
 
-    forester.findByTaxonomyCode = function (node, code) {
-        let found = [];
-        forester.preOrderTraversalAll(node, function (n) {
-            if (n.taxonomies && n.taxonomies.length > 0 && n.taxonomies[0].code === code) {
-                found.push(n);
-            }
-        });
-        return found;
-    };
-
-    forester.findByTaxonomyScientificName = function (node, scientificName) {
-        let found = [];
-        forester.preOrderTraversalAll(node, function (n) {
-            if (n.taxonomies && n.taxonomies.length > 0 && n.taxonomies[0].scientific_name === scientificName) {
-                found.push(n);
-            }
-        });
-        return found;
-    };
-
-
     /**
      * To delete a sub-tree or external node.
      *
@@ -222,13 +218,6 @@
                 p.children.splice(i, 1);
             }
         }
-        if ((p._children) && (p._children.length > 1)) {
-            let ii = p._children.indexOf(nodeToDelete);
-            if (ii !== -1) {
-                p._children.splice(ii, 1);
-            }
-        }
-
         if (p.children.length === 1) {
             let pp = p.parent;
             let cni = forester.getChildNodeIndex(pp, p);
@@ -563,28 +552,6 @@
     };
 
 
-    forester.getChildren = function (node) {
-        return node._children ? node._children : (node.children ? node.children : []);
-    };
-
-
-    forester.calcAverageTreeHeight = function (node, externalDescendants) {
-        let c = externalDescendants ? externalDescendants : forester.getAllExternalNodes(node);
-        let l = c.length;
-        let s = 0;
-        for (let i = 0; i < l; ++i) {
-            let cc = c[i];
-            while (cc !== node) {
-                if (cc.branch_length > 0) {
-                    s += cc.branch_length;
-                }
-                cc = cc.parent;
-            }
-        }
-        return s / l;
-    };
-
-
     // ------------------------------------------------------------------
     // Automatic visualization candidates
     // ------------------------------------------------------------------
@@ -594,50 +561,70 @@
     // caller-supplied "nodeVisualizations" configuration: the tree is the
     // only input.
     //
-    // Only external nodes are considered; the domains always come from the
-    // COMPLETE tree, so a value keeps its colour inside a subtree view even
-    // when the subtree does not contain it.
+    // Only external nodes are considered.
+    //
+    // Candidacy is decided on the TREE, once: at launch, and again only after
+    // the user edits it (deletes a subtree). A VIEW -- the subtree the user
+    // switches into -- never re-decides it; it only re-summarizes each
+    // candidate over the tips on screen (visualizationSummary). A clade is by
+    // nature a set of tips sharing a value, and one value is refused, so
+    // re-classifying per view would (and until 2026-09-12 did) drop the
+    // chosen colouring in most clades. The desktop works the same way.
     //
     // Candidates: taxonomy code / scientific name / common name, sequence
-    // name / symbol / gene name, and node properties (applies_to "node").
-    // The "style:" namespace is never a candidate -- the desktop reserves it
-    // for per-node rendering instructions (font_color, node_shape, ...), so
-    // treating it as data would mean colouring by a colour.
+    // name / symbol / gene name, and node properties whose applies_to is
+    // "node" or "clade" (isNodeScopedProperty). The "style:" namespace is
+    // never a candidate -- the desktop reserves it for per-node rendering
+    // instructions (font_color, node_shape, ...), so treating it as data
+    // would mean colouring by a colour. Nor are record-keeping fields, by
+    // NAME (VIS_EXCLUDED_WORD_RES below): authors, sets, data-use terms,
+    // ids, accessions, identifiers, taxon ids.
     //
     // The rules, tuned against the real ViPR / BV-BRC trees in docs/data
-    // (which test/visualization_test.js holds as executable fixtures):
+    // (which test/visualization_test.js holds as executable fixtures) and
+    // pinned for the desktop by test/fixtures/vis-contract.tsv (names) and
+    // test/fixtures/vis-trees.tsv (data):
     //
-    //   coverage    present on >= 2/3 of the external nodes. Database
-    //               exports are always patchy -- demanding 100% would
-    //               reject nearly every field of the BV-BRC trees while a
-    //               field on 9% of nodes (state_province) says nothing.
-    //               Nodes without a value simply keep the default look.
+    //   multi-value a ref carried more than once by any external node is
+    //               not a candidate: a node cannot be two colours, and
+    //               picking one silently is worse than not offering it.
     //   repetition  at least 2 distinct values (1 paints the whole tree
-    //               alike), and fewer distinct values than external nodes
-    //               (all-unique means identifiers).
+    //               alike). A CATEGORICAL field with as many distinct
+    //               values as the tree has tips is an identifier and is
+    //               refused; a NUMERIC one is kept, because a measurement
+    //               is naturally one value per sample.
+    //   coverage    a field on fewer than 2/3 of the tips is SPARSE: offered,
+    //               ranked after everything dense, never opening a tree that
+    //               has anything denser. Database exports are always patchy,
+    //               and a half-annotated field is often the interesting one.
     //   categorical <= 20 distinct values -> Color. Above ~12 the reader
     //               leans on the legend, but the real trees cluster at
     //               15-17 (host names, countries, taxonomy codes).
-    //   wide        21+ distinct values are still offered -- as the desktop
-    //               does, every value gets a colour and the LEGEND caps the
-    //               display -- but only when values genuinely repeat:
-    //               distinct/covered <= 0.6, or near-unique fields (strains,
-    //               species names, dates) would flood the menus. Wide fields
-    //               rank after everything else and are never auto-applied.
-    //   numeric     every value parses as a finite number. Up to 10 distinct
-    //               values default to individual colours -- numbers that few
-    //               are usually codes (HA/NA subtypes), and ten is what the
-    //               palette's strong first half holds -- 11 to 20 default to
-    //               a Color-range, and both of those may be switched in the
-    //               legend; above 20 it is a range with no switch. Guard:
-    //               distinct/covered <= 0.9, or "numeric" identifiers
-    //               (genome ids) would become ramps.
+    //   wide        21+ distinct values are still offered -- every value
+    //               gets a colour and the LEGEND caps the display -- but
+    //               never open a tree. If they repeat reasonably
+    //               (distinct/covered <= 3/5) they rank after the numerics;
+    //               if they barely repeat they are NEAR-UNIQUE and rank at
+    //               the very bottom (strains, species names, dates).
+    //   numeric     every value matches VIS_NUMERIC_RE, a decimal grammar
+    //               pinned below; spellings of one number ("1", "1.0") fold
+    //               to one value. Up to 10 distinct values default to
+    //               individual colours -- numbers that few are usually codes
+    //               (HA/NA subtypes), and ten is what the palette's strong
+    //               first half holds -- 11 to 20 default to a Color-range,
+    //               and both of those may be switched in the legend; above
+    //               20 it is a range with no switch. The band is computed
+    //               per VIEW. No uniqueness test for numbers.
     //   shape       <= 7 distinct values (d3 v7 has exactly 7 distinct
     //               fill symbols), numeric or not -- two years as two
     //               shapes is genuinely useful.
-    //   multi-value a ref carried more than once by any external node is
-    //               not a candidate: a node cannot be two colours, and
-    //               picking one silently is worse than not offering it.
+    //   in/out-group offered, ranked after the numerics: a fact about the
+    //               analysis the person who rooted the tree already knows.
+    //
+    // Ranking, best first (tierOf below): 0 clean categorical, 1 numeric,
+    // 2 wide, 3 in/out-group, 4 sparse, 5 near-unique; within a tier by
+    // coverage x balance. The tree OPENS with the first candidate that is
+    // not wide (openingVisualization).
     //
     const VIS_MIN_COVERAGE_NUM = 2;    // coverage >= 2/3, held as a
     const VIS_MIN_COVERAGE_DEN = 3;    // fraction so the test is integer-exact
@@ -646,9 +633,15 @@
     const VIS_NUMERIC_CATEGORY_MAX = 10;   // <= this many distinct numbers -> colours by default
     const VIS_WIDE_REPEAT_NUM = 3;         // wide categorical: distinct/covered <= 0.6,
     const VIS_WIDE_REPEAT_DEN = 5;         // held integer-exact
-    const VIS_MAX_NUMERIC_UNIQUE_NUM = 9;    // distinct/covered <= 0.9,
-    const VIS_MAX_NUMERIC_UNIQUE_DEN = 10;   // integer-exact as well
     const VIS_EXCLUDED_REF_PREFIX = 'style:';
+    // What "numeric" means, spelled out: an optional sign, decimal digits with
+    // an optional fraction, an optional exponent. PINNED as a grammar because
+    // the host language's own idea of a number is not portable: JavaScript's
+    // Number() accepts "0x1A" and "0b101", Java's parseDouble accepts
+    // "Infinity" and "NaN", and a field of either would be a gradient in one
+    // program and a category in the other. Values are trimmed before this
+    // sees them.
+    const VIS_NUMERIC_RE = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
     // Refs that are never a visualization, however their values distribute.
     // A taxon identifier repeats like a category and passes every statistical
     // test above, yet says nothing a colour could carry that the species name
@@ -657,12 +650,95 @@
     // ncbi_taxid, taxon_id and taxonomy_id all count.
     const VIS_EXCLUDED_LOCAL_NAME_RE = /(taxonomy|taxon|tax)id$/;
 
+    // The rest are matched on THE NAME THE MENU SHOWS, split into words.
+    //
+    // Matching the displayed name rather than the raw ref is the point, not a
+    // convenience: `prettifyVisLabel` splits camelCase, so the ref
+    // `dataUseTerms` reaches the user as "Data Use Terms". A first version of
+    // this rule matched the raw ref, and so read that as one word and offered
+    // it -- the menu said "Data Use Terms" while the rule saw "datauseterms".
+    // Going through the same function means the rule and the label cannot
+    // drift apart again.
+    //
+    // On top of that, every run of non-alphanumerics -- whitespace, '-', '_',
+    // punctuation -- is one word break. Separator-aware on purpose, and that
+    // is the whole difference from the rule above: "Authority" and "Dataset"
+    // are ordinary properties and must survive, while "Abbr Authors" and
+    // "Region Set" must not. Reading punctuation as a break also makes the
+    // literal column name "Author(s)" come out as the words "author s".
+    //
+    // What these have in common is that they describe the RECORD rather than
+    // the organism: who deposited it, which collection it belongs to, what may
+    // be done with it and until when, and what to call it in a database. They repeat like
+    // categories and so pass every statistical test, but a colour spent on one
+    // says nothing about the tree.
+    const VIS_EXCLUDED_WORD_RES = [
+        /(^| )authors?( |$)/,   // Author, Authors, Author(s), Abbr Authors
+        /(^| )set( |$)/,        // Region Set -- but not Dataset or Subset
+        /(^| )data use( |$)/,   // Data use, Data-Use Terms
+        /(^| )restricted ?until( |$)/,   // Restricted Until, restricted_until, restrictedUntil: a data-use embargo date
+        /(^| )ids?( |$)/,       // genome_id, patric_id, GenomeID, Feature_ID
+        /accessions?$/,         // ...Accession, ...Accessions
+        /identifiers?$/         // ...Identifier, ...Identifiers
+    ];
+    // A note on why "id" is a WORD rule and accession/identifier are suffix
+    // rules, since the inconsistency is deliberate. "accession" and
+    // "identifier" are long enough that a name ending in those letters is one:
+    // GBAccession is an accession. "id" is two letters and ends a great many
+    // ordinary words -- Plasmid, Hybrid, Nucleic Acid, Lipid, Steroid, Orchid,
+    // Centroid, Grid, Rapid -- any of which is a plausible property on a
+    // biological tree. Matched as a word it catches genome_id, patric_id,
+    // GenomeID, genomeId and Feature_ID while leaving every one of those
+    // alone.
+
+    // Offered, but never the tree's OPENING visualization unless it is the
+    // only thing on offer. "In-Group" and "Out-Group" say which tips were the
+    // study set and which were there to root it -- a fact about the ANALYSIS,
+    // and one the person who rooted the tree already knows. They are also
+    // typically an even two-value split with full coverage, which is exactly
+    // the shape that wins the automatic pick, so without this they open trees
+    // coloured by the least surprising thing in them.
+    //
+    // Both hyphenations and both one-word spellings, since the rule is about a
+    // name rather than a punctuation style: In-Group, InGroup, In Group,
+    // in_group, ingroup, and the same six for out. Plural too.
+    //
+    // Anchored as WORDS, which is not decoration: "Within Group" contains the
+    // substring "in group" and must keep leading.
+    const VIS_DEPRIORITIZED_WORD_RES = [
+        /(^| )(in|out) groups?( |$)/,
+        /(^| )(in|out)groups?( |$)/
+    ];
+
+    // The name as the MENU shows it, split into words -- see the note on
+    // VIS_EXCLUDED_WORD_RES for why the displayed name is the right input.
+    function visNameWords(ref) {
+        let local = ref.indexOf(':') >= 0 ? ref.substring(ref.indexOf(':') + 1) : ref;
+        return prettifyVisLabel(local).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    }
+
+    function matchesAny(res, words) {
+        for (let i = 0, l = res.length; i !== l; ++i) {
+            if (res[i].test(words)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     function visExcludedRef(ref) {
         if (ref.indexOf(VIS_EXCLUDED_REF_PREFIX) === 0) {
             return true;
         }
-        let local = ref.substring(ref.indexOf(':') + 1).toLowerCase().replace(/[^a-z0-9]/g, '');
-        return VIS_EXCLUDED_LOCAL_NAME_RE.test(local);
+        let local = ref.substring(ref.indexOf(':') + 1);
+        if (VIS_EXCLUDED_LOCAL_NAME_RE.test(local.toLowerCase().replace(/[^a-z0-9]/g, ''))) {
+            return true;
+        }
+        return matchesAny(VIS_EXCLUDED_WORD_RES, visNameWords(ref));
+    }
+
+    function visDeprioritizedRef(ref) {
+        return matchesAny(VIS_DEPRIORITIZED_WORD_RES, visNameWords(ref));
     }
 
     // ---- display normalization --------------------------------------------
@@ -683,6 +759,12 @@
     // "Saimiri boliviensis (squirrel monkey; voucher: X)" reads as
     // "Saimiri boliviensis" rather than dangling.
     //
+    // A value that normalizes to NOTHING -- "_", "___", a host that is only
+    // its ";" qualifier -- is no value at all, everywhere: the tip is not
+    // covered, no group is made, the legend shows no row for it, and it does
+    // not count as the ref being carried twice. (Decided 2026-09-12; the
+    // desktop already read it that way.)
+    //
     // Matching is WHOLE-VALUE only (after a trailing parenthetical is tried
     // stripped: "Bos taurus (cattle)" looks up "bos taurus") -- never by
     // substring, so "ferret badger" (a Melogale, not a ferret) and
@@ -779,6 +861,19 @@
         return hit || s;
     }
 
+    // How a numeric field draws by default, from how many distinct values it
+    // shows: up to VIS_NUMERIC_CATEGORY_MAX as individual colours (numbers
+    // that few are usually codes), up to VIS_MAX_COLOR_CATEGORIES as a
+    // gradient the legend can switch back to colours, above that a gradient
+    // only. Computed per VIEW: ten distinct years inside a clade draw better
+    // as ten colours than as a slice of the whole tree's gradient.
+    function visNumericModes(distinct) {
+        return {
+            colorMode: distinct <= VIS_NUMERIC_CATEGORY_MAX ? 'category' : 'range',
+            switchable: distinct <= VIS_MAX_COLOR_CATEGORIES
+        };
+    }
+
     // Fixed candidate slots for the phyloXML elements (properties use their
     // ref). CROSS-IMPLEMENTATION CONTRACT with desktop Archaeopteryx: the
     // ids here (tax:code, seq:name, ...) and the rule that taxonomy/sequence
@@ -819,12 +914,26 @@
         return prettifyVisLabel(local);
     };
 
+    // Is this property about the node itself? phyloXML's applies_to has six
+    // values and two of them describe the node's own data at a tip: 'node',
+    // and 'clade' -- the clade rooted at an external node IS that node. Tools
+    // differ on which they write: BV-BRC/ViPR exports say node, the repseq
+    // pipeline says clade for every field, and until 2026-09-12 this library
+    // accepted only node, so a repseq tree with country, host, subtype and
+    // year on every tip offered NOTHING to colour by -- four of the thirteen
+    // trees in test_trees, silently. The desktop applies no filter at all.
+    // 'parent_branch' is deliberately still out: that is the branch above the
+    // node, and colouring a node by its branch's property would be wrong.
+    forester.isNodeScopedProperty = function (p) {
+        return p.applies_to === 'node' || p.applies_to === 'clade';
+    };
+
     forester.visualizationCandidates = function (tree) {
         let total = 0;
         let stats = Object.create(null);   // id -> {kind, ref, label, nodes, values:Set, multi}; null-proto: ids embed file refs
 
         forester.preOrderTraversalAll(tree, function (n) {
-            if (n.children || n._children) {
+            if (n.children) {
                 return;
             }
             total++;
@@ -855,37 +964,50 @@
             if (n.properties) {
                 for (let i = 0; i < n.properties.length; ++i) {
                     let p = n.properties[i];
-                    if (p.ref && p.applies_to === 'node' && !visExcludedRef(p.ref)) {
+                    if (p.ref && forester.isNodeScopedProperty(p) && !visExcludedRef(p.ref)) {
                         add('prop:' + p.ref, 'property', p.ref, null, p.value);
                     }
                 }
             }
             Object.keys(perNode).forEach(function (id) {
                 let g = perNode[id];
+                let cut = g.kind === 'property' ? visQualifierCut(g.ref) : null;
+                // properties group under their normalized display form;
+                // taxonomy / sequence elements are curated text, verbatim.
+                // A value that folds to NOTHING ("_", a host that is only its
+                // ";" qualifier) is NO VALUE, exactly like the empty string
+                // dropped above: it does not cover the tip, makes no group,
+                // and does not count as "carried twice". Until 2026-09-12 the
+                // tip was counted covered here and the legend then showed a
+                // row with an empty label (Christian: fix; the desktop had it
+                // right).
+                let displays = [];
+                for (let i = 0; i < g.values.length; ++i) {
+                    let display = g.kind === 'property' ? visDisplayLabel(g.values[i], cut) : g.values[i];
+                    if (display.length > 0) {
+                        displays.push(display);
+                    }
+                }
+                if (displays.length === 0) {
+                    return;
+                }
                 if (!stats[id]) {
-                    stats[id] = {kind: g.kind, ref: g.ref, label: g.label,
-                        cut: g.kind === 'property' ? visQualifierCut(g.ref) : null,
+                    stats[id] = {kind: g.kind, ref: g.ref, label: g.label, cut: cut,
                         nodes: 0, keys: Object.create(null), multi: false};
                 }
                 let s = stats[id];
                 s.nodes++;
-                if (g.values.length > 1) {
+                if (displays.length > 1) {
                     s.multi = true;
                 }
-                for (let i = 0; i < g.values.length; ++i) {
-                    // properties group under their normalized display form;
-                    // taxonomy / sequence elements are curated text, verbatim
-                    let display = g.kind === 'property' ? visDisplayLabel(g.values[i], s.cut) : g.values[i];
-                    if (display.length === 0) {
-                        continue;
-                    }
+                displays.forEach(function (display) {
                     let key = g.kind === 'property' ? display.toLowerCase() : display;
                     if (!s.keys[key]) {
                         s.keys[key] = {count: 0, spellings: Object.create(null)};
                     }
                     s.keys[key].count++;
                     s.keys[key].spellings[display] = (s.keys[key].spellings[display] || 0) + 1;
-                }
+                });
             });
         });
 
@@ -918,38 +1040,121 @@
                 canon[key] = rep;
                 counts[rep] = group.count;
             });
-            let distinct = Object.keys(canon).length;
-            if (covered * VIS_MIN_COVERAGE_DEN < total * VIS_MIN_COVERAGE_NUM) {
-                return;
-            }
-            if (distinct < 2) {
-                return;
-            }
             let values = Object.keys(counts);
             let numeric = values.every(function (v) {
-                return Number.isFinite(Number(v));
+                return VIS_NUMERIC_RE.test(v);
             });
+            if (numeric) {
+                // "1", "1.0" and "+1" are one value. Group the spellings by
+                // the number they denote; the representative is the SHORTEST
+                // spelling, ties alphabetically (a number has no preferred
+                // spelling, so frequency would only pick the exporter's
+                // habit). canon then maps every raw spelling to it, so
+                // visualizationNodeValue folds a node's "1.0" the same way.
+                let byNumber = Object.create(null);
+                values.forEach(function (v) {
+                    let k = String(Number(v));
+                    let g = byNumber[k];
+                    if (!g) {
+                        byNumber[k] = {rep: v, count: counts[v]};
+                    } else {
+                        g.count += counts[v];
+                        if (v.length < g.rep.length || (v.length === g.rep.length && v < g.rep)) {
+                            g.rep = v;
+                        }
+                    }
+                });
+                let folded = Object.create(null);
+                Object.keys(byNumber).forEach(function (k) {
+                    folded[byNumber[k].rep] = byNumber[k].count;
+                });
+                Object.keys(canon).forEach(function (key) {
+                    canon[key] = byNumber[String(Number(canon[key]))].rep;
+                });
+                counts = folded;
+                values = Object.keys(counts);
+            }
+            let distinct = values.length;
+            // Sparse fields are RANKED LAST, not refused. A half-annotated
+            // field is often the most interesting thing in the tree -- someone
+            // hand-annotates a subset precisely because it is worth marking --
+            // it just should not be what opens the tree.
+            //
+            // This was a hard refusal, and it cost real data: on the 13,246-tip
+            // BV-BRC flu tree, Country (8,031 covered, 28 values) and Region
+            // (8,030, 13 values) both sit at 61% and were dropped from the menu
+            // outright, while Isolation_Source cleared the bar by twelve tips.
+            // The two fields a phylogeography user reaches for first were
+            // missing from our own flagship demo, invisibly, because a refused
+            // field leaves no trace in the UI. The desktop ranked instead of
+            // refusing from 0.11.133 and was right; this matches it.
+            //
+            // The legend already carries the honest part: a "no value" row
+            // with the uncovered count, at reduced opacity.
+            let sparse = covered * VIS_MIN_COVERAGE_DEN < total * VIS_MIN_COVERAGE_NUM;
+            if (distinct < 2) {
+                return;
+            }
             let colorMode;
             let switchable = false;
             let wide = false;
+            let nearUnique = false;
             if (numeric) {
-                if (distinct * VIS_MAX_NUMERIC_UNIQUE_DEN > covered * VIS_MAX_NUMERIC_UNIQUE_NUM) {
-                    return;
-                }
-                colorMode = distinct <= VIS_NUMERIC_CATEGORY_MAX ? 'category' : 'range';
-                switchable = distinct <= VIS_MAX_COLOR_CATEGORIES;
+                // No uniqueness refusal for numbers. There used to be one
+                // (distinct/covered > 9/10 -> refused) meant to catch numeric
+                // identifiers, and it could not tell an identifier from a
+                // MEASUREMENT: a read count, a viral load, an expression level
+                // or a year is naturally one value per sample, which is what a
+                // measurement is. Run over the desktop's gallery it refused
+                // exactly those -- read_count, viral_load, expression_tpm, a
+                // 1930-2010 year field -- on nine trees and left one opening
+                // uncoloured. Run over ours it refused three things, every one
+                // an identifier the NAME rules catch anyway (genome_id twice,
+                // BVBRC_Accession). Identifiers are a fact about a name, not a
+                // distribution, and the name rules are the right instrument.
+                // Removed 2026-09-12, jointly with the desktop.
+                let modes = visNumericModes(distinct);
+                colorMode = modes.colorMode;
+                switchable = modes.switchable;
                 values.sort(function (a, b) {
                     return Number(a) - Number(b);
                 });
             } else {
+                // KNOWN EDGE, left alone BY DECISION (Christian, 2026-09-12):
+                // this counts against TOTAL, so a field unique across its
+                // annotated subset -- strain on a 1,170-tip flu tree, 1,168
+                // distinct over the 1,168 tips that carry it -- is offered
+                // rather than refused as the identifier it is. It lands as
+                // near-unique, tier 5, the bottom of the menu, and never
+                // opens a tree. Counting against COVERED instead closes that
+                // (five corpus fields, four of them strain/collection date)
+                // but also refuses a field carried by two tips with two
+                // values, where all-unique is a sample of two, not evidence.
+                // Both were put to him with the numbers; he chose to keep
+                // this until a user complains. Also decided then: strain and
+                // genome name are NOT excluded by name -- both are grouping
+                // fields wherever an isolate contributes several sequences
+                // (eight segment records per strain in bvbrc+flu_seg4), and
+                // the data rules already sort the identifier case to the
+                // bottom. Do not "fix" either without asking him.
                 if (distinct >= total) {
                     return;
                 }
                 if (distinct > VIS_MAX_COLOR_CATEGORIES) {
+                    // More than 20 values. If they repeat reasonably (distinct
+                    // no more than 3/5 of covered) this is a WIDE category:
+                    // offered, never leading. If they barely repeat -- but DO
+                    // repeat, else the all-distinct test above would have
+                    // refused it -- it goes to the very bottom of the menu.
+                    // Christian, 2026-09-12: an all-distinct categorical is an
+                    // identifier and stays refused; a barely-repeating one is
+                    // nearly one, so it is offered last rather than hidden,
+                    // because a refusal cannot be seen failing and a rank can.
+                    // It is wide as well, so it never opens a tree.
+                    wide = true;
                     if (distinct * VIS_WIDE_REPEAT_DEN > covered * VIS_WIDE_REPEAT_NUM) {
-                        return;
+                        nearUnique = true;
                     }
-                    wide = true;
                 }
                 colorMode = 'category';
                 values.sort();
@@ -978,12 +1183,15 @@
                 total: total,
                 values: values,
                 counts: counts,
-                canon: s.kind === 'property' ? canon : null,
+                canon: (s.kind === 'property' || numeric) ? canon : null,
                 cut: s.cut,
                 score: (covered / total) * balance,
                 colorMode: colorMode,
                 switchable: switchable,
                 wide: wide,
+                nearUnique: nearUnique,
+                sparse: sparse,
+                deprioritized: visDeprioritizedRef(s.ref || id),
                 shape: distinct <= VIS_MAX_SHAPE_CATEGORIES
             });
         });
@@ -998,15 +1206,36 @@
             }
         });
 
-        // Best first: clean categorical fields, then numeric ranges, then the
-        // wide categoricals (offered, never leading) -- within each tier by
-        // score, ties alphabetically. The first entry is what the viewer
-        // applies on load.
+        // Best first: clean categorical fields, then EVERY numeric field, then
+        // the wide categoricals (offered, never leading), then the
+        // deprioritized ones, then the sparse, and last the barely-repeating
+        // wide ones -- within each tier by score, ties alphabetically. What
+        // OPENS the tree is openingVisualization below: the first entry that
+        // is not wide. So tiers 0, 1, 3 and 4 can open a tree, each only when
+        // nothing above it exists, and tiers 2 and 5 never do -- a wide field
+        // above an In-Group does not stop the In-Group from opening the tree,
+        // it just precedes it in the menu.
         function tierOf(c) {
-            if (c.colorMode === 'category') {
-                return c.wide ? 2 : 0;
+            if (c.nearUnique) {
+                return 5;
             }
-            return 1;
+            if (c.sparse) {
+                return 4;
+            }
+            if (c.deprioritized) {
+                return 3;
+            }
+            // Every numeric field is tier 1, including one with few enough
+            // values to draw as discrete colours. Tiering on colour MODE put
+            // a small measurement in tier 0 beside the real categories, where
+            // an evenly spread one outscores them on entropy -- so with the
+            // uniqueness refusal gone, Viral Load would open a tree instead of
+            // Segment, and Year instead of Clade. A measurement is always
+            // offered; a category, when there is one, still opens the tree.
+            if (c.numeric) {
+                return 1;
+            }
+            return c.wide ? 2 : 0;
         }
         candidates.sort(function (a, b) {
             let ta = tierOf(a);
@@ -1047,7 +1276,7 @@
         let idLike = 0;
         let refs = {};   // ref -> {covered, values:Set, wordy}
         forester.preOrderTraversalAll(tree, function (n) {
-            if (n.children || n._children) {
+            if (n.children) {
                 return;
             }
             total++;
@@ -1062,7 +1291,7 @@
                 let seen = {};
                 for (let i = 0; i < n.properties.length; ++i) {
                     let p = n.properties[i];
-                    if (!p.ref || p.applies_to !== 'node' || seen[p.ref]
+                    if (!p.ref || !forester.isNodeScopedProperty(p) || seen[p.ref]
                         || p.ref.indexOf(VIS_EXCLUDED_REF_PREFIX) === 0) {
                         continue;
                     }
@@ -1127,7 +1356,7 @@
         }
         for (let i = 0; i < node.properties.length; ++i) {
             let p = node.properties[i];
-            if (!p.ref || p.applies_to !== 'node' || p.value === undefined || p.value === null) {
+            if (!p.ref || !forester.isNodeScopedProperty(p) || p.value === undefined || p.value === null) {
                 continue;
             }
             let v = String(p.value).trim();
@@ -1190,7 +1419,7 @@
         let names = [];
         let slot = labelProperty ? {kind: 'property', ref: labelProperty} : null;
         forester.preOrderTraversalAll(tree, function (n) {
-            if (n.children || n._children) {
+            if (n.children) {
                 return;
             }
             let name = slot ? forester.visualizationNodeValue(n, slot) : null;
@@ -1306,7 +1535,7 @@
             if (node.properties) {
                 for (let i = 0; i < node.properties.length; ++i) {
                     let p = node.properties[i];
-                    if (p.ref === candidate.ref && p.applies_to === 'node') {
+                    if (p.ref === candidate.ref && forester.isNodeScopedProperty(p)) {
                         let v = clean(p.value);
                         if (v !== null) {
                             // a classifier-built candidate folds the value the
@@ -1314,6 +1543,11 @@
                             // {kind, ref} probe (labels, prefixes) reads raw
                             if (candidate.canon) {
                                 let display = visDisplayLabel(v, candidate.cut || null);
+                                if (display.length === 0) {
+                                    // folds to nothing: no value, as the
+                                    // classifier counted it -- keep looking
+                                    continue;
+                                }
                                 return candidate.canon[display.toLowerCase()] || display;
                             }
                             return v;
@@ -1332,7 +1566,9 @@
                 for (let j = 0; j < list.length; ++j) {
                     let v = clean(VIS_ELEMENT_SLOTS[i].get(list[j]));
                     if (v !== null) {
-                        return v;
+                        // verbatim, except that a numeric slot folds its
+                        // spellings exactly as the classifier grouped them
+                        return candidate.canon ? (candidate.canon[v] || v) : v;
                     }
                 }
                 return null;
@@ -1341,23 +1577,111 @@
         return null;
     };
 
-    forester.collectPropertyRefs = function (phy, appliesTo, externalOnly) {
-        let propertyRefs = new Set();
-        forester.preOrderTraversalAll(phy, function (n) {
-
-            if (!externalOnly || externalOnly !== true || (!n.children && !n._children)) {
-                if (n.properties && n.properties.length > 0) {
-                    let propertiesLength = n.properties.length;
-                    for (let i = 0; i < propertiesLength; ++i) {
-                        let property = n.properties[i];
-                        if (property.ref && property.value && property.datatype && property.applies_to && property.applies_to === appliesTo) {
-                            propertyRefs.add(property.ref);
-                        }
-                    }
+    // The visualization a tree OPENS with: the first candidate that is not
+    // wide (21+ values are offered, never imposed), or null for none. One
+    // definition, used by the viewer and by the fixture generator, so the
+    // rule the desktop ports is the rule the viewer runs.
+    forester.openingVisualization = function (candidates) {
+        for (let i = 0; i < candidates.length; ++i) {
+            if (!candidates[i].wide) {
+                return candidates[i];
+            }
+        }
+        return null;
+    };
+
+    // What a VIEW shows of a candidate: its values, counts and coverage over
+    // the tips under `root` -- the subtree the user switched into, or the
+    // whole tree. Candidacy is decided ONCE, on the tree
+    // (visualizationCandidates); a view never re-decides it, it only
+    // re-summarizes. Until 2026-09-12 the viewer re-ran the classifier on
+    // every subtree, and since a clade is by nature a set of tips sharing a
+    // value, and one value is refused, entering a clade dropped the colouring
+    // in 61% of the corpus's clades (4,192 of 6,857) and did not bring it back
+    // on return. Values are read exactly as the classifier grouped them, so
+    // everything found here is in the candidate's domain and keeps its
+    // colour. A numeric candidate also gets the view's colour-mode band
+    // (see visNumericModes); a category keeps its mode.
+    // `root` is a node, walked in preorder, or an array of the tips to
+    // describe (the viewer passes what is on screen, which a collapsed clade
+    // shortens).
+    forester.visualizationSummary = function (candidate, root) {
+        let counts = Object.create(null);
+        let total = 0;
+        let coverage = 0;
+        let tips = root;
+        if (!Array.isArray(root)) {
+            tips = [];
+            forester.preOrderTraversalAll(root, function (n) {
+                if (!n.children) {
+                    tips.push(n);
                 }
+            });
+        }
+        tips.forEach(function (n) {
+            if (n.children) {
+                return;
+            }
+            total++;
+            let v = forester.visualizationNodeValue(n, candidate);
+            if (v !== null) {
+                coverage++;
+                counts[v] = (counts[v] || 0) + 1;
             }
         });
-        return propertyRefs;
+        let values = Object.keys(counts);
+        if (candidate.numeric) {
+            values.sort(function (a, b) {
+                return Number(a) - Number(b);
+            });
+        } else {
+            values.sort();
+        }
+        let summary = {values: values, counts: counts, coverage: coverage, total: total, distinct: values.length};
+        if (candidate.numeric) {
+            let modes = visNumericModes(values.length);
+            summary.colorMode = modes.colorMode;
+            summary.switchable = modes.switchable;
+        }
+        return summary;
+    };
+
+    // The candidates of a tree the user has EDITED (a subtree deleted), with
+    // the fields they had chosen KEPT as long as those still carry a value
+    // somewhere in what remains. The refusal rules decide what is offered,
+    // never what is already chosen: colouring by Host and deleting every
+    // clade but one must not silently uncolour the tree because one host is
+    // "not a category". A kept field is appended after the offered ones and
+    // flagged `kept`, so the menu holds it exactly as long as the user does;
+    // the next edit drops it unless it is still chosen. `chosen` is the
+    // previous candidate objects -- their grouping travels with them.
+    forester.visualizationCandidatesKeeping = function (tree, chosen) {
+        let candidates = forester.visualizationCandidates(tree);
+        let ids = Object.create(null);
+        candidates.forEach(function (c) {
+            ids[c.id] = true;
+        });
+        (chosen || []).forEach(function (c) {
+            if (!c || ids[c.id]) {
+                return;
+            }
+            let s = forester.visualizationSummary(c, tree);
+            if (s.coverage === 0) {
+                return;
+            }
+            c.values = s.values;
+            c.counts = s.counts;
+            c.coverage = s.coverage;
+            c.total = s.total;
+            if (c.numeric) {
+                c.colorMode = s.colorMode;
+                c.switchable = s.switchable;
+            }
+            c.kept = true;
+            ids[c.id] = true;
+            candidates.push(c);
+        });
+        return candidates;
     };
 
     forester.collectBasicTreeProperties = function (tree) {
@@ -1376,12 +1700,12 @@
         properties.taxonomies = false;
         properties.alignedMolSeqs = true;
         properties.maxMolSeqLength = 0;
+        // protein domain architectures on the tips: whether any tip carries
+        // one, and the longest (Lmax, the scale every track shares)
+        properties.domainArchitectures = false;
+        properties.maxDomainArchitectureLength = 0;
         properties.externalNodesCount = 0;
         properties.nodeCount = 0;
-        // How many of the tree's branches actually carry a positive length.
-        // Whether a tree is worth drawing to scale is a question about the
-        // majority of its branches, not about whether any branch has a length.
-        properties.branchesWithPositiveLength = 0;
         // Branches that carry a length AT ALL -- an explicit zero is a real
         // measurement, not a missing one, so these are counted separately from
         // the "positive" tally above. Split internal-vs-all because a missing
@@ -1394,6 +1718,14 @@
         properties.internalBranchCount = 0;
         properties.internalBranchesWithLength = 0;
         properties.averageBranchLength = 0;
+        // Positive lengths only, and the root included: these feed
+        // averageBranchLength and nothing else. They are deliberately NOT the
+        // same population as branchCount / branchesWithLength below, which
+        // exclude the root and count an explicit zero as the measurement it is.
+        // A `branchesWithPositiveLength` property built from this counter was
+        // removed on 2026-09-11 -- nothing read it, and having two tallies over
+        // two different node sets invited exactly the comparison that would be
+        // wrong.
         let bl_counter = 0;
         let bl_sum = 0;
         // Counting the super-root would add a node and a branch that do not
@@ -1404,7 +1736,7 @@
         forester.preOrderTraversalAll(rootNode, function (n) {
             properties.nodeCount += 1;
             if (n !== rootNode) {
-                let internal = !!(n.children || n._children);
+                let internal = !!(n.children);
                 let measured = typeof n.branch_length === 'number' && isFinite(n.branch_length);
                 properties.branchCount += 1;
                 if (measured) {
@@ -1422,11 +1754,11 @@
                 if (n.name.length > properties.longestNodeName) {
                     properties.longestNodeName = n.name.length;
                 }
-                if ((n.children || n._children) && (n.parent)) {
+                if ((n.children) && (n.parent)) {
                     properties.internalNodeData = true;
                 }
             }
-            if (!(n.children || n._children)) {
+            if (!(n.children)) {
                 properties.externalNodesCount += 1;
             }
             if (n.branch_length && n.branch_length > 0) {
@@ -1443,7 +1775,7 @@
             if (n.sequences && n.sequences.length > 0) {
                 properties.sequences = true;
 
-                if (n.children || n._children) {
+                if (n.children) {
                     properties.internalNodeData = true;
                 } else {
                     let s = n.sequences[0];
@@ -1455,11 +1787,18 @@
                             properties.alignedMolSeqs = false;
                         }
                     }
+                    let da = forester.domainArchitectureOf(n);
+                    if (da) {
+                        properties.domainArchitectures = true;
+                        if (Number(da.length) > properties.maxDomainArchitectureLength) {
+                            properties.maxDomainArchitectureLength = Number(da.length);
+                        }
+                    }
                 }
             }
             if (n.taxonomies && n.taxonomies.length > 0) {
                 properties.taxonomies = true;
-                if (n.children || n._children) {
+                if (n.children) {
                     properties.internalNodeData = true;
                 }
             }
@@ -1483,7 +1822,6 @@
 
         });
 
-        properties.branchesWithPositiveLength = bl_counter;
 
         if (bl_counter > 0) {
             properties.averageBranchLength = bl_sum / bl_counter;
@@ -1522,15 +1860,14 @@
     forester.calcSumOfAllExternalDescendants = function (node) {
         let nodes = 0;
         forester.preOrderTraversalAll(node, function (n) {
-            if (!(n.children || n._children)) {
+            if (!(n.children)) {
                 ++nodes;
             }
         });
         return nodes;
     };
 
-    // Ladderize: at every node, order the VISIBLE children (n.children; a
-    // collapsed node's hidden _children are left untouched) by clade size --
+    // Ladderize: at every node, order the children by clade size --
     // largest first when largestFirst, smallest first when not. Works at ANY
     // child count, not just 2, so a polytomy (common on a phylodynamic tree,
     // e.g. an Auspice build, where every internal node may carry 3+ children)
@@ -1580,7 +1917,7 @@
     forester.getAllExternalNodes = function (node) {
         let nodes = [];
         forester.preOrderTraversalAll(node, function (n) {
-            if (!n.children && !n._children) {
+            if (!n.children) {
                 nodes.push(n);
             }
         });
@@ -1595,19 +1932,6 @@
         return nodes;
     };
 
-    forester.calcMaxDepth = function (node) {
-        let max = 0;
-        forester.preOrderTraversalAll(node, function (n) {
-            if (!n.children && !n._children) {
-                let steps = forester.calcDepth(n);
-                if (steps > max) {
-                    max = steps;
-                }
-            }
-        });
-        return max;
-    };
-
     forester.calcDepth = function (node) {
 
         let steps = 0;
@@ -1619,31 +1943,6 @@
     };
 
 
-    forester.calcBranchLengthSimpleStatistics = function (node) {
-        let stats = {};
-        stats.mean = 0;
-        stats.min = Number.MAX_VALUE;
-        stats.max = 0;
-        stats.n = 0;
-        let sum = 0;
-        forester.preOrderTraversalAll(node, function (n) {
-            if (n !== node && n.branch_length && n.branch_length >= 0) {
-                ++stats.n;
-                sum += n.branch_length;
-                if (n.branch_length < stats.min) {
-                    stats.min = n.branch_length;
-                }
-                if (n.branch_length > stats.max) {
-                    stats.max = n.branch_length;
-                }
-            }
-        });
-        if (stats.n > 0) {
-            stats.mean = sum / stats.n;
-        }
-        return stats;
-    };
-
     forester.calcMaxBranchLength = function (node) {
         let max = 0;
         forester.preOrderTraversalAll(node, function (n) {
@@ -1655,33 +1954,6 @@
     };
 
 
-    forester.isHasNodeData = function (node) {
-        return ((node.name && node.name.length > 0) || (node.taxonomies && node.taxonomies.length > 0) || (node.sequences && node.sequences.length > 0) || (node.properties && node.properties.length > 0));
-    };
-
-
-    forester.removeMaxBranchLength = function (node) {
-        forester.preOrderTraversalAll(node, function (n) {
-            if (n.max) {
-                n.max = undefined;
-            }
-        });
-    };
-
-    forester.collapse = function (node) {
-        if (node.children) {
-            node._children = node.children;
-            node.children = null;
-        }
-    };
-
-    forester.unCollapse = function (node) {
-        if (node._children) {
-            node.children = node._children;
-            node._children = null;
-        }
-    };
-
     /**
      * To parse a New Hampshire (Newick) formatted tree.
      *
@@ -2058,6 +2330,17 @@
         // the shared contract -- and throwing on a combination a user
         // plausibly wants is what forced callers into workarounds.
 
+        // A text holding several trees (one per ';') reads as its FIRST;
+        // parseNewHampshireTrees reads them all. Before this the statements
+        // ran together and the LAST tree came back, the others silently
+        // dropped.
+        {
+            let statements = forester.splitNewHampshire(nhStr);
+            if (statements.length > 1) {
+                nhStr = statements[0];
+            }
+        }
+
         let ancs = [];
         let x = {};
 
@@ -2150,7 +2433,16 @@
                         // the separator before a branch length: the length itself
                         // is read by the branch below, so there is nothing to do here
                     } else {
-                        let e = ss[i - 1];
+                        // What came before decides what this element is: a name
+                        // follows an opening bracket, a comma or a close, and a
+                        // branch length follows a colon.
+                        //
+                        // At i === 0 there IS no previous token, and the string
+                        // beginning with a label is the one-node tree "a;" --
+                        // valid Newick, and for want of this line its name was
+                        // read as nothing at all and written back as "". The
+                        // start of input opens the tree, so it counts as '('.
+                        let e = (i === 0) ? '(' : ss[i - 1];
                         if (e) {
                             e = e.trim();
                             // re-attach any annotation blobs riding on this
@@ -2280,7 +2572,7 @@
 
         function moveInternalNodeNamesToConfidenceValues(node) {
             forester.preOrderTraversalAll(node, function (n) {
-                if (n.children || n._children) {
+                if (n.children) {
                     if (n.name) {
                         let s = n.name;
                         if (NUMBERS_ONLY_PATTERN.test(s)) {
@@ -2300,6 +2592,66 @@
         }
     };
 
+    // Splits a New Hampshire text into its tree statements, one per ';'
+    // outside quotes and [...] comments (a ';' inside a quoted label or a
+    // [&...] annotation is data), each trimmed; blank statements are
+    // dropped. A text without a terminating ';' is one statement.
+    forester.splitNewHampshire = function (nhStr) {
+        let s = String(nhStr);
+        let parts = [];
+        let start = 0;
+        let inSingle = false;
+        let inDouble = false;
+        let depth = 0;
+        for (let i = 0, n = s.length; i < n; ++i) {
+            let c = s.charAt(i);
+            if (inSingle) {
+                if (c === "'") {
+                    inSingle = false;
+                }
+            } else if (inDouble) {
+                if (c === '"') {
+                    inDouble = false;
+                }
+            } else if (depth > 0) {
+                if (c === ']') {
+                    --depth;
+                } else if (c === '[') {
+                    ++depth;
+                }
+            } else if (c === "'") {
+                inSingle = true;
+            } else if (c === '"') {
+                inDouble = true;
+            } else if (c === '[') {
+                depth = 1;
+            } else if (c === ';') {
+                parts.push(s.substring(start, i + 1));
+                start = i + 1;
+            }
+        }
+        parts.push(s.substring(start));
+        return parts.map(function (p) {
+            return p.trim();
+        }).filter(function (p) {
+            return p.length > 0;
+        });
+    };
+
+    // Every tree in a New Hampshire text (a file can hold many, one per
+    // ';'), each parsed as parseNewHampshire does, in file order. A text
+    // with no statement at all is handed to parseNewHampshire whole, so it
+    // fails the way an empty tree always did.
+    forester.parseNewHampshireTrees = function (nhStr, confidenceValuesInBrackets, confidenceValuesAsInternalNames) {
+        let statements = forester.splitNewHampshire(nhStr);
+        if (statements.length === 0) {
+            return [forester.parseNewHampshire(nhStr, confidenceValuesInBrackets, confidenceValuesAsInternalNames)];
+        }
+        return statements.map(function (statement) {
+            return forester.parseNewHampshire(statement, confidenceValuesInBrackets, confidenceValuesAsInternalNames);
+        });
+    };
+
     // Parses a Nexus-formatted string and returns an ARRAY of tree objects,
     // each in the same shape parseNewHampshire produces (a Nexus file can
     // hold any number of trees). Ported from the desktop's
@@ -2998,7 +3350,7 @@
         let v = metricOf(node);
         node.branch_length = (parentValue !== null && v !== null)
             ? Math.max(0, v - parentValue) : 0;
-        let children = node.children || node._children;
+        let children = node.children;
         if (children) {
             for (let i = 0; i < children.length; ++i) {
                 setDeltaBranchLengths(children[i], v, metricOf);
@@ -3028,93 +3380,19 @@
         return auspiceHasAnyDate(root) && auspiceHasAnyDiv(root);
     };
 
+    // A number that is not NaN. It used to test only for null, undefined and
+    // NaN, and so answered TRUE for "hello", "", {}, [] and true -- which no
+    // caller was hurt by, since all of them pass the result of parseFloat, but
+    // the name promised a check it did not make.
+    //
+    // Infinity is deliberately still accepted, so that this stays a rename in
+    // behaviour as well as in intent: parseFloat('1e999') is Infinity, and
+    // whether a branch length of Infinity should be refused is a separate
+    // question from whether a string is a number.
     forester.isNumber = function (v) {
-        if (v === undefined || v === null) {
-            return false;
-        }
-        if (v != v) {
-            // This can only be true if the v is NaN
-            return false;
-        }
-        return true;
-    };
-
-    forester.getOneDistinctTaxonomy = function (node) {
-        let id = null;
-        let code = null;
-        let sn = null;
-        let cn = null;
-        let result = true;
-        let sawTax = false;
-        forester.preOrderTraversalAll(node, function (n) {
-            if (n.taxonomies && n.taxonomies.length === 1) {
-                let tax = n.taxonomies[0];
-                if (tax.code && tax.code.length > 0) {
-                    sawTax = true;
-                    if (code === null) {
-                        code = tax.code;
-                    } else if (code !== tax.code) {
-                        result = false;
-                        return;
-                    }
-                }
-                if (tax.scientific_name && tax.scientific_name.length > 0) {
-                    sawTax = true;
-                    if (sn === null) {
-                        sn = tax.scientific_name;
-                    } else if (sn !== tax.scientific_name) {
-                        result = false;
-                        return;
-                    }
-                }
-                if (tax.common_name && tax.common_name.length > 0) {
-                    sawTax = true;
-                    if (cn === null) {
-                        cn = tax.common_name;
-                    } else if (cn !== tax.common_name) {
-                        result = false;
-                        return;
-                    }
-                }
-                if (tax.id && tax.id.value && tax.id.value.length > 0) {
-                    sawTax = true;
-                    let myid;
-                    if (tax.id.provider && tax.id.provider.length > 0) {
-                        myid = tax.id.provider + ':' + tax.id.value;
-                    } else {
-                        myid = tax.id.value;
-                    }
-                    if (id === null) {
-                        id = myid;
-                    } else if (id !== myid) {
-                        result = false;
-
-                    }
-                }
-            } else if (!n.children && !n._children) {
-                // If an external node lacks taxonomy, return false.
-                result = false;
-            }
-        });
-        if (!sawTax) {
-            return null;
-        }
-        if (result === true) {
-
-            if (sn) {
-                return sn;
-            } else if (code) {
-                return code;
-            } else if (cn) {
-                return cn;
-            } else if (id) {
-                return id;
-            }
-        }
-        return null;
+        return typeof v === 'number' && v === v;
     };
 
-
     // How a label is written into Newick or Nexus, ported from the desktop's
     // ForesterUtil.santitizeStringForNH so both programs emit the same token
     // for the same name. Quoting rather than transliterating is what makes a
@@ -3181,13 +3459,6 @@
                     toNewHampshireHelper(node.children[i], i === l - 1);
                 }
                 nh += ")";
-            } else if (node._children) {
-                let ll = node._children.length;
-                nh += "(";
-                for (let ii = 0; ii < ll; ++ii) {
-                    toNewHampshireHelper(node._children[ii], ii === ll - 1);
-                }
-                nh += ")";
             }
             if (node.name && node.name.length > 0) {
                 nh += sanitizeLabelForNH(node.name);
@@ -3378,6 +3649,436 @@
     };
 
 
+    // --------------------------------------------------------------
+    // Protein domain architectures
+    // --------------------------------------------------------------
+    // The pure half of drawing <domain_architecture> beside the tips, ported
+    // from desktop Archaeopteryx (RenderableDomainArchitecture, TreePanel and
+    // AptxUtil at forester 416c705b; the spec is section D1 of the repo's
+    // TODO.md): which domains a threshold admits, where each box sits along
+    // the backbone, the Tableau palette and how names take their colours,
+    // the legend rows and the E-value readout. Everything a fixture can pin
+    // lives here and test/domain_test.js checks it against the numbers the
+    // desktop computed by running its own classes on apaf.xml. The SVG and
+    // the controls are archaeopteryx.js's.
+
+    const DOMAIN_PALETTE = ['#4E79A7', '#F28E2B', '#E15759', '#76B7B2', '#59A14F',
+        '#EDC948', '#B07AA1', '#FF9DA7', '#9C755F', '#BAB0AC'];   // Tableau 10
+    forester.DOMAIN_UNNAMED_COLOR = '#808080';                   // a domain with no name
+    forester.DOMAIN_EVALUE_EXPONENT_DEFAULT = -3;
+    forester.DOMAIN_EVALUE_EXPONENT_MIN = -20;
+    forester.DOMAIN_EVALUE_EXPONENT_MAX = 3;
+
+    function hexToRgb(hex) {
+        let n = parseInt(hex.substring(1), 16);
+        return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    }
+
+    function rgbToHex(rgb) {
+        return '#' + rgb.map(function (c) {
+            let s = Math.max(0, Math.min(255, Math.round(c))).toString(16);
+            return s.length < 2 ? '0' + s : s;
+        }).join('');
+    }
+
+    // Colour i of the qualitative sequence: Tableau 10 for the first ten,
+    // then the same ten shifted toward white (odd cycles) or black (even
+    // cycles), further with each cycle, capped at 0.55.
+    forester.domainQualitativeColor = function (i) {
+        let base = hexToRgb(DOMAIN_PALETTE[i % DOMAIN_PALETTE.length]);
+        let cycle = Math.floor(i / DOMAIN_PALETTE.length);
+        if (cycle === 0) {
+            return rgbToHex(base);
+        }
+        let t = Math.min(0.55, 0.2 * cycle);
+        let toward = (cycle % 2 === 1) ? 255 : 0;
+        return rgbToHex(base.map(function (c) {
+            return Math.round(c + t * (toward - c));
+        }));
+    };
+
+    forester.domainLighten = function (hex, t) {
+        return rgbToHex(hexToRgb(hex).map(function (c) {
+            return c + Math.round((255 - c) * t);
+        }));
+    };
+
+    forester.domainDarken = function (hex, t) {
+        return rgbToHex(hexToRgb(hex).map(function (c) {
+            return Math.round(c * (1 - t));
+        }));
+    };
+
+    // The ink a name is written in on its box: near-black on a light base,
+    // white on a dark one.
+    forester.domainLabelInk = function (hex) {
+        let c = hexToRgb(hex);
+        let lum = (0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]) / 255;
+        return lum > 0.55 ? '#141a1d' : '#ffffff';
+    };
+
+    forester.domainEvalueThreshold = function (exponent) {
+        return Math.pow(10, exponent);
+    };
+
+    // "10" with the exponent in superscript digits: 10⁻³, 10⁰, 10³.
+    const SUPERSCRIPT_DIGITS = ['⁰', '¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹'];
+    forester.domainEvalueLabel = function (exponent) {
+        let digits = String(Math.abs(exponent)).split('').map(function (d) {
+            return SUPERSCRIPT_DIGITS[+d];
+        }).join('');
+        return '10' + (exponent < 0 ? '⁻' : '') + digits;
+    };
+
+    function domainNumber(v) {
+        return (v === null || v === undefined || v === '') ? NaN : Number(v);
+    }
+
+    // The architecture a node carries: the first of its sequences that has
+    // one, provided its length is a positive integer -- without a length
+    // there is no backbone to draw on. The desktop refuses the whole file in
+    // that case; refusing input over a drawing attribute is the one kind of
+    // strictness this library does not copy, so the architecture is simply
+    // not drawn.
+    forester.domainArchitectureOf = function (node) {
+        if (!node.sequences) {
+            return null;
+        }
+        for (let i = 0; i < node.sequences.length; ++i) {
+            let da = node.sequences[i].domain_architecture;
+            if (da) {
+                let L = domainNumber(da.length);
+                return (Number.isInteger(L) && L > 0) ? da : null;
+            }
+        }
+        return null;
+    };
+
+    // The drawable domains of an architecture, in from order (equal froms
+    // keep file order). A malformed domain -- a coordinate missing or not an
+    // integer, to <= from, no E-value -- is left out and counted, never
+    // fatal; the caller reports the count once.
+    forester.domainArchitectureDomains = function (da) {
+        let domains = [];
+        let ignored = 0;
+        (da.domains || []).forEach(function (d) {
+            let from = domainNumber(d.from);
+            let to = domainNumber(d.to);
+            let e = domainNumber(d.confidence);
+            if (!Number.isInteger(from) || !Number.isInteger(to) || to <= from || !isFinite(e)) {
+                ignored++;
+                return;
+            }
+            domains.push({name: d.name ? String(d.name) : '', from: from, to: to, length: to - from + 1, evalue: e});
+        });
+        domains.sort(function (a, b) {
+            return a.from - b.from;
+        });
+        return {domains: domains, ignored: ignored};
+    };
+
+    // The tree's domain facts: tips carrying an architecture, the longest
+    // architecture (Lmax -- it sets one scale for every track and, counting
+    // every domain whatever its E-value, never moves with the threshold),
+    // the drawable domain count and the malformed count.
+    forester.domainArchitectureStats = function (tree) {
+        let stats = {tips: 0, maxLength: 0, domains: 0, ignored: 0};
+        forester.preOrderTraversalAll(tree, function (n) {
+            if (n.children) {
+                return;
+            }
+            let da = forester.domainArchitectureOf(n);
+            if (!da) {
+                return;
+            }
+            stats.tips++;
+            let L = Number(da.length);
+            if (L > stats.maxLength) {
+                stats.maxLength = L;
+            }
+            let dd = forester.domainArchitectureDomains(da);
+            stats.domains += dd.domains.length;
+            stats.ignored += dd.ignored;
+        });
+        return stats;
+    };
+
+    // What a threshold admits over the tips: the distinct drawn names sorted
+    // by UTF-16 code unit (the palette's order -- Java's string order,
+    // uppercase before lowercase, so DED sorts before Death), the drawn box
+    // count, the legend rows in first-appearance order (tips in the order
+    // given, domains in from order) each with its count of drawn boxes, and
+    // how many drawn boxes have no name. `tips` is a root, walked in
+    // preorder, or an array of tips in DISPLAY order -- the legend reads
+    // the way the eye goes down the tree, which a ladderized display does
+    // not do in data order.
+    forester.domainSummary = function (tips, exponent) {
+        let T = forester.domainEvalueThreshold(exponent);
+        let counts = Object.create(null);
+        let legend = [];
+        let boxes = 0;
+        let unnamed = 0;
+        let nodes = tips;
+        if (!Array.isArray(tips)) {
+            nodes = [];
+            forester.preOrderTraversalAll(tips, function (n) {
+                if (!n.children) {
+                    nodes.push(n);
+                }
+            });
+        }
+        nodes.forEach(function (n) {
+            let da = forester.domainArchitectureOf(n);
+            if (!da) {
+                return;
+            }
+            forester.domainArchitectureDomains(da).domains.forEach(function (d) {
+                if (d.evalue > T) {
+                    return;
+                }
+                boxes++;
+                if (d.name.length === 0) {
+                    unnamed++;
+                    return;
+                }
+                if (!(d.name in counts)) {
+                    counts[d.name] = 0;
+                    legend.push({name: d.name, count: 0});
+                }
+                counts[d.name]++;
+            });
+        });
+        legend.forEach(function (row) {
+            row.count = counts[row.name];
+        });
+        return {names: Object.keys(counts).sort(), boxes: boxes, legend: legend, unnamed: unnamed};
+    };
+
+    // One architecture's geometry: the backbone and the boxes the threshold
+    // admits, given its start x and the px per residue f. Residue r covers
+    // [(r-1) f, r f], so a domain from..to spans [start + (from-1) f,
+    // start + to f] and a domain 1..L is exactly the backbone (decided with
+    // the desktop 2026-09-12; until its 416c705b it placed at from f, one
+    // residue to the right). A box with no width is skipped.
+    forester.domainBoxes = function (da, start, f, exponent) {
+        let T = forester.domainEvalueThreshold(exponent);
+        let boxes = [];
+        forester.domainArchitectureDomains(da).domains.forEach(function (d) {
+            if (d.evalue > T) {
+                return;
+            }
+            let w = d.length * f;
+            if (!(w > 0) || !isFinite(w)) {
+                return;
+            }
+            boxes.push({name: d.name, x: start + ((d.from - 1) * f), w: w, from: d.from, to: d.to, evalue: d.evalue});
+        });
+        return {backbone: {x: start, w: Number(da.length) * f}, boxes: boxes};
+    };
+
+    // --------------------------------------------------------------
+    // Scale bar
+    // --------------------------------------------------------------
+    // A phylogram's scale bar spans a round number of branch-length units
+    // -- 1, 2 or 5 times a power of ten -- chosen so the bar comes out about
+    // targetPx long at pxPerUnit pixels per unit. Returns {length, label,
+    // px}, or null when the scale is unusable (zero, negative or infinite).
+    forester.scaleBarLength = function (pxPerUnit, targetPx) {
+        if (!(pxPerUnit > 0) || !isFinite(pxPerUnit)) {
+            return null;
+        }
+        let raw = (targetPx || 100) / pxPerUnit;
+        let k = Math.floor(Math.log10(raw));
+        let base = raw / Math.pow(10, k);
+        let nice = base < 1.5 ? 1 : (base < 3.5 ? 2 : (base < 7.5 ? 5 : 10));
+        let length = Number((nice * Math.pow(10, k)).toPrecision(2));
+        return {length: length, label: String(length), px: length * pxPerUnit};
+    };
+
+    // --------------------------------------------------------------
+    // Metadata tables
+    // --------------------------------------------------------------
+    // A table beside the tree -- TSV or CSV with a header row, the first
+    // column naming the tip -- joined onto the tips as node properties, so
+    // that everything downstream of a property sees the columns as if the
+    // file had carried them: the automatic Color-by and Shape candidates,
+    // the legends, the search fields, the node-data dialog, the phyloXML
+    // writer. Every other browser viewer takes such a table; it was the one
+    // input this library lacked (field review, 2026-09-13).
+
+    forester.METADATA_NAMESPACE = 'meta';
+
+    function splitDelimitedLine(line, delimiter) {
+        let out = [];
+        let cur = '';
+        let quoted = false;
+        for (let i = 0; i < line.length; ++i) {
+            let c = line.charAt(i);
+            if (quoted) {
+                if (c === '"') {
+                    if (line.charAt(i + 1) === '"') {   // a doubled quote is a literal one
+                        cur += '"';
+                        i++;
+                    } else {
+                        quoted = false;
+                    }
+                } else {
+                    cur += c;
+                }
+            } else if (c === '"') {
+                quoted = true;
+            } else if (c === delimiter) {
+                out.push(cur);
+                cur = '';
+            } else {
+                cur += c;
+            }
+        }
+        out.push(cur);
+        return out.map(function (s) {
+            return s.trim();
+        });
+    }
+
+    // Splits delimited text into its header and rows. The delimiter is
+    // whichever of tab, comma and semicolon occurs most in the header line
+    // (tab when none does); fields may be double-quoted; blank lines and
+    // lines starting with '#' are skipped; Windows line ends are fine.
+    // Header names and cells come back trimmed. Throws when there is no
+    // header or fewer than two columns.
+    forester.parseDelimitedTable = function (text) {
+        let lines = String(text || '').split(/\r?\n/).filter(function (l) {
+            return l.trim().length > 0 && l.charAt(0) !== '#';
+        });
+        if (lines.length === 0) {
+            throw new Error('the table is empty');
+        }
+        let delimiter = '\t';
+        let best = -1;
+        ['\t', ',', ';'].forEach(function (d) {
+            let n = lines[0].split(d).length - 1;
+            if (n > best) {
+                best = n;
+                delimiter = d;
+            }
+        });
+        let columns = splitDelimitedLine(lines[0], delimiter);
+        if (columns.length < 2) {
+            throw new Error('the table needs a header row with at least two columns: the tip name, then the data');
+        }
+        let rows = [];
+        for (let i = 1; i < lines.length; ++i) {
+            rows.push(splitDelimitedLine(lines[i], delimiter));
+        }
+        return {columns: columns, rows: rows, delimiter: delimiter};
+    };
+
+    // The property ref for a column. A header that already reads as a
+    // phyloXML ref (ns:local, no whitespace) is kept as it is; any other
+    // becomes "meta:" plus the header with its whitespace as '_' -- the
+    // display name prettifies that back to spaces, so "Collection Date"
+    // stays "Collection Date" in every menu.
+    forester.metadataColumnRef = function (header, index) {
+        let h = String(header || '').trim();
+        if (h.length === 0) {
+            h = 'column_' + (index + 1);
+        }
+        if (/^[A-Za-z0-9_]+:\S+$/.test(h)) {
+            return h;
+        }
+        return forester.METADATA_NAMESPACE + ':' + h.replace(/\s+/g, '_');
+    };
+
+    // Joins a table onto the tree's tips. The first column is the key,
+    // matched to the tip's name exactly, then case-insensitively. Every
+    // other column becomes one property per matched tip with a non-empty
+    // cell (applies_to node; the datatype is xsd:integer or xsd:double when
+    // every filled cell of the column is such a number, xsd:string
+    // otherwise). A property the tip already carries under the same ref is
+    // replaced -- the table wins. Returns what happened:
+    //   {columns: [{header, ref, datatype, filled}], tips, matchedTips,
+    //    unmatchedTips: [names], unmatchedRows: [keys], properties}
+    forester.joinMetadataTable = function (tree, text) {
+        let table = forester.parseDelimitedTable(text);
+        let tips = forester.getAllExternalNodes(tree);
+        let byName = Object.create(null);
+        let byLower = Object.create(null);
+        tips.forEach(function (n) {
+            if (n.name) {
+                byName[n.name] = n;
+                let lower = n.name.toLowerCase();
+                if (!byLower[lower]) {
+                    byLower[lower] = n;
+                }
+            }
+        });
+        let columns = [];
+        for (let j = 1; j < table.columns.length; ++j) {
+            let filled = table.rows.map(function (r) {
+                return r[j] === undefined ? '' : r[j];
+            }).filter(function (v) {
+                return v.length > 0;
+            });
+            let datatype = 'xsd:string';
+            if (filled.length > 0) {
+                if (filled.every(function (v) { return /^[+-]?\d+$/.test(v); })) {
+                    datatype = 'xsd:integer';
+                } else if (filled.every(function (v) { return VIS_NUMERIC_RE.test(v); })) {
+                    datatype = 'xsd:double';
+                }
+            }
+            columns.push({header: table.columns[j], ref: forester.metadataColumnRef(table.columns[j], j),
+                datatype: datatype, filled: 0});
+        }
+        let matched = new Set();
+        let unmatchedRows = [];
+        let properties = 0;
+        table.rows.forEach(function (r) {
+            let key = r[0] === undefined ? '' : r[0];
+            if (key.length === 0) {
+                return;
+            }
+            let tip = byName[key] || byLower[key.toLowerCase()];
+            if (!tip) {
+                unmatchedRows.push(key);
+                return;
+            }
+            matched.add(tip);
+            columns.forEach(function (col, k) {
+                let v = r[k + 1] === undefined ? '' : r[k + 1];
+                if (v.length === 0) {
+                    return;
+                }
+                if (!tip.properties) {
+                    tip.properties = [];
+                }
+                let existing = null;
+                for (let i = 0; i < tip.properties.length; ++i) {
+                    if (tip.properties[i].ref === col.ref) {
+                        existing = tip.properties[i];
+                        break;
+                    }
+                }
+                if (existing) {
+                    existing.value = v;
+                    existing.datatype = col.datatype;
+                    existing.applies_to = 'node';
+                } else {
+                    tip.properties.push({ref: col.ref, value: v, datatype: col.datatype, applies_to: 'node'});
+                }
+                col.filled++;
+                properties++;
+            });
+        });
+        let unmatchedTips = tips.filter(function (n) {
+            return !matched.has(n);
+        }).map(function (n) {
+            return n.name || '';
+        });
+        return {columns: columns, tips: tips.length, matchedTips: matched.size,
+            unmatchedTips: unmatchedTips, unmatchedRows: unmatchedRows, properties: properties};
+    };
+
     // --------------------------------------------------------------
     // Search engine
     // --------------------------------------------------------------
@@ -3390,16 +4091,6 @@
     // and ',' = OR / '+' = AND inside a text value. Used by archaeopteryx.js;
     // pure tree logic, no DOM -- tested by test/search_test.js.
 
-    const SEARCH_FIELD_LABELS = {
-        NN: 'Node Name',
-        TS: 'Taxonomy Scientific', TN: 'Taxonomy Common', TC: 'Taxonomy Code',
-        TI: 'Taxonomy Identifier', SY: 'Taxonomy Synonym', LN: 'Taxonomy Lineage',
-        SN: 'Seq Name', GN: 'Gene Name', SS: 'Gene Symbol', SA: 'Seq Accession',
-        MS: 'Molecular Sequence', DO: 'Domain', AN: 'Annotation', XR: 'Cross-Reference'
-    };
-    const SEARCH_TEXT_ORDER = ['TS', 'TN', 'TC', 'TI', 'SY', 'LN', 'SN', 'GN', 'SS', 'SA', 'DO', 'AN', 'XR', 'MS'];
-    // Fields folded into the "Any Text" umbrella (desktop omits MS + DO there).
-    const SEARCH_ANY_TEXT_KEYS = ['NN', 'TS', 'TN', 'TC', 'TI', 'SY', 'LN', 'SN', 'GN', 'SS', 'SA', 'AN', 'XR'];
     const SEARCH_NUMERIC_DATATYPES = new Set(['decimal', 'double', 'float', 'integer', 'int', 'long', 'short',
         'byte', 'unsignedint', 'unsignedlong', 'unsignedshort', 'unsignedbyte', 'nonnegativeinteger',
         'nonpositiveinteger', 'negativeinteger', 'positiveinteger']);
@@ -3407,24 +4098,124 @@
     function searchTaxa(n) { return (n.taxonomies && n.taxonomies.length) ? n.taxonomies : []; }
     function searchSeqs(n) { return (n.sequences && n.sequences.length) ? n.sequences : []; }
 
-    const SEARCH_TEXT_EXTRACTORS = {
-        NN: n => (n.name ? [n.name] : []),
-        TS: n => searchTaxa(n).map(t => t.scientific_name).filter(Boolean),
-        TN: n => searchTaxa(n).map(t => t.common_name).filter(Boolean),
-        TC: n => searchTaxa(n).map(t => t.code).filter(Boolean),
-        TI: n => searchTaxa(n).map(t => t.id && t.id.value).filter(Boolean),
-        SY: n => searchTaxa(n).reduce((a, t) => a.concat(t.synonyms || []), []).filter(Boolean),
-        LN: n => searchTaxa(n).reduce((a, t) => a.concat(t.lineage || []), []).filter(Boolean),
-        SN: n => searchSeqs(n).map(s => s.name).filter(Boolean),
-        GN: n => searchSeqs(n).map(s => s.gene_name).filter(Boolean),
-        SS: n => searchSeqs(n).map(s => s.symbol).filter(Boolean),
-        SA: n => searchSeqs(n).map(s => s.accession && s.accession.value).filter(Boolean),
-        MS: n => searchSeqs(n).map(s => s.mol_seq).filter(Boolean),
-        DO: n => searchSeqs(n).reduce((a, s) => a.concat((s.domain_architecture && s.domain_architecture.domains) ? s.domain_architecture.domains.map(d => d.name) : []), []).filter(Boolean),
-        AN: n => searchSeqs(n).reduce((a, s) => a.concat((s.annotations || []).reduce((b, an) => b.concat([an.desc, an.ref]), [])), []).filter(Boolean),
-        XR: n => searchSeqs(n).reduce((a, s) => a.concat((s.cross_references || []).reduce((b, x) => b.concat([x.value, x.source, x.comment]), [])), []).filter(Boolean)
+    // A search field is an object -- {label, numeric, extract(node, root)}
+    // and a few flags -- and nothing more: the field menu lists them, a spec
+    // carries one, the engine calls its extract. There are no field ids.
+    // Until 2026-09-12 every field was named by a two-letter code (NN, TS,
+    // SA, ...): the suffixes of the 2.x search syntax ("foo:NN"). 3.0.0
+    // replaced that syntax with the field menu, and the alphabet outlived it
+    // as ids until Christian spotted it. A field is multi-valued; any value
+    // matching is a match; root is needed only by Node Type.
+    //
+    // Flags: `anyText` -- "Any Text" ORs the field in (the molecular
+    // sequence and the domains stay out, as on the desktop); `always` -- in
+    // the menu even when no node carries it; `suggest: false` -- the value
+    // box does not offer its values as type-ahead (near-unique, huge);
+    // `metrics` -- needs the per-node depth / distance / clade size first.
+    function textField(label, extract, flags) {
+        return Object.assign({label: label, numeric: false, extract: extract}, flags || {});
+    }
+    function numericField(label, extract, flags) {
+        return Object.assign({label: label, numeric: true, extract: extract}, flags || {});
+    }
+
+    // The text fields of a node; the labels are the desktop's, verbatim.
+    const SEARCH_NODE_NAME = textField('Node Name', n => (n.name ? [n.name] : []), {always: true, anyText: true});
+    const SEARCH_TAXONOMY_SCIENTIFIC_NAME = textField('Taxonomy Scientific', n => searchTaxa(n).map(t => t.scientific_name).filter(Boolean), {anyText: true});
+    const SEARCH_TAXONOMY_COMMON_NAME = textField('Taxonomy Common', n => searchTaxa(n).map(t => t.common_name).filter(Boolean), {anyText: true});
+    const SEARCH_TAXONOMY_CODE = textField('Taxonomy Code', n => searchTaxa(n).map(t => t.code).filter(Boolean), {anyText: true});
+    const SEARCH_TAXONOMY_ID = textField('Taxonomy Identifier', n => searchTaxa(n).map(t => t.id && t.id.value).filter(Boolean), {anyText: true});
+    const SEARCH_TAXONOMY_SYNONYM = textField('Taxonomy Synonym', n => searchTaxa(n).reduce((a, t) => a.concat(t.synonyms || []), []).filter(Boolean), {anyText: true});
+    const SEARCH_TAXONOMY_LINEAGE = textField('Taxonomy Lineage', n => searchTaxa(n).reduce((a, t) => a.concat(t.lineage || []), []).filter(Boolean), {anyText: true});
+    const SEARCH_SEQUENCE_NAME = textField('Seq Name', n => searchSeqs(n).map(s => s.name).filter(Boolean), {anyText: true});
+    const SEARCH_GENE_NAME = textField('Gene Name', n => searchSeqs(n).map(s => s.gene_name).filter(Boolean), {anyText: true});
+    // phyloXML <sequence><symbol>: the gene symbol
+    const SEARCH_SEQUENCE_SYMBOL = textField('Gene Symbol', n => searchSeqs(n).map(s => s.symbol).filter(Boolean), {anyText: true});
+    const SEARCH_SEQUENCE_ACCESSION = textField('Seq Accession', n => searchSeqs(n).map(s => s.accession && s.accession.value).filter(Boolean), {anyText: true});
+    const SEARCH_DOMAIN = textField('Domain', n => searchSeqs(n).reduce((a, s) => a.concat((s.domain_architecture && s.domain_architecture.domains) ? s.domain_architecture.domains.map(d => d.name) : []), []).filter(Boolean));
+    const SEARCH_ANNOTATION = textField('Annotation', n => searchSeqs(n).reduce((a, s) => a.concat((s.annotations || []).reduce((b, an) => b.concat([an.desc, an.ref]), [])), []).filter(Boolean), {anyText: true});
+    const SEARCH_CROSS_REFERENCE = textField('Cross-Reference', n => searchSeqs(n).reduce((a, s) => a.concat((s.cross_references || []).reduce((b, x) => b.concat([x.value, x.source, x.comment]), [])), []).filter(Boolean), {anyText: true});
+    const SEARCH_MOLECULAR_SEQUENCE = textField('Molecular Sequence', n => searchSeqs(n).map(s => s.mol_seq).filter(Boolean), {suggest: false});
+    // in menu order
+    const SEARCH_TEXT_FIELDS = [
+        SEARCH_NODE_NAME, SEARCH_TAXONOMY_SCIENTIFIC_NAME, SEARCH_TAXONOMY_COMMON_NAME, SEARCH_TAXONOMY_CODE,
+        SEARCH_TAXONOMY_ID, SEARCH_TAXONOMY_SYNONYM, SEARCH_TAXONOMY_LINEAGE, SEARCH_SEQUENCE_NAME, SEARCH_GENE_NAME,
+        SEARCH_SEQUENCE_SYMBOL, SEARCH_SEQUENCE_ACCESSION, SEARCH_DOMAIN, SEARCH_ANNOTATION, SEARCH_CROSS_REFERENCE,
+        SEARCH_MOLECULAR_SEQUENCE
+    ];
+
+    // "Any Text": every anyText field above plus every custom property.
+    const SEARCH_ANY_TEXT = textField('Any Text', function (node) {
+        let out = [];
+        SEARCH_TEXT_FIELDS.forEach(function (f) {
+            if (f.anyText) out = out.concat(f.extract(node));
+        });
+        if (node.properties) {
+            for (let i = 0; i < node.properties.length; ++i) {
+                let p = node.properties[i];
+                if (!isInternalPropRef(p.ref) && p.value !== null && p.value !== undefined && p.value !== '') out.push(p.value);
+            }
+        }
+        return out;
+    }, {suggest: false});
+
+    const SEARCH_BRANCH_LENGTH = numericField('Branch Length', n => (typeof n.branch_length === 'number') ? [n.branch_length] : []);
+    const SEARCH_CONFIDENCE = numericField('Confidence', n => n.confidences ? n.confidences.map(c => c.value).filter(v => typeof v === 'number') : []);
+    const SEARCH_CLADE_SIZE = numericField('Clade Size (tips)', n => [n._srchClade], {metrics: true});
+    const SEARCH_CHILD_COUNT = numericField('Number of Children', n => [n.children ? n.children.length : 0]);
+    const SEARCH_DEPTH = numericField('Depth from Root', n => [n._srchDepth], {metrics: true});
+    const SEARCH_DISTANCE_FROM_ROOT = numericField('Distance from Root', n => [n._srchDist], {metrics: true});
+    const SEARCH_NODE_TYPE = textField('Node Type', function (node, root) {
+        let kids = node.children;
+        let isLeaf = !kids || kids.length === 0;
+        return [isLeaf ? 'leaf' : (node === root ? 'root' : 'internal')];
+    });
+
+    // The built-in fields by name, for a caller that asks "does this tree
+    // carry X?" -- the viewer's label presets test whether a field object is
+    // among availableSearchFields(tree), by identity. Property fields have
+    // no entry here: there is one per ref, made per tree.
+    forester.searchFields = {
+        anyText: SEARCH_ANY_TEXT,
+        nodeName: SEARCH_NODE_NAME,
+        taxonomyScientificName: SEARCH_TAXONOMY_SCIENTIFIC_NAME,
+        taxonomyCommonName: SEARCH_TAXONOMY_COMMON_NAME,
+        taxonomyCode: SEARCH_TAXONOMY_CODE,
+        taxonomyId: SEARCH_TAXONOMY_ID,
+        taxonomySynonym: SEARCH_TAXONOMY_SYNONYM,
+        taxonomyLineage: SEARCH_TAXONOMY_LINEAGE,
+        sequenceName: SEARCH_SEQUENCE_NAME,
+        geneName: SEARCH_GENE_NAME,
+        sequenceSymbol: SEARCH_SEQUENCE_SYMBOL,
+        sequenceAccession: SEARCH_SEQUENCE_ACCESSION,
+        domain: SEARCH_DOMAIN,
+        annotation: SEARCH_ANNOTATION,
+        crossReference: SEARCH_CROSS_REFERENCE,
+        molecularSequence: SEARCH_MOLECULAR_SEQUENCE,
+        branchLength: SEARCH_BRANCH_LENGTH,
+        confidence: SEARCH_CONFIDENCE,
+        cladeSize: SEARCH_CLADE_SIZE,
+        childCount: SEARCH_CHILD_COUNT,
+        depth: SEARCH_DEPTH,
+        distanceFromRoot: SEARCH_DISTANCE_FROM_ROOT,
+        nodeType: SEARCH_NODE_TYPE
     };
 
+    // One field per custom property ref; numeric when its declared datatype
+    // or, failing that, every one of its values says so.
+    function propertyField(ref, numeric) {
+        return {label: ref, numeric: numeric, extract: function (node) {
+            let out = [];
+            if (node.properties) {
+                for (let i = 0; i < node.properties.length; ++i) {
+                    let p = node.properties[i];
+                    if (p.ref === ref && p.value !== null && p.value !== undefined && p.value !== '') out.push(p.value);
+                }
+            }
+            return out;
+        }};
+    }
+
     function isInternalPropRef(ref) { return !ref || ref.indexOf('aptx:') === 0; }
 
     function datatypeIsNumeric(dt) {
@@ -3492,19 +4283,19 @@
     // dropdowns). Always exposes Any Text + Node Name; adds the text, numeric
     // and custom-property fields that are present, then structure fields.
     forester.availableSearchFields = function (root) {
-        let fields = [];
-        fields.push({ key: 'ANY', label: 'Any Text', numeric: false });
-        fields.push({ key: 'NN', label: SEARCH_FIELD_LABELS.NN, numeric: false });
-        if (!root) return fields;
+        let fields = [SEARCH_ANY_TEXT];
+        if (!root) {
+            SEARCH_TEXT_FIELDS.forEach(function (f) { if (f.always) fields.push(f); });
+            return fields;
+        }
 
-        let present = {};
+        let present = new Set();
         let hasBL = false, hasConf = false;
         let propRefs = {}; // ref -> { num, tot, dtNum, dtStr }
         forester.preOrderTraversalAll(root, function (n) {
-            for (let k = 0; k < SEARCH_TEXT_ORDER.length; ++k) {
-                let key = SEARCH_TEXT_ORDER[k];
-                if (!present[key] && SEARCH_TEXT_EXTRACTORS[key](n).length > 0) present[key] = true;
-            }
+            SEARCH_TEXT_FIELDS.forEach(function (f) {
+                if (!f.always && !present.has(f) && f.extract(n).length > 0) present.add(f);
+            });
             if (!hasBL && typeof n.branch_length === 'number' && n.branch_length >= 0) hasBL = true;
             if (!hasConf && n.confidences) {
                 for (let i = 0; i < n.confidences.length; ++i) {
@@ -3523,23 +4314,20 @@
             }
         });
 
-        for (let k = 0; k < SEARCH_TEXT_ORDER.length; ++k) {
-            let key = SEARCH_TEXT_ORDER[k];
-            if (present[key]) fields.push({ key: key, label: SEARCH_FIELD_LABELS[key], numeric: false });
-        }
-        if (hasBL) fields.push({ key: 'BL', label: 'Branch Length', numeric: true });
-        if (hasConf) fields.push({ key: 'CO', label: 'Confidence', numeric: true });
+        SEARCH_TEXT_FIELDS.forEach(function (f) {
+            if (f.always || present.has(f)) fields.push(f);
+        });
+        if (hasBL) fields.push(SEARCH_BRANCH_LENGTH);
+        if (hasConf) fields.push(SEARCH_CONFIDENCE);
         let refs = Object.keys(propRefs).sort();
         for (let i = 0; i < refs.length; ++i) {
             let r = propRefs[refs[i]];
             let numeric = r.dtStr ? false : (r.dtNum ? true : (r.tot > 0 && r.num === r.tot));
-            fields.push({ key: 'PROP:' + refs[i], label: refs[i], numeric: numeric, propRef: refs[i] });
+            fields.push(propertyField(refs[i], numeric));
         }
-        fields.push({ key: 'CS', label: 'Clade Size (tips)', numeric: true });
-        fields.push({ key: 'NC', label: 'Number of Children', numeric: true });
-        fields.push({ key: 'DE', label: 'Depth from Root', numeric: true });
-        if (hasBL) fields.push({ key: 'DR', label: 'Distance from Root', numeric: true });
-        fields.push({ key: 'NT', label: 'Node Type', numeric: false });
+        fields.push(SEARCH_CLADE_SIZE, SEARCH_CHILD_COUNT, SEARCH_DEPTH);
+        if (hasBL) fields.push(SEARCH_DISTANCE_FROM_ROOT);
+        fields.push(SEARCH_NODE_TYPE);
         return fields;
     };
 
@@ -3550,11 +4338,11 @@
             n._srchDepth = depth;
             let d = dist + (typeof n.branch_length === 'number' && n.branch_length > 0 ? n.branch_length : 0);
             n._srchDist = d;
-            let kids = n.children || n._children;
+            let kids = n.children;
             if (kids) for (let i = 0; i < kids.length; ++i) pre(kids[i], depth + 1, d);
         })(root, 0, 0);
         forester.postOrderTraversalAll(root, function (n) {
-            let kids = n.children || n._children;
+            let kids = n.children;
             if (!kids || kids.length === 0) { n._srchClade = 1; return; }
             let s = 0;
             for (let i = 0; i < kids.length; ++i) s += kids[i]._srchClade;
@@ -3562,51 +4350,6 @@
         });
     }
 
-    // Extract the value(s) of a field from a node (strings for text fields,
-    // numbers for the numeric ones). A field is multi-valued; any value matching
-    // is a match. root is needed only for the Node Type field.
-    forester.extractSearchValues = function (node, field, root) {
-        let key = field.key;
-        if (key === 'ANY') {
-            let out = [];
-            for (let i = 0; i < SEARCH_ANY_TEXT_KEYS.length; ++i) {
-                out = out.concat(SEARCH_TEXT_EXTRACTORS[SEARCH_ANY_TEXT_KEYS[i]](node));
-            }
-            if (node.properties) {
-                for (let i = 0; i < node.properties.length; ++i) {
-                    let p = node.properties[i];
-                    if (!isInternalPropRef(p.ref) && p.value !== null && p.value !== undefined && p.value !== '') out.push(p.value);
-                }
-            }
-            return out;
-        }
-        if (key === 'NT') {
-            let kids = node.children || node._children;
-            let isLeaf = !kids || kids.length === 0;
-            return [isLeaf ? 'leaf' : (node === root ? 'root' : 'internal')];
-        }
-        if (key.indexOf('PROP:') === 0) {
-            let out = [];
-            if (node.properties) {
-                for (let i = 0; i < node.properties.length; ++i) {
-                    let p = node.properties[i];
-                    if (p.ref === field.propRef && p.value !== null && p.value !== undefined && p.value !== '') out.push(p.value);
-                }
-            }
-            return out;
-        }
-        if (SEARCH_TEXT_EXTRACTORS[key]) return SEARCH_TEXT_EXTRACTORS[key](node);
-        switch (key) {
-            case 'BL': return (typeof node.branch_length === 'number') ? [node.branch_length] : [];
-            case 'CO': return node.confidences ? node.confidences.map(c => c.value).filter(v => typeof v === 'number') : [];
-            case 'CS': return [node._srchClade];
-            case 'NC': { let kids = node.children || node._children; return [kids ? kids.length : 0]; }
-            case 'DE': return [node._srchDepth];
-            case 'DR': return [node._srchDist];
-            default: return [];
-        }
-    };
-
     // Run one search spec { field, mode, value, value2, caseSensitive, inverse }
     // over the tree and return the Set of matching nodes.
     // A parsed tree is anchored on a SUPER-ROOT: a synthetic node whose single
@@ -3633,7 +4376,7 @@
         // values are unchanged; only the set of nodes considered is narrowed.
         let nodes = realRootOf(root);
         let field = spec.field;
-        if (field.key === 'CS' || field.key === 'DE' || field.key === 'DR' || field.key === 'NC') computeSearchMetrics(root);
+        if (field.metrics) computeSearchMetrics(root);
 
         let v = (spec.value === null || spec.value === undefined) ? '' : String(spec.value);
         v = v.replace(/\s+/g, ' ').trim();
@@ -3646,7 +4389,7 @@
             let lo = (b !== null) ? Math.min(a, b) : a;
             let hi = (b !== null) ? Math.max(a, b) : a;
             test = function (n) {
-                let vals = forester.extractSearchValues(n, field, root);
+                let vals = field.extract(n, root);
                 for (let i = 0; i < vals.length; ++i) {
                     let x = (typeof vals[i] === 'number') ? vals[i] : forester.parseFiniteDouble(vals[i]);
                     if (x !== null && numMatches(x, spec.mode, a, lo, hi)) return true;
@@ -3675,7 +4418,7 @@
             }
             if (!compiled.length) return result;
             test = function (n) {
-                let vals = forester.extractSearchValues(n, field, root);
+                let vals = field.extract(n, root);
                 for (let oi = 0; oi < compiled.length; ++oi) {
                     let ands = compiled[oi], ok = true;
                     for (let ai = 0; ai < ands.length; ++ai) {
@@ -3695,7 +4438,7 @@
             // Complement, scoped to nodes that actually carry this field.
             let inv = new Set();
             forester.preOrderTraversalAll(nodes, function (n) {
-                if (!result.has(n) && forester.extractSearchValues(n, field, root).length > 0) inv.add(n);
+                if (!result.has(n) && field.extract(n, root).length > 0) inv.add(n);
             });
             return inv;
         }
@@ -3703,13 +4446,14 @@
     };
 
     // Distinct, trimmed, sorted values of a specific text field across the tree,
-    // for the value-box autocomplete. Empty for numeric, Any Text, or Molecular
-    // Sequence (near-unique / huge). cap limits the list length (optional).
+    // for the value-box autocomplete. Empty for a numeric field and for the
+    // fields flagged suggest: false (Any Text; the molecular sequence, which
+    // is near-unique and huge). cap limits the list length (optional).
     forester.distinctSearchValues = function (root, field, cap) {
-        if (!root || !field || field.numeric || field.key === 'ANY' || field.key === 'MS') return [];
+        if (!root || !field || field.numeric || field.suggest === false) return [];
         let set = new Set();
         forester.preOrderTraversalAll(root, function (n) {
-            let vals = forester.extractSearchValues(n, field, root);
+            let vals = field.extract(n, root);
             for (let i = 0; i < vals.length; ++i) {
                 if (vals[i] !== null && vals[i] !== undefined) {
                     let v = String(vals[i]).trim();
@@ -4021,7 +4765,7 @@
         let hasInternalIntervals = false;
         let hasExternalIntervals = false;
         forester.preOrderTraversalAll(root, function (n) {
-            let isExt = !n.children && !n._children;
+            let isExt = !n.children;
             if (isExt) {
                 ++external;
             } else {
@@ -4497,7 +5241,7 @@
         let candidates = [];
         let anyConfidence = false;
         forester.preOrderTraversalAll(root, function (n) {
-            if (n === root || !(n.children || n._children)) {
+            if (n === root || !(n.children)) {
                 return;
             }
             if (n.confidences && n.confidences.length > 0) {