archaeopteryx 3.15.0 → 3.17.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
@@ -599,7 +630,8 @@ missing symbol `?` arrives as `X` or `N`. A phyloXML `<mol_seq>` is kept
 exactly as written, by both programs. Sequences
 of *unequal* length are not an alignment and cannot form a character matrix,
 so they are not written at all — the file says so in a bracketed comment
-rather than padding them into an alignment that does not exist.
+rather than padding them into an alignment that does not exist, and the
+Nexus entry of the Download menu says so before you choose it.
 
 ## Heat maps
 
@@ -973,12 +1005,62 @@ a popup any more, and nothing fails silently.
 | **MrBayes** annotations | in (embedded in Newick/Nexus) | `prob=`/`prob.stddev=` blobs: posterior-probability clade support. | [8] |
 | **Metadata table** (`.tsv`, `.csv`) | in (beside a tree) | A header row and one row per tip, the first column naming the tip: every other column is joined onto the tips as a property, so it is offered for Color-by and Shape, searched, shown in the node data and written into phyloXML exports. See [Metadata tables](#metadata-tables). | — |
 | **FASTA** | out | The molecular sequence(s) of the selected tip(s), or every sequence the tree carries. Offered in the Download menu only when the tree actually carries molecular sequences (aligned or not). | [9] |
-| SVG · PNG · vector PDF | out | A snapshot of the drawn tree for publication or further editing — vector (SVG, PDF) or raster (PNG). General-purpose graphics formats, not phylogenetic data, so no literature reference applies. | — |
+| SVG · PNG · vector PDF | out | The drawn tree for publication or further editing — vector (SVG, PDF) or raster (PNG), either as shown on screen or the whole tree at full size (see [Downloads](#downloads)). General-purpose graphics formats, not phylogenetic data, so no literature reference applies. | — |
 
 The parser for a given input is auto-detected (see **The entry points**
 above); the Download menu offers whichever output formats the current tree
 can carry.
 
+### Downloads
+
+The panel's **Download** section (folded until you open it) holds the choices
+every download shares, and its **Download…** button opens the format menu,
+grouped as Graphics, Tree and Tip data. Each entry says what that format keeps — phyloXML everything the
+tree carries, Newick only names, branch lengths and support — and the Nexus
+entry says, before you pick it, whether the file will carry the alignment or,
+when the sequences are of unequal length, why it cannot.
+
+* **Name** — the file name; each format adds its own extension (a typed
+  `.svg` or `.tre` is not doubled). It starts as the tree's name.
+* **Graphics: As shown / Full size** — what SVG, PDF and PNG draw. *As shown*
+  is the window: the part of the tree in view, at the current zoom. *Full
+  size* (the default) is the whole tree, re-laid-out large enough that no tip
+  name has to be hidden — in rows in the rectangular layout, around the ring in
+  the circular one — and cropped to the drawing, with the legends (colour,
+  shape, domains, the heat-map ring's scale) stacked beside the tree rather
+  than over it. The window itself is left exactly as it was. An unrooted fan
+  is enlarged only while that still frees names: tips on very short branches
+  can collide at any size. An alignment track is drawn as its window, the
+  columns in view, in a full-size figure too: a genome-length alignment drawn
+  whole would be hundreds of thousands of cells.
+* **PNG: 2× / 4× / 8×** — the image's resolution relative to the screen
+  (`pngExportScale` sets the starting choice, snapped to one of the three). A browser caps how large a
+  canvas it will paint; past that the PNG comes out at the largest scale it can
+  paint, with a console warning, rather than blank.
+* **Copy Newick** puts the tree on the clipboard, exactly as the Newick
+  download writes it.
+* **Copy PNG** puts the picture on the clipboard, drawn as the Graphics and PNG
+  choices say — ready to paste into a Word document or a slide. It needs a
+  secure page (https, or localhost) and canvg, and is offered only where both
+  are there.
+
+**In a subtree, and with clades collapsed.** Every download follows the tree
+you are looking at. In a **subtree** the files hold the subtree only — the
+menu's Tree and Tip data groups say so ("subtree, 19 of 50 tips"), and
+phyloXML and Nexus name it after the tree, marked "(subtree)"; the subtree is
+written as a rooted tree of its own, its root keeping the branch that leads
+into it. A **collapsed** clade is how the tree is drawn, not what it holds:
+the graphics draw it collapsed, as on screen, and every file writes it in
+full.
+
+**TSV** (under Tip data) writes every tip's data as a table, one row per tip in
+the order drawn: the node menu's **Download Ext. Node Data** for the whole
+tree, with the same columns, and a table that joins back onto the tree as
+[metadata](#metadata-tables).
+
+A full-size PDF taller or wider than 200 inches (14,400 pt, the PDF page
+limit) is scaled onto the largest page; it is vector, so nothing is lost.
+
 Newick and Nexus files usually carry branch support as a bare internal label
 (`)100:0.05`). Archaeopteryx.js recognises those automatically and treats them
 as confidence values, so support-based features work without any setup. If your
@@ -1110,7 +1192,56 @@ 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 same size always drops the same marks — on screen and in an *As shown*
+export. A *Full size* figure is drawn larger, so it has room to keep more.
+
+**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
@@ -1195,7 +1326,7 @@ copy-pastable JSON.
 | `visualizationsLegendXpos` | `254` | Legend position, x. |
 | `visualizationsLegendYpos` | `30` | Legend position, y. |
 | `enableDownloads` | `true` | Offer the download buttons. |
-| `pngExportScale` | `4` | PNG export resolution multiplier. |
+| `pngExportScale` | `4` | The PNG resolution the Download section starts on: 2, 4 or 8 (any other value is snapped to the nearest, with a console warning). |
 | `nhExportWriteConfidences` | `true` | Write confidences into exported Newick. |
 | `internalNumericLabels` | `'auto'` | Newick / Nexus parsing: how a bare numeric internal label (`)100:0.05`) is read. `'auto'` reads them as confidence values only when *every* internal label looks like support; `'confidence'` reads every numeric label as one, whatever its value; `'label'` keeps them as names. Replaces `nhConfidenceValuesAsInternalNames` (still accepted, with a warning; its `true` maps to `'confidence'`). |
 | `nodeLabels` | `null` | Custom label-field checkboxes: `{key: {label, description, propertyRef, showButton, selected}}` — each adds a panel checkbox labelling nodes with the named property's value. (Was `launch()`'s sixth positional argument.) |
@@ -1306,11 +1437,11 @@ All 118 of them, alphabetically:
 | `labelColorDefault` | The default label colour is fixed. |
 | `minBranchLengthValueToShow` | No longer configurable. |
 | `minConfidenceValueToShow` | No longer configurable. |
-| `nameForFastaDownload` | Download names follow `treeName`. |
-| `nameForNhDownload` | Download names follow `treeName`. |
-| `nameForPhyloXmlDownload` | Download names follow `treeName`. |
-| `nameForPngDownload` | Download names follow `treeName`. |
-| `nameForSvgDownload` | Download names follow `treeName`. |
+| `nameForFastaDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForNhDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForPhyloXmlDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForPngDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForSvgDownload` | Download names follow `treeName`, or the Download section's Name field. |
 | `nhExportReplaceIllegalChars` | Always on; Newick cannot carry those characters. |
 | `nodeLabelGap` | The label gap is fixed. |
 | `nodeSizeDefault` | Node size is fixed; the Node size slider changes it. |
@@ -1334,7 +1465,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 +1485,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 +1863,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 +1901,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 +1917,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 +1933,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]`,

package/archaeopteryx.d.ts

@@ -79,6 +79,8 @@ export interface ArchaeopteryxConfig {
     /** 'compact' tightens the control panel's spacing and narrows it (the
      * tree's left margin follows). The same controls, nothing hidden. */
     panelDensity?: 'comfortable' | 'compact';
+    /** The PNG resolution the Download section starts on, snapped to its
+     * 2x, 4x or 8x. */
     pngExportScale?: number;
     rootOffset?: number;
     searchAinitialValue?: string | null;