@opendata-ai/openchart-engine 2.10.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "2.10.0",
+    "@opendata-ai/openchart-core": "2.11.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/axes.test.ts

@@ -1,8 +1,8 @@
-import type { LayoutStrategy } from '@opendata-ai/openchart-core';
+import type { AxisTick, LayoutStrategy } from '@opendata-ai/openchart-core';
 import { resolveTheme } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../compiler/types';
-import { computeAxes, effectiveDensity } from '../layout/axes';
+import { computeAxes, effectiveDensity, thinTicksUntilFit, ticksOverlap } from '../layout/axes';
 import { computeScales } from '../layout/scales';
 
 const lineSpec: NormalizedChartSpec = {
@@ -300,3 +300,180 @@ describe('effectiveDensity', () => {
     expect(effectiveDensity('full', 400, X_MINIMAL, X_REDUCED)).toBe('full');
   });
 });
+
+// ---------------------------------------------------------------------------
+// ticksOverlap unit tests
+// ---------------------------------------------------------------------------
+
+describe('ticksOverlap', () => {
+  const fontSize = 12;
+  const fontWeight = 400;
+
+  it('returns false for empty or single tick', () => {
+    expect(ticksOverlap([], fontSize, fontWeight)).toBe(false);
+    expect(ticksOverlap([{ value: 0, position: 100, label: 'A' }], fontSize, fontWeight)).toBe(
+      false,
+    );
+  });
+
+  it('returns false when ticks are well-spaced', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'A' },
+      { value: 1, position: 200, label: 'B' },
+      { value: 2, position: 400, label: 'C' },
+    ];
+    expect(ticksOverlap(ticks, fontSize, fontWeight)).toBe(false);
+  });
+
+  it('returns true when ticks are too close together', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'January 2025' },
+      { value: 1, position: 30, label: 'February 2025' },
+      { value: 2, position: 60, label: 'March 2025' },
+    ];
+    expect(ticksOverlap(ticks, fontSize, fontWeight)).toBe(true);
+  });
+
+  it('uses measureText when provided', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'A' },
+      { value: 1, position: 100, label: 'B' },
+    ];
+
+    // With a measureText that reports very wide labels, they should overlap
+    const wideMeasure = () => ({ width: 200, height: 12 });
+    expect(ticksOverlap(ticks, fontSize, fontWeight, wideMeasure)).toBe(true);
+
+    // With a measureText that reports very narrow labels, they should not overlap
+    const narrowMeasure = () => ({ width: 1, height: 12 });
+    expect(ticksOverlap(ticks, fontSize, fontWeight, narrowMeasure)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// thinTicksUntilFit unit tests
+// ---------------------------------------------------------------------------
+
+describe('thinTicksUntilFit', () => {
+  const fontSize = 12;
+  const fontWeight = 400;
+
+  it('returns original array when no overlap', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'A' },
+      { value: 1, position: 200, label: 'B' },
+      { value: 2, position: 400, label: 'C' },
+    ];
+    const result = thinTicksUntilFit(ticks, fontSize, fontWeight);
+    expect(result).toBe(ticks); // Same reference, not a copy
+  });
+
+  it('thins overlapping ticks while keeping first and last', () => {
+    // Ticks at 10px intervals with long labels that will overlap
+    const ticks: AxisTick[] = Array.from({ length: 8 }, (_, i) => ({
+      value: i,
+      position: i * 10,
+      label: 'Long Label Text',
+    }));
+
+    const result = thinTicksUntilFit(ticks, fontSize, fontWeight);
+
+    // Should have fewer ticks than the original
+    expect(result.length).toBeLessThan(ticks.length);
+    // Should always keep first and last
+    expect(result[0]).toBe(ticks[0]);
+    expect(result[result.length - 1]).toBe(ticks[ticks.length - 1]);
+    // Should have at least MIN_TICK_COUNT (2)
+    expect(result.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('returns at least 2 ticks even when labels are very wide', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'Very Long Label That Is Wide' },
+      { value: 1, position: 5, label: 'Another Very Long Label' },
+      { value: 2, position: 10, label: 'Yet Another Long Label Here' },
+    ];
+    const result = thinTicksUntilFit(ticks, fontSize, fontWeight);
+    expect(result.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Text-aware tick density integration tests
+// ---------------------------------------------------------------------------
+
+describe('text-aware tick density', () => {
+  it('produces fewer x-axis ticks in narrow charts', () => {
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const wideArea = { x: 50, y: 50, width: 800, height: 300 };
+
+    const scalesNarrow = computeScales(lineSpec, narrowArea, lineSpec.data);
+    const scalesWide = computeScales(lineSpec, wideArea, lineSpec.data);
+
+    const axesNarrow = computeAxes(scalesNarrow, narrowArea, fullStrategy, theme);
+    const axesWide = computeAxes(scalesWide, wideArea, fullStrategy, theme);
+
+    expect(axesNarrow.x!.ticks.length).toBeLessThanOrEqual(axesWide.x!.ticks.length);
+  });
+
+  it('does not thin x-axis ticks when explicit tickCount is set', () => {
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const specWithTickCount: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        x: { field: 'date', type: 'temporal', axis: { tickCount: 8 } },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    const scales = computeScales(specWithTickCount, narrowArea, specWithTickCount.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    // With explicit tickCount, the engine should not thin
+    // D3 may return fewer than 8 for this small dataset, but the point is
+    // thinTicksUntilFit should not be called
+    expect(axes.x!.ticks.length).toBeGreaterThan(0);
+  });
+
+  it('band scale shows all categories regardless of width', () => {
+    const categories = ['Alpha', 'Bravo', 'Charlie', 'Delta', 'Echo'];
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      type: 'column',
+      data: categories.map((cat, i) => ({ cat, val: (i + 1) * 10 })),
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const scales = computeScales(barSpec, narrowArea, barSpec.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    // Band scales show all categories (auto-rotation handles overlap instead)
+    expect(axes.x!.ticks.length).toBe(categories.length);
+  });
+
+  it('passes measureText to auto-rotation detection', () => {
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      type: 'column',
+      data: [
+        { cat: 'A', val: 10 },
+        { cat: 'B', val: 20 },
+      ],
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+
+    // measureText that reports very wide labels should trigger rotation
+    const wideMeasure = () => ({ width: 1000, height: 12 });
+    const scales = computeScales(barSpec, chartArea, barSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme, wideMeasure);
+
+    expect(axes.x!.tickAngle).toBe(-45);
+  });
+});

package/src/annotations/__tests__/compute.test.ts

@@ -354,8 +354,8 @@ describe('computeAnnotations', () => {
       // The offset annotation should be shifted by the dx/dy amount
       const dx = withOffset[0].label!.x - withoutOffset[0].label!.x;
       const dy = withOffset[0].label!.y - withoutOffset[0].label!.y;
-      expect(dx).toBe(20);
-      expect(dy).toBe(-30);
+      expect(dx).toBeCloseTo(20);
+      expect(dy).toBeCloseTo(-30);
     });
   });
 
@@ -514,8 +514,8 @@ describe('computeAnnotations', () => {
 
       const dx = withOffset[0].label!.x - withoutOffset[0].label!.x;
       const dy = withOffset[0].label!.y - withoutOffset[0].label!.y;
-      expect(dx).toBe(20);
-      expect(dy).toBe(10);
+      expect(dx).toBeCloseTo(20);
+      expect(dy).toBeCloseTo(10);
     });
   });
 
@@ -773,4 +773,173 @@ describe('computeAnnotations', () => {
       expect(connector.from.x).toBeCloseTo(label.x + 66, 1);
     });
   });
