core+site: Tier-2 mark: "beeswarm" — packed strip plot

@glyph/core
  - New mark in MarkSchema: "beeswarm". Categorical x (band scale),
    quantitative y. Compiler runs per-band 1D non-overlap packing
    so dots are placed near their encoded y position but nudged
    horizontally within the band so they don't overlap. Visually
    halfway between a strip plot and a violin — keeps every
    individual data point visible while distribution shape emerges
    naturally from density.
  - Deterministic placement: rows processed in source order; the
    offset-search algorithm is fully deterministic (no random
    tiebreaks), so byte-identical SVG on every run.
  - Added "beeswarm" to the Phase-1 allowedMarks gate alongside the
    other distribution / data marks.
  - 4 new tests in src/compiler/beeswarm-mark.test.ts: one circle
    per row, 2r minimum spacing between any pair, byte-identical
    output across runs, SVG renders with the expected circle count.

site/play
  - New "Tenure beeswarm — by team" chip: 4 teams × 12 employees
    each, packed by tenure months. Shows the canonical beeswarm
    use-case (compare distributions across categories without
    binning or losing individual points).

Tests now 720/720 passing. Biome clean. Playground bundle rebuilt.

Tier-2 status after this PR:
  - arc        ✓ shipped (#106)
  - slopegraph ✓ shipped via playground example (#106)
  - step-line  ✓ shipped (#103 core + #106 example)
  - beeswarm   ✓ shipped (this PR)
  - sankey     ← still deferred (next-PR scope: ~400-500 LOC for
                 longest-path layering + crossing-minimization +
                 curved bezier links; no existing layout to lean
                 on)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: seanhanca

packages/core/src/compiler/beeswarm-mark.test.ts

@@ -0,0 +1,91 @@
+// Tier-2 — `mark: "beeswarm"` packed strip plot.
+import { describe, expect, it } from "vitest";
+import { renderSvg } from "../render/svg.js";
+import type { GlyphSpec } from "../spec/types.js";
+import { compileSpec } from "./compile.js";
+
+const schema = [
+  { name: "team", type: "VARCHAR", nullable: false },
+  { name: "tenure", type: "DOUBLE", nullable: false },
+];
+
+// 3 teams × 8 employees each. tenure is months at the company.
+const rows: ReadonlyArray<ReadonlyArray<unknown>> = [
+  // Platform team
+  ["Platform", 6],
+  ["Platform", 12],
+  ["Platform", 18],
+  ["Platform", 24],
+  ["Platform", 30],
+  ["Platform", 36],
+  ["Platform", 48],
+  ["Platform", 60],
+  // Product team
+  ["Product", 3],
+  ["Product", 9],
+  ["Product", 15],
+  ["Product", 21],
+  ["Product", 27],
+  ["Product", 33],
+  ["Product", 42],
+  ["Product", 54],
+  // Design team
+  ["Design", 8],
+  ["Design", 14],
+  ["Design", 20],
+  ["Design", 26],
+  ["Design", 32],
+  ["Design", 38],
+  ["Design", 50],
+  ["Design", 62],
+];
+
+describe('Tier-2 — `mark: "beeswarm"`', () => {
+  it("emits one circle SceneMark per row", () => {
+    const spec: GlyphSpec = {
+      layers: [{ mark: "beeswarm", encoding: { x: "team", y: "tenure" } }],
+    };
+    const scene = compileSpec({ spec, rows, schema });
+    const circles = scene.marks.filter((m) => m.type === "circle");
+    expect(circles.length).toBe(24);
+  });
+
+  it("dots within a band are non-overlapping (2r minimum spacing)", () => {
+    const spec: GlyphSpec = {
+      layers: [{ mark: "beeswarm", encoding: { x: "team", y: "tenure" } }],
+    };
+    const scene = compileSpec({ spec, rows, schema });
+    const circles = scene.marks.filter(
+      (m): m is Extract<typeof m, { type: "circle" }> => m.type === "circle",
+    );
+    // For every pair of circles, distance ≥ 2r.
+    for (let i = 0; i < circles.length; i++) {
+      for (let j = i + 1; j < circles.length; j++) {
+        const a = circles[i]!;
+        const b = circles[j]!;
+        const d = Math.hypot(a.cx - b.cx, a.cy - b.cy);
+        // Allow a 0.5px slack for round-pixel rounding.
+        expect(d).toBeGreaterThanOrEqual(2 * a.r - 0.5);
+      }
+    }
+  });
+
+  it("is deterministic — same rows produce identical SVG", () => {
+    const spec: GlyphSpec = {
+      layers: [{ mark: "beeswarm", encoding: { x: "team", y: "tenure" } }],
+    };
+    const a = renderSvg(compileSpec({ spec, rows, schema }));
+    const b = renderSvg(compileSpec({ spec, rows, schema }));
+    expect(a).toBe(b);
+  });
+
+  it("renders to a non-empty SVG with the expected number of circles", () => {
+    const spec: GlyphSpec = {
+      layers: [{ mark: "beeswarm", encoding: { x: "team", y: "tenure" } }],
+    };
+    const scene = compileSpec({ spec, rows, schema });
+    const svg = renderSvg(scene);
+    expect(svg.startsWith("<svg")).toBe(true);
+    expect((svg.match(/<circle /g) ?? []).length).toBe(24);
+  });
+});

packages/core/src/compiler/compile.ts

@@ -1097,6 +1097,9 @@ export function compileSpec(input: CompileInput): Scene {
       // control points (no row data; configuration lives in
       // `layer.bezier`). Cartesian path with linear x/y.
       "bezier",
+      // Tier-2 — packed strip plot. Categorical x, quantitative y;
+      // per x-group the compiler runs 1D non-overlap packing.
+      "beeswarm",
     ];
     if (!allowedMarks.includes(l.mark)) {
       throw new Error(`Phase 1 supports marks ${allowedMarks.join("|")}; layer ${i} has ${l.mark}`);
@@ -3112,6 +3115,100 @@ function buildRules(
   }
 }
 
+/**
+ * buildBeeswarm — packed strip plot (Tier-2).
+ *
+ * For each x-band (categorical), collects all the rows whose x value
+ * matches, then runs a 1D non-overlap pack: dots are placed at their
+ * encoded y, but nudged horizontally within the band so adjacent dots
+ * don't overlap. Halfway visually between a strip plot and a violin
+ * — keeps every individual point visible while letting density shape
+ * emerge.
+ *
+ * Determinism: rows are processed in source order; the placement
+ * algorithm is a deterministic offset search (no random tiebreaks).
+ * Same rows → same offsets → byte-identical SVG.
+ */
+function buildBeeswarm(
+  out: SceneMark[],
+  rows: ReadonlyArray<ReadonlyArray<unknown>>,
+  schema: ReadonlyArray<CompileFieldInfo>,
+  encoding: Encoding,
+  xField: string,
+  yField: string,
+  xScale: ReturnType<typeof bandScale>,
+  yScale: ReturnType<typeof linearScale>,
+  theme: Theme,
+): void {
+  const colorField = fieldOf(encoding.color);
+  const colorDomain = colorField ? distinctOrdered(rows, schema, colorField) : [];
+  const yIdx = schema.findIndex((c) => c.name === yField);
+  const radius = 4;
+  // Group rows by x-band.
+  type Point = { y: number; row: ReadonlyArray<unknown>; rowIdx: number };
+  const bands = new Map<string, Point[]>();
+  for (let i = 0; i < rows.length; i++) {
+    const r = rows[i];
+    if (!r) continue;
+    const xv = valueAt(r, schema, xField);
+    if (xv == null) continue;
+    const yv = yIdx >= 0 ? Number(r[yIdx]) : Number.NaN;
+    if (!Number.isFinite(yv)) continue;
+    const key = String(xv);
+    let list = bands.get(key);
+    if (!list) {
+      list = [];
+      bands.set(key, list);
+    }
+    list.push({ y: yScale.apply(yv), row: r, rowIdx: i });
+  }
+  // Per-band layout: sort by y, then place each point at the closest
+  // x-offset that doesn't collide with already-placed neighbors.
+  // Search candidates: bandCenter, ±radius·2, ±radius·4, … This is
+  // d3-beeswarm's "force-x clamped to a band" pattern, simplified.
+  const bandHalfWidth = xScale.bandwidth / 2 - radius;
+  for (const [bandKey, ptsRaw] of bands) {
+    const bandCenter = xScale.apply(bandKey) + xScale.bandwidth / 2;
+    const pts = [...ptsRaw].sort((a, b) => a.y - b.y);
+    const placed: Array<{ x: number; y: number; row: ReadonlyArray<unknown>; rowIdx: number }> = [];
+    for (const p of pts) {
+      let chosenX = bandCenter;
+      // Generate up to N offset candidates outward from bandCenter.
+      const candidates = [0];
+      for (let i = 1; i < 50; i++) {
+        candidates.push(i * radius);
+        candidates.push(-i * radius);
+      }
+      let found = false;
+      for (const dx of candidates) {
+        if (Math.abs(dx) > bandHalfWidth) continue;
+        const x = bandCenter + dx;
+        // Collision check: distance to any already-placed point in
+        // this band must be ≥ 2r.
+        const collides = placed.some((q) => Math.hypot(x - q.x, p.y - q.y) < radius * 2);
+        if (!collides) {
+          chosenX = x;
+          found = true;
+          break;
+        }
+      }
+      // Fallback: if every candidate inside the band collides, allow
+      // overlap at the closest legal x (caps overflowing slightly).
+      if (!found) chosenX = bandCenter;
+      placed.push({ x: chosenX, y: p.y, row: p.row, rowIdx: p.rowIdx });
+    }
+    for (const q of placed) {
+      out.push({
+        type: "circle",
+        cx: roundPx(q.x),
+        cy: q.y,
+        r: radius,
+        fill: colorForRow(encoding, schema, q.row, colorDomain, theme, rows),
+      });
+    }
+  }
+}
+
 /**
  * buildBoxplot — distribution mark (PR50).
  *
@@ -3987,6 +4084,24 @@ registerMark({
     );
   },
 });
+registerMark({
+  type: "beeswarm",
+  compile(args) {
+    if (!args.yScale) return;
+    if (args.xScale.type !== "band") return;
+    buildBeeswarm(
+      args.out,
+      args.rows,
+      args.schema,
+      args.layer.encoding,
+      args.xField,
+      args.yField,
+      args.xScale,
+      args.yScale,
+      args.theme,
+    );
+  },
+});
 registerMark({
   type: "text",
   compile(args) {

packages/core/src/spec/schemas.ts

@@ -550,6 +550,12 @@ export const MarkSchema = z.enum([
   // the compiler computes Q1 / median / Q3 / whiskers (Tukey, 1.5 × IQR)
   // and outliers beyond the whisker bounds.
   "boxplot",
+  // Tier-2 — beeswarm packing. Categorical x, quantitative y; per
+  // x-group the compiler runs a 1D non-overlap pack that nudges
+  // dots horizontally within the band so they don't overlap.
+  // Visually halfway between a strip plot and a violin — keeps every
+  // individual data point visible while showing distribution shape.
+  "beeswarm",
   // PR50 — direct label annotation. Renders a text mark at each row's
   // (x, y) with the value of encoding.text. Composes with other marks
   // via multi-layer specs (e.g. bars + text labels).

site/play/examples/business/tenure-beeswarm.csv

@@ -0,0 +1,49 @@
+team,tenure_months
+Platform,6
+Platform,14
+Platform,18
+Platform,22
+Platform,28
+Platform,33
+Platform,37
+Platform,42
+Platform,48
+Platform,55
+Platform,62
+Platform,71
+Product,4
+Product,9
+Product,13
+Product,17
+Product,21
+Product,24
+Product,28
+Product,32
+Product,36
+Product,40
+Product,46
+Product,52
+Design,8
+Design,12
+Design,16
+Design,20
+Design,24
+Design,29
+Design,34
+Design,41
+Design,50
+Design,58
+Design,65
+Design,74
+Sales,3
+Sales,8
+Sales,12
+Sales,16
+Sales,20
+Sales,24
+Sales,29
+Sales,33
+Sales,40
+Sales,48
+Sales,57
+Sales,66

site/play/examples/business/tenure-beeswarm.spec.json

@@ -0,0 +1,15 @@
+{
+  "version": "glyph/0.1",
+  "title": "Employee tenure by team — beeswarm (months at company)",
+  "width": 640,
+  "height": 420,
+  "layers": [
+    {
+      "mark": "beeswarm",
+      "encoding": {
+        "x": { "field": "team", "type": "ordinal" },
+        "y": { "field": "tenure_months", "type": "quantitative", "scale": { "domain": [0, 80] } }
+      }
+    }
+  ]
+}

site/play/examples/index.json

@@ -231,6 +231,14 @@
     "csv": "examples/business/step-line.csv",
     "spec": "examples/business/step-line.spec.json"
   },
+  {
+    "id": "tenure-beeswarm",
+    "category": "Business charts",
+    "name": "Tenure beeswarm — by team",
+    "description": "12 employees × 4 teams. Each dot is one person; the `beeswarm` mark packs them horizontally inside each band so density shows without losing individual points.",
+    "csv": "examples/business/tenure-beeswarm.csv",
+    "spec": "examples/business/tenure-beeswarm.spec.json"
+  },
 
   {
     "id": "ridgeline",