`, add optional `onPlay` prop, add `+ queue` button | | `web/src/lib/components/TrackRow.test.ts` | Update for refactor; add new tests | | `web/src/lib/components/AlbumCard.svelte` | Add `+ queue` button overlaid on the link | | `web/src/lib/components/AlbumCard.test.ts` | Add `+ queue` click test | | `web/src/lib/components/Shell.svelte` | Insert `` between brand and user menu | --- ## Task 1: `/api/radio` stub (server) **Files:** - Create: `internal/api/radio.go` - Create: `internal/api/radio_test.go` - Modify: `internal/api/api.go` This task ships the server-side `/api/radio?seed_track=` endpoint as a stub: validates the param, looks up the track, returns `{ tracks: [] }` using the existing `trackRefFrom` + parent-album/artist-name resolve pattern from `handleGetTrack`. - [ ] **Step 1: Write failing tests** Create `internal/api/radio_test.go`: ```go package api import ( "encoding/json" "net/http" "net/http/httptest" "testing" "github.com/go-chi/chi/v5" ) func newRadioRouter(h *handlers) chi.Router { r := chi.NewRouter() r.Get("/api/radio", h.handleRadio) return r } func TestHandleRadio_Stub_ReturnsSeedOnly(t *testing.T) { h, pool := testHandlers(t) truncateLibrary(t, pool) artist := seedArtist(t, pool, "Beatles") album := seedAlbum(t, pool, artist.ID, "Abbey Road", 1969) track := seedTrack(t, pool, album.ID, artist.ID, "Something", 3, 183_000) req := httptest.NewRequest(http.MethodGet, "/api/radio?seed_track="+uuidToString(track.ID), nil) w := httptest.NewRecorder() newRadioRouter(h).ServeHTTP(w, req) if w.Code != http.StatusOK { t.Fatalf("status = %d body=%s", w.Code, w.Body.String()) } var got struct { Tracks []TrackRef `json:"tracks"` } if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil { t.Fatalf("decode: %v", err) } if len(got.Tracks) != 1 { t.Fatalf("len=%d, want 1", len(got.Tracks)) } if got.Tracks[0].Title != "Something" { t.Errorf("title=%q", got.Tracks[0].Title) } if got.Tracks[0].AlbumTitle != "Abbey Road" || got.Tracks[0].ArtistName != "Beatles" { t.Errorf("ref = %+v", got.Tracks[0]) } } func TestHandleRadio_NotFound(t *testing.T) { h, pool := testHandlers(t) truncateLibrary(t, pool) req := httptest.NewRequest(http.MethodGet, "/api/radio?seed_track=00000000-0000-0000-0000-000000000000", nil) w := httptest.NewRecorder() newRadioRouter(h).ServeHTTP(w, req) if w.Code != http.StatusNotFound { t.Fatalf("status = %d", w.Code) } } func TestHandleRadio_MissingSeed(t *testing.T) { h, _ := testHandlers(t) req := httptest.NewRequest(http.MethodGet, "/api/radio", nil) w := httptest.NewRecorder() newRadioRouter(h).ServeHTTP(w, req) if w.Code != http.StatusBadRequest { t.Errorf("status=%d, want 400", w.Code) } } func TestHandleRadio_BlankSeed(t *testing.T) { h, _ := testHandlers(t) req := httptest.NewRequest(http.MethodGet, "/api/radio?seed_track=%20%20", nil) w := httptest.NewRecorder() newRadioRouter(h).ServeHTTP(w, req) if w.Code != http.StatusBadRequest { t.Errorf("status=%d, want 400", w.Code) } } func TestHandleRadio_BadUUID(t *testing.T) { h, _ := testHandlers(t) req := httptest.NewRequest(http.MethodGet, "/api/radio?seed_track=not-a-uuid", nil) w := httptest.NewRecorder() newRadioRouter(h).ServeHTTP(w, req) if w.Code != http.StatusBadRequest { t.Errorf("status=%d, want 400", w.Code) } } ``` - [ ] **Step 2: Run tests, confirm they fail** Run: `go test ./internal/api -run TestHandleRadio -v` Expected: FAIL — `h.handleRadio undefined`. - [ ] **Step 3: Implement `internal/api/radio.go`** ```go package api import ( "errors" "net/http" "strings" "github.com/jackc/pgx/v5" "git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq" ) // RadioResponse is the body of GET /api/radio. type RadioResponse struct { Tracks []TrackRef `json:"tracks"` } // handleRadio implements GET /api/radio?seed_track=. // // M6 stub: returns a queue containing only the seed track. The full M4 // implementation (similarity-based candidate pool + scoring) replaces the // body without changing the request/response shape. func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) { raw := strings.TrimSpace(r.URL.Query().Get("seed_track")) if raw == "" { writeErr(w, http.StatusBadRequest, "bad_request", "seed_track is required") return } id, ok := parseUUID(raw) if !ok { writeErr(w, http.StatusBadRequest, "bad_request", "invalid seed_track id") return } q := dbq.New(h.pool) track, err := q.GetTrackByID(r.Context(), id) if err != nil { if errors.Is(err, pgx.ErrNoRows) { writeErr(w, http.StatusNotFound, "not_found", "seed_track not found") return } h.logger.Error("api: get radio seed track failed", "err", err) writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed") return } album, err := q.GetAlbumByID(r.Context(), track.AlbumID) if err != nil { h.logger.Error("api: get radio seed album failed", "err", err) writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed") return } artist, err := q.GetArtistByID(r.Context(), track.ArtistID) if err != nil { h.logger.Error("api: get radio seed artist failed", "err", err) writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed") return } writeJSON(w, http.StatusOK, RadioResponse{ Tracks: []TrackRef{trackRefFrom(track, album.Title, artist.Name)}, }) } ``` - [ ] **Step 4: Register the route in `internal/api/api.go`** Find the authed group and add `/radio` next to `/search`: ```go authed.Get("/search", h.handleSearch) authed.Get("/radio", h.handleRadio) ``` - [ ] **Step 5: Run tests, confirm pass** Run: `go test ./internal/api -run TestHandleRadio -v` Expected: PASS — 5 tests. - [ ] **Step 6: Lint + full server tests** Run: `golangci-lint run ./...` Expected: clean. Run: `go test -short -race ./...` Expected: all packages PASS. - [ ] **Step 7: Commit** ```bash git add internal/api/radio.go internal/api/radio_test.go internal/api/api.go git commit -m "feat(api): add /api/radio stub returning the seed track only M6 stub. Validates seed_track param (400 on missing/blank/bad UUID), looks up the track (404 on miss), returns RadioResponse with a single TrackRef. M4 will replace the body with similarity-driven candidate pool + scoring; the request/response shape is final." ``` --- ## Task 2: Web types — `SearchResponse`, `RadioResponse` **Files:** - Modify: `web/src/lib/api/types.ts` Foundation for everything downstream. No tests — pure type declarations. - [ ] **Step 1: Open `web/src/lib/api/types.ts` and append the new types** After the existing `AlbumDetail` declaration: ```ts export type SearchResponse = { artists: Page; albums: Page; tracks: Page; }; export type RadioResponse = { tracks: TrackRef[]; }; ``` - [ ] **Step 2: Type-check** Run: `cd web && npm run check` Expected: `0 ERRORS 0 WARNINGS`. - [ ] **Step 3: Commit** ```bash git add web/src/lib/api/types.ts git commit -m "feat(web): add SearchResponse and RadioResponse types" ``` --- ## Task 3: Player store — `enqueueTrack`, `enqueueTracks`, `playRadio` **Files:** - Modify: `web/src/lib/player/store.svelte.ts` - Modify: `web/src/lib/player/store.test.ts` Adds three new exports. Existing 24 tests must keep passing. - [ ] **Step 1: Append failing tests to `web/src/lib/player/store.test.ts`** At the bottom of the file, append: ```ts import { enqueueTrack, enqueueTracks, playRadio } from './store.svelte'; import * as client from '$lib/api/client'; describe('player store — enqueue + playRadio', () => { test('enqueueTrack appends to a non-empty queue, _index unchanged', () => { playQueue([track('1'), track('2')], 1); enqueueTrack(track('3')); expect(player.queue.length).toBe(3); expect(player.queue[2].id).toBe('3'); expect(player.index).toBe(1); }); test('enqueueTrack on idle (empty queue) sets index=0 and _state stays idle', () => { playQueue([]); // explicit reset expect(player.state).toBe('idle'); enqueueTrack(track('1')); expect(player.queue.length).toBe(1); expect(player.index).toBe(0); expect(player.state).toBe('idle'); // append must not auto-play }); test('enqueueTracks([]) is a no-op', () => { playQueue([track('1')]); enqueueTracks([]); expect(player.queue.length).toBe(1); }); test('enqueueTracks concatenates non-empty list', () => { playQueue([track('1')]); enqueueTracks([track('2'), track('3')]); expect(player.queue.map((t) => t.id)).toEqual(['1', '2', '3']); }); test('playRadio fetches /api/radio and feeds tracks into playQueue', async () => { const apiGet = vi.spyOn(client.api, 'get').mockResolvedValueOnce({ tracks: [track('seed'), track('next')] }); await playRadio('seed'); expect(apiGet).toHaveBeenCalledWith('/api/radio?seed_track=seed'); expect(player.queue.length).toBe(2); expect(player.index).toBe(0); expect(player.state).toBe('loading'); // playQueue sets state='loading' apiGet.mockRestore(); }); test('playRadio with empty response leaves queue alone', async () => { playQueue([track('a')]); const apiGet = vi.spyOn(client.api, 'get').mockResolvedValueOnce({ tracks: [] }); await playRadio('seed'); expect(player.queue.map((t) => t.id)).toEqual(['a']); apiGet.mockRestore(); }); }); ``` - [ ] **Step 2: Run tests, confirm new ones fail** Run: `cd web && npm test -- src/lib/player/store.test.ts` Expected: FAIL — `enqueueTrack`, `enqueueTracks`, `playRadio` not exported. The 24 existing tests still pass. - [ ] **Step 3: Append the new actions to `web/src/lib/player/store.svelte.ts`** At the bottom, after `reportStateFromAudio`: ```ts import { api } from '$lib/api/client'; import type { RadioResponse } from '$lib/api/types'; export function enqueueTrack(t: TrackRef): void { _queue = [..._queue, t]; if (_state === 'idle') _index = 0; } export function enqueueTracks(ts: TrackRef[]): void { if (ts.length === 0) return; _queue = [..._queue, ...ts]; if (_state === 'idle') _index = 0; } export async function playRadio(seedTrackId: string): Promise { const resp = await api.get( `/api/radio?seed_track=${encodeURIComponent(seedTrackId)}` ); if (resp.tracks.length > 0) playQueue(resp.tracks, 0); } ``` Note: hoist the `import { api } from '$lib/api/client'` and `import type { RadioResponse } from '$lib/api/types'` to the top of the file alongside the existing imports. - [ ] **Step 4: Run tests, confirm all pass** Run: `cd web && npm test -- src/lib/player/store.test.ts` Expected: PASS — 30 tests (24 existing + 6 new). - [ ] **Step 5: Type-check** Run: `cd web && npm run check` Expected: `0 ERRORS 0 WARNINGS`. - [ ] **Step 6: Commit** ```bash git add web/src/lib/player/store.svelte.ts web/src/lib/player/store.test.ts git commit -m "feat(web): add enqueueTrack, enqueueTracks, playRadio to player store enqueueTrack/enqueueTracks append to the queue without disturbing playback state (no auto-play on append, no state mutation when queue was non-empty). playRadio fetches /api/radio?seed_track= and feeds the response into playQueue. Empty response leaves queue alone." ``` --- ## Task 4: Query helpers — `createSearchQuery` + three infinite queries **Files:** - Modify: `web/src/lib/api/queries.ts` - Modify: `web/src/lib/api/queries.test.ts` Adds `qk.search*` keys and four query factories. Tests cover only the keys (TanStack's own behavior is already trusted). - [ ] **Step 1: Append failing tests to `web/src/lib/api/queries.test.ts`** ```ts import { qk } from './queries'; describe('qk search keys', () => { test('search summary key includes q', () => { expect(qk.search('foo')).toEqual(['search', { q: 'foo' }]); }); test('searchArtists key includes q', () => { expect(qk.searchArtists('foo')).toEqual(['searchArtists', { q: 'foo' }]); }); test('searchAlbums key includes q', () => { expect(qk.searchAlbums('foo')).toEqual(['searchAlbums', { q: 'foo' }]); }); test('searchTracks key includes q', () => { expect(qk.searchTracks('foo')).toEqual(['searchTracks', { q: 'foo' }]); }); }); ``` - [ ] **Step 2: Run tests, confirm new ones fail** Run: `cd web && npm test -- src/lib/api/queries.test.ts` Expected: FAIL — `qk.search` undefined. - [ ] **Step 3: Extend `web/src/lib/api/queries.ts`** Append these imports + symbols: ```ts import type { SearchResponse } from './types'; export const SEARCH_SUMMARY_LIMIT = 10; export const SEARCH_FACET_PAGE_SIZE = 50; ``` Extend the `qk` object with the four new keys (place them after the existing entries): ```ts export const qk = { artists: (sort: ArtistSort) => ['artists', { sort }] as const, artist: (id: string) => ['artist', id] as const, album: (id: string) => ['album', id] as const, search: (q: string) => ['search', { q }] as const, searchArtists: (q: string) => ['searchArtists', { q }] as const, searchAlbums: (q: string) => ['searchAlbums', { q }] as const, searchTracks: (q: string) => ['searchTracks', { q }] as const, }; ``` Append the query factories after `createAlbumQuery`: ```ts export function createSearchQuery(q: string) { return createQuery({ queryKey: qk.search(q), queryFn: () => api.get( `/api/search?q=${encodeURIComponent(q)}&limit=${SEARCH_SUMMARY_LIMIT}` ), enabled: q.length > 0 }); } export function createSearchArtistsInfiniteQuery(q: string) { return createInfiniteQuery({ queryKey: qk.searchArtists(q), queryFn: ({ pageParam = 0 }) => api.get( `/api/search?q=${encodeURIComponent(q)}&limit=${SEARCH_FACET_PAGE_SIZE}&offset=${pageParam}` ).then((r) => r.artists), initialPageParam: 0, getNextPageParam: (last) => { const loaded = last.offset + last.items.length; return loaded >= last.total ? undefined : loaded; }, enabled: q.length > 0 }); } export function createSearchAlbumsInfiniteQuery(q: string) { return createInfiniteQuery({ queryKey: qk.searchAlbums(q), queryFn: ({ pageParam = 0 }) => api.get( `/api/search?q=${encodeURIComponent(q)}&limit=${SEARCH_FACET_PAGE_SIZE}&offset=${pageParam}` ).then((r) => r.albums), initialPageParam: 0, getNextPageParam: (last) => { const loaded = last.offset + last.items.length; return loaded >= last.total ? undefined : loaded; }, enabled: q.length > 0 }); } export function createSearchTracksInfiniteQuery(q: string) { return createInfiniteQuery({ queryKey: qk.searchTracks(q), queryFn: ({ pageParam = 0 }) => api.get( `/api/search?q=${encodeURIComponent(q)}&limit=${SEARCH_FACET_PAGE_SIZE}&offset=${pageParam}` ).then((r) => r.tracks), initialPageParam: 0, getNextPageParam: (last) => { const loaded = last.offset + last.items.length; return loaded >= last.total ? undefined : loaded; }, enabled: q.length > 0 }); } ``` - [ ] **Step 4: Run tests, confirm all pass** Run: `cd web && npm test -- src/lib/api/queries.test.ts` Expected: PASS — 7 tests. - [ ] **Step 5: Type-check** Run: `cd web && npm run check` Expected: `0 ERRORS 0 WARNINGS`. - [ ] **Step 6: Commit** ```bash git add web/src/lib/api/queries.ts web/src/lib/api/queries.test.ts git commit -m "feat(web): add search query helpers (summary + 3 facet infinite queries) createSearchQuery hits /api/search with limit=10 (the main /search page summary). createSearchArtistsInfiniteQuery / createSearchAlbumsInfiniteQuery / createSearchTracksInfiniteQuery each hit /api/search with limit=50 and project to their own facet, used by the per-facet overflow pages. All four are gated by q.length > 0 so empty queries don't fire." ``` --- ## Task 5: `TrackRow` refactor — `

` + `onPlay` + `+ queue` **Files:** - Modify: `web/src/lib/components/TrackRow.svelte` - Modify: `web/src/lib/components/TrackRow.test.ts` Two structural changes: 1. Outer element becomes `

` so a real `

Artists

Albums

Tracks

Artists matching '{q}'

Albums matching '{q}'

Tracks matching '{q}'