+
+  // -----------------------------------------------------------------
+  // Annotation-to-annotation collision resolution
+  // -----------------------------------------------------------------
+
+  describe('annotation-to-annotation collision', () => {
+    it('nudges second annotation when two overlap at the same data point', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'First note' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Second note' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+
+      const label1 = annotations[0].label!;
+      const label2 = annotations[1].label!;
+
+      // Both should be visible
+      expect(label1.visible).toBe(true);
+      expect(label2.visible).toBe(true);
+
+      // Labels should not overlap: their positions should differ
+      const samePosition = label1.x === label2.x && label1.y === label2.y;
+      expect(samePosition).toBe(false);
+    });
+
+    it('nudges second annotation when nearby data points produce overlapping labels', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'First annotation' },
+        { type: 'text', x: '2020-01-01', y: 21, text: 'Second annotation' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+
+      const label1 = annotations[0].label!;
+      const label2 = annotations[1].label!;
+
+      // After collision resolution, bounding boxes should not overlap
+      // Check that at least one coordinate differs meaningfully
+      const dy = Math.abs(label1.y - label2.y);
+      const dx = Math.abs(label1.x - label2.x);
+      expect(dx + dy).toBeGreaterThan(5);
+    });
+
+    it('recomputes connector origin after nudging', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'First note' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Second note' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const nudgedLabel = annotations[1].label!;
+
+      // The nudged annotation should still have a connector
+      expect(nudgedLabel.connector).toBeDefined();
+
+      // The connector "from" should be near the nudged label position, not the original
+      const connFrom = nudgedLabel.connector!.from;
+      const labelCenterX = nudgedLabel.x;
+      const labelCenterY = nudgedLabel.y;
+
+      // Connector origin should be within a reasonable distance of the label
+      const distFromLabel = Math.sqrt(
+        (connFrom.x - labelCenterX) ** 2 + (connFrom.y - labelCenterY) ** 2,
+      );
+      // Should be within the label's bounding box range (text width + height)
+      expect(distFromLabel).toBeLessThan(200);
+    });
+
+    it('resolves three overlapping annotations without any collision', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Note A' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Note B' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Note C' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(3);
+
+      // All three should be visible
+      for (const ann of annotations) {
+        expect(ann.label!.visible).toBe(true);
+      }
+
+      // All three should have distinct positions
+      const positions = annotations.map((a) => `${a.label!.x.toFixed(1)},${a.label!.y.toFixed(1)}`);
+      const unique = new Set(positions);
+      expect(unique.size).toBe(3);
+    });
+
+    it('does not nudge annotations that already have distinct positions', () => {
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 10,
+          text: 'Low point',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 40 },
+        },
+        {
+          type: 'text',
+          x: '2022-01-01',
+          y: 40,
+          text: 'High point',
+          anchor: 'top',
+          offset: { dx: 0, dy: -40 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Compute once to get positions
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+
+      // These annotations are far apart, so positions should match what they'd
+      // be without collision resolution (i.e., not nudged)
+      const specSingle1 = makeSpec([spec.annotations[0]]);
+      const specSingle2 = makeSpec([spec.annotations[1]]);
+      const single1 = computeAnnotations(specSingle1, scales, chartArea, fullStrategy);
+      const single2 = computeAnnotations(specSingle2, scales, chartArea, fullStrategy);
+
+      expect(annotations[0].label!.x).toBeCloseTo(single1[0].label!.x, 1);
+      expect(annotations[0].label!.y).toBeCloseTo(single1[0].label!.y, 1);
+      expect(annotations[1].label!.x).toBeCloseTo(single2[0].label!.x, 1);
+      expect(annotations[1].label!.y).toBeCloseTo(single2[0].label!.y, 1);
+    });
+  });
+
+  // -----------------------------------------------------------------
+  // Obstacle avoidance (label bounds as obstacles)
+  // -----------------------------------------------------------------
+
+  describe('obstacle avoidance', () => {
+    it('nudges annotation away from an obstacle rect at the same position', () => {
+      const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'Annotation' }]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Place an obstacle rect exactly where the annotation would land
+      const withoutObstacles = computeAnnotations(spec, scales, chartArea, fullStrategy);
+      const originalLabel = withoutObstacles[0].label!;
+
+      const obstacle: Rect = {
+        x: originalLabel.x - 5,
+        y: originalLabel.y - 5,
+        width: 80,
+        height: 30,
+      };
+
+      const withObstacles = computeAnnotations(spec, scales, chartArea, fullStrategy, false, [
+        obstacle,
+      ]);
+
+      expect(withObstacles).toHaveLength(1);
+      const nudgedLabel = withObstacles[0].label!;
+      expect(nudgedLabel.visible).toBe(true);
+
+      // The annotation should have moved away from the obstacle
+      const moved = nudgedLabel.x !== originalLabel.x || nudgedLabel.y !== originalLabel.y;
+      expect(moved).toBe(true);
+    });
+  });
 });

