archaeopteryx 3.14.0 → 3.16.0

package/README.md

@@ -256,9 +256,38 @@ the mouse wheel zooms too, and never rotates), **X− / X+ become rotate** (a
 32nd of a turn per press), and the fit-width slot becomes the **node label
 direction** flip — labels riding their spokes or standing upright — while
 vertical expansion greys out. **Fit** centres and scales the fan; **Esc**
-also resets rotation and label direction. Unrooted
-additionally greys out the aligned-phylogram option and Auto-hide Labels
-(there is no common label edge, and no even row spacing to hide against).
+also resets rotation and label direction. **Each radial layout greys out the
+display type it cannot show.** Circular always aligns — its external labels are
+pulled out to a shared ring, with dashed connectors to match, whichever type is
+chosen — so the circular phylogram is the aligned one, and the greyed button
+there is the *unaligned* phylogram. Unrooted is the other way round: it has no
+common edge to align to, so the aligned type is the one greyed. The button shown
+as chosen describes the picture, and choosing the phylogram in circular leaves
+your aligned-or-not preference for the other layouts untouched. Auto-hide Labels
+stays live in every layout.
+
+### The control-panel cheat sheet
+
+The card button in the panel header opens **Control panel**: one row for every
+control the panel is currently showing, in the order it shows them, each with
+the control's own glyph or name and the sentence that explains it — the layout
+and display-type buttons included, drawn with the very glyph they carry in the
+panel. The About box has a row for it too.
+
+The display types say what they do and when they are greyed, whether or not
+they are greyed in the view you are looking at: *"phylogram: branch lengths
+drawn to scale, so the tips end ragged. Greyed in the circular layout, which
+always carries its labels to the outer ring, so there the aligned phylogram is
+the one drawn."*
+
+It is **modeless** and sits beside the panel, so a row can be read while the
+control it names is used. It describes what is on the screen: fold a section
+and its controls leave the sheet, open a tree that offers no alignment and the
+alignment controls are not listed. Nothing on it is written twice — a row's
+words are the tooltip the control already carries, so a control added later
+needs no edit here, only a tooltip. And no row shows a live value, so a sheet
+that is saved or printed does not go wrong for every reader but the one who
+made it.
 
 ## Rooting
 
@@ -526,9 +555,23 @@ section holds the controls:
   the tree), or `None`.
 * **Glow** — a soft glow in each domain's own colour around its box.
 
-In the circular and unrooted layouts the tracks ride each tip's spoke
-outward and carry no names (the legend still works); they need radial
-labels, which switching layouts turns on. A malformed domain — a missing or
+**Hovering a domain** reads it out: the domain's name, its E-value (small
+ones keep their exponent, 7.20e-117), the residues it spans with its own length and the protein's,
+the tree tip it belongs to, and its accession where the file carries one.
+**Clicking the box** looks the domain up: straight to the Pfam entry when
+there is an accession, and an InterPro search by name when there is not —
+phyloXML's domain `id` is optional, and a file with names alone (our own
+`apaf.xml` among them) cannot address an entry, since InterPro resolves
+accessions and not Pfam identifiers. Only the domain boxes take the mouse, so
+the tree behind the track stays clickable.
+
+In the circular and unrooted layouts the tracks ride each named tip's spoke
+outward and carry no names of their own (the legend still works); they need
+radial labels, which switching layouts turns on. An architecture goes with
+its name: where the crowding rule has taken a tip's name away, its track is
+left out too, since a track with no name beside it can only be identified by
+which spoke it sits on. Switching the name fields off is not the same thing —
+nothing is hidden by the rule then, and every track is still drawn. A malformed domain — a missing or
 impossible position or E-value — is skipped and counted in a console
 warning, never fatal. The tracks ride into the SVG, PDF and PNG exports.
 This is the desktop's domain display, drawn to the same numbers
@@ -555,7 +598,7 @@ To find a motif, pick **Molecular Sequence** in a search box: it matches the
 residues as written, gap characters included, as the desktop does.
 
 **Sequence Logo** (the checkbox under **Alignment**) replaces the conservation
