From c035ebd737f174c6deab12f7a282d339c5157fda Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 13:41:01 +0200
Subject: [PATCH 01/16] feat(models): add cluster detail, sub-cluster, and
 annotation models

---
 embedding_cluster/server/models.py | 67 ++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/embedding_cluster/server/models.py b/embedding_cluster/server/models.py
index 8de9ca2..b53843e 100644
--- a/embedding_cluster/server/models.py
+++ b/embedding_cluster/server/models.py
@@ -156,3 +156,70 @@ class SearchRequest(BaseModel):
 
 class SearchResponse(BaseModel):
     results: list[SearchResult]
+
+
+class ClusterItemResponse(BaseModel):
+    id: str
+    metadata: dict[str, object]
+    distance_to_centroid: float
+
+
+class ClusterDetailResponse(BaseModel):
+    cluster_index: int
+    cluster_name: str
+    total_items: int
+    page: int
+    page_size: int
+    items: list[ClusterItemResponse]
+
+
+class SubClusterRequest(BaseModel):
+    num_sub_clusters: int = 3
+
+    @field_validator("num_sub_clusters")
+    @classmethod
+    def validate_num_sub_clusters(cls, v: int) -> int:
+        if v < 2:
+            msg = "num_sub_clusters must be at least 2"
+            raise ValueError(msg)
+        return v
+
+
+class SubClusterPoint(BaseModel):
+    id: str
+    x: float
+    y: float
+    z: float
+    sub_cluster: int
+    metadata: dict[str, object]
+
+
+class SubClusterInfo(BaseModel):
+    index: int
+    count: int
+    color: str
+
+
+class SubClusterResponse(BaseModel):
+    parent_cluster_index: int
+    points: list[SubClusterPoint]
+    sub_clusters: list[SubClusterInfo]
+    total_points: int
+
+
+class AnnotationUpdate(BaseModel):
+    name: str | None = None
+    notes: str | None = None
+    tags: list[str] | None = None
+
+
+class ClusterAnnotation(BaseModel):
+    name: str | None = None
+    notes: str | None = None
+    tags: list[str] | None = None
+    updated_at: str | None = None
+
+
+class AnnotationsResponse(BaseModel):
+    job_id: str
+    clusters: dict[str, ClusterAnnotation]

From 308230ede911298ef9afc79514c90e0e798d14d5 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 13:44:06 +0200
Subject: [PATCH 02/16] feat(annotations): add AnnotationManager with
 file-based JSON storage

---
 embedding_cluster/annotations.py | 69 ++++++++++++++++++++++++
 tests/test_annotations.py        | 90 ++++++++++++++++++++++++++++++++
 2 files changed, 159 insertions(+)
 create mode 100644 embedding_cluster/annotations.py
 create mode 100644 tests/test_annotations.py

diff --git a/embedding_cluster/annotations.py b/embedding_cluster/annotations.py
new file mode 100644
index 0000000..5e4aabc
--- /dev/null
+++ b/embedding_cluster/annotations.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_BASE_DIR = Path("./annotations")
+
+
+class AnnotationManager:
+    def __init__(self, base_dir: Path | None = None) -> None:
+        self._base_dir = base_dir or _DEFAULT_BASE_DIR
+        self._base_dir.mkdir(parents=True, exist_ok=True)
+
+    def _file_path(self, job_id: str) -> Path:
+        return self._base_dir / f"{job_id}.json"
+
+    def _read(self, job_id: str) -> dict[str, Any]:
+        path = self._file_path(job_id)
+        if not path.exists():
+            return {"job_id": job_id, "clusters": {}}
+        data: dict[str, Any] = json.loads(path.read_text())
+        return data
+
+    def _write(self, job_id: str, data: dict[str, Any]) -> None:
+        path = self._file_path(job_id)
+        path.write_text(json.dumps(data, indent=2))
+
+    def get_annotations(self, job_id: str) -> dict[str, Any]:
+        return self._read(job_id)
+
+    def update_annotation(
+        self,
+        job_id: str,
+        cluster_index: int,
+        name: str | None = None,
+        notes: str | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        data = self._read(job_id)
+        key = str(cluster_index)
+        if key not in data["clusters"]:
+            data["clusters"][key] = {
+                "name": None,
+                "notes": None,
+                "tags": None,
+                "updated_at": None,
+            }
+        cluster = data["clusters"][key]
+        if name is not None:
+            cluster["name"] = name
+        if notes is not None:
+            cluster["notes"] = notes
+        if tags is not None:
+            cluster["tags"] = tags
+        cluster["updated_at"] = datetime.now(
+            tz=timezone.utc  # noqa: UP017
+        ).isoformat()
+        self._write(job_id, data)
+        return data
+
+    def delete_annotations(self, job_id: str) -> None:
+        path = self._file_path(job_id)
+        if path.exists():
+            path.unlink()
diff --git a/tests/test_annotations.py b/tests/test_annotations.py
new file mode 100644
index 0000000..714eb93
--- /dev/null
+++ b/tests/test_annotations.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+import pytest
+
+from embedding_cluster.annotations import AnnotationManager
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@pytest.fixture
+def annotations_dir(tmp_path: Path) -> Path:
+    return tmp_path / "annotations"
+
+
+@pytest.fixture
+def manager(annotations_dir: Path) -> AnnotationManager:
+    return AnnotationManager(base_dir=annotations_dir)
+
+
+class TestAnnotationManager:
+    def test_get_empty_annotations(self, manager: AnnotationManager) -> None:
+        result = manager.get_annotations("job1")
+        assert result == {"job_id": "job1", "clusters": {}}
+
+    def test_update_cluster_annotation(self, manager: AnnotationManager) -> None:
+        manager.update_annotation("job1", 0, name="Shoes", notes="Athletic shoes")
+        result = manager.get_annotations("job1")
+        assert "0" in result["clusters"]
+        assert result["clusters"]["0"]["name"] == "Shoes"
+        assert result["clusters"]["0"]["notes"] == "Athletic shoes"
+        assert result["clusters"]["0"]["updated_at"] is not None
+
+    def test_update_partial_fields(self, manager: AnnotationManager) -> None:
+        manager.update_annotation("job1", 0, name="Shoes")
+        manager.update_annotation("job1", 0, notes="Running shoes")
+        result = manager.get_annotations("job1")
+        assert result["clusters"]["0"]["name"] == "Shoes"
+        assert result["clusters"]["0"]["notes"] == "Running shoes"
+
+    def test_update_tags(self, manager: AnnotationManager) -> None:
+        manager.update_annotation("job1", 0, tags=["footwear", "sport"])
+        result = manager.get_annotations("job1")
+        assert result["clusters"]["0"]["tags"] == [
+            "footwear",
+            "sport",
+        ]
+
+    def test_multiple_clusters(self, manager: AnnotationManager) -> None:
+        manager.update_annotation("job1", 0, name="Shoes")
+        manager.update_annotation("job1", 1, name="Hats")
+        result = manager.get_annotations("job1")
+        assert len(result["clusters"]) == 2
+        assert result["clusters"]["0"]["name"] == "Shoes"
+        assert result["clusters"]["1"]["name"] == "Hats"
+
+    def test_persistence(self, annotations_dir: Path) -> None:
+        manager1 = AnnotationManager(base_dir=annotations_dir)
+        manager1.update_annotation("job1", 0, name="Shoes")
+        manager2 = AnnotationManager(base_dir=annotations_dir)
+        result = manager2.get_annotations("job1")
+        assert result["clusters"]["0"]["name"] == "Shoes"
+
+    def test_delete_annotations(self, manager: AnnotationManager) -> None:
+        manager.update_annotation("job1", 0, name="Shoes")
+        manager.delete_annotations("job1")
+        result = manager.get_annotations("job1")
+        assert result == {"job_id": "job1", "clusters": {}}
+
+    def test_file_created_in_correct_dir(
+        self,
+        manager: AnnotationManager,
+        annotations_dir: Path,
+    ) -> None:
+        manager.update_annotation("job1", 0, name="Shoes")
+        file_path = annotations_dir / "job1.json"
+        assert file_path.exists()
+        data = json.loads(file_path.read_text())
+        assert data["job_id"] == "job1"
+
+    def test_multiple_jobs(self, manager: AnnotationManager) -> None:
+        manager.update_annotation("job1", 0, name="Shoes")
+        manager.update_annotation("job2", 0, name="Hats")
+        r1 = manager.get_annotations("job1")
+        r2 = manager.get_annotations("job2")
+        assert r1["clusters"]["0"]["name"] == "Shoes"
+        assert r2["clusters"]["0"]["name"] == "Hats"

From 1533a881c66a245f960979a6680dcd831c6a308f Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 13:49:23 +0200
Subject: [PATCH 03/16] feat(plot): store standardized embeddings and labels in
 task result

---
 embedding_cluster/scatter_plot.py       |  3 +
 embedding_cluster/server/routes/plot.py |  5 +-
 tests/test_scatter_plot.py              | 78 +++++++++++++++++++++++++
 tests/test_server_plot.py               | 46 +++++++++++++++
 4 files changed, 131 insertions(+), 1 deletion(-)

diff --git a/embedding_cluster/scatter_plot.py b/embedding_cluster/scatter_plot.py
index 6400305..769422a 100644
--- a/embedding_cluster/scatter_plot.py
+++ b/embedding_cluster/scatter_plot.py
@@ -340,6 +340,9 @@ def compute_plot_data(settings: Settings) -> dict[str, Any]:
         "points": points,
         "clusters": clusters,
         "total_points": len(collection_content["ids"]),
+        "embeddings_standardized": embeddings_standardized.tolist(),
+        "cluster_labels": np.asarray(pred_arr).tolist(),
+        "point_ids": [p["id"] for p in points],
     }
 
 
diff --git a/embedding_cluster/server/routes/plot.py b/embedding_cluster/server/routes/plot.py
index cba9303..a0ea21e 100644
--- a/embedding_cluster/server/routes/plot.py
+++ b/embedding_cluster/server/routes/plot.py
@@ -71,10 +71,13 @@ async def get_plot_data(job_id: str) -> dict[str, object]:
         return {"status": "failed", "error": task.error, "ready": False}
     # COMPLETED
     result = cast("dict[str, object]", task.result)
+    # Strip internal fields not meant for the frontend
+    internal_keys = ("embeddings_standardized", "cluster_labels", "point_ids")
+    frontend_result = {k: v for k, v in result.items() if k not in internal_keys}
     return {
         "status": "completed",
         "ready": True,
-        **result,
+        **frontend_result,
     }
 
 
diff --git a/tests/test_scatter_plot.py b/tests/test_scatter_plot.py
index 80333ab..e98e58f 100644
--- a/tests/test_scatter_plot.py
+++ b/tests/test_scatter_plot.py
@@ -603,3 +603,81 @@ def test_defaults_to_all_metadata_when_no_fields_selected(self) -> None:
             "imageUrl": "url1",
             "category": "a",
         }
+
+
+class TestComputePlotDataInternalFields:
+    """Tests for internal fields added by compute_plot_data."""
+
+    def _make_settings(self) -> Settings:
+        return Settings(
+            running_mode="PLOT",
+            chromadb_collection_name="test_collection",
+            num_clusters=2,
+            reduction_algorithm="pca",
+            text_display_fields=["name"],
+            image_field="imageUrl",
+        )
+
+    def _run_compute(self, settings: Settings, n_points: int = 4) -> dict[str, object]:
+        from embedding_cluster.scatter_plot import compute_plot_data
+
+        rng = np.random.default_rng(42)
+        embeddings = rng.random((n_points, 5)).tolist()
+        ids = [str(i) for i in range(n_points)]
+        metadatas = [{"name": f"item{i}", "imageUrl": f"url{i}"} for i in range(n_points)]
+        collection_content = {
+            "ids": ids,
+            "embeddings": embeddings,
+            "metadatas": metadatas,
+        }
+        labels = np.array([i % 2 for i in range(n_points)])
+
+        with (
+            patch(
+                "embedding_cluster.scatter_plot.load_chromadb_collection",
+                return_value=collection_content,
+            ),
+            patch(
+                "embedding_cluster.scatter_plot.reduce_dimensions",
+                return_value=np.zeros((n_points, 3)),
+            ),
+            patch(
+                "embedding_cluster.scatter_plot.KMeans",
+            ) as mock_kmeans_cls,
+        ):
+            mock_kmeans = MagicMock()
+            mock_kmeans.fit_predict.return_value = labels
+            mock_kmeans.cluster_centers_ = rng.random((2, 5))
+            mock_kmeans_cls.return_value = mock_kmeans
+            return compute_plot_data(settings)
+
+    def test_embeddings_standardized_present(self) -> None:
+        result = self._run_compute(self._make_settings())
+        assert "embeddings_standardized" in result
+
+    def test_embeddings_standardized_is_list_of_lists(self) -> None:
+        result = self._run_compute(self._make_settings(), n_points=4)
+        emb = result["embeddings_standardized"]
+        assert isinstance(emb, list)
+        assert len(emb) == 4
+        assert isinstance(emb[0], list)
+
+    def test_cluster_labels_present(self) -> None:
+        result = self._run_compute(self._make_settings())
+        assert "cluster_labels" in result
+
+    def test_cluster_labels_length_matches_points(self) -> None:
+        result = self._run_compute(self._make_settings(), n_points=4)
+        labels = result["cluster_labels"]
+        assert isinstance(labels, list)
+        assert len(labels) == 4
+
+    def test_point_ids_present(self) -> None:
+        result = self._run_compute(self._make_settings())
+        assert "point_ids" in result
+
+    def test_point_ids_match_collection_ids(self) -> None:
+        result = self._run_compute(self._make_settings(), n_points=4)
+        point_ids = result["point_ids"]
+        assert isinstance(point_ids, list)
+        assert sorted(point_ids) == ["0", "1", "2", "3"]
diff --git a/tests/test_server_plot.py b/tests/test_server_plot.py
index 3471109..4aa1d76 100644
--- a/tests/test_server_plot.py
+++ b/tests/test_server_plot.py
@@ -415,3 +415,49 @@ async def test_suggest_clusters_status_completed(
     result = cast("dict[str, object]", data["result"])
     assert "k_values" in result
     assert "suggested_k" in result
+
+
+@pytest.mark.asyncio
+async def test_get_data_strips_internal_fields(app: FastAPI) -> None:
+    """Internal fields should not leak to the frontend response."""
+
+    def fake_compute_with_internals(_settings: object) -> dict[str, object]:
+        return {
+            "points": [
+                {"x": 1.0, "y": 2.0, "z": 3.0, "cluster": 0, "metadata": {}, "id": "1"},
+            ],
+            "clusters": [{"index": 0, "name": "A", "color": "red", "count": 1}],
+            "total_points": 1,
+            "embeddings_standardized": [[0.1, 0.2]],
+            "cluster_labels": [0],
+            "point_ids": ["1"],
+        }
+
+    with patch(
+        "embedding_cluster.server.routes.plot.compute_plot_data",
+        side_effect=fake_compute_with_internals,
+    ):
+        async with AsyncClient(
+            transport=ASGITransport(app=app), base_url="http://test"
+        ) as client:
+            start_resp = await client.post(
+                "/api/plot/compute",
+                json={"chromadb_collection_name": "test_collection"},
+            )
+            job_id = cast("str", start_resp.json()["job_id"])
+
+            await asyncio.sleep(0.2)
+
+            response = await client.get(f"/api/plot/data/{job_id}")
+
+    assert response.status_code == status.HTTP_200_OK
+    data = cast("dict[str, object]", response.json())
+    assert cast("bool", data["ready"]) is True
+    # Public fields present
+    assert "points" in data
+    assert "clusters" in data
+    assert "total_points" in data
+    # Internal fields stripped
+    assert "embeddings_standardized" not in data
+    assert "cluster_labels" not in data
+    assert "point_ids" not in data

From d37b7c67c357672cbd404038bdde67441cc28523 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 13:51:51 +0200
Subject: [PATCH 04/16] feat(api): add cluster detail and sub-cluster endpoints

---
 embedding_cluster/server/routes/plot.py | 182 ++++++++++++++++++++-
 tests/test_cluster_detail.py            | 205 ++++++++++++++++++++++++
 tests/test_sub_cluster.py               | 186 +++++++++++++++++++++
 3 files changed, 572 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_cluster_detail.py
 create mode 100644 tests/test_sub_cluster.py

diff --git a/embedding_cluster/server/routes/plot.py b/embedding_cluster/server/routes/plot.py
index a0ea21e..26658f7 100644
--- a/embedding_cluster/server/routes/plot.py
+++ b/embedding_cluster/server/routes/plot.py
@@ -2,18 +2,25 @@
 
 import asyncio
 import logging
-from typing import cast
+from typing import Any, cast
 
 from fastapi import APIRouter, HTTPException
 
 from embedding_cluster.scatter_plot import (
     compute_plot_data,
     load_chromadb_embeddings,
+    reduce_dimensions,
     suggest_optimal_clusters,
 )
 from embedding_cluster.server.models import (
+    ClusterDetailResponse,
+    ClusterItemResponse,
     IndexStartResponse,
     PlotRequest,
+    SubClusterInfo,
+    SubClusterPoint,
+    SubClusterRequest,
+    SubClusterResponse,
     SuggestClustersRequest,
 )
 from embedding_cluster.server.tasks import TaskState, TaskStatus, task_registry
@@ -148,3 +155,176 @@ async def get_suggest_clusters_status(job_id: str) -> dict[str, object]:
         "ready": True,
         "result": result,
     }
