archaeopteryx 3.15.0 → 3.16.0

package/README.md

@@ -256,11 +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 (there is no common label
-edge). Auto-hide Labels stays live: the tip-label thinning it governs needs
-even row spacing and so does nothing in unrooted, but the crowded-branch-data
-rule it also governs applies in every layout.
+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
 
@@ -538,9 +565,13 @@ phyloXML's domain `id` is optional, and a file with names alone (our own
 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 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
+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
@@ -1111,6 +1142,54 @@ 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
@@ -1334,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. |
@@ -1354,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. |
@@ -1732,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
@@ -1754,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
 
@@ -1766,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
@@ -1779,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]`,