insomni-plot 0.1.0-alpha.0

package/src/grammar/aes.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vite-plus/test";
+import { inferDataType, materialize, resolveAes } from "./aes.ts";
+
+interface Row {
+  revenue: number;
+  sector: string;
+  founded: Date;
+}
+
+const rows: Row[] = [
+  { revenue: 100, sector: "SaaS", founded: new Date("2010-01-01") },
+  { revenue: 50, sector: "FinTech", founded: new Date("2015-06-01") },
+  { revenue: 200, sector: "DevTools", founded: new Date("2020-03-01") },
+];
+
+describe("resolveAes", () => {
+  it("resolves a column key to an accessor with metadata", () => {
+    const r = resolveAes<Row, number>("revenue");
+    expect(r.kind).toBe("column");
+    expect(r.column).toBe("revenue");
+    expect(r.fn(rows[0]!, 0)).toBe(100);
+  });
+
+  it("resolves an accessor function", () => {
+    const r = resolveAes<Row, number>((d) => d.revenue * 2);
+    expect(r.kind).toBe("accessor");
+    expect(r.column).toBeUndefined();
+    expect(r.fn(rows[1]!, 1)).toBe(100);
+  });
+
+  it("resolves a constant value", () => {
+    const r = resolveAes<Row, number>(7);
+    expect(r.kind).toBe("constant");
+    expect(r.fn(rows[0]!, 0)).toBe(7);
+  });
+
+  it("uses fallback when aes is undefined", () => {
+    const r = resolveAes<Row, number>(undefined, 3);
+    expect(r.kind).toBe("constant");
+    expect(r.fn(rows[0]!, 0)).toBe(3);
+  });
+
+  it("throws if no aes and no fallback", () => {
+    expect(() => resolveAes<Row, number>(undefined)).toThrow();
+  });
+});
+
+describe("materialize", () => {
+  it("flattens an aesthetic across the dataset", () => {
+    const r = resolveAes<Row, number>("revenue");
+    expect(materialize(r, rows)).toEqual([100, 50, 200]);
+  });
+});
+
+describe("inferDataType", () => {
+  it("detects number", () => {
+    expect(inferDataType([1, 2, 3])).toBe("number");
+  });
+  it("detects string", () => {
+    expect(inferDataType(["a", "b"])).toBe("string");
+  });
+  it("detects date", () => {
+    expect(inferDataType([new Date()])).toBe("date");
+  });
+  it("detects boolean", () => {
+    expect(inferDataType([true, false])).toBe("boolean");
+  });
+  it("skips nullish to find a real type", () => {
+    expect(inferDataType([null, undefined, "x"])).toBe("string");
+  });
+  it("returns unknown for empty / all-nullish", () => {
+    expect(inferDataType([])).toBe("unknown");
+    expect(inferDataType([null, undefined])).toBe("unknown");
+  });
+});

package/src/grammar/aes.ts

