archaeopteryx 3.6.0 → 3.7.0

package/README.md

@@ -322,6 +322,38 @@ a Newick or Nexus download never puts one where a support value goes.
    gene families. *PLOS ONE*, 15(5), e0232950.
    <https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0232950>
 
+## Representative tips
+
+A large tree often holds many near-identical tips. The tool row's
+**representative tips** button thins them out the way the desktop
+Archaeopteryx's Tools → Select Representative Tips does: the tips are grouped
+into the largest clades whose tips are all close to each other, and one tip of
+each group is kept. Distance is patristic, the sum of the branch lengths on
+the path between two tips; in a tree without branch lengths it counts edges.
+
+The dialog takes either a **distance cutoff**, and no two tips of a group are
+then farther apart than it, or a **target number** of representatives, for
+which the cutoff giving the nearest count the tree allows is used (a tie keeps
+more tips; the count reached is reported). A distance cutoff needs branch
+lengths. The tip kept is the group's **most central** one (the medoid, with
+the smallest summed distance to its group-mates) or its **most divergent** one
+(the longest terminal branch). Tips that are selected or found by a search can
+be kept whatever their group: they stand in for their group's representative,
+so more tips than the target may stay.
+
+The tips kept show as search A's hits, with its colour, hit count and
+step-through, and a summary offers **Create tree**: a tree of only those tips,
+added to the tree picker and opened drawn as the tree was (phylogram, aligned
+or cladogram). It is named after the tree and the count, as in
+`mammals_233reps`, and its description says how it was made. An internal node
+left with one child is replaced by that child, whose branch gains the node's
+length; the new root keeps the original root's own branch length. The original
+tree is not changed.
+
+The grouping and the tips kept are the desktop's: they match its own results
+on 129 generated trees in 5,666 settings (`test/fixtures/rep-contract.tsv`,
+made by running the desktop's code).
+
 ## Metadata tables
 
 A tree file rarely carries everything known about its tips. A **metadata

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.6.0
+// v 3.7.0
 // 2026-09-10
 //
 // Archaeopteryx.js is a software tool for the visualization and
@@ -103,7 +103,7 @@ function (root, d3, forester, phyloXml) {
     // IIFE's own function name -- a plain object says what it is.)
     let archaeopteryx = {};
 
-    const VERSION = '3.6.0';
+    const VERSION = '3.7.0';
     const WEBSITE = 'https://cmzmasek.github.io/archaeopteryx-js/';
     const DESKTOP_WEBSITE = 'https://cmzmasek.github.io/archaeopteryx/';
     const SOURCE_WEBSITE = 'https://github.com/cmzmasek/archaeopteryx-js';
@@ -380,6 +380,8 @@ function (root, d3, forester, phyloXml) {
     const INTERNAL_LABEL_CB = 'intl_cb';
     const LABEL_COLOR_SELECT_MENU = 'lcs_menu';
     const MIDPOINT_ROOT_BUTTON = 'midpointr_b';
+    const REPRESENTATIVES_BUTTON = 'reps_b';
+    const REPRESENTATIVES_DIALOG = 'reps_dialog';
     const MAD_CITATION = 'Tria F, Landan G, Dagan T. Phylogenetic rooting using minimal ancestor deviation. Nature Ecology and Evolution. 2017;1:0193';
     const UNCOLLAPSE_ALL_BUTTON = 'uncollapse_all_b';
     const TREE_PREV_BUTTON = 'tree_prev_b';
@@ -5724,6 +5726,11 @@ function (root, d3, forester, phyloXml) {
             _baseSvg = d3.select(containerEl).append('svg')
                 .attr('width', _displayWidth)
                 .attr('height', _displayHeight)
+                // an inline svg sits on a text baseline, and the room left
+                // under it for descenders makes a container sized to the
+                // svg a few pixels taller than the svg itself -- enough to
+                // make a full-window page scroll
+                .style('display', 'block')
                 .call(_zoomListener)
                 // d3.zoom binds its own double-click-to-zoom, which scales the
                 // picture -- fonts and all -- and so behaves like the wheel
@@ -9434,6 +9441,297 @@ function (root, d3, forester, phyloXml) {
         }
     }
 
+    // ---- representative tips ------------------------------------------------
+    //
+    // The desktop's Tools > Select Representative Tips, from the tool row: a
+    // dialog takes a distance cutoff or a target count, the representative to
+    // keep and whether the selected and found tips stay; the tips kept show
+    // as search A's hits, and can be cut out into a new tree in the tree
+    // picker (the desktop's new tab). The choosing is
+    // forester.selectRepresentativeTips, held to the desktop's own results by
+    // test/fixtures/rep-contract.tsv.
+
+    // the dialog's inputs, remembered while the page is open (the desktop
+    // remembers them for its session)
+    let _repsInputs = {byCutoff: true, cutoff: '0.05', target: '100', pickIndex: 0};
+
+    // what the viewer writes onto a tree's nodes, left off a tree cut out of it
+    const VIEW_NODE_FIELDS = ['viewId', 'collapsed', 'x', 'y', 'x0', 'y0', 'id', 'hide', 'hasVis', 'distToRoot',
+        'ux', 'uy', 'uangle', '_style', '_suppDot', '_extLabelText', '_eventText', '_confText', '_blText'];
+
+    // the whole tree's tip count, counted again only when the tree changes
+    // (every change makes new _basicTreeProperties)
+    let _repsTipCount = {properties: null, count: 0};
+
+    function wholeTreeTipCount() {
+        if (_repsTipCount.properties !== _basicTreeProperties) {
+            _repsTipCount = {
+                properties: _basicTreeProperties,
+                count: _root_const ? forester.getAllExternalNodes(_root_const).length : 0
+            };
+        }
+        return _repsTipCount.count;
+    }
+
+    // why representative tips cannot be selected now, or null
+    function representativesBlockedReason() {
+        if (_in_subtree) {
+            return 'return to the whole tree to select representative tips';
+        }
+        if (!_root_const || wholeTreeTipCount() < 3) {
+            return 'the tree needs at least three tips to select representatives';
+        }
+        return null;
+    }
+
+    function repsElement(parent, tag, className, text) {
+        let e = document.createElement(tag);
+        if (className) {
+            e.className = className;
+        }
+        if (text !== undefined) {
+            e.textContent = text;
+        }
+        parent.appendChild(e);
+        return e;
+    }
+
+    function repsButton(parent, label, primary, action) {
+        let b = repsElement(parent, 'button', 'aptx-reps-button' + (primary ? ' aptx-reps-primary' : ''), label);
+        b.type = 'button';
+        b.addEventListener('click', action);
+        return b;
+    }
+
+    // Java's Double.parseDouble and Integer.parseInt, which read the desktop's
+    // fields: null for what they refuse
+    function javaParseDouble(s) {
+        let m = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)[fFdD]?$/.exec(s);
+        if (m) {
+            return Number(m[1]);
+        }
+        return /^[+-]?(?:Infinity|NaN)$/.test(s) ? Number(s) : null;
+    }
+
+    function javaParseInt(s) {
+        if (!/^[+-]?\d+$/.test(s)) {
+            return null;
+        }
+        let v = Number(s);
+        return (v < -2147483648 || v > 2147483647) ? null : v;
+    }
+
+    function representativesButtonPressed() {
+        if (representativesBlockedReason()) {
+            return;
+        }
+        // the selected and found tips can be kept; taken now, before the
+        // result replaces search A's hits
+        let protectable = [];
+        let seen = new Set();
+        [_selectedNodes, _foundNodes0, _foundNodes1].forEach(function (nodes) {
+            (nodes || []).forEach(function (n) {
+                if ((!n.children || n.children.length === 0) && !seen.has(n)) {
+                    seen.add(n);
+                    protectable.push(n);
+                }
+            });
+        });
+        showRepresentativesDialog(_treeData, forester.hasUsableBranchLengths(_treeData), protectable);
+    }
+
+    // The desktop's input dialog, its texts and checks included; a distance
+    // cutoff needs branch lengths.
+    function showRepresentativesDialog(phy, hasLengths, protectable) {
+        let shell = makeDialogShell(REPRESENTATIVES_DIALOG, 'Select representative tips', 330);
+        let body = shell.body;
+        body.classList.add('aptx-reps');
+        let startByCutoff = hasLengths && _repsInputs.byCutoff;
+
+        repsElement(body, 'div', 'aptx-reps-lead', 'Select one representative per group of similar tips:');
+        let choice = function (type, label, checked, disabled) {
+            let row = repsElement(body, 'label', 'aptx-reps-choice' + (disabled ? ' aptx-reps-disabled' : ''));
+            let input = repsElement(row, 'input');
+            input.type = type;
+            input.name = REPRESENTATIVES_DIALOG + '_' + type;
+            input.checked = checked;
+            input.disabled = disabled;
+            repsElement(row, 'span', null, label);
+            return input;
+        };
+        let byCutoff = choice('radio', 'By distance cutoff', startByCutoff, !hasLengths);
+        let byTarget = choice('radio', 'By target number of representatives', !startByCutoff, false);
+        if (!hasLengths) {
+            repsElement(body, 'div', 'aptx-reps-note',
+                'This tree has no branch lengths, so only "target number" is available.');
+        }
+
+        repsElement(body, 'div', 'aptx-dialog-head', 'Value');
+        let value = repsElement(body, 'input', 'aptx-reps-input');
+        value.type = 'text';
+        value.spellcheck = false;
+        value.autocomplete = 'off';
+        value.value = startByCutoff ? _repsInputs.cutoff : _repsInputs.target;
+        let hint = repsElement(body, 'div', 'aptx-reps-note');
+
+        repsElement(body, 'div', 'aptx-dialog-head', 'Representative');
+        let pick = repsElement(body, 'select', 'aptx-reps-input');
+        ['Most central (medoid)', 'Most divergent (longest branch)'].forEach(function (label) {
+            repsElement(pick, 'option', null, label);
+        });
+        pick.selectedIndex = _repsInputs.pickIndex;
+
+        let n = protectable.length;
+        let protect = choice('checkbox', n > 0
+            ? 'Keep the ' + n + ' selected/found ' + (n === 1 ? 'tip' : 'tips') + ' (never drop them)'
+            : 'Keep selected/found tips (none are selected)', n > 0, n === 0);
+        protect.parentNode.classList.add('aptx-reps-protect');
+
+        let error = repsElement(body, 'div', 'aptx-reps-error');
+        let sync = function () {
+            hint.textContent = byCutoff.checked
+                ? 'Maximum distance between any two tips kept in the same group.'
+                : 'Approximate number of representative tips to keep.';
+            error.textContent = '';
+        };
+        byCutoff.addEventListener('change', function () {
+            value.value = _repsInputs.cutoff;
+            sync();
+        });
+        byTarget.addEventListener('change', function () {
+            value.value = _repsInputs.target;
+            sync();
+        });
+        sync();
+
+        let submit = function () {
+            let text = value.value.trim();
+            let cutoff = 0;
+            let target = 0;
+            if (byCutoff.checked) {
+                cutoff = javaParseDouble(text);
+                if (cutoff === null) {
+                    error.textContent = 'Please enter a numeric distance cutoff (for example 0.05).';
+                    return;
+                }
+                if (!isFinite(cutoff) || cutoff <= 0) {
+                    error.textContent = 'The distance cutoff must be a positive number.';
+                    return;
+                }
+            } else {
+                target = javaParseInt(text);
+                if (target === null) {
+                    error.textContent = 'Please enter a whole number of representatives (for example 100).';
+                    return;
+                }
+                if (target < 1) {
+                    error.textContent = 'The target number of representatives must be at least 1.';
+                    return;
+                }
+            }
+            // a tree without branch lengths forced the target: that is not a preference
+            if (hasLengths) {
+                _repsInputs.byCutoff = byCutoff.checked;
+            }
+            if (byCutoff.checked) {
+                _repsInputs.cutoff = text;
+            } else {
+                _repsInputs.target = text;
+            }
+            _repsInputs.pickIndex = pick.selectedIndex;
+            shell.dialog.close();
+
+            let options = {
+                pick: pick.selectedIndex === 1 ? forester.REPRESENTATIVE_LONGEST_BRANCH : forester.REPRESENTATIVE_MEDOID,
+                protectedTips: protect.checked ? protectable : []
+            };
+            if (byCutoff.checked) {
+                options.cutoff = cutoff;
+            } else {
+                options.target = target;
+            }
+            let result = forester.selectRepresentativeTips(phy, options);
+            showRepresentativesAsHits(result);
+            showRepresentativesResult(phy, result, byCutoff.checked, cutoff, target, options.pick);
+        };
+        value.addEventListener('keydown', function (event) {
+            if (event.key === 'Enter') {
+                event.preventDefault();
+                submit();
+            }
+        });
+
+        let actions = repsElement(body, 'div', 'aptx-reps-actions');
+        repsButton(actions, 'Cancel', false, function () {
+            shell.dialog.close();
+        });
+        repsButton(actions, 'Select', true, submit);
+        shell.dialog.showModal();
+        value.focus();
+        value.select();
+    }
+
+    // The tips kept, as search A's hits -- the desktop shows them as its
+    // found nodes: A's colour, the hit count, the step-through. The next
+    // search replaces them, and resetting search A clears them.
+    function showRepresentativesAsHits(result) {
+        _foundNodes0 = new Set(result.keptTips);
+        _searchBox0Empty = false;
+        _searchHitIndex = -1;
+        scheduleUpdate(null, 0, true);
+        updateSearchHitNavigation();
+    }
+
+    // The desktop's summary, and its offer of a new tree of the tips kept.
+    function showRepresentativesResult(phy, result, byCutoff, cutoff, target, pick) {
+        let shell = makeDialogShell(REPRESENTATIVES_DIALOG, 'Representative tips selected', 360);
+        shell.body.classList.add('aptx-reps');
+        result.summary.split('\n').forEach(function (line) {
+            repsElement(shell.body, 'div', 'aptx-reps-line', line);
+        });
+        let n = result.keptCount;
+        repsElement(shell.body, 'div', 'aptx-reps-question',
+            'Create a new tree containing only these ' + n + (n === 1 ? ' tip?' : ' tips?'));
+        let actions = repsElement(shell.body, 'div', 'aptx-reps-actions');
+        repsButton(actions, 'Close', false, function () {
+            shell.dialog.close();
+        });
+        let create = repsButton(actions, 'Create tree', true, function () {
+            shell.dialog.close();
+            openRepresentativeTree(phy, result, byCutoff, cutoff, target, pick);
+        });
+        shell.dialog.showModal();
+        create.focus();
+    }
+
+    // The tips kept, cut out into a new tree at the end of the tree picker,
+    // which opens at once: named <parent>_Nreps, its description saying how
+    // it was made, drawn as this tree is (phylogram, aligned or cladogram),
+    // as the desktop's derived tab. This tree is left as it is.
+    function openRepresentativeTree(phy, result, byCutoff, cutoff, target, pick) {
+        let copy = forester.copyTreeKeepingTips(phy, result.keptTips);
+        forester.preOrderTraversalAll(copy, function (n) {
+            VIEW_NODE_FIELDS.forEach(function (f) {
+                delete n[f];
+            });
+        });
+        forester.addParents(copy);
+        let parentName = (typeof phy.name === 'string' && phy.name.length > 0) ? phy.name : null;
+        copy.name = forester.representativeTreeName(parentName, result.keptCount);
+        let provenance = forester.representativeTreeDescription(byCutoff, cutoff, target, pick, result.keptCount,
+            forester.stripShortExtension(parentName), result.tipCount);
+        copy.description = copy.description ? copy.description + ' ' + provenance : provenance;
+
+        let display = _state.phylogram ? (_state.alignPhylogram ? 'aligned' : 'phylogram') : 'cladogram';
+        clearCollapsedFlags(_trees[_treeIndex]);
+        _trees.push(copy);
+        let launchConfig = _launchConfig;
+        let cfg = Object.assign({}, launchConfig || {});
+        cfg.view = {display: display};
+        launchInto(_container, _trees, _trees.length - 1, cfg);
+        _launchConfig = launchConfig;   // later switches open each tree its own way
+    }
+
     function escPressed() {
         if (_in_subtree) {
             _root = _root_const;
@@ -10765,6 +11063,16 @@ function (root, d3, forester, phyloXml) {
             + glyphDot(50, 50, 11);
     }
 
+    // Representative tips: two clades of two tips, one tip of each kept --
+    // the dot. The desktop has it only as a menu item, so it is drawn to
+    // match the midpoint glyph's weight.
+    function glyphRepresentatives() {
+        return '<path d="M10,30 V70 M10,30 H38 M10,70 H38 M38,16 V44 M38,56 V84'
+            + ' M38,16 H66 M38,44 H66 M38,56 H66 M38,84 H66"/>'
+            + glyphDot(84, 16, 10)
+            + glyphDot(84, 84, 10);
+    }
+
     // Build one glyph as an inline <svg>. Stroke weight, caps and joins follow
     // the desktop class each glyph came from.
     function makeGlyph(kind) {
@@ -10789,6 +11097,7 @@ function (root, d3, forester, phyloXml) {
             case 'ladderize_asc': sw = 8; cap = 'round'; body = glyphLadderize(true); break;
             case 'ladderize_desc': sw = 8; cap = 'round'; body = glyphLadderize(false); break;
             case 'midpoint': sw = 8; cap = 'round'; body = glyphMidpoint(); break;
+            case 'representatives': sw = 8; cap = 'round'; body = glyphRepresentatives(); break;
             case 'uncollapse_all': sw = 8.5; cap = 'round'; body = glyphUncollapseAll(); break;
             case 'tree_prev': sw = 9; cap = 'round'; body = glyphChevron(false); break;
             case 'tree_next': sw = 9; cap = 'round'; body = glyphChevron(true); break;
@@ -10980,6 +11289,29 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-keys { display:inline-flex; gap:3px; flex-wrap:wrap; }'
             + '.aptx-kbd { font-family:inherit; font-size:10.5px; line-height:1; padding:3px 5px; min-width:18px; text-align:center; color:var(--p-ink); background:var(--p-surface2); border:1px solid var(--p-line-strong); border-bottom-width:2px; border-radius:4px; }'
             + '.aptx-shortcuts-note { margin:8px 0 0; font-size:10.5px; line-height:1.4; color:var(--p-muted); }'
+            // representative tips: the input dialog and its result
+            + '.aptx-reps { line-height:1.35; }'
+            + '.aptx-reps-lead { margin:0 0 4px; }'
+            + '.aptx-reps-choice { display:flex; align-items:center; gap:6px; padding:2px 0; cursor:pointer; }'
+            + '.aptx-reps-choice input { accent-color:var(--p-accent); width:13px; height:13px; margin:0; flex:none; }'
+            + '.aptx-reps-disabled { color:var(--p-faint); cursor:default; }'
+            + '.aptx-reps-input { display:block; box-sizing:border-box; width:100%; font:inherit; color:var(--p-ink);'
+            + '  background:var(--p-surface2); border:1px solid var(--p-line-strong); border-radius:6px; padding:4px 7px; }'
+            + '.aptx-reps-input:focus { outline:none; border-color:var(--p-accent); box-shadow:0 0 0 3px var(--p-accent-weak); }'
+            + '.aptx-reps-note { margin-top:3px; font-size:10.5px; color:var(--p-muted); }'
+            + '.aptx-reps-protect { margin-top:10px; }'
+            + '.aptx-reps-error { margin-top:6px; font-size:10.5px; color:#e5484d; }'
+            + '.aptx-reps-error:empty { display:none; }'
+            + '.aptx-reps-line { padding:1px 0; }'
+            + '.aptx-reps-question { margin-top:9px; font-weight:600; }'
+            + '.aptx-reps-actions { display:flex; justify-content:flex-end; gap:8px; margin-top:12px; }'
+            + '.aptx-reps-button { font:inherit; font-size:11px; height:26px; padding:0 12px; color:var(--p-ink);'
+            + '  background:var(--p-surface2); border:1px solid var(--p-line-strong); border-radius:6px; cursor:pointer;'
+            + '  transition:background .12s,border-color .12s,color .12s; }'
+            + '.aptx-reps-button:hover,.aptx-reps-primary { background:var(--p-accent-weak); border-color:var(--p-accent);'
+            + '  color:var(--p-accent-ink); }'
+            + '.aptx-reps-primary { font-weight:600; }'
+            + '.aptx-reps-button:focus-visible { outline:none; box-shadow:0 0 0 3px var(--p-accent-weak); }'
             + '.aptx-dialog-mono { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,"Courier New",monospace;'
             + '  font-size:11px; white-space:pre-wrap; overflow-wrap:anywhere; }'
             // The hover tooltip, on the same palette.
@@ -11118,7 +11450,9 @@ function (root, d3, forester, phyloXml) {
             + '.aptx-panel .aptx-slider-row input[type=range] { flex:1 1 auto; min-width:0; margin:0; }'
             + '.aptx-panel .aptx-linkbtn { background:none; border:0; padding:1px 0 2px; margin:0; font:inherit; font-size:10px; color:var(--p-accent); cursor:pointer; display:block; }'
             + '.aptx-panel .aptx-linkbtn:hover { text-decoration:underline; }'
-            + '.aptx-panel .aptx-toolrow { margin-top:5px; }'
+            // one row, its buttons sharing it evenly, its edges on the zoom rows'
+            + '.aptx-panel .aptx-toolrow { margin-top:5px; display:flex; gap:3px; }'
+            + '.aptx-panel .aptx-toolrow .aptx-gbtn { flex:1 1 0; min-width:0; padding:0; margin:2px 0; }'
             + '.aptx-panel .aptx-searchnav { align-items:center; gap:4px; margin:2px 0 4px; }'
             + '.aptx-panel .aptx-searchnav span { flex:1 1 auto; text-align:center; font-weight:600; font-size:11px; color:var(--p-ink); }'
             + '.aptx-panel .aptx-searchnav .aptx-gbtn:last-child { margin-right:0; }'
@@ -12203,6 +12537,8 @@ function (root, d3, forester, phyloXml) {
 
         on(MIDPOINT_ROOT_BUTTON, 'click', midpointRootButtonPressed);
 
+        on(REPRESENTATIVES_BUTTON, 'click', representativesButtonPressed);
+
         // Search Controls
         // ---------------
 
@@ -12651,6 +12987,7 @@ function (root, d3, forester, phyloXml) {
             h = h.concat(makeGlyphButton('up_one_level', RETURN_TO_SUPERTREE_BUTTON_BY_ONE, 'move up by one level towards the complete tree (if in a sub-tree)'));
             h = h.concat(makeGlyphButton('uncollapse_all', UNCOLLAPSE_ALL_BUTTON, 'uncollapse all'));
             h = h.concat(makeGlyphButton('midpoint', MIDPOINT_ROOT_BUTTON, 're-root the tree: MAD or midpoint'));
+            h = h.concat(makeGlyphButton('representatives', REPRESENTATIVES_BUTTON, 'select representative tips: one per group of close tips'));
             h = h.concat('</div>');
             h = h.concat('</fieldset>');
             return h;
@@ -13015,6 +13352,16 @@ function (root, d3, forester, phyloXml) {
             rerootButton.title = blocked
                 || (_in_subtree ? 'return to the whole tree to re-root it' : 're-root the tree: MAD or midpoint');
         }
+        let repsButton = byId(REPRESENTATIVES_BUTTON);
+        if (repsButton) {
+            let repsBlocked = representativesBlockedReason();
+            if (repsBlocked) {
+                disableButton(repsButton);
+            } else {
+                enableButton(repsButton);
+            }
+            repsButton.title = repsBlocked || 'select representative tips: one per group of close tips';
+        }
         let b;
         if (_foundNodes0 && !_searchBox0Empty) {
             b = byId(RESET_SEARCH_A_BTN);
@@ -13290,6 +13637,22 @@ function (root, d3, forester, phyloXml) {
         holder.style.top = '0';
         holder.appendChild(el);
         document.body.appendChild(holder);
+        // jsPDF's built-in faces come in two weights only: svg2pdf passes any
+        // other (the legend titles' 600) on as a style Helvetica lacks, and
+        // jsPDF then falls back to Times -- snap every weight to one of the two.
+        // Those faces also encode only WinAnsi, where '≤' and '≥' come out as
+        // spaced-out garbage, so the ones the viewer draws itself are spelled out.
+        el.querySelectorAll('text, tspan').forEach(function (t) {
+            let weight = parseInt(window.getComputedStyle(t).fontWeight, 10);
+            if (weight !== 400 && weight !== 700) {
+                t.style.fontWeight = weight >= 600 ? 'bold' : 'normal';
+            }
+            t.childNodes.forEach(function (c) {
+                if (c.nodeType === Node.TEXT_NODE && /[≤≥]/.test(c.nodeValue)) {
+                    c.nodeValue = c.nodeValue.replace(/≤/g, '<=').replace(/≥/g, '>=');
+                }
+            });
+        });
         let svgEl = treeSvgElement();
         let w = (svgEl && svgEl.width.baseVal.value) || _displayWidth;
         let h = (svgEl && svgEl.height.baseVal.value) || _displayHeight;

package/forester.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.6.0",
+  "version": "3.7.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",