@@ -1,24 +1,35 @@
 import logging
-from collections import Counter
 from pathlib import Path
 
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 from matplotlib.axes import Axes
+from matplotlib.colors import to_rgba
 from matplotlib.patches import FancyBboxPatch
+from matplotlib.patheffects import withSimplePatchShadow
 
 from .base import add_axis_labels, add_bird_images, add_date, add_quadrant_labels, add_quadrants, setup_plot
 
 logger = logging.getLogger(__name__)
 
 _BOX_HEIGHT = 1.0
-_CLUSTER_PAD = 0.5  # breathing room kept between boxes
+_BOX_PAD = 0.3  # FancyBboxPatch round padding, in data units (expands the box each side)
+_BOX_GAP = 0.08  # minimum visual gap kept between boxes (a few px) so they never touch
+_CLUSTER_PAD = 2 * _BOX_PAD + _BOX_GAP  # reserve each box's padding on both sides + the gap
+_CALLOUT_OFFSET = 6.0  # how far a colliding group's stack is moved off its point
+_CALLOUT_BOX_GAP = _BOX_HEIGHT + _CLUSTER_PAD  # center-to-center spacing of stacked callout boxes
+_CALLOUT_DOT_GAP = 0.8  # vertical spacing of the per-person dots at the true point
+_GRADIENT_BAND = 0.12  # half-width of the soft transition between the two fill colours
 
-# Box border colour keyed to a person's dominant bird, so the label reads on any
-# quadrant background (white fill) while the border still carries meaning.
-_BIRD_BORDER = {"D": "royalblue", "E": "crimson", "O": "goldenrod", "P": "seagreen"}
-_NEUTRAL_BORDER = "0.4"
+_BIRD_NAME = {"D": "Dove", "E": "Eagle", "O": "Owl", "P": "Peacock"}
+# Light bird hues for the label fill (matching the quadrant colours).
+_BIRD_LIGHT = {"D": "lightskyblue", "E": "lightcoral", "O": "khaki", "P": "lightgreen"}
+_PASTEL = 0.5  # how far the fill colours are blended toward white (0 = none, 1 = white)
+
+# Direction each bird leans toward, matching its quadrant corner:
+# Dove top-right, Owl bottom-right, Peacock top-left, Eagle bottom-left.
+_BIRD_DIR = {"D": (1.0, 1.0), "O": (1.0, -1.0), "P": (-1.0, 1.0), "E": (-1.0, -1.0)}
 
 
 def _box_text(row) -> str:
@@ -28,22 +39,87 @@ def _box_text(row) -> str:
     return f"{row['Name']} {note_str}".strip()
 
 
-def _border_color(row) -> str:
-    """Pick a border colour from the dominant bird.
+def _bird_vector(row) -> np.ndarray:
+    """Direction a person leans, from their primary (and secondary) bird.
+
+    Uses the Note's two letters (primary weighted more); falls back to the two
+    highest scores. Returns an unnormalized 2-vector pointing toward that blend.
+    """
+    note = row.get("Note", "")
+    letters = [c for c in str(note).upper() if c in _BIRD_DIR][:2] if (note and not pd.isna(note)) else []
+    if not letters:
+        scores = {b: (row.get(b) or 0) for b in ("Dove", "Eagle", "Owl", "Peacock")}
+        letters = [b[0] for b in sorted(scores, key=scores.get, reverse=True)[:2]]
+    vec = np.zeros(2)
+    for letter, weight in zip(letters, (1.0, 0.5), strict=False):
+        vec += np.array(_BIRD_DIR[letter]) * weight
+    return vec
+
+
+def _gradient_stops(row):
+    """Return (primary_colour, secondary_colour, ratio) for the label fill.
 
