archaeopteryx 3.2.1 → 3.4.0

package/README.md

@@ -31,6 +31,7 @@ config key live and shows the exact config JSON to copy into your own
 * [Herpesviridae DNA polymerase (201 tips)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=herpes_dnapol)
 * [Caliciviridae (186 strains)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=caliciviridae_500)
 * [Adenoviridae (321 strains)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=adenoviridae)
+* [Apaf-1 gene family (domain architectures)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=apaf)
 * [Nucleotide alignment (600 columns)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=alignment_nt)
 * [Genome alignment (150 × 30,000 columns)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=genome_alignment)
 * [Sequence alignment](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=alignment)
@@ -38,7 +39,6 @@ config key live and shows the exact config JSON to copy into your own
 * [Dinosaur time tree](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=dinosaur)
 * [Ammonite time tree (fossil ranges)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=ammonite)
 * [Late Cretaceous time tree (stages)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=late_cretaceous)
-* [Apaf-1 gene family](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=apaf)
 * [Bcl-2 family](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=bcl2)
 * [Confidence values](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=confidences)
 * [Branch events](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=branch_events)
@@ -177,15 +177,19 @@ and decides by itself what is worth showing. There is nothing to configure.
   two where both make sense.
 * The **legend** is a card you can **drag anywhere**. It shows a colour and
   a **count** per value, `[by count]` / `[A-Z]` toggles the order, a dashed
-  **no value** row counts the nodes the field does not cover, and very long
+  **no value** row counts the nodes the field does not cover (a value that is
+  nothing but underscores or a `;`/`:` qualifier counts as no value), and very long
   legends show the top 20 with a `[+N more]` chip. Legends are part of PNG,
   PDF
   and SVG exports (exports always come out light).
-* **Switch into a subtree** (or delete part of the tree) and the menus,
-  counts and legends are re-derived for what is on screen — a field with too
-  many values on the full tree may become available inside a clade. Colours
-  never change when you do this: a value keeps its colour for the whole
-  session.
+* **Switch into a subtree** and the legend re-describes what is on screen —
+  rows, counts, the **no value** row, and a numeric field's colours-or-gradient
+  band — while the menus and your Color / Shape choice stand exactly as they
+  were: colouring by Genus and entering a one-genus clade shows a one-row
+  legend, not a grey tree. A category value keeps its colour for the whole
+  session; a gradient re-spans the values on screen. **Deleting** part of the
+  tree re-derives the menus from what is left, and keeps your choice as long
+  as its field still has a value somewhere.
 * The **Visualizations** checkbox hides the chosen colours/shapes; the
   **Visual Styles** checkbox controls colours embedded in the tree file
   itself (and phyloXML branch colours). Search hits and selections always
@@ -198,6 +202,42 @@ panel: **rectangular** (root at left), **circular**, and **unrooted** — the
 desktop's equal-angle fan, where each subtree opens a wedge proportional to
 how many tips it holds.
 
