insomni-plot 0.1.0-alpha.0

package/src/grammar/pan-zoom.test.ts

@@ -0,0 +1,398 @@
+// @vitest-environment jsdom
+import { describe, expect, test } from "vite-plus/test";
+import { createFrame } from "insomni";
+import { __test__ } from "./mount.ts";
+import { coordCartesian, coordPolar, coordRadial } from "./coord.ts";
+import { createDataViewport } from "../viewport.ts";
+import { linearScale } from "../scales.ts";
+import type { ScaleBundle } from "./scales.ts";
+
+const { resolvePanZoom, computeVisibleYExtent, wrapViewportThroughCoord, screenToData } = __test__;
+
+// ============ Fixtures ============
+
+interface Row {
+  x: number;
+  y: number;
+}
+
+const fixture = {
+  series: (): Row[] => [
+    { x: 0, y: 10 },
+    { x: 10, y: 20 },
+    { x: 20, y: 5 },
+    { x: 30, y: 30 },
+    { x: 40, y: 8 },
+  ],
+  /** A "geom"-ish stub — only `channels.x` / `channels.y` are read. */
+  pointGeom: (xKey: keyof Row = "x", yKey: keyof Row = "y") => ({
+    channels: { x: xKey as unknown, y: yKey as unknown },
+  }),
+};
+
+// ============ resolvePanZoom ============
+
+describe("resolvePanZoom", () => {
+  test("input false returns null (panZoom off)", () => {
+    expect(resolvePanZoom(false)).toBeNull();
+    expect(resolvePanZoom(undefined)).toBeNull();
+  });
+
+  test("input true uses chart-tightened defaults, not viewport defaults", () => {
+    const r = resolvePanZoom(true)!;
+    expect(r.minZoom).toBe(1);
+    expect(r.maxZoom).toBe(100);
+    expect(r.pan).toBe("xy");
+    expect(r.zoom).toBe("xy");
+    expect(r.yFitPadding).toBeNull();
+    expect(r.panBounds).toEqual({ overshoot: 0.1 });
+  });
+
+  test("explicit overrides win over defaults", () => {
+    const r = resolvePanZoom({ minZoom: 0.5, maxZoom: 50, pan: "x", zoom: "x" })!;
+    expect(r.minZoom).toBe(0.5);
+    expect(r.maxZoom).toBe(50);
+    expect(r.pan).toBe("x");
+    expect(r.zoom).toBe("x");
+  });
+
+  test("panBounds: false disables clamping (undefined at viewport)", () => {
+    expect(resolvePanZoom({ panBounds: false })!.panBounds).toBeUndefined();
+  });
+
+  test("yFit forces x-only pan/zoom and default 5% padding", () => {
+    const r = resolvePanZoom({ yFit: true })!;
+    expect(r.pan).toBe("x");
+    expect(r.zoom).toBe("x");
+    expect(r.yFitPadding).toBe(0.05);
+  });
+
+  test("yFit overrides user-supplied pan/zoom — Y is read-only", () => {
+    const r = resolvePanZoom({ yFit: true, pan: "xy", zoom: "xy" })!;
+    expect(r.pan).toBe("x");
+    expect(r.zoom).toBe("x");
+  });
+
+  test("yFit accepts custom padding within [0, 0.5]", () => {
+    expect(resolvePanZoom({ yFit: { padding: 0 } })!.yFitPadding).toBe(0);
+    expect(resolvePanZoom({ yFit: { padding: 0.2 } })!.yFitPadding).toBe(0.2);
+  });
+
+  test("yFit padding out of range throws", () => {
+    expect(() => resolvePanZoom({ yFit: { padding: -0.1 } })).toThrow(/padding/);
+    expect(() => resolvePanZoom({ yFit: { padding: 0.6 } })).toThrow(/padding/);
+  });
+});
+
+// ============ computeVisibleYExtent ============
+
+describe("computeVisibleYExtent", () => {
+  test("returns padded extent of points whose x falls in the window", () => {
+    // Visible x ∈ [5, 25] selects rows at x=10 (y=20) and x=20 (y=5).
+    const ext = computeVisibleYExtent([fixture.pointGeom()], fixture.series(), [5, 25], 0.1)!;
+    // span = 15, pad = 1.5 → [5 - 1.5, 20 + 1.5]
+    expect(ext[0]).toBeCloseTo(3.5, 6);
+    expect(ext[1]).toBeCloseTo(21.5, 6);
+  });
+
+  test("inclusive on both edges of the X window", () => {
+    const ext = computeVisibleYExtent([fixture.pointGeom()], fixture.series(), [0, 40], 0)!;
+    // Whole series, no padding.
+    expect(ext).toEqual([5, 30]);
+  });
+
+  test("returns null when no point falls inside the window", () => {
+    const ext = computeVisibleYExtent([fixture.pointGeom()], fixture.series(), [100, 200], 0.05);
+    expect(ext).toBeNull();
+  });
+
+  test("returns null on empty data or no layers", () => {
+    expect(computeVisibleYExtent([fixture.pointGeom()], [], [0, 10], 0.05)).toBeNull();
+    expect(computeVisibleYExtent([], fixture.series(), [0, 10], 0.05)).toBeNull();
+  });
+
+  test("singleton y collapses to a baseline-padded range, not a zero span", () => {
+    const data: Row[] = [{ x: 10, y: 7 }];
+    const ext = computeVisibleYExtent([fixture.pointGeom()], data, [0, 20], 0.1)!;
+    // pad = |7| * 0.1 = 0.7
+    expect(ext[0]).toBeCloseTo(6.3, 6);
+    expect(ext[1]).toBeCloseTo(7.7, 6);
+  });
+
+  test("unions extent across multiple layers", () => {
+    const a: Row[] = [{ x: 5, y: 100 }];
+    // Use same data array but second layer reads a different field — simulate
+    // by providing a function accessor that yields 200.
+    const geom2 = { channels: { x: "x", y: (() => 200) as unknown } };
+    const ext = computeVisibleYExtent([fixture.pointGeom(), geom2], a, [0, 10], 0)!;
+    expect(ext).toEqual([100, 200]);
+  });
+
+  test("array-shaped channels (stacked / multi-series) are skipped in v1", () => {
+    const geom = { channels: { x: ["a", "b"], y: ["a", "b"] } };
+    const data = [{ a: 1, b: 1 }];
+    expect(computeVisibleYExtent([geom], data, [0, 10], 0)).toBeNull();
+  });
+
+  test("treats x window endpoints in any order (lo/hi swap-safe)", () => {
+    const ext = computeVisibleYExtent([fixture.pointGeom()], fixture.series(), [25, 5], 0)!;
+    // Same selection as [5, 25].
+    expect(ext).toEqual([5, 20]);
+  });
+});
+
+// ============ wrapViewportThroughCoord ============
+//
+// Verifies the mount-time wrapper that routes `panBy` / `zoomAt` through
+// `coord.handlePan` / `coord.handleZoom`. Cartesian must be byte-identical
+// to a direct `panBy` / `zoomAt` call; polar must rotate `startAngle` on
+// horizontal pan and only zoom the radius scale.
+
+describe("wrapViewportThroughCoord", () => {
+  function makeViewport() {
+    return createDataViewport<number, number>({
+      frame: createFrame({ x: 0, y: 0, width: 200, height: 200 }),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+      minZoom: 0.01,
+      maxZoom: 100,
+    });
+  }
+
+  type PolarReadout = { __polar__: { startAngle: () => number } };
+
+  test("cartesian: panBy delegates to underlying viewport with the same delta", () => {
+    const vp = makeViewport();
+    // Control viewport: a direct panBy on a parallel instance gives us the
+    // expected domains.
+    const control = makeViewport();
+    control.panBy(10, -5);
+    const xCtrl = control.visibleXDomain;
+    const yCtrl = control.visibleYDomain;
+
+    let invalidated = 0;
+    const wrapped = wrapViewportThroughCoord(
+      vp,
+      () => coordCartesian(),
+      () => {
+        invalidated++;
+      },
+    );
+    wrapped.panBy(10, -5);
+
+    expect(vp.visibleXDomain).toEqual(xCtrl);
+    expect(vp.visibleYDomain).toEqual(yCtrl);
+    expect(invalidated).toBe(1);
+  });
+
+  test("cartesian: zoomAt delegates with the same anchor + factor", () => {
+    const vp = makeViewport();
+    const control = makeViewport();
+    control.zoomAt(120, 80, 1.5);
+    const xCtrl = control.visibleXDomain;
+    const yCtrl = control.visibleYDomain;
+
+    const wrapped = wrapViewportThroughCoord(
+      vp,
+      () => coordCartesian(),
+      () => {},
+    );
+    wrapped.zoomAt(120, 80, 1.5);
+
+    expect(vp.visibleXDomain).toEqual(xCtrl);
+    expect(vp.visibleYDomain).toEqual(yCtrl);
+  });
+
+  test("polar: horizontal pan rotates startAngle and leaves the viewport untouched", () => {
+    const vp = makeViewport();
+    const xBefore = vp.visibleXDomain;
+    const yBefore = vp.visibleYDomain;
+    const polar = coordPolar();
+    polar.bindFrame(vp.frame);
+    const polarState = (polar as unknown as PolarReadout).__polar__;
+    const startBefore = polarState.startAngle();
+
+    let invalidated = 0;
+    const wrapped = wrapViewportThroughCoord(
+      vp,
+      () => polar,
+      () => {
+        invalidated++;
+      },
+    );
+    wrapped.panBy(50, 0);
+
+    // dx=50, width=200, arc=2π → rotation = π/2.
+    expect(polarState.startAngle() - startBefore).toBeCloseTo(Math.PI / 2, 4);
+    // No radial component — viewport domains stay put.
+    expect(vp.visibleXDomain).toEqual(xBefore);
+    expect(vp.visibleYDomain).toEqual(yBefore);
+    expect(invalidated).toBe(1);
+  });
+
+  test("polar: vertical pan translates the radius (x) domain, startAngle unchanged", () => {
+    const vp = makeViewport();
+    const polar = coordPolar(); // angleChannel='y'; radius axis = x.
+    polar.bindFrame(vp.frame);
+    const polarState = (polar as unknown as PolarReadout).__polar__;
+    const startBefore = polarState.startAngle();
+    const xBefore = vp.visibleXDomain;
+    const yBefore = vp.visibleYDomain;
+
+    const wrapped = wrapViewportThroughCoord(
+      vp,
+      () => polar,
+      () => {},
+    );
+    wrapped.panBy(0, 10);
+
+    expect(polarState.startAngle()).toBe(startBefore);
+    expect(vp.visibleXDomain).not.toEqual(xBefore);
+    expect(vp.visibleYDomain).toEqual(yBefore);
+  });
+
+  test("polar: zoom only affects the radius (x) domain — y stays put", () => {
+    const vp = makeViewport();
+    const polar = coordPolar();
+    polar.bindFrame(vp.frame);
+    const xBefore = vp.visibleXDomain;
+    const yBefore = vp.visibleYDomain;
+
+    const wrapped = wrapViewportThroughCoord(
+      vp,
+      () => polar,
+      () => {},
+    );
+    // bindDataViewport issues per-axis factors. Both should collapse to the
+    // radial channel under polar (angle stays fixed under zoom).
+    wrapped.zoomAt(100, 100, { x: 1.5, y: 1.5 });
+
+    expect(vp.visibleXDomain).not.toEqual(xBefore);
+    expect(vp.visibleYDomain).toEqual(yBefore);
+  });
+
+  test("getCoord is read at-event-time so chart.update() can swap coords", () => {
+    const vp = makeViewport();
+    let current = coordCartesian();
+    const wrapped = wrapViewportThroughCoord(
+      vp,
+      () => current,
+      () => {},
+    );
+
+    // First pan under cartesian — applies as a straight delta.
+    wrapped.panBy(5, 0);
+    const xAfterCart = vp.visibleXDomain;
+
+    // Swap to polar — same delta should now rotate, not pan.
+    const polar = coordPolar();
+    polar.bindFrame(vp.frame);
+    current = polar;
+    const polarState = (polar as unknown as PolarReadout).__polar__;
+    const startBefore = polarState.startAngle();
+    wrapped.panBy(5, 0);
+
+    expect(vp.visibleXDomain).toEqual(xAfterCart);
+    expect(polarState.startAngle()).not.toBe(startBefore);
+  });
+});
+
+// ============ screenToData (MountedPlot.pickAt primitive) ============
+
+describe("screenToData", () => {
+  // Build a minimal scale bundle good enough for the helper. Only `x.axisScale`
+  // / `y.axisScale` (their `invert`) and the `kind`/`type`/`dataType`/`fn`
+  // identity are read.
+  function makeScales(
+    xDomain: [number, number],
+    yDomain: [number, number],
+    plotW = 100,
+    plotH = 100,
+  ): ScaleBundle {
+    const xRange: [number, number] = [0, plotW];
+    const yRange: [number, number] = [plotH, 0]; // flipped (y grows down on screen)
+    const xAxis = linearScale(xDomain, xRange);
+    const yAxis = linearScale(yDomain, yRange);
+    return {
+      x: {
+        kind: "position" as const,
+        type: "linear" as const,
+        dataType: "number" as const,
+        fn: (v: unknown) => xAxis(v as number),
+        axisScale: xAxis,
+      },
+      y: {
+        kind: "position" as const,
+        type: "linear" as const,
+        dataType: "number" as const,
+        fn: (v: unknown) => yAxis(v as number),
+        axisScale: yAxis,
+      },
+    };
+  }
+
+  test("returns null when scales are absent (pre-first-draw)", () => {
+    const frame = createFrame({ x: 10, y: 20, width: 100, height: 100 });
+    expect(screenToData(50, 50, { frame, scales: null, coord: coordCartesian() })).toBeNull();
+  });
+
+  test("returns null for a point outside the plot frame", () => {
+    const frame = createFrame({ x: 10, y: 20, width: 100, height: 100 });
+    const scales = makeScales([0, 10], [0, 10]);
+    expect(screenToData(0, 0, { frame, scales, coord: coordCartesian() })).toBeNull();
+    expect(screenToData(200, 200, { frame, scales, coord: coordCartesian() })).toBeNull();
+  });
+
+  test("Cartesian — canvas px maps to data via axis.invert (frame-relative)", () => {
+    const frame = createFrame({ x: 10, y: 20, width: 100, height: 100 });
+    // xDomain [0..10] mapped to [0..100], y flipped: yDomain [0..10] → [100..0].
+    const scales = makeScales([0, 10], [0, 10]);
+    // Canvas (60, 70) → plot-frame (50, 50) → coord identity → invert:
+    //   dataX = 50 / 100 * 10 = 5, dataY = (100 - 50) / 100 * 10 = 5.
+    const got = screenToData(60, 70, { frame, scales, coord: coordCartesian() });
+    expect(got).not.toBeNull();
+    expect(got!.dataX).toBeCloseTo(5, 6);
+    expect(got!.dataY).toBeCloseTo(5, 6);
+    expect(got!.plotFrameX).toBeCloseTo(50, 6);
+    expect(got!.plotFrameY).toBeCloseTo(50, 6);
+  });
+
+  test("polar — canvas px routes through coord.unproject before invert", () => {
+    // A 200×200 frame at origin; coordRadial uses min(w, h)/2 = 100 as
+    // outerRadius. coordRadial defaults: angleChannel='y', startAngle=-π/2.
+    // The 'y' channel is the angular axis. Pick a point on the +x axis from
+    // the centre at r = outerR/2 = 50 → unproject lands on plot-frame
+    // (plotW * t_radial, plotH - plotH * t_angle), where t_radial = 0.5 and
+    // t_angle corresponds to θ = 0 (one quarter-turn CCW from start θ=-π/2):
+    //   t_angle = 0.25 → plot-frame y = plotH * (1 - 0.25) = 150.
+    //   plot-frame x = plotW * t_radial = 100.
+    const frame = createFrame({ x: 0, y: 0, width: 200, height: 200 });
+    // Same domains the chart would supply: x → [0..plotW], y → [0..plotH].
+    const scales = makeScales([0, 200], [0, 200], 200, 200);
+    const coord = coordRadial();
+    coord.bindFrame(frame);
+    // Centre (cx, cy) = (100, 100). Move 50 px along +x.
+    const got = screenToData(150, 100, { frame, scales, coord });
+    expect(got).not.toBeNull();
+    // After unproject, plot-frame y maps to top-half of frame.
+    expect(got!.plotFrameX).toBeCloseTo(100, 4);
+    expect(got!.plotFrameY).toBeCloseTo(150, 4);
+    // And the inverted scales recover those domain values 1:1 here
+    // (domain == range orientation modulo y flip).
+    expect(got!.dataX).toBeCloseTo(100, 4);
+    expect(got!.dataY).toBeCloseTo(50, 4);
+  });
+
+  test("polar — returns null when canvas point falls outside the outerRadius", () => {
+    const frame = createFrame({ x: 0, y: 0, width: 200, height: 200 });
+    const scales = makeScales([0, 200], [0, 200], 200, 200);
+    const coord = coordRadial();
+    coord.bindFrame(frame);
+    // (100, 100) is the centre; (199, 100) is at r=99, just inside.
+    // (10, 100) is at r=90, also inside. (1, 1) is at the corner of the frame
+    // — inside the rect but r ≈ √(99²+99²) ≈ 140 > 100 outerR. Within frame
+    // bounds but outside the polar disc → unproject returns null.
+    const got = screenToData(1, 1, { frame, scales, coord });
+    expect(got).toBeNull();
+  });
+});