-    Prefers the primary letter of the Note (what the label shows); falls back to
-    the highest raw score, then to a neutral grey when nothing is available.
+    Colours are the light bird hues; ratio is the primary bird's share of the
+    two scores, so the gradient leans toward whichever bird dominates.
     """
     note = row.get("Note", "")
-    if note and not pd.isna(note):
-        color = _BIRD_BORDER.get(str(note)[:1].upper())
-        if color:
-            return color
-    scores = {b: row.get(b) for b in ("Dove", "Eagle", "Owl", "Peacock")}
-    scores = {b: v for b, v in scores.items() if v is not None and not pd.isna(v)}
-    if scores:
-        return _BIRD_BORDER[max(scores, key=scores.get)[0]]
-    return _NEUTRAL_BORDER
+    letters = [c for c in str(note).upper() if c in _BIRD_LIGHT][:2] if (note and not pd.isna(note)) else []
+    scores = {b: (row.get(b) or 0) for b in ("Dove", "Eagle", "Owl", "Peacock")}
+    if len(letters) < 2:
+        for letter in (b[0] for b in sorted(scores, key=scores.get, reverse=True)):
+            if letter not in letters:
+                letters.append(letter)
+            if len(letters) == 2:
+                break
+    s1, s2 = scores[_BIRD_NAME[letters[0]]], scores[_BIRD_NAME[letters[1]]]
+    ratio = s1 / (s1 + s2) if (s1 + s2) else 0.5
+    return _BIRD_LIGHT[letters[0]], _BIRD_LIGHT[letters[1]], ratio
+
+
+def _pastel(color) -> np.ndarray:
+    """Return an RGBA blended toward white for a softer, pastel fill."""
+    rgba = np.array(to_rgba(color))
+    rgba[:3] = rgba[:3] + (1.0 - rgba[:3]) * _PASTEL
+    return rgba
+
+
+def _gradient_image(rgba1, rgba2, ratio):
+    """A 1xN horizontal gradient that splits primary->secondary at ``ratio``.
+
+    Proportional split: the primary colour fills ``ratio`` of the width, the
+    secondary the rest, with a soft transition band so the share stays legible.
+    """
+    xs = np.linspace(0.0, 1.0, 64)
+    blend = np.clip((xs - ratio) / (2 * _GRADIENT_BAND) + 0.5, 0.0, 1.0)
+    return ((1 - blend)[:, None] * rgba1 + blend[:, None] * rgba2).reshape(1, 64, 4)
+
+
+def _fill_gradient_box(ax, bx, by, w, h, c1, c2, ratio):
+    """Draw a rounded, borderless label box filled with a primary->secondary
+    pastel gradient, plus a soft drop shadow for a bit of volume."""
+    ratio = min(max(ratio, 0.05), 0.95)
+    fill = _gradient_image(_pastel(c1), _pastel(c2), ratio)
+    rounded = f"round,pad={_BOX_PAD}"
+
+    # Drop shadow: a hidden white source patch (fully covered by the opaque fill
+    # on top) whose offset shadow peeks out below-right.
+    shadow = FancyBboxPatch(
+        (bx - w / 2, by - h / 2), w, h, boxstyle=rounded, facecolor="white", edgecolor="none", zorder=2.6,
+    )
+    shadow.set_path_effects([withSimplePatchShadow(offset=(2.5, -2.5), alpha=0.15, shadow_rgbFace="black")])
+    ax.add_patch(shadow)
+
+    # Gradient fill, clipped to the rounded box.
+    clip = FancyBboxPatch(
+        (bx - w / 2, by - h / 2), w, h, boxstyle=rounded, facecolor="none", edgecolor="none", zorder=3,
+    )
+    ax.add_patch(clip)
+    img = ax.imshow(
+        fill,
+        extent=(bx - w / 2 - _BOX_PAD, bx + w / 2 + _BOX_PAD, by - h / 2 - _BOX_PAD, by + h / 2 + _BOX_PAD),
+        aspect="auto", origin="lower", zorder=3, interpolation="bilinear",
+    )
+    img.set_clip_path(clip)
 
 
 def _declutter(centers: np.ndarray, sizes: np.ndarray, max_value: float, iters: int = 400) -> np.ndarray:
@@ -113,53 +189,85 @@ def find(a):
 
 
 def add_name_boxes(ax: Axes, df: pd.DataFrame, max_value: float) -> None:
-    """Draw name boxes, decluttering only where they would overlap.
+    """Draw name boxes, with callouts for people who collide.
 
-    Each box starts on its person's true (X, Y). Overlapping boxes are pushed
-    apart; any box that had to move shows a small dot at its true point and a
-    grey leader line back to it, so people with identical or very similar
-    profiles stay individually readable. Boxes that don't collide are left
-    exactly on their point, with no extra marks.
+    Each box starts on its person's true (X, Y). Where boxes overlap, the whole
+    group is lifted aside (horizontally, toward the birds' side) and each person
+    gets their own dot fanned at the true location, joined to their box by a thin
+    dashed leader line — so even identical profiles stay individually readable.
+    People who don't collide are left exactly on their point.
     """
     texts = [_box_text(row) for _, row in df.iterrows()]
     if not texts:
         return
