feat(discover): explain the taste match on both clients — #2377 (clients)

"Matches your taste in shoegaze and dream pop." replaces the seed
attribution when the candidate's own tags overlap the taste profile.

The preference order is the point of slice 6: the tag reason describes the
MUSIC ("sounds like what you like"), while seed attribution describes the
graph ("adjacent to something you played"). When we can say the former, it
is strictly the better explanation. When we can't — the common case, since
tag coverage for out-of-library artists is partial by nature (#2376) — the
card falls back to attribution rather than going blank.

Both clients share the wording, Oxford comma included, and both have tests
asserting the exact strings. That's deliberate: identical copy across two
codebases silently diverges unless something fails when it does.

Android caps at 3 tags client-side even though the server already does.
The server contract could widen; a run-on subtitle shouldn't be how we
find out.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

web/src/lib/api/types.ts

@@ -332,6 +332,10 @@ export type ArtistSuggestion = {
   score: number;
   attribution: SeedContribution[]; // up to 3 entries, ordered by contribution DESC
   image_url?: string; // resolved on-demand from Lidarr; absent → card placeholder
+  // Tags this candidate shares with your taste profile, strongest first (max 3,
+  // #2377). Absent for most candidates — tag coverage for artists you don't own
+  // is partial by nature (#2376) — so the card falls back to seed attribution.
+  matched_tags?: string[];
 };
 
 // One parked suggestion — "not right now", not a dislike. The server only

web/src/lib/components/SuggestionFeed.svelte

@@ -44,6 +44,20 @@
     return next;
   }
 
+  // "Matches your taste in shoegaze and dream pop." — the reason line when the
+  // candidate's own tags overlap the taste profile (#2377). Preferred over seed
+  // attribution because it describes the MUSIC ("sounds like what you like")
+  // rather than the graph ("adjacent to something you played"), which is the
+  // whole point of slice 6. Falls back when there are no matched tags, which is
+  // the common case: coverage is partial by nature (#2376).
+  function reasonText(s: ArtistSuggestion): string {
+    const tags = s.matched_tags ?? [];
+    if (tags.length === 0) return attributionText(s.attribution);
+    if (tags.length === 1) return `Matches your taste in ${tags[0]}.`;
+    if (tags.length === 2) return `Matches your taste in ${tags[0]} and ${tags[1]}.`;
+    return `Matches your taste in ${tags[0]}, ${tags[1]}, and ${tags[2]}.`;
+  }
+
   function attributionText(attribution: SeedContribution[]): string {
     if (attribution.length === 0) return '';
     const verb = (s: SeedContribution) => (s.is_liked ? 'liked' : 'played');
@@ -151,7 +165,7 @@
           title={s.name}
           imageUrl={s.image_url}
           state={cardState(s)}
-          attribution={attributionText(s.attribution)}
+          attribution={reasonText(s)}
           onRequest={() => onRequest(s)}
           onSnooze={() => onSnooze(s)}
           onUnsnooze={() => onUnsnooze(s.mbid, s.name)}

web/src/lib/components/SuggestionFeed.test.ts

@@ -244,3 +244,49 @@ describe('SuggestionFeed snooze (#2375)', () => {
     expect(screen.queryByText(/listen to something or like an artist/i)).not.toBeInTheDocument();
   });
 });
+
+describe('SuggestionFeed taste-tag reason (#2377)', () => {
+  const tagged = (over: Partial<ArtistSuggestion> = {}): ArtistSuggestion => ({
+    ...oneSeed,
+    mbid: 'mbT',
+    name: 'Tag Match',
+    ...over
+  });
+
+  test('matched tags replace seed attribution as the reason line', () => {
+    setSuggestions([tagged({ matched_tags: ['shoegaze', 'dream pop'] })]);
+    render(SuggestionFeed);
+    expect(
+      screen.getByText(/matches your taste in shoegaze and dream pop\./i)
+    ).toBeInTheDocument();
+    // The graph-adjacency line is superseded — describing the music beats
+    // describing the graph when we can do both.
+    expect(screen.queryByText(/because you liked/i)).not.toBeInTheDocument();
+  });
+
+  test('one matched tag reads in the singular', () => {
+    setSuggestions([tagged({ matched_tags: ['shoegaze'] })]);
+    render(SuggestionFeed);
+    expect(screen.getByText(/matches your taste in shoegaze\./i)).toBeInTheDocument();
+  });
+
+  test('three matched tags use an Oxford comma, matching the seed copy', () => {
+    setSuggestions([tagged({ matched_tags: ['a', 'b', 'c'] })]);
+    render(SuggestionFeed);
+    expect(screen.getByText(/matches your taste in a, b, and c\./i)).toBeInTheDocument();
+  });
+
+  // The common case: most candidates have no cached tags, and the card must
+  // still explain itself rather than going blank.
+  test('no matched tags falls back to seed attribution', () => {
+    setSuggestions([oneSeed]);
+    render(SuggestionFeed);
+    expect(screen.getByText(/because you liked seed\./i)).toBeInTheDocument();
+  });
+
+  test('an empty matched_tags array also falls back, not to an empty line', () => {
+    setSuggestions([tagged({ matched_tags: [] })]);
+    render(SuggestionFeed);
+    expect(screen.getByText(/because you liked seed\./i)).toBeInTheDocument();
+  });
+});