package/src/grammar/phylo.d.ts

@@ -0,0 +1,65 @@
+import type { Color } from "insomni";
+import type { TextAnnotationSpec } from "./annotations.ts";
+import type { BandPositionScaleOptions } from "./scales.ts";
+/**
+ * Subset of `@phylon/renderer`'s `TipAxis` consumed by the bridge. Any object
+ * with this shape (typically the `tipAxis` field on a `RectLayout`) works.
+ */
+export interface TipAxisLike {
+    /** Number of tips. */
+    count: number;
+    /** Tip node ids in display order (top→bottom for rectilinear). */
+    order: ArrayLike<number>;
+    /** Tip node id → label, or `null` if the tip is unnamed. */
+    name(tipId: number): string | null;
+}
+export interface TipScaleOptions {
+    /**
+     * Band padding in [0, 1). Default `0` — heatmaps and tile-style geoms want
+     * tight rows. Bump to e.g. `0.1` for visible gaps between bars.
+     */
+    padding?: number;
+    /**
+     * Replacement label for unnamed tips. Receives the tip's node id and its
+     * row index. Default: `(id) => "tip_" + id`.
+     */
+    unnamed?: (tipId: number, row: number) => string;
+}
+/**
+ * Build a y-channel `PositionScaleOptions` from a phylo `TipAxis`. The
+ * resulting scale is a band scale whose domain is the tip names in tree
+ * display order (top→bottom). Geoms whose `y` aesthetic resolves to a tip
+ * name will land on the matching tree row.
+ *
+ * Tip labels in the data must match `axis.name(tipId)`. Use `joinByTip`
+ * (phylo) to align metadata rows to tip names ahead of time.
+ */
+export declare function tipScale(axis: TipAxisLike, opts?: TipScaleOptions): BandPositionScaleOptions;
+/**
+ * Structural shape of a phylo `CladeStrip` — neutral data describing a clade
+ * range plus a label. Mirrors `@phylon/renderer`'s exported `CladeStrip` so the
+ * plot package doesn't have to depend on phylo to consume them.
+ */
+export interface CladeStripLike {
+    label: string;
+    tipCenter: string;
+    color?: Color;
+    offsetX?: number;
+}
+export interface CladeStripAnnotationOptions {
+    /**
+     * Pixel offset added to every strip's annotation. Default `8` — pushes the
+     * label clear of the chart's right edge / tip labels. Per-strip
+     * `offsetX` is added on top of this.
+     */
+    offsetX?: number;
+    fontSize?: number;
+    fontStyle?: string;
+}
+/**
+ * Convert phylo `CladeStrip[]` into plot `AnnotationSpec[]`. Labels anchor at
+ * the chart's right frame edge, vertically aligned to the clade's y-center
+ * (resolved by the y-channel's `tipScale`). v1 emits text-only annotations;
+ * brackets are a follow-up that needs a non-text annotation kind.
+ */
+export declare function cladeStripsToAnnotations(strips: readonly CladeStripLike[], opts?: CladeStripAnnotationOptions): TextAnnotationSpec[];

