Combine track search with live YouTube Music results

GET /tracks now merges the local catalog page with a live YouTube Music
search (deduplicated against tracks already provisioned locally) whenever a
name filter is given, appending the YouTube hits after the local matches and
carrying a continuation token for further pages. Each item is tagged with its
source via the new TrackSearchItemResponse/TracksSearchResponse shapes,
wrapping the existing TrackApplicationResponse or a raw YouTubeSongResult so
neither type had to change.

GET /youtube/search is removed along with its now-unused handler; the
web-player's explore page, its /api/tracks proxy, and the YouTube filler
helper are updated to call the combined endpoint instead of hitting the two
separately.

backend/Core/Musify.Application/Tracks/GetTracks.cs

@@ -1,22 +1,31 @@
 using ErrorOr;
 using Mediator;
 using Microsoft.EntityFrameworkCore;
-using Musify.Application.Shared;
+using Microsoft.Extensions.Logging;
 using Musify.Application.Tracks.Responses;
 using X.PagedList;
 using X.PagedList.EF;
 using Musify.Application.Contracts;
 using Musify.Domain.Entities;
+using Musify.Domain.ValueObjects;
 
 namespace Musify.Application.Tracks
 {
-    public record GetTracksQuery(string? Name, int PageNumber, int PageSize)
-        : IQuery<ErrorOr<PaginatedResponse<TrackApplicationResponse> >>;
+    public record GetTracksQuery(string? Name, int PageNumber, int PageSize, string? YoutubeContinuationToken = null)
+        : IQuery<ErrorOr<TracksSearchResponse>>;
 
-    public class GetTracksQueryHandler(IDatabase database)
-        : IQueryHandler<GetTracksQuery, ErrorOr<PaginatedResponse<TrackApplicationResponse>> >
+    public class GetTracksQueryHandler(
+        IDatabase database,
+        IYouTubeMusicService youTubeMusicService,
+        ILogger<GetTracksQueryHandler> logger)
+        : IQueryHandler<GetTracksQuery, ErrorOr<TracksSearchResponse>>
     {
-        public async ValueTask<ErrorOr<PaginatedResponse<TrackApplicationResponse> >> Handle(GetTracksQuery request, CancellationToken cancellationToken)
+        // Mirrors the web client's search-box debounce threshold: a query shorter than this is too
+        // likely to still be mid-keystroke to justify a live call to the YouTube Music API for every
+        // client that hits this endpoint.
+        private const int MinNameLengthForYouTubeSearch = 2;
+
+        public async ValueTask<ErrorOr<TracksSearchResponse>> Handle(GetTracksQuery request, CancellationToken cancellationToken)
         {
             var tracksQuery = database.UserHasTracks
                 .AsNoTracking()
@@ -39,11 +48,61 @@ namespace Musify.Application.Tracks
                 .Select(t => new { t.Track, ListensCount = t.Track.ListeningHistories.Count })
                 .ToPagedListAsync(request.PageNumber, request.PageSize, totalCount, cancellationToken);
 
-            var pagedTracks = new StaticPagedList<TrackApplicationResponse>(
-                pagedEntities.Select(x => TrackApplicationResponse.FromEntity(x.Track, x.ListensCount)),
-                pagedEntities.PageNumber, pagedEntities.PageSize, pagedEntities.TotalItemCount);
+            var localItems = pagedEntities
+                .Select(x => TrackSearchItemResponse.FromTrack(TrackApplicationResponse.FromEntity(x.Track, x.ListensCount)))
+                .ToList();
 
-            return PaginatedResponse<TrackApplicationResponse>.FromPagedList(pagedTracks);
+            var knownVideoIds = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var entry in pagedEntities)
+            {
+                if (entry.Track is ExternalTrack { Source: TrackSource.YouTube } external)
+                    knownVideoIds.Add(external.ExternalId);
+            }
+
+            var youtubeItems = new List<TrackSearchItemResponse>();
+            string? nextContinuationToken = null;
+            var youtubeUnavailable = false;
+
+            if (request.Name?.Trim().Length >= MinNameLengthForYouTubeSearch)
+                (youtubeItems, nextContinuationToken, youtubeUnavailable) =
+                    await SearchYouTubeAsync(request.Name, request.YoutubeContinuationToken, knownVideoIds, cancellationToken);
+
+            return new TracksSearchResponse(
+                [.. localItems, .. youtubeItems],
+                pagedEntities.PageNumber,
+                pagedEntities.PageSize,
+                pagedEntities.PageCount,
+                pagedEntities.TotalItemCount,
+                pagedEntities.HasPreviousPage,
+                pagedEntities.HasNextPage,
+                nextContinuationToken,
+                youtubeUnavailable);
+        }
+
+        private async Task<(List<TrackSearchItemResponse> Items, string? NextContinuationToken, bool Unavailable)> SearchYouTubeAsync(
+            string name,
+            string? continuationToken,
+            HashSet<string> knownVideoIds,
+            CancellationToken cancellationToken)
+        {
+            var searchResult = await youTubeMusicService.SearchSongsAsync(name, continuationToken ?? string.Empty, cancellationToken);
+            if (searchResult.IsError)
+            {
+                logger.LogInformation(
+                    "YouTube search unavailable while combining track results: {Error}", searchResult.FirstError.Description);
+                return ([], null, true);
+            }
+
+            var items = searchResult.Value.Items
+                .Where(song => knownVideoIds.Add(song.VideoId))
+                .Select(TrackSearchItemResponse.FromYouTubeSong)
+                .ToList();
+
+            var nextToken = string.IsNullOrEmpty(searchResult.Value.ContinuationToken)
+                ? null
+                : searchResult.Value.ContinuationToken;
+
+            return (items, nextToken, false);
         }
     }
 }