feat: /map page — force-directed spec map clustered by tag similarity

api/cache.py

@@ -178,6 +178,7 @@ def clear_spec_cache(spec_id: str) -> int:
     count += clear_cache_by_pattern(f"spec:{spec_id}")
     count += clear_cache_by_pattern(f"spec_images:{spec_id}")
     count += clear_cache_by_pattern("specs_list")  # List might have changed
+    count += clear_cache_by_pattern("specs_map")  # Map page payload might have changed
     count += clear_cache_by_pattern("filter:")  # Filters might be affected
     count += clear_cache_by_pattern("stats")  # Stats might have changed
     count += clear_cache_by_pattern("sitemap")  # Sitemap includes spec URLs

api/routers/specs.py

@@ -6,7 +6,7 @@
 from api.cache import cache_key, get_or_set_cache
 from api.dependencies import require_db
 from api.exceptions import raise_not_found
-from api.schemas import ImplementationResponse, SpecDetailResponse, SpecListItem
+from api.schemas import ImplementationResponse, SpecDetailResponse, SpecListItem, SpecMapItem
 from core.config import settings
 from core.database import ImplRepository, SpecRepository
 from core.database.connection import get_db_context
@@ -28,6 +28,33 @@ async def _build_specs_list(db: AsyncSession) -> list[SpecListItem]:
     ]
 
 
+async def _build_specs_map(db: AsyncSession) -> list[SpecMapItem]:
+    """One row per spec with its best-rated impl image + spec/impl tag bag for the /map page.
+
+    Best-impl tiebreak: highest quality_score, then lexicographic library_id for determinism.
+    Specs without any implementations are skipped (mirrors _build_specs_list).
+    """
+    repo = SpecRepository(db)
+    specs = await repo.get_all()
+    items: list[SpecMapItem] = []
+    for spec in specs:
+        if not spec.impls:
+            continue
+        best = max(spec.impls, key=lambda i: ((i.quality_score or 0.0), i.library_id))
+        items.append(
+            SpecMapItem(
+                id=spec.id,
+                title=spec.title,
+                preview_url_light=best.preview_url_light,
+                preview_url_dark=best.preview_url_dark,
+                quality_score=best.quality_score,
+                tags=spec.tags,
+                impl_tags=best.impl_tags,
+            )
+        )
+    return items
+
+
 async def _build_spec_detail(db: AsyncSession, spec_id: str) -> SpecDetailResponse:
     repo = SpecRepository(db)
     spec = await repo.get_by_id(spec_id)
@@ -125,6 +152,25 @@ async def _refresh() -> list[SpecListItem]:
     )
 
 
+@router.get("/specs/map", response_model=list[SpecMapItem])
+async def get_specs_map(db: AsyncSession = Depends(require_db)):
+    """Get one row per spec (best-impl image + tag bag) for the /map clustering page.
+
+    NOTE: must stay declared before /specs/{spec_id} so the path-parameter route doesn't capture "map".
+    """
+
+    async def _fetch() -> list[SpecMapItem]:
+        return await _build_specs_map(db)
+
+    async def _refresh() -> list[SpecMapItem]:
+        async with get_db_context() as fresh_db:
+            return await _build_specs_map(fresh_db)
+
+    return await get_or_set_cache(
+        cache_key("specs_map"), _fetch, refresh_after=settings.cache_refresh_after, refresh_factory=_refresh
+    )
+
+
 @router.get("/specs/{spec_id}", response_model=SpecDetailResponse)
 async def get_spec(spec_id: str, db: AsyncSession = Depends(require_db)):
     """Get detailed spec information including all implementations."""

api/schemas.py

@@ -69,6 +69,18 @@ class SpecListItem(BaseModel):
     library_count: int = 0
 
 
+class SpecMapItem(BaseModel):
+    """One row per spec for the /map page: best-impl preview + full tag bag for client-side similarity clustering."""
+
+    id: str
+    title: str
+    preview_url_light: str | None = None
+    preview_url_dark: str | None = None
+    quality_score: float | None = None
+    tags: dict[str, Any] | None = None
+    impl_tags: dict[str, Any] | None = None
+
+
 class ImageResponse(BaseModel):
     """Image/plot response for grid display."""
 

app/package.json

@@ -22,9 +22,11 @@
     "@emotion/styled": "^11.14.1",
     "@mui/icons-material": "^9.0.0",
     "@mui/material": "^9.0.0",
+    "force-graph": "^1.51.4",
     "fuse.js": "^7.3.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
+    "react-force-graph-2d": "^1.29.1",
     "react-helmet-async": "^3.0.0",
     "react-router-dom": "^7.14.2",
     "react-syntax-highlighter": "^16.1.1",

app/src/components/NavBar.tsx

@@ -10,6 +10,7 @@ const DEBUG_CLICK_WINDOW_MS = 800;
 const NAV_LINKS: { label: string; to: string; short?: string }[] = [
   { label: 'specs', to: '/specs' },
   { label: 'plots', to: '/plots' },
+  { label: 'map', to: '/map' },
   { label: 'libraries', to: '/libraries', short: 'libs' },
   { label: 'stats', to: '/stats' },
   { label: 'palette', to: '/palette', short: 'pal' },