package/src/grammar/phylo.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "vite-plus/test";
+import { cladeStripsToAnnotations, tipScale, type TipAxisLike } from "./phylo.ts";
+
+function makeAxis(names: readonly (string | null)[]): TipAxisLike {
+  return {
+    count: names.length,
+    order: names.map((_, i) => i),
+    name: (id: number) => names[id] ?? null,
+  };
+}
+
+describe("tipScale", () => {
+  test("emits a band scale whose domain is tip names in tree order", () => {
+    const axis = makeAxis(["C", "B", "A"]);
+    const opts = tipScale(axis);
+    expect(opts.type).toBe("band");
+    expect(opts.domain).toEqual(["C", "B", "A"]);
+    expect(opts.padding).toBe(0);
+  });
+
+  test("padding override is forwarded", () => {
+    const axis = makeAxis(["x", "y"]);
+    expect(tipScale(axis, { padding: 0.25 }).padding).toBe(0.25);
+  });
+
+  test("unnamed tips fall back to a synthetic id", () => {
+    const axis = makeAxis(["A", null, "C"]);
+    const opts = tipScale(axis);
+    expect(opts.domain).toEqual(["A", "tip_1", "C"]);
+  });
+
+  test("custom unnamed fallback receives id and row", () => {
+    const axis = makeAxis([null, null]);
+    const opts = tipScale(axis, { unnamed: (id, row) => `r${row}_id${id}` });
+    expect(opts.domain).toEqual(["r0_id0", "r1_id1"]);
+  });
+});
+
+describe("cladeStripsToAnnotations", () => {
+  test("anchors each strip at the right frame edge with tipCenter as y", () => {
+    const annotations = cladeStripsToAnnotations([
+      { label: "AB", tipCenter: "B" },
+      { label: "CD", tipCenter: "D", offsetX: 4 },
+    ]);
+    expect(annotations).toHaveLength(2);
+    expect(annotations[0]!.x).toBe("right");
+    expect(annotations[0]!.y).toBe("B");
+    expect(annotations[0]!.align).toBe("left");
+    expect(annotations[0]!.offsetX).toBe(8);
+    // Per-strip offsetX adds on top of the base.
+    expect(annotations[1]!.offsetX).toBe(12);
+    expect(annotations[1]!.text).toBe("CD");
+  });
+
+  test("base offsetX option overrides the default", () => {
+    const annotations = cladeStripsToAnnotations([{ label: "X", tipCenter: "T" }], { offsetX: 20 });
+    expect(annotations[0]!.offsetX).toBe(20);
+  });
+});