-bar with a **logo**: every column a stack of letters, as tall as that column's
+bar with a **logo**: a stack of letters per column, as tall as that column's
 information content in bits and shared out by residue frequency, most frequent
 on top — the display the MEME Suite and WebLogo draw. A conserved column is one
 tall letter, a variable one a short pile, and the caption gives the scale
@@ -566,7 +609,8 @@ clade's motif rather than the file's, and the caption names how many tips that
 is (`n = 12`). Two consequences worth knowing: gaps are not a letter —
 frequencies are taken over the residues present, and the stack is then scaled
 by the column's occupancy, so a column held up by two sequences out of fifty
-draws short rather than perfectly conserved; and there is **no small-sample
+draws short rather than perfectly conserved and an all-gap column draws
+nothing; and there is **no small-sample
 correction**, because entering a three-tip clade is a normal thing to do and
 Schneider's correction would subtract more than the maximum and leave the
 column blank. Read `n` and judge.
@@ -1040,11 +1084,13 @@ each with a checkbox under Display Data to turn it off.
 Support and branch-length values draw **2 px smaller than the label font**
 (never below 6 px), as on the desktop, so they annotate without competing.
 And besides the numeric display there are **Support Dots**: a filled dot at
-the midpoint of every branch whose support is at least 95% (`supportDotMinimum`;
+the midpoint of a branch whose support is at least 95% (`supportDotMinimum`;
 posterior- and bootstrap-scaled trees are told apart automatically). The dot
 is always a fixed amount wider than the branch itself, so it tracks the
 Branch Width slider instead of sitting at one fixed size. A branch drawn
-shorter than the dot itself stays clean.
+shorter than the dot itself stays clean, and so does one whose dot would land
+on a dot already drawn — see the crowding rule below, which is what decides
+between them rather than either one being shrunk.
 
 The **control panel itself** follows the same idea. It opens showing the
 sections that describe the tree — what it can be coloured by, what it shows —
@@ -1090,6 +1136,85 @@ It describes what is on screen, so inside a subtree it describes the subtree
 and says so, and it is recomputed each time it opens rather than cached (24 ms
 on the 13,246-tip demo). There is no histogram.
 
+**Auto-hide Labels** also thins out **crowded branch data**. Support values,
+branch-length values and support symbols are drawn only where they fit: each
+mark claims the box it is about to occupy, and one that would overlap a box
+already claimed in that pass is left out. The claim order is the tree's own,
+root first, so the mark nearer the root keeps its place and the same tree at
+the same size always drops the same marks — on screen and in every export.
+
+**The Auto-hide Labels toggle lights up while it is taking something away**,
+and its tooltip says what. The switch governs three rules and the light asks
+all three: *1 in k labels shown* in the rectangular layout, which thins by
+index; *n names that would overprint* in the two radial layouts, which thin by
+overlap; and *n branch values that would overlap*, in any layout. It stays dark
+on a tree with room for everything.
+
+**In the circular and unrooted layouts, crowded tip labels are hidden by
+whether they actually overprint.** A name is drawn only where its own outline
+overlaps no name already drawn; the order is the tree's own, root first, so
+the same tree at the same size always keeps the same names. **A name found by
+a search is the exception**: it is drawn without being asked, so what you
+searched for is always on the screen — and since the names it would have
+yielded to are already down, a hit can be drawn across one. That is the rule
+both programs agreed on, the hit being the thing you are looking for, and it
+is the one case where the sentence above does not hold. The outlines are compared as they are drawn, turned, not as the
+upright boxes that enclose them — the bounds of a turned name are several
+times its own area, and comparing those would drop names that are plainly
+clear of each other.
+
+The rectangular layout keeps the every-k-th thinning, where it belongs: its
+rows really are evenly spaced, and `k` is read from the font size against the
+row pitch. A fan has no rows, and until 2026-09-27 the circular layout
+borrowed that rule anyway — thinning a ring by the display's *height* over the
+node count, a quantity with nothing to do with a ring's circumference. It was
+wrong in both directions. Measured at 1100×850: on `Caliciviridae_100.xml` it
+kept 48 of 97 names where all 97 fit the ring with **not one** overlapping
+pair; on `flu_h5.xml` it kept 59 of 354 where 118 are readable. Both now draw
+what fits.
+
+Both fans lose names where a fan is crowded — circular takes 236 of 354 on
+`flu_h5.xml`, and unrooted is the harsher of the two: on `Caliciviridae_100.xml`
+its 97 names had 172 overlapping pairs, the deepest printing 9.5 px through
+its neighbour, and 34 remain with none overlapping by more than the width of
+the measurement itself. Where there is room, nothing is dropped:
+`woese-tree-of-life.xml` keeps all 23 in every layout.
+
+**Names go down first, and numbers yield to them.** Every node label that will
+be drawn — a tip name or a clade name — reserves its space before any mark is
+placed, and it is never asked: a label is drawn whatever else is there, so a
+number that would print through a name is the one left out. A value that has
+landed across a name is worse than a value not drawn at all, and it is the
+name that says what the tree is about. Measured at 1100×850 with both numbers
+on, before this: 44 of 93 numbers printed through a name in the rectangular
+view of `flu_h5.xml`, 30 of 55 on `confidences.xml`, 10 of 15 in the unrooted
+view. Now none, in any of the three layouts, and no number is refused unless
+something drawn is in its way.
+Numbers and symbols are kept in separate maps, since the symbol sits on the
+branch and the numbers just above and below it. Symbols are never shrunk to
+fit: where a symbol's size means something, a smaller one would report
+something else. Switch the toggle off and everything is drawn. Zero needs no
+special case — a lone zero-length branch overlaps nothing, so its number
+stays. Branch events take part too. This is the desktop Archaeopteryx's rule,
+adopted so the two programs thin the same tree the same way; the marks they
+drop are close but not identical, because the boxes come from each program's
+own font metrics.
+
+It applies in **all three layouts**. In the circular and unrooted views a mark
+rides its branch: it is drawn at the branch's midpoint, turned to the branch's
+direction and set just off the line, so the box claimed for it is the
+axis-aligned bounds of that turned rectangle, centred where the text's own
+centre lands — the desktop's formula, which carries over because both programs
+measure it in real screen space rather than in the layout's own units. A
+diagonal label's bounds are wider than its ink, so a crowded number is dropped
+rather than overprinted. The circular view of `flu_h5.xml` goes from 785 drawn
+numbers, 743 of them overlapping another, to 87 with none.
+
+One placement follows from that: in the two radial views every mark is drawn on
+the same point, the branch's midpoint, so a **branch event** sits a line clear
+of the branch-length value rather than on top of it. In the rectangular layout
+they are already apart along the branch and share the line above it.
+
 A host with little room to give can
 also start the whole panel tighter and narrower with
 [`panelDensity: 'compact'`](#configuration), or collapsed to its header bar
@@ -1128,7 +1253,7 @@ 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. |
-| `showMsaLogo` | `false` | Open with the alignment summarised as a sequence logo instead of a conservation bar: each column a stack of letters as tall as its information content, over the tips currently on screen. Only drawn while the alignment track is shown. |
+| `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. |
 | `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. |
@@ -1288,7 +1413,7 @@ All 118 of them, alphabetically:
 | `showBranchVisualizations` | Node and branch visualizations are one switch now; use the Visualizations checkbox. |
 | `showConfidenceValues` | Shown when the tree has confidences. |
 | `showDistributions` | Off by default. |
-| `showDynahideButton` | Shown automatically once the tree has enough tips to need it. |
+| `showDynahideButton` | The Auto-hide Labels checkbox is always shown. |
 | `showExternalLabels` | On by default; use the Ext. Labels checkbox. |
 | `showExternalLabelsButton` | Always shown. |
 | `showExternalNodes` | Node shapes now appear wherever a node visualization applies. |
@@ -1308,7 +1433,7 @@ All 118 of them, alphabetically:
 | `showSequenceGeneSymbol` | Sequence labelling follows what the tree contains. |
 | `showSequenceName` | Sequence labelling follows what the tree contains. |
 | `showSequenceSymbol` | Sequence labelling follows what the tree contains. |
-| `showShortenNodeNamesButton` | Shown automatically when the tree has long node names. |
+| `showShortenNodeNamesButton` | The Short Names checkbox is always shown; it starts on when the tree has long node names. |
 | `showTaxonomy` | Shown when the tree has taxonomies. |
 | `showTaxonomyButton` | Shown automatically when the tree has taxonomies. |
 | `showTaxonomyCode` | Taxonomy labelling follows what the tree contains. |
@@ -1686,6 +1811,22 @@ The 2026 additions beyond the visualization system, specified tightly enough
 to rebuild. All pure logic lives in forester.js under `npm test`; the viewer
 draws.
 
+The counts quoted above are measurements on one machine, and how many names
+fit a ring depends on how wide the system draws them: the same tree keeps 34
+in the unrooted view here and 33 on a Linux CI runner, with the crowding
+identical on both (97 names, 172 overlapping pairs with the rule off). The
+rule is the same; the font is not.
+
+What the viewer draws is checked separately, by driving it in headless Chrome:
+`npm run test:browser` (or `test:browser:quick`, one case per harness, which is
+what CI runs). Those harnesses open a real tree, work the controls and measure
+the result — which marks are drawn, where they sit, whether a control lights.
+They exist because `npm test` cannot reach any of it: it covers the arithmetic,
+and the defects this code has actually had were wiring. A connector drawn out
+to the ring for a name that was hidden, an Auto-hide indicator dark over a tree
+it was thinning, a domain architecture left beside a tip whose name had gone —
+each of those passed every node test and every lint.
+
 ### The unrooted layout
 
 `forester.equalAngleLayout(root, startAngle, lengthOf)` — Meacham's
@@ -1708,8 +1849,12 @@ mathematics — `spokeAngle(d)` is `uangle` in unrooted and the cluster angle
 minus π/2 in circular; `labelAngleDeg` rotates a label along its spoke and
 `labelFlip` adds 180° on the left half (`spokeAngle mod 2π ∈ (π/2, 3π/2)`).
 `layoutPointXY(d)` resolves a node's position in any layout for every
-consumer (overview dots, hit navigator, node transforms). Unrooted disables
-aligned phylograms and label auto-hiding, as the desktop does.
+consumer (overview dots, hit navigator, node transforms). Unrooted has no
+common edge to align labels to, so the aligned phylogram is the display type
+it greys out (circular greys the unaligned one instead, since it always
+aligns). Neither radial layout has even rows, so the every-k-th
+tip-label thinning runs in the rectangular layout alone — both fans hide their
+crowded names by overlap instead, as on the desktop.
 
 ### The domain tracks
 
@@ -1720,7 +1865,10 @@ drawable when `from` and `to` are integers with `to > from` and `confidence`
 (its E-value) is a number; otherwise it is skipped and counted
 (`forester.domainArchitectureDomains`). Gate: `showDomainArchitectures`
 state (auto-on when `_basicTreeProperties.domainArchitectures`) AND external
-labels shown AND, in a radial layout, radial rather than upright labels.
+labels shown AND, in a radial layout, radial rather than upright labels AND,
+per tip, a name the crowding rule has not taken (`_labelDropped`) — note
+"taken by the rule", not "absent": with the name fields switched off nothing
+is hidden by the rule and every track is still drawn.
 
 Scale: one factor for the tree, `f = W_eff / Lmax × 0.9` px per residue.
 `W` (the track width) starts at `0.25 × viewport width`; `d+` / `d−` scale it
@@ -1733,8 +1881,8 @@ threshold never rescales. The rectangular layout reserves `20 + W + 10` px
 from `_w` past the label reservation (`_domainReserve`, counted wherever `_w`
 is), so the tree compresses to make room; the radial fit adds
 `4 + W_eff + 10` to the ring. Placement: rectangular `start = _w +
-nodeLabelGap + labelSpace + 20` for every tip (one aligned column) with box
-height `clamp(round(tipPitch / 2), 6, 16)`; circular `r0 = maxRad +
+nodeLabelGap + labelSpace + 20` for every tip still showing its name (one
+aligned column) with box height `clamp(round(tipPitch / 2), 6, 16)`; circular `r0 = maxRad +
 labelSpace + 4` under `rotate(spoke)`; unrooted `translate(tip)
 rotate(spoke)` with `start = labelSpace + 4`. A domain `from..to` covers
 `[start + (from − 1) f, start + to f]` — residue `r` is `[(r − 1) f, r f]`,