package/src/annotations/compute.ts

@@ -24,7 +24,7 @@ import type {
   TextAnnotation,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { detectCollision, estimateTextWidth } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear, ScaleTime } from 'd3-scale';
 import type { NormalizedChartSpec } from '../compiler/types';
 import type { ResolvedScales } from '../layout/scales';
@@ -549,14 +549,43 @@ function estimateLabelBounds(label: ResolvedLabel): Rect {
   return computeTextBounds(label.x, label.y, label.text, fontSize, fontWeight);
 }
 
-/** Check if two rects overlap. */
-function rectsOverlap(a: Rect, b: Rect): boolean {
-  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
-}
-
 /** Padding between annotation and obstacle when nudging. */
 const NUDGE_PADDING = 6;
 
+/**
+ * Generate candidate displacement vectors to move `selfBounds` clear of each
+ * obstacle in 4 directions (below, above, left, right), sorted by smallest
+ * movement first.
+ */
+function generateNudgeCandidates(
+  selfBounds: Rect,
+  obstacles: Rect[],
+  padding: number,
+): { dx: number; dy: number; distance: number }[] {
+  const candidates: { dx: number; dy: number; distance: number }[] = [];
+
+  for (const obs of obstacles) {
+    // Below: shift self so its top edge clears the obstacle bottom
+    const belowDy = obs.y + obs.height + padding - selfBounds.y;
+    candidates.push({ dx: 0, dy: belowDy, distance: Math.abs(belowDy) });
+
+    // Above: shift self so its bottom edge clears the obstacle top
+    const aboveDy = obs.y - padding - (selfBounds.y + selfBounds.height);
+    candidates.push({ dx: 0, dy: aboveDy, distance: Math.abs(aboveDy) });
+
+    // Left: shift self so its right edge clears the obstacle left
+    const leftDx = obs.x - padding - (selfBounds.x + selfBounds.width);
+    candidates.push({ dx: leftDx, dy: 0, distance: Math.abs(leftDx) });
+
+    // Right: shift self so its left edge clears the obstacle right
+    const rightDx = obs.x + obs.width + padding - selfBounds.x;
+    candidates.push({ dx: rightDx, dy: 0, distance: Math.abs(rightDx) });
+  }
+
+  candidates.sort((a, b) => a.distance - b.distance);
+  return candidates;
+}
+
 /**
  * Try to reposition a text annotation to avoid overlapping with obstacle rects
  * (legend bounds, etc.). First tries standard anchor alternatives, then
@@ -573,7 +602,7 @@ function nudgeAnnotationFromObstacles(
 
   const labelBounds = estimateLabelBounds(annotation.label);
   const collidingObs = obstacles.filter(
-    (obs) => obs.width > 0 && obs.height > 0 && rectsOverlap(labelBounds, obs),
+    (obs) => obs.width > 0 && obs.height > 0 && detectCollision(labelBounds, obs),
   );
 
   if (collidingObs.length === 0) return false;
@@ -583,39 +612,9 @@ function nudgeAnnotationFromObstacles(
   const py = resolvePosition(originalAnnotation.y, scales.y);
   if (px === null || py === null) return false;
 
-  // Generate candidate positions: calculated offsets to clear each obstacle
-  const candidates: { dx: number; dy: number; distance: number }[] = [];
+  const candidates = generateNudgeCandidates(labelBounds, collidingObs, NUDGE_PADDING);
   const fontSize = labelBounds.height / Math.max(1, annotation.label.text.split('\n').length);
 
-  for (const obs of collidingObs) {
-    // Below obstacle: shift label so its top edge clears the obstacle bottom
-    const currentLabelTop = labelBounds.y;
-    const targetLabelTop = obs.y + obs.height + NUDGE_PADDING;
-    const belowDy = targetLabelTop - currentLabelTop;
-    candidates.push({ dx: 0, dy: belowDy, distance: Math.abs(belowDy) });
-
-    // Above obstacle: shift label so its bottom edge clears the obstacle top
-    const currentLabelBottom = labelBounds.y + labelBounds.height;
-    const targetLabelBottom = obs.y - NUDGE_PADDING;
-    const aboveDy = targetLabelBottom - currentLabelBottom;
-    candidates.push({ dx: 0, dy: aboveDy, distance: Math.abs(aboveDy) });
-
-    // Left of obstacle: shift label so its right edge clears the obstacle left
-    const currentLabelRight = labelBounds.x + labelBounds.width;
-    const targetLabelRight = obs.x - NUDGE_PADDING;
-    const leftDx = targetLabelRight - currentLabelRight;
-    candidates.push({ dx: leftDx, dy: 0, distance: Math.abs(leftDx) });
-
-    // Right of obstacle: shift label so its left edge clears the obstacle right
-    const currentLabelLeft = labelBounds.x;
-    const targetLabelLeft = obs.x + obs.width + NUDGE_PADDING;
-    const rightDx = targetLabelLeft - currentLabelLeft;
-    candidates.push({ dx: rightDx, dy: 0, distance: Math.abs(rightDx) });
-  }
-
-  // Sort candidates by distance (prefer smallest movement)
-  candidates.sort((a, b) => a.distance - b.distance);
-
   for (const { dx, dy } of candidates) {
     const newLabelX = annotation.label.x + dx;
     const newLabelY = annotation.label.y + dy;
@@ -651,7 +650,7 @@ function nudgeAnnotationFromObstacles(
 
     // Check no collisions with any obstacle
     const stillCollides = obstacles.some(
-      (obs) => obs.width > 0 && obs.height > 0 && rectsOverlap(candidateBounds, obs),
+      (obs) => obs.width > 0 && obs.height > 0 && detectCollision(candidateBounds, obs),
     );
     if (stillCollides) continue;
 
@@ -660,11 +659,14 @@ function nudgeAnnotationFromObstacles(
     // the text doesn't go completely off-screen.
     const labelCenterX = candidateBounds.x + candidateBounds.width / 2;
     const labelCenterY = candidateBounds.y + candidateBounds.height / 2;
+    // Allow nudged labels to extend into the chrome region below the chart
+    // (source/footer area) since annotations near the bottom edge often
+    // need to shift into that space to avoid marks or the brand watermark.
     const inBounds =
       labelCenterX >= chartArea.x &&
       labelCenterX <= chartArea.x + chartArea.width + 100 &&
       labelCenterY >= chartArea.y - fontSize &&
-      labelCenterY <= chartArea.y + chartArea.height + fontSize;
+      labelCenterY <= chartArea.y + chartArea.height + fontSize * 3;
 
     if (inBounds) {
       // When nudged vertically (directly above/below the data), use a caret
@@ -683,6 +685,117 @@ function nudgeAnnotationFromObstacles(
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// Annotation-to-annotation collision resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve collisions between text annotation labels using a greedy algorithm.
+ *
+ * Iterates through text annotations in order, building a list of "placed"
+ * bounding rects. When a later annotation overlaps an already-placed one,
+ * it tries offset positions (below, above, left, right) to find a
+ * non-colliding spot. Recomputes the connector origin after nudging.
+ */
+function resolveAnnotationCollisions(
+  annotations: ResolvedAnnotation[],
+  originalSpecs: NormalizedChartSpec['annotations'],
+  scales: ResolvedScales,
+  chartArea: Rect,
+): void {
+  const placedBounds: Rect[] = [];
+
+  for (let i = 0; i < annotations.length; i++) {
+    const annotation = annotations[i];
+    if (annotation.type !== 'text' || !annotation.label) {
+      continue;
+    }
+
+    const bounds = estimateLabelBounds(annotation.label);
+
+    // Check against all previously placed annotation labels
+    const collidingBounds = placedBounds.filter(
+      (pb) => pb.width > 0 && pb.height > 0 && detectCollision(bounds, pb),
+    );
+
+    if (collidingBounds.length > 0) {
+      // Find the original spec to get data point coordinates for connector recomputation
+      const originalSpec = originalSpecs[i];
+
+      if (originalSpec?.type === 'text') {
+        const px = resolvePosition(originalSpec.x, scales.x);
+        const py = resolvePosition(originalSpec.y, scales.y);
+
+        if (px !== null && py !== null) {
+          const candidates = generateNudgeCandidates(bounds, collidingBounds, NUDGE_PADDING);
+          const fontSize = bounds.height / Math.max(1, annotation.label.text.split('\n').length);
+
+          for (const { dx, dy } of candidates) {
+            const newLabelX = annotation.label.x + dx;
+            const newLabelY = annotation.label.y + dy;
+
+            const candidateLabel: ResolvedLabel = {
+              ...annotation.label,
+              x: newLabelX,
+              y: newLabelY,
+            };
+            const candidateBounds = estimateLabelBounds(candidateLabel);
+
+            // Check no collisions with any placed label
+            const stillCollides = placedBounds.some(
+              (pb) => pb.width > 0 && pb.height > 0 && detectCollision(candidateBounds, pb),
+            );
+            if (stillCollides) continue;
+
+            // Check the label center stays reasonably in bounds
+            const labelCenterX = candidateBounds.x + candidateBounds.width / 2;
+            const labelCenterY = candidateBounds.y + candidateBounds.height / 2;
+            const inBounds =
+              labelCenterX >= chartArea.x &&
+              labelCenterX <= chartArea.x + chartArea.width + 100 &&
+              labelCenterY >= chartArea.y - fontSize &&
+              labelCenterY <= chartArea.y + chartArea.height + fontSize;
+
+            if (inBounds) {
+              // Recompute connector origin for the new position
+              let newConnector = annotation.label.connector;
+              if (newConnector) {
+                const annFontSize = annotation.label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+                const annFontWeight =
+                  annotation.label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+                const connStyle =
+                  newConnector.style === 'curve' ? ('curve' as const) : ('straight' as const);
+                const newFrom = computeConnectorOrigin(
+                  newLabelX,
+                  newLabelY,
+                  annotation.label.text,
+                  annFontSize,
+                  annFontWeight,
+                  px,
+                  py,
+                  connStyle,
+                );
+                newConnector = { ...newConnector, from: newFrom };
+              }
+
+              annotation.label = {
+                ...annotation.label,
+                x: newLabelX,
+                y: newLabelY,
+                connector: newConnector,
+              };
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    // Add this annotation's final bounds to the placed list
+    placedBounds.push(estimateLabelBounds(annotation.label));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -696,7 +809,8 @@ function nudgeAnnotationFromObstacles(
  *
  * When obstacle rects are provided (e.g. legend bounds), text annotations
  * that overlap with them are automatically repositioned using alternate
- * anchor directions.
+ * anchor directions. After individual obstacle avoidance, annotation-to-
+ * annotation collisions are resolved using a greedy placement algorithm.
  */
 export function computeAnnotations(
   spec: NormalizedChartSpec,
@@ -737,6 +851,9 @@ export function computeAnnotations(
     }
   }
 
+  // Resolve annotation-to-annotation collisions (greedy, order-preserving)
+  resolveAnnotationCollisions(annotations, spec.annotations, scales, chartArea);
+
   // Sort by zIndex (lower first, undefined treated as 0)
   annotations.sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));