package/src/grammar/phylo.ts

@@ -0,0 +1,112 @@
+// ---------------------------------------------------------------------------
+// Bridge: phylo ↔ plot
+// ---------------------------------------------------------------------------
+// `tipScale(axis)` returns a `PositionScaleOptions` whose discrete domain is
+// the tree's tip names in display order. Hand it to a chart's y-channel to
+// align any geom (heatmap, bar, point, …) to the tip rows of a phylogeny.
+//
+// The bridge is plot-side so phylo can stay dependency-free. To avoid the
+// reverse dependency, plot does not import from phylo — instead it consumes
+// a structural `TipAxisLike` (the subset of `phylo.TipAxis` we actually use).
+
+import type { Color } from "insomni";
+import type { TextAnnotationSpec } from "./annotations.ts";
+import type { BandPositionScaleOptions } from "./scales.ts";
+
+/**
+ * Subset of `@phylon/renderer`'s `TipAxis` consumed by the bridge. Any object
+ * with this shape (typically the `tipAxis` field on a `RectLayout`) works.
+ */
+export interface TipAxisLike {
+  /** Number of tips. */
+  count: number;
+  /** Tip node ids in display order (top→bottom for rectilinear). */
+  order: ArrayLike<number>;
+  /** Tip node id → label, or `null` if the tip is unnamed. */
+  name(tipId: number): string | null;
+}
+
+export interface TipScaleOptions {
+  /**
+   * Band padding in [0, 1). Default `0` — heatmaps and tile-style geoms want
+   * tight rows. Bump to e.g. `0.1` for visible gaps between bars.
+   */
+  padding?: number;
+  /**
+   * Replacement label for unnamed tips. Receives the tip's node id and its
+   * row index. Default: `(id) => "tip_" + id`.
+   */
+  unnamed?: (tipId: number, row: number) => string;
+}
+
+/**
+ * Build a y-channel `PositionScaleOptions` from a phylo `TipAxis`. The
+ * resulting scale is a band scale whose domain is the tip names in tree
+ * display order (top→bottom). Geoms whose `y` aesthetic resolves to a tip
+ * name will land on the matching tree row.
+ *
+ * Tip labels in the data must match `axis.name(tipId)`. Use `joinByTip`
+ * (phylo) to align metadata rows to tip names ahead of time.
+ */
+export function tipScale(axis: TipAxisLike, opts: TipScaleOptions = {}): BandPositionScaleOptions {
+  const fallback = opts.unnamed ?? ((id: number) => `tip_${id}`);
+  const domain: string[] = Array.from({ length: axis.count });
+  for (let row = 0; row < axis.count; row++) {
+    const id = axis.order[row]!;
+    domain[row] = axis.name(id) ?? fallback(id, row);
+  }
+  return {
+    type: "band",
+    domain,
+    padding: opts.padding ?? 0,
+  };
+}
+
+/**
+ * Structural shape of a phylo `CladeStrip` — neutral data describing a clade
+ * range plus a label. Mirrors `@phylon/renderer`'s exported `CladeStrip` so the
+ * plot package doesn't have to depend on phylo to consume them.
+ */
+export interface CladeStripLike {
+  label: string;
+  tipCenter: string;
+  color?: Color;
+  offsetX?: number;
+}
+
+export interface CladeStripAnnotationOptions {
+  /**
+   * Pixel offset added to every strip's annotation. Default `8` — pushes the
+   * label clear of the chart's right edge / tip labels. Per-strip
+   * `offsetX` is added on top of this.
+   */
+  offsetX?: number;
+  fontSize?: number;
+  fontStyle?: string;
+}
+
+/**
+ * Convert phylo `CladeStrip[]` into plot `AnnotationSpec[]`. Labels anchor at
+ * the chart's right frame edge, vertically aligned to the clade's y-center
+ * (resolved by the y-channel's `tipScale`). v1 emits text-only annotations;
+ * brackets are a follow-up that needs a non-text annotation kind.
+ */
+export function cladeStripsToAnnotations(
+  strips: readonly CladeStripLike[],
+  opts: CladeStripAnnotationOptions = {},
+): TextAnnotationSpec[] {
+  const baseOffset = opts.offsetX ?? 8;
+  return strips.map(
+    (s): TextAnnotationSpec => ({
+      kind: "text",
+      text: s.label,
+      x: "right",
+      y: s.tipCenter,
+      align: "left",
+      offsetX: baseOffset + (s.offsetX ?? 0),
+      color: s.color,
+      fontSize: opts.fontSize,
+      fontStyle: opts.fontStyle,
+    }),
+  );
+}

