feat: cluster drill-down and annotation

[aGallea]

Summary

Implements #12 -- cluster drill-down, sub-clustering, and annotation.

Cluster Detail Panel

Click a cluster name in the legend to open a slide-in drawer showing every item in that cluster, sorted by distance to centroid, with pagination and image thumbnails.

Sub-Clustering

Re-run k-means within a single cluster. Results render as a mini 3D scatter plot (PCA-reduced) inside the detail drawer.

Annotations

Rename clusters, add notes and tags. Changes auto-save (debounced) as JSON sidecar files in annotations/ (gitignored). Annotations persist across page reloads, scoped per plot job.

API Endpoints

• GET /api/plot/{job_id}/cluster/{index} -- paginated cluster detail
• POST /api/plot/{job_id}/cluster/{index}/sub-cluster -- sub-cluster with configurable k
• GET /api/annotations/{job_id} -- fetch annotations
• PUT /api/annotations/{job_id} -- update annotations
• DELETE /api/annotations/{job_id} -- delete annotations

Backend

• 8 new Pydantic models (ClusterItemResponse, ClusterDetailResponse, SubClusterRequest/Point/Info/Response, AnnotationUpdate, ClusterAnnotation)
• AnnotationManager with file-based JSON persistence
• compute_plot_data() now returns internal fields (embeddings, labels, IDs) stripped before sending to frontend
• 22 files changed, +1,775 lines

Frontend

• ClusterDetailDrawer (280 lines) -- side panel with metadata, images, annotations, sub-cluster toggle
• SubClusterView (110 lines) -- mini 3D scatter via @react-three/fiber
• Updated ClusterLegend -- name click opens drawer, eye icon toggles visibility, annotation indicator dot
• 9 new TypeScript interfaces, 6 new API functions, Zustand store extensions

Tests

• 242 total tests passing, 98% coverage
• New test files: test_annotations.py, test_cluster_detail.py, test_sub_cluster.py, test_server_annotations.py
• Extended: test_scatter_plot.py, test_server_plot.py

Closes #12

[github-actions]

Tests Report 📄

Tests Succees ✅

JUnit Details

Total Tests	Failures	Errors	Skipped	Time ⏳
242	0	0	0	60.46s

Coverage Details (100% >= 90%) ✅

Diff Cover Details

File	Covered Lines		Missing Lines
embedding_cluster/annotations.py	69/69	100%
embedding_cluster/scatter_plot.py	3/3	100%
embedding_cluster/server/app.py	4/4	100%
embedding_cluster/server/models.py	67/67	100%
embedding_cluster/server/routes/annotations.py	57/57	100%
embedding_cluster/server/routes/plot.py	184/185	99%	249
Total	384/385	100%