fix(api): plot of the day shows light preview image in dark mode (#10308)

## Summary

- Fixes a user bug report (on `/roc-curve/python/altair`, in German):
the "plot of the day" on the landing page was not displayed correctly in
dark mode — the terminal card rendered the light-background preview
image on the dark page.
- Root cause: `GET /insights/plot-of-the-day` only returned the legacy
`preview_url`, which is an ORM synonym for `preview_url_light`. The
frontend has been theme-aware since Phase C (`selectPreviewUrl` in
`app/src/utils/themedPreview.ts`, and `PlotOfTheDayData` already
declares the themed fields), but with no `preview_url_dark` in the
payload it always fell back to the light image.
- Fix: `PlotOfTheDayResponse` now carries `preview_url_light` /
`preview_url_dark`, and `_build_potd` threads the dark URL through the
candidate selection. No frontend change needed — `PlotOfTheDayTerminal`
picks the dark variant up automatically.

## Test plan

- [x] `uv run pytest tests/unit/api/test_routers.py` — 137 passed,
including the extended `test_potd_with_db` which now asserts both themed
URLs flow through to the response
- [x] `uv run ruff check` / `ruff format --check` / `uv run mypy
api/routers/insights.py` — clean

## Checklist

- [x] `CHANGELOG.md` updated under `[Unreleased]` (follow-up commit on
this branch referencing this PR number)
- [x] Related documentation updated if behavior changed — none needed
(no analytics events, workflows, or user-facing docs touched)

---
_Generated by [Claude
Code](https://claude.ai/code/session_0162HVVDfD1xUDwP3Gs2b3ns)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

CHANGELOG.md

@@ -138,6 +138,11 @@ aggregate instead: an italic *Catalog* line at the end of the version section an
 
 ### Fixed
 
+- **Plot of the day now respects dark mode** — the landing-page terminal card always showed the
+  light preview image because `GET /insights/plot-of-the-day` only returned the legacy
+  `preview_url` (a synonym for the light variant); the response now carries
+  `preview_url_light` / `preview_url_dark`, so the already theme-aware frontend picks the dark
+  render automatically (user bug report, in German, on `/roc-curve/python/altair`) (#10308).
 - **A correctly rejected plot was reported as a crashed review, deadlocking the PR** —
   `impl-review.yml` used quality score `0` as its sentinel for "the AI review produced no
   output", but `0` is also a score the review prompt *mandates*: the Stage 1 auto-reject gates

api/routers/insights.py

@@ -145,6 +145,8 @@ class PlotOfTheDayResponse(BaseModel):
     language: str
     quality_score: float
     preview_url: str | None = None
+    preview_url_light: str | None = None
+    preview_url_dark: str | None = None
     image_description: str | None = None
     code: str | None = None
     library_version: str | None = None
@@ -422,7 +424,7 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
     today = date.today().isoformat()
 
     # Collect candidates: implementations with quality_score >= 90 (lightweight, no code loaded)
-    candidates: list[tuple[str, str, str, str, str, float, str]] = []
+    candidates: list[tuple[str, str, str, str, str, float, str, str | None]] = []
     for spec in all_specs:
         for impl in spec.impls:
             if impl.quality_score is not None and impl.quality_score >= 90 and impl.preview_url:
@@ -436,6 +438,7 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
                         language,
                         impl.quality_score,
                         impl.preview_url,
+                        impl.preview_url_dark,
                     )
                 )
 
@@ -445,11 +448,19 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
     # Deterministic selection based on date
     seed = int(hashlib.md5(today.encode()).hexdigest(), 16)  # noqa: S324
     idx = seed % len(candidates)
-    spec_id, spec_title, description, library_id, language, quality_score, preview_url = candidates[idx]
+    spec_id, spec_title, description, library_id, language, quality_score, preview_url, preview_url_dark = candidates[
+        idx
+    ]
 
     # Load deferred fields (code, image_description) for just this one impl
     full_impl = await impl_repo.get_by_spec_and_library(spec_id, library_id)
 
+    # Prefer preview URLs from the fresh per-impl load so they can't drift from
+    # the code/metadata below; the candidate-snapshot values are the fallback.
+    if full_impl:
+        preview_url = full_impl.preview_url_light or preview_url
+        preview_url_dark = full_impl.preview_url_dark or preview_url_dark
+
     return PlotOfTheDayResponse(
         spec_id=spec_id,
         spec_title=spec_title,
@@ -459,6 +470,8 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
         language=language,
         quality_score=quality_score,
         preview_url=preview_url,
+        preview_url_light=preview_url,
+        preview_url_dark=preview_url_dark,
         image_description=full_impl.review_image_description if full_impl else None,
         code=strip_noqa_comments(full_impl.code) if full_impl and full_impl.code else None,
         library_version=full_impl.library_version if full_impl else None,

tests/unit/api/test_routers.py

@@ -1775,7 +1775,9 @@ def test_potd_without_db(self, client: TestClient) -> None:
             assert response.status_code == 503
 
     def test_potd_with_db(self, client: TestClient, mock_spec) -> None:
-        """Plot of the day should return a featured implementation."""
+        """Plot of the day should return a featured implementation with themed preview URLs."""
+        dark_url = "https://example.com/plot-dark.png"
+        mock_spec.impls[0].preview_url_dark = dark_url
         mock_spec_repo = MagicMock()
         mock_spec_repo.get_all = AsyncMock(return_value=[mock_spec])
         mock_impl = MagicMock()
@@ -1784,6 +1786,8 @@ def test_potd_with_db(self, client: TestClient, mock_spec) -> None:
         mock_impl.library_version = "3.10.0"
         mock_impl.python_version = "3.13.11"
         mock_impl.language_version = "3.13.11"
+        mock_impl.preview_url_light = TEST_IMAGE_URL
+        mock_impl.preview_url_dark = dark_url
         mock_impl_repo = MagicMock()
         mock_impl_repo.get_by_spec_and_library = AsyncMock(return_value=mock_impl)
 
@@ -1799,6 +1803,8 @@ def test_potd_with_db(self, client: TestClient, mock_spec) -> None:
             assert data["spec_id"] == "scatter-basic"
             assert data["library_id"] == "matplotlib"
             assert data["quality_score"] == 92.5
+            assert data["preview_url_light"] == TEST_IMAGE_URL
+            assert data["preview_url_dark"] == dark_url
 
     def test_potd_no_candidates(self, client: TestClient) -> None:
         """Plot of the day should return null when no high-quality implementations."""