@@ -0,0 +1,120 @@
+// ---------------------------------------------------------------------------
+// Aes<T, V> — aesthetic mappings
+// ---------------------------------------------------------------------------
+// A mapping from data row T to channel value V can be:
+//   - a column key   (keyof T whose value is assignable to V)
+//   - an accessor    (d, i) => V
+//   - a constant V
+//
+// Column-key autocomplete narrows by type: y: "sector" is rejected when
+// the y channel demands `number | Date` and `T["sector"]` is `string`.
+
+export type ColumnKeys<T, V> = {
+  [K in keyof T]-?: T[K] extends V ? K : never;
+}[keyof T];
+
+export type Accessor<T, V> = (datum: T, index: number) => V;
+
+export type Aes<T, V> = ColumnKeys<T, V> | Accessor<T, V> | V;
+
+export type Row = Record<string, unknown>;
+
+export interface ResolvedAes<T, V> {
+  readonly kind: "column" | "accessor" | "constant";
+  readonly column?: keyof T & string;
+  readonly fn: Accessor<T, V>;
+}
+
+function isAccessor<T, V>(v: unknown): v is Accessor<T, V> {
+  return typeof v === "function";
+}
+
+/**
+ * Normalize an `Aes<T, V>` to a `(d, i) => V` accessor plus metadata. The
+ * `kind` and `column` fields let consumers (auto-scale inference, legends,
+ * tooltip labels) introspect the original mapping.
+ */
+export function resolveAes<T, V>(aes: Aes<T, V> | undefined, fallback?: V): ResolvedAes<T, V> {
+  if (aes === undefined) {
+    if (fallback === undefined) {
+      throw new Error("resolveAes: missing aesthetic and no fallback provided");
+    }
+    const fb = fallback;
+    return { kind: "constant", fn: () => fb };
+  }
+  if (isAccessor<T, V>(aes)) {
+    return { kind: "accessor", fn: aes };
+  }
+  if (typeof aes === "string") {
+    const key = aes as keyof T & string;
+    return {
+      kind: "column",
+      column: key,
+      fn: (d: T) => (d as Record<string, unknown>)[key] as V,
+    };
+  }
+  // Constant (number, boolean, object, etc.)
+  const constant = aes as V;
+  return { kind: "constant", fn: () => constant };
+}
+
+/**
+ * Materialize an aesthetic to a flat array. Used when the chart needs the
+ * full column for domain inference.
+ */
+export function materialize<T, V>(aes: ResolvedAes<T, V>, data: readonly T[]): V[] {
+  const out = Array.from<V>({ length: data.length });
+  for (let i = 0; i < data.length; i++) out[i] = aes.fn(data[i]!, i);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Null / undefined policy for categorical channels
+// ---------------------------------------------------------------------------
+// Rows whose categorical channel (`color`, `shape`, …) materializes to `null`
+// or `undefined` are *dropped* — they do not become a `"null"` category and
+// they do not throw. Mirrors how numeric channels treat `NaN`. The scale
+// helpers (`uniqueStrings` in `scales.ts`) already filter at domain build;
+// geoms that group rows by a categorical channel (see `smooth`, `histogram`)
+// also drop the row before grouping so the rendered output stays aligned
+// with the scale domain.
+//
+// `dropNullCategoricalIndices` is the shared helper for geoms.
+
+/**
+ * Return the subset of `indices` whose row produces a non-null categorical
+ * value under `aes`. Used by geoms that group by a categorical channel; keeps
+ * the drop-row policy in one place.
+ */
+export function dropNullCategoricalIndices<T>(
+  indices: readonly number[],
+  aes: ResolvedAes<T, unknown>,
+  data: readonly T[],
+): number[] {
+  const out: number[] = [];
+  for (const i of indices) {
+    const v = aes.fn(data[i]!, i);
+    if (v === null || v === undefined) continue;
+    out.push(i);
+  }
+  return out;
+}
+
+/**
+ * Best-effort guess of a channel's data type. Used to pick a default scale
+ * type when no override is supplied. Null / undefined values are skipped
+ * (see "Null / undefined policy" above).
+ */
+export type ChannelDataType = "number" | "date" | "string" | "boolean" | "unknown";
+
+export function inferDataType(values: readonly unknown[]): ChannelDataType {
+  for (const v of values) {
+    if (v === null || v === undefined) continue;
+    if (typeof v === "number") return "number";
+    if (typeof v === "string") return "string";
+    if (typeof v === "boolean") return "boolean";
+    if (v instanceof Date) return "date";
+    return "unknown";
+  }
+  return "unknown";
+}

package/src/grammar/annotations.d.ts

@@ -0,0 +1,86 @@
+import type { Color, Frame, Layer } from "insomni";
+import { type LabelBoxStyle, type ValueLabelAlign } from "../annotations.ts";
+import type { ScaleBundle } from "./geoms/types.ts";
+import type { Theme } from "./theme.ts";
+export type FrameAnchorX = "left" | "center" | "right";
+export type FrameAnchorY = "top" | "middle" | "bottom";
+/** Coordinate value accepted by annotation factories — data value or frame anchor. */
+export type AnnotationX = FrameAnchorX | number | Date | string;
+export type AnnotationY = FrameAnchorY | number | Date | string;
+export interface TextAnnotationSpec {
+    kind?: "text";
+    text: string;
+    /**
+     * Horizontal position. A `FrameAnchorX` resolves to the plot frame edges;
+     * a number/Date is run through the active x scale.
+     */
+    x: AnnotationX;
+    /** Vertical position. See `x` — but resolves against the y scale. */
+    y: AnnotationY;
+    /** Pixel offset added after position resolution. */
+    offsetX?: number;
+    offsetY?: number;
+    align?: ValueLabelAlign;
+    color?: Color;
+    fontSize?: number;
+    fontStyle?: string;
+    box?: LabelBoxStyle;
+}
+export interface ArrowAnnotationSpec {
+    kind: "arrow";
+    /** Tail of the arrow — `[x, y]` in data or frame-anchor coordinates. */
+    from: readonly [AnnotationX, AnnotationY];
+    /** Head of the arrow. Direction is `from → to`. */
+    to: readonly [AnnotationX, AnnotationY];
+    /** Optional label rendered near the arrowhead. */
+    label?: string;
+    /**
+     * Pixel offset for the label relative to the arrowhead. Default
+     * `[6, -6]` — to-the-right-and-above the head.
+     */
+    labelOffset?: readonly [number, number];
+    labelAlign?: ValueLabelAlign;
+    labelBox?: LabelBoxStyle;
+    /** Stroke color for the shaft and head fill. Defaults to `theme.text.color`. */
+    color?: Color;
+    /** Shaft thickness in CSS pixels. Default `1.5`. */
+    strokeWidth?: number;
+    /**
+     * Arrowhead size in CSS pixels — total length from base to tip. Default
+     * `9`; the head is `headSize × 0.5` wide at the base.
+     */
+    headSize?: number;
+    fontSize?: number;
+    fontStyle?: string;
+}
+export interface CalloutAnnotationSpec {
+    kind: "callout";
+    /** Data point the callout is anchored to. */
+    at: readonly [AnnotationX, AnnotationY];
+    /** Label text rendered at the offset position. */
+    label: string;
+    /**
+     * Pixel offset from the anchor to the label position. The leader line
+     * runs between them. Default `[40, -20]`.
+     */
+    offset?: readonly [number, number];
+    /** Leader stroke color. Defaults to `theme.text.color` (faded by `leaderAlpha`). */
+    color?: Color;
+    /** Multiplier on the leader's stroke alpha. Default `0.6`. */
+    leaderAlpha?: number;
+    /** Leader thickness in CSS pixels. Default `1`. */
+    strokeWidth?: number;
+    /** Label text color. Defaults to `theme.text.color`. */
+    labelColor?: Color;
+    align?: ValueLabelAlign;
+    box?: LabelBoxStyle;
+    fontSize?: number;
+    fontStyle?: string;
+}
+export type AnnotationSpec = TextAnnotationSpec | ArrowAnnotationSpec | CalloutAnnotationSpec;
+export declare const annotate: {
+    readonly arrow: (spec: Omit<ArrowAnnotationSpec, "kind">) => ArrowAnnotationSpec;
+    readonly callout: (spec: Omit<CalloutAnnotationSpec, "kind">) => CalloutAnnotationSpec;
+    readonly text: (spec: Omit<TextAnnotationSpec, "kind">) => TextAnnotationSpec;
+};
+export declare function renderAnnotations(specs: readonly AnnotationSpec[], scales: ScaleBundle, plot: Frame, theme: Theme, hud: Layer): void;

package/src/grammar/annotations.test.ts

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+import { describe, expect, test } from "vite-plus/test";
+
+import { annotate, type AnnotationSpec } from "./annotations.ts";
+import { ruleMark } from "../annotations.ts";
+import { createLayer } from "insomni";
+import { INSTANCE_BYTES } from "insomni/advanced";
+
+describe("annotate namespace", () => {
+  test("annotate.arrow tags the spec with kind: 'arrow'", () => {
+    const spec = annotate.arrow({ from: [0, 0], to: [10, 10], label: "Peak" });
+    expect(spec.kind).toBe("arrow");
+    expect(spec.from).toEqual([0, 0]);
+    expect(spec.to).toEqual([10, 10]);
+    expect(spec.label).toBe("Peak");
+  });
+
+  test("annotate.callout tags the spec with kind: 'callout'", () => {
+    const spec = annotate.callout({
+      at: [5, 5],
+      label: "Started medication",
+      offset: [40, -20],
+    });
+    expect(spec.kind).toBe("callout");
+    expect(spec.at).toEqual([5, 5]);
+    expect(spec.offset).toEqual([40, -20]);
+    expect(spec.label).toBe("Started medication");
+  });
+
+  test("annotate.text tags the spec with kind: 'text'", () => {
+    const spec = annotate.text({ text: "p < 0.05", x: "left", y: "top" });
+    expect(spec.kind).toBe("text");
+    expect(spec.text).toBe("p < 0.05");
+  });
+
+  test("union spec discriminates on kind", () => {
+    const specs: AnnotationSpec[] = [
+      annotate.arrow({ from: [0, 0], to: [1, 1] }),
+      annotate.callout({ at: [0, 0], label: "x" }),
+      annotate.text({ text: "y", x: 1, y: 2 }),
+      // Backward compat: kind-less text annotation still parses as a TextAnnotationSpec.
+      { text: "z", x: "left", y: "top" },
+    ];
+    expect(specs.length).toBe(4);
+    expect(specs[0]!.kind).toBe("arrow");
+    expect(specs[1]!.kind).toBe("callout");
+    expect(specs[2]!.kind).toBe("text");
+    // Backward-compat entry has no kind set.
+    expect((specs[3] as { kind?: string }).kind).toBeUndefined();
+  });
+});
+
+describe("annotation marks — atlas-less layer (SVG export path)", () => {
+  test("ruleMark with label does not throw on an atlas-less layer and still emits line geometry", () => {
+    const layer = createLayer({ space: "ui" });
+
+    expect(() =>
+      ruleMark({
+        y: 50,
+        extent: [0, 200],
+        label: "threshold",
+      }).addTo(layer, { x: 0, y: 0 }),
+    ).not.toThrow();
+
+    // The rule line should still be emitted even without an atlas.
+    expect(layer.pack.byteLength / INSTANCE_BYTES).toBeGreaterThan(0);
+  });
+});

package/src/grammar/annotations.ts

@@ -0,0 +1,336 @@
+// ---------------------------------------------------------------------------
+// Free-form chart annotations
+// ---------------------------------------------------------------------------
+// `chart.annotate({ ... })` adds a one-off label/box to the HUD layer. Position
+// can be a domain value (run through the scale) or a frame anchor — useful for
+// model equations, p-values, callouts.
+//
+// Discriminated by `kind`:
+//
+// - `kind: "text"` (or omitted): the original text/box annotation — a
+//   `valueLabelMark` at a resolved position.
+// - `kind: "arrow"`: a line segment + filled arrowhead from `from` to `to`,
+//   with an optional label near the head. Both endpoints resolve through
+//   the active scales (or frame anchors). Use for "the peak happened
+//   here" callouts where direction matters.
+// - `kind: "callout"`: a single anchor `at` plus a pixel `offset` to the
+//   label position. A leader line connects them, then the label
+//   (optionally boxed) renders at the offset. Use for narrative
+//   annotations whose label needs to dodge nearby marks without losing
+//   the connection to the data point.
+//
+// The `annotate` namespace exports `arrow` / `callout` factory functions
+// that produce these specs. Pair with `chart.annotate(annotate.arrow(...))`
+// or pass the literal object directly.
+
+import type { Color, Frame, Layer, Vec2 } from "insomni";
+import { valueLabelMark, type LabelBoxStyle, type ValueLabelAlign } from "../annotations.ts";
+import type { ScaleBundle } from "./geoms/types.ts";
+import type { Theme } from "./theme.ts";
+
+export type FrameAnchorX = "left" | "center" | "right";
+export type FrameAnchorY = "top" | "middle" | "bottom";
+
+/** Coordinate value accepted by annotation factories — data value or frame anchor. */
+// oxlint-disable-next-line no-redundant-type-constituents -- FrameAnchorX/Y string literals are intentionally kept for IDE autocomplete; `string` subsumes them by design.
+export type AnnotationX = FrameAnchorX | number | Date | string;
+// oxlint-disable-next-line no-redundant-type-constituents -- same as AnnotationX
+export type AnnotationY = FrameAnchorY | number | Date | string;
+
+export interface TextAnnotationSpec {
+  kind?: "text";
+  text: string;
+  /**
+   * Horizontal position. A `FrameAnchorX` resolves to the plot frame edges;
+   * a number/Date is run through the active x scale.
+   */
+  x: AnnotationX;
+  /** Vertical position. See `x` — but resolves against the y scale. */
+  y: AnnotationY;
+  /** Pixel offset added after position resolution. */
+  offsetX?: number;
+  offsetY?: number;
+  align?: ValueLabelAlign;
+  color?: Color;
+  fontSize?: number;
+  fontStyle?: string;
+  box?: LabelBoxStyle;
+}
+
+export interface ArrowAnnotationSpec {
+  kind: "arrow";
+  /** Tail of the arrow — `[x, y]` in data or frame-anchor coordinates. */
+  from: readonly [AnnotationX, AnnotationY];
+  /** Head of the arrow. Direction is `from → to`. */
+  to: readonly [AnnotationX, AnnotationY];
+  /** Optional label rendered near the arrowhead. */
+  label?: string;
+  /**
+   * Pixel offset for the label relative to the arrowhead. Default
+   * `[6, -6]` — to-the-right-and-above the head.
+   */
+  labelOffset?: readonly [number, number];
+  labelAlign?: ValueLabelAlign;
+  labelBox?: LabelBoxStyle;
+  /** Stroke color for the shaft and head fill. Defaults to `theme.text.color`. */
+  color?: Color;
+  /** Shaft thickness in CSS pixels. Default `1.5`. */
+  strokeWidth?: number;
+  /**
+   * Arrowhead size in CSS pixels — total length from base to tip. Default
+   * `9`; the head is `headSize × 0.5` wide at the base.
+   */
+  headSize?: number;
+  fontSize?: number;
+  fontStyle?: string;
+}
+
+export interface CalloutAnnotationSpec {
+  kind: "callout";
+  /** Data point the callout is anchored to. */
+  at: readonly [AnnotationX, AnnotationY];
+  /** Label text rendered at the offset position. */
+  label: string;
+  /**
+   * Pixel offset from the anchor to the label position. The leader line
+   * runs between them. Default `[40, -20]`.
+   */
+  offset?: readonly [number, number];
+  /** Leader stroke color. Defaults to `theme.text.color` (faded by `leaderAlpha`). */
+  color?: Color;
+  /** Multiplier on the leader's stroke alpha. Default `0.6`. */
+  leaderAlpha?: number;
+  /** Leader thickness in CSS pixels. Default `1`. */
+  strokeWidth?: number;
+  /** Label text color. Defaults to `theme.text.color`. */
+  labelColor?: Color;
+  align?: ValueLabelAlign;
+  box?: LabelBoxStyle;
+  fontSize?: number;
+  fontStyle?: string;
+}
+
+export type AnnotationSpec = TextAnnotationSpec | ArrowAnnotationSpec | CalloutAnnotationSpec;
+
+// ---------------------------------------------------------------------------
+// Factory namespace — sugar for producing specs with sensible defaults
+// ---------------------------------------------------------------------------
+
+export const annotate = {
+  arrow: (spec: Omit<ArrowAnnotationSpec, "kind">): ArrowAnnotationSpec => ({
+    kind: "arrow",
+    ...spec,
+  }),
+  callout: (spec: Omit<CalloutAnnotationSpec, "kind">): CalloutAnnotationSpec => ({
+    kind: "callout",
+    ...spec,
+  }),
+  text: (spec: Omit<TextAnnotationSpec, "kind">): TextAnnotationSpec => ({
+    kind: "text",
+    ...spec,
+  }),
+} as const;
+
+// ---------------------------------------------------------------------------
+// Coordinate resolution
+// ---------------------------------------------------------------------------
+
+const FRAME_X: ReadonlySet<string> = new Set(["left", "center", "right"]);
+const FRAME_Y: ReadonlySet<string> = new Set(["top", "middle", "bottom"]);
+
+function isFrameAnchorX(v: unknown): v is FrameAnchorX {
+  return typeof v === "string" && FRAME_X.has(v);
+}
+function isFrameAnchorY(v: unknown): v is FrameAnchorY {
+  return typeof v === "string" && FRAME_Y.has(v);
+}
+
+function resolveX(value: AnnotationX, scales: ScaleBundle, plot: Frame): number {
+  if (isFrameAnchorX(value)) {
+    if (value === "left") return plot.x;
+    if (value === "right") return plot.x + plot.width;
+    return plot.x + plot.width / 2;
+  }
+  return plot.x + scales.x.fn(value);
+}
+
+function resolveY(value: AnnotationY, scales: ScaleBundle, plot: Frame): number {
+  if (isFrameAnchorY(value)) {
+    if (value === "top") return plot.y;
+    if (value === "bottom") return plot.y + plot.height;
+    return plot.y + plot.height / 2;
+  }
+  return plot.y + scales.y.fn(value);
+}
+
+function resolvePoint(
+  coord: readonly [AnnotationX, AnnotationY],
+  scales: ScaleBundle,
+  plot: Frame,
+): Vec2 {
+  return { x: resolveX(coord[0], scales, plot), y: resolveY(coord[1], scales, plot) };
+}
+
+/** Default `align` for a frame anchor: stick text inside the chart. */
+function defaultTextAlign(spec: TextAnnotationSpec): ValueLabelAlign {
+  if (spec.align) return spec.align;
+  if (isFrameAnchorX(spec.x)) {
+    if (spec.x === "left") return "left";
+    if (spec.x === "right") return "right";
+    return "center";
+  }
+  return "left";
+}
+
+// ---------------------------------------------------------------------------
+// Arrowhead geometry — three-point filled triangle at `to`
+// ---------------------------------------------------------------------------
+
+function arrowHeadPoints(from: Vec2, to: Vec2, size: number): readonly Vec2[] {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const len = Math.hypot(dx, dy);
+  if (!Number.isFinite(len) || len === 0) {
+    // Degenerate: zero-length arrow. Skip the head — the line itself will
+    // also collapse to a point and rendering it is harmless.
+    return [];
+  }
+  const ux = dx / len;
+  const uy = dy / len;
+  // Perpendicular to direction.
+  const px = -uy;
+  const py = ux;
+  const halfWidth = size * 0.5;
+  const baseX = to.x - ux * size;
+  const baseY = to.y - uy * size;
+  return [
+    { x: to.x, y: to.y },
+    { x: baseX + px * halfWidth, y: baseY + py * halfWidth },
+    { x: baseX - px * halfWidth, y: baseY - py * halfWidth },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Renderers — one branch per kind, dispatched from `renderAnnotations`
+// ---------------------------------------------------------------------------
+
+function renderText(
+  spec: TextAnnotationSpec,
+  scales: ScaleBundle,
+  plot: Frame,
+  theme: Theme,
+  hud: Layer,
+): void {
+  const x = resolveX(spec.x, scales, plot) + (spec.offsetX ?? 0);
+  const y = resolveY(spec.y, scales, plot) + (spec.offsetY ?? 0);
+  valueLabelMark([0], {
+    x: () => x,
+    y: () => y,
+    text: () => spec.text,
+    fontSize: spec.fontSize ?? theme.marks.annotationFontSize,
+    fontStyle: spec.fontStyle,
+    color: spec.color ?? theme.text.color,
+    align: defaultTextAlign(spec),
+    offset: { x: 0, y: 0 },
+    box: spec.box,
+  }).addTo(hud);
+}
+
+function renderArrow(
+  spec: ArrowAnnotationSpec,
+  scales: ScaleBundle,
+  plot: Frame,
+  theme: Theme,
+  hud: Layer,
+): void {
+  const from = resolvePoint(spec.from, scales, plot);
+  const to = resolvePoint(spec.to, scales, plot);
+  const color = spec.color ?? theme.text.color;
+  const width = spec.strokeWidth ?? 1.5;
+  const headSize = spec.headSize ?? 9;
+
+  // Shorten the shaft so it terminates at the back of the arrowhead — keeps
+  // the join clean instead of the line poking through the triangle tip.
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const len = Math.hypot(dx, dy);
+  let shaftEnd: Vec2 = to;
+  if (len > headSize) {
+    const t = (len - headSize * 0.9) / len;
+    shaftEnd = { x: from.x + dx * t, y: from.y + dy * t };
+  }
+  hud.addLines([{ x1: from.x, y1: from.y, x2: shaftEnd.x, y2: shaftEnd.y, color, width }]);
+  const head = arrowHeadPoints(from, to, headSize);
+  if (head.length === 3) {
+    hud.addPolygons([{ points: head, fill: color }]);
+  }
+
+  if (spec.label) {
+    const [ox, oy] = spec.labelOffset ?? [6, -6];
+    valueLabelMark([0], {
+      x: () => to.x + ox,
+      y: () => to.y + oy,
+      text: () => spec.label!,
+      fontSize: spec.fontSize ?? theme.marks.annotationFontSize,
+      fontStyle: spec.fontStyle,
+      color: spec.color ?? theme.text.color,
+      align: spec.labelAlign ?? (ox >= 0 ? "left" : "right"),
+      offset: { x: 0, y: 0 },
+      box: spec.labelBox,
+    }).addTo(hud);
+  }
+}
+
+function renderCallout(
+  spec: CalloutAnnotationSpec,
+  scales: ScaleBundle,
+  plot: Frame,
+  theme: Theme,
+  hud: Layer,
+): void {
+  const anchor = resolvePoint(spec.at, scales, plot);
+  const [ox, oy] = spec.offset ?? [40, -20];
+  const label: Vec2 = { x: anchor.x + ox, y: anchor.y + oy };
+  const baseColor = spec.color ?? theme.text.color;
+  const alpha = (baseColor.a ?? 1) * (spec.leaderAlpha ?? 0.6);
+  const leaderColor: Color = { r: baseColor.r, g: baseColor.g, b: baseColor.b, a: alpha };
+  hud.addLines([
+    {
+      x1: anchor.x,
+      y1: anchor.y,
+      x2: label.x,
+      y2: label.y,
+      color: leaderColor,
+      width: spec.strokeWidth ?? 1,
+    },
+  ]);
+
+  valueLabelMark([0], {
+    x: () => label.x,
+    y: () => label.y,
+    text: () => spec.label,
+    fontSize: spec.fontSize ?? theme.marks.annotationFontSize,
+    fontStyle: spec.fontStyle,
+    color: spec.labelColor ?? theme.text.color,
+    align: spec.align ?? (ox >= 0 ? "left" : "right"),
+    offset: { x: 0, y: 0 },
+    box: spec.box,
+  }).addTo(hud);
+}
+
+export function renderAnnotations(
+  specs: readonly AnnotationSpec[],
+  scales: ScaleBundle,
+  plot: Frame,
+  theme: Theme,
+  hud: Layer,
+): void {
+  if (specs.length === 0) return;
+  for (const spec of specs) {
+    const kind = spec.kind ?? "text";
+    if (kind === "arrow") renderArrow(spec as ArrowAnnotationSpec, scales, plot, theme, hud);
+    else if (kind === "callout")
+      renderCallout(spec as CalloutAnnotationSpec, scales, plot, theme, hud);
+    else renderText(spec as TextAnnotationSpec, scales, plot, theme, hud);
+  }
+}