+In the rectangular layouts a rooted tree shows a short **stub** branch into
+its root; a tree that declares itself unrooted (phyloXML `rooted="false"`, a
+Nexus `[&U]` tree) shows none, and the circular layout never draws one. A
+subtree view always shows the stub, since a clade has a definite root,
+whatever the branch above it was. When the whole tree is a phylogram and the
+file gives the root a branch length, that branch is drawn to scale instead
+of the stub — except in the **unrooted** display, which draws no root branch
+of any kind, real or stub: there the root is a point of the fan, not the end
+of a branch from nowhere. The root itself wears a circle only for the reasons
+any node does — an event, a search hit, a selection, a visualization.
+
+**Collapsing a clade.** The node menu's **Collapse/Uncollapse** folds an
+internal node's whole clade into a wedge and opens it again; **Uncollapse
+Subtree** opens everything below a node; the tool row's uncollapse-all button
+(the desktop's glyph, lit only while something is collapsed) opens the whole
+tree, and so does **Esc**. The wedge is the desktop's triangle: its apex at
+the node, its vertical base at the clade's average tip distance (one depth
+step in a cladogram), so its depth stays readable; it is filled in the colour most of its tips wear under the current
+Color-by, grows gently taller with its tip count, and is named — the node's
+own name if it has one; else the one Color-by value nearly all its tips share,
+so a clade reads "Bovine · 12 tips" while you look at hosts; else the tips'
+common name prefix; always with the tip count, and with `[found/total]` while
+a search hits inside it. Legends, alignment rows and domain tracks describe
+the tips on screen, so a collapsed clade's tips leave them. Collapsing is
+display state only: nothing is removed, exports and downloads carry every
+tip, and the unrooted layout, which has no rows to fold, shows every clade
+open. The controls are the desktop's; the drawing and naming are this
+program's.
+
+A phylogram carries a **scale bar** at the bottom left: a round number of
+branch-length units (1, 2 or 5 × 10ᵏ, whichever makes the bar about 100 px)
+with its length written above it. It is drawn with the tree, so it zooms and
+exports with it and its label always holds. A cladogram has nothing to
+measure and shows none, and a tree under a time axis leaves the measuring to
+the axis.
+
 In the two radial layouts the zoom row changes meaning, exactly as on the
 desktop: **Y+ / Y− become the plain + / − zoom** (a circle has one diameter;
 the mouse wheel zooms too, and never rotates), **X− / X+ become rotate** (a
@@ -208,6 +248,36 @@ 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).
 