package/src/grammar/pipeline.auto-ticks.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vite-plus/test";
+import { makeAxisOptions } from "./pipeline.ts";
+import { themeDefault } from "./theme.ts";
+
+describe("makeAxisOptions — default ticks and labelCollision", () => {
+  it("defaults ticks to 'auto' when no spec is provided", () => {
+    const opts = makeAxisOptions(undefined, themeDefault, undefined);
+    expect(opts.ticks).toBe("auto");
+  });
+
+  it("defaults ticks to 'auto' when spec has no ticks field", () => {
+    const opts = makeAxisOptions({}, themeDefault, undefined);
+    expect(opts.ticks).toBe("auto");
+  });
+
+  it("respects an explicit numeric ticks value", () => {
+    const opts = makeAxisOptions({ ticks: 5 }, themeDefault, undefined);
+    expect(opts.ticks).toBe(5);
+  });
+
+  it("respects an explicit 'auto' ticks value (no-op, same result)", () => {
+    const opts = makeAxisOptions({ ticks: "auto" }, themeDefault, undefined);
+    expect(opts.ticks).toBe("auto");
+  });
+
+  it("defaults labelCollision to 'auto' when no spec is provided", () => {
+    const opts = makeAxisOptions(undefined, themeDefault, undefined);
+    expect(opts.labelCollision).toBe("auto");
+  });
+
+  it("defaults labelCollision to 'auto' when spec has no labelCollision field", () => {
+    const opts = makeAxisOptions({}, themeDefault, undefined);
+    expect(opts.labelCollision).toBe("auto");
+  });
+
+  it("respects an explicit labelCollision value", () => {
+    const opts = makeAxisOptions({ labelCollision: "auto" }, themeDefault, undefined);
+    expect(opts.labelCollision).toBe("auto");
+  });
+});