archaeopteryx 3.19.0 → 3.20.0

package/README.md

@@ -661,16 +661,42 @@ number wherever it appears — that is what makes a block of related columns
 readable as a block, and it is the point of a heat map rather than a row of
 independent stripes. The scale spans the whole tree, so entering a subtree
 narrows the rows and leaves the colours where they were. The columns that
-appear are exactly the numeric fields the **Color by** menu offers, so the two
-agree about what the tree holds; by default their left-to-right order follows
+appear are the numeric fields the **Color by** menu offers, so the two agree
+about what the tree holds — plus a field with **one value on every tip**, which
+has nothing to colour by but is a column all the same (a single-copy core gene
+is a column of 1s); by default their left-to-right order follows
 the order the file lists them in, which keeps a producer's grouping (core genes,
 then resistance, then prophages) intact even where some tips are missing a
 field — see **Order columns** below for the alternatives.
 
+Where a cell is at least 5 px on screen, each cell is drawn on its own with a
+**thin border in its own hue, darker** — a block of equal values still reads
+as a block, and each cell can be counted. The border stays 0.75 px at any
+zoom. Smaller cells, or a matrix of more than 60,000 cells, are drawn as merged
+runs of equal colour instead, and zooming across that threshold switches
+between the two.
+
 A cell **nobody filled in** is drawn as an outlined empty box, never as the
 scale's low end: on a presence/absence matrix, reading a missing field as zero
 states the opposite of what the file says. The key beside the scale names it.
 
+**A file can open straight into its matrix.** The desktop Archaeopteryx
+stores its figure setting as one property of the phylogeny, directly under
+`<phylogeny>`:
+
+```xml
+<property ref="aptx:figure" datatype="xsd:string" applies_to="phylogeny">v1;columns=pgfam:PGF_00019355\sMATRIX\sCIRCLE\sfalse\ppgfam:PGF_00019313\sMATRIX\sCIRCLE\sfalse</property>
+```
+
+When it names two or more `MATRIX` columns the tree has, the tree opens with the
+heat map on, showing **only those columns, in that order** (the order is then
+`manual`, and **Order columns** can still change it). Other column types are
+the desktop's and are not drawn here. Only a property directly under
+`<phylogeny>` counts: an `aptx:figure` on a clade — where desktops
+0.11.117 to 0.11.172 wrote it — is ignored and left out of what is saved; the phylogeny's
+own is saved back unchanged. An explicit `showHeatmap`, `heatmapColumnOrder`
+or `heatmapManualOrder` in the config wins over the file.
+
 **Hover any cell** for its tip, the column and its value — or `not assessed` —
 and the scale it was coloured against. The column names stand under the matrix,
 turned; a matrix with more columns than will fit shows a window and says so
@@ -1353,8 +1379,10 @@ copy-pastable JSON.
 | `layout` | `'rectangular'` | The starting layout: `'rectangular'`, `'circular'`, or `'unrooted'`. |
 | `ladderizeTree` | `true` | Ladderize the tree on load: at each node, the larger clade first (any number of children, so a polytomy sorts too). |
 | `showMsa` | tree-derived | Open with the alignment track shown. Default: on when the tree carries an aligned `mol_seq`, off otherwise — an explicit `true`/`false` overrides that. |
+| `showProperties` | tree-derived | Open with the nodes' property values in their labels. Default: off, unless the file's figure setting (`show.SHOW_PROPERTIES=true`) says on. See [Properties in the label](#properties-in-the-label). |
+| `labelProperties` | tree-derived | Which properties the label shows, in order, as an array of refs (`['BVBRC:species', 'BVBRC:host_name']`). Default: the figure setting's `labelprops`, else `null` — every property but the heat map's columns. |
 | `showMsaLogo` | `false` | Open with the alignment summarised as a sequence logo instead of a conservation bar: a stack of letters per column, as tall as its information content, over the tips currently on screen. Only drawn while the alignment track is shown. |
-| `showHeatmap` | `false` | Open with the heat map shown. Offered whenever the tree carries two or more numeric per-tip fields, but off unless asked for: almost any annotated tree has such fields, so turning it on by itself would be an opinion about the tree rather than a service. |
+| `showHeatmap` | tree-derived | Open with the heat map shown. Offered whenever the tree carries two or more numeric per-tip fields, but off unless asked for — almost any annotated tree has such fields, so turning it on by itself would be an opinion about the tree rather than a service — or unless the file's own figure setting (`aptx:figure`, see [Heat maps](#heat-maps)) draws them as a matrix. |
 | `heatmapColumnOrder` | tree-derived | How the heat map's columns are ordered: `'document'` (as the file lists them), `'clustered'` (Euclidean), `'clustered-presence'` (Bray–Curtis), `'alphabetical'`, `'frequency'`. The clustered modes also draw the dendrogram. Default: a **clustered** order, with the distance chosen from the values — Bray–Curtis where the matrix has zeros to ignore and nothing negative, Euclidean otherwise. An explicit value always wins and is never re-derived. |
 | `heatmapManualOrder` | `null` | The heat map's columns in your own order, as an array of property refs (`['meta:recA', 'meta:gyrA', …]`). Only read while `heatmapColumnOrder` is `'manual'`. A ref the tree has not got is ignored, and a column the list does not name follows the ones it does. |
 | `showDomainArchitectures` | tree-derived | Open with the domain tracks shown. Default: on when any tip carries a `<domain_architecture>`, off otherwise — an explicit `true`/`false` overrides that. |
@@ -1849,6 +1877,28 @@ rather than 300 identical "Influenz.." labels).
 Both menus live in the single control panel, above Display Data, which is where
 the desktop puts them.
 
