From e358a92cf46d7d99018f75722a83b3493cfc92ff Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Sat, 6 Jun 2026 22:34:46 -0400
Subject: [PATCH] feat(web): similar-artists strip + top-tracks panel on artist
 detail

---
 web/src/lib/api/queries.ts                 | 18 +++++++++
 web/src/routes/artists/[id]/+page.svelte   | 43 +++++++++++++++++++++-
 web/src/routes/artists/[id]/artist.test.ts | 41 +++++++++++++++++++--
 3 files changed, 97 insertions(+), 5 deletions(-)

diff --git a/web/src/lib/api/queries.ts b/web/src/lib/api/queries.ts
index 50f9ad9e..71f444f4 100644
--- a/web/src/lib/api/queries.ts
+++ b/web/src/lib/api/queries.ts
@@ -56,6 +56,8 @@ export const qk = {
   home:         ()                 => ['home'] as const,
   albumsAlpha:  ()                 => ['albumsAlpha'] as const,
   artistTracks: (artistId: string) => ['artistTracks', artistId] as const,
+  similarArtists:  (artistId: string) => ['similarArtists', artistId] as const,
+  artistTopTracks: (artistId: string) => ['artistTopTracks', artistId] as const,
   playlists:                (kind?: 'user' | 'system' | 'all') =>
     ['playlists', { kind: kind ?? 'user' }] as const,
   playlist:                 (id: string) => ['playlist', id] as const,
@@ -88,6 +90,22 @@ export function createAlbumQuery(id: string) {
   });
 }
 
