Phylo overview

insomni-phylo is a phylogenetic-tree toolkit. It carries a tree model designed for very large trees (flat structure-of-arrays buffers), parsers and writers for the common interchange formats, a set of layout algorithms, and a GPU renderer built on insomni and Plot.

Everything is exported from the package root:

import { parseNewick, layoutRectilinear, ladderize, mountPhyloScene } from "insomni-phylo";

The three layers

1. Model — TreeBuffers is a flat structure-of-arrays tree (parent / firstChild / nextSibling / length arrays). Around it sit traversal helpers, ladderize, an AnnotationTable for per-node metadata, an attribute catalog that summarizes columns for UI, and the joinByTip / groupClade operators.
2. Parsers & writers — Newick, NHX, NEXUS, FigTree. parseNewick / parseNexus produce TreeBuffers (+ an AnnotationTable); writeNewick / writeNexus serialize back with Java-compatible number formatting for byte-stable FigTree/BEAST round-trips.
3. Rendering — layout algorithms turn a tree into per-node coordinates, and the PhyloScene renderer (mounted with mountPhyloScene) draws it on a WebGPU canvas.

Note

A grammar-of-graphics rendering path (phyloChart / geoms composed on insomni-plot) was prototyped and removed before shipping. The chart-config types it used (PhyloChartConfig and friends) survive as the pure configuration shape that applyFigtreeSettings emits, but there is no geom builder today. The shipping renderer is PhyloScene / mountPhyloScene.

A minimal example: parse and mount

import { AnnotationTable, parseNewick, mountPhyloScene } from "insomni-phylo";

// 1. Parse a Newick string into flat tree buffers (+ optional annotations).
const annotations = new AnnotationTable();
const tree = parseNewick("((A:0.1,B:0.2):0.3,C:0.4);", { annotations });

// 2. Mount the renderer onto a canvas. The caller owns the GPU device.
const canvas = document.querySelector("canvas")!;
const handle = mountPhyloScene(canvas, { device, tree, annotations });

// 3. Drive it imperatively.
handle.setStyle({ branchStyle: "curve", showTips: true });
const hit = handle.pickAt(120, 80);

// 4. Tear down (cancels the rAF loop + ResizeObserver).
handle.destroy();

mountPhyloScene runs its own requestAnimationFrame loop and a ResizeObserver, so the host only feeds in data and style. See Rendering for the full handle surface.

Map of this section

• Tree model — TreeBuffers, traversal, ladderize, annotations, attribute catalog, joinByTip, groupClade.
• Parsers & writers — parseNewick / parseNexus / writeNewick / writeNexus, NHX annotations, and lossless editing via phylon-parser.
• Layout algorithms — layoutRectilinear, layoutDendrogram, layoutUnrootedEqualAngle + equalDaylight, applyTreeTransform.
• Rendering — PhyloScene / mountPhyloScene, the PhyloStyle surface, and the populate* primitives.
• FigTree compatibility — applying & writing FIGTREE settings and the int-vs-double round-trip contract.