+### Properties in the label
+
+A tip's other fields — a species, a host, a country, anything a node carries
+as a `<property>` — can go into its label, as on the desktop. **Properties**
+under Display Data (offered when nodes carry properties, off by default) adds
+their **values** after the rest of the label, joined by ` | ` as the rest of the
+label is: `255457.3 | Brucella lupini | host`, or `Brucella lupini` alone with
+Node Name off. (The desktop joins them with `, `; a pipe was chosen here
+because values often contain commas — a host such as `Bottlenose dolphin,
+Tursiops truncatus`.) A unit follows its value. With nothing chosen, every property shows in the
+node's own order, except the heat map's columns while it is shown — a field
+has one display role. **Label fields…** picks which properties, and in what
+order; picking one turns Properties on. The checkbox and the fields travel in
+a shared view (`show=…,properties`, `labelFields=`), and the config keys are
+`showProperties` and `labelProperties`.
+
+A file can choose for itself: the desktop's figure setting (`aptx:figure`,
+see [Heat maps](#heat-maps)) carries `labelprops=` (the properties, in order)
+and the display switches `show.SHOW_PROPERTIES=true` and
+`show.SHOW_NODE_NAMES=false`, and a tree opens labelled that way in both
+programs. The config wins over the file.
+
 ### Initial label fields
 
 Which of the three label checkboxes — Node Name, Taxonomy, Sequence — start
@@ -2084,8 +2134,10 @@ bottom reserve the fit allows for follows that.
 
 Model (`forester.heatmapColumns(tree)` → `{refs:[{ref,label}], min, max}`,
 pure, in `test/heatmap_test.js`): a column is any candidate that
-`forester.visualizationCandidates` already calls a **numeric property** — so
-candidacy is not re-invented here and the refusal rules are inherited — carried
+`forester.visualizationCandidates(tree, {keepConstant: true})` calls a
+**numeric property** — so candidacy is not re-invented here and the refusal
+rules are inherited, except the one against a field with a single value, which
+suits colour-by and not a matrix — carried
 by at least one **tip**; an internal node has no row, so a ref only internal
 nodes hold is not a column and its values never reach the scale. `min`/`max`
 span every drawn cell of the whole tree. `forester.heatmapValue(node, ref)`
@@ -2188,8 +2240,16 @@ order the columns happened to be in. Measured: without it, the 6×6 linkage
 fixture fed in reverse clustered to `h6,h5,h3,h4,h2,h1` instead of R's
 `h6,h3,h5,h4,h1,h2` — the index order drives the tie-break and the leaf order,
 so the incoming order really does leak through. The normaliser deliberately does
-**not** go through `heatmapColumns`: that applies candidacy rules (a constant
-column is refused), and ordering must not move with them.
+**not** go through `heatmapColumns`: that applies candidacy rules, and
+ordering must not move with them.
+
+`forester.heatmapColumns(tree, only)` keeps just the refs in `only` — the
+figure's MATRIX columns (`forester.figureMatrixRefs(tree)`, from
+`forester.readFigure`, which reads the phylogeny's own `aptx:figure` only:
+`"v1;key=value;…"`, values escaped as the desktop's `PropertyTextCodec` does,
+`columns=` a `|` list of `ref~TYPE~SHAPE~normalized`; an unknown version is no
+figure, unknown keys are ignored). `forester.dropCladeFigures(tree)` removes
+the old clade-level copies at launch.
 
 Distances are `forester.heatmapEuclideanDistances` (R's `dist` convention for
 missing values: pairwise deletion, the squared sum scaled up by `tips / used`;

package/archaeopteryx.d.ts

@@ -104,6 +104,10 @@ export interface ArchaeopteryxConfig {
      * bar: each column a stack of letters as tall as its information content,
      * over the tips currently on screen. Only drawn with the track shown. */
     showMsaLogo?: boolean;
+    /** The nodes' property values in their labels (the desktop's "Properties"). */
+    showProperties?: boolean;
+    /** Which properties the label shows, in order; null for all but the heat map's columns. */
+    labelProperties?: string[] | null;
     /** The scale axis under a phylogram: the time axis on a time tree whose
      * branches show time, a distance axis on any other. Default: on for a
      * time tree, off otherwise. */
@@ -169,6 +173,8 @@ export interface ViewState {
     heatmap?: boolean;
     heatmapOrder?: 'document' | 'clustered' | 'clustered-presence' | 'alphabetical' | 'frequency' | 'manual';
     heatmapManual?: string[];
+    /** The properties the label shows, in order (labelProperties). */
+    labelFields?: string[];
     domains?: boolean;
     domainLabels?: 'none' | 'domains' | 'legend';
     domainGlow?: boolean;

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.19.0
+// v 3.20.0
 // 2026-09-17
 //
 // 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.19.0';
+    const VERSION = '3.20.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';
@@ -456,6 +456,9 @@ function (root, d3, forester, phyloXml) {
     const SEARCH_COMBINE_SELECT = 'scmb';
     const SEARCH_COMBINE_ROW = 'scmb_row';
     const SEQUENCE_CB = 'seq_cb';
+    const PROPERTIES_CB = 'props_cb';
+    const LABEL_FIELDS_BUTTON = 'label_fields_b';
+    const LABEL_FIELDS_DIALOG = 'label_fields_dialog';
     const SHORTEN_NODE_NAME_CB = 'shortennodename_cb';
     const TAXONOMY_CB = 'tax_cb';
     const ZOOM_IN_X = 'zoomin_x';
@@ -630,11 +633,24 @@ function (root, d3, forester, phyloXml) {
     // within 1.2px of a ring boundary came out background-coloured.
     const HEATMAP_RING_BLEED = 1.2;
     const HEATMAP_BLANK = 'blank';        // the run-merger's stand-in for a cell nobody filled in
+    // Cell borders (Christian, 2026-09-30): each cell outlined in its own hue,
+    // darker, so a block of equal values still reads as a block while each
+    // cell can be counted. Only where a cell is big enough on SCREEN to carry
+    // one, and not on a matrix so large that a node per cell would drag.
+    const HEATMAP_BORDER_MIN_PX = 5;      // the cell's smaller side on screen
+    const HEATMAP_BORDER_MAX_CELLS = 60000;
+    const HEATMAP_BORDER_W = 0.75;        // screen px at any zoom (non-scaling stroke)
+    const HEATMAP_BORDER_DARKEN = 0.8;    // d3's darker(k): each step x0.7
+    const HEATMAP_SEAL_W = 0.6;           // a merged run's stroke in its own colour, over the seams
     const HEATMAP_DENDRO_GAP = 5;         // px between the dendrogram's leaves and the first row
     const HEATMAP_DENDRO_MIN_BAND = 24;   // the band it is drawn in, from the label font
     const HEATMAP_DENDRO_MAX_BAND = 72;
     let _heatmapReserve = 0;              // horizontal px reserved for the matrix, set with _w
     let _heatmapModel = null;             // forester.heatmapColumns of the WHOLE tree, cached per launch
+    let _heatmapCells = null;             // what was drawn: {cellMin (tree units), count, bordered}
+    let _heatmapBorderTimer = null;
+    let _figureMatrix = null;             // the MATRIX refs the file's aptx:figure names, when it draws a matrix
+    let _labelFields = null;              // forester.labelPropertyRefs of the tree, cached until an edit
     let _heatmapColor = null;             // the one scale every column is painted on
     let _heatmapColOffset = 0;            // first shown column, while the matrix is windowed
     let _heatmapGeom = null;              // the last draw's geometry, for the hover readout
@@ -1331,6 +1347,7 @@ function (root, d3, forester, phyloXml) {
         _svgGroup.attr('transform', event.transform);
         placeFloatingOverlays();
         updateOverviewViewport();
+        heatmapBordersFollowZoom();
     }
 
     // A strip in the floating layer. Drawn in TREE coordinates like everything
@@ -3391,7 +3408,7 @@ function (root, d3, forester, phyloXml) {
         _svgGroup.selectAll('g.aptx-align-ext').remove();
         let alignedRect = !radialDisplay() && _state.phylogram && _state.alignPhylogram;
         let tipGuides = alignedRect && _state.showExternalLabels
-            && (_state.showNodeName || _state.showTaxonomy || _state.showSequence);
+            && (_state.showNodeName || _state.showTaxonomy || _state.showSequence || _state.showProperties);
         // a collapsed clade's label always shows, so its guide does too: from
         // past the wedge's farthest tip to the label column
         let collapsedGuides = alignedRect ? nodes.filter(function (d) {
@@ -4661,6 +4678,10 @@ function (root, d3, forester, phyloXml) {
         }
 
 
+        if (_state.showProperties && phynode.properties) {
+            l = append(l, labelPropertiesOf(phynode));
+        }
+
         if (_nodeLabels && phynode.properties) {
             const props_length = phynode.properties.length;
             if (props_length > 0) {
@@ -5621,6 +5642,8 @@ function (root, d3, forester, phyloXml) {
         'layout',
         'showMsa',
         'showMsaLogo',
+        'showProperties',
+        'labelProperties',
         'showHeatmap',
         'heatmapColumnOrder',
         'heatmapManualOrder',
@@ -5860,8 +5883,18 @@ function (root, d3, forester, phyloXml) {
         // numeric per-tip fields, which is common enough that turning it on
         // by itself would be an opinion about the tree rather than a service
         // -- the alignment track, by contrast, is on when there IS one.
+        // The desktop's figure setting: its MATRIX columns open as the heat
+        // map, only those, in the file's order. Only the phylogeny's own
+        // aptx:figure counts; a copy on a clade (the old place) is dropped,
+        // so a tree saved from here carries none. Here and not in launchInto:
+        // telling whether the columns exist is a scan of every tip, which on
+        // a big tree belongs behind the working card, not in front of it.
+        if (_treeData) {
+            forester.dropCladeFigures(_treeData);
+        }
+        _figureMatrix = _treeData ? figureMatrixOf(_treeData) : null;
         if (_state.showHeatmap === undefined) {
-            _state.showHeatmap = false;
+            _state.showHeatmap = _figureMatrix !== null;
         }
         // The logo is a summary of the alignment, not a second view of the
         // tree, so it waits to be asked for: an alignment opens showing its
@@ -5876,7 +5909,7 @@ function (root, d3, forester, phyloXml) {
         // value always wins and is never re-derived -- including 'document',
         // which keeps the order the producer wrote the fields in.
         if (_state.heatmapColumnOrder === undefined) {
-            _state.heatmapColumnOrder = null;
+            _state.heatmapColumnOrder = _figureMatrix ? 'manual' : null;
         } else if (_state.heatmapColumnOrder !== null
             && forester.HEATMAP_ORDER_MODES.indexOf(_state.heatmapColumnOrder) < 0) {
             throw new Error(ERROR + '"heatmapColumnOrder" must be one of '
@@ -5887,7 +5920,7 @@ function (root, d3, forester, phyloXml) {
         // not got is ignored rather than fatal -- an order outliving one of
         // its columns is ordinary (see forester.heatmapManualOrder).
         if (_state.heatmapManualOrder === undefined) {
-            _state.heatmapManualOrder = null;
+            _state.heatmapManualOrder = _figureMatrix ? _figureMatrix.slice() : null;
         } else if (_state.heatmapManualOrder !== null
             && !(Array.isArray(_state.heatmapManualOrder)
                 && _state.heatmapManualOrder.every(function (r) {
@@ -6060,6 +6093,27 @@ function (root, d3, forester, phyloXml) {
                 + ' characters)');
         }
 
+        // Properties in the tip label: off unless asked for, as on the desktop,
+        // in every user-visible property's own order unless a list says which.
+        // The file's figure setting (aptx:figure) can say both, and whether
+        // the names show: labelprops, show.SHOW_PROPERTIES and
+        // show.SHOW_NODE_NAMES, the desktop's own keys. The config wins.
+        let figure = _treeData ? forester.readFigure(_treeData) : null;
+        if (_state.showProperties === undefined) {
+            _state.showProperties = !!(figure && figure.show.SHOW_PROPERTIES === true);
+        }
+        if (_state.labelProperties === undefined) {
+            _state.labelProperties = (figure && figure.labelProps) ? figure.labelProps.slice() : null;
+        } else if (_state.labelProperties !== null && !(Array.isArray(_state.labelProperties)
+            && _state.labelProperties.every(function (r) {
+                return typeof r === 'string';
+            }))) {
+            throw new Error(ERROR + '"labelProperties" must be an array of property refs');
+        }
+        if (figure && typeof figure.show.SHOW_NODE_NAMES === 'boolean' && _basicTreeProperties.nodeNames) {
+            _state.showNodeName = figure.show.SHOW_NODE_NAMES;
+        }
+
         // A small tree is drawn with a heavier stroke; hairlines are for trees
         // dense enough to need them.
         _state.branchWidthDefault = _basicTreeProperties.externalNodesCount <= SMALL_TREE_MAX_EXT_NODES
@@ -6518,6 +6572,8 @@ function (root, d3, forester, phyloXml) {
         _treeData = phylo;
         _trees = trees;
         _treeIndex = index;
+        _figureMatrix = null;   // read by initializeState, behind the working card
+        _labelFields = null;
         _launchConfig = config;
         _container = containerEl;
         assignViewIds(phylo);
@@ -7275,6 +7331,7 @@ function (root, d3, forester, phyloXml) {
             _domain.palette = null;   // the tree changed: the domain names are dealt their colours again
         }
         if (edited) {
+            _labelFields = null;      // the fields the labels can show, too
             _heatmapModel = null;     // ... and the heat map's columns and scale are derived from it again
             _heatmapColor = null;
         }
@@ -8192,11 +8249,28 @@ function (root, d3, forester, phyloXml) {
 
     function heatmapModel() {
         if (!_heatmapModel && _treeData) {
-            _heatmapModel = forester.heatmapColumns(_treeData);
+            _heatmapModel = forester.heatmapColumns(_treeData, _figureMatrix);
         }
         return _heatmapModel;
     }
 
+    // The file's MATRIX columns, when at least a heat map's worth of them are
+    // numeric fields this tree has; otherwise null, and the heat map offers
+    // every numeric field as it would without a figure.
+    // The model it builds is kept as the heat map's own, so the scan runs once.
+    function figureMatrixOf(tree) {
+        let refs = forester.figureMatrixRefs(tree);
+        if (refs.length < HEATMAP_MIN_COLUMNS) {
+            return null;
+        }
+        let model = forester.heatmapColumns(tree, refs);
+        if (model.refs.length < HEATMAP_MIN_COLUMNS) {
+            return null;
+        }
+        _heatmapModel = model;
+        return refs;
+    }
+
     // Offered when the tree holds at least two numeric per-tip refs that
     // actually carry values: one column is a stripe rather than a matrix,
     // and a scale needs something to span.
@@ -8404,7 +8478,53 @@ function (root, d3, forester, phyloXml) {
         return heatmapTopReserve();
     }
 
+    // Whether cells of this size (tree units) and number are drawn one by one
+    // with borders at zoom scale k, or merged into runs.
+    function heatmapBordered(cellMin, count, k) {
+        return count <= HEATMAP_BORDER_MAX_CELLS && (cellMin * k) >= HEATMAP_BORDER_MIN_PX;
+    }
+
+    function heatmapBorderColor(fill) {
+        let c = d3.color(fill);
+        return c ? c.darker(HEATMAP_BORDER_DARKEN).formatHex() : fill;
+    }
+
+    // A cell (or a merged run) of colour `fill`: bordered, its edge a darker
+    // shade of itself; or sealed, stroked in its own colour so that no seam of
+    // background shows between two runs at a fractional zoom -- the faint lines
+    // that came and went with the zoom level. Both strokes are a constant
+    // screen width, so a zoom neither fattens nor loses them.
+    function paintHeatmapCell(el, fill, bordered) {
+        el.attr('fill', fill)
+            .attr('stroke', bordered ? heatmapBorderColor(fill) : fill)
+            .attr('stroke-width', bordered ? HEATMAP_BORDER_W : HEATMAP_SEAL_W)
+            .attr('vector-effect', 'non-scaling-stroke');
+        return el;
+    }
+
+    // Called on every zoom event: when the zoom has carried the cells across
+    // the border threshold, the heat map alone is drawn again once the zoom
+    // settles.
+    function heatmapBordersFollowZoom() {
+        if (!_heatmapCells || !_baseSvg) {
+            return;
+        }
+        let want = heatmapBordered(_heatmapCells.cellMin, _heatmapCells.count, currentZoomScale());
+        if (want === _heatmapCells.bordered) {
+            return;
+        }
+        if (_heatmapBorderTimer) {
+            clearTimeout(_heatmapBorderTimer);
+        }
+        _heatmapBorderTimer = setTimeout(function () {
+            _heatmapBorderTimer = null;
+            drawHeatmapTrack();
+            placeFloatingOverlays();
+        }, 120);
+    }
+
     function drawHeatmapTrack() {
+        _heatmapCells = null;
         if (!_svgGroup) {
             return;
         }
@@ -8487,6 +8607,9 @@ function (root, d3, forester, phyloXml) {
         // a run of CELLS, or its top and bottom edges read as a drawn rule
         // across the matrix rather than as missing data.
         let mergeBlanks = cw < HEATMAP_LABEL_MIN_COL_W;
+        let cellMin = Math.min(cw, n > 1 ? 2 * pad : cw);
+        let bordered = heatmapBordered(cellMin, n * visible, currentZoomScale());
+        _heatmapCells = {cellMin: cellMin, count: n * visible, bordered: bordered};
         for (let r = 0; r < n; ++r) {
             let d = tips[r];
             let cy = Math.round(bounds[r]);
@@ -8508,7 +8631,7 @@ function (root, d3, forester, phyloXml) {
                     rect.attr('fill', _state.backgroundColorDefault)
                         .attr('stroke', ink).attr('stroke-opacity', 0.45).attr('stroke-width', 1);
                 } else {
-                    rect.attr('fill', runFill);
+                    paintHeatmapCell(rect, runFill, bordered);
                 }
                 runStart = -1;
                 runFill = null;
@@ -8519,7 +8642,8 @@ function (root, d3, forester, phyloXml) {
                 if (fill === HEATMAP_BLANK) {
                     blanks++;
                 }
-                if (runFill === fill && (mergeBlanks || fill !== HEATMAP_BLANK)) {
+                // bordered, every cell is its own: a run would hide the cells in it
+                if (!bordered && runFill === fill && (mergeBlanks || fill !== HEATMAP_BLANK)) {
                     continue;   // the run extends
                 }
                 flush(i);
@@ -8829,6 +8953,10 @@ function (root, d3, forester, phyloXml) {
         edge[n] = ang[n - 1] + pad;
 
         let blanks = 0;
+        // a cell's smaller side: its ring width, or its arc at the ring's inside
+        let cellMin = Math.min(ringW, n > 1 ? 2 * pad * start : ringW);
+        let bordered = heatmapBordered(cellMin, n * columns.length, currentZoomScale());
+        _heatmapCells = {cellMin: cellMin, count: n * columns.length, bordered: bordered};
         for (let c = 0; c < columns.length; ++c) {
             let r0 = start + (c * ringW);
             let r1 = r0 + ringW;
@@ -8847,15 +8975,19 @@ function (root, d3, forester, phyloXml) {
                 // A BLANK is not bled -- it is background-coloured, so a seam
                 // beside it shows nothing, and bleeding it would push its
                 // outward OUTLINE under the next ring and cost it an edge.
-                let bleed = (runFill === HEATMAP_BLANK) ? 0 : HEATMAP_RING_BLEED;
+                // (bordered, the border covers the seam and a bleed would push
+                // one cell's edge under its neighbour)
+                let bleed = (runFill === HEATMAP_BLANK || bordered) ? 0 : HEATMAP_RING_BLEED;
                 let a1 = edge[endI] + (bleed / Math.max(1, r1));
                 let path = g.append('path')
                     .attr('d', heatmapSector(edge[runStart], a1, r0, r1 + bleed));
                 if (runFill === HEATMAP_BLANK) {
                     path.attr('fill', _state.backgroundColorDefault)
                         .attr('stroke', ink).attr('stroke-opacity', 0.45).attr('stroke-width', 1);
+                } else if (bordered) {
+                    paintHeatmapCell(path, runFill, true);
                 } else {
-                    path.attr('fill', runFill);
+                    path.attr('fill', runFill);   // the bleed already closes the seams here
                 }
                 runStart = -1;
                 runFill = null;
@@ -8866,7 +8998,7 @@ function (root, d3, forester, phyloXml) {
                 if (fill === HEATMAP_BLANK) {
                     blanks++;
                 }
-                if (runFill === fill && (ringW < HEATMAP_LABEL_MIN_COL_W || fill !== HEATMAP_BLANK)) {
+                if (!bordered && runFill === fill && (ringW < HEATMAP_LABEL_MIN_COL_W || fill !== HEATMAP_BLANK)) {
                     continue;
                 }
                 flush(i);
@@ -9627,6 +9759,7 @@ function (root, d3, forester, phyloXml) {
         ['name', NODE_NAME_CB, 'showNodeName'],
         ['taxonomy', TAXONOMY_CB, 'showTaxonomy'],
         ['sequence', SEQUENCE_CB, 'showSequence'],
+        ['properties', PROPERTIES_CB, 'showProperties'],
         ['confidence', CONFIDENCE_VALUES_CB, 'showConfidenceValues'],
         ['madValues', MAD_VALUES_CB, 'showMadValues'],
         ['branchLength', BRANCH_LENGTH_VALUES_CB, 'showBranchLengthValues'],
@@ -9749,6 +9882,9 @@ function (root, d3, forester, phyloXml) {
         if (heatmapAvailable()) {
             s.heatmap = _state.showHeatmap === true;
             s.heatmapOrder = heatmapMode();
+            if (_state.labelProperties) {
+                s.labelFields = _state.labelProperties.slice();
+            }
             if (_state.heatmapManualOrder) {
                 s.heatmapManual = _state.heatmapManualOrder.slice();
             }
@@ -9892,6 +10028,11 @@ function (root, d3, forester, phyloXml) {
         if (typeof s.heatmap === 'boolean') {
             _state.showHeatmap = s.heatmap;
         }
+        if (Array.isArray(s.labelFields) && s.labelFields.every(function (r) {
+            return typeof r === 'string';
+        })) {
+            _state.labelProperties = s.labelFields.slice();
+        }
         if (Array.isArray(s.heatmapManual) && s.heatmapManual.every(function (r) {
             return typeof r === 'string';
         })) {
@@ -10088,7 +10229,7 @@ function (root, d3, forester, phyloXml) {
         'scaleAxis', 'scaleGrid', 'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
     // Lists of strings, comma-joined. A property ref carries ':' but never a
     // comma, and encodeViewValue leaves both readable in a hash.
-    const VIEW_LIST_KEYS = ['heatmapManual'];
+    const VIEW_LIST_KEYS = ['heatmapManual', 'labelFields'];
     const VIEW_SEARCH_KEYS = [['searchA', 'a'], ['searchB', 'b']];
 
     function encodeViewValue(v) {
@@ -13593,6 +13734,182 @@ function (root, d3, forester, phyloXml) {
         scheduleUpdate();
     }
 
+    // ===================== Properties in the label =====================
+    // The desktop's "Properties" option and its Annotation Fields chooser:
+    // a node's property values in its label, values only, " | "-joined, in
+    // the order chosen (forester.labelPropertiesText). Nothing chosen means
+    // every user-visible property in the node's own order, less the heat
+    // map's columns while it is shown -- a field has one display role.
+
+    function labelFields() {
+        if (_labelFields === null && _treeData) {
+            _labelFields = forester.labelPropertyRefs(_treeData);
+        }
+        return _labelFields || [];
+    }
+
+    // the heat map's columns while it is shown: left out of the default label
+    function labelFieldsExcluded() {
+        let excluded = Object.create(null);
+        if (heatmapShown()) {
+            let m = heatmapModel();
+            (m ? m.refs : []).forEach(function (c) {
+                excluded[c.ref] = true;
+            });
+        }
+        return excluded;
+    }
+
+    function labelPropertiesOf(node) {
+        return forester.labelPropertiesText(node, _state.labelProperties,
+            _state.labelProperties ? null : labelFieldsExcluded());
+    }
+
+    function propertiesCbClicked() {
+        _state.showProperties = getCheckboxValue(PROPERTIES_CB);
+        if (_state.showProperties) {
+            _state.showExternalLabels = true;
+            setCheckboxValue(EXTERNAL_LABEL_CB, true);
+        }
+        search0();
+        search1();
+        scheduleUpdate();
+    }
+
+    // Which properties the label shows, and in what order: each field ticked
+    // or not, and moved with the arrows (or the arrow keys). Apply keeps the ticked
+    // ones in the order shown; picking a field that was not shown turns the
+    // Properties label on, as the desktop does, since otherwise choosing it
+    // would visibly do nothing. "All" goes back to every field.
+    function showLabelFieldsDialog() {
+        let all = labelFields();
+        if (all.length < 1) {
+            return;
+        }
+        let chosen = _state.labelProperties ? _state.labelProperties.filter(function (r) {
+            return all.indexOf(r) >= 0;
+        }) : null;
+        // the chosen fields first, in their order, then the rest as offered;
+        // with none chosen, ticked is what the label shows by default
+        let excluded = chosen ? null : labelFieldsExcluded();
+        let working = (chosen || []).concat(all.filter(function (r) {
+            return !chosen || chosen.indexOf(r) < 0;
+        })).map(function (ref) {
+            return {ref: ref, on: chosen ? chosen.indexOf(ref) >= 0 : !excluded[ref]};
+        });
+        if (!chosen) {
+            // the ticked ones first, so the list reads as the label does
+            working = working.filter(function (w) {
+                return w.on;
+            }).concat(working.filter(function (w) {
+                return !w.on;
+            }));
+        }
+        let before = working.filter(function (w) {
+            return w.on && (chosen !== null || _state.showProperties);
+        }).map(function (w) {
+            return w.ref;
+        });
+        let shell = makeDialogShell(LABEL_FIELDS_DIALOG, 'Label fields', 340);
+        let body = shell.body;
+        repsElement(body, 'div', 'aptx-reps-lead',
+            'Tick the properties the labels show, and set their order with the arrows.');
+        let list = repsElement(body, 'div', 'aptx-reorder');
+
+        function move(from, to) {
+            if (to < 0 || to >= working.length || from === to) {
+                return false;
+            }
+            working.splice(to, 0, working.splice(from, 1)[0]);
+            draw();
+            return true;
+        }
+
+        function draw() {
+            list.textContent = '';
+            working.forEach(function (w, i) {
+                let row = repsElement(list, 'div', 'aptx-reorder-row');
+                row.tabIndex = 0;
+                let box = repsElement(row, 'input', 'aptx-reorder-check');
+                box.type = 'checkbox';
+                box.checked = w.on;
+                box.addEventListener('change', function () {
+                    w.on = box.checked;
+                });
+                repsElement(row, 'span', 'aptx-reorder-name', forester.propertyDisplayName(w.ref)).title = w.ref;
+                let up = repsElement(row, 'button', 'aptx-reorder-move', '↑');
+                let down = repsElement(row, 'button', 'aptx-reorder-move', '↓');
+                up.type = 'button';
+                down.type = 'button';
+                up.title = 'Move up';
+                down.title = 'Move down';
+                up.disabled = (i === 0);
+                down.disabled = (i === working.length - 1);
+                up.addEventListener('click', function () {
+                    if (move(i, i - 1)) {
+                        list.children[i - 1].focus();
+                    }
+                });
+                down.addEventListener('click', function () {
+                    if (move(i, i + 1)) {
+                        list.children[i + 1].focus();
+                    }
+                });
+                row.addEventListener('keydown', function (event) {
+                    if (event.key === ' ' && event.target === row) {
+                        event.preventDefault();
+                        box.checked = !box.checked;
+                        w.on = box.checked;
+                        return;
+                    }
+                    let d = (event.key === 'ArrowUp') ? -1 : ((event.key === 'ArrowDown') ? 1 : 0);
+                    if (d === 0) {
+                        return;
+                    }
+                    event.preventDefault();
+                    if (move(i, i + d)) {
+                        list.children[i + d].focus();
+                    }
+                });
+            });
+        }
+        draw();
+
+        let actions = repsElement(body, 'div', 'aptx-reps-actions');
+        repsButton(actions, 'All', false, function () {
+            _state.labelProperties = null;
+            shell.dialog.close();
+            scheduleUpdate();
+        });
+        repsButton(actions, 'Cancel', false, function () {
+            shell.dialog.close();
+        });
+        repsButton(actions, 'Apply', true, function () {
+            _state.labelProperties = working.filter(function (w) {
+                return w.on;
+            }).map(function (w) {
+                return w.ref;
+            });
+            let added = _state.labelProperties.some(function (r) {
+                return before.indexOf(r) < 0;
+            });
+            if (added && !_state.showProperties) {
+                _state.showProperties = true;
+                _state.showExternalLabels = true;
+                setCheckboxValue(PROPERTIES_CB, true);
+                setCheckboxValue(EXTERNAL_LABEL_CB, true);
+            }
+            shell.dialog.close();
+            search0();
+            search1();
+            scheduleUpdate();
+        });
+        shell.dialog.showModal();
+        if (list.firstChild) {
+            list.firstChild.focus();
+        }
+    }
+
     function sequenceCbClicked() {
         _state.showSequence = getCheckboxValue(SEQUENCE_CB);
         if (_state.showSequence) {
@@ -16304,6 +16621,8 @@ function (root, d3, forester, phyloXml) {
         on(TAXONOMY_CB, 'click', taxonomyCbClicked);
 
         on(SEQUENCE_CB, 'click', sequenceCbClicked);
+        on(PROPERTIES_CB, 'click', propertiesCbClicked);
+        on(LABEL_FIELDS_BUTTON, 'click', showLabelFieldsDialog);
 
         on(CONFIDENCE_VALUES_CB, 'click', confidenceValuesCbClicked);
         on(SUPPORT_DOTS_CB, 'click', supportDotsCbClicked);
@@ -16832,6 +17151,10 @@ function (root, d3, forester, phyloXml) {
             if (_basicTreeProperties.sequences) {
                 labels.push(makeCheckboxItem('Sequence', SEQUENCE_CB, 'to show/hide node sequence information'));
             }
+            if (labelFields().length > 0) {
+                labels.push(makeCheckboxItem('Properties', PROPERTIES_CB, 'to show/hide the nodes\' property values'
+                    + ' (Label fields… chooses which, and in what order)'));
+            }
             if (_nodeLabels) {
                 for (const [key, value] of Object.entries(_nodeLabels)) {
                     if (value.label && value.propertyRef && value.description) {
@@ -16913,6 +17236,12 @@ function (root, d3, forester, phyloXml) {
 
             let h = '<fieldset><legend>Display Data</legend>';
             h = h.concat(makeCheckboxGroup('Labels', labels));
+            if (labelFields().length > 0) {
+                h = h.concat('<div class="aptx-domrow"><span class="aptx-domlabel"></span>'
+                    + '<input type="button" class="aptx-widebtn" value="Label fields…" name="' + LABEL_FIELDS_BUTTON
+                    + '" id="' + LABEL_FIELDS_BUTTON + '" title="choose which properties the labels show, and in what'
+                    + ' order"></div>');
+            }
             h = h.concat(makeCheckboxGroup('Nodes', nodes));
             h = h.concat(makeCheckboxGroup('Options', opts));
             h = h.concat('</fieldset>');
@@ -17237,6 +17566,7 @@ function (root, d3, forester, phyloXml) {
         setCheckboxValue(NODE_NAME_CB, _state.showNodeName);
         setCheckboxValue(TAXONOMY_CB, _state.showTaxonomy);
         setCheckboxValue(SEQUENCE_CB, _state.showSequence)
+        setCheckboxValue(PROPERTIES_CB, _state.showProperties);
         setCheckboxValue(CONFIDENCE_VALUES_CB, _state.showConfidenceValues);
         setCheckboxValue(SUPPORT_DOTS_CB, _state.showSupportDots);
         syncMadValuesCheckbox();
@@ -17911,9 +18241,11 @@ function (root, d3, forester, phyloXml) {
         }
         let name = _root_const.name ? String(_root_const.name).trim() : '';
         // what the phylogeny itself states goes with the part: without its
-        // branch_length_unit a subtree saved from Div opened again as time
+        // branch_length_unit a subtree saved from Div opened again as time,
+        // and without its properties (the figure setting) the part opened
+        // without the heat map the whole tree opens with
         let part = Object.assign({}, _root, {name: name ? name + ' (subtree)' : undefined});
-        ['rooted', 'rerootable', 'type', 'branch_length_unit'].forEach(function (k) {
+        ['rooted', 'rerootable', 'type', 'branch_length_unit', 'properties'].forEach(function (k) {
             if (_root_const[k] !== undefined && _root_const[k] !== null) {
                 part[k] = _root_const[k];
             }

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.19.0
+// v 3.20.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -2091,7 +2091,12 @@
         return p.applies_to === 'node' || p.applies_to === 'clade';
     };
 
-    forester.visualizationCandidates = function (tree) {
+    // options.keepConstant: also return a NUMERIC field that has one value on
+    // every tip. There is nothing to colour by in it, so the selection never
+    // asks for it -- but a matrix does: a single-copy core gene is a column
+    // of 1s, and dropping it from the heat map hid a gene the file lists.
+    forester.visualizationCandidates = function (tree, options) {
+        let keepConstant = !!(options && options.keepConstant);
         let total = 0;
         let stats = Object.create(null);   // id -> {kind, ref, label, nodes, values:Set, multi}; null-proto: ids embed file refs
 
@@ -2255,7 +2260,7 @@
             // 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) {
+            if (distinct < 2 && !(keepConstant && numeric)) {
                 return;
             }
             let colorMode;
@@ -2883,11 +2888,18 @@
      * no numeric per-tip property. `min`/`max` are over every value of every
      * column and are `null` when there is nothing to scale.
      */
-    forester.heatmapColumns = function (tree) {
+    forester.heatmapColumns = function (tree, only) {
+        let wanted = null;               // the figure's columns, when a file names them
+        if (Array.isArray(only)) {
+            wanted = Object.create(null);
+            only.forEach(function (ref) {
+                wanted[ref] = true;
+            });
+        }
         let numeric = Object.create(null);
         let label = Object.create(null);
-        forester.visualizationCandidates(tree).forEach(function (c) {
-            if (c && c.kind === 'property' && c.numeric === true && c.ref) {
+        forester.visualizationCandidates(tree, {keepConstant: true}).forEach(function (c) {
+            if (c && c.kind === 'property' && c.numeric === true && c.ref && (!wanted || wanted[c.ref])) {
                 numeric[c.ref] = true;
                 label[c.ref] = c.label || c.ref;
             }
@@ -2933,6 +2945,179 @@
         };
     };
 
+    // --------------------------------------------------------------
+    // The desktop's figure setting (aptx:figure)
+    // --------------------------------------------------------------
+    // The desktop Archaeopteryx stores what a tree is to be drawn with in one
+    // property of the PHYLOGENY: <property ref="aptx:figure" applies_to=
+    // "phylogeny"> as a direct child of <phylogeny>. Its value (FigureSpec
+    // on the desktop) is "v1;key=value;..." with every value escaped
+    // (PropertyTextCodec): \\ \t \n \r, \_ a space, \p "|", \s "~",
+    // \c ";", \e "=". columns= is a "|" list of ref~TYPE~SHAPE~normalized.
+    // Only a direct child of <phylogeny> counts (Christian, 2026-09-30: "a
+    // hard break"): desktops 0.11.117 to 0.11.172 wrote it on the root clade,
+    // and such a copy is ignored here and dropped on the way out, as the
+    // desktop does. An unknown version is no figure; unknown keys are ignored.
+    forester.FIGURE_REF = 'aptx:figure';
+
+    forester.unescapeFigureValue = function (v) {
+        const map = {'\\': '\\', 't': '\t', 'n': '\n', 'r': '\r', '_': ' ', 'p': '|', 's': '~', 'c': ';', 'e': '='};
+        return String(v).replace(/\\(.)/g, function (all, c) {
+            return map[c] !== undefined ? map[c] : all;
+        });
+    };
+
+    // {columns: [{ref, type, shape, normalized}]} from the tree's figure, or
+    // null when it has none (or one this version cannot read).
+    forester.readFigure = function (tree) {
+        let props = tree && Array.isArray(tree.properties) ? tree.properties : [];
+        let p = props.find(function (q) {
+            return q && q.ref === forester.FIGURE_REF;
+        });
+        if (!p || typeof p.value !== 'string') {
+            return null;
+        }
+        let parts = p.value.trim().split(';');
+        if (parts[0] !== 'v1') {
+            return null;
+        }
+        // labelProps: the properties the label shows, in order (null when the
+        // figure does not say, [] when it says none); show: the desktop's
+        // display switches by DisplayOption name ("show.SHOW_PROPERTIES=true")
+        let figure = {columns: [], labelProps: null, show: {}};
+        parts.slice(1).forEach(function (kv) {
+            let at = kv.indexOf('=');
+            if (at < 1) {
+                return;
+            }
+            let key = kv.substring(0, at);
+            let value = forester.unescapeFigureValue(kv.substring(at + 1));
+            if (key === 'labelprops') {
+                figure.labelProps = value.split('|').filter(function (r) {
+                    return r.length > 0;
+                });
+                return;
+            }
+            if (key.indexOf('show.') === 0 && (value === 'true' || value === 'false')) {
+                figure.show[key.substring(5)] = value === 'true';
+                return;
+            }
+            if (key !== 'columns') {
+                return;
+            }
+            value.split('|').forEach(function (col) {
+                let f = col.split('~');
+                if (f[0] && f[0].length > 0) {
+                    figure.columns.push({ref: f[0], type: f[1] || '', shape: f[2] || 'CIRCLE',
+                        normalized: f[3] === 'true'});
+                }
+            });
+        });
+        return figure;
+    };
+
+    // The refs the figure draws as a MATRIX, in its order ([] without one).
+    forester.figureMatrixRefs = function (tree) {
+        let figure = forester.readFigure(tree);
+        let seen = Object.create(null);
+        return figure ? figure.columns.filter(function (c) {
+            let keep = c.type === 'MATRIX' && !seen[c.ref];
+            seen[c.ref] = true;
+            return keep;
+        }).map(function (c) {
+            return c.ref;
+        }) : [];
+    };
+
+    // ---- Properties in the tip label (the desktop's "Properties" option) ----
+
+    // A property a reader would want to see: not the viewer's own aptx:
+    // metadata, not a style: instruction.
+    const LABEL_PROPERTY_SEPARATOR = ' | ';
+
+    forester.isUserVisiblePropertyRef = function (ref) {
+        return typeof ref === 'string' && ref.length > 0 && ref.indexOf('aptx:') !== 0 && ref.indexOf('style:') !== 0;
+    };
+
+    // Every user-visible property ref any node carries, internal nodes
+    // included, sorted by the name the reader sees (then by ref): what the
+    // label-field chooser offers. Deliberately BROADER than the colour-by
+    // candidates, which drop constant, per-tip-unique and internal-only fields
+    // -- all perfectly good label text (the desktop's userVisiblePropertyRefs).
+    forester.labelPropertyRefs = function (tree) {
+        let seen = Object.create(null);
+        forester.preOrderTraversalAll(tree, function (n) {
+            (n.properties || []).forEach(function (p) {
+                if (p && forester.isUserVisiblePropertyRef(p.ref)
+                    && p.value !== undefined && p.value !== null && String(p.value).trim().length > 0) {
+                    seen[p.ref] = true;
+                }
+            });
+        });
+        return Object.keys(seen).sort(function (a, b) {
+            let da = forester.propertyDisplayName(a).toLowerCase();
+            let db = forester.propertyDisplayName(b).toLowerCase();
+            return da < db ? -1 : (da > db ? 1 : (a < b ? -1 : (a > b ? 1 : 0)));
+        });
+    };
+
+    // A node's properties as one line of label text: values only, a unit
+    // after its value (without its namespace), joined by " | " as the rest of
+    // the label is. Not by ", " as on the desktop (Christian, 2026-09-30): a
+    // value often holds a comma itself -- a BV-BRC host "Bottlenose dolphin,
+    // Tursiops truncatus" -- and "host, species" then reads as three fields. `refs` picks and orders the fields; null is every
+    // user-visible property in the node's own order, less `excluded` (the
+    // heat map's columns: a field has one display role).
+    forester.labelPropertiesText = function (node, refs, excluded) {
+        let props = (node && node.properties) || [];
+        let parts = [];
+        let add = function (p) {
+            if (!p || !forester.isUserVisiblePropertyRef(p.ref) || p.value === undefined || p.value === null) {
+                return;
+            }
+            let v = String(p.value).trim();
+            if (v.length < 1) {
+                return;
+            }
+            if (typeof p.unit === 'string' && p.unit.length > 0) {
+                v += ' ' + p.unit.substring(p.unit.lastIndexOf(':') + 1);
+            }
+            parts.push(v);
+        };
+        if (refs) {
+            refs.forEach(function (ref) {
+                props.forEach(function (p) {
+                    if (p && p.ref === ref) {
+                        add(p);
+                    }
+                });
+            });
+        } else {
+            props.forEach(function (p) {
+                if (!(excluded && p && excluded[p.ref])) {
+                    add(p);
+                }
+            });
+        }
+        return parts.join(LABEL_PROPERTY_SEPARATOR);
+    };
+
+    // Removes an aptx:figure from every clade (the old place, now ignored),
+    // so a tree saved from here carries no dead copy. Returns how many.
+    forester.dropCladeFigures = function (tree) {
+        let n = 0;
+        forester.preOrderTraversalAll(tree, function (node) {
+            if (node !== tree && Array.isArray(node.properties)) {
+                let kept = node.properties.filter(function (q) {
+                    return !(q && q.ref === forester.FIGURE_REF);
+                });
+                n += node.properties.length - kept.length;
+                node.properties = kept;
+            }
+        });
+        return n;
+    };
+
     /**
      * The number in `node`'s heat-map cell for `ref`, or `null` when there is none.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.19.0",
+  "version": "3.20.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",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "phyloxml": "^1.1.2"
+    "phyloxml": "^1.1.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.13.0",