-    border_colors = [_border_color(row) for _, row in df.iterrows()]
+    stops = [_gradient_stops(row) for _, row in df.iterrows()]  # (primary, secondary, ratio) per person
+    bird_vecs = [_bird_vector(row) for _, row in df.iterrows()]
 
     sizes = np.array([[max(8, len(t) * 0.4), _BOX_HEIGHT] for t in texts], dtype=float)
     anchors = df[["X", "Y"]].to_numpy(dtype=float)
 
-    # Boxes start on their true point; overlapping ones get pushed apart.
+    # Singletons rest on their point; clustered boxes get repositioned below.
     pos = _declutter(anchors.copy(), sizes, max_value)
 
-    # One marker per overlapping cluster: a single dot at the group's location
-    # with one leader line to the stack. Coincident people share a point, so a
-    # per-person dot would be ambiguous; the stacked chips list who is there.
+    # For each overlapping group, lift the whole stack along its bird direction
+    # to make room for a dot per person fanned at the true location.
+    clusters = []  # (member indices, true cx, cy)
     for group in _clusters(anchors, sizes):
         if len(group) < 2:
             continue
-        anchor_mid = anchors[group].mean(axis=0)
-        box_mid = pos[group].mean(axis=0)
-        color = Counter(border_colors[i] for i in group).most_common(1)[0][0]
-        ax.plot([box_mid[0], anchor_mid[0]], [box_mid[1], anchor_mid[1]], color=color, linewidth=0.9, zorder=2)
-        ax.scatter([anchor_mid[0]], [anchor_mid[1]], s=16, color=color, zorder=4)
-
+        members = sorted(group, key=lambda i: anchors[i, 1], reverse=True)
+        n = len(members)
+        cx, cy = anchors[group].mean(axis=0)
+        half_w = sizes[group][:, 0].max() / 2
+        half_h = (n - 1) / 2 * _CALLOUT_BOX_GAP + _BOX_HEIGHT / 2
+
+        # Offset the stack HORIZONTALLY toward the side the birds lean (Dove/Owl
+        # -> right, Peacock/Eagle -> left); if that side has no room, use the
+        # other. A purely horizontal move keeps the dots beside the stack, so the
+        # leader lines stay clear of the sibling boxes.
+        bird = np.sum([bird_vecs[i] for i in group], axis=0)
+        side = 1.0 if bird[0] >= 0 else -1.0
+        stack_y = np.clip(cy, -max_value + half_h, max_value - half_h)
+        center = np.array([cx, stack_y])
+        for sx in (side, -side):
+            x = np.clip(cx + sx * _CALLOUT_OFFSET, -max_value + half_w, max_value - half_w)
+            center = np.array([x, stack_y])
+            if abs(x - cx) >= half_w + 0.5:  # enough room to clear the dots
+                break
+
+        for rank, i in enumerate(members):
+            level = (n - 1) / 2 - rank
+            pos[i] = [center[0], center[1] + level * _CALLOUT_BOX_GAP]
+        clusters.append((group, cx, cy))
+
+    # A moved stack may now overlap a neighbour; declutter once more so
+    # everything is collision-free before we draw the leader lines.
+    if clusters:
+        pos = _declutter(pos, sizes, max_value)
+
+    # One dot per collided person at its true location, matched to the FINAL
+    # vertical order of the boxes. The line simply targets the box centre — the
+    # opaque gradient box drawn on top hides the part of the line beneath it.
+    for group, cx, cy in clusters:
+        members = sorted(group, key=lambda i: pos[i][1], reverse=True)
+        n = len(members)
+        for rank, i in enumerate(members):
+            level = (n - 1) / 2 - rank
+            dot_x, dot_y = cx, cy + level * _CALLOUT_DOT_GAP
+            ax.plot([pos[i][0], dot_x], [pos[i][1], dot_y], color="black", linewidth=0.5, linestyle="--", zorder=2)
+            ax.scatter([dot_x], [dot_y], s=2, color="black", zorder=4)
+
+    # Gradient-filled label boxes (imshow can disturb the axes aspect/limits, so
+    # snapshot and restore them afterwards).
+    xlim, ylim = ax.get_xlim(), ax.get_ylim()
     for i, text in enumerate(texts):
         bx, by = pos[i]
