archaeopteryx 3.1.0 → 3.2.0

package/archaeopteryx.js

@@ -20,8 +20,8 @@
  *
  */
 
-// v 3.1.0
-// 2026-09-04
+// v 3.2.0
+// 2026-09-10
 //
 // Archaeopteryx.js is a software tool for the visualization and
 // analysis of highly annotated phylogenetic trees.

package/forester.js

@@ -20,8 +20,8 @@
  *
  */
 
-// v 3.1.0
-// 2026-09-04
+// v 3.2.0
+// 2026-09-10
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
 // 
@@ -1159,18 +1159,33 @@
         return style;
     };
 
-    // The boring part of every tip name. When the displayed names all share
-    // a long prefix ("Influenza A virus ..."), a shortener that keeps the
-    // first characters keeps exactly the characters that carry no
-    // information. This returns the longest common prefix of the displayed
-    // external names -- the label property's value where one is in effect,
-    // the node name otherwise -- cut back to the last separator so no word
-    // is split, and only when it is long enough to matter (>= 6 characters).
-    // The Short Names rendering strips it before truncating, so what
-    // survives is the part that tells the tips apart. The comparison is
-    // case-insensitive -- "Influenza A virus" and "Influenza A Virus" are
-    // the same boring prefix -- so callers must strip by LENGTH, comparing
-    // case-insensitively, not by exact match.
+    // The share of tips that must carry a prefix for it to count as boilerplate.
+    // A strict longest-common-prefix (1.0) lets a handful of oddly-named tips
+    // veto the strip for everyone else: on the BV-BRC influenza tree 13,096 of
+    // 13,246 tips share a 51-character prefix, but the other 0.8% drag the LCP
+    // down to "A" and nothing is stripped at all. 0.95 fixes that with real
+    // margin, and still refuses splits that would leave two groups of tips
+    // incomparable -- at 0.67 the same corpus strips the country code from 78%
+    // of tips while 22% keep their full names. DESIGNED JOINTLY WITH THE
+    // DESKTOP, which uses the identical value: this rule and its output are
+    // byte-identical across both programs, so the threshold is not ours alone
+    // to change.
+    const COMMON_PREFIX_QUANTILE = 0.95;
+
+    // The boring part of every tip name. When most displayed names share a
+    // long prefix ("Influenza A virus ..."), a shortener that keeps the first
+    // characters keeps exactly the characters that carry no information. This
+    // returns the longest prefix shared by at least COMMON_PREFIX_QUANTILE of
+    // the displayed external names -- the label property's value where one is
+    // in effect, the node name otherwise -- cut back to the last separator so
+    // no word is split, and only when it is long enough to matter
+    // (>= 6 characters). The Short Names rendering strips it before
+    // truncating, so what survives is the part that tells the tips apart. The
+    // comparison is case-insensitive -- "Influenza A virus" and "Influenza A
+    // Virus" are the same boring prefix -- so callers must strip by LENGTH,
+    // comparing case-insensitively, not by exact match. Tips that do NOT
+    // carry the prefix keep their full names; the caller's startsWith test
+    // handles that without needing to know about the quantile.
     forester.commonNamePrefix = function (tree, labelProperty) {
         let names = [];
         let slot = labelProperty ? {kind: 'property', ref: labelProperty} : null;
@@ -1192,29 +1207,72 @@
         if (names.length < 2) {
             return '';
         }
-        let prefix = names[0];
-        for (let k = 1; k < names.length && prefix.length > 0; ++k) {
-            let a = prefix.toLowerCase();
-            let b = names[k].toLowerCase();
+        // Any k names sharing a prefix are CONTIGUOUS once sorted, so
+        // comparing each sorted name with the one k-1 places later finds the
+        // longest prefix shared by k of them exactly -- no approximation, and
+        // O(n log n + n*L) rather than the quadratic scan the obvious reading
+        // suggests. At q = 1.0, k = n and this reduces to the strict LCP.
+        let lower = names.map(function (s) {
+            return s.toLowerCase();
+        }).sort();
+        let n = lower.length;
+        let k = Math.ceil(COMMON_PREFIX_QUANTILE * n);
+        if (k < 2) {
+            k = 2;
+        }
+        if (k > n) {
+            k = n;
+        }
+        let bestLen = 0;
+        let bestIdx = -1;
+        for (let i = 0; i + k - 1 < n; ++i) {
+            let a = lower[i];
+            let b = lower[i + k - 1];
             let max = Math.min(a.length, b.length);
-            let i = 0;
-            while (i < max && a.charCodeAt(i) === b.charCodeAt(i)) {
-                ++i;
+            let j = 0;
+            while (j < max && a.charCodeAt(j) === b.charCodeAt(j)) {
+                ++j;
             }
-            if (i < prefix.length) {
-                prefix = prefix.substring(0, i);
+            if (j > bestLen) {
+                bestLen = j;
+                bestIdx = i;
             }
         }
-        if (prefix.length === 0) {
+        if (bestLen === 0) {
+            return '';
+        }
+        let lowerPrefix = lower[bestIdx].substring(0, bestLen);
+        // Casing comes from the first name in TRAVERSAL order that carries the
+        // prefix. At q = 1.0 that is names[0], which is exactly what the
+        // strict-LCP version returned, so the two agree character for
+        // character -- and the desktop mirrors this traversal order
+        // deliberately, so the two programs do too.
+        let prefix = null;
+        let carriers = [];
+        for (let ci = 0; ci < names.length; ++ci) {
+            let name = names[ci];
+            if (name.length >= bestLen
+                && name.substring(0, bestLen).toLowerCase() === lowerPrefix) {
+                if (prefix === null) {
+                    prefix = name.substring(0, bestLen);
+                }
+                carriers.push(name);
+            }
+        }
+        if (prefix === null) {
             return '';
         }
         // Trim back to the last separator ONLY when the prefix actually
         // splits a word -- "ABC_ho" against "ABC_house"/"ABC_horse" does,
         // "Influenza A virus" against "...virus A/x" and "...virus(A/y)"
-        // does not, whatever character each name continues with.
+        // does not, whatever character each name continues with. Only the
+        // names that CARRY the prefix get a say: one that does not share it
+        // says nothing about whether the prefix splits a word, and letting it
+        // vote throws the prefix away -- 19 tips of "ABCDEFG_..."/"ABCDEFG-..."
+        // plus one unrelated longer tip yields "" instead of "ABCDEFG".
         let alnum = /[A-Za-z0-9]/;
         let splitsWord = alnum.test(prefix.charAt(prefix.length - 1))
-            && names.some(function (name) {
+            && carriers.some(function (name) {
                 return name.length > prefix.length && alnum.test(name.charAt(prefix.length));
             });
         if (splitsWord) {
@@ -1792,6 +1850,35 @@
         return (lo !== null && hi !== null) ? [lo, hi] : null;
     }
 
+    // Nexus/Newick quoting: a quoted token is wrapped in a matching pair, and a
+    // literal quote INSIDE it is written twice. Reading one back therefore
+    // means removing one matching outer pair and un-doubling what is inside --
+    // 'Seba''s bat' is the single label "Seba's bat", not "Sebas bat", which is
+    // what stripping every quote gave. The doubling is per quote, so a token
+    // holding two escapes in a row un-doubles to two literal quotes; a pass
+    // that removes quotes wholesale loses both.
+    //
+    // A token that is NOT well-formed -- an odd number of quotes, no closing
+    // quote, a quote in the middle of a bare word -- is not a quoted token at
+    // all. Those keep the old lenient behaviour of dropping stray quotes rather
+    // than throwing: a viewer that refuses to open a file teaches the user
+    // nothing, and Nexus in the wild is written by many programs. Strict on
+    // output, lenient on input. Matches the desktop (0.11.141+).
+    function unquoteLabel(s) {
+        if (s === null || s === undefined) {
+            return s;
+        }
+        let t = String(s).trim();
+        let len = t.length;
+        if (len > 1) {
+            let q = t.charAt(0);
+            if ((q === "'" || q === '"') && t.charAt(len - 1) === q) {
+                return t.substring(1, len - 1).split(q + q).join(q);
+            }
+        }
+        return t.replace(/['"]+/g, '');
+    }
+
     function stripValueQuotes(v) {
         if (v.length >= 2
             && ((v.charAt(0) === '"' && v.charAt(v.length - 1) === '"')
@@ -1986,6 +2073,19 @@
         let in_double_q = false;
         let in_single_q = false;
         let buffer = '';
+        // In a quoted label a literal quote is DOUBLED. The tokenizer splits
+        // on quotes, so a doubled one arrives as two quote elements with only
+        // empty strings between them -- that is the signature. Seeing it means
+        // 'emit one quote and stay inside the run', not 'close the run': the
+        // run continuing is what keeps the label in one piece, and emitting
+        // the character is what stops the apostrophe being swallowed.
+        let doubledQuoteEnd = function (at, qch) {
+            let j = at + 1;
+            while (j < ssl && ss[j] === '') {
+                ++j;
+            }
+            return (j < ssl && ss[j] === qch) ? j : -1;
+        };
         for (let i = 0; i < ssl; ++i) {
             let element = ss[i].replace(/\s+/g, '');
 
@@ -1993,25 +2093,37 @@
                 if (!in_double_q) {
                     in_double_q = true;
                 } else {
-                    in_double_q = false;
-                    if (x.name && x.name.length > 0) {
-                        x.name = x.name + buffer;
+                    let dq = doubledQuoteEnd(i, '"');
+                    if (dq > -1) {
+                        buffer += '"';
+                        i = dq;
                     } else {
-                        x.name = buffer;
+                        in_double_q = false;
+                        if (x.name && x.name.length > 0) {
+                            x.name = x.name + buffer;
+                        } else {
+                            x.name = buffer;
+                        }
+                        buffer = '';
                     }
-                    buffer = '';
                 }
             } else if (element === "'" && !in_double_q) {
                 if (!in_single_q) {
                     in_single_q = true;
                 } else {
-                    in_single_q = false;
-                    if (x.name && x.name.length > 0) {
-                        x.name = x.name + buffer;
+                    let dq = doubledQuoteEnd(i, "'");
+                    if (dq > -1) {
+                        buffer += "'";
+                        i = dq;
                     } else {
-                        x.name = buffer;
+                        in_single_q = false;
+                        if (x.name && x.name.length > 0) {
+                            x.name = x.name + buffer;
+                        } else {
+                            x.name = buffer;
+                        }
+                        buffer = '';
                     }
-                    buffer = '';
                 }
             } else {
                 if (in_double_q || in_single_q) {
@@ -2284,10 +2396,14 @@
                     throw new Error(NEXUS_FORMAT_ERR + 'ill-formatted translate table entry: "'
                         + pair.trim() + '" -- is the Translate sub-command terminated with a ";"?');
                 }
-                let value = m[2].replace(/['"]+/g, '').trim();
+                // The sub-command terminator comes off BEFORE unquoting, or a
+                // well-formed quoted value followed by ';' would not look
+                // well-formed and would fall to the lenient path.
+                let value = m[2].trim();
                 if (value.endsWith(';')) {
-                    value = value.slice(0, -1);
+                    value = value.slice(0, -1).trim();
                 }
+                value = unquoteLabel(value);
                 translateMap[m[1]] = value;
             });
         }
@@ -2371,14 +2487,38 @@
             for (let id in seqs) {
                 seqsByKey[joinKey(id)] = seqs[id];
             }
-            forester.getAllExternalNodes(phy).forEach(function (node) {
+            let externals = forester.getAllExternalNodes(phy);
+            // A bare integer tip name counts as a TAXLABELS index only when
+            // the WHOLE tree reads as index references: every tip a bare
+            // integer AND every one of them in range. All-or-nothing, because
+            // deciding it per tip fails silently and plausibly -- against six
+            // labels, ((a,b,c),(1,2,3)) renamed just the three integers and
+            // handed back a tree whose every tip was DUPLICATED, which still
+            // parses and still renders; and a single out-of-range index left a
+            // half-renamed tree behind for the same reason. Both are reachable
+            // through our own writer: save as Nexus, reopen. So if any tip is
+            // not an index, none of them are. Matches the desktop (0.11.140+).
+            // A TRANSLATE entry still wins wherever it applies -- it is the
+            // explicit mechanism, this is only the heuristic.
+            let indexed = taxlabels.length > 0 && externals.every(function (node) {
+                if (node.name && translateMap[node.name] !== undefined) {
+                    return true;
+                }
+                if (!node.name || !/^\d+$/.test(node.name)) {
+                    return false;
+                }
+                let i = parseInt(node.name, 10);
+                return i > 0 && i <= taxlabels.length;
+            });
+            externals.forEach(function (node) {
                 if (node.name && translateMap[node.name] !== undefined) {
                     node.name = translateMap[node.name];
-                } else if (taxlabels.length > 0 && node.name && /^\d+$/.test(node.name)) {
-                    let i = parseInt(node.name, 10);
-                    if (i > 0 && i <= taxlabels.length) {
-                        node.name = taxlabels[i - 1].replace(/['"]+/g, '');
-                    }
+                } else if (indexed) {
+                    // The TAXLABELS tokenizer has already removed the outer
+                    // quotes and un-doubled what was inside, so the label is
+                    // used as-is: stripping quotes again here would undo the
+                    // un-doubling and drop the apostrophe a second time.
+                    node.name = taxlabels[parseInt(node.name, 10) - 1];
                 }
                 if (node.name) {
                     let s = seqsByKey[joinKey(node.name)];
@@ -2457,7 +2597,7 @@
                     inTree = true;
                     let nm = TREE_NAME_RE.exec(line);
                     if (nm) {
-                        name = nm[1].replace(/['"]+/g, '');
+                        name = unquoteLabel(nm[1]);
                     }
                     let rm = ROOTEDNESS_RE.exec(line);
                     if (rm) {
@@ -2489,24 +2629,56 @@
                     // silently sheared such labels apart and shifted every
                     // numeric tip onto the wrong name. ';' (unquoted) ends
                     // the sub-command.
+                    //
+                    // A quote OPENS a run only at a TOKEN BOUNDARY. Inside a
+                    // word it is just a character -- an unquoted O'Neil must
+                    // not open a run and swallow the rest of the line, the
+                    // terminating ';' included, which is what the first
+                    // version of this tokenizer did: it merged every remaining
+                    // label into one and left the other tips as bare numbers.
                     let tok = '';
                     let q = null;
+                    let closed = false; // this token already held a quoted run
                     let push = function () {
                         if (tok.length > 0 && tok.toLowerCase() !== 'taxlabels') {
                             taxlabels.push(tok);
                         }
                         tok = '';
+                        closed = false;
                     };
                     for (let ci = 0; ci < line.length; ++ci) {
                         let ch = line.charAt(ci);
                         if (q) {
                             if (ch === q) {
                                 q = null;
+                                closed = true;
                             } else {
                                 tok += ch;
                             }
                         } else if (ch === "'" || ch === '"') {
-                            q = ch;
+                            if (tok.length === 0 && !closed) {
+                                q = ch;
+                            } else if (closed) {
+                                // A quote directly after a closing one is the
+                                // doubled Nexus escape: emit ONE literal quote
+                                // and let the run CONTINUE. The continuing is
+                                // what keeps a quoted label holding an
+                                // apostrophe in one piece instead of splitting
+                                // it at the space (that was N1); emitting the
+                                // character is the un-doubling half, deferred
+                                // until both programs could land it together.
+                                tok += ch;
+                                q = ch;
+                            } else {
+                                // A quote in the middle of a BARE word is not
+                                // an escape and not a delimiter -- an unquoted
+                                // token may not legally hold one at all. It is
+                                // dropped rather than kept, which is the older
+                                // lenient behaviour and is SHARED with the
+                                // desktop; keeping it here would be a new
+                                // divergence, not a fix.
+                                void ch;
+                            }
                         } else if (ch === ' ') {
                             push();
                         } else if (ch === ';') {
@@ -2943,16 +3115,55 @@
     };
 
 
+    // 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
+    // save-and-reopen lossless: the previous rule mapped every quote, comma,
+    // paren and space to '_', which no reader can undo, so a tip named
+    // "Cooper's Hawk" came back "Cooper_s_Hawk".
+    //
+    // The one case that still loses information is a name carrying BOTH quote
+    // styles: there is no quote character left to wrap it in, so the
+    // apostrophes become backticks. The desktop does the same, deliberately;
+    // that case is a JOINT open item and is NOT to be fixed on one side.
+    //
+    // Note the asymmetry with the READER: a doubled '' is how a quote is
+    // escaped INSIDE a quoted token, and our reader un-doubles it, but neither
+    // writer produces that form -- both sidestep it by switching quote style.
+    // Reading a form you do not write is intentional here.
+    function sanitizeLabelForNH(s) {
+        let t = String(s).replace(/\s+/g, ' ').trim();
+        let hasSingle = t.indexOf("'") > -1;
+        let hasDouble = t.indexOf('"') > -1;
+        if (hasSingle && hasDouble) {
+            return "'" + t.replace(/'/g, '`') + "'";
+        }
+        if (hasSingle) {
+            return '"' + t + '"';
+        }
+        if (hasDouble || /[\s,():;[\]]/.test(t)) {
+            return "'" + t + "'";
+        }
+        return t;
+    }
+
     /**
      * To convert a phylogentic tree object to a New Hampshire (Newick) formatted string.
      *
      * @param phy - A phylogentic tree object.
      * @param decPointsMax - Maximal number of decimal points for branch lengths (optional)
-     * @param replaceChars - To replace illegal characters (),:;"' instead of surrounding with quotation marks
+     * @param replaceChars - RETIRED 2026-09-10 and ignored. It used to map
+     *        every space, comma, paren, colon, semicolon, bracket and quote to
+     *        '_', which no reader can undo: a tip named "Cooper's Hawk" was
+     *        written Cooper_s_Hawk and came back that way. Labels are now
+     *        always quoted instead, by the same rule the desktop uses, so a
+     *        save-and-reopen keeps the name. The parameter is still accepted
+     *        so positional callers keep working.
      * @param writeConfidences - to write confidence values in brackets
      * @returns {*} - a New Hampshire (Newick) formatted string.
      */
     forester.toNewHampshire = function (phy, decPointsMax, replaceChars, writeConfidences) {
+        void replaceChars; // retired: see the note above; labels are always quoted now
         let nh = "";
         if (phy.children && phy.children.length === 1) {
             toNewHampshireHelper(phy.children[0], true);
@@ -2979,22 +3190,7 @@
                 nh += ")";
             }
             if (node.name && node.name.length > 0) {
-                if (replaceChars === true) {
-                    nh += replaceUnsafeChars(node.name);
-                } else {
-                    let myName = node.name.replace(/\s+/g, ' ');
-                    if (/[\s,():;'"[\]]/.test(myName)) {
-                        if ((myName.indexOf('"') > -1) && (myName.indexOf("'") > -1)) {
-                            nh += '"' + myName.replace(/"/g, "'") + '"';
-                        } else if (myName.indexOf('"') > -1) {
-                            nh += "'" + myName + "'";
-                        } else {
-                            nh += '"' + myName + '"';
-                        }
-                    } else {
-                        nh += myName;
-                    }
-                }
+                nh += sanitizeLabelForNH(node.name);
             }
             if (node.branch_length !== undefined && node.branch_length !== null) {
                 if (decPointsMax && decPointsMax > 0) {
@@ -3015,9 +3211,6 @@
             }
         }
 
-        function replaceUnsafeChars(str) {
-            return str.replace(/[\s,():;'"[\]]+/g, '_');
-        }
     };
 
     // Writes a phylogeny as a Nexus-formatted string, ported from the
@@ -3029,11 +3222,16 @@
     // carrying the tree and its alignment in one file is the point of Nexus,
     // and parseNexus reads the alignment back onto the tips.
     forester.toNexus = function (phy, decPointsMax, writeConfidences) {
-        // the same replacement toNewHampshire applies, so the TaxLabels and
-        // Matrix labels match the tree's tip tokens exactly
-        function safeLabel(s) {
-            return s.replace(/[\s,():;'"[\]]+/g, '_');
-        }
+        // The TaxLabels tokens, the Matrix row labels and the tree's tip
+        // tokens must be byte-identical or nothing can join them back up, so
+        // all three go through sanitizeLabelForNH -- the same helper
+        // toNewHampshire writes the tree with.
+        //
+        // nexusLabel returns the label UNQUOTED, because it is also assigned
+        // to node.name for a nameless tip and toNewHampshire quotes it again
+        // on the way out. The old '_' substitution was idempotent so applying
+        // it twice was harmless; quoting is not, and would emit "'a b'"
+        // wrapped in quotes a second time.
 
         // label preference as on the desktop: name, then taxonomy
         // (code/scientific/common), then sequence (name/symbol/gene)
@@ -3051,7 +3249,7 @@
             if (!s) {
                 s = 'node' + (i + 1); // an empty TaxLabels token would not parse back
             }
-            return safeLabel(s);
+            return s;
         }
 
         let ext = forester.getAllExternalNodes(phy).reverse();
@@ -3071,7 +3269,7 @@
         s += ' Dimensions NTax=' + ext.length + ';\n';
         s += ' TaxLabels';
         ext.forEach(function (node, i) {
-            s += ' ' + nexusLabel(node, i);
+            s += ' ' + sanitizeLabelForNH(nexusLabel(node, i));
         });
         s += ';\n';
         s += 'End;\n';
@@ -3086,7 +3284,7 @@
             for (let j = 0; j < node.sequences.length; ++j) {
                 let q = node.sequences[j];
                 if (q.mol_seq && q.mol_seq.is_aligned && q.mol_seq.value) {
-                    rows.push({label: nexusLabel(node, i), value: q.mol_seq.value});
+                    rows.push({label: sanitizeLabelForNH(nexusLabel(node, i)), value: q.mol_seq.value});
                     nchar = Math.max(nchar, q.mol_seq.value.length);
                     if (!datatype && (q.type === 'protein' || q.type === 'dna' || q.type === 'rna')) {
                         datatype = q.type;
@@ -3121,8 +3319,10 @@
         }
 
         s += 'Begin Trees;\n';
-        let treeName = phy.name ? String(phy.name).replace(/['"]+/g, '').trim() : '';
-        s += ' Tree ' + (treeName ? ("'" + treeName + "'") : 'tree1') + '=';
+        // the tree name was stripped of its quotes for the same reason the tip
+        // names were transliterated, and loses an apostrophe the same way
+        let treeName = phy.name ? String(phy.name).trim() : '';
+        s += ' Tree ' + (treeName ? sanitizeLabelForNH(treeName) : 'tree1') + '=';
         s += (phy.rooted === false) ? '[&U]' : '[&R]';
         let nh = forester.toNewHampshire(phy, decPointsMax, true, writeConfidences);
         renamed.forEach(function (node) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Archaeopteryx.js is a software tool for the visualization and analysis of highly annotated phylogenetic trees.",
   "main": "archaeopteryx.js",
   "types": "archaeopteryx.d.ts",