feat: /map page — force-directed spec map clustered by tag similarity (#5647)

## Summary

- Backend: new `GET /api/specs/map` endpoint — one row per spec with the
highest-rated implementation's preview URLs, quality score, and full tag
bag (spec + impl).
- Frontend: new `/map` page powered by `react-force-graph-2d` —
image-thumbnail nodes positioned by client-side weighted-Jaccard
similarity over tags (IDF-weighted, sparse KNN edges).
- Wired into `NavBar` as a top-level link and registered as a
lazy-loaded route.

Closes #5646.

## Approach in one paragraph

Tag similarity, IDF weighting, and KNN edge construction all happen
client-side as pure helpers in `app/src/pages/MapPage.helpers.ts` (19
unit tests). 327 specs × pairwise weighted-Jaccard runs in ~30 ms in the
browser, so there's no need to precompute positions on the server. The
wrapper's built-in d3-force physics handles the layout from a sparse
link list (K=5, min-sim 0.05 → ~1.6k edges). Best-impl thumbnails are
eager-preloaded and attached to nodes as they resolve, so the canvas
re-paints organically without restarting physics. Hover highlights
neighbors, click navigates to the spec page, and a visually-hidden
anchor list mirrors the canvas for screen readers + keyboard users.

## Test plan

- [x] `uv run ruff check api/ tests/` — clean
- [x] `uv run ruff format --check api/ tests/` — clean
- [x] `uv run pytest tests/unit/api/ tests/unit/core/` — 739 passed (5
new SpecsRouter tests for the endpoint)
- [x] `cd app && yarn lint` — no new errors in MapPage files
(pre-existing baseline drift in unrelated files unchanged)
- [x] `cd app && yarn tsc --noEmit` — clean
- [x] `cd app && yarn test` — 421 passed (19 new helper tests + 3 new
page smoke tests)
- [x] `cd app && yarn build` — succeeds; `/map` chunk is 193 KB raw / 63
KB gz, lazy-loaded only when visiting `/map`
- [ ] Manual visual QA in dev server: nav link appears, ~327 thumbnails
render, scatter/bar/line clusters form distinct neighborhoods, hover
highlights neighbors + dims the rest, click → spec page, theme toggle
switches link colors and thumbnails, mobile breakpoint usable

## Notes / known follow-ups

1. **Optional edge tag labels** (the user's "optional" feature) —
explicitly out of scope here, deferred to a follow-up issue. Idea: on
hover, render shared-tag chips at link midpoints as DOM overlays.
2. **Layout opt-out via negative margins** in `MapPage.tsx` cancels
`RootLayout`'s container padding so the canvas goes full-bleed. TODO
comment left in place; cleaner long-term answer is a router-level layout
switch analog to the existing `mastheadSticks` flag.
3. **Thumbnail size**: full-size GCS PNGs at 327 × ~40 KB ≈ 13 MB.
Acceptable on warm CDN, slightly heavy on cold. If perf review pushes
back, the follow-up is to add a smaller variant in the responsive-image
pipeline.
4. **K=5, min-sim=0.05** are gut-feel values; helpers are pure so tuning
is a one-line PR after live observation.
5. **Pre-existing eslint baseline drift**: 35
`react-hooks/set-state-in-effect` and `no-undef` errors in unrelated
files were already present before this branch. None added; one
previously-introduced one in `MapPage.tsx` was refactored away during
review.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarkusNeusinger

.gitignore

@@ -242,3 +242,6 @@ docker-compose.override.yml
 secrets/
 /.playwright-mcp/
 /screenshots/
+
+# Map page tuning screenshots (root-level only — must not match plots/*/preview.png etc.)
+/map-*.png

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/seo.py

@@ -47,6 +47,7 @@ def _build_sitemap_xml(specs: list) -> str:
         "  <url><loc>https://anyplot.ai/plots</loc></url>",
         "  <url><loc>https://anyplot.ai/specs</loc></url>",
         "  <url><loc>https://anyplot.ai/libraries</loc></url>",
+        "  <url><loc>https://anyplot.ai/map</loc></url>",
         "  <url><loc>https://anyplot.ai/palette</loc></url>",
         "  <url><loc>https://anyplot.ai/about</loc></url>",
         "  <url><loc>https://anyplot.ai/mcp</loc></url>",

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,40 @@ 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 lexicographically *greatest* library_id
+    (since `max()` picks the largest tuple — e.g. seaborn over matplotlib on a tie).
+    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
+        # Prefer impls that actually have a preview URL — otherwise the map
+        # would render blank-bordered nodes for specs whose top-quality impl
+        # happens to have no thumbnail. Fall back to the full impl list only
+        # when *no* impl has a preview (very rare, but keeps the spec on the map).
+        with_preview = [i for i in spec.impls if i.preview_url_light or i.preview_url_dark]
+        candidates = with_preview or list(spec.impls)
+        best = max(candidates, 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 +159,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,22 @@ 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
+    # Tag bags: each category maps to a list of strings. Tightened from
+    # dict[str, Any] so the OpenAPI contract matches what the /map frontend
+    # expects (Record<string, string[]>) and so unexpected shapes get
+    # caught at validation time instead of breaking client-side similarity.
+    tags: dict[str, list[str]] | None = None
+    impl_tags: dict[str, list[str]] | 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' },