feat: show primary copyright match in portal tooltip (#389)

- add CopyrightInfo dataclass with is_flagged and primary_match
- extract most frequent match from copyright scan results
- add copyright_match field to TrackResponse API schema
- update tooltip to show "potential copyright violation: [match]"

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

Co-authored-by: Claude <[e-mail]>

backend/src/backend/api/tracks/listing.py

···
 from backend.schemas import TrackResponse
 from backend.utilities.aggregations import (
     get_comment_counts,
-    get_copyright_flags,
+    get_copyright_info,
     get_like_counts,
 )
 
···
     result = await db.execute(stmt)
     tracks = result.scalars().all()
 
-    # batch fetch like, comment counts and copyright flags for all tracks
+    # batch fetch like, comment counts and copyright info for all tracks
     track_ids = [track.id for track in tracks]
-    like_counts, comment_counts, copyright_flags = await asyncio.gather(
+    like_counts, comment_counts, copyright_info = await asyncio.gather(
         get_like_counts(db, track_ids),
         get_comment_counts(db, track_ids),
-        get_copyright_flags(db, track_ids),
+        get_copyright_info(db, track_ids),
     )
 
     # use cached PDS URLs with fallback on failure
···
                 liked_track_ids,
                 like_counts,
                 comment_counts,
-                copyright_flags,
+                copyright_info,
             )
             for track in tracks
         ]
···
     result = await db.execute(stmt)
     tracks = result.scalars().all()
 
-    # batch fetch copyright flags
+    # batch fetch copyright info
     track_ids = [track.id for track in tracks]
-    copyright_flags = await get_copyright_flags(db, track_ids)
+    copyright_info = await get_copyright_info(db, track_ids)
 
     # fetch all track responses concurrently
     track_responses = await asyncio.gather(
         *[
-            TrackResponse.from_track(track, copyright_flags=copyright_flags)
+            TrackResponse.from_track(track, copyright_info=copyright_info)
             for track in tracks
         ]
     )
···
     result = await db.execute(stmt)
     tracks = result.scalars().all()
 
-    # batch fetch copyright flags
+    # batch fetch copyright info
     track_ids = [track.id for track in tracks]
-    copyright_flags = await get_copyright_flags(db, track_ids)
+    copyright_info = await get_copyright_info(db, track_ids)
 
     # fetch all track responses concurrently
     track_responses = await asyncio.gather(
         *[
-            TrackResponse.from_track(track, copyright_flags=copyright_flags)
+            TrackResponse.from_track(track, copyright_info=copyright_info)
             for track in tracks
         ]
     )

backend/src/backend/schemas.py

···
 from pydantic import BaseModel
 
 from backend.models import Album, Track
+from backend.utilities.aggregations import CopyrightInfo
 
 
 class AlbumSummary(BaseModel):
···
     copyright_flagged: bool | None = (
         None  # None = not scanned, False = clear, True = flagged
     )
+    copyright_match: str | None = None  # "Title by Artist" of primary match
 
     @classmethod
     async def from_track(
···
         liked_track_ids: set[int] | None = None,
         like_counts: dict[int, int] | None = None,
         comment_counts: dict[int, int] | None = None,
-        copyright_flags: dict[int, bool] | None = None,
+        copyright_info: dict[int, CopyrightInfo] | None = None,
     ) -> "TrackResponse":
         """build track response from Track model.
 
···
             liked_track_ids: optional set of liked track IDs for this user
             like_counts: optional dict of track_id -> like_count
             comment_counts: optional dict of track_id -> comment_count
-            copyright_flags: optional dict of track_id -> is_flagged (None if not scanned)
+            copyright_info: optional dict of track_id -> CopyrightInfo
         """
         # check if user has liked this track
         is_liked = liked_track_ids is not None and track.id in liked_track_ids
···
                 f"&rkey={rkey}"
             )
 
-        # get copyright flag status (None if not in dict = not scanned)
-        copyright_flagged = copyright_flags.get(track.id) if copyright_flags else None
+        # get copyright info (None if not in dict = not scanned)
+        track_copyright = copyright_info.get(track.id) if copyright_info else None
+        copyright_flagged = track_copyright.is_flagged if track_copyright else None
+        copyright_match = track_copyright.primary_match if track_copyright else None
 
         return cls(
             id=track.id,
···
             comment_count=comment_count,
             album=album_data,
             copyright_flagged=copyright_flagged,
+            copyright_match=copyright_match,
         )