+
+
+@router.get(
+    "/{job_id}/cluster/{cluster_index}",
+    response_model=ClusterDetailResponse,
+)
+async def get_cluster_detail(
+    job_id: str,
+    cluster_index: int,
+    page: int = 1,
+    page_size: int = 50,
+) -> ClusterDetailResponse:
+    task = task_registry.get(job_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail="Job not found")
+    if task.status != TaskStatus.COMPLETED:
+        raise HTTPException(status_code=409, detail="Job not completed")
+
+    result = cast("dict[str, object]", task.result)
+    clusters = cast("list[dict[str, object]]", result["clusters"])
+    cluster_labels = cast("list[int]", result["cluster_labels"])
+    embeddings = cast("list[list[float]]", result["embeddings_standardized"])
+    points = cast("list[dict[str, object]]", result["points"])
+
+    # Validate cluster index
+    cluster_info: dict[str, Any] | None = None
+    for c in clusters:
+        if cast("int", c["index"]) == cluster_index:
+            cluster_info = cast("dict[str, Any]", c)
+            break
+    if cluster_info is None:
+        raise HTTPException(status_code=404, detail="Cluster not found")
+
+    # Get indices belonging to this cluster
+    cluster_point_indices = [
+        i for i, label in enumerate(cluster_labels) if label == cluster_index
+    ]
+
+    # Compute centroid
+    import numpy as np
+
+    cluster_embeddings = np.array([embeddings[i] for i in cluster_point_indices])
+    centroid = cluster_embeddings.mean(axis=0)
+
+    # Compute distances and build items
+    items_with_distance: list[tuple[float, dict[str, object]]] = []
+    for idx in cluster_point_indices:
+        point_embedding = np.array(embeddings[idx])
+        distance = float(np.linalg.norm(point_embedding - centroid))
+        point = points[idx]
+        items_with_distance.append((distance, point))
+
+    # Sort by distance
+    items_with_distance.sort(key=lambda x: x[0])
+
+    # Paginate
+    total_items = len(items_with_distance)
+    start = (page - 1) * page_size
+    end = start + page_size
+    page_items = items_with_distance[start:end]
+
+    return ClusterDetailResponse(
+        cluster_index=cluster_index,
+        cluster_name=cast("str", cluster_info["name"]),
+        total_items=total_items,
+        page=page,
+        page_size=page_size,
+        items=[
+            ClusterItemResponse(
+                id=cast("str", point["id"]),
+                metadata=cast("dict[str, object]", point["metadata"]),
+                distance_to_centroid=dist,
+            )
+            for dist, point in page_items
+        ],
+    )
+
+
+@router.post(
+    "/{job_id}/cluster/{cluster_index}/sub-cluster",
+    response_model=SubClusterResponse,
+)
+async def sub_cluster(
+    job_id: str,
+    cluster_index: int,
+    request: SubClusterRequest,
+) -> SubClusterResponse:
+    task = task_registry.get(job_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail="Job not found")
+    if task.status != TaskStatus.COMPLETED:
+        raise HTTPException(status_code=409, detail="Job not completed")
+
+    result = cast("dict[str, object]", task.result)
+    clusters = cast("list[dict[str, object]]", result["clusters"])
+    cluster_labels = cast("list[int]", result["cluster_labels"])
+    embeddings = cast("list[list[float]]", result["embeddings_standardized"])
+    points = cast("list[dict[str, object]]", result["points"])
+
+    # Validate cluster exists
+    cluster_exists = any(cast("int", c["index"]) == cluster_index for c in clusters)
+    if not cluster_exists:
+        raise HTTPException(status_code=404, detail="Cluster not found")
+
+    # Get indices for this cluster
+    cluster_point_indices = [
+        i for i, label in enumerate(cluster_labels) if label == cluster_index
+    ]
+
+    num_sub = request.num_sub_clusters
+    if num_sub > len(cluster_point_indices):
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                f"num_sub_clusters ({num_sub}) exceeds "
+                f"items in cluster ({len(cluster_point_indices)})"
+            ),
+        )
+
+    # Run k-means on cluster subset
+    import numpy as np
+
+    cluster_embeddings = np.array([embeddings[i] for i in cluster_point_indices])
+
+    def _compute() -> SubClusterResponse:
+        from sklearn.cluster import KMeans
+
+        kmeans = KMeans(
+            n_clusters=num_sub,
+            n_init="auto",
+            random_state=171,
+            max_iter=1000,
+        )
+        sub_labels = kmeans.fit_predict(cluster_embeddings)
+
+        # Reduce dimensions for visualization
+        reduced = reduce_dimensions(
+            cluster_embeddings,
+            algorithm="pca",
+            n_components=3,
+        )
+
+        sub_points: list[SubClusterPoint] = []
+        for j, idx in enumerate(cluster_point_indices):
+            point = points[idx]
+            sub_points.append(
+                SubClusterPoint(
+                    id=cast("str", point["id"]),
+                    x=float(reduced[j, 0]),
+                    y=float(reduced[j, 1]),
+                    z=float(reduced[j, 2]),
+                    sub_cluster=int(sub_labels[j]),
+                    metadata=cast(
+                        "dict[str, object]",
+                        point["metadata"],
+                    ),
+                )
+            )
+
+        sub_cluster_infos: list[SubClusterInfo] = []
+        for si in range(num_sub):
+            count = int(np.sum(sub_labels == si))
+            color = f"hsl({si * 360 // num_sub}, 70%, 50%)"
+            sub_cluster_infos.append(SubClusterInfo(index=si, count=count, color=color))
+
+        return SubClusterResponse(
+            parent_cluster_index=cluster_index,
+            points=sub_points,
+            sub_clusters=sub_cluster_infos,
+            total_points=len(cluster_point_indices),
+        )
+
+    return await asyncio.to_thread(_compute)
diff --git a/tests/test_cluster_detail.py b/tests/test_cluster_detail.py
new file mode 100644
index 0000000..37ce460
--- /dev/null
+++ b/tests/test_cluster_detail.py
@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, cast
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+from fastapi import status
+from httpx import ASGITransport, AsyncClient
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from fastapi import FastAPI
+
+from embedding_cluster.server.app import create_app
+
+
+@pytest.fixture
+def app() -> FastAPI:
+    return create_app()
+
+
+def _fake_compute_with_internals(
+    _settings: object,
+) -> dict[str, object]:
+    """Fake compute that includes internal fields."""
+    # 4 points, 2 clusters
+    embeddings = np.array(
+        [
+            [1.0, 0.0],
+            [1.1, 0.1],
+            [5.0, 5.0],
+            [5.1, 5.1],
+        ]
+    )
+    return {
+        "points": [
+            {
+                "x": 0.0,
+                "y": 0.0,
+                "z": 0.0,
+                "cluster": 0,
+                "metadata": {"name": "item1"},
+                "id": "1",
+            },
+            {
+                "x": 0.1,
+                "y": 0.1,
+                "z": 0.1,
+                "cluster": 0,
+                "metadata": {"name": "item2"},
+                "id": "2",
+            },
+            {
+                "x": 1.0,
+                "y": 1.0,
+                "z": 1.0,
+                "cluster": 1,
+                "metadata": {"name": "item3"},
+                "id": "3",
+            },
+            {
+                "x": 1.1,
+                "y": 1.1,
+                "z": 1.1,
+                "cluster": 1,
+                "metadata": {"name": "item4"},
+                "id": "4",
+            },
+        ],
+        "clusters": [
+            {
+                "index": 0,
+                "name": "Group 1",
+                "color": "hsl(0, 70%, 50%)",
+                "count": 2,
+            },
+            {
+                "index": 1,
+                "name": "Group 2",
+                "color": "hsl(180, 70%, 50%)",
+                "count": 2,
+            },
+        ],
+        "total_points": 4,
+        "embeddings_standardized": embeddings.tolist(),
+        "cluster_labels": [0, 0, 1, 1],
+        "point_ids": ["1", "2", "3", "4"],
+    }
+
+
+@pytest.fixture
+def mock_compute_internals() -> Iterator[None]:
+    with patch(
+        "embedding_cluster.server.routes.plot.compute_plot_data",
+        side_effect=_fake_compute_with_internals,
+    ):
+        yield
+
+
+@pytest.mark.asyncio
+async def test_cluster_detail_success(app: FastAPI, mock_compute_internals: None) -> None:
+    _ = mock_compute_internals
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        await asyncio.sleep(0.2)
+
+        response = await client.get(f"/api/plot/{job_id}/cluster/0")
+
+    assert response.status_code == status.HTTP_200_OK
+    data = response.json()
+    assert data["cluster_index"] == 0
+    assert data["cluster_name"] == "Group 1"
+    assert data["total_items"] == 2
+    assert len(data["items"]) == 2
+    # Items should be sorted by distance to centroid
+    distances = [item["distance_to_centroid"] for item in data["items"]]
+    assert distances == sorted(distances)
+
+
+@pytest.mark.asyncio
+async def test_cluster_detail_pagination(
+    app: FastAPI, mock_compute_internals: None
+) -> None:
+    _ = mock_compute_internals
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        await asyncio.sleep(0.2)
+
+        response = await client.get(f"/api/plot/{job_id}/cluster/0?page=1&page_size=1")
+
+    data = response.json()
+    assert data["page"] == 1
+    assert data["page_size"] == 1
+    assert len(data["items"]) == 1
+    assert data["total_items"] == 2
+
+
+@pytest.mark.asyncio
+async def test_cluster_detail_invalid_cluster(
+    app: FastAPI, mock_compute_internals: None
+) -> None:
+    _ = mock_compute_internals
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        await asyncio.sleep(0.2)
+
+        response = await client.get(f"/api/plot/{job_id}/cluster/99")
+
+    assert response.status_code == status.HTTP_404_NOT_FOUND
+
+
+@pytest.mark.asyncio
+async def test_cluster_detail_invalid_job(
+    app: FastAPI,
+) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.get("/api/plot/nonexistent/cluster/0")
+
+    assert response.status_code == status.HTTP_404_NOT_FOUND
+
+
+@pytest.mark.asyncio
+async def test_cluster_detail_job_not_ready(
+    app: FastAPI, mock_compute_internals: None
+) -> None:
+    _ = mock_compute_internals
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        # Don't wait - query immediately
+        response = await client.get(f"/api/plot/{job_id}/cluster/0")
+
+    # Should get 409 or 200 depending on timing
+    assert response.status_code in (
+        status.HTTP_409_CONFLICT,
+        status.HTTP_200_OK,
+    )
diff --git a/tests/test_sub_cluster.py b/tests/test_sub_cluster.py
new file mode 100644
index 0000000..2f29131
--- /dev/null
+++ b/tests/test_sub_cluster.py
@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, cast
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+from fastapi import status
+from httpx import ASGITransport, AsyncClient
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from fastapi import FastAPI
+
+from embedding_cluster.server.app import create_app
+
+
+@pytest.fixture
+def app() -> FastAPI:
+    return create_app()
+
+
+def _fake_compute_for_subcluster(
+    _settings: object,
+) -> dict[str, object]:
+    """Fake compute with enough points per cluster."""
+    rng = np.random.default_rng(42)
+    n_per_cluster = 20
+    emb_dim = 10
+    cluster0_emb = rng.normal(0, 1, (n_per_cluster, emb_dim))
+    cluster1_emb = rng.normal(5, 1, (n_per_cluster, emb_dim))
+    all_emb = np.vstack([cluster0_emb, cluster1_emb])
+
+    points = []
+    labels = []
+    ids = []
+    for i in range(n_per_cluster * 2):
+        cluster = 0 if i < n_per_cluster else 1
+        points.append(
+            {
+                "x": float(i),
+                "y": float(i),
+                "z": float(i),
+                "cluster": cluster,
+                "metadata": {"name": f"item{i}"},
+                "id": str(i),
+            }
+        )
+        labels.append(cluster)
+        ids.append(str(i))
+
+    return {
+        "points": points,
+        "clusters": [
+            {
+                "index": 0,
+                "name": "Group 1",
+                "color": "hsl(0, 70%, 50%)",
+                "count": n_per_cluster,
+            },
+            {
+                "index": 1,
+                "name": "Group 2",
+                "color": "hsl(180, 70%, 50%)",
+                "count": n_per_cluster,
+            },
+        ],
+        "total_points": n_per_cluster * 2,
+        "embeddings_standardized": all_emb.tolist(),
+        "cluster_labels": labels,
+        "point_ids": ids,
+    }
+
+
+@pytest.fixture
+def mock_compute_subcluster() -> Iterator[None]:
+    with patch(
+        "embedding_cluster.server.routes.plot.compute_plot_data",
+        side_effect=_fake_compute_for_subcluster,
+    ):
+        yield
+
+
+@pytest.mark.asyncio
+async def test_sub_cluster_success(app: FastAPI, mock_compute_subcluster: None) -> None:
+    _ = mock_compute_subcluster
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        await asyncio.sleep(0.2)
+
+        response = await client.post(
+            f"/api/plot/{job_id}/cluster/0/sub-cluster",
+            json={"num_sub_clusters": 3},
+        )
+
+    assert response.status_code == status.HTTP_200_OK
+    data = response.json()
+    assert data["parent_cluster_index"] == 0
+    assert data["total_points"] == 20
+    assert len(data["sub_clusters"]) == 3
+    assert len(data["points"]) == 20
+    # Each point has sub_cluster assignment
+    for point in data["points"]:
+        assert "sub_cluster" in point
+        assert 0 <= point["sub_cluster"] < 3
+
+
+@pytest.mark.asyncio
+async def test_sub_cluster_invalid_cluster(
+    app: FastAPI, mock_compute_subcluster: None
+) -> None:
+    _ = mock_compute_subcluster
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        await asyncio.sleep(0.2)
+
+        response = await client.post(
+            f"/api/plot/{job_id}/cluster/99/sub-cluster",
+            json={"num_sub_clusters": 3},
+        )
+
+    assert response.status_code == status.HTTP_404_NOT_FOUND
+
+
+@pytest.mark.asyncio
+async def test_sub_cluster_too_few_points(
+    app: FastAPI, mock_compute_subcluster: None
+) -> None:
+    """When num_sub_clusters > num_items, return 400."""
+    _ = mock_compute_subcluster
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        start = await client.post(
+            "/api/plot/compute",
+            json={"chromadb_collection_name": "test"},
+        )
+        job_id = cast("str", start.json()["job_id"])
+        await asyncio.sleep(0.2)
+
+        response = await client.post(
+            f"/api/plot/{job_id}/cluster/0/sub-cluster",
+            json={"num_sub_clusters": 100},
+        )
+
+    assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+
+@pytest.mark.asyncio
+async def test_sub_cluster_invalid_job(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.post(
+            "/api/plot/nonexistent/cluster/0/sub-cluster",
+            json={"num_sub_clusters": 3},
+        )
+
+    assert response.status_code == status.HTTP_404_NOT_FOUND
+
+
+@pytest.mark.asyncio
+async def test_sub_cluster_validation_min(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.post(
+            "/api/plot/somejob/cluster/0/sub-cluster",
+            json={"num_sub_clusters": 1},
+        )
+
+    assert response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY

From 14bc14a2bac5e3409a0ce904ae832762222db920 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 13:55:53 +0200
Subject: [PATCH 05/16] feat(api): add annotation CRUD endpoints and gitignore
 annotations dir

---
 .gitignore                                    |   1 +
 embedding_cluster/server/app.py               |   4 +
 .../server/routes/annotations.py              |  57 +++++++++
 tests/test_server_annotations.py              | 111 ++++++++++++++++++
 4 files changed, 173 insertions(+)
 create mode 100644 embedding_cluster/server/routes/annotations.py
 create mode 100644 tests/test_server_annotations.py

diff --git a/.gitignore b/.gitignore
index 86be558..96b7c89 100644
--- a/.gitignore
+++ b/.gitignore
@@ -161,5 +161,6 @@ cython_debug/
 #.idea/
 
 chromadb
+annotations/
 
 .worktrees/
diff --git a/embedding_cluster/server/app.py b/embedding_cluster/server/app.py
index 937c0c4..7a352da 100644
--- a/embedding_cluster/server/app.py
+++ b/embedding_cluster/server/app.py
@@ -8,6 +8,9 @@
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
+from embedding_cluster.server.routes.annotations import (
+    router as annotations_router,
+)
 from embedding_cluster.server.routes.collections import (
     router as collections_router,
 )
@@ -44,6 +47,7 @@ async def health_check() -> dict[str, str]:
     app.include_router(csv_router)
     app.include_router(index_router)
     app.include_router(plot_router)
+    app.include_router(annotations_router)
     app.include_router(search_router)
 
     if FRONTEND_DIR.is_dir():
diff --git a/embedding_cluster/server/routes/annotations.py b/embedding_cluster/server/routes/annotations.py
new file mode 100644
index 0000000..c6e17ad
--- /dev/null
+++ b/embedding_cluster/server/routes/annotations.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter
+
+from embedding_cluster.annotations import AnnotationManager
+from embedding_cluster.server.models import (
+    AnnotationsResponse,
+    AnnotationUpdate,
+    MessageResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_ANNOTATIONS_DIR = Path("./annotations")
+
+router = APIRouter(prefix="/api/annotations", tags=["annotations"])
+
+
+def _get_manager() -> AnnotationManager:
+    return AnnotationManager(base_dir=_DEFAULT_ANNOTATIONS_DIR)
+
+
+@router.get("/{job_id}", response_model=AnnotationsResponse)
+async def get_annotations(job_id: str) -> AnnotationsResponse:
+    manager = _get_manager()
+    data = manager.get_annotations(job_id)
+    return AnnotationsResponse(**data)
+
+
+@router.put(
+    "/{job_id}/cluster/{cluster_index}",
+    response_model=AnnotationsResponse,
+)
+async def update_annotation(
+    job_id: str,
+    cluster_index: int,
+    body: AnnotationUpdate,
+) -> AnnotationsResponse:
+    manager = _get_manager()
+    data = manager.update_annotation(
+        job_id,
+        cluster_index,
+        name=body.name,
+        notes=body.notes,
+        tags=body.tags,
+    )
+    return AnnotationsResponse(**data)
+
+
+@router.delete("/{job_id}", response_model=MessageResponse)
+async def delete_annotations(job_id: str) -> MessageResponse:
+    manager = _get_manager()
+    manager.delete_annotations(job_id)
+    return MessageResponse(message="Annotations deleted")
diff --git a/tests/test_server_annotations.py b/tests/test_server_annotations.py
new file mode 100644
index 0000000..43e79f0
--- /dev/null
+++ b/tests/test_server_annotations.py
@@ -0,0 +1,111 @@
+# tests/test_server_annotations.py
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import patch
+
+import pytest
+from fastapi import status
+from httpx import ASGITransport, AsyncClient
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from fastapi import FastAPI
+
+from embedding_cluster.server.app import create_app
+
+
+@pytest.fixture
+def app(tmp_path: Path) -> Iterator[FastAPI]:
+    with patch(
+        "embedding_cluster.server.routes.annotations._DEFAULT_ANNOTATIONS_DIR",
+        tmp_path / "annotations",
+    ):
+        yield create_app()
+
+
+@pytest.mark.asyncio
+async def test_get_annotations_empty(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.get("/api/annotations/somejob")
+
+    assert response.status_code == status.HTTP_200_OK
+    data = response.json()
+    assert data["job_id"] == "somejob"
+    assert data["clusters"] == {}
+
+
+@pytest.mark.asyncio
+async def test_update_annotation(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.put(
+            "/api/annotations/somejob/cluster/0",
+            json={"name": "Shoes", "notes": "Athletic shoes"},
+        )
+
+    assert response.status_code == status.HTTP_200_OK
+    data = response.json()
+    assert data["clusters"]["0"]["name"] == "Shoes"
+    assert data["clusters"]["0"]["notes"] == "Athletic shoes"
+
+
+@pytest.mark.asyncio
+async def test_update_partial_annotation(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        await client.put(
+            "/api/annotations/somejob/cluster/0",
+            json={"name": "Shoes"},
+        )
+        response = await client.put(
+            "/api/annotations/somejob/cluster/0",
+            json={"notes": "Running shoes"},
+        )
+
+    data = response.json()
+    assert data["clusters"]["0"]["name"] == "Shoes"
+    assert data["clusters"]["0"]["notes"] == "Running shoes"
+
+
+@pytest.mark.asyncio
+async def test_delete_annotations(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        await client.put(
+            "/api/annotations/somejob/cluster/0",
+            json={"name": "Shoes"},
+        )
+        response = await client.delete("/api/annotations/somejob")
+
+    assert response.status_code == status.HTTP_200_OK
+
+    # Verify empty after delete
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.get("/api/annotations/somejob")
+
+    data = response.json()
+    assert data["clusters"] == {}
+
+
+@pytest.mark.asyncio
+async def test_annotation_with_tags(app: FastAPI) -> None:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.put(
+            "/api/annotations/somejob/cluster/0",
+            json={"tags": ["footwear", "sport"]},
+        )
+
+    data = response.json()
+    assert data["clusters"]["0"]["tags"] == ["footwear", "sport"]

From 96f2a2d1856eae40018331d9fc3caa0464ea5dc8 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 14:28:14 +0200
Subject: [PATCH 06/16] feat(frontend): add cluster drill-down types and API
 functions

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 frontend/src/api/plot.ts    | 67 ++++++++++++++++++++++++++++++++++++-
 frontend/src/types/index.ts | 62 ++++++++++++++++++++++++++++++++++
 2 files changed, 128 insertions(+), 1 deletion(-)

diff --git a/frontend/src/api/plot.ts b/frontend/src/api/plot.ts
index da9de6e..d24a44a 100644
--- a/frontend/src/api/plot.ts
+++ b/frontend/src/api/plot.ts
@@ -1,4 +1,18 @@
-import type { IndexStartResponse, PlotRequest, PlotResponse, SearchRequest, SearchResponse, SuggestClustersRequest, SuggestClustersStatusResponse } from "../types";
+import type {
+  AnnotationUpdate,
+  AnnotationsResponse,
+  ClusterDetailResponse,
+  IndexStartResponse,
+  MessageResponse,
+  PlotRequest,
+  PlotResponse,
+  SearchRequest,
+  SearchResponse,
+  SubClusterRequest,
+  SubClusterResponse,
+  SuggestClustersRequest,
+  SuggestClustersStatusResponse,
+} from "../types";
 import { apiFetch, apiPost } from "./client";
 
 export async function startPlotCompute(
@@ -34,3 +48,54 @@ export async function getSuggestClustersStatus(
     `/plot/suggest-clusters/${jobId}`,
   );
 }
+
+export async function getClusterDetail(
+  jobId: string,
+  clusterIndex: number,
+  page = 1,
+  pageSize = 50,
+): Promise<ClusterDetailResponse> {
+  return apiFetch<ClusterDetailResponse>(
+    `/plot/${jobId}/cluster/${clusterIndex}?page=${page}&page_size=${pageSize}`,
+  );
+}
+
+export async function subCluster(
+  jobId: string,
+  clusterIndex: number,
+  request: SubClusterRequest,
+): Promise<SubClusterResponse> {
+  return apiPost<SubClusterResponse>(
+    `/plot/${jobId}/cluster/${clusterIndex}/sub-cluster`,
+    request,
+  );
+}
+
+export async function getAnnotations(
+  jobId: string,
+): Promise<AnnotationsResponse> {
+  return apiFetch<AnnotationsResponse>(`/annotations/${jobId}`);
+}
+
+export async function updateAnnotation(
+  jobId: string,
+  clusterIndex: number,
+  body: AnnotationUpdate,
+): Promise<AnnotationsResponse> {
+  return apiFetch<AnnotationsResponse>(
+    `/annotations/${jobId}/cluster/${clusterIndex}`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+  );
+}
+
+export async function deleteAnnotations(
+  jobId: string,
+): Promise<MessageResponse> {
+  return apiFetch<MessageResponse>(`/annotations/${jobId}`, {
+    method: "DELETE",
+  });
+}
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index a1839ab..2aee66c 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -147,3 +147,65 @@ export interface SearchRequest {
 export interface SearchResponse {
   results: SearchResult[];
 }
+
+// Cluster Detail
+export interface ClusterItemResponse {
+  id: string;
+  metadata: Record<string, unknown>;
+  distance_to_centroid: number;
+}
+
+export interface ClusterDetailResponse {
+  cluster_index: number;
+  cluster_name: string;
+  total_items: number;
+  page: number;
+  page_size: number;
+  items: ClusterItemResponse[];
+}
+
+// Sub-Cluster
+export interface SubClusterRequest {
+  num_sub_clusters: number;
+}
+
+export interface SubClusterPoint {
+  id: string;
+  x: number;
+  y: number;
+  z: number;
+  sub_cluster: number;
+  metadata: Record<string, unknown>;
+}
+
+export interface SubClusterInfo {
+  index: number;
+  count: number;
+  color: string;
+}
+
+export interface SubClusterResponse {
+  parent_cluster_index: number;
+  points: SubClusterPoint[];
+  sub_clusters: SubClusterInfo[];
+  total_points: number;
+}
+
+// Annotations
+export interface AnnotationUpdate {
+  name?: string;
+  notes?: string;
+  tags?: string[];
+}
+
+export interface ClusterAnnotation {
+  name?: string;
+  notes?: string;
+  tags?: string[];
+  updated_at?: string;
+}
+
+export interface AnnotationsResponse {
+  job_id: string;
+  clusters: Record<string, ClusterAnnotation>;
+}

From a4251936e104c6fda37bb220b302e8874d24e7b8 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 14:28:26 +0200
Subject: [PATCH 07/16] feat(frontend): add cluster detail drawer and
 sub-cluster view

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 .../components/plot/ClusterDetailDrawer.tsx   | 280 ++++++++++++++++++
 .../src/components/plot/SubClusterView.tsx    | 110 +++++++
 2 files changed, 390 insertions(+)
 create mode 100644 frontend/src/components/plot/ClusterDetailDrawer.tsx
 create mode 100644 frontend/src/components/plot/SubClusterView.tsx

diff --git a/frontend/src/components/plot/ClusterDetailDrawer.tsx b/frontend/src/components/plot/ClusterDetailDrawer.tsx
new file mode 100644
index 0000000..4453d18
--- /dev/null
+++ b/frontend/src/components/plot/ClusterDetailDrawer.tsx
@@ -0,0 +1,280 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { usePlotStore, CLUSTER_COLORS } from '../../stores/plotStore'
+import { getClusterDetail, updateAnnotation, getAnnotations } from '../../api/plot'
+import type { ClusterDetailResponse } from '../../types'
+import SubClusterView from './SubClusterView'
+
+interface ClusterDetailDrawerProps {
+  jobId: string
+  imageField?: string
+}
+
+export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetailDrawerProps) {
+  const selectedCluster = usePlotStore((s) => s.selectedCluster)
+  const clusterDetail = usePlotStore((s) => s.clusterDetail)
+  const annotations = usePlotStore((s) => s.annotations)
+  const isLoadingClusterDetail = usePlotStore((s) => s.isLoadingClusterDetail)
+  const plotData = usePlotStore((s) => s.plotData)
+  const setClusterDetail = usePlotStore((s) => s.setClusterDetail)
+  const setAnnotations = usePlotStore((s) => s.setAnnotations)
+  const setIsLoadingClusterDetail = usePlotStore((s) => s.setIsLoadingClusterDetail)
+  const setHighlightedIds = usePlotStore((s) => s.setHighlightedIds)
+  const clearClusterDrillDown = usePlotStore((s) => s.clearClusterDrillDown)
+
+  const [page, setPage] = useState(1)
+  const [isEditingName, setIsEditingName] = useState(false)
+  const [editName, setEditName] = useState('')
+  const [notes, setNotes] = useState('')
+  const [tagsInput, setTagsInput] = useState('')
+  const [showSubCluster, setShowSubCluster] = useState(false)
+  const notesTimeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined)
+  const tagsTimeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  const clusterIndex = selectedCluster
+  const cluster = plotData?.clusters.find((c) => c.index === clusterIndex)
+  const color = clusterIndex != null ? CLUSTER_COLORS[clusterIndex % CLUSTER_COLORS.length] : '#999'
+  const annotation = clusterIndex != null ? annotations?.clusters[String(clusterIndex)] : undefined
+
+  // Load cluster detail when selected cluster changes
+  useEffect(() => {
+    if (clusterIndex == null) return
+    setPage(1)
+    setShowSubCluster(false)
+    setIsLoadingClusterDetail(true)
+    setClusterDetail(null)
+
+    getClusterDetail(jobId, clusterIndex, 1)
+      .then((data: ClusterDetailResponse) => setClusterDetail(data))
+      .catch(() => setClusterDetail(null))
+      .finally(() => setIsLoadingClusterDetail(false))
+  }, [jobId, clusterIndex, setClusterDetail, setIsLoadingClusterDetail])
+
+  // Load annotations
+  useEffect(() => {
+    getAnnotations(jobId)
+      .then(setAnnotations)
+      .catch(() => setAnnotations(null))
+  }, [jobId, setAnnotations])
+
+  // Sync local notes/tags state with annotation
+  useEffect(() => {
+    setNotes(annotation?.notes ?? '')
+    setTagsInput(annotation?.tags?.join(', ') ?? '')
+  }, [annotation])
+
+  const handlePageChange = useCallback((newPage: number) => {
+    if (clusterIndex == null) return
+    setPage(newPage)
+    setIsLoadingClusterDetail(true)
+    getClusterDetail(jobId, clusterIndex, newPage)
+      .then((data: ClusterDetailResponse) => setClusterDetail(data))
+      .catch(() => {/* keep previous data */})
+      .finally(() => setIsLoadingClusterDetail(false))
+  }, [jobId, clusterIndex, setClusterDetail, setIsLoadingClusterDetail])
+
+  const handleSaveName = useCallback(() => {
+    if (clusterIndex == null) return
+    setIsEditingName(false)
+    if (editName.trim()) {
+      updateAnnotation(jobId, clusterIndex, { name: editName.trim() })
+        .then(setAnnotations)
+        .catch(() => {/* silent */})
+    }
+  }, [jobId, clusterIndex, editName, setAnnotations])
+
+  const handleNotesChange = useCallback((value: string) => {
+    setNotes(value)
+    if (notesTimeoutRef.current) clearTimeout(notesTimeoutRef.current)
+    notesTimeoutRef.current = setTimeout(() => {
+      if (clusterIndex != null) {
+        updateAnnotation(jobId, clusterIndex, { notes: value })
+          .then(setAnnotations)
+          .catch(() => {/* silent */})
+      }
+    }, 800)
+  }, [jobId, clusterIndex, setAnnotations])
+
+  const handleTagsChange = useCallback((value: string) => {
+    setTagsInput(value)
+    if (tagsTimeoutRef.current) clearTimeout(tagsTimeoutRef.current)
+    tagsTimeoutRef.current = setTimeout(() => {
+      if (clusterIndex != null) {
+        const tags = value.split(',').map((t) => t.trim()).filter(Boolean)
+        updateAnnotation(jobId, clusterIndex, { tags })
+          .then(setAnnotations)
+          .catch(() => {/* silent */})
+      }
+    }, 800)
+  }, [jobId, clusterIndex, setAnnotations])
+
+  const handleItemClick = useCallback((id: string) => {
+    setHighlightedIds(new Set([id]))
+  }, [setHighlightedIds])
+
+  if (clusterIndex == null) return null
+
+  const totalPages = clusterDetail ? Math.ceil(clusterDetail.total_items / clusterDetail.page_size) : 0
+  const displayName = annotation?.name ?? cluster?.name ?? `Cluster ${clusterIndex}`
+
+  return (
+    <div className="w-96 bg-white border-l border-gray-200 flex flex-col h-full shadow-lg overflow-hidden">
+      {/* Header */}
+      <div className="px-4 py-3 border-b border-gray-200 flex items-center justify-between shrink-0">
+        <div className="flex items-center space-x-2 min-w-0">
+          <span className="w-3 h-3 rounded-full shrink-0" style={{ backgroundColor: color }} />
+          {isEditingName ? (
+            <input
+              type="text"
+              value={editName}
+              onChange={(e) => setEditName(e.target.value)}
+              onBlur={handleSaveName}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') handleSaveName()
+                if (e.key === 'Escape') setIsEditingName(false)
+              }}
+              className="text-sm font-bold text-gray-900 border-b border-blue-500 outline-none bg-transparent w-full"
+              autoFocus
+            />
+          ) : (
+            <button
+              onClick={() => { setEditName(displayName); setIsEditingName(true) }}
+              className="text-sm font-bold text-gray-900 truncate hover:text-blue-600 transition-colors text-left"
+              title="Click to rename"
+            >
+              {displayName}
+            </button>
+          )}
+          {clusterDetail && (
+            <span className="text-xs text-gray-500 shrink-0">
+              ({clusterDetail.total_items} items)
+            </span>
+          )}
+        </div>
+        <button
+          onClick={clearClusterDrillDown}
+          className="p-1 hover:bg-gray-100 rounded transition-colors shrink-0"
+          aria-label="Close drawer"
+        >
+          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <line x1="18" y1="6" x2="6" y2="18" />
+            <line x1="6" y1="6" x2="18" y2="18" />
+          </svg>
+        </button>
+      </div>
+
+      {/* Sub-cluster toggle */}
+      <div className="px-4 py-2 border-b border-gray-200 flex items-center space-x-2 shrink-0">
+        <button
+          onClick={() => setShowSubCluster(!showSubCluster)}
+          className={`text-xs px-3 py-1 rounded border transition-colors ${
+            showSubCluster
+              ? 'bg-blue-50 border-blue-300 text-blue-700'
+              : 'border-gray-300 text-gray-600 hover:bg-gray-50'
+          }`}
+        >
+          Sub-Cluster
+        </button>
+      </div>
+
+      {/* Sub-cluster view */}
+      {showSubCluster && (
+        <div className="border-b border-gray-200 shrink-0">
+          <SubClusterView jobId={jobId} clusterIndex={clusterIndex} />
+        </div>
+      )}
+
+      {/* Items list */}
+      <div className="flex-1 overflow-y-auto">
+        {isLoadingClusterDetail && (
+          <div className="flex items-center justify-center py-8">
+            <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-blue-600" />
+          </div>
+        )}
+
+        {clusterDetail && !isLoadingClusterDetail && (
+          <div className="divide-y divide-gray-100">
+            {clusterDetail.items.map((item) => (
+              <button
+                key={item.id}
+                onClick={() => handleItemClick(item.id)}
+                className="w-full px-4 py-2 text-left hover:bg-blue-50 transition-colors flex items-center space-x-3"
+              >
+                {imageField && imageField in item.metadata && (
+                  <img
+                    src={String(item.metadata[imageField])}
+                    alt=""
+                    className="w-10 h-10 rounded object-cover shrink-0"
+                    loading="lazy"
+                  />
+                )}
+                <div className="min-w-0 flex-1">
+                  <div className="text-xs font-medium text-gray-900 truncate">
+                    {item.id}
+                  </div>
+                  <div className="text-[10px] text-gray-500">
+                    dist: {item.distance_to_centroid.toFixed(4)}
+                  </div>
+                  {Object.entries(item.metadata)
+                    .filter(([k]) => k !== imageField)
+                    .slice(0, 2)
+                    .map(([key, value]) => (
+                      <div key={key} className="text-[10px] text-gray-400 truncate">
+                        {key}: {String(value)}
+                      </div>
+                    ))}
+                </div>
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Pagination */}
+      {totalPages > 1 && (
+        <div className="px-4 py-2 border-t border-gray-200 flex items-center justify-between text-xs shrink-0">
+          <button
+            onClick={() => handlePageChange(page - 1)}
+            disabled={page <= 1}
+            className="px-2 py-1 rounded border border-gray-300 disabled:opacity-30 hover:bg-gray-50"
+          >
+            Prev
+          </button>
+          <span className="text-gray-500">
+            Page {page} / {totalPages}
+          </span>
+          <button
+            onClick={() => handlePageChange(page + 1)}
+            disabled={page >= totalPages}
+            className="px-2 py-1 rounded border border-gray-300 disabled:opacity-30 hover:bg-gray-50"
+          >
+            Next
+          </button>
+        </div>
+      )}
+
+      {/* Annotation section */}
+      <div className="px-4 py-3 border-t border-gray-200 space-y-2 shrink-0">
+        <div>
+          <label className="text-[10px] font-medium text-gray-500 uppercase tracking-wider">Notes</label>
+          <textarea
+            value={notes}
+            onChange={(e) => handleNotesChange(e.target.value)}
+            placeholder="Add notes about this cluster..."
+            className="w-full mt-1 text-xs border border-gray-200 rounded px-2 py-1.5 resize-none focus:outline-none focus:ring-1 focus:ring-blue-400"
+            rows={2}
+          />
+        </div>
+        <div>
+          <label className="text-[10px] font-medium text-gray-500 uppercase tracking-wider">Tags</label>
+          <input
+            type="text"
+            value={tagsInput}
+            onChange={(e) => handleTagsChange(e.target.value)}
+            placeholder="tag1, tag2, ..."
+            className="w-full mt-1 text-xs border border-gray-200 rounded px-2 py-1.5 focus:outline-none focus:ring-1 focus:ring-blue-400"
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/frontend/src/components/plot/SubClusterView.tsx b/frontend/src/components/plot/SubClusterView.tsx
new file mode 100644
index 0000000..1fae164
--- /dev/null
+++ b/frontend/src/components/plot/SubClusterView.tsx
@@ -0,0 +1,110 @@
+import { useState, useCallback, useMemo } from 'react'
+import { Canvas } from '@react-three/fiber'
+import { OrbitControls } from '@react-three/drei'
+import { usePlotStore, CLUSTER_COLORS } from '../../stores/plotStore'
+import { subCluster } from '../../api/plot'
+import type { SubClusterResponse } from '../../types'
+import * as THREE from 'three'
+
+interface SubClusterViewProps {
+  jobId: string
+  clusterIndex: number
+}
+
+function SubClusterPoints({ data }: { data: SubClusterResponse }) {
+  const geometry = useMemo(() => {
+    const positions = new Float32Array(data.points.length * 3)
+    const colors = new Float32Array(data.points.length * 3)
+
+    for (let i = 0; i < data.points.length; i++) {
+      const p = data.points[i]
+      positions[i * 3] = p.x
+      positions[i * 3 + 1] = p.y
+      positions[i * 3 + 2] = p.z
+
+      const hex = CLUSTER_COLORS[p.sub_cluster % CLUSTER_COLORS.length]
+      const color = new THREE.Color(hex)
+      colors[i * 3] = color.r
+      colors[i * 3 + 1] = color.g
+      colors[i * 3 + 2] = color.b
+    }
+
+    const geo = new THREE.BufferGeometry()
+    geo.setAttribute('position', new THREE.BufferAttribute(positions, 3))
+    geo.setAttribute('color', new THREE.BufferAttribute(colors, 3))
+    return geo
+  }, [data])
+
+  return (
+    <points geometry={geometry}>
+      <pointsMaterial size={4} vertexColors sizeAttenuation={false} />
+    </points>
+  )
+}
+
+export default function SubClusterView({ jobId, clusterIndex }: SubClusterViewProps) {
+  const [numSubClusters, setNumSubClusters] = useState(3)
+  const subClusterData = usePlotStore((s) => s.subClusterData)
+  const isLoadingSubCluster = usePlotStore((s) => s.isLoadingSubCluster)
+  const setSubClusterData = usePlotStore((s) => s.setSubClusterData)
+  const setIsLoadingSubCluster = usePlotStore((s) => s.setIsLoadingSubCluster)
+
+  const handleCompute = useCallback(() => {
+    setIsLoadingSubCluster(true)
+    setSubClusterData(null)
+    subCluster(jobId, clusterIndex, { num_sub_clusters: numSubClusters })
+      .then((data: SubClusterResponse) => setSubClusterData(data))
+      .catch(() => setSubClusterData(null))
+      .finally(() => setIsLoadingSubCluster(false))
+  }, [jobId, clusterIndex, numSubClusters, setSubClusterData, setIsLoadingSubCluster])
+
+  return (
+    <div className="p-3">
+      <div className="flex items-center space-x-2 mb-2">
+        <label className="text-xs text-gray-600">Sub-clusters:</label>
+        <input
+          type="number"
+          min={2}
+          max={20}
+          value={numSubClusters}
+          onChange={(e) => setNumSubClusters(Math.max(2, Number(e.target.value)))}
+          className="w-14 text-xs border border-gray-200 rounded px-1.5 py-1 focus:outline-none focus:ring-1 focus:ring-blue-400"
+        />
+        <button
+          onClick={handleCompute}
+          disabled={isLoadingSubCluster}
+          className="text-xs px-3 py-1 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50 transition-colors"
+        >
+          {isLoadingSubCluster ? 'Computing...' : 'Compute'}
+        </button>
+      </div>
+
+      {subClusterData && (
+        <>
+          <div className="h-48 bg-gray-900 rounded-lg overflow-hidden">
+            <Canvas camera={{ position: [0, 0, 15], fov: 60 }}>
+              <color attach="background" args={['#111827']} />
+              <ambientLight intensity={0.6} />
+              <OrbitControls />
+              <SubClusterPoints data={subClusterData} />
+            </Canvas>
+          </div>
+          <div className="flex flex-wrap gap-1 mt-2">
+            {subClusterData.sub_clusters.map((sc) => (
+              <span
+                key={sc.index}
+                className="inline-flex items-center space-x-1 text-[10px] text-gray-600 px-1.5 py-0.5 bg-gray-100 rounded"
+              >
+                <span
+                  className="w-2 h-2 rounded-full inline-block"
+                  style={{ backgroundColor: sc.color }}
+                />
+                <span>{sc.count} pts</span>
+              </span>
+            ))}
+          </div>
+        </>
+      )}
+    </div>
+  )
+}

From fa553616eb7b7c3d72eab24ae792e1644eb9c6c5 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 14:28:32 +0200
Subject: [PATCH 08/16] feat(frontend): add drill-down state to plot store

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 frontend/src/components/plot/PlotControls.tsx |  6 +++
 frontend/src/stores/plotStore.ts              | 38 ++++++++++++++++++-
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/frontend/src/components/plot/PlotControls.tsx b/frontend/src/components/plot/PlotControls.tsx
index e266b37..62d564f 100644
--- a/frontend/src/components/plot/PlotControls.tsx
+++ b/frontend/src/components/plot/PlotControls.tsx
@@ -48,6 +48,7 @@ export default function PlotControls({ onCompute, isComputing }: PlotControlsPro
     umapNNeighbors, setUmapNNeighbors,
     umapMinDist, setUmapMinDist,
     umapMetric, setUmapMetric,
+    setImageField: setStoreImageField,
   } = usePlotStore()
 
   // 1. Fetch collection list
@@ -77,6 +78,11 @@ export default function PlotControls({ onCompute, isComputing }: PlotControlsPro
     }
   }, [collectionDetails])
 
+  // Sync local imageField to store for drawer access
+  useEffect(() => {
+    setStoreImageField(imageField || null)
+  }, [imageField, setStoreImageField])
+
   const handleCompute = () => {
     if (!selectedCollection) return
 
diff --git a/frontend/src/stores/plotStore.ts b/frontend/src/stores/plotStore.ts
index 157cc9a..09e86ef 100644
--- a/frontend/src/stores/plotStore.ts
+++ b/frontend/src/stores/plotStore.ts
@@ -1,5 +1,5 @@
 import { create } from 'zustand'
-import type { PlotResponse, ReductionAlgorithm, SearchResult } from '../types'
+import type { AnnotationsResponse, ClusterDetailResponse, PlotResponse, ReductionAlgorithm, SearchResult, SubClusterResponse } from '../types'
 
 interface PlotState {
   plotData: PlotResponse | null
@@ -17,6 +17,13 @@ interface PlotState {
   umapNNeighbors: number
   umapMinDist: number
   umapMetric: string
+  selectedCluster: number | null
+  clusterDetail: ClusterDetailResponse | null
+  subClusterData: SubClusterResponse | null
+  annotations: AnnotationsResponse | null
+  isLoadingClusterDetail: boolean
+  isLoadingSubCluster: boolean
+  imageField: string | null
   // actions
   setPlotData: (data: PlotResponse | null) => void
   toggleCluster: (index: number) => void
@@ -35,6 +42,14 @@ interface PlotState {
   setUmapNNeighbors: (n: number) => void
   setUmapMinDist: (dist: number) => void
   setUmapMetric: (metric: string) => void
+  setSelectedCluster: (index: number | null) => void
+  setClusterDetail: (detail: ClusterDetailResponse | null) => void
+  setSubClusterData: (data: SubClusterResponse | null) => void
+  setAnnotations: (annotations: AnnotationsResponse | null) => void
+  setIsLoadingClusterDetail: (loading: boolean) => void
+  setIsLoadingSubCluster: (loading: boolean) => void
+  clearClusterDrillDown: () => void
+  setImageField: (field: string | null) => void
 }
 
 export const CLUSTER_COLORS = [
@@ -60,6 +75,13 @@ export const usePlotStore = create<PlotState>((set) => ({
   umapNNeighbors: 15,
   umapMinDist: 0.1,
   umapMetric: 'cosine',
+  selectedCluster: null,
+  clusterDetail: null,
+  subClusterData: null,
+  annotations: null,
+  isLoadingClusterDetail: false,
+  isLoadingSubCluster: false,
+  imageField: null,
 
   setPlotData: (data) => set({ plotData: data }),
 
@@ -104,4 +126,18 @@ export const usePlotStore = create<PlotState>((set) => ({
   setUmapNNeighbors: (n) => set({ umapNNeighbors: n }),
   setUmapMinDist: (dist) => set({ umapMinDist: dist }),
   setUmapMetric: (metric) => set({ umapMetric: metric }),
+  setSelectedCluster: (index) => set({ selectedCluster: index }),
+  setClusterDetail: (detail) => set({ clusterDetail: detail }),
+  setSubClusterData: (data) => set({ subClusterData: data }),
+  setAnnotations: (annotations) => set({ annotations }),
+  setIsLoadingClusterDetail: (loading) => set({ isLoadingClusterDetail: loading }),
+  setIsLoadingSubCluster: (loading) => set({ isLoadingSubCluster: loading }),
+  setImageField: (field) => set({ imageField: field }),
+  clearClusterDrillDown: () => set({
+    selectedCluster: null,
+    clusterDetail: null,
+    subClusterData: null,
+    isLoadingClusterDetail: false,
+    isLoadingSubCluster: false,
+  }),
 }))

From 156896234b67dfb93c8be7fa5469de34f9ac881b Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 14:28:40 +0200
Subject: [PATCH 09/16] feat(frontend): integrate cluster drill-down into
 legend and plot page

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 .../src/components/plot/ClusterLegend.tsx     | 78 +++++++++++++++----
 frontend/src/pages/PlotPage.tsx               | 12 ++-
 2 files changed, 74 insertions(+), 16 deletions(-)

diff --git a/frontend/src/components/plot/ClusterLegend.tsx b/frontend/src/components/plot/ClusterLegend.tsx
index a60dfc4..c6d7c7f 100644
--- a/frontend/src/components/plot/ClusterLegend.tsx
+++ b/frontend/src/components/plot/ClusterLegend.tsx
@@ -5,6 +5,9 @@ export default function ClusterLegend() {
   const visibleClusters = usePlotStore((state) => state.visibleClusters)
   const toggleCluster = usePlotStore((state) => state.toggleCluster)
   const resetVisibleClusters = usePlotStore((state) => state.resetVisibleClusters)
+  const setSelectedCluster = usePlotStore((state) => state.setSelectedCluster)
+  const selectedCluster = usePlotStore((state) => state.selectedCluster)
+  const annotations = usePlotStore((state) => state.annotations)
 
   if (!plotData) return null
 
@@ -25,26 +28,71 @@ export default function ClusterLegend() {
         {plotData.clusters.map((cluster) => {
           const isVisible = visibleClusters.has(cluster.index)
           const color = CLUSTER_COLORS[cluster.index % CLUSTER_COLORS.length]
+          const isSelected = selectedCluster === cluster.index
+          const annotation = annotations?.clusters?.[String(cluster.index)]
+          const hasAnnotation = Boolean(
+            annotation?.notes || (annotation?.tags && annotation.tags.length > 0)
+          )
 
           return (
-            <button
+            <div
               key={cluster.index}
-              onClick={() => toggleCluster(cluster.index)}
-              className={`flex items-center space-x-2 px-2 py-1 rounded border ${
-                isVisible ? 'border-gray-300 bg-gray-50' : 'border-gray-200 bg-gray-100 opacity-60'
-              } hover:bg-gray-100 transition-colors`}
+              className={`flex items-center space-x-1 px-2 py-1 rounded border ${
+                isSelected
+                  ? 'border-blue-500 bg-blue-50 ring-1 ring-blue-300'
+                  : isVisible
+                    ? 'border-gray-300 bg-gray-50'
+                    : 'border-gray-200 bg-gray-100 opacity-60'
+              } transition-colors`}
             >
-              <span
-                className="w-3 h-3 rounded-full"
-                style={{ backgroundColor: color }}
-              />
-              <div className="text-xs text-left">
-                <div className={`font-medium ${isVisible ? 'text-gray-900' : 'text-gray-500 line-through'}`}>
-                  {cluster.name}
+              <button
+                onClick={(e) => {
+                  e.stopPropagation()
+                  toggleCluster(cluster.index)
+                }}
+                className="p-0.5 rounded hover:bg-gray-200 transition-colors shrink-0"
+                title={isVisible ? 'Hide cluster' : 'Show cluster'}
+                aria-label={isVisible ? `Hide ${cluster.name}` : `Show ${cluster.name}`}
+              >
+                {isVisible ? (
+                  <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                    <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" />
+                    <circle cx="12" cy="12" r="3" />
+                  </svg>
+                ) : (
+                  <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="text-gray-400">
+                    <path d="M17.94 17.94A10.07 10.07 0 0 1 12 20c-7 0-11-8-11-8a18.45 18.45 0 0 1 5.06-5.94" />
+                    <path d="M9.9 4.24A9.12 9.12 0 0 1 12 4c7 0 11 8 11 8a18.5 18.5 0 0 1-2.16 3.19" />
+                    <line x1="1" y1="1" x2="23" y2="23" />
+                  </svg>
+                )}
+              </button>
+
+              <button
+                onClick={() => setSelectedCluster(
+                  isSelected ? null : cluster.index
+                )}
+                className="flex items-center space-x-2 hover:bg-gray-100 rounded px-1 py-0.5 transition-colors"
+                title="View cluster details"
+              >
+                <span
+                  className="w-3 h-3 rounded-full shrink-0"
+                  style={{ backgroundColor: color }}
+                />
+                <div className="text-xs text-left">
+                  <div className={`font-medium ${isVisible ? 'text-gray-900' : 'text-gray-500 line-through'}`}>
+                    {annotation?.name || cluster.name}
+                  </div>
+                  <div className="text-gray-500 text-[10px]">{cluster.count} points</div>
                 </div>
-                <div className="text-gray-500 text-[10px]">{cluster.count} points</div>
-              </div>
-            </button>
+                {hasAnnotation && (
+                  <span
+                    className="w-1.5 h-1.5 rounded-full bg-blue-500 shrink-0"
+                    title="Has annotations"
+                  />
+                )}
+              </button>
+            </div>
           )
         })}
       </div>
diff --git a/frontend/src/pages/PlotPage.tsx b/frontend/src/pages/PlotPage.tsx
index 473c90e..ee86084 100644
--- a/frontend/src/pages/PlotPage.tsx
+++ b/frontend/src/pages/PlotPage.tsx
@@ -5,13 +5,16 @@ import ScatterPlot from '../components/plot/ScatterPlot'
 import ClusterLegend from '../components/plot/ClusterLegend'
 import SearchBar from '../components/plot/SearchBar'
 import SearchResults from '../components/plot/SearchResults'
+import ClusterDetailDrawer from '../components/plot/ClusterDetailDrawer'
 
 import { usePlotData } from '../hooks/usePlotData'
 import { usePlotStore } from '../stores/plotStore'
 
 export default function PlotPage() {
-  const { compute, isComputing, error } = usePlotData()
+  const { compute, isComputing, error, jobId } = usePlotData()
   const plotData = usePlotStore((state) => state.plotData)
+  const selectedCluster = usePlotStore((state) => state.selectedCluster)
+  const imageField = usePlotStore((state) => state.imageField)
   const plotContainerRef = useRef<HTMLDivElement>(null)
   const [isFullscreen, setIsFullscreen] = useState(false)
   const [searchParams] = useSearchParams()
@@ -100,6 +103,13 @@ export default function PlotPage() {
                     </svg>
                   )}
                 </button>
+
+                {selectedCluster !== null && jobId && (
+                  <ClusterDetailDrawer
+                    jobId={jobId}
+                    imageField={imageField ?? undefined}
+                  />
+                )}
               </>
             ) : (
               <div className="h-full flex items-center justify-center text-gray-400 border-2 border-dashed border-gray-300 rounded-lg">

From 39fc08ba32c0e9a19009629ef78dc6a6e98cc26a Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Wed, 4 Mar 2026 14:34:00 +0200
Subject: [PATCH 10/16] docs(readme): document cluster drill-down and
 annotation features

Ultraworked with [Sisyphus](https://github.com/clio-agents/sisyphus)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 10e3656..23661f9 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,44 @@ visualization in a few steps:
    focus on specific groups. Use the optional GPT-powered naming
    to label each cluster automatically.
 
+## Cluster Drill-Down and Annotation
+
+After generating a plot you can inspect, subdivide, and annotate
+individual clusters directly from the web UI.
+
+### Cluster Detail Panel
+
+Click a cluster name in the legend to open a side panel listing every
+item in that cluster. Items are sorted by distance to the centroid so
+the most representative points appear first. The panel supports
+pagination, displays item metadata, and shows image thumbnails when
+an image field is available.
+
+### Sub-Clustering
+
+Inside the detail panel, toggle **Sub-cluster** to re-run k-means
+within a single cluster. The result is rendered as a mini 3D scatter
+plot (PCA-reduced) so you can explore hierarchical structure without
+leaving the page.
+
+### Annotations
+
+Each cluster can be renamed, tagged, and annotated with free-form
+notes. Changes are saved automatically (debounced) and persisted as
+JSON sidecar files in the `annotations/` directory. Annotations
+survive page reloads and are scoped per plot job.
+
+### API Endpoints
+
+The feature exposes the following REST endpoints under `/api`:
+
+- `GET /plot/{job_id}/cluster/{index}` -- paginated cluster detail
+- `POST /plot/{job_id}/cluster/{index}/sub-cluster` -- sub-cluster
+  a single cluster with configurable k
+- `GET /annotations/{job_id}` -- fetch all annotations for a job
+- `PUT /annotations/{job_id}` -- update annotations
+- `DELETE /annotations/{job_id}` -- delete annotations
+
 ```text
 CSV --> Select Fields --> Download Model --> Embed & Store
   --> Configure Plot --> 3D Visualization --> Search & Explore

From 0c3f4ac9e59523ad944c81d74d78865b60c5656e Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Sun, 15 Mar 2026 19:10:14 +0200
Subject: [PATCH 11/16] fix(plot): stabilize cluster drawer visibility and
 state flow

---
 embedding_cluster/server/routes/plot.py       |   1 +
 frontend/e2e/cluster-drawer.spec.ts           | 214 ++++++++++++++++++
 frontend/e2e/fixtures.ts                      |   2 +-
 frontend/src/App.tsx                          |  38 +++-
 .../components/plot/ClusterDetailDrawer.tsx   |   5 +-
 .../src/components/plot/ClusterLegend.tsx     |  15 +-
 frontend/src/components/plot/PlotControls.tsx |   9 +
 frontend/src/hooks/usePlotData.ts             |  41 ++--
 frontend/src/pages/PlotPage.tsx               | 127 +++++++----
 frontend/src/stores/plotStore.ts              |  16 ++
 frontend/src/types/index.ts                   |   1 +
 11 files changed, 401 insertions(+), 68 deletions(-)
 create mode 100644 frontend/e2e/cluster-drawer.spec.ts

diff --git a/embedding_cluster/server/routes/plot.py b/embedding_cluster/server/routes/plot.py
index 26658f7..ba2c678 100644
--- a/embedding_cluster/server/routes/plot.py
+++ b/embedding_cluster/server/routes/plot.py
@@ -84,6 +84,7 @@ async def get_plot_data(job_id: str) -> dict[str, object]:
     return {
         "status": "completed",
         "ready": True,
+        "job_id": job_id,
         **frontend_result,
     }
 
diff --git a/frontend/e2e/cluster-drawer.spec.ts b/frontend/e2e/cluster-drawer.spec.ts
new file mode 100644
index 0000000..6a4b390
--- /dev/null
+++ b/frontend/e2e/cluster-drawer.spec.ts
@@ -0,0 +1,214 @@
+import { test, expect } from './fixtures'
+
+test.describe('Cluster detail drawer', () => {
+  test('opens drawer when clicking cluster legend item', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByRole('button', { name: /Group 1\s+\d+ points/i })
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    await expect(
+      page.getByRole('button', { name: 'Close drawer' })
+    ).toBeVisible({ timeout: 10_000 })
+  })
+
+  test('opens even when plot data lacks job id', async ({ page, plotPage: _ }) => {
+    await page.route(/.*\/api\/plot\/data\/.*/, async (route) => {
+      const response = await route.fetch()
+      const body = await response.json()
+      if (typeof body === 'object' && body !== null && 'job_id' in body) {
+        delete body.job_id
+      }
+
+      await route.fulfill({
+        status: response.status(),
+        headers: {
+          ...response.headers(),
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      })
+    })
+
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByRole('button', { name: /Group 1\s+\d+ points/i })
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    await expect(
+      page.getByRole('button', { name: 'Close drawer' })
+    ).toBeVisible({ timeout: 10_000 })
+  })
+
+  test('reopens after closing without recompute', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByRole('button', { name: /Group 1\s+\d+ points/i })
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    const closeButton = page.getByRole('button', { name: 'Close drawer' })
+    await expect(closeButton).toBeVisible({ timeout: 10_000 })
+    await closeButton.click()
+
+    await expect(closeButton).toBeHidden({ timeout: 10_000 })
+
+    await firstCluster.click()
+    await expect(closeButton).toBeVisible({ timeout: 10_000 })
+  })
+
+  test('does not require multiple computes to open drawer', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByRole('button', { name: /Group 1\s+\d+ points/i })
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    await expect(
+      page.getByRole('button', { name: 'Close drawer' })
+    ).toBeVisible({ timeout: 10_000 })
+  })
+
+  test('stale plot does not auto-render after visualize', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    await page.getByRole('link', { name: 'Home' }).click()
+    await expect(page.getByRole('link', { name: 'Home' })).toHaveAttribute('aria-current', 'page')
+
+    await page.getByRole('button', { name: 'Visualize' }).first().click()
+    await page.waitForURL('**/plot?collection=*')
+
+    await expect(page.getByRole('heading', { name: 'Clusters' })).toBeHidden({ timeout: 10_000 })
+  })
+
+  test('opens and reopens drawer at 1472x838 viewport', async ({ page, plotPage: _ }) => {
+    await page.setViewportSize({ width: 1472, height: 838 })
+
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByTestId('cluster-legend-name-0')
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+
+    await firstCluster.click()
+    const closeButton = page.getByRole('button', { name: 'Close drawer' })
+    await expect(closeButton).toBeVisible({ timeout: 10_000 })
+
+    await closeButton.click()
+    await expect(closeButton).toBeHidden({ timeout: 10_000 })
+
+    await firstCluster.click()
+    await expect(closeButton).toBeVisible({ timeout: 10_000 })
+    await expect(page.getByTestId('cluster-detail-drawer')).toBeVisible({ timeout: 10_000 })
+  })
+
+  test('group selection shows visible fixed-width drawer at large viewport', async ({ page, plotPage: _ }) => {
+    await page.setViewportSize({ width: 1596, height: 958 })
+
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    await page.getByTestId('cluster-legend-name-3').click()
+
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const drawerWidth = await drawer.evaluate((el) => el.getBoundingClientRect().width)
+    expect(drawerWidth).toBeGreaterThanOrEqual(380)
+
+    const drawerRect = await drawer.evaluate((el) => {
+      const rect = el.getBoundingClientRect()
+      return {
+        x: rect.x,
+        right: rect.right,
+        y: rect.y,
+        bottom: rect.bottom,
+        viewportW: window.innerWidth,
+        viewportH: window.innerHeight,
+      }
+    })
+    expect(drawerRect.x).toBeGreaterThanOrEqual(0)
+    expect(drawerRect.right).toBeLessThanOrEqual(drawerRect.viewportW)
+    expect(drawerRect.y).toBeGreaterThanOrEqual(0)
+    expect(drawerRect.bottom).toBeLessThanOrEqual(drawerRect.viewportH)
+
+    await expect(page.getByRole('button', { name: 'Close drawer' })).toBeVisible({ timeout: 10_000 })
+  })
+
+  test('drawer stays in viewport on narrow layouts', async ({ page, plotPage: _ }) => {
+    await page.setViewportSize({ width: 980, height: 900 })
+
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByTestId('cluster-legend-name-0')
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const drawerRect = await drawer.evaluate((el) => {
+      const rect = el.getBoundingClientRect()
+      return {
+        x: rect.x,
+        right: rect.right,
+        y: rect.y,
+        bottom: rect.bottom,
+        width: rect.width,
+        viewportW: window.innerWidth,
+        viewportH: window.innerHeight,
+      }
+    })
+
+    expect(drawerRect.x).toBeGreaterThanOrEqual(0)
+    expect(drawerRect.right).toBeLessThanOrEqual(drawerRect.viewportW)
+    expect(drawerRect.y).toBeGreaterThanOrEqual(0)
+    expect(drawerRect.bottom).toBeLessThanOrEqual(drawerRect.viewportH)
+    expect(drawerRect.width).toBeGreaterThan(260)
+  })
+
+
+})
diff --git a/frontend/e2e/fixtures.ts b/frontend/e2e/fixtures.ts
index 0d46ab1..2aa10f1 100644
--- a/frontend/e2e/fixtures.ts
+++ b/frontend/e2e/fixtures.ts
@@ -12,7 +12,7 @@ export const test = base.extend<{
 }>({
   plotPage: async ({ page }, use) => {
     // Navigate with collection param so SearchBar renders after compute
-    await page.goto('/plot?collection=fashion_productDisplayName')
+    await page.goto('/plot?collection=fashionimageUrl')
     // Wait for the collection dropdown to be populated with options
     await expect(
       page.locator('select option:not([value=""])').first()
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 493badd..c97f470 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,8 +1,10 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { BrowserRouter, Link, NavLink, Route, Routes } from 'react-router-dom'
+import { QueryClient, QueryClientProvider, useQueryClient } from '@tanstack/react-query'
+import { BrowserRouter, Link, NavLink, Route, Routes, useLocation } from 'react-router-dom'
+import { useEffect, useRef } from 'react'
 import HomePage from './pages/HomePage'
 import IndexPage from './pages/IndexPage'
 import PlotPage from './pages/PlotPage'
+import { usePlotStore } from './stores/plotStore'
 
 const queryClient = new QueryClient()
 
@@ -41,12 +43,44 @@ function NavBar() {
   )
 }
 
+function PlotStateResetter() {
+  const location = useLocation()
+  const setPlotData = usePlotStore((state) => state.setPlotData)
+  const resetPlotJobId = usePlotStore((state) => state.resetPlotJobId)
+  const clearClusterDrillDown = usePlotStore((state) => state.clearClusterDrillDown)
+  const resetPlotCollectionName = usePlotStore((state) => state.resetPlotCollectionName)
+  const queryClient = useQueryClient()
+  const previousLocationRef = useRef(location)
+
+  useEffect(() => {
+    const previousLocation = previousLocationRef.current
+    const leftPlot = previousLocation.pathname === '/plot' && location.pathname !== '/plot'
+    const enteredPlotWithNewQuery =
+      location.pathname === '/plot' && previousLocation.search !== location.search
+    const enteredPlot =
+      location.pathname === '/plot' && previousLocation.pathname !== '/plot'
+
+    if (leftPlot || enteredPlotWithNewQuery || enteredPlot) {
+      setPlotData(null)
+      resetPlotJobId()
+      clearClusterDrillDown()
+      resetPlotCollectionName()
+      queryClient.removeQueries({ queryKey: ['plotData'] })
+    }
+
+    previousLocationRef.current = location
+  }, [clearClusterDrillDown, location, resetPlotCollectionName, resetPlotJobId, setPlotData, queryClient])
+
+  return null
+}
+
 export default function App() {
   return (
     <QueryClientProvider client={queryClient}>
       <BrowserRouter>
         <div className="min-h-screen bg-gray-100">
           <NavBar />
+          <PlotStateResetter />
           <main>
             <Routes>
               <Route path="/" element={<HomePage />} />
diff --git a/frontend/src/components/plot/ClusterDetailDrawer.tsx b/frontend/src/components/plot/ClusterDetailDrawer.tsx
index 4453d18..260c05e 100644
--- a/frontend/src/components/plot/ClusterDetailDrawer.tsx
+++ b/frontend/src/components/plot/ClusterDetailDrawer.tsx
@@ -117,7 +117,10 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
   const displayName = annotation?.name ?? cluster?.name ?? `Cluster ${clusterIndex}`
 
   return (
-    <div className="w-96 bg-white border-l border-gray-200 flex flex-col h-full shadow-lg overflow-hidden">
+    <div
+      className="w-[min(24rem,calc(100vw-20rem))] min-w-[280px] max-w-[24rem] bg-white border-l border-gray-200 flex flex-col h-full shadow-lg overflow-hidden relative z-50 pointer-events-auto"
+      data-testid="cluster-detail-drawer"
+    >
       {/* Header */}
       <div className="px-4 py-3 border-b border-gray-200 flex items-center justify-between shrink-0">
         <div className="flex items-center space-x-2 min-w-0">
diff --git a/frontend/src/components/plot/ClusterLegend.tsx b/frontend/src/components/plot/ClusterLegend.tsx
index c6d7c7f..07daaa8 100644
--- a/frontend/src/components/plot/ClusterLegend.tsx
+++ b/frontend/src/components/plot/ClusterLegend.tsx
@@ -14,7 +14,11 @@ export default function ClusterLegend() {
   const handleShowAll = () => resetVisibleClusters(plotData.clusters.length)
 
   return (
-    <div className="bg-white p-4 border-t border-gray-200 overflow-x-auto">
+    <div
+      className="bg-white p-4 border-t border-gray-200 overflow-x-auto relative z-50 pointer-events-auto"
+      onPointerDown={(event) => event.stopPropagation()}
+      data-testid="cluster-legend"
+    >
       <div className="flex items-center space-x-4 mb-2">
         <h3 className="text-sm font-bold text-gray-700">Clusters</h3>
         <button
@@ -68,10 +72,11 @@ export default function ClusterLegend() {
                 )}
               </button>
 
-              <button
-                onClick={() => setSelectedCluster(
-                  isSelected ? null : cluster.index
-                )}
+               <button
+                 data-testid={`cluster-legend-name-${cluster.index}`}
+                 onClick={() => setSelectedCluster(
+                   isSelected ? null : cluster.index
+                 )}
                 className="flex items-center space-x-2 hover:bg-gray-100 rounded px-1 py-0.5 transition-colors"
                 title="View cluster details"
               >
diff --git a/frontend/src/components/plot/PlotControls.tsx b/frontend/src/components/plot/PlotControls.tsx
index 62d564f..b4bea7a 100644
--- a/frontend/src/components/plot/PlotControls.tsx
+++ b/frontend/src/components/plot/PlotControls.tsx
@@ -49,6 +49,10 @@ export default function PlotControls({ onCompute, isComputing }: PlotControlsPro
     umapMinDist, setUmapMinDist,
     umapMetric, setUmapMetric,
     setImageField: setStoreImageField,
+    resetPlotJobId,
+    clearClusterDrillDown,
+    setPlotData,
+    resetVisibleClusters,
   } = usePlotStore()
 
   // 1. Fetch collection list
@@ -86,6 +90,11 @@ export default function PlotControls({ onCompute, isComputing }: PlotControlsPro
   const handleCompute = () => {
     if (!selectedCollection) return
 
+    resetPlotJobId()
+    clearClusterDrillDown()
+    setPlotData(null)
+    resetVisibleClusters(0)
+
     const request: PlotRequest = {
       chromadb_collection_name: selectedCollection,
       num_clusters: numClusters,
diff --git a/frontend/src/hooks/usePlotData.ts b/frontend/src/hooks/usePlotData.ts
index 0d82484..8eb416d 100644
--- a/frontend/src/hooks/usePlotData.ts
+++ b/frontend/src/hooks/usePlotData.ts
@@ -1,28 +1,33 @@
 import { useMutation, useQuery } from '@tanstack/react-query'
-import { useState, useEffect } from 'react'
+import { useEffect } from 'react'
 import { startPlotCompute, getPlotData } from '../api/plot'
 import { usePlotStore } from '../stores/plotStore'
 import type { PlotRequest } from '../types'
 
 export function usePlotData() {
-  const [jobId, setJobId] = useState<string | null>(null)
   const setPlotData = usePlotStore((state) => state.setPlotData)
   const resetVisibleClusters = usePlotStore((state) => state.resetVisibleClusters)
+  const setPlotJobId = usePlotStore((state) => state.setPlotJobId)
+  const plotJobId = usePlotStore((state) => state.plotJobId)
+  const plotData = usePlotStore((state) => state.plotData)
+  const setPlotCollectionName = usePlotStore((state) => state.setPlotCollectionName)
 
   // 1. Mutation to start compute job
   const mutation = useMutation({
     mutationFn: (params: PlotRequest) => startPlotCompute(params),
-    onSuccess: (data) => {
-      setJobId(data.job_id)
+    onSuccess: (data, params) => {
+      setPlotJobId(data.job_id)
       setPlotData(null) // Clear previous plot
+      resetVisibleClusters(0)
+      setPlotCollectionName(params.chromadb_collection_name)
     },
   })
 
   // 2. Poll for results
   const { data, error, isError } = useQuery({
-    queryKey: ['plotData', jobId],
-    queryFn: () => getPlotData(jobId!),
-    enabled: !!jobId,
+    queryKey: ['plotData', plotJobId],
+    queryFn: () => getPlotData(plotJobId!),
+    enabled: !!plotJobId,
     refetchInterval: (query) => {
       const data = query.state.data
       if (data?.ready) return false
@@ -32,20 +37,30 @@ export function usePlotData() {
 
   // 3. Update store when data is ready
   useEffect(() => {
-    if (data?.ready) {
+    if (plotJobId && data?.ready) {
       setPlotData(data)
+      if (data.job_id) {
+        setPlotJobId(data.job_id)
+      }
       resetVisibleClusters(data.clusters.length)
-      // Stop polling by clearing job ID? No, query stays enabled but refetchInterval stops.
-      // But if we want to "stop" the computing state effectively...
     }
-  }, [data, setPlotData, resetVisibleClusters])
+  }, [data, plotJobId, resetVisibleClusters, setPlotData, setPlotJobId])
 
-  const isComputing = mutation.isPending || (!!jobId && !data?.ready && !isError)
+  const isComputing = mutation.isPending || (!!plotJobId && !data?.ready && !isError)
+
+  useEffect(() => {
+    if (!plotJobId && plotData) {
+      console.warn('[Plot] clearing stale plot data: missing plotJobId')
+      setPlotData(null)
+      resetVisibleClusters(0)
+      setPlotCollectionName(null)
+    }
+  }, [plotData, plotJobId, resetVisibleClusters, setPlotCollectionName, setPlotData])
 
   return {
     compute: mutation.mutate,
     isComputing,
     error: mutation.error || error,
-    jobId,
+    jobId: plotJobId,
   }
 }
diff --git a/frontend/src/pages/PlotPage.tsx b/frontend/src/pages/PlotPage.tsx
index ee86084..f327bc3 100644
--- a/frontend/src/pages/PlotPage.tsx
+++ b/frontend/src/pages/PlotPage.tsx
@@ -14,11 +14,29 @@ export default function PlotPage() {
   const { compute, isComputing, error, jobId } = usePlotData()
   const plotData = usePlotStore((state) => state.plotData)
   const selectedCluster = usePlotStore((state) => state.selectedCluster)
+  const plotJobId = usePlotStore((state) => state.plotJobId)
+  const plotCollectionName = usePlotStore((state) => state.plotCollectionName)
   const imageField = usePlotStore((state) => state.imageField)
+  const setPlotData = usePlotStore((state) => state.setPlotData)
+  const resetPlotJobId = usePlotStore((state) => state.resetPlotJobId)
+  const resetPlotCollectionName = usePlotStore((state) => state.resetPlotCollectionName)
+  const clearClusterDrillDown = usePlotStore((state) => state.clearClusterDrillDown)
+  const resetVisibleClusters = usePlotStore((state) => state.resetVisibleClusters)
   const plotContainerRef = useRef<HTMLDivElement>(null)
   const [isFullscreen, setIsFullscreen] = useState(false)
   const [searchParams] = useSearchParams()
   const collectionName = searchParams.get('collection') ?? ''
+  const effectivePlotData = plotJobId ? plotData : null
+
+  useEffect(() => {
+    if (plotJobId && (!plotCollectionName || plotCollectionName !== collectionName)) {
+      setPlotData(null)
+      resetPlotJobId()
+      resetPlotCollectionName()
+      clearClusterDrillDown()
+      resetVisibleClusters(0)
+    }
+  }, [clearClusterDrillDown, collectionName, plotCollectionName, plotJobId, resetPlotCollectionName, resetPlotJobId, resetVisibleClusters, setPlotData])
 
   const toggleFullscreen = useCallback(() => {
     if (!plotContainerRef.current) return
@@ -41,14 +59,15 @@ export default function PlotPage() {
     }
   }, [])
 
+
   return (
-    <div className="flex flex-col h-screen max-h-[calc(100vh-64px)] overflow-hidden bg-gray-50">
+    <div className="flex flex-col h-screen max-h-[calc(100vh-64px)] overflow-hidden bg-gray-50 relative">
       <div className="flex flex-1 overflow-hidden">
         <div
           data-testid="plot-sidebar"
           className="w-80 border-r border-gray-200 bg-white overflow-y-auto shrink-0 z-10 shadow-sm"
         >
-          {plotData && collectionName && (
+          {effectivePlotData && collectionName && (
             <>
               <div className="px-3 py-2 border-b border-gray-200">
                 <SearchBar collectionName={collectionName} />
@@ -59,7 +78,7 @@ export default function PlotPage() {
           <PlotControls onCompute={compute} isComputing={isComputing} />
         </div>
 
-        <div className="flex-1 flex flex-col relative bg-gray-100">
+        <div className="flex-1 min-w-0 flex flex-col relative bg-gray-100 z-0">
           {error && (
             <div className="absolute top-4 right-4 z-50 bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded shadow-lg max-w-md">
               <p className="font-bold">Error</p>
@@ -77,57 +96,73 @@ export default function PlotPage() {
             </div>
           )}
 
-          <div ref={plotContainerRef} className="flex-1 p-4 overflow-hidden relative">
-            {plotData ? (
-              <>
-                <ScatterPlot />
-                <button
-                  onClick={toggleFullscreen}
-                  className="absolute top-6 right-14 z-10 p-2 bg-gray-800/50 hover:bg-gray-700/80 text-white/80 hover:text-white rounded-md backdrop-blur-sm transition-all shadow-lg border border-white/10"
-                  title={isFullscreen ? 'Exit Fullscreen' : 'Fullscreen'}
-                  aria-label={isFullscreen ? 'Exit Fullscreen' : 'Fullscreen'}
-                >
-                  {isFullscreen ? (
-                    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                      <polyline points="4 14 10 14 10 20" />
-                      <polyline points="20 10 14 10 14 4" />
-                      <line x1="14" y1="10" x2="21" y2="3" />
-                      <line x1="3" y1="21" x2="10" y2="14" />
-                    </svg>
-                  ) : (
-                    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                      <polyline points="15 3 21 3 21 9" />
-                      <polyline points="9 21 3 21 3 15" />
-                      <line x1="21" y1="3" x2="14" y2="10" />
-                      <line x1="3" y1="21" x2="10" y2="14" />
-                    </svg>
+           <div className="flex-1 min-w-0 relative overflow-hidden">
+            <div
+              ref={plotContainerRef}
+              className="h-full w-full min-w-0 p-4 overflow-hidden relative z-0"
+            >
+              {effectivePlotData ? (
+                <>
+                  <ScatterPlot />
+                  {effectivePlotData && selectedCluster !== null && !plotJobId && !jobId && (
+                    <div
+                      data-testid="plot-jobid-warning"
+                      className="absolute top-6 left-6 z-20 bg-yellow-100 border border-yellow-400 text-yellow-800 px-3 py-2 rounded shadow-sm text-xs max-w-xs"
+                    >
+                      Cluster details are unavailable because the plot job ID is missing.
+                      Please recompute the plot or refresh after compute completes.
+                    </div>
                   )}
-                </button>
-
-                {selectedCluster !== null && jobId && (
-                  <ClusterDetailDrawer
-                    jobId={jobId}
-                    imageField={imageField ?? undefined}
-                  />
-                )}
-              </>
-            ) : (
-              <div className="h-full flex items-center justify-center text-gray-400 border-2 border-dashed border-gray-300 rounded-lg">
-                <div className="text-center">
-                  <svg xmlns="http://www.w3.org/2000/svg" className="h-16 w-16 mx-auto mb-4 opacity-50" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1} d="M7 12l3-3 3 3 4-4M8 21l4-4 4 4M3 4h18M4 4h16v12a1 1 0 01-1 1H5a1 1 0 01-1-1V4z" />
-                  </svg>
-                  <h3 className="text-lg font-medium text-gray-900">No Data Visualized</h3>
-                  <p className="mt-1">Select a collection and click Compute to generate a plot.</p>
+                  <button
+                    onClick={toggleFullscreen}
+                    className="absolute top-6 right-14 z-10 p-2 bg-gray-800/50 hover:bg-gray-700/80 text-white/80 hover:text-white rounded-md backdrop-blur-sm transition-all shadow-lg border border-white/10"
+                    title={isFullscreen ? 'Exit Fullscreen' : 'Fullscreen'}
+                    aria-label={isFullscreen ? 'Exit Fullscreen' : 'Fullscreen'}
+                  >
+                    {isFullscreen ? (
+                      <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                        <polyline points="4 14 10 14 10 20" />
+                        <polyline points="20 10 14 10 14 4" />
+                        <line x1="14" y1="10" x2="21" y2="3" />
+                        <line x1="3" y1="21" x2="10" y2="14" />
+                      </svg>
+                    ) : (
+                      <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                        <polyline points="15 3 21 3 21 9" />
+                        <polyline points="9 21 3 21 3 15" />
+                        <line x1="21" y1="3" x2="14" y2="10" />
+                        <line x1="3" y1="21" x2="10" y2="14" />
+                      </svg>
+                    )}
+                  </button>
+                </>
+              ) : (
+                <div className="h-full flex items-center justify-center text-gray-400 border-2 border-dashed border-gray-300 rounded-lg">
+                  <div className="text-center">
+                    <svg xmlns="http://www.w3.org/2000/svg" className="h-16 w-16 mx-auto mb-4 opacity-50" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1} d="M7 12l3-3 3 3 4-4M8 21l4-4 4 4M3 4h18M4 4h16v12a1 1 0 01-1 1H5a1 1 0 01-1-1V4z" />
+                    </svg>
+                    <h3 className="text-lg font-medium text-gray-900">No Data Visualized</h3>
+                    <p className="mt-1">Select a collection and click Compute to generate a plot.</p>
+                  </div>
                 </div>
+              )}
+            </div>
+
+            {selectedCluster !== null && (plotJobId ?? jobId) && (
+              <div className="absolute inset-y-0 right-0 z-30 pointer-events-auto">
+                <ClusterDetailDrawer
+                  jobId={plotJobId ?? jobId!}
+                  imageField={imageField ?? undefined}
+                />
               </div>
             )}
           </div>
         </div>
       </div>
 
-      {plotData && (
-        <div className="border-t border-gray-200 bg-white z-20 shrink-0">
+      {effectivePlotData && (
+        <div className="border-t border-gray-200 bg-white relative z-40 shrink-0 pointer-events-auto">
           <ClusterLegend />
         </div>
       )}
diff --git a/frontend/src/stores/plotStore.ts b/frontend/src/stores/plotStore.ts
index 09e86ef..a5921ce 100644
--- a/frontend/src/stores/plotStore.ts
+++ b/frontend/src/stores/plotStore.ts
@@ -24,6 +24,8 @@ interface PlotState {
   isLoadingClusterDetail: boolean
   isLoadingSubCluster: boolean
   imageField: string | null
+  plotJobId: string | null
+  plotCollectionName: string | null
   // actions
   setPlotData: (data: PlotResponse | null) => void
   toggleCluster: (index: number) => void
@@ -50,6 +52,10 @@ interface PlotState {
   setIsLoadingSubCluster: (loading: boolean) => void
   clearClusterDrillDown: () => void
   setImageField: (field: string | null) => void
+  setPlotJobId: (jobId: string | null) => void
+  resetPlotJobId: () => void
+  setPlotCollectionName: (name: string | null) => void
+  resetPlotCollectionName: () => void
 }
 
 export const CLUSTER_COLORS = [
@@ -82,6 +88,8 @@ export const usePlotStore = create<PlotState>((set) => ({
   isLoadingClusterDetail: false,
   isLoadingSubCluster: false,
   imageField: null,
+  plotJobId: null,
+  plotCollectionName: null,
 
   setPlotData: (data) => set({ plotData: data }),
 
@@ -133,6 +141,10 @@ export const usePlotStore = create<PlotState>((set) => ({
   setIsLoadingClusterDetail: (loading) => set({ isLoadingClusterDetail: loading }),
   setIsLoadingSubCluster: (loading) => set({ isLoadingSubCluster: loading }),
   setImageField: (field) => set({ imageField: field }),
+  setPlotJobId: (jobId) => set({ plotJobId: jobId }),
+  resetPlotJobId: () => set({ plotJobId: null }),
+  setPlotCollectionName: (name) => set({ plotCollectionName: name }),
+  resetPlotCollectionName: () => set({ plotCollectionName: null }),
   clearClusterDrillDown: () => set({
     selectedCluster: null,
     clusterDetail: null,
@@ -141,3 +153,7 @@ export const usePlotStore = create<PlotState>((set) => ({
     isLoadingSubCluster: false,
   }),
 }))
+
+if (typeof window !== 'undefined') {
+  (window as Window & { __plotStore?: typeof usePlotStore }).__plotStore = usePlotStore
+}
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 2aee66c..5b27801 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -96,6 +96,7 @@ export interface PlotResponse {
   points: PlotPoint[];
   clusters: PlotCluster[];
   total_points: number;
+  job_id?: string;
 }
 
 // Cluster Suggestion

From 491dd8a11867d5f39509f2c6e05c32631968490c Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Sun, 15 Mar 2026 19:10:29 +0200
Subject: [PATCH 12/16] fix(plot): prevent hover tooltip crash and clamp
 tooltip placement

---
 frontend/e2e/search.spec.ts                   | 24 +++++++
 frontend/e2e/tooltip-positioning.spec.ts      | 57 ++++++++++++++++
 frontend/src/components/plot/TooltipCard.tsx  | 67 ++++++++++++++++++-
 .../src/components/plot/tooltipPositioning.ts | 55 +++++++++++++++
 4 files changed, 200 insertions(+), 3 deletions(-)
 create mode 100644 frontend/e2e/tooltip-positioning.spec.ts
 create mode 100644 frontend/src/components/plot/tooltipPositioning.ts

diff --git a/frontend/e2e/search.spec.ts b/frontend/e2e/search.spec.ts
index 511c17a..c2c7f30 100644
--- a/frontend/e2e/search.spec.ts
+++ b/frontend/e2e/search.spec.ts
@@ -183,4 +183,28 @@ test.describe('Semantic Search', () => {
       page.getByText('Results: 25')
     ).toBeVisible()
   })
+
+  test('hovering points does not trigger visualization error', async ({ page }) => {
+    const canvas = page.locator('canvas')
+    await expect(canvas).toBeVisible({ timeout: 10_000 })
+
+    const box = await canvas.boundingBox()
+    expect(box).not.toBeNull()
+
+    if (!box) {
+      throw new Error('Canvas bounding box is null')
+    }
+
+    for (let i = 0; i < 12; i += 1) {
+      const x = Math.floor(box.x + box.width * (0.25 + (i % 4) * 0.15))
+      const y = Math.floor(box.y + box.height * (0.25 + Math.floor(i / 4) * 0.2))
+      await page.mouse.move(x, y)
+      await page.mouse.move(Math.floor(box.x + 4), Math.floor(box.y + 4))
+    }
+
+    await expect(
+      page.getByRole('heading', { name: 'Visualization Error' })
+    ).toHaveCount(0)
+  })
+
 })
diff --git a/frontend/e2e/tooltip-positioning.spec.ts b/frontend/e2e/tooltip-positioning.spec.ts
new file mode 100644
index 0000000..6cfd326
--- /dev/null
+++ b/frontend/e2e/tooltip-positioning.spec.ts
@@ -0,0 +1,57 @@
+import { test, expect } from '@playwright/test'
+import { computeTooltipPlacement } from '../src/components/plot/tooltipPositioning'
+
+test.describe('Tooltip placement algorithm', () => {
+  test('clamps and flips within viewport bounds', async () => {
+    const placement = {
+      centeredAbove: computeTooltipPlacement({
+        x: 400,
+        y: 300,
+        width: 256,
+        height: 180,
+        viewportWidth: 1200,
+        viewportHeight: 900,
+        offset: 12,
+        margin: 8,
+      }),
+      flipBelow: computeTooltipPlacement({
+        x: 400,
+        y: 40,
+        width: 256,
+        height: 180,
+        viewportWidth: 1200,
+        viewportHeight: 900,
+        offset: 12,
+        margin: 8,
+      }),
+      clampLeft: computeTooltipPlacement({
+        x: 30,
+        y: 400,
+        width: 256,
+        height: 180,
+        viewportWidth: 1200,
+        viewportHeight: 900,
+        offset: 12,
+        margin: 8,
+      }),
+      clampRight: computeTooltipPlacement({
+        x: 1180,
+        y: 400,
+        width: 256,
+        height: 180,
+        viewportWidth: 1200,
+        viewportHeight: 900,
+        offset: 12,
+        margin: 8,
+      }),
+    }
+
+    expect(placement.centeredAbove.x).toBe(272)
+    expect(placement.centeredAbove.y).toBe(108)
+
+    expect(placement.flipBelow.y).toBe(52)
+
+    expect(placement.clampLeft.x).toBe(8)
+    expect(placement.clampRight.x).toBe(936)
+  })
+})
diff --git a/frontend/src/components/plot/TooltipCard.tsx b/frontend/src/components/plot/TooltipCard.tsx
index 8b15fb3..b05f058 100644
--- a/frontend/src/components/plot/TooltipCard.tsx
+++ b/frontend/src/components/plot/TooltipCard.tsx
@@ -1,16 +1,68 @@
 import { Html } from '@react-three/drei'
-import { useMemo } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { Camera, Object3D } from 'three'
+import { Vector3 } from 'three'
 import { usePlotStore } from '../../stores/plotStore'
+import { computeTooltipPlacement } from './tooltipPositioning'
+
+const TOOLTIP_WIDTH = 256
+const TOOLTIP_OFFSET = 12
+const VIEWPORT_MARGIN = 8
 
 export default function TooltipCard() {
   const hoveredPointId = usePlotStore((state) => state.hoveredPointId)
   const plotData = usePlotStore((state) => state.plotData)
+  const cardRef = useRef<HTMLDivElement | null>(null)
+  const projectedPosition = useRef(new Vector3())
+  const [cardSize, setCardSize] = useState({ width: TOOLTIP_WIDTH, height: 220 })
 
   const point = useMemo(() => {
     if (!hoveredPointId || !plotData) return null
     return plotData.points.find((p) => p.id === hoveredPointId)
   }, [hoveredPointId, plotData])
 
+  useEffect(() => {
+    const element = cardRef.current
+    if (!element) return
+
+    const updateSize = () => {
+      const rect = element.getBoundingClientRect()
+      if (rect.width > 0 && rect.height > 0) {
+        setCardSize({ width: rect.width, height: rect.height })
+      }
+    }
+
+    updateSize()
+
+    const observer = new ResizeObserver(updateSize)
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [point?.id])
+
+  const calculatePosition = useCallback((el: Object3D, camera: Camera, size: { width: number; height: number }) => {
+    el.getWorldPosition(projectedPosition.current)
+    projectedPosition.current.project(camera)
+
+    const anchorX = (projectedPosition.current.x * 0.5 + 0.5) * size.width
+    const anchorY = (-projectedPosition.current.y * 0.5 + 0.5) * size.height
+
+    const placement = computeTooltipPlacement({
+      x: anchorX,
+      y: anchorY,
+      width: cardSize.width,
+      height: cardSize.height,
+      viewportWidth: size.width,
+      viewportHeight: size.height,
+      offset: TOOLTIP_OFFSET,
+      margin: VIEWPORT_MARGIN,
+    })
+
+    return [placement.x, placement.y]
+  }, [cardSize.height, cardSize.width])
+
   if (!point) return null
 
   // Find image URL in metadata if any
@@ -24,8 +76,17 @@ export default function TooltipCard() {
   })?.[1] as string | undefined
 
   return (
-    <Html position={[point.x, point.y, point.z]} style={{ pointerEvents: 'none' }} zIndexRange={[100, 0]}>
-      <div className="bg-white p-3 rounded-lg shadow-lg border border-gray-200 w-64 text-sm pointer-events-none transform -translate-x-1/2 -translate-y-[120%]">
+    <Html
+      position={[point.x, point.y, point.z]}
+      style={{ pointerEvents: 'none' }}
+      zIndexRange={[100, 0]}
+      calculatePosition={calculatePosition}
+    >
+      <div
+        ref={cardRef}
+        data-testid="plot-hover-tooltip"
+        className="bg-white p-3 rounded-lg shadow-lg border border-gray-200 w-64 text-sm pointer-events-none"
+      >
         {imageUrl && (
           <img
             src={imageUrl}
diff --git a/frontend/src/components/plot/tooltipPositioning.ts b/frontend/src/components/plot/tooltipPositioning.ts
new file mode 100644
index 0000000..f31851b
--- /dev/null
+++ b/frontend/src/components/plot/tooltipPositioning.ts
@@ -0,0 +1,55 @@
+export interface TooltipPlacementInput {
+  x: number
+  y: number
+  width: number
+  height: number
+  viewportWidth: number
+  viewportHeight: number
+  offset: number
+  margin: number
+}
+
+export interface TooltipPlacementOutput {
+  x: number
+  y: number
+}
+
+export function computeTooltipPlacement(
+  input: TooltipPlacementInput
+): TooltipPlacementOutput {
+  const {
+    x,
+    y,
+    width,
+    height,
+    viewportWidth,
+    viewportHeight,
+    offset,
+    margin,
+  } = input
+
+  const minX = margin
+  const maxX = Math.max(margin, viewportWidth - width - margin)
+  const centeredX = x - width / 2
+  const clampedX = Math.min(Math.max(centeredX, minX), maxX)
+
+  const preferredTopY = y - height - offset
+  const bottomY = y + offset
+  const canPlaceAbove = preferredTopY >= margin
+  const canPlaceBelow = bottomY + height <= viewportHeight - margin
+
+  let nextY = preferredTopY
+  if (!canPlaceAbove && canPlaceBelow) {
+    nextY = bottomY
+  } else if (!canPlaceAbove && !canPlaceBelow) {
+    nextY = Math.min(
+      Math.max(preferredTopY, margin),
+      Math.max(margin, viewportHeight - height - margin)
+    )
+  }
+
+  return {
+    x: clampedX,
+    y: nextY,
+  }
+}

From f8b95316b9406b8a6340a2c9f03dceed38c3f91d Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Sun, 15 Mar 2026 20:38:50 +0200
Subject: [PATCH 13/16] feat(plot): add multi-select drawer state and controls

---
 frontend/e2e/cluster-drawer.spec.ts           | 175 ++++++++++++++++++
 .../components/plot/ClusterDetailDrawer.tsx   |  58 +++++-
 frontend/src/stores/plotStore.ts              |  16 ++
 3 files changed, 242 insertions(+), 7 deletions(-)

diff --git a/frontend/e2e/cluster-drawer.spec.ts b/frontend/e2e/cluster-drawer.spec.ts
index 6a4b390..237b53f 100644
--- a/frontend/e2e/cluster-drawer.spec.ts
+++ b/frontend/e2e/cluster-drawer.spec.ts
@@ -1,5 +1,15 @@
 import { test, expect } from './fixtures'
 
+type PlotStoreSnapshot = {
+  selectedPointIds?: Set<string>
+}
+
+type PlotStoreWindow = Window & {
+  __plotStore?: {
+    getState: () => PlotStoreSnapshot
+  }
+}
+
 test.describe('Cluster detail drawer', () => {
   test('opens drawer when clicking cluster legend item', async ({ page, plotPage: _ }) => {
     await expect(
@@ -211,4 +221,169 @@ test.describe('Cluster detail drawer', () => {
   })
 
 
+
+  test('drawer item click toggles multi-select state', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByTestId('cluster-legend-name-0')
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const rows = drawer.getByRole('button').filter({ hasText: /dist: /i })
+    await expect(rows.first()).toBeVisible({ timeout: 10_000 })
+
+    await rows.nth(0).click()
+    await rows.nth(1).click()
+
+    let size = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(size).toBe(2)
+
+    await rows.nth(0).click()
+
+    size = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(size).toBe(1)
+  })
+
+  test('drawer supports clear selected and select page', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    const firstCluster = page.getByTestId('cluster-legend-name-0')
+    await expect(firstCluster).toBeVisible({ timeout: 10_000 })
+    await firstCluster.click()
+
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const rows = drawer.getByRole('button').filter({ hasText: /dist: /i })
+    await expect(rows.first()).toBeVisible({ timeout: 10_000 })
+
+    await rows.nth(0).click()
+    await rows.nth(1).click()
+
+    let size = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(size).toBe(2)
+
+    await page.getByRole('button', { name: 'Clear selected' }).click()
+
+    size = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(size).toBe(0)
+
+    await page.getByRole('button', { name: 'Select page' }).click()
+
+    size = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(size).toBeGreaterThan(1)
+  })
+
+  test('selected items remain emphasized in particle mode', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Rendering' }).click()
+    await page.getByRole('radio', { name: 'Particles' }).check()
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    await page.getByTestId('cluster-legend-name-0').click()
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const rows = drawer.getByRole('button').filter({ hasText: /dist: /i })
+    await rows.nth(0).click()
+    await rows.nth(1).click()
+
+    const selectedState = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(selectedState).toBe(2)
+
+    await expect(page.getByRole('heading', { name: 'Visualization Error' })).toHaveCount(0)
+  })
+
+  test('selected items persist in spheres and sprites modes', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Rendering' }).click()
+    await page.getByRole('radio', { name: 'Spheres' }).check()
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    await page.getByTestId('cluster-legend-name-0').click()
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const rows = drawer.getByRole('button').filter({ hasText: /dist: /i })
+    await rows.nth(0).click()
+    await rows.nth(1).click()
+
+    let selectedState = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(selectedState).toBe(2)
+    await expect(page.getByRole('heading', { name: 'Visualization Error' })).toHaveCount(0)
+
+    await page.getByRole('button', { name: 'Rendering' }).click()
+    await page.getByRole('button', { name: 'Rendering' }).click()
+    await page.getByRole('radio', { name: 'Sprites' }).check()
+
+    selectedState = await page.evaluate(() => {
+      const plotWindow = window as PlotStoreWindow
+      return plotWindow.__plotStore?.getState().selectedPointIds?.size
+    })
+    expect(selectedState).toBe(2)
+    await expect(page.getByRole('heading', { name: 'Visualization Error' })).toHaveCount(0)
+  })
+
+  test('distance panel shows pairwise distances for selected products', async ({ page, plotPage: _ }) => {
+    await expect(
+      page.getByRole('button', { name: 'Compute Plot' })
+    ).toBeVisible({ timeout: 10_000 })
+
+    await page.getByRole('button', { name: 'Compute Plot' }).click()
+    await expect(page.locator('canvas')).toBeVisible({ timeout: 120_000 })
+
+    await page.getByTestId('cluster-legend-name-0').click()
+    const drawer = page.getByTestId('cluster-detail-drawer')
+    await expect(drawer).toBeVisible({ timeout: 10_000 })
+
+    const rows = drawer.getByRole('button').filter({ hasText: /dist: /i })
+    await rows.nth(0).click()
+    await rows.nth(1).click()
+
+    await expect(page.getByRole('heading', { name: 'Selected distances' })).toBeVisible({ timeout: 10_000 })
+    await expect(page.getByTestId('selected-distance-row').first()).toBeVisible({ timeout: 10_000 })
+    await expect(page.getByTestId('selected-distance-row').first()).toContainText(/vs/i)
+  })
 })
diff --git a/frontend/src/components/plot/ClusterDetailDrawer.tsx b/frontend/src/components/plot/ClusterDetailDrawer.tsx
index 260c05e..5fecc28 100644
--- a/frontend/src/components/plot/ClusterDetailDrawer.tsx
+++ b/frontend/src/components/plot/ClusterDetailDrawer.tsx
@@ -3,6 +3,7 @@ import { usePlotStore, CLUSTER_COLORS } from '../../stores/plotStore'
 import { getClusterDetail, updateAnnotation, getAnnotations } from '../../api/plot'
 import type { ClusterDetailResponse } from '../../types'
 import SubClusterView from './SubClusterView'
+import SelectedPointsDistancePanel from './SelectedPointsDistancePanel'
 
 interface ClusterDetailDrawerProps {
   jobId: string
@@ -15,10 +16,13 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
   const annotations = usePlotStore((s) => s.annotations)
   const isLoadingClusterDetail = usePlotStore((s) => s.isLoadingClusterDetail)
   const plotData = usePlotStore((s) => s.plotData)
+  const selectedPointIds = usePlotStore((s) => s.selectedPointIds)
   const setClusterDetail = usePlotStore((s) => s.setClusterDetail)
   const setAnnotations = usePlotStore((s) => s.setAnnotations)
   const setIsLoadingClusterDetail = usePlotStore((s) => s.setIsLoadingClusterDetail)
   const setHighlightedIds = usePlotStore((s) => s.setHighlightedIds)
+  const clearSelectedPointIds = usePlotStore((s) => s.clearSelectedPointIds)
+  const setSelectedPointIds = usePlotStore((s) => s.setSelectedPointIds)
   const clearClusterDrillDown = usePlotStore((s) => s.clearClusterDrillDown)
 
   const [page, setPage] = useState(1)
@@ -108,13 +112,33 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
   }, [jobId, clusterIndex, setAnnotations])
 
   const handleItemClick = useCallback((id: string) => {
-    setHighlightedIds(new Set([id]))
-  }, [setHighlightedIds])
+    const nextSelected = new Set(selectedPointIds)
+    if (nextSelected.has(id)) {
+      nextSelected.delete(id)
+    } else {
+      nextSelected.add(id)
+    }
+    setSelectedPointIds(nextSelected)
+    setHighlightedIds(nextSelected)
+  }, [selectedPointIds, setHighlightedIds, setSelectedPointIds])
+
+  const handleClearSelected = useCallback(() => {
+    clearSelectedPointIds()
+    setHighlightedIds(new Set())
+  }, [clearSelectedPointIds, setHighlightedIds])
+
+  const handleSelectPage = useCallback(() => {
+    if (!clusterDetail) return
+    const pageIds = new Set(clusterDetail.items.map((item) => item.id))
+    setSelectedPointIds(pageIds)
+    setHighlightedIds(pageIds)
+  }, [clusterDetail, setHighlightedIds, setSelectedPointIds])
 
   if (clusterIndex == null) return null
 
   const totalPages = clusterDetail ? Math.ceil(clusterDetail.total_items / clusterDetail.page_size) : 0
   const displayName = annotation?.name ?? cluster?.name ?? `Cluster ${clusterIndex}`
+  const selectedItems = clusterDetail?.items.filter((item) => selectedPointIds.has(item.id)) ?? []
 
   return (
     <div
@@ -177,6 +201,18 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
         >
           Sub-Cluster
         </button>
+        <button
+          onClick={handleClearSelected}
+          className="text-xs px-3 py-1 rounded border border-gray-300 text-gray-600 hover:bg-gray-50 transition-colors"
+        >
+          Clear selected
+        </button>
+        <button
+          onClick={handleSelectPage}
+          className="text-xs px-3 py-1 rounded border border-gray-300 text-gray-600 hover:bg-gray-50 transition-colors"
+        >
+          Select page
+        </button>
       </div>
 
       {/* Sub-cluster view */}
@@ -196,17 +232,23 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
 
         {clusterDetail && !isLoadingClusterDetail && (
           <div className="divide-y divide-gray-100">
-            {clusterDetail.items.map((item) => (
+            {clusterDetail.items.map((item) => {
+              const isSelected = selectedPointIds.has(item.id)
+              return (
               <button
                 key={item.id}
                 onClick={() => handleItemClick(item.id)}
-                className="w-full px-4 py-2 text-left hover:bg-blue-50 transition-colors flex items-center space-x-3"
+                className={`w-full px-4 text-left transition-colors flex items-start space-x-3 ${
+                  isSelected
+                    ? 'py-3 bg-blue-50 border-l-2 border-blue-500'
+                    : 'py-2 hover:bg-blue-50'
+                }`}
               >
                 {imageField && imageField in item.metadata && (
                   <img
                     src={String(item.metadata[imageField])}
                     alt=""
-                    className="w-10 h-10 rounded object-cover shrink-0"
+                    className={`rounded object-cover shrink-0 ${isSelected ? 'w-12 h-12' : 'w-10 h-10'}`}
                     loading="lazy"
                   />
                 )}
@@ -219,7 +261,7 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
                   </div>
                   {Object.entries(item.metadata)
                     .filter(([k]) => k !== imageField)
-                    .slice(0, 2)
+                    .slice(0, isSelected ? 6 : 2)
                     .map(([key, value]) => (
                       <div key={key} className="text-[10px] text-gray-400 truncate">
                         {key}: {String(value)}
@@ -227,7 +269,7 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
                     ))}
                 </div>
               </button>
-            ))}
+            )})}
           </div>
         )}
       </div>
@@ -255,6 +297,8 @@ export default function ClusterDetailDrawer({ jobId, imageField }: ClusterDetail
         </div>
       )}
 
+      <SelectedPointsDistancePanel selectedItems={selectedItems} />
+
       {/* Annotation section */}
       <div className="px-4 py-3 border-t border-gray-200 space-y-2 shrink-0">
         <div>
diff --git a/frontend/src/stores/plotStore.ts b/frontend/src/stores/plotStore.ts
index a5921ce..2e1f31e 100644
--- a/frontend/src/stores/plotStore.ts
+++ b/frontend/src/stores/plotStore.ts
@@ -26,6 +26,7 @@ interface PlotState {
   imageField: string | null
   plotJobId: string | null
   plotCollectionName: string | null
+  selectedPointIds: Set<string>
   // actions
   setPlotData: (data: PlotResponse | null) => void
   toggleCluster: (index: number) => void
@@ -56,6 +57,9 @@ interface PlotState {
   resetPlotJobId: () => void
   setPlotCollectionName: (name: string | null) => void
   resetPlotCollectionName: () => void
+  toggleSelectedPointId: (id: string) => void
+  clearSelectedPointIds: () => void
+  setSelectedPointIds: (ids: Set<string>) => void
 }
 
 export const CLUSTER_COLORS = [
@@ -90,6 +94,7 @@ export const usePlotStore = create<PlotState>((set) => ({
   imageField: null,
   plotJobId: null,
   plotCollectionName: null,
+  selectedPointIds: new Set(),
 
   setPlotData: (data) => set({ plotData: data }),
 
@@ -145,6 +150,17 @@ export const usePlotStore = create<PlotState>((set) => ({
   resetPlotJobId: () => set({ plotJobId: null }),
   setPlotCollectionName: (name) => set({ plotCollectionName: name }),
   resetPlotCollectionName: () => set({ plotCollectionName: null }),
+  toggleSelectedPointId: (id) => set((state) => {
+    const newSelected = new Set(state.selectedPointIds)
+    if (newSelected.has(id)) {
+      newSelected.delete(id)
+    } else {
+      newSelected.add(id)
+    }
+    return { selectedPointIds: newSelected }
+  }),
+  clearSelectedPointIds: () => set({ selectedPointIds: new Set() }),
+  setSelectedPointIds: (ids) => set({ selectedPointIds: new Set(ids) }),
   clearClusterDrillDown: () => set({
     selectedCluster: null,
     clusterDetail: null,

From e3175a93fe4d992b84d89df69af0da0ae0f64f02 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Sun, 15 Mar 2026 20:39:14 +0200
Subject: [PATCH 14/16] feat(plot): emphasize selected points across render
 modes

---
 .../src/components/plot/ImageSpriteCloud.tsx  |  25 ++++
 .../src/components/plot/InstancedSpheres.tsx  |  14 +-
 .../src/components/plot/ParticleCloud.tsx     | 121 +++++++++++++-----
 3 files changed, 127 insertions(+), 33 deletions(-)

diff --git a/frontend/src/components/plot/ImageSpriteCloud.tsx b/frontend/src/components/plot/ImageSpriteCloud.tsx
index a0ba776..e8b527f 100644
--- a/frontend/src/components/plot/ImageSpriteCloud.tsx
+++ b/frontend/src/components/plot/ImageSpriteCloud.tsx
@@ -83,6 +83,7 @@ export default function ImageSpriteCloud() {
   const visibleClusters = usePlotStore((state) => state.visibleClusters)
   const pointSize = usePlotStore((state) => state.pointSize)
   const highlightedIds = usePlotStore((state) => state.highlightedIds)
+  const selectedPointIds = usePlotStore((state) => state.selectedPointIds)
   const setHoveredPointId = usePlotStore((state) => state.setHoveredPointId)
 
   const visiblePoints = useMemo(() => {
@@ -100,6 +101,17 @@ export default function ImageSpriteCloud() {
     })
   }, [visiblePoints, highlightedIds])
 
+  const selectedSprites = useMemo(() => {
+    return visiblePoints
+      .filter((point) => selectedPointIds.has(point.id))
+      .map((point) => ({
+        point,
+        color: '#ffffff',
+        imageUrl: getImageUrl(point.metadata),
+        opacity: 1,
+      }))
+  }, [visiblePoints, selectedPointIds])
+
   if (!plotData) return null
 
   return (
@@ -116,6 +128,19 @@ export default function ImageSpriteCloud() {
           />
         </Suspense>
       ))}
+
+      {selectedSprites.map(({ point, color, imageUrl, opacity }) => (
+        <Suspense key={`selected-${point.id}`} fallback={<FallbackSprite point={point} color={color} size={pointSize * 1.4} />}>
+          <PointSprite
+            point={point}
+            color={color}
+            imageUrl={imageUrl}
+            size={pointSize * 1.4}
+            opacity={opacity}
+            onHover={setHoveredPointId}
+          />
+        </Suspense>
+      ))}
     </group>
   )
 }
diff --git a/frontend/src/components/plot/InstancedSpheres.tsx b/frontend/src/components/plot/InstancedSpheres.tsx
index 016618e..c1c667b 100644
--- a/frontend/src/components/plot/InstancedSpheres.tsx
+++ b/frontend/src/components/plot/InstancedSpheres.tsx
@@ -9,6 +9,7 @@ export default function InstancedSpheres() {
   const visibleClusters = usePlotStore((state) => state.visibleClusters)
   const pointSize = usePlotStore((state) => state.pointSize)
   const highlightedIds = usePlotStore((state) => state.highlightedIds)
+  const selectedPointIds = usePlotStore((state) => state.selectedPointIds)
   const setHoveredPointId = usePlotStore((state) => state.setHoveredPointId)
 
   const { filteredPoints, filteredPointIds } = useMemo(() => {
@@ -23,6 +24,9 @@ export default function InstancedSpheres() {
     if (!meshRef.current || filteredPoints.length === 0) return
     const mesh = meshRef.current
     const matrix = new THREE.Matrix4()
+    const position = new THREE.Vector3()
+    const quaternion = new THREE.Quaternion()
+    const scale = new THREE.Vector3()
     // Pre-create color objects for efficiency
     const colorObjects = CLUSTER_COLORS.map(hex => new THREE.Color(hex))
     const hasHighlights = highlightedIds.size > 0
@@ -30,17 +34,23 @@ export default function InstancedSpheres() {
 
     for (let i = 0; i < filteredPoints.length; i++) {
       const p = filteredPoints[i]
-      matrix.setPosition(p.x, p.y, p.z)
+      const isSelected = selectedPointIds.has(p.id)
+      position.set(p.x, p.y, p.z)
+      scale.setScalar(isSelected ? 1.8 : 1)
+      matrix.compose(position, quaternion, scale)
       mesh.setMatrixAt(i, matrix)
 
       const dimFactor = hasHighlights && !highlightedIds.has(p.id) ? 0.15 : 1.0
       const c = colorObjects[p.cluster % colorObjects.length].clone().multiplyScalar(dimFactor)
+      if (isSelected) {
+        c.lerp(new THREE.Color('#ffffff'), 0.45)
+      }
       mesh.setColorAt(i, c)
     }
 
     mesh.instanceMatrix.needsUpdate = true
     if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true
-  }, [filteredPoints, highlightedIds])
+  }, [filteredPoints, highlightedIds, selectedPointIds])
 
   const handlePointerMove = useCallback((e: ThreeEvent<PointerEvent>) => {
     e.stopPropagation()
diff --git a/frontend/src/components/plot/ParticleCloud.tsx b/frontend/src/components/plot/ParticleCloud.tsx
index 1605985..1e2fefc 100644
--- a/frontend/src/components/plot/ParticleCloud.tsx
+++ b/frontend/src/components/plot/ParticleCloud.tsx
@@ -9,24 +9,30 @@ export default function ParticleCloud() {
   const visibleClusters = usePlotStore((state) => state.visibleClusters)
   const pointSize = usePlotStore((state) => state.pointSize)
   const highlightedIds = usePlotStore((state) => state.highlightedIds)
+  const selectedPointIds = usePlotStore((state) => state.selectedPointIds)
   const setHoveredPointId = usePlotStore((state) => state.setHoveredPointId)
 
   // Memoize positions, colors, and the mapping back to original point IDs
-  const { positions, colors, filteredPointIds } = useMemo(() => {
+  const { positions, colors, filteredPointIds, selectedPositions, selectedColors } = useMemo(() => {
     if (!plotData) {
       return {
         positions: new Float32Array(0),
         colors: new Float32Array(0),
         filteredPointIds: [],
+        selectedPositions: new Float32Array(0),
+        selectedColors: new Float32Array(0),
       }
     }
 
     const filteredPoints = plotData.points.filter((p) => visibleClusters.has(p.cluster))
     const count = filteredPoints.length
+    const selectedPoints = filteredPoints.filter((p) => selectedPointIds.has(p.id))
 
     const pos = new Float32Array(count * 3)
     const cols = new Float32Array(count * 3)
     const ids = new Array(count)
+    const selectedPos = new Float32Array(selectedPoints.length * 3)
+    const selectedCols = new Float32Array(selectedPoints.length * 3)
 
     const colorObjects = CLUSTER_COLORS.map(hex => new THREE.Color(hex))
 
@@ -51,8 +57,25 @@ export default function ParticleCloud() {
       ids[i] = p.id
     }
 
-    return { positions: pos, colors: cols, filteredPointIds: ids }
-  }, [plotData, visibleClusters, highlightedIds])
+    for (let i = 0; i < selectedPoints.length; i++) {
+      const p = selectedPoints[i]
+      selectedPos[i * 3] = p.x
+      selectedPos[i * 3 + 1] = p.y
+      selectedPos[i * 3 + 2] = p.z
+
+      selectedCols[i * 3] = 1
+      selectedCols[i * 3 + 1] = 1
+      selectedCols[i * 3 + 2] = 1
+    }
+
+    return {
+      positions: pos,
+      colors: cols,
+      filteredPointIds: ids,
+      selectedPositions: selectedPos,
+      selectedColors: selectedCols,
+    }
+  }, [plotData, visibleClusters, highlightedIds, selectedPointIds])
 
   const handlePointerMove = useCallback((e: ThreeEvent<PointerEvent>) => {
     // Stop event propagation so we don't trigger other things
@@ -72,34 +95,70 @@ export default function ParticleCloud() {
   if (!plotData) return null
 
   return (
-    <points
-      ref={pointsRef}
-      onPointerMove={handlePointerMove}
-      onPointerLeave={handlePointerLeave}
-    >
-      <bufferGeometry>
-        <bufferAttribute
-          attach="attributes-position"
-          count={positions.length / 3}
-          array={positions}
-          itemSize={3}
-          args={[positions, 3]}
-        />
-        <bufferAttribute
-          attach="attributes-color"
-          count={colors.length / 3}
-          array={colors}
-          itemSize={3}
-          args={[colors, 3]}
-        />
-      </bufferGeometry>
-      <pointsMaterial
-        size={pointSize * 0.1}
-        vertexColors
-        sizeAttenuation={true}
-        transparent={false}
-        opacity={1}
+    <group>
+      <group
+        data-testid="particle-selection-overlay"
+        data-count={String(selectedPointIds.size)}
+        visible={false}
       />
-    </points>
+      <points
+        ref={pointsRef}
+        onPointerMove={handlePointerMove}
+        onPointerLeave={handlePointerLeave}
+      >
+        <bufferGeometry>
+          <bufferAttribute
+            attach="attributes-position"
+            count={positions.length / 3}
+            array={positions}
+            itemSize={3}
+            args={[positions, 3]}
+          />
+          <bufferAttribute
+            attach="attributes-color"
+            count={colors.length / 3}
+            array={colors}
+            itemSize={3}
+            args={[colors, 3]}
+          />
+        </bufferGeometry>
+        <pointsMaterial
+          size={pointSize * 0.1}
+          vertexColors
+          sizeAttenuation={true}
+          transparent={false}
+          opacity={1}
+        />
+      </points>
+
+      {selectedPositions.length > 0 && (
+        <points data-testid="particle-selection-overlay">
+          <bufferGeometry>
+            <bufferAttribute
+              attach="attributes-position"
+              count={selectedPositions.length / 3}
+              array={selectedPositions}
+              itemSize={3}
+              args={[selectedPositions, 3]}
+            />
+            <bufferAttribute
+              attach="attributes-color"
+              count={selectedColors.length / 3}
+              array={selectedColors}
+              itemSize={3}
+              args={[selectedColors, 3]}
+            />
+          </bufferGeometry>
+          <pointsMaterial
+            size={pointSize * 0.2}
+            vertexColors
+            sizeAttenuation={true}
+            transparent={true}
+            opacity={1}
+            depthWrite={false}
+          />
+        </points>
+      )}
+    </group>
   )
 }

From 06158ce18fc98826d490b7a714b156c9cd011818 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Sun, 15 Mar 2026 20:39:30 +0200
Subject: [PATCH 15/16] feat(plot): add selected product distance comparisons

---
 .../plot/SelectedPointsDistancePanel.tsx      | 64 +++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 frontend/src/components/plot/SelectedPointsDistancePanel.tsx

diff --git a/frontend/src/components/plot/SelectedPointsDistancePanel.tsx b/frontend/src/components/plot/SelectedPointsDistancePanel.tsx
new file mode 100644
index 0000000..d36a6fb
--- /dev/null
+++ b/frontend/src/components/plot/SelectedPointsDistancePanel.tsx
@@ -0,0 +1,64 @@
+import type { ClusterItemResponse } from '../../types'
+
+interface SelectedPointsDistancePanelProps {
+  selectedItems: ClusterItemResponse[]
+}
+
+interface DistanceRow {
+  key: string
+  leftId: string
+  rightId: string
+  distance: number
+}
+
+function buildDistanceRows(selectedItems: ClusterItemResponse[]): DistanceRow[] {
+  const rows: DistanceRow[] = []
+
+  for (let i = 0; i < selectedItems.length; i += 1) {
+    for (let j = i + 1; j < selectedItems.length; j += 1) {
+      const left = selectedItems[i]
+      const right = selectedItems[j]
+      rows.push({
+        key: `${left.id}-${right.id}`,
+        leftId: left.id,
+        rightId: right.id,
+        distance: Math.abs(left.distance_to_centroid - right.distance_to_centroid),
+      })
+    }
+  }
+
+  return rows
+}
+
+export default function SelectedPointsDistancePanel({ selectedItems }: SelectedPointsDistancePanelProps) {
+  if (selectedItems.length < 2) {
+    return null
+  }
+
+  const rows = buildDistanceRows(selectedItems)
+
+  return (
+    <div className="px-4 py-3 border-t border-gray-200 space-y-2 shrink-0">
+      <h3 className="text-[10px] font-medium text-gray-500 uppercase tracking-wider">
+        Selected distances
+      </h3>
+
+      <div className="space-y-2 max-h-28 overflow-y-auto">
+        {rows.map((row) => (
+          <div
+            key={row.key}
+            data-testid="selected-distance-row"
+            className="rounded border border-gray-200 bg-gray-50 px-2 py-1.5 text-[10px] text-gray-700"
+          >
+            <div className="font-medium text-gray-900">
+              {row.leftId} vs {row.rightId}
+            </div>
+            <div>
+              centroid distance delta: {row.distance.toFixed(4)}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

From fde934a71271f696c0193dd5ee4132ce948a1e70 Mon Sep 17 00:00:00 2001
From: aGallea <asafgallea@gmail.com>
Date: Sun, 15 Mar 2026 21:43:49 +0200
Subject: [PATCH 16/16] fix(plot): remove invalid r3f debug props from particle
 overlay

---
 frontend/src/components/plot/ParticleCloud.tsx | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/frontend/src/components/plot/ParticleCloud.tsx b/frontend/src/components/plot/ParticleCloud.tsx
index 1e2fefc..066fe2a 100644
--- a/frontend/src/components/plot/ParticleCloud.tsx
+++ b/frontend/src/components/plot/ParticleCloud.tsx
@@ -96,11 +96,6 @@ export default function ParticleCloud() {
 
   return (
     <group>
-      <group
-        data-testid="particle-selection-overlay"
-        data-count={String(selectedPointIds.size)}
-        visible={false}
-      />
       <points
         ref={pointsRef}
         onPointerMove={handlePointerMove}
@@ -132,7 +127,7 @@ export default function ParticleCloud() {
       </points>
 
       {selectedPositions.length > 0 && (
-        <points data-testid="particle-selection-overlay">
+        <points>
           <bufferGeometry>
             <bufferAttribute
               attach="attributes-position"