+## Metadata tables
+
+A tree file rarely carries everything known about its tips. A **metadata
+table** beside it does: TSV or CSV, a header row, the first column naming the
+tip and every other column a piece of data. On the [open page](https://cmzmasek.github.io/archaeopteryx-js/open.html)
+drop, choose or paste the table before or after the tree — a table pasted
+first waits for the tree; one added while a tree is showing joins it and the
+view relaunches — and the toolbar says how many columns joined how many tips,
+with the rows that matched no tip and the tips without a row a hover away.
+
+Each column becomes a node property (`meta:` plus the header, so "Collection
+Date" comes back as `Collection Date` in every menu; a header that already
+reads as `namespace:name` is kept as it is). From there nothing is special:
+the columns are offered for **Color-by** and **Shape** by the same rules as
+any property, with the same legends; they are **search** fields, typed
+numeric when every filled cell is a number; they appear in the **node data**;
+and they are written into a phyloXML export, so a saved tree keeps them.
+Tip names are matched exactly, then case-insensitively; empty cells add
+nothing; a column the tree already carries under the same ref is replaced by
+the table's values. Quoted cells, `#` comment lines and Windows line ends are
+fine.
+
+Embedders do the same in two lines, before `launch()`:
+
+```js
+const tree = archaeopteryx.parseTree(name, treeText);
+const report = forester.joinMetadataTable(tree, tableText);  // {columns, tips, matchedTips, unmatchedTips, unmatchedRows, properties}
+archaeopteryx.launch('#tree', tree, config);
+```
+
 ## Searching
 
 Two search boxes (A and B), each with its own **field** menu (built from what
@@ -228,12 +298,93 @@ press centres the previous / next hit in the viewport, wrapping around.
 
 ## Keyboard
 
-Deliberately minimal: **Esc** or **Home** resets the view, **O** cycles the
-overview between corners, **PageUp / PageDown** change the font size — and
-the **mouse wheel** zooms (Shift: vertical only; Shift+Alt: horizontal;
-Ctrl+Shift: font size). Everything else is a button; the old Alt+letter
-combos are gone (macOS labels that key Option and types glyphs with it).
-Nothing fires while the cursor is in a text box.
+The same actions on every platform; only the modifier differs: **⌘** on
+macOS, **Ctrl** on Windows and Linux. **⌘/** (Ctrl+/) shows this list in
+the viewer, drawn for the platform you are on; the About box links to it
+too.
+
+| macOS | Windows / Linux | Does |
+|---|---|---|
+| ⌘0 | Ctrl+0 | Fit the tree to the window |
+| ⌘+ / ⌘− | Ctrl++ / Ctrl+− | Zoom in / out |
+| ⌘⇧↑ / ⌘⇧↓ | Ctrl+Shift+↑ / ↓ | Zoom in / out vertically |
+| ⌘⇧→ / ⌘⇧← | Ctrl+Shift+→ / ← | Zoom in / out horizontally (circular: rotate) |
+| ⌘⇧E | Ctrl+Shift+E | Expand vertically until the labels fit |
+| ⌘⇧L | Ctrl+Shift+L | Next layout: rectangular, circular, unrooted |
+| ⌘⇧D | Ctrl+Shift+D | Next display type: phylogram, aligned, cladogram |
+| ⌘⇧X | Ctrl+Shift+X | Time axis on / off |
+| ⌘⇧O | Ctrl+Shift+O | Ladderize |
+| ⌘⇧U | Ctrl+Shift+U | Uncollapse every clade |
+| ⌘F | Ctrl+F | Go to the search box |
+| ⌘G / ⌘⇧G | Ctrl+G / Ctrl+Shift+G | Next / previous search hit |
+| ⌘⇧< / ⌘⇧> | Ctrl+Shift+< / > | Previous / next tree of a multi-tree file |
+| ⌘/ | Ctrl+/ | The shortcut list |
+| Esc or Home | Esc or Home | Back to the whole tree, the launch view |
+| O | O | Move the overview to the next corner |
+| Page Up / Page Down | PageUp / PageDown | Larger / smaller font |
+
+Mouse wheel, also the same everywhere: plain zooms both axes, **Shift**
+vertical only, **Shift+Alt** (macOS: Shift+Option) horizontal only,
+**Ctrl+Shift** the font size. Inside a text box only the combos that cannot
+interfere with typing fire (fit, zoom, search, the list); the plain keys
+never do. The letters follow the desktop Archaeopteryx where it has the
+action (its Alt+O, Alt+U, Alt+E and ⌘0, ⌘G). There is no key for
+re-rooting, by decision. On Linux, Ctrl+Shift+U inside a text field is the
+desktop's Unicode entry: it stays with the text field there, as it should.
+
+## Sharing a view
+
+A view is what you made of a tree with the panel: the layout and display
+type, which labels show, the colour and shape fields, both searches, the
+clade you switched to, the clades you collapsed, the font, node and branch
+sizes, the rotation, the tracks. On the demo pages it rides in the URL's
+`#` hash and follows every change, so the address bar is always a link to
+what is on screen: copy it (**Copy link to this view** in the toolbar) and
+the recipient opens the same tree in the same view. Opening your own file
+keeps the view in the hash too, so the same file reopened at that address
+comes back as you left it. Zoom, pan, the legend's position and the node
+selection are not part of a view; a shared view opens fitted.
+
+Embedders get the same four pieces: the handle's `getViewState()` and
+`applyViewState(state)`, the config's `view` (open straight into one) and
+`onViewChange(state, encoded)` (called when it changes), and
+`archaeopteryx.encodeViewState()` / `decodeViewState()` for the hash form,
+which reads like
+`layout=circular&colorBy=tax:common_name&show=name,external&font=9&collapsed=12,44&a=HUMAN&af=Any+Text&am=contains`.
+Nodes are named by their launch-time preorder index, so a view belongs to
+the tree it was made on; a key a view leaves out keeps its current value,
+and anything that does not fit the tree is skipped.
+
+## Protein domain architectures
+
+A tree whose tips carry `<domain_architecture>` elements (a protein's length
+and its domains, each with a position and an E-value) draws them as **domain
+tracks** beside the tips: a thin grey backbone, `L` residues long, with a
+rounded box per domain, placed at its residues on one scale shared by the
+whole tree so lengths compare across tips, coloured by domain name from the
+Tableau palette, with the name written on the box when it fits. The tracks
+appear from the start whenever a tree carries them; the **Domain
+Architectures** checkbox under Display Data toggles them, and their own
+section holds the controls:
+
+* **Track width** `−` / `+` — the longest architecture's track starts at a
+  quarter of the window and scales by 0.8 / 1.2 per press (hold to repeat).
+* **E-value ≤** `−` `10⁻³` `+` — only domains at or under the threshold are
+  drawn; each press moves it by a factor of ten, from `10⁻²⁰` to `10³`. The
+  colours are dealt again to the names that remain, in sorted order.
+* **Labels** — `On domains` (the default), `Legend` (a card, at home in the
+  bottom-right corner, draggable, double-click to send it back: one row per
+  drawn name with its box count, in the order the names first appear down
+  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
+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
+(`test/domain_test.js` holds them).
 
 ## Sequence alignments
 
@@ -365,6 +516,13 @@ const viewer = archaeopteryx.launchArchaeopteryx(container, fileName, data, conf
 const tree = archaeopteryx.parseTree(fileName, data);
 const viewer = archaeopteryx.launch(container, tree, config);
 
+// every tree the file holds (a Nexus TREES block, a multi-tree Newick,
+// several phylogenies): launch() takes the list, shows the first, and
+// the panel gets a picker for the rest
+const trees = archaeopteryx.parseTrees(fileName, data);
+const viewer = archaeopteryx.launch(container, trees, config);
+viewer.showTree(1);   // also viewer.getTreeIndex(), viewer.getTreeCount()
+
 // later, e.g. when an SPA removes the view:
 viewer.destroy();
 ```
@@ -390,7 +548,7 @@ viewer.destroy();          // unmount COMPLETELY: the container DOM, the node
                            // handler; a later launch() works normally
 ```
 
-**Big trees draw on the next frame.** Above 2,000 nodes, `launch()` does all
+**Big trees draw on the next frame.** Above 3,000 nodes, `launch()` does all
 its validation, shows a "Drawing N nodes" card over the tree area, and
 returns within milliseconds — the label analysis, visualization candidates,
 control panel and the draw itself all run one frame later, so the browser
@@ -454,9 +612,13 @@ The parser is picked from the data and the `location`: content starting with
 `#NEXUS` (or a name ending in `.nex`/`.nexus`) is read as Nexus, JSON content
 (or a name ending in `.json`) as an **Auspice/Nextstrain v2** `dataset.json`,
 a name ending in `xml` as phyloXML, anything else as New Hampshire (Newick).
-A Nexus file shows its **first** tree; a protein/DNA/RNA characters matrix in
-the file (sequential or interleaved) lands on the tips as an aligned
-`mol_seq`, so the alignment track appears just as it does for phyloXML.
+A file holding **several trees** — a Nexus TREES block, a Newick file with one
+tree per `;`, a phyloXML with several phylogenies — opens on the first, and a
+picker with previous / next buttons at the top of the control panel moves
+between them; each tree opens fresh under the same config, the way a new tab
+does on the desktop. A protein/DNA/RNA characters matrix in a Nexus file
+(sequential or interleaved) lands on the tips as an aligned `mol_seq`, so the
+alignment track appears just as it does for phyloXML.
 
 An Auspice dataset opens on the **time view** (branch lengths from `num_date`
 differences; a divergence-only build falls back to `div` differences): the
@@ -496,6 +658,7 @@ a popup any more, and nothing fails silently.
 | **Auspice / Nextstrain** `dataset.json` (v2) | in | Phylodynamic builds: sampling dates and their confidence, cumulative divergence, and discrete traits (country, clade, host, ...) with their posterior distributions. | [5] |
 | **BEAST** / BEAST 2 / TreeAnnotator annotations | in (embedded in Newick/Nexus) | `[&posterior=...,height_95%_HPD={lo,hi},rate=...]`-style blobs: posterior clade support, node-age confidence intervals, per-branch rates and other traits. FigTree's `!color` is read the same way. | [6, 7] |
 | **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. | — |
 
@@ -588,7 +751,7 @@ shorter than the dot itself stays clean.
 One object, passed as the third argument. It is optional, and the best
 configuration is usually an empty one — almost everything that used to be
 configured is now read off the tree (see **Intelligent pre-sets** above). The
-twenty-eight keys below are the ones no tree can answer for you.
+thirty keys below are the ones no tree can answer for you.
 
 There used to be two objects, `options` and `settings`, split by whether the
 user could also change the value from the control panel. That was a fact about
@@ -615,11 +778,17 @@ 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. |
+| `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. |
+| `domainLabels` | `'domains'` | Where domain names go: `'domains'` (on the boxes), `'legend'` (a card), or `'none'`. |
+| `domainGlow` | `false` | Open with the glow around each domain box on. |
+| `domainEvalueExponent` | `-3` | The E-value threshold's exponent at launch, an integer from `-20` to `3`: domains with an E-value at or under `10^exponent` are drawn. |
 | `showTimeAxis` | tree-derived | Open with the time axis shown. Default: on when the tree carries `<date>` elements, off otherwise — an explicit `true`/`false` overrides that. |
 | `timeAxisGrid` | `false` | Open with the Time Grid vertical lines on (only meaningful — and only offered as a checkbox — while the time axis itself is shown). |
 | `showSupportDots` | `false` | Open with the Support Dots marks on (the checkbox appears whenever the tree has confidences). |
 | `supportDotMinimum` | `95` | Support Dots threshold, as a percentage. On a tree whose confidences top out at 1 (posterior probabilities) it is read on the 0–1 scale, so the default means ≥ 0.95 there and ≥ 95 on a bootstrap tree. |
 | `searchAinitialValue` | `null` | Prefill search box A. |
+| `view` | `null` | Open straight into a saved view — the object `getViewState()` returns, or `decodeViewState()` reads from a URL hash: layout, display type, labels, colours, searches, the clade and the collapsed clades, sizes. See **Sharing a view**. |
+| `onViewChange` | `null` | `function (state, encoded)`, called once per settled redraw when the view changed: `state` as `getViewState()` returns it, `encoded` its hash-ready string. The demo pages write it into the URL. |
 | `searchBinitialValue` | `null` | Prefill search box B. |
 | `enableVisualizations` | `true` | Offer the Color / Shape visualizations (which fields they cover is decided from the tree). |
 | `initialVisualization` | `null` | The visualization to open with, by its Color-menu name (e.g. `'Host'`; case-insensitive). A name the tree cannot honour logs a console warning and falls back to the automatic choice, so a site-wide value is safe on trees without that field. Default: Archaeopteryx.js picks the most informative field itself. |
@@ -1188,6 +1357,57 @@ minus π/2 in circular; `labelAngleDeg` rotates a label along its spoke and
 consumer (overview dots, hit navigator, node transforms). Unrooted disables
 aligned phylograms and label auto-hiding, as the desktop does.
 
+### The domain tracks
+
+Data model: per-tip `sequences[i].domain_architecture = {length, domains:
+[{name, from, to, confidence}]}` — the first sequence carrying one; `length`
+must be a positive integer or the architecture is not drawn. A domain is
+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.
+
+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
+by 1.2 / 0.8 and stop at 2000 / 20. `W_eff = W` in the rectangular layout,
+a width of the radial layouts' own, which starts at `min(W, 0.2 × radius)`
+and is then stepped by the same buttons (the desktop caps the drawn width at
+that fifth of the radius instead). `Lmax` is the longest architecture
+in the displayed tree, counting every domain whatever its E-value, so the
+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 +
+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]`,
+decided jointly with the desktop on 2026-09-12.
+
+Drawing, per box, in this order: three stepped shadow rects (`rgb(8,18,21)`
+at 40 / 28 / 17 of 255, offset 0.4/0.7, 0.9/1.5, 1.6/2.5), the optional two
+glow rects (the base colour at 20 then 34 of 255, grown by 3.2 then 1.6),
+the body (a vertical gradient `lighten(base, 0.12)` → `darken(base, 0.10)`,
+corner radius `min(2, min(w, h) / 2)`) with a 1 px `darken(base, 0.24)`
+border, and the name — rectangular only, in `min(external font, h − 2)` px
+when that is over 4 px and the text is at most `w − 4` wide, in near-black
+when the base luminance is over 0.55 and white otherwise. Colours: the drawn
+names over the whole tree, sorted by code unit, take Tableau 10 in order,
+then the same ten shifted toward white (odd cycles) or black (even cycles)
+by `min(0.55, 0.2 × cycle)`; an unnamed domain is `#808080`; dealt at load,
+after an edit and on every threshold change, and a name met later takes the
+next unused index. Legend (`'legend'` mode): title `Protein domains
+(E ≤ 1e<exp>)`, rows `NAME (count)` in first-appearance order over the tips
+in display order, clipped to 240 px; home bottom-right, inset 10; a drag
+keeps its place as a fraction of the view, a double-click sends it home.
+Everything is plain rects plus one `<linearGradient>` per colour in the
+track group's own `<defs>`, so exports match the screen. The acceptance
+numbers — apaf.xml: 31 tips, `Lmax` 2080, 202 domains; 9 names / 166 boxes
+at 1e−3; the palette; 22_MOUSE's box offsets at `W = 300` — are the
+desktop's, in `test/domain_test.js`.
+
 ### The alignment track
 
 Data model: per-tip `sequences[0].mol_seq = {is_aligned, value}` (the gapped

package/archaeopteryx.d.ts

@@ -73,6 +73,9 @@ export interface ArchaeopteryxConfig {
     nhConfidenceValuesInBrackets?: boolean;
     nhExportWriteConfidences?: boolean;
     nodeLabels?: Record<string, NodeLabelSpec> | null;
+    /** Called once per settled redraw when the view changed: the state as
+     * getViewState() returns it, and its hash-ready string. */
+    onViewChange?: ((state: ViewState, encoded: string) => void) | null;
     pngExportScale?: number;
     rootOffset?: number;
     searchAinitialValue?: string | null;
@@ -82,27 +85,103 @@ export interface ArchaeopteryxConfig {
     showTimeAxis?: boolean;
     supportDotMinimum?: number;
     timeAxisGrid?: boolean;
+    /** Open straight into a view (getViewState / decodeViewState). */
+    view?: ViewState | null;
     visualizationsLegendXpos?: number;
     visualizationsLegendYpos?: number;
     zoomToFitUponWindowResize?: boolean;
 }
 
+/** One search box in a view: the field by its menu label, the mode, the
+ * value (and the range's second value). */
+export interface ViewSearch {
+    field?: string;
+    mode?: string;
+    value: string;
+    value2?: string;
+}
+
+/** A view of a tree as the control panel left it: what getViewState()
+ * returns, what the config's view key and applyViewState() take, and what
+ * encodeViewState() / decodeViewState() turn into a URL-hash string and
+ * back. Every key is optional; a key left out keeps its current value,
+ * except searchA / searchB, which an absent key clears. Nodes (subtree,
+ * collapsed) are named by their launch-time preorder index. */
+export interface ViewState {
+    /** Which tree of a multi-tree launch (0-based). */
+    tree?: number;
+    layout?: Layout;
+    display?: 'phylogram' | 'aligned' | 'cladogram';
+    /** The ladderize direction applied. */
+    order?: 'asc' | 'desc';
+    /** Midpoint re-rooted. */
+    root?: 'midpoint';
+    subtree?: number;
+    collapsed?: number[];
+    /** A visualization id (as the Color-by menu values them), or 'none'. */
+    colorBy?: string;
+    shapeBy?: string;
+    /** The panel's checked boxes: name, taxonomy, sequence, confidence,
+     * branchLength, external, internal, nodeEvents, branchEvents,
+     * supportDots, shortNames, autoHide, visualizations, visualStyles, and
+     * custom:<key> for a nodeLabels checkbox. */
+    show?: string[];
+    font?: number;
+    node?: number;
+    branch?: number;
+    /** Radial rotation in button presses (pi/32 each). */
+    rotation?: number;
+    horizontalLabels?: boolean;
+    msa?: boolean;
+    domains?: boolean;
+    domainLabels?: 'none' | 'domains' | 'legend';
+    domainGlow?: boolean;
+    domainEvalue?: number;
+    timeAxis?: boolean;
+    timeGrid?: boolean;
+    searchA?: ViewSearch;
+    searchB?: ViewSearch;
+    combine?: 'and' | 'or';
+    matchCase?: boolean;
+    inverse?: boolean;
+}
+
 /** What launch() returns: the per-viewer surface an embedder needs after
  * launching. */
 export interface ViewerHandle {
     /** The nodes the user has selected via the node menu (when
      * enableManualNodeSelection is on). */
     getSelectedNodes(): PhylogenyNode[];
+    /** How many trees the launch holds: one, or every tree the file held
+     * (launch() with the array parseTrees returns). */
+    getTreeCount(): number;
+    /** Which of them is shown (0-based). */
+    getTreeIndex(): number;
+    /** Shows another tree of the launch in the same container under the
+     * same config; it opens fresh. Returns the handle for the new viewer. */
+    showTree(index: number): ViewerHandle;
+    /** The view as the panel left it (see ViewState). */
+    getViewState(): ViewState;
+    /** Opens a view on the running viewer; a view of another tree of the
+     * launch relaunches into that tree. */
+    applyViewState(state: ViewState): void;
     /** Unmounts the viewer completely: the DOM inside the container, the
      * body-level pieces, the window resize listener and every page-level
      * key/wheel handler. A later launch() works normally. */
     destroy(): void;
 }
 
+/** How bare numeric internal labels of a Newick / Nexus tree are read:
+ * 'auto' decides per tree, 'confidence' takes every one as a support
+ * value, 'label' keeps them as names. */
+export type InternalNumericLabels = 'auto' | 'confidence' | 'label';
+
 export interface Archaeopteryx {
     /** Launch the viewer into a container (a CSS selector or the element
-     * itself; an unresolvable container throws). Exactly three arguments. */
-    launch(container: string | Element, tree: Phylogeny, config?: ArchaeopteryxConfig): ViewerHandle;
+     * itself; an unresolvable container throws). Exactly three arguments.
+     * A tree, or every tree of a file (parseTrees): the first is shown and
+     * the control panel gets a picker for the others. */
+    launch(container: string | Element, tree: Phylogeny | Phylogeny[], config?: ArchaeopteryxConfig): ViewerHandle;
 
     /** Parse-and-launch in one step. Fetch the file content yourself; the
      * fileName picks the parser (extension; content is sniffed too).
@@ -112,23 +191,34 @@ export interface Archaeopteryx {
 
     /** Parse tree data, auto-detecting the format from content and fileName:
      * Nexus (#NEXUS / .nex / .nexus), Auspice/Nextstrain v2 JSON ({ / .json),
-     * phyloXML (*xml), otherwise New Hampshire (Newick). */
+     * phyloXML (*xml), otherwise New Hampshire (Newick). The FIRST tree the
+     * data holds; parseTrees returns them all. */
     parseTree(fileName: string, data: string,
-        nhConfidenceValuesInBrackets?: boolean,
-        nhConfidenceValuesAsInternalNames?: boolean): Phylogeny;
+        internalNumericLabels?: InternalNumericLabels): Phylogeny;
+    /** Every tree the data holds, in file order: a Nexus TREES block, a
+     * Newick text with one tree per ';', a phyloXML with several
+     * phylogenies (an Auspice dataset is one tree). Hand the array to
+     * launch(). */
+    parseTrees(fileName: string, data: string,
+        internalNumericLabels?: InternalNumericLabels): Phylogeny[];
 
     parsePhyloXML(data: string): Phylogeny;
     parseNewHampshire(data: string,
-        confidenceValuesInBrackets?: boolean,
-        confidenceValuesAsInternalNames?: boolean): Phylogeny;
-    /** A Nexus file can hold several trees; the FIRST is returned. */
+        internalNumericLabels?: InternalNumericLabels): Phylogeny;
+    /** A Nexus file can hold several trees; the FIRST is returned
+     * (parseTrees returns them all). */
     parseNexus(data: string,
-        confidenceValuesInBrackets?: boolean,
-        confidenceValuesAsInternalNames?: boolean): Phylogeny;
+        internalNumericLabels?: InternalNumericLabels): Phylogeny;
     parseAuspiceJson(data: string | object): Phylogeny;
 
     /** Module-level twin of the handle's getSelectedNodes. */
     getSelectedNodes(): PhylogenyNode[];
+
+    /** A view as a "key=value&..." string for a URL hash, and back. decode
+     * accepts a leading '#', ignores what it does not know, and returns
+     * null for nothing. */
+    encodeViewState(state: ViewState): string;
+    decodeViewState(text: string | null | undefined): ViewState | null;
 }
 
 export const archaeopteryx: Archaeopteryx;