-
-        box = FancyBboxPatch(
-            (bx - sizes[i, 0] / 2, by - sizes[i, 1] / 2),
-            width=sizes[i, 0],
-            height=sizes[i, 1],
-            boxstyle="round,pad=0.3",
-            edgecolor=border_colors[i],
-            facecolor="white",
-            linewidth=1.6,
-            alpha=0.95,
-            zorder=3,
-        )
-        ax.add_patch(box)
+        c1, c2, ratio = stops[i]
+        _fill_gradient_box(ax, bx, by, sizes[i, 0], sizes[i, 1], c1, c2, ratio)
         ax.text(bx, by, text, fontsize=10, ha="center", va="center", color="black", zorder=5)
+    ax.set_aspect("equal", adjustable="box")
+    ax.set_xlim(*xlim)
+    ax.set_ylim(*ylim)
 
 
 def add_grid(ax: Axes) -> None:
 
@@ -4,10 +4,9 @@
 import numpy as np
 import pandas as pd
 import pytest
-from matplotlib.patches import FancyBboxPatch
 
 from bird_plot.plots.base import setup_plot
-from bird_plot.plots.scatter import _border_color, _clusters, _declutter, add_grid, add_name_boxes, scatter_chart
+from bird_plot.plots.scatter import _BOX_GAP, _BOX_PAD, _clusters, _declutter, add_grid, add_name_boxes, scatter_chart
 
 MV = 25
 
@@ -37,15 +36,15 @@ def test_add_grid_adds_two_lines(fig_ax):
     assert len(ax.get_lines()) - before == 2
 
 
-def test_add_name_boxes_one_box_and_text_per_row(fig_ax):
+def test_add_name_boxes_one_label_per_row(fig_ax):
     _, ax = fig_ax
     df = _df()
-    boxes_before = sum(isinstance(p, FancyBboxPatch) for p in ax.patches)
     texts_before = len(ax.texts)
+    images_before = len(ax.images)
     add_name_boxes(ax, df, MV)
-    boxes_after = sum(isinstance(p, FancyBboxPatch) for p in ax.patches)
-    assert boxes_after - boxes_before == len(df)
+    # One text label and one gradient-fill image per person.
     assert len(ax.texts) - texts_before == len(df)
+    assert len(ax.images) - images_before == len(df)
     assert any("Alice" in t.get_text() for t in ax.texts)
 
 