backend/src/backend/utilities/aggregations.py

···
 """aggregation utilities for efficient batch counting."""
 
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any
+
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.sql import func
 
 from backend.models import CopyrightScan, TrackComment, TrackLike
+
+
+@dataclass
+class CopyrightInfo:
+    """copyright scan result with match details."""
+
+    is_flagged: bool
+    primary_match: str | None = None  # "Title by Artist" for most frequent match
 
 
 async def get_like_counts(db: AsyncSession, track_ids: list[int]) -> dict[int, int]:
···
     return dict(result.all())  # type: ignore
 
 
-async def get_copyright_flags(
+async def get_copyright_info(
     db: AsyncSession, track_ids: list[int]
-) -> dict[int, bool]:
-    """get copyright flag status for multiple tracks in a single query.
+) -> dict[int, CopyrightInfo]:
+    """get copyright scan info for multiple tracks in a single query.
 
     args:
         db: database session
-        track_ids: list of track IDs to get flags for
+        track_ids: list of track IDs to get info for
 
     returns:
-        dict mapping track_id -> is_flagged (only includes scanned tracks)
+        dict mapping track_id -> CopyrightInfo (only includes scanned tracks)
     """
     if not track_ids:
         return {}
 
-    stmt = select(CopyrightScan.track_id, CopyrightScan.is_flagged).where(
-        CopyrightScan.track_id.in_(track_ids)
-    )
+    stmt = select(
+        CopyrightScan.track_id, CopyrightScan.is_flagged, CopyrightScan.matches
+    ).where(CopyrightScan.track_id.in_(track_ids))
 
     result = await db.execute(stmt)
-    return dict(result.all())  # type: ignore
+    rows = result.all()
+
+    copyright_info: dict[int, CopyrightInfo] = {}
+    for track_id, is_flagged, matches in rows:
+        primary_match = _extract_primary_match(matches) if is_flagged else None
+        copyright_info[track_id] = CopyrightInfo(
+            is_flagged=is_flagged,
+            primary_match=primary_match,
+        )
+
+    return copyright_info
+
+
+def _extract_primary_match(matches: list[dict[str, Any]]) -> str | None:
+    """extract the most frequent match from copyright scan results.
+
+    args:
+        matches: list of match dicts with 'title' and 'artist' keys
+
+    returns:
+        "Title by Artist" string for the most common match, or None
+    """
+    if not matches:
+        return None
+
+    # count occurrences of each (title, artist) pair
+    match_counts: Counter[tuple[str, str]] = Counter()
+    for match in matches:
+        title = match.get("title", "").strip()
+        artist = match.get("artist", "").strip()
+        if title and artist:
+            match_counts[(title, artist)] += 1
+
+    if not match_counts:
+        return None
+
+    # get the most common match
+    (title, artist), _ = match_counts.most_common(1)[0]
+    return f"{title} by {artist}"

frontend/src/lib/types.ts

···
 	image_url?: string;
 	is_liked?: boolean;
 	copyright_flagged?: boolean | null; // null = not scanned, false = clear, true = flagged
+	copyright_match?: string | null; // "Title by Artist" of primary match
 }
 
 export interface User {

frontend/src/routes/portal/+page.svelte

···
 					<div class="track-title">
 						{track.title}
 						{#if track.copyright_flagged}
+							{@const matchText = track.copyright_match ? `potential copyright violation: ${track.copyright_match}` : 'potential copyright violation'}
 							{#if track.atproto_record_url}
 								<a
 									href={track.atproto_record_url}
 									target="_blank"
 									rel="noopener noreferrer"
 									class="copyright-flag"
-									title="potential copyright match - click to view record"
+									title="{matchText}"
 								>
 									<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
 										<path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"></path>
···
 									</svg>
 								</a>
 							{:else}
-								<span class="copyright-flag" title="potential copyright match detected">
+								<span class="copyright-flag" title={matchText}>
 									<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
 										<path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"></path>
 										<line x1="12" y1="9" x2="12" y2="13"></line>