+export function createSimilarArtistsQuery(id: string) {
+  return createQuery({
+    queryKey: qk.similarArtists(id),
+    queryFn: () => api.get<ArtistRef[]>(`/api/artists/${id}/similar`),
+    enabled: id.length > 0,
+  });
+}
+
+export function createArtistTopTracksQuery(id: string) {
+  return createQuery({
+    queryKey: qk.artistTopTracks(id),
+    queryFn: () => api.get<TrackRef[]>(`/api/artists/${id}/top-tracks`),
+    enabled: id.length > 0,
+  });
+}
+
 export function createSearchQuery(q: string) {
   return createQuery({
     queryKey: qk.search(q),
diff --git a/web/src/routes/artists/[id]/+page.svelte b/web/src/routes/artists/[id]/+page.svelte
index c79fe59e..3f829273 100644
--- a/web/src/routes/artists/[id]/+page.svelte
+++ b/web/src/routes/artists/[id]/+page.svelte
@@ -1,9 +1,16 @@
 <script lang="ts">
   import { Play } from 'lucide-svelte';
   import { page } from '$app/state';
-  import { createArtistQuery } from '$lib/api/queries';
+  import {
+    createArtistQuery,
+    createSimilarArtistsQuery,
+    createArtistTopTracksQuery
+  } from '$lib/api/queries';
   import { pageTitle } from '$lib/branding';
   import AlbumCard from '$lib/components/AlbumCard.svelte';
+  import ArtistCard from '$lib/components/ArtistCard.svelte';
+  import CompactTrackCard from '$lib/components/CompactTrackCard.svelte';
+  import HorizontalScrollRow from '$lib/components/HorizontalScrollRow.svelte';
   import LikeButton from '$lib/components/LikeButton.svelte';
   import LibrarySkeleton from '$lib/components/LibrarySkeleton.svelte';
   import ApiErrorBanner from '$lib/components/ApiErrorBanner.svelte';
@@ -11,13 +18,20 @@
   import { api } from '$lib/api/client';
   import { playQueue } from '$lib/player/store.svelte';
   import type { ApiError } from '$lib/api/client';
-  import type { TrackRef } from '$lib/api/types';
+  import type { ArtistRef, TrackRef } from '$lib/api/types';
 
   const id = $derived(page.params.id ?? '');
   const queryStore = $derived(createArtistQuery(id));
   const query = $derived($queryStore);
   const showSkeleton = useDelayed(() => query.isPending);
 
+  // Secondary sections, lazy-loaded alongside the detail. Each hides itself
+  // when empty (no similarity matches yet / user hasn't played this artist).
+  const similarStore = $derived(createSimilarArtistsQuery(id));
+  const similarQuery = $derived($similarStore);
+  const topTracksStore = $derived(createArtistTopTracksQuery(id));
+  const topTracksQuery = $derived($topTracksStore);
+
   const notFound = $derived(
     query.isError && (query.error as unknown as ApiError | undefined)?.code === 'not_found'
   );
@@ -97,5 +111,30 @@
         {/each}
       </div>
     {/if}
+
+    {#if (topTracksQuery.data?.length ?? 0) > 0}
+      {@const top = topTracksQuery.data ?? []}
+      <section class="space-y-3">
+        <HorizontalScrollRow rows={[top]} title="Top tracks" ariaLabel={`Top tracks for ${detail.name}`}>
+          {#snippet item(track: TrackRef, globalIdx: number)}
+            <CompactTrackCard {track} sectionTracks={top} index={globalIdx} />
+          {/snippet}
+        </HorizontalScrollRow>
+      </section>
+    {/if}
+
+    {#if (similarQuery.data?.length ?? 0) > 0}
+      <section class="space-y-3">
+        <HorizontalScrollRow
+          rows={[similarQuery.data ?? []]}
+          title="Similar artists"
+          ariaLabel="Similar artists"
+        >
+          {#snippet item(artist: ArtistRef)}
+            <div class="w-36"><ArtistCard {artist} /></div>
+          {/snippet}
+        </HorizontalScrollRow>
+      </section>
+    {/if}
   {/if}
 </div>
diff --git a/web/src/routes/artists/[id]/artist.test.ts b/web/src/routes/artists/[id]/artist.test.ts
index 38541d1d..5153893b 100644
--- a/web/src/routes/artists/[id]/artist.test.ts
+++ b/web/src/routes/artists/[id]/artist.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 import { render, screen } from '@testing-library/svelte';
 import { flushSync } from 'svelte';
 import { mockQuery } from '../../../test-utils/query';
@@ -16,13 +16,19 @@ vi.mock('$app/state', () => ({
 
 vi.mock('$lib/api/queries', () => ({
   qk: { artist: (id: string) => ['artist', id] },
-  createArtistQuery: vi.fn()
+  createArtistQuery: vi.fn(),
+  createSimilarArtistsQuery: vi.fn(),
+  createArtistTopTracksQuery: vi.fn()
 }));
 
 vi.mock('$lib/api/likes', () => emptyLikesMock());
 
 import ArtistPage from './+page.svelte';
-import { createArtistQuery } from '$lib/api/queries';
+import {
+  createArtistQuery,
+  createSimilarArtistsQuery,
+  createArtistTopTracksQuery
+} from '$lib/api/queries';
 
 function album(id: string, title: string, year?: number): AlbumRef {
   return {
@@ -40,6 +46,13 @@ afterEach(() => {
   state.pageParams = { id: 'abc' };
 });
 
+beforeEach(() => {
+  // Secondary sections default to empty so the existing album-grid assertions
+  // are unaffected; individual tests can override to exercise the new strips.
+  (createSimilarArtistsQuery as ReturnType<typeof vi.fn>).mockReturnValue(mockQuery({ data: [] }));
+  (createArtistTopTracksQuery as ReturnType<typeof vi.fn>).mockReturnValue(mockQuery({ data: [] }));
+});
+
 describe('artist detail page', () => {
   test('renders artist name, subtitle, and one AlbumCard per album', () => {
     const detail: ArtistDetail = {
@@ -54,6 +67,28 @@ describe('artist detail page', () => {
     expect(screen.getByRole('link', { name: /Second/ })).toHaveAttribute('href', '/albums/a2');
   });
 
+  test('renders top-tracks panel and similar-artists strip when present', () => {
+    const detail: ArtistDetail = {
+      id: 'abc', name: 'Alice', sort_name: 'Alice', album_count: 1, cover_url: '',
+      albums: [album('a1', 'First', 2020)]
+    };
+    (createArtistQuery as ReturnType<typeof vi.fn>).mockReturnValue(mockQuery({ data: detail }));
+    (createArtistTopTracksQuery as ReturnType<typeof vi.fn>).mockReturnValue(mockQuery({
+      data: [{
+        id: 't1', title: 'Hit Song', album_id: 'a1', album_title: 'First',
+        artist_id: 'abc', artist_name: 'Alice', duration_sec: 200, stream_url: '/s/t1'
+      }]
+    }));
+    (createSimilarArtistsQuery as ReturnType<typeof vi.fn>).mockReturnValue(mockQuery({
+      data: [{ id: 'sim1', name: 'Bob', sort_name: 'Bob', album_count: 2, cover_url: '' }]
+    }));
+    render(ArtistPage);
+    expect(screen.getByText(/top tracks/i)).toBeInTheDocument();
+    expect(screen.getByText('Hit Song')).toBeInTheDocument();
+    expect(screen.getByText(/similar artists/i)).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /Bob/ })).toHaveAttribute('href', '/artists/sim1');
+  });
+
   test('back link points to Library', () => {
     (createArtistQuery as ReturnType<typeof vi.fn>).mockReturnValue(mockQuery({
       data: { id: 'abc', name: 'Alice', sort_name: 'Alice', album_count: 0, cover_url: '', albums: [] }