@@ -58,15 +57,15 @@ def test_add_name_boxes_no_dot_without_collision(fig_ax):
     assert len(ax.collections) == before
 
 
-def test_add_name_boxes_one_dot_per_cluster(fig_ax):
+def test_add_name_boxes_dot_per_collided_person(fig_ax):
     _, ax = fig_ax
-    # Three coincident people form ONE cluster -> a single dot, not three.
+    # Three coincident people -> a distinct dot each (callout).
     df = pd.DataFrame(
         {"Name": ["A", "B", "C"], "Note": ["D/O", "D/O", "D/O"], "X": [5.0, 5.0, 5.0], "Y": [5.0, 5.0, 5.0]}
     )
     before = len(ax.collections)
     add_name_boxes(ax, df, MV)
-    assert len(ax.collections) - before == 1
+    assert len(ax.collections) - before == 3
 
 
 def test_add_name_boxes_handles_nan_note(fig_ax):
@@ -118,23 +117,34 @@ def test_clusters_groups_overlapping_separates_distant():
     assert sizes_of_groups == [1, 2]  # two coincident together, the far one alone
 
 
-# --- border colour ---
-
-
-def test_border_color_from_note_primary_letter():
-    assert _border_color(pd.Series({"Name": "X", "Note": "D/O"})) == "royalblue"
-    assert _border_color(pd.Series({"Name": "X", "Note": "E/P"})) == "crimson"
-    assert _border_color(pd.Series({"Name": "X", "Note": "O/D"})) == "goldenrod"
-    assert _border_color(pd.Series({"Name": "X", "Note": "P/D"})) == "seagreen"
+def test_declutter_separates_horizontally():
+    # Boxes overlapping more vertically than horizontally separate along x.
+    centers = np.array([[0.0, 0.0], [8.5, 0.0]])
+    sizes = np.array([[9.0, 1.0], [9.0, 1.0]])
+    out = _declutter(centers, sizes, MV)
+    assert abs(out[0, 0] - out[1, 0]) >= 9.0  # cleared on the x-axis
 
 
-def test_border_color_falls_back_to_dominant_score():
-    row = pd.Series({"Name": "X", "Note": np.nan, "Dove": 1, "Eagle": 2, "Owl": 9, "Peacock": 3})
-    assert _border_color(row) == "goldenrod"  # Owl highest
+def test_declutter_leaves_no_visual_overlap():
+    # A pile of overlapping boxes must end up with no two boxes visually
+    # overlapping (accounting for each box's rounded padding on every side).
+    centers = np.array([[0.0, 0.0]] * 6)
+    sizes = np.array([[9.0, 1.0]] * 6)
+    out = _declutter(centers, sizes, MV)
+    for i in range(len(out)):
+        for j in range(i + 1, len(out)):
+            dx, dy = abs(out[i, 0] - out[j, 0]), abs(out[i, 1] - out[j, 1])
+            need_x = (sizes[i, 0] + sizes[j, 0]) / 2 + 2 * _BOX_PAD + _BOX_GAP
+            need_y = (sizes[i, 1] + sizes[j, 1]) / 2 + 2 * _BOX_PAD + _BOX_GAP
+            # Cleared (visual extents disjoint) on at least one axis.
+            assert dx >= need_x - 1e-9 or dy >= need_y - 1e-9
 
 
-def test_border_color_neutral_when_unknown():
-    assert _border_color(pd.Series({"Name": "X", "Note": ""})) == "0.4"
+def test_add_name_boxes_empty_df_is_noop(fig_ax):
+    _, ax = fig_ax
+    before = (len(ax.texts), len(ax.images), len(ax.patches))
+    add_name_boxes(ax, pd.DataFrame({"Name": [], "Note": [], "X": [], "Y": []}), MV)
+    assert (len(ax.texts), len(ax.images), len(ax.patches)) == before
 
 
 def test_scatter_chart_writes_png(base_config, tmp_path):