minstrel/docs/superpowers/plans/2026-04-30-m6a-home-page.md

M6a — Home page redesign + library list relocation — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace / with a personalized home page composed of independent horizontal-scroll rows (Recently added · Rediscover · Most played · Last played), relocate the library list to /library/artists and /library/albums as wrapping grids with alphabetical dividers, polish <AlbumCard> to the FabledSword bar, retire <ArtistRow> (and its click-target bug) in favor of a circular <ArtistCard>, and ship play affordances on album/artist cards.

Architecture: No DB migration. Backend adds composite SQL queries for each home section + new alpha-with-cover variants for the library lists. New internal/recommendation/home.go runs the section queries in parallel and assembles a single HomePayload. New GET /api/home, GET /api/library/albums, GET /api/artists/{id}/tracks endpoints. Frontend introduces four reusable components (<HorizontalScrollRow>, <ArtistCard>, <CompactTrackCard>, <AlphabeticalGrid>), polishes <AlbumCard>, and ships three new routes.

Tech Stack: Go 1.23 · pgx/v5 + sqlc · Postgres (no migration) · SvelteKit 2 / Svelte 5 (runes) · TanStack Query · Vitest · Lucide icons · FabledSword design tokens.

Spec: docs/superpowers/specs/2026-04-30-m6a-home-page-design.md. Read it before starting — every decision is explained there.

Memory dependencies: project_design_system.md (FabledSword tokens), project_subsonic_legacy.md (/api/* is primary), project_no_github.md (Forgejo MCP for PR ops), project_git_workflow.md (commit on dev; PR to main separately), project_ui_quality.md (this slice raises the bar — no half-built UI).

---

File map

Backend — create

• internal/recommendation/home.go — HomeData composite service + HomePayload struct
• internal/recommendation/home_integration_test.go
• internal/api/home.go — GET /api/home handler
• internal/api/home_test.go
• internal/api/library_albums.go — GET /api/library/albums handler
• internal/api/library_albums_test.go

Backend — modify

• internal/db/queries/recommendation.sql — append home-section + rediscover queries
• internal/db/queries/albums.sql — append ListRecentlyAddedAlbumsWithArtist, ListAlbumsAlphaWithArtist, CountAlbums
• internal/db/queries/artists.sql — append ListArtistsAlphaWithCovers
• internal/db/queries/tracks.sql — append ListArtistTracksForUser
• internal/db/dbq/* — regenerated by sqlc generate
• internal/api/types.go — extend ArtistRef + AlbumRef
• internal/api/convert.go — extend artistRefFrom + albumRefFrom to populate new fields
• internal/api/library.go — replace ListArtistsAlpha call with ListArtistsAlphaWithCovers; add handleGetArtistTracks
• internal/api/library_test.go — extend with artist-tracks tests
• internal/api/api.go — register /api/home, /api/library/albums, /api/artists/{id}/tracks routes

Frontend — create

• web/src/lib/api/home.ts — listHome() + createHomeQuery()
• web/src/lib/api/home.test.ts
• web/src/lib/api/albums.ts — listAlbumsAlpha() + createAlbumsAlphaInfiniteQuery() + listAlbumTracks() if extracted later
• web/src/lib/api/albums.test.ts
• web/src/lib/components/HorizontalScrollRow.svelte
• web/src/lib/components/HorizontalScrollRow.test.ts
• web/src/lib/components/ArtistCard.svelte
• web/src/lib/components/ArtistCard.test.ts
• web/src/lib/components/CompactTrackCard.svelte
• web/src/lib/components/CompactTrackCard.test.ts
• web/src/lib/components/AlphabeticalGrid.svelte
• web/src/lib/components/AlphabeticalGrid.test.ts
• web/src/routes/library/artists/+page.svelte
• web/src/routes/library/albums/+page.svelte

Frontend — modify

• web/src/lib/api/types.ts — extend ArtistRef + AlbumRef, add HomePayload
• web/src/lib/api/queries.ts — add qk.home(), qk.albumsAlpha(), qk.artistTracks()
• web/src/lib/api/artists.ts — create or extend with listArtistTracks()
• web/src/lib/components/AlbumCard.svelte — FabledSword polish + play-button overlay + sort_title exposure
• web/src/lib/components/AlbumCard.test.ts — extend with play-overlay test
• web/src/lib/components/Shell.svelte — nav order updated
• web/src/lib/components/Shell.test.ts — assert new nav items
• web/src/routes/+page.svelte — full rewrite as home page
• web/src/routes/artists.test.ts — adjust expectations now that / is the home

Frontend — delete

• web/src/lib/components/ArtistRow.svelte (retired with the click-target bug)
• web/src/lib/components/ArtistRow.test.ts

---

Task list

Task 1 — SQL: Recently added + Most played + Last played queries

Files:

• Modify: internal/db/queries/albums.sql — append ListRecentlyAddedAlbumsWithArtist

• Modify: internal/db/queries/recommendation.sql — append ListMostPlayedTracksForUser, ListLastPlayedArtistsForUser

• Regenerate: internal/db/dbq/*

• Step 1.1: Append ListRecentlyAddedAlbumsWithArtist to albums.sql

Append at the bottom of internal/db/queries/albums.sql:

-- name: ListRecentlyAddedAlbumsWithArtist :many
-- M6a: recently-added albums joined with artist_name + artist_id for the
-- home-page section. created_at is the row-insert timestamp from the
-- scanner — the closest proxy to "added to library". Stable secondary
-- ordering by id keeps pagination tie-break deterministic.
SELECT sqlc.embed(albums), artists.name AS artist_name
FROM albums
JOIN artists ON artists.id = albums.artist_id
ORDER BY albums.created_at DESC, albums.id
LIMIT $1;

• Step 1.2: Append ListMostPlayedTracksForUser to recommendation.sql

Append at the bottom of internal/db/queries/recommendation.sql:

-- name: ListMostPlayedTracksForUser :many
-- M6a: top-N tracks by completed-play count for the user. was_skipped
-- excludes skips so a user spamming next doesn't fabricate a top track.
-- Quarantined tracks (per-user soft-hide from M5b) are filtered out.
SELECT sqlc.embed(t),
       albums.title AS album_title,
       artists.name AS artist_name
FROM tracks t
JOIN albums  ON albums.id  = t.album_id
JOIN artists ON artists.id = t.artist_id
JOIN play_events pe ON pe.track_id = t.id
WHERE pe.user_id = $1
  AND pe.was_skipped = false
  AND NOT EXISTS (
      SELECT 1 FROM lidarr_quarantine q
      WHERE q.user_id = $1 AND q.track_id = t.id
  )
GROUP BY t.id, t.title, t.album_id, t.artist_id, t.duration_ms, t.file_path,
         t.file_format, t.file_size, t.bitrate, t.track_number, t.disc_number,
         t.mbid, t.genre, t.added_at, t.updated_at,
         albums.title, artists.name
ORDER BY count(*) DESC, t.id
LIMIT $2;

• Step 1.3: Append ListLastPlayedArtistsForUser to recommendation.sql

Append at the bottom of internal/db/queries/recommendation.sql:

-- name: ListLastPlayedArtistsForUser :many
-- M6a: artists ranked by max(play_events.started_at) for the user, with
-- a derived cover_album_id via a representative-album lateral join (most
-- recent album that has cover_art_path set). album_count joined for the
-- ArtistRef wire shape.
SELECT sqlc.embed(a),
       cov.id        AS cover_album_id,
       cnt.album_count::bigint AS album_count,
       max_started.started_at::timestamptz AS last_played_at
FROM artists a
JOIN LATERAL (
    SELECT max(pe.started_at) AS started_at
    FROM play_events pe
    JOIN tracks t ON t.id = pe.track_id
    WHERE pe.user_id = $1 AND t.artist_id = a.id
) max_started ON max_started.started_at IS NOT NULL
LEFT JOIN LATERAL (
    SELECT id FROM albums
    WHERE artist_id = a.id AND cover_art_path IS NOT NULL
    ORDER BY created_at DESC LIMIT 1
) cov ON true
LEFT JOIN LATERAL (
    SELECT count(*) AS album_count
    FROM albums WHERE artist_id = a.id
) cnt ON true
ORDER BY max_started.started_at DESC, a.id
LIMIT $2;

• Step 1.4: Regenerate sqlc

Run:

cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && sqlc generate
go build ./...
go vet ./...

Expected: clean build. New methods ListRecentlyAddedAlbumsWithArtist, ListMostPlayedTracksForUser, ListLastPlayedArtistsForUser appear in internal/db/dbq/.

• Step 1.5: Commit

git add internal/db/queries/albums.sql \
        internal/db/queries/recommendation.sql \
        internal/db/dbq/
git commit -m "feat(db): add M6a home-section queries (recently added, most played, last played)"

---

Task 2 — SQL: Rediscover queries (albums + artists, with fallbacks)

Files:

• Modify: internal/db/queries/recommendation.sql

• Regenerate: internal/db/dbq/*

• Step 2.1: Append rediscover-album queries

Append at the bottom of internal/db/queries/recommendation.sql:

-- name: ListRediscoverAlbumsForUser :many
-- M6a: albums liked >30 days ago AND not played in the last 14 days,
-- ordered by longest-since-last-play first. The HAVING clause uses an
-- epoch sentinel so albums with NO plays count as eligible (their
-- "last play" is treated as 1970, which is always >14 days ago).
WITH eligible AS (
    SELECT al.id        AS album_id,
           gla.liked_at,
           max(pe.started_at) AS last_played
    FROM general_likes_albums gla
    JOIN albums al ON al.id = gla.album_id
    LEFT JOIN tracks t       ON t.album_id = al.id
    LEFT JOIN play_events pe ON pe.track_id = t.id AND pe.user_id = $1
    WHERE gla.user_id = $1
      AND gla.liked_at < now() - interval '30 days'
    GROUP BY al.id, gla.liked_at
    HAVING COALESCE(max(pe.started_at), '1970-01-01'::timestamptz)
           < now() - interval '14 days'
)
SELECT sqlc.embed(albums), artists.name AS artist_name
FROM eligible e
JOIN albums  ON albums.id = e.album_id
JOIN artists ON artists.id = albums.artist_id
ORDER BY (now() - COALESCE(e.last_played, e.liked_at)) DESC, albums.id
LIMIT $2;

-- name: ListRediscoverAlbumsFallbackForUser :many
-- M6a: random sample of liked albums for the user. The Go service uses
-- this to top up the rediscover row when ListRediscoverAlbumsForUser
-- returns fewer than `limit` rows.
SELECT sqlc.embed(albums), artists.name AS artist_name
FROM general_likes_albums gla
JOIN albums  ON albums.id = gla.album_id
JOIN artists ON artists.id = albums.artist_id
WHERE gla.user_id = $1
ORDER BY random()
LIMIT $2;

• Step 2.2: Append rediscover-artist queries

Append at the bottom of internal/db/queries/recommendation.sql:

-- name: ListRediscoverArtistsForUser :many
-- M6a: artists liked >30 days ago AND none of their tracks played in the
-- last 14 days, ordered by longest-since-last-play. cover_album_id is
-- derived from a representative album (LEFT JOIN LATERAL).
WITH eligible AS (
    SELECT a.id        AS artist_id,
           gla.liked_at,
           max(pe.started_at) AS last_played
    FROM general_likes_artists gla
    JOIN artists a ON a.id = gla.artist_id
    LEFT JOIN tracks t       ON t.artist_id = a.id
    LEFT JOIN play_events pe ON pe.track_id = t.id AND pe.user_id = $1
    WHERE gla.user_id = $1
      AND gla.liked_at < now() - interval '30 days'
    GROUP BY a.id, gla.liked_at
    HAVING COALESCE(max(pe.started_at), '1970-01-01'::timestamptz)
           < now() - interval '14 days'
)
SELECT sqlc.embed(artists),
       cov.id AS cover_album_id,
       cnt.album_count::bigint AS album_count
FROM eligible e
JOIN artists ON artists.id = e.artist_id
LEFT JOIN LATERAL (
    SELECT id FROM albums
    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
    ORDER BY created_at DESC LIMIT 1
) cov ON true
LEFT JOIN LATERAL (
    SELECT count(*) AS album_count
    FROM albums WHERE artist_id = artists.id
) cnt ON true
ORDER BY (now() - COALESCE(e.last_played, e.liked_at)) DESC, artists.id
LIMIT $2;

-- name: ListRediscoverArtistsFallbackForUser :many
SELECT sqlc.embed(artists),
       cov.id AS cover_album_id,
       cnt.album_count::bigint AS album_count
FROM general_likes_artists gla
JOIN artists ON artists.id = gla.artist_id
LEFT JOIN LATERAL (
    SELECT id FROM albums
    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
    ORDER BY created_at DESC LIMIT 1
) cov ON true
LEFT JOIN LATERAL (
    SELECT count(*) AS album_count
    FROM albums WHERE artist_id = artists.id
) cnt ON true
WHERE gla.user_id = $1
ORDER BY random()
LIMIT $2;

• Step 2.3: Regenerate sqlc

Run:

cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && sqlc generate
go build ./...
go vet ./...

Expected: clean build. Four new methods (ListRediscoverAlbumsForUser, ListRediscoverAlbumsFallbackForUser, ListRediscoverArtistsForUser, ListRediscoverArtistsFallbackForUser) appear in internal/db/dbq/recommendation.sql.go.

• Step 2.4: Commit

git add internal/db/queries/recommendation.sql internal/db/dbq/
git commit -m "feat(db): add M6a rediscover queries (albums + artists, with fallbacks)"

---

Task 3 — SQL: Library list + artist tracks queries

Files:

• Modify: internal/db/queries/artists.sql

• Modify: internal/db/queries/albums.sql

• Modify: internal/db/queries/tracks.sql

• Regenerate: internal/db/dbq/*

• Step 3.1: Append ListArtistsAlphaWithCovers to artists.sql

Append at the bottom of internal/db/queries/artists.sql:

-- name: ListArtistsAlphaWithCovers :many
-- M6a: alpha-sorted artist list with derived cover_album_id (most-recent
-- album whose cover_art_path is set). Replaces ListArtistsAlpha for the
-- /api/artists?sort=alpha branch — the new column is appended, so the
-- alpha branch is purely additive on the wire. album_count is computed
-- in the same query to drop the old N+1 in handleListArtists.
SELECT sqlc.embed(artists),
       cov.id AS cover_album_id,
       cnt.album_count::bigint AS album_count
FROM artists
LEFT JOIN LATERAL (
    SELECT id FROM albums
    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
    ORDER BY created_at DESC LIMIT 1
) cov ON true
LEFT JOIN LATERAL (
    SELECT count(*) AS album_count
    FROM albums WHERE artist_id = artists.id
) cnt ON true
ORDER BY artists.sort_name, artists.name, artists.id
LIMIT $1 OFFSET $2;

• Step 3.2: Append ListAlbumsAlphaWithArtist + CountAlbums to albums.sql

Append at the bottom of internal/db/queries/albums.sql:

-- name: ListAlbumsAlphaWithArtist :many
-- M6a: alpha-sorted album list joined with artist_name. Used by
-- /api/library/albums for the wrapping-grid page. Stable id-tiebreak.
SELECT sqlc.embed(albums), artists.name AS artist_name
FROM albums
JOIN artists ON artists.id = albums.artist_id
ORDER BY albums.sort_title, albums.id
LIMIT $1 OFFSET $2;

-- name: CountAlbums :one
-- M6a: total album count for the /api/library/albums envelope.
SELECT COUNT(*) FROM albums;

• Step 3.3: Append ListArtistTracksForUser to tracks.sql

Append at the bottom of internal/db/queries/tracks.sql:

-- name: ListArtistTracksForUser :many
-- M6a: every track for the artist across their albums, with album_title
-- and artist_name joined. Honors per-user lidarr_quarantine. Used by
-- /api/artists/{id}/tracks for the artist-card play affordance, which
-- shuffles client-side. Ordering matches album/track natural order so
-- the shuffle has a deterministic input.
SELECT sqlc.embed(t),
       albums.title AS album_title,
       artists.name AS artist_name
FROM tracks t
JOIN albums  ON albums.id  = t.album_id
JOIN artists ON artists.id = t.artist_id
WHERE t.artist_id = $1
  AND NOT EXISTS (
      SELECT 1 FROM lidarr_quarantine q
      WHERE q.user_id = $2 AND q.track_id = t.id
  )
ORDER BY albums.release_date NULLS LAST, albums.sort_title,
         t.disc_number NULLS FIRST, t.track_number NULLS FIRST, t.id;

• Step 3.4: Regenerate sqlc + build

cd /home/bvandeusen/Nextcloud/Projects/Minstrel/minstrel && sqlc generate
go build ./...
go vet ./...

Expected: clean build. New methods appear in internal/db/dbq/.

• Step 3.5: Commit

git add internal/db/queries/artists.sql \
        internal/db/queries/albums.sql \
        internal/db/queries/tracks.sql \
        internal/db/dbq/
git commit -m "feat(db): add M6a library-list + artist-tracks queries"

---

Task 4 — Recommendation service: HomeData

Files:

• Create: internal/recommendation/home.go

• Create: internal/recommendation/home_integration_test.go

• Step 4.1: Write failing integration test (new-user empty payload)

Create internal/recommendation/home_integration_test.go:

package recommendation

import (
	"context"
	"testing"

	"github.com/jackc/pgx/v5/pgtype"
)

func TestHomeData_NewUser_AllSectionsEmpty(t *testing.T) {
	pool := newPool(t)
	user := seedUser(t, pool, "home-newuser")

	got, err := HomeData(context.Background(), pool, user.ID)
	if err != nil {
		t.Fatalf("HomeData: %v", err)
	}
	if got == nil {
		t.Fatal("HomeData returned nil payload")
	}
	if len(got.RecentlyAddedAlbums) != 0 {
		t.Errorf("RecentlyAddedAlbums len = %d, want 0", len(got.RecentlyAddedAlbums))
	}
	if len(got.RediscoverAlbums) != 0 {
		t.Errorf("RediscoverAlbums len = %d, want 0", len(got.RediscoverAlbums))
	}
	if len(got.RediscoverArtists) != 0 {
		t.Errorf("RediscoverArtists len = %d, want 0", len(got.RediscoverArtists))
	}
	if len(got.MostPlayedTracks) != 0 {
		t.Errorf("MostPlayedTracks len = %d, want 0", len(got.MostPlayedTracks))
	}
	if len(got.LastPlayedArtists) != 0 {
		t.Errorf("LastPlayedArtists len = %d, want 0", len(got.LastPlayedArtists))
	}
}

// Compile-time assert that pgtype.UUID is a valid map key — used by the
// service when de-duping rediscover fallback rows. If this changes, the
// service needs to switch to keying by string.
var _ = func() pgtype.UUID { return pgtype.UUID{} }

• Step 4.2: Run test to verify it fails

Run:

go test ./internal/recommendation/ -run TestHomeData_NewUser_AllSectionsEmpty -count=1

Expected: FAIL with "undefined: HomeData" or similar.

• Step 4.3: Write the service

Create internal/recommendation/home.go:

// home.go is the M6a per-user composite home-page service. Reads five
// sections (recently added, rediscover albums, rediscover artists, most
// played tracks, last played artists) in parallel via goroutines and
// assembles them into a single payload for /api/home.
package recommendation

import (
	"context"
	"fmt"
	"sync"

	"github.com/jackc/pgx/v5/pgtype"
	"github.com/jackc/pgx/v5/pgxpool"

	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)

// Section size caps. SPA splits these into rows on the page.
const (
	HomeRecentlyAddedLimit = 50
	HomeRediscoverLimit    = 25
	HomeMostPlayedLimit    = 75
	HomeLastPlayedLimit    = 25
)

// HomePayload is the composite returned by HomeData. All slices are
// non-nil at return time so the API handler can encode `[]` rather than
// `null` for empty sections.
type HomePayload struct {
	RecentlyAddedAlbums []dbq.ListRecentlyAddedAlbumsWithArtistRow
	RediscoverAlbums    []dbq.ListRediscoverAlbumsForUserRow
	RediscoverArtists   []dbq.ListRediscoverArtistsForUserRow
	MostPlayedTracks    []dbq.ListMostPlayedTracksForUserRow
	LastPlayedArtists   []dbq.ListLastPlayedArtistsForUserRow
}

// HomeData runs five queries in parallel and assembles the payload.
// Rediscover sections fall back to a random sample of liked entities
// when the eligibility query returns fewer than HomeRediscoverLimit rows.
// Any single query error fails the whole call (predictable empty-or-full
// UX for the SPA — partial payloads are not a feature).
func HomeData(ctx context.Context, pool *pgxpool.Pool, userID pgtype.UUID) (*HomePayload, error) {
	q := dbq.New(pool)

	var (
		wg       sync.WaitGroup
		mu       sync.Mutex
		firstErr error
	)
	fail := func(stage string, err error) {
		mu.Lock()
		defer mu.Unlock()
		if firstErr == nil {
			firstErr = fmt.Errorf("home: %s: %w", stage, err)
		}
	}

	out := &HomePayload{
		RecentlyAddedAlbums: []dbq.ListRecentlyAddedAlbumsWithArtistRow{},
		RediscoverAlbums:    []dbq.ListRediscoverAlbumsForUserRow{},
		RediscoverArtists:   []dbq.ListRediscoverArtistsForUserRow{},
		MostPlayedTracks:    []dbq.ListMostPlayedTracksForUserRow{},
		LastPlayedArtists:   []dbq.ListLastPlayedArtistsForUserRow{},
	}

	wg.Add(5)
	go func() {
		defer wg.Done()
		rows, err := q.ListRecentlyAddedAlbumsWithArtist(ctx, HomeRecentlyAddedLimit)
		if err != nil {
			fail("recently_added", err)
			return
		}
		out.RecentlyAddedAlbums = rows
	}()
	go func() {
		defer wg.Done()
		rows, err := q.ListMostPlayedTracksForUser(ctx, dbq.ListMostPlayedTracksForUserParams{
			UserID: userID, Limit: HomeMostPlayedLimit,
		})
		if err != nil {
			fail("most_played", err)
			return
		}
		out.MostPlayedTracks = rows
	}()
	go func() {
		defer wg.Done()
		rows, err := q.ListLastPlayedArtistsForUser(ctx, dbq.ListLastPlayedArtistsForUserParams{
			UserID: userID, Limit: HomeLastPlayedLimit,
		})
		if err != nil {
			fail("last_played", err)
			return
		}
		out.LastPlayedArtists = rows
	}()
	go func() {
		defer wg.Done()
		rows, err := loadRediscoverAlbums(ctx, q, userID)
		if err != nil {
			fail("rediscover_albums", err)
			return
		}
		out.RediscoverAlbums = rows
	}()
	go func() {
		defer wg.Done()
		rows, err := loadRediscoverArtists(ctx, q, userID)
		if err != nil {
			fail("rediscover_artists", err)
			return
		}
		out.RediscoverArtists = rows
	}()
	wg.Wait()

	if firstErr != nil {
		return nil, firstErr
	}
	return out, nil
}

func loadRediscoverAlbums(ctx context.Context, q *dbq.Queries, userID pgtype.UUID) ([]dbq.ListRediscoverAlbumsForUserRow, error) {
	primary, err := q.ListRediscoverAlbumsForUser(ctx, dbq.ListRediscoverAlbumsForUserParams{
		UserID: userID, Limit: HomeRediscoverLimit,
	})
	if err != nil {
		return nil, err
	}
	if len(primary) >= HomeRediscoverLimit {
		return primary, nil
	}
	fallback, err := q.ListRediscoverAlbumsFallbackForUser(ctx, dbq.ListRediscoverAlbumsFallbackForUserParams{
		UserID: userID, Limit: HomeRediscoverLimit,
	})
	if err != nil {
		return nil, err
	}
	seen := make(map[pgtype.UUID]struct{}, len(primary))
	for _, r := range primary {
		seen[r.Album.ID] = struct{}{}
	}
	for _, r := range fallback {
		if _, dup := seen[r.Album.ID]; dup {
			continue
		}
		// Fallback rows have the same shape after a manual projection
		// (ListRediscoverAlbumsFallbackForUserRow → ListRediscoverAlbumsForUserRow).
		primary = append(primary, dbq.ListRediscoverAlbumsForUserRow{
			Album:      r.Album,
			ArtistName: r.ArtistName,
		})
		if len(primary) >= HomeRediscoverLimit {
			break
		}
		seen[r.Album.ID] = struct{}{}
	}
	return primary, nil
}

func loadRediscoverArtists(ctx context.Context, q *dbq.Queries, userID pgtype.UUID) ([]dbq.ListRediscoverArtistsForUserRow, error) {
	primary, err := q.ListRediscoverArtistsForUser(ctx, dbq.ListRediscoverArtistsForUserParams{
		UserID: userID, Limit: HomeRediscoverLimit,
	})
	if err != nil {
		return nil, err
	}
	if len(primary) >= HomeRediscoverLimit {
		return primary, nil
	}
	fallback, err := q.ListRediscoverArtistsFallbackForUser(ctx, dbq.ListRediscoverArtistsFallbackForUserParams{
		UserID: userID, Limit: HomeRediscoverLimit,
	})
	if err != nil {
		return nil, err
	}
	seen := make(map[pgtype.UUID]struct{}, len(primary))
	for _, r := range primary {
		seen[r.Artist.ID] = struct{}{}
	}
	for _, r := range fallback {
		if _, dup := seen[r.Artist.ID]; dup {
			continue
		}
		primary = append(primary, dbq.ListRediscoverArtistsForUserRow{
			Artist:        r.Artist,
			CoverAlbumID:  r.CoverAlbumID,
			AlbumCount:    r.AlbumCount,
		})
		if len(primary) >= HomeRediscoverLimit {
			break
		}
		seen[r.Artist.ID] = struct{}{}
	}
	return primary, nil
}

• Step 4.4: Run test to verify it passes

Run:

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./internal/recommendation/ -run TestHomeData_NewUser_AllSectionsEmpty -count=1

Expected: PASS.

• Step 4.5: Add deeper integration tests

Append to internal/recommendation/home_integration_test.go:

import (
	"time"
)

func TestHomeData_RecentlyAdded_OrderedByCreatedAt(t *testing.T) {
	pool := newPool(t)
	user := seedUser(t, pool, "home-recents")
	a1 := seedArtist(t, pool, "ArtistA", "")
	// Three albums, oldest first — created_at increases naturally with each insert.
	al1 := seedAlbumForArtist(t, pool, a1.ID, "Older")
	al2 := seedAlbumForArtist(t, pool, a1.ID, "Middle")
	al3 := seedAlbumForArtist(t, pool, a1.ID, "Newest")

	got, err := HomeData(context.Background(), pool, user.ID)
	if err != nil {
		t.Fatalf("HomeData: %v", err)
	}
	if len(got.RecentlyAddedAlbums) != 3 {
		t.Fatalf("len = %d, want 3", len(got.RecentlyAddedAlbums))
	}
	if got.RecentlyAddedAlbums[0].Album.ID != al3.ID ||
		got.RecentlyAddedAlbums[1].Album.ID != al2.ID ||
		got.RecentlyAddedAlbums[2].Album.ID != al1.ID {
		t.Errorf("order = [%s, %s, %s], want newest→oldest",
			got.RecentlyAddedAlbums[0].Album.Title,
			got.RecentlyAddedAlbums[1].Album.Title,
			got.RecentlyAddedAlbums[2].Album.Title)
	}
}

func TestHomeData_MostPlayed_RanksByCount_HonorsQuarantine(t *testing.T) {
	pool := newPool(t)
	user := seedUser(t, pool, "home-mostplayed")
	artist := seedArtist(t, pool, "ArtistB", "")
	album := seedAlbumForArtist(t, pool, artist.ID, "AlbumB")
	tHigh := seedTrackOnAlbum(t, pool, album.ID, artist.ID, "High")
	tLow := seedTrackOnAlbum(t, pool, album.ID, artist.ID, "Low")
	tQuar := seedTrackOnAlbum(t, pool, album.ID, artist.ID, "Quarantined")
	now := time.Now()
	for i := 0; i < 3; i++ {
		insertPlayEvent(t, pool, user.ID, tHigh.ID, now.Add(-time.Duration(i)*time.Minute))
	}
	insertPlayEvent(t, pool, user.ID, tLow.ID, now)
	for i := 0; i < 5; i++ {
		insertPlayEvent(t, pool, user.ID, tQuar.ID, now)
	}
	if _, err := pool.Exec(context.Background(),
		`INSERT INTO lidarr_quarantine (user_id, track_id, reason) VALUES ($1, $2, 'bad_rip')`,
		user.ID, tQuar.ID,
	); err != nil {
		t.Fatalf("insert quarantine: %v", err)
	}

	got, err := HomeData(context.Background(), pool, user.ID)
	if err != nil {
		t.Fatalf("HomeData: %v", err)
	}
	if len(got.MostPlayedTracks) != 2 {
		t.Fatalf("len = %d, want 2 (quarantined excluded)", len(got.MostPlayedTracks))
	}
	if got.MostPlayedTracks[0].Track.ID != tHigh.ID || got.MostPlayedTracks[1].Track.ID != tLow.ID {
		t.Errorf("ranking wrong: got [%s, %s], want [High, Low]",
			got.MostPlayedTracks[0].Track.Title,
			got.MostPlayedTracks[1].Track.Title)
	}
}

func TestHomeData_RediscoverAlbums_FallbackWhenSparse(t *testing.T) {
	pool := newPool(t)
	user := seedUser(t, pool, "home-rediscover")
	artist := seedArtist(t, pool, "ArtistC", "")
	// Like one album NOW (won't satisfy >30d eligibility) — should still
	// surface via fallback because primary returns 0 rows.
	al := seedAlbumForArtist(t, pool, artist.ID, "RecentLike")
	if _, err := pool.Exec(context.Background(),
		`INSERT INTO general_likes_albums (user_id, album_id, liked_at) VALUES ($1, $2, now())`,
		user.ID, al.ID,
	); err != nil {
		t.Fatalf("insert like: %v", err)
	}
	got, err := HomeData(context.Background(), pool, user.ID)
	if err != nil {
		t.Fatalf("HomeData: %v", err)
	}
	if len(got.RediscoverAlbums) != 1 {
		t.Fatalf("len = %d, want 1 (from fallback)", len(got.RediscoverAlbums))
	}
	if got.RediscoverAlbums[0].Album.ID != al.ID {
		t.Errorf("got %s, want %s", got.RediscoverAlbums[0].Album.Title, al.Title)
	}
}

• Step 4.6: Run all home tests

Run:

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./internal/recommendation/ -run TestHomeData -count=1 -v

Expected: 3/3 PASS.

• Step 4.7: Commit

git add internal/recommendation/home.go \
        internal/recommendation/home_integration_test.go
git commit -m "feat(recommendation): add HomeData composite service for /api/home"

---

Task 5 — API types + convert helpers

Files:

• Modify: internal/api/types.go

• Modify: internal/api/convert.go

• Modify: internal/api/library.go (handler signature follow-up — covered separately in Task 9)

• Step 5.1: Extend ArtistRef and AlbumRef in types.go

Modify internal/api/types.go — replace the ArtistRef and AlbumRef blocks:

// ArtistRef is the lightweight artist shape used in lists and search results.
// SortName is exposed so the SPA's alphabetical-grid divider can group rows
// by the catalogue sort order ("The Beatles" → "B"). CoverURL is derived from
// a representative album (most-recent with cover_art_path); empty when the
// artist's discography has no cover art.
type ArtistRef struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	SortName   string `json:"sort_name"`
	AlbumCount int    `json:"album_count"`
	CoverURL   string `json:"cover_url"`
}

// AlbumRef is the lightweight album shape used in lists, artist details,
// and search results. SortTitle is exposed so the SPA's alphabetical-grid
// divider can group rows by sort order ("The Wall" → "W"). CoverURL points
// to /api/albums/{id}/cover.
type AlbumRef struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	SortTitle   string `json:"sort_title"`
	ArtistID    string `json:"artist_id"`
	ArtistName  string `json:"artist_name"`
	Year        int    `json:"year,omitempty"`
	TrackCount  int    `json:"track_count"`
	DurationSec int    `json:"duration_sec"`
	CoverURL    string `json:"cover_url"`
}

• Step 5.2: Add HomePayload view type to types.go

Append at the bottom of internal/api/types.go:

// HomePayload is the response body of GET /api/home. Field counts:
// 50 (recently_added) / 25 (rediscover_albums) / 25 (rediscover_artists)
// / 75 (most_played) / 25 (last_played). All slices are non-nil at JSON
// encode time so empty sections render as [] rather than null.
type HomePayload struct {
	RecentlyAddedAlbums []AlbumRef  `json:"recently_added_albums"`
	RediscoverAlbums    []AlbumRef  `json:"rediscover_albums"`
	RediscoverArtists   []ArtistRef `json:"rediscover_artists"`
	MostPlayedTracks    []TrackRef  `json:"most_played_tracks"`
	LastPlayedArtists   []ArtistRef `json:"last_played_artists"`
}

• Step 5.3: Update albumRefFrom to populate SortTitle

Modify internal/api/convert.go — replace the albumRefFrom function:

// albumRefFrom projects a dbq.Album into an AlbumRef. artistName must be
// pre-resolved because Album only carries artist_id. trackCount and
// durationSec may be 0 when the caller does not compute them.
func albumRefFrom(a dbq.Album, artistName string, trackCount, durationSec int) AlbumRef {
	return AlbumRef{
		ID:          uuidToString(a.ID),
		Title:       a.Title,
		SortTitle:   a.SortTitle,
		ArtistID:    uuidToString(a.ArtistID),
		ArtistName:  artistName,
		Year:        yearFromDate(a.ReleaseDate),
		TrackCount:  trackCount,
		DurationSec: durationSec,
		CoverURL:    coverURL(a.ID),
	}
}

• Step 5.4: Update artistRefFrom to populate SortName (existing call sites use empty cover)

Modify internal/api/convert.go — replace the artistRefFrom function and add a covered variant:

// artistRefFrom projects a dbq.Artist into an ArtistRef without cover.
// albumCount must be pre-computed by the caller. Used by code paths that
// don't have a representative-album lookup at hand (artist detail, search,
// liked-artists list).
func artistRefFrom(a dbq.Artist, albumCount int) ArtistRef {
	return ArtistRef{
		ID:         uuidToString(a.ID),
		Name:       a.Name,
		SortName:   a.SortName,
		AlbumCount: albumCount,
	}
}

// artistRefFromCovered projects a dbq.Artist into an ArtistRef with the
// derived CoverURL populated from a representative album id (nullable).
// Used by /api/home and /api/artists?sort=alpha which carry the lookup
// in the same query.
func artistRefFromCovered(a dbq.Artist, albumCount int, coverAlbumID pgtype.UUID) ArtistRef {
	ref := artistRefFrom(a, albumCount)
	if coverAlbumID.Valid {
		ref.CoverURL = coverURL(coverAlbumID)
	}
	return ref
}

• Step 5.5: Run vet + build

go vet ./internal/api/...
go build ./...

Expected: clean build. Existing call sites continue to compile because the appended fields default to zero values — JSON marshal still includes them as "sort_name": "", which is harmless.

• Step 5.6: Commit

git add internal/api/types.go internal/api/convert.go
git commit -m "feat(api): extend ArtistRef/AlbumRef + add HomePayload for M6a"

---

Task 6 — GET /api/home handler

Files:

• Create: internal/api/home.go

• Create: internal/api/home_test.go

• Step 6.1: Write failing test for the happy-path empty payload

Create internal/api/home_test.go:

package api

import (
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/go-chi/chi/v5"

	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)

func newHomeRouter(h *handlers) chi.Router {
	r := chi.NewRouter()
	r.Get("/api/home", h.handleGetHome)
	return r
}

func doGetHome(h *handlers, user dbq.User) *httptest.ResponseRecorder {
	req := httptest.NewRequest(http.MethodGet, "/api/home", nil)
	req = withUser(req, user)
	w := httptest.NewRecorder()
	newHomeRouter(h).ServeHTTP(w, req)
	return w
}

func TestHome_EmptyForNewUser(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)

	w := doGetHome(h, user)
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d, want 200; body = %s", w.Code, w.Body.String())
	}
	var got HomePayload
	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
		t.Fatalf("decode: %v", err)
	}
	// All slices must be non-nil so the SPA branches consistently on
	// length rather than dealing with null.
	if got.RecentlyAddedAlbums == nil || got.RediscoverAlbums == nil ||
		got.RediscoverArtists == nil || got.MostPlayedTracks == nil ||
		got.LastPlayedArtists == nil {
		t.Errorf("payload has nil slice: %+v", got)
	}
	if len(got.RecentlyAddedAlbums) != 0 {
		t.Errorf("RecentlyAddedAlbums len = %d, want 0", len(got.RecentlyAddedAlbums))
	}
}

func TestHome_RecentlyAddedSurfacesAlbums(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)
	q := dbq.New(pool)
	artist, _ := q.UpsertArtist(t.Context(), dbq.UpsertArtistParams{
		Name: "ArtistOne", SortName: "ArtistOne",
	})
	_, _ = q.UpsertAlbum(t.Context(), dbq.UpsertAlbumParams{
		Title: "Newest", SortTitle: "Newest", ArtistID: artist.ID,
	})

	w := doGetHome(h, user)
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d, body = %s", w.Code, w.Body.String())
	}
	var got HomePayload
	_ = json.Unmarshal(w.Body.Bytes(), &got)
	if len(got.RecentlyAddedAlbums) != 1 {
		t.Fatalf("len = %d, want 1", len(got.RecentlyAddedAlbums))
	}
	if got.RecentlyAddedAlbums[0].Title != "Newest" {
		t.Errorf("title = %q, want Newest", got.RecentlyAddedAlbums[0].Title)
	}
	if got.RecentlyAddedAlbums[0].ArtistName != "ArtistOne" {
		t.Errorf("artist_name = %q, want ArtistOne", got.RecentlyAddedAlbums[0].ArtistName)
	}
}

NOTE: this test uses t.Context(). The repo standard is context.Background() because Go 1.23 doesn't have t.Context() — replace before saving:

import "context"
// then: context.Background() everywhere instead of t.Context()

• Step 6.2: Run test to verify it fails

go test ./internal/api/ -run TestHome_ -count=1

Expected: FAIL with "undefined: handleGetHome" or similar.

• Step 6.3: Write the handler

Create internal/api/home.go:

package api

import (
	"net/http"

	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
)

// handleGetHome implements GET /api/home. Returns five sections in one
// payload; sections that have no rows render as []. 500 on any underlying
// DB failure (no partial payload — the SPA should render either empty
// states or full content, not a half-broken page).
func (h *handlers) handleGetHome(w http.ResponseWriter, r *http.Request) {
	user, ok := auth.UserFromContext(r.Context())
	if !ok {
		writeErr(w, http.StatusUnauthorized, "unauthorized", "authentication required")
		return
	}
	data, err := recommendation.HomeData(r.Context(), h.pool, user.ID)
	if err != nil {
		h.logger.Error("api: home data", "err", err)
		writeErr(w, http.StatusInternalServerError, "server_error", "failed to load home")
		return
	}

	out := HomePayload{
		RecentlyAddedAlbums: make([]AlbumRef, 0, len(data.RecentlyAddedAlbums)),
		RediscoverAlbums:    make([]AlbumRef, 0, len(data.RediscoverAlbums)),
		RediscoverArtists:   make([]ArtistRef, 0, len(data.RediscoverArtists)),
		MostPlayedTracks:    make([]TrackRef, 0, len(data.MostPlayedTracks)),
		LastPlayedArtists:   make([]ArtistRef, 0, len(data.LastPlayedArtists)),
	}
	for _, row := range data.RecentlyAddedAlbums {
		out.RecentlyAddedAlbums = append(out.RecentlyAddedAlbums, albumRefFrom(row.Album, row.ArtistName, 0, 0))
	}
	for _, row := range data.RediscoverAlbums {
		out.RediscoverAlbums = append(out.RediscoverAlbums, albumRefFrom(row.Album, row.ArtistName, 0, 0))
	}
	for _, row := range data.RediscoverArtists {
		out.RediscoverArtists = append(out.RediscoverArtists, artistRefFromCovered(row.Artist, int(row.AlbumCount), row.CoverAlbumID))
	}
	for _, row := range data.MostPlayedTracks {
		out.MostPlayedTracks = append(out.MostPlayedTracks, trackRefFrom(row.Track, row.AlbumTitle, row.ArtistName))
	}
	for _, row := range data.LastPlayedArtists {
		out.LastPlayedArtists = append(out.LastPlayedArtists, artistRefFromCovered(row.Artist, int(row.AlbumCount), row.CoverAlbumID))
	}
	writeJSON(w, http.StatusOK, out)
}

// Compile-time guard that dbq has the row types we need; if the SQL is
// regenerated with a different name, this fails fast at build time.
var _ = dbq.ListMostPlayedTracksForUserRow{}.Track

• Step 6.4: Run tests to verify they pass

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./internal/api/ -run TestHome_ -count=1 -v

Expected: 2/2 PASS.

• Step 6.5: Commit

git add internal/api/home.go internal/api/home_test.go
git commit -m "feat(api): add GET /api/home composite handler"

---

Task 7 — GET /api/library/albums handler

Files:

• Create: internal/api/library_albums.go

• Create: internal/api/library_albums_test.go

• Step 7.1: Write failing test

Create internal/api/library_albums_test.go:

package api

import (
	"context"
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/go-chi/chi/v5"

	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)

func newLibraryAlbumsRouter(h *handlers) chi.Router {
	r := chi.NewRouter()
	r.Get("/api/library/albums", h.handleListLibraryAlbums)
	return r
}

func doListLibraryAlbums(h *handlers, user dbq.User, query string) *httptest.ResponseRecorder {
	url := "/api/library/albums"
	if query != "" {
		url += "?" + query
	}
	req := httptest.NewRequest(http.MethodGet, url, nil)
	req = withUser(req, user)
	w := httptest.NewRecorder()
	newLibraryAlbumsRouter(h).ServeHTTP(w, req)
	return w
}

func TestLibraryAlbums_AlphaSorted(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)
	q := dbq.New(pool)
	artist, _ := q.UpsertArtist(context.Background(), dbq.UpsertArtistParams{
		Name: "ArtistA", SortName: "ArtistA",
	})
	_, _ = q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
		Title: "Zoo", SortTitle: "Zoo", ArtistID: artist.ID,
	})
	_, _ = q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
		Title: "Apple", SortTitle: "Apple", ArtistID: artist.ID,
	})
	_, _ = q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
		Title: "Mango", SortTitle: "Mango", ArtistID: artist.ID,
	})

	w := doListLibraryAlbums(h, user, "limit=10")
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d, body = %s", w.Code, w.Body.String())
	}
	var got Page[AlbumRef]
	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
		t.Fatalf("decode: %v", err)
	}
	if got.Total != 3 {
		t.Errorf("total = %d, want 3", got.Total)
	}
	titles := []string{got.Items[0].Title, got.Items[1].Title, got.Items[2].Title}
	if titles[0] != "Apple" || titles[1] != "Mango" || titles[2] != "Zoo" {
		t.Errorf("titles = %v, want [Apple Mango Zoo]", titles)
	}
	if got.Items[0].SortTitle != "Apple" {
		t.Errorf("sort_title = %q, want Apple", got.Items[0].SortTitle)
	}
}

func TestLibraryAlbums_Paging(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)
	q := dbq.New(pool)
	artist, _ := q.UpsertArtist(context.Background(), dbq.UpsertArtistParams{
		Name: "ArtistA", SortName: "ArtistA",
	})
	for _, title := range []string{"A", "B", "C", "D"} {
		_, _ = q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
			Title: title, SortTitle: title, ArtistID: artist.ID,
		})
	}

	w := doListLibraryAlbums(h, user, "limit=2&offset=2")
	if w.Code != http.StatusOK {
		t.Fatalf("status = %d", w.Code)
	}
	var got Page[AlbumRef]
	_ = json.Unmarshal(w.Body.Bytes(), &got)
	if got.Total != 4 || got.Limit != 2 || got.Offset != 2 {
		t.Errorf("envelope = %+v, want total=4 limit=2 offset=2", got)
	}
	if len(got.Items) != 2 || got.Items[0].Title != "C" || got.Items[1].Title != "D" {
		t.Errorf("items = %v, want [C D]", got.Items)
	}
}

• Step 7.2: Run test to verify it fails

go test ./internal/api/ -run TestLibraryAlbums_ -count=1

Expected: FAIL with "undefined: handleListLibraryAlbums".

• Step 7.3: Write the handler

Create internal/api/library_albums.go:

package api

import (
	"net/http"

	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)

// handleListLibraryAlbums implements GET /api/library/albums. Mirrors
// /api/artists?sort=alpha but for albums. The new wrapping-grid page on
// the SPA infinite-scrolls against this endpoint via TanStack
// createInfiniteQuery.
func (h *handlers) handleListLibraryAlbums(w http.ResponseWriter, r *http.Request) {
	limit, offset, err := parsePaging(r.URL.Query())
	if err != nil {
		writeErr(w, http.StatusBadRequest, "bad_request", err.Error())
		return
	}
	q := dbq.New(h.pool)
	rows, err := q.ListAlbumsAlphaWithArtist(r.Context(), dbq.ListAlbumsAlphaWithArtistParams{
		Limit: int32(limit), Offset: int32(offset),
	})
	if err != nil {
		h.logger.Error("api: list library albums", "err", err)
		writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
		return
	}
	total, err := q.CountAlbums(r.Context())
	if err != nil {
		h.logger.Error("api: count albums", "err", err)
		writeErr(w, http.StatusInternalServerError, "server_error", "count failed")
		return
	}
	items := make([]AlbumRef, 0, len(rows))
	for _, row := range rows {
		items = append(items, albumRefFrom(row.Album, row.ArtistName, 0, 0))
	}
	writeJSON(w, http.StatusOK, Page[AlbumRef]{
		Items: items, Total: int(total), Limit: limit, Offset: offset,
	})
}

• Step 7.4: Run tests to verify they pass

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./internal/api/ -run TestLibraryAlbums_ -count=1 -v

Expected: 2/2 PASS.

• Step 7.5: Commit

git add internal/api/library_albums.go internal/api/library_albums_test.go
git commit -m "feat(api): add GET /api/library/albums handler"

---

Task 8 — GET /api/artists/{id}/tracks handler

Files:

• Modify: internal/api/library.go (append handleGetArtistTracks)

• Modify: internal/api/library_test.go (append tests)

• Step 8.1: Write failing tests

Append to internal/api/library_test.go at the bottom (preserve all existing tests):

func TestGetArtistTracks_HappyPath(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)
	q := dbq.New(pool)
	artist, _ := q.UpsertArtist(context.Background(), dbq.UpsertArtistParams{
		Name: "ArtistA", SortName: "ArtistA",
	})
	album, _ := q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
		Title: "AlbumA", SortTitle: "AlbumA", ArtistID: artist.ID,
	})
	_, _ = q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{
		Title: "T1", AlbumID: album.ID, ArtistID: artist.ID,
		DurationMs: 1000, FilePath: "/tmp/m6a-T1.mp3",
		FileSize: 1, FileFormat: "mp3",
	})
	_, _ = q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{
		Title: "T2", AlbumID: album.ID, ArtistID: artist.ID,
		DurationMs: 1000, FilePath: "/tmp/m6a-T2.mp3",
		FileSize: 1, FileFormat: "mp3",
	})

	r := chi.NewRouter()
	r.Get("/api/artists/{id}/tracks", h.handleGetArtistTracks)
	req := httptest.NewRequest(http.MethodGet, "/api/artists/"+uuidToString(artist.ID)+"/tracks", nil)
	req = withUser(req, user)
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)

	if w.Code != http.StatusOK {
		t.Fatalf("status = %d, body = %s", w.Code, w.Body.String())
	}
	var got []TrackRef
	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
		t.Fatalf("decode: %v", err)
	}
	if len(got) != 2 {
		t.Fatalf("len = %d, want 2", len(got))
	}
	if got[0].ArtistName != "ArtistA" || got[0].AlbumTitle != "AlbumA" {
		t.Errorf("got = %+v", got[0])
	}
}

func TestGetArtistTracks_HonorsQuarantine(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)
	q := dbq.New(pool)
	artist, _ := q.UpsertArtist(context.Background(), dbq.UpsertArtistParams{
		Name: "ArtistB", SortName: "ArtistB",
	})
	album, _ := q.UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
		Title: "AlbumB", SortTitle: "AlbumB", ArtistID: artist.ID,
	})
	track, _ := q.UpsertTrack(context.Background(), dbq.UpsertTrackParams{
		Title: "Q", AlbumID: album.ID, ArtistID: artist.ID,
		DurationMs: 1000, FilePath: "/tmp/m6a-Q.mp3",
		FileSize: 1, FileFormat: "mp3",
	})
	if _, err := pool.Exec(context.Background(),
		`INSERT INTO lidarr_quarantine (user_id, track_id, reason) VALUES ($1, $2, 'bad_rip')`,
		user.ID, track.ID,
	); err != nil {
		t.Fatalf("quarantine insert: %v", err)
	}

	r := chi.NewRouter()
	r.Get("/api/artists/{id}/tracks", h.handleGetArtistTracks)
	req := httptest.NewRequest(http.MethodGet, "/api/artists/"+uuidToString(artist.ID)+"/tracks", nil)
	req = withUser(req, user)
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)

	if w.Code != http.StatusOK {
		t.Fatalf("status = %d", w.Code)
	}
	var got []TrackRef
	_ = json.Unmarshal(w.Body.Bytes(), &got)
	if len(got) != 0 {
		t.Errorf("len = %d, want 0 (quarantined)", len(got))
	}
}

func TestGetArtistTracks_NotFound(t *testing.T) {
	h, pool := testHandlers(t)
	user := seedUser(t, pool, "alice", "pw", false)

	r := chi.NewRouter()
	r.Get("/api/artists/{id}/tracks", h.handleGetArtistTracks)
	// Random UUID — no such artist exists.
	req := httptest.NewRequest(http.MethodGet, "/api/artists/00000000-0000-0000-0000-000000000000/tracks", nil)
	req = withUser(req, user)
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)

	if w.Code != http.StatusNotFound {
		t.Errorf("status = %d, want 404", w.Code)
	}
	_ = pool
}

• Step 8.2: Run tests to verify they fail

go test ./internal/api/ -run TestGetArtistTracks_ -count=1

Expected: FAIL with "undefined: handleGetArtistTracks".

• Step 8.3: Append the handler to library.go

Append at the bottom of internal/api/library.go:

// handleGetArtistTracks implements GET /api/artists/{id}/tracks. Returns
// every track the artist has across albums (per-user-quarantine filtered)
// as a flat list. Used by ArtistCard's play affordance, which shuffles
// client-side. 404 when the artist doesn't exist.
func (h *handlers) handleGetArtistTracks(w http.ResponseWriter, r *http.Request) {
	id, ok := parseUUID(chi.URLParam(r, "id"))
	if !ok {
		writeErr(w, http.StatusBadRequest, "bad_request", "invalid artist id")
		return
	}
	user, ok := auth.UserFromContext(r.Context())
	if !ok {
		writeErr(w, http.StatusUnauthorized, "unauthorized", "authentication required")
		return
	}
	q := dbq.New(h.pool)
	if _, err := q.GetArtistByID(r.Context(), id); err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			writeErr(w, http.StatusNotFound, "not_found", "artist not found")
			return
		}
		h.logger.Error("api: get artist for tracks", "err", err)
		writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
		return
	}
	rows, err := q.ListArtistTracksForUser(r.Context(), dbq.ListArtistTracksForUserParams{
		ArtistID: id, UserID: user.ID,
	})
	if err != nil {
		h.logger.Error("api: list artist tracks", "err", err)
		writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
		return
	}
	out := make([]TrackRef, 0, len(rows))
	for _, row := range rows {
		out = append(out, trackRefFrom(row.Track, row.AlbumTitle, row.ArtistName))
	}
	writeJSON(w, http.StatusOK, out)
}

• Step 8.4: Run tests to verify they pass

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./internal/api/ -run TestGetArtistTracks_ -count=1 -v

Expected: 3/3 PASS.

• Step 8.5: Commit

git add internal/api/library.go internal/api/library_test.go
git commit -m "feat(api): add GET /api/artists/{id}/tracks handler"

---

Task 9 — Update /api/artists?sort=alpha to use covers query + register routes

Files:

• Modify: internal/api/library.go (handleListArtists alpha branch)

• Modify: internal/api/library_test.go (existing alpha tests still pass; add cover-url assertion)

• Modify: internal/api/api.go

• Step 9.1: Update handleListArtists alpha branch to use the new query

Modify internal/api/library.go — the handleListArtists function's switch block:

	switch sort {
	case "newest":
		artists, err = q.ListArtistsNewest(r.Context(), dbq.ListArtistsNewestParams{
			Limit: int32(limit), Offset: int32(offset),
		})
		if err != nil {
			h.logger.Error("api: list artists newest", "err", err)
			writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
			return
		}
		total, terr := q.CountArtists(r.Context())
		if terr != nil {
			h.logger.Error("api: count artists", "err", terr)
			writeErr(w, http.StatusInternalServerError, "server_error", "count failed")
			return
		}
		items := make([]ArtistRef, 0, len(artists))
		for _, a := range artists {
			albums, aerr := q.ListAlbumsByArtist(r.Context(), a.ID)
			if aerr != nil {
				h.logger.Error("api: list albums for artist", "err", aerr)
				writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
				return
			}
			items = append(items, artistRefFrom(a, len(albums)))
		}
		writeJSON(w, http.StatusOK, Page[ArtistRef]{
			Items: items, Total: int(total), Limit: limit, Offset: offset,
		})
		return

	default: // alpha
		rows, err := q.ListArtistsAlphaWithCovers(r.Context(), dbq.ListArtistsAlphaWithCoversParams{
			Limit: int32(limit), Offset: int32(offset),
		})
		if err != nil {
			h.logger.Error("api: list artists alpha", "err", err)
			writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
			return
		}
		total, terr := q.CountArtists(r.Context())
		if terr != nil {
			h.logger.Error("api: count artists", "err", terr)
			writeErr(w, http.StatusInternalServerError, "server_error", "count failed")
			return
		}
		items := make([]ArtistRef, 0, len(rows))
		for _, row := range rows {
			items = append(items, artistRefFromCovered(row.Artist, int(row.AlbumCount), row.CoverAlbumID))
		}
		writeJSON(w, http.StatusOK, Page[ArtistRef]{
			Items: items, Total: int(total), Limit: limit, Offset: offset,
		})
		return
	}

Then delete the redundant _ = artists; _ = err and old shared total block at the bottom of the function — both branches now return inline. The function should end after the switch with no further statements.

• Step 9.2: Register routes in api.go

Modify internal/api/api.go — add three new routes inside the authenticated group, alongside the existing authed.Get("/artists/...", ...) lines:

		authed.Get("/home", h.handleGetHome)
		authed.Get("/library/albums", h.handleListLibraryAlbums)
		authed.Get("/artists/{id}/tracks", h.handleGetArtistTracks)

Place these adjacent to the existing artist/album/track registrations for readability. The exact location:

		authed.Get("/artists", h.handleListArtists)
		authed.Get("/artists/{id}", h.handleGetArtist)
		authed.Get("/artists/{id}/tracks", h.handleGetArtistTracks)  // NEW
		authed.Get("/albums/{id}", h.handleGetAlbum)
		authed.Get("/albums/{id}/cover", h.handleGetCover)
		authed.Get("/library/albums", h.handleListLibraryAlbums)     // NEW
		authed.Get("/tracks/{id}", h.handleGetTrack)
		authed.Get("/tracks/{id}/stream", h.handleGetStream)
		authed.Get("/search", h.handleSearch)
		authed.Get("/radio", h.handleRadio)
		authed.Get("/home", h.handleGetHome)                          // NEW

• Step 9.3: Run all api tests

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./internal/api/ -count=1

Expected: all PASS. Existing artist-list tests must continue to pass — the alpha branch now exposes cover_url (empty string when no cover) and sort_name (always populated).

• Step 9.4: Commit

git add internal/api/library.go internal/api/api.go
git commit -m "feat(api): wire M6a routes; alpha artist list uses covers query"

---

Task 10 — Frontend: TS types + queries.ts

Files:

• Modify: web/src/lib/api/types.ts

• Modify: web/src/lib/api/queries.ts

• Step 10.1: Extend ArtistRef and AlbumRef; add HomePayload

Modify web/src/lib/api/types.ts — replace the ArtistRef and AlbumRef blocks:

export type ArtistRef = {
  id: string;
  name: string;
  sort_name: string;
  album_count: number;
  cover_url: string;   // "" when no representative album cover
};

export type AlbumRef = {
  id: string;
  title: string;
  sort_title: string;
  artist_id: string;
  artist_name: string;
  year?: number;
  track_count: number;
  duration_sec: number;
  cover_url: string;
};

Append at the bottom of web/src/lib/api/types.ts:

// Mirrors internal/api/types.go HomePayload. All slices are non-null
// per the server contract — empty sections render as [].
export type HomePayload = {
  recently_added_albums: AlbumRef[];
  rediscover_albums:     AlbumRef[];
  rediscover_artists:    ArtistRef[];
  most_played_tracks:    TrackRef[];
  last_played_artists:   ArtistRef[];
};

• Step 10.2: Add new query keys

Modify web/src/lib/api/queries.ts — append entries to the qk object literal:

  home:         ()                 => ['home'] as const,
  albumsAlpha:  ()                 => ['albumsAlpha'] as const,
  artistTracks: (artistId: string) => ['artistTracks', artistId] as const,

• Step 10.3: Update existing queries.test.ts

Append to web/src/lib/api/queries.test.ts:

test('M6a query keys are stable', () => {
  expect(qk.home()).toEqual(['home']);
  expect(qk.albumsAlpha()).toEqual(['albumsAlpha']);
  expect(qk.artistTracks('a1')).toEqual(['artistTracks', 'a1']);
});

• Step 10.4: Update existing test fixtures for new required fields

Search for AlbumRef/ArtistRef literals in tests:

cd web && grep -rln "album_count\|track_count" src/ --include="*.test.ts"

For each file with an AlbumRef literal, add sort_title: '<value>'. For each ArtistRef literal, add sort_name: '<value>' and cover_url: ''. Example for web/src/lib/components/AlbumCard.test.ts:

const album: AlbumRef = {
  id: 'xyz',
  title: 'Kind of Blue',
  sort_title: 'Kind of Blue',
  artist_id: 'm-davis',
  artist_name: 'Miles Davis',
  year: 1959,
  track_count: 5,
  duration_sec: 2630,
  cover_url: '/api/albums/xyz/cover',
};

• Step 10.5: Run all frontend tests

cd web && pnpm check && pnpm test

Expected: all PASS.

• Step 10.6: Commit

git add web/src/lib/api/types.ts web/src/lib/api/queries.ts web/src/lib/api/queries.test.ts \
        web/src/lib/components/*.test.ts
git commit -m "feat(web): extend ArtistRef/AlbumRef + add HomePayload + new query keys"

---

Task 11 — Frontend API clients: home.ts + albums.ts + artists.ts

Files:

• Create: web/src/lib/api/home.ts + home.test.ts

• Create: web/src/lib/api/albums.ts + albums.test.ts

• Create: web/src/lib/api/artists.ts + artists.test.ts

• Step 11.1: Write failing tests for home.ts

Create web/src/lib/api/home.test.ts:

import { afterEach, describe, expect, test, vi } from 'vitest';

vi.mock('./client', () => ({
  api: { get: vi.fn() }
}));

import { listHome } from './home';
import { qk } from './queries';
import { api } from './client';
import type { HomePayload } from './types';

afterEach(() => vi.clearAllMocks());

describe('home client', () => {
  test('listHome hits /api/home', async () => {
    const fixture: HomePayload = {
      recently_added_albums: [],
      rediscover_albums: [],
      rediscover_artists: [],
      most_played_tracks: [],
      last_played_artists: []
    };
    (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce(fixture);
    const got = await listHome();
    expect(api.get).toHaveBeenCalledWith('/api/home');
    expect(got).toEqual(fixture);
  });

  test('qk.home key is stable', () => {
    expect(qk.home()).toEqual(['home']);
  });
});

• Step 11.2: Create home.ts

Create web/src/lib/api/home.ts:

import { createQuery } from '@tanstack/svelte-query';
import { api } from './client';
import { qk } from './queries';
import type { HomePayload } from './types';

export async function listHome(): Promise<HomePayload> {
  return api.get<HomePayload>('/api/home');
}

// staleTime = 60s — repeat home-page mounts within a minute reuse cached
// data. Like-state changes, new plays, freshly-added albums surface on
// the next refetch.
export function createHomeQuery() {
  return createQuery({
    queryKey: qk.home(),
    queryFn: listHome,
    staleTime: 60_000
  });
}

• Step 11.3: Write failing tests for albums.ts

Create web/src/lib/api/albums.test.ts:

import { afterEach, describe, expect, test, vi } from 'vitest';

vi.mock('./client', () => ({
  api: { get: vi.fn() }
}));

import { listAlbumsAlpha } from './albums';
import { qk } from './queries';
import { api } from './client';

afterEach(() => vi.clearAllMocks());

describe('albums client', () => {
  test('listAlbumsAlpha hits /api/library/albums with paging', async () => {
    (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
      items: [], total: 0, limit: 50, offset: 0
    });
    await listAlbumsAlpha(50, 0);
    expect(api.get).toHaveBeenCalledWith('/api/library/albums?limit=50&offset=0');
  });

  test('listAlbumsAlpha honors custom limit and offset', async () => {
    (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
      items: [], total: 0, limit: 25, offset: 100
    });
    await listAlbumsAlpha(25, 100);
    expect(api.get).toHaveBeenCalledWith('/api/library/albums?limit=25&offset=100');
  });

  test('qk.albumsAlpha key is stable', () => {
    expect(qk.albumsAlpha()).toEqual(['albumsAlpha']);
  });
});

• Step 11.4: Create albums.ts

Create web/src/lib/api/albums.ts:

import { createInfiniteQuery } from '@tanstack/svelte-query';
import { api } from './client';
import { qk } from './queries';
import type { AlbumRef, Page } from './types';

export const ALBUM_PAGE_SIZE = 50;

export async function listAlbumsAlpha(limit: number, offset: number): Promise<Page<AlbumRef>> {
  return api.get<Page<AlbumRef>>(`/api/library/albums?limit=${limit}&offset=${offset}`);
}

export function createAlbumsAlphaInfiniteQuery() {
  return createInfiniteQuery({
    queryKey: qk.albumsAlpha(),
    queryFn: ({ pageParam = 0 }) => listAlbumsAlpha(ALBUM_PAGE_SIZE, pageParam),
    initialPageParam: 0,
    getNextPageParam: (last) => {
      const loaded = last.offset + last.items.length;
      return loaded >= last.total ? undefined : loaded;
    }
  });
}

• Step 11.5: Write failing tests for artists.ts

Create web/src/lib/api/artists.test.ts:

import { afterEach, describe, expect, test, vi } from 'vitest';

vi.mock('./client', () => ({
  api: { get: vi.fn() }
}));

import { listArtistTracks } from './artists';
import { qk } from './queries';
import { api } from './client';

afterEach(() => vi.clearAllMocks());

describe('artists client', () => {
  test('listArtistTracks hits /api/artists/:id/tracks', async () => {
    (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce([]);
    await listArtistTracks('art-1');
    expect(api.get).toHaveBeenCalledWith('/api/artists/art-1/tracks');
  });

  test('qk.artistTracks key includes the artist id', () => {
    expect(qk.artistTracks('art-1')).toEqual(['artistTracks', 'art-1']);
  });
});

• Step 11.6: Create artists.ts

Create web/src/lib/api/artists.ts:

import { createQuery } from '@tanstack/svelte-query';
import { api } from './client';
import { qk } from './queries';
import type { TrackRef } from './types';

export async function listArtistTracks(artistId: string): Promise<TrackRef[]> {
  return api.get<TrackRef[]>(`/api/artists/${artistId}/tracks`);
}

export function createArtistTracksQuery(artistId: string) {
  return createQuery({
    queryKey: qk.artistTracks(artistId),
    queryFn: () => listArtistTracks(artistId),
    enabled: artistId.length > 0
  });
}

• Step 11.7: Run all client tests + commit

cd web && pnpm test src/lib/api/home.test.ts src/lib/api/albums.test.ts src/lib/api/artists.test.ts

Expected: all PASS. Commit:

git add web/src/lib/api/home.ts web/src/lib/api/home.test.ts \
        web/src/lib/api/albums.ts web/src/lib/api/albums.test.ts \
        web/src/lib/api/artists.ts web/src/lib/api/artists.test.ts
git commit -m "feat(web): add home/albums/artists API clients for M6a"

---

Task 12 — <HorizontalScrollRow> component

Files:

• Create: web/src/lib/components/HorizontalScrollRow.svelte

• Create: web/src/lib/components/HorizontalScrollRow.test.ts

• Step 12.1: Write failing test

Create web/src/lib/components/HorizontalScrollRow.test.ts:

import { afterEach, describe, expect, test, vi } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/svelte';
import HorizontalScrollRow from './HorizontalScrollRow.svelte';

afterEach(() => vi.clearAllMocks());

describe('HorizontalScrollRow', () => {
  test('renders left and right scroll buttons', () => {
    render(HorizontalScrollRow, { props: { items: ['a', 'b', 'c'] } });
    expect(screen.getByRole('button', { name: /scroll left/i })).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /scroll right/i })).toBeInTheDocument();
  });

  test('left button starts disabled (scrollLeft is 0)', () => {
    render(HorizontalScrollRow, { props: { items: ['a'] } });
    expect(screen.getByRole('button', { name: /scroll left/i })).toBeDisabled();
  });

  test('clicking right button calls scrollBy on the container', async () => {
    const { container } = render(HorizontalScrollRow, { props: { items: ['a', 'b'] } });
    const scroller = container.querySelector('[data-testid="scroll-container"]') as HTMLElement;
    const spy = vi.fn();
    scroller.scrollBy = spy as unknown as HTMLElement['scrollBy'];
    Object.defineProperty(scroller, 'clientWidth', { value: 800, configurable: true });
    Object.defineProperty(scroller, 'scrollWidth', { value: 2000, configurable: true });
    Object.defineProperty(scroller, 'scrollLeft', { value: 0, configurable: true, writable: true });

    await fireEvent.click(screen.getByRole('button', { name: /scroll right/i }));
    expect(spy).toHaveBeenCalledWith({ left: expect.any(Number), behavior: 'smooth' });
    expect(spy.mock.calls[0][0].left).toBeGreaterThan(0);
  });
});

• Step 12.2: Run test to verify failure

cd web && pnpm test src/lib/components/HorizontalScrollRow.test.ts

Expected: FAIL.

• Step 12.3: Create the component

Create web/src/lib/components/HorizontalScrollRow.svelte:

<script lang="ts" generics="T">
  import { ChevronLeft, ChevronRight } from 'lucide-svelte';
  import type { Snippet } from 'svelte';

  let {
    items,
    item,
    ariaLabel
  }: {
    items: T[];
    item?: Snippet<[T, number]>;
    ariaLabel?: string;
  } = $props();

  let scroller: HTMLElement | undefined = $state();
  let scrollLeft = $state(0);
  let scrollWidth = $state(0);
  let clientWidth = $state(0);

  const atStart = $derived(scrollLeft <= 1);
  const atEnd   = $derived(scrollLeft + clientWidth >= scrollWidth - 1);

  function refreshMetrics() {
    if (!scroller) return;
    scrollLeft  = scroller.scrollLeft;
    scrollWidth = scroller.scrollWidth;
    clientWidth = scroller.clientWidth;
  }

  function page(direction: -1 | 1) {
    if (!scroller) return;
    const delta = direction * scroller.clientWidth * 0.85;
    scroller.scrollBy({ left: delta, behavior: 'smooth' });
    setTimeout(refreshMetrics, 350);
  }

  $effect(() => { refreshMetrics(); });
</script>

<div class="row relative" aria-label={ariaLabel}>
  <button
    type="button"
    class="arrow arrow-left"
    aria-label="Scroll left"
    onclick={() => page(-1)}
    disabled={atStart}
  >
    <ChevronLeft size={16} strokeWidth={1} />
  </button>

  <div
    bind:this={scroller}
    onscroll={refreshMetrics}
    data-testid="scroll-container"
    class="scroller flex gap-4 overflow-x-auto"
  >
    {#each items as it, i (i)}
      {@render item?.(it, i)}
    {/each}
  </div>

  <button
    type="button"
    class="arrow arrow-right"
    aria-label="Scroll right"
    onclick={() => page(1)}
    disabled={atEnd}
  >
    <ChevronRight size={16} strokeWidth={1} />
  </button>
</div>

<style>
  .row { padding: 0 36px; }
  .scroller {
    scroll-snap-type: x mandatory;
    scrollbar-width: thin;
  }
  .scroller > :global(*) {
    flex-shrink: 0;
    scroll-snap-align: start;
  }
  .arrow {
    position: absolute;
    top: 50%;
    transform: translateY(-50%);
    width: 32px;
    height: 32px;
    border-radius: 9999px;
    background: var(--fs-iron);
    color: var(--fs-vellum);
    display: flex;
    align-items: center;
    justify-content: center;
    border: 1px solid var(--fs-pewter);
    z-index: 1;
  }
  .arrow:hover:not(:disabled) { color: var(--fs-parchment); }
  .arrow:disabled { opacity: 0.3; cursor: not-allowed; }
  .arrow-left  { left: 0; }
  .arrow-right { right: 0; }
  @media (hover: hover) {
    .arrow { opacity: 0; transition: opacity 150ms ease; }
    .row:hover .arrow { opacity: 1; }
  }
</style>

• Step 12.4: Run tests + commit

cd web && pnpm test src/lib/components/HorizontalScrollRow.test.ts

Expected: 3/3 PASS. Commit:

git add web/src/lib/components/HorizontalScrollRow.svelte \
        web/src/lib/components/HorizontalScrollRow.test.ts
git commit -m "feat(web): add HorizontalScrollRow component"

---

Task 13 — <AlbumCard> polish + play overlay

Files:

• Modify: web/src/lib/components/AlbumCard.svelte

• Modify: web/src/lib/components/AlbumCard.test.ts

• Step 13.1: Update existing test mock to include playQueue

Edit web/src/lib/components/AlbumCard.test.ts — change the player mock at the top of the file:

vi.mock('$lib/player/store.svelte', () => ({
  enqueueTracks: vi.fn(),
  playQueue: vi.fn()
}));

And the corresponding import:

import { enqueueTracks, playQueue } from '$lib/player/store.svelte';

• Step 13.2: Append failing test for play overlay

Append inside the describe('AlbumCard', ...) block:

test('play overlay click fetches album detail and calls playQueue at index 0', async () => {
  const tracks: TrackRef[] = [
    { id: 't1', title: 'So What',
      album_id: 'xyz', album_title: 'Kind of Blue',
      artist_id: 'm-davis', artist_name: 'Miles Davis',
      track_number: 1, disc_number: 1, duration_sec: 545,
      stream_url: '/api/tracks/t1/stream' }
  ];
  const detail: AlbumDetail = { ...album, tracks };
  (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce(detail);

  render(AlbumCard, { props: { album } });
  await fireEvent.click(screen.getByRole('button', { name: /play kind of blue/i }));
  expect(api.get).toHaveBeenCalledWith('/api/albums/xyz');
  await Promise.resolve();
  await Promise.resolve();
  expect(playQueue).toHaveBeenCalledWith(tracks, 0);
});

• Step 13.3: Run test to verify failure

cd web && pnpm test src/lib/components/AlbumCard.test.ts

Expected: FAIL — no play button exists.

• Step 13.4: Rewrite AlbumCard.svelte

Replace the entire contents of web/src/lib/components/AlbumCard.svelte:

<script lang="ts">
  import type { AlbumRef, AlbumDetail } from '$lib/api/types';
  import { FALLBACK_COVER } from '$lib/media/covers';
  import { api } from '$lib/api/client';
  import { enqueueTracks, playQueue } from '$lib/player/store.svelte';
  import { Plus, Play } from 'lucide-svelte';
  import LikeButton from './LikeButton.svelte';

  let { album }: { album: AlbumRef } = $props();

  function onImgError(e: Event) {
    (e.currentTarget as HTMLImageElement).src = FALLBACK_COVER;
  }

  async function onAddClick(e: MouseEvent) {
    e.preventDefault();
    e.stopPropagation();
    const detail = await api.get<AlbumDetail>(`/api/albums/${album.id}`);
    enqueueTracks(detail.tracks);
  }

  async function onPlayClick(e: MouseEvent) {
    e.preventDefault();
    e.stopPropagation();
    const detail = await api.get<AlbumDetail>(`/api/albums/${album.id}`);
    playQueue(detail.tracks, 0);
  }
</script>

<div class="card relative">
  <a
    href={`/albums/${album.id}`}
    class="group block rounded focus-visible:ring-2 focus-visible:ring-accent"
  >
    <div class="art-wrap relative aspect-square w-full overflow-hidden rounded-md">
      <img
        src={album.cover_url}
        alt=""
        class="h-full w-full object-cover transition-transform group-hover:scale-[1.03]"
        loading="lazy"
        onerror={onImgError}
      />
      <button
        type="button"
        aria-label={`Play ${album.title}`}
        onclick={onPlayClick}
        class="play-overlay absolute inset-0 m-auto flex h-12 w-12 items-center justify-center rounded-full"
      >
        <Play size={24} strokeWidth={1.5} fill="currentColor" />
      </button>
    </div>
    <div class="mt-2 truncate text-sm font-medium text-text-primary">{album.title}</div>
    {#if album.artist_name}
      <div class="truncate text-xs text-text-secondary">{album.artist_name}</div>
    {/if}
    {#if album.year}
      <div class="text-xs text-text-secondary">{album.year}</div>
    {/if}
  </a>
  <div class="absolute right-2 top-2 z-10 flex gap-1">
    <LikeButton entityType="album" entityId={album.id} />
    <button
      type="button"
      aria-label="Add to queue"
      onclick={onAddClick}
      class="rounded-full bg-surface px-2 py-1 text-sm text-text-secondary hover:text-text-primary focus-visible:ring-2 focus-visible:ring-accent"
    >
      <Plus size={16} strokeWidth={1} />
    </button>
  </div>
</div>

<style>
  .play-overlay {
    background: var(--fs-accent);
    color: var(--fs-parchment);
    opacity: 0;
    transition: opacity 150ms ease;
  }
  @media (hover: hover) {
    .card:hover .play-overlay { opacity: 1; }
  }
  @media (hover: none) {
    .play-overlay { opacity: 1; }
  }
</style>

• Step 13.5: Run tests + commit

cd web && pnpm test src/lib/components/AlbumCard.test.ts

Expected: all PASS. Commit:

git add web/src/lib/components/AlbumCard.svelte web/src/lib/components/AlbumCard.test.ts
git commit -m "feat(web): polish AlbumCard with FabledSword tokens + play overlay"

---

Task 14 — <ArtistCard> (circular)

Files:

• Create: web/src/lib/components/ArtistCard.svelte

• Create: web/src/lib/components/ArtistCard.test.ts

• Step 14.1: Write failing test

Create web/src/lib/components/ArtistCard.test.ts:

import { afterEach, describe, expect, test, vi } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/svelte';
import type { ArtistRef, TrackRef } from '$lib/api/types';

vi.mock('$lib/api/client', () => ({
  api: { get: vi.fn() }
}));
vi.mock('$lib/player/store.svelte', () => ({
  playQueue: vi.fn()
}));

import ArtistCard from './ArtistCard.svelte';
import { api } from '$lib/api/client';
import { playQueue } from '$lib/player/store.svelte';

const artist: ArtistRef = {
  id: 'art-1',
  name: 'Boards of Canada',
  sort_name: 'Boards of Canada',
  album_count: 5,
  cover_url: '/api/albums/cov-1/cover'
};

afterEach(() => vi.clearAllMocks());

describe('ArtistCard', () => {
  test('renders cover img inside link to /artists/:id', () => {
    const { container } = render(ArtistCard, { props: { artist } });
    const link = screen.getByRole('link');
    expect(link).toHaveAttribute('href', '/artists/art-1');
    const img = container.querySelector('img') as HTMLImageElement;
    expect(img.src).toContain('/api/albums/cov-1/cover');
  });

  test('falls back to Disc3 glyph when cover_url is empty', () => {
    const { container } = render(ArtistCard, {
      props: { artist: { ...artist, cover_url: '' } }
    });
    expect(container.querySelector('img')).not.toBeInTheDocument();
    expect(container.querySelector('svg')).toBeInTheDocument();
  });

  test('play overlay fetches tracks, shuffles, calls playQueue', async () => {
    const tracks: TrackRef[] = [
      { id: 't1', title: 'A', album_id: 'al-1', album_title: 'X',
        artist_id: 'art-1', artist_name: 'BoC',
        track_number: 1, disc_number: 1, duration_sec: 1, stream_url: '/x' },
      { id: 't2', title: 'B', album_id: 'al-1', album_title: 'X',
        artist_id: 'art-1', artist_name: 'BoC',
        track_number: 2, disc_number: 1, duration_sec: 1, stream_url: '/x' }
    ];
    (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce(tracks);

    render(ArtistCard, { props: { artist } });
    await fireEvent.click(screen.getByRole('button', { name: /play boards of canada/i }));
    expect(api.get).toHaveBeenCalledWith('/api/artists/art-1/tracks');
    await Promise.resolve();
    await Promise.resolve();
    expect(playQueue).toHaveBeenCalledOnce();
    const [calledTracks, idx] = (playQueue as ReturnType<typeof vi.fn>).mock.calls[0];
    expect(calledTracks).toHaveLength(2);
    expect(idx).toBe(0);
    expect(calledTracks.map((t: TrackRef) => t.id).sort()).toEqual(['t1', 't2']);
  });
});

• Step 14.2: Run test to verify failure

cd web && pnpm test src/lib/components/ArtistCard.test.ts

Expected: FAIL.

• Step 14.3: Create the component

Create web/src/lib/components/ArtistCard.svelte:

<script lang="ts">
  import type { ArtistRef, TrackRef } from '$lib/api/types';
  import { api } from '$lib/api/client';
  import { playQueue } from '$lib/player/store.svelte';
  import { Disc3, Play } from 'lucide-svelte';

  let { artist }: { artist: ArtistRef } = $props();

  function shuffle<T>(items: T[]): T[] {
    const arr = items.slice();
    for (let i = arr.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [arr[i], arr[j]] = [arr[j], arr[i]];
    }
    return arr;
  }

  async function onPlayClick(e: MouseEvent) {
    e.preventDefault();
    e.stopPropagation();
    const tracks = await api.get<TrackRef[]>(`/api/artists/${artist.id}/tracks`);
    if (tracks.length === 0) return;
    playQueue(shuffle(tracks), 0);
  }
</script>

<div class="card relative">
  <a
    href={`/artists/${artist.id}`}
    class="group block rounded focus-visible:ring-2 focus-visible:ring-accent"
  >
    <div class="art-wrap relative mx-auto aspect-square w-full overflow-hidden rounded-full bg-surface-hover">
      {#if artist.cover_url}
        <img
          src={artist.cover_url}
          alt=""
          class="h-full w-full object-cover transition-transform group-hover:scale-[1.03]"
          loading="lazy"
        />
      {:else}
        <div class="flex h-full w-full items-center justify-center">
          <Disc3 size={32} strokeWidth={1.5} class="text-text-muted" />
        </div>
      {/if}
      <button
        type="button"
        aria-label={`Play ${artist.name}`}
        onclick={onPlayClick}
        class="play-overlay absolute inset-0 m-auto flex h-12 w-12 items-center justify-center rounded-full"
      >
        <Play size={24} strokeWidth={1.5} fill="currentColor" />
      </button>
    </div>
    <div class="mt-2 truncate text-center text-sm font-medium text-text-primary">{artist.name}</div>
  </a>
</div>

<style>
  .play-overlay {
    background: var(--fs-accent);
    color: var(--fs-parchment);
    opacity: 0;
    transition: opacity 150ms ease;
  }
  @media (hover: hover) {
    .card:hover .play-overlay { opacity: 1; }
  }
  @media (hover: none) {
    .play-overlay { opacity: 1; }
  }
</style>

• Step 14.4: Run tests + commit

cd web && pnpm test src/lib/components/ArtistCard.test.ts

Expected: 3/3 PASS. Commit:

git add web/src/lib/components/ArtistCard.svelte \
        web/src/lib/components/ArtistCard.test.ts
git commit -m "feat(web): add ArtistCard (circular) with play-shuffle overlay"

---

Task 15 — <CompactTrackCard>

Files:

• Create: web/src/lib/components/CompactTrackCard.svelte

• Create: web/src/lib/components/CompactTrackCard.test.ts

• Step 15.1: Write failing test

Create web/src/lib/components/CompactTrackCard.test.ts:

import { afterEach, describe, expect, test, vi } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/svelte';
import type { TrackRef } from '$lib/api/types';

vi.mock('$lib/player/store.svelte', () => ({
  playQueue: vi.fn()
}));

import CompactTrackCard from './CompactTrackCard.svelte';
import { playQueue } from '$lib/player/store.svelte';

const tracks: TrackRef[] = [
  { id: 't1', title: 'First', album_id: 'a1', album_title: 'A',
    artist_id: 'art-1', artist_name: 'Artist',
    track_number: 1, disc_number: 1, duration_sec: 1, stream_url: '/a' },
  { id: 't2', title: 'Second', album_id: 'a1', album_title: 'A',
    artist_id: 'art-1', artist_name: 'Artist',
    track_number: 2, disc_number: 1, duration_sec: 1, stream_url: '/b' },
  { id: 't3', title: 'Third', album_id: 'a1', album_title: 'A',
    artist_id: 'art-1', artist_name: 'Artist',
    track_number: 3, disc_number: 1, duration_sec: 1, stream_url: '/c' }
];

afterEach(() => vi.clearAllMocks());

describe('CompactTrackCard', () => {
  test('clicking the card calls playQueue with sectionTracks at the right index', async () => {
    render(CompactTrackCard, {
      props: { track: tracks[1], sectionTracks: tracks, index: 1 }
    });
    await fireEvent.click(screen.getByRole('button', { name: /play second/i }));
    expect(playQueue).toHaveBeenCalledWith(tracks, 1);
  });

  test('renders title and artist name', () => {
    render(CompactTrackCard, {
      props: { track: tracks[0], sectionTracks: tracks, index: 0 }
    });
    expect(screen.getByText('First')).toBeInTheDocument();
    expect(screen.getByText('Artist')).toBeInTheDocument();
  });
});

• Step 15.2: Create the component

Create web/src/lib/components/CompactTrackCard.svelte:

<script lang="ts">
  import type { TrackRef } from '$lib/api/types';
  import { playQueue } from '$lib/player/store.svelte';
  import { FALLBACK_COVER } from '$lib/media/covers';

  let {
    track,
    sectionTracks,
    index
  }: {
    track: TrackRef;
    sectionTracks: TrackRef[];
    index: number;
  } = $props();

  const coverUrl = $derived(`/api/albums/${track.album_id}/cover`);

  function onImgError(e: Event) {
    (e.currentTarget as HTMLImageElement).src = FALLBACK_COVER;
  }

  function onClick() {
    playQueue(sectionTracks, index);
  }
</script>

<button
  type="button"
  aria-label={`Play ${track.title}`}
  onclick={onClick}
  class="card group block w-36 rounded text-left focus-visible:ring-2 focus-visible:ring-accent"
>
  <div class="aspect-square w-full overflow-hidden rounded-md bg-surface-hover">
    <img
      src={coverUrl}
      alt=""
      class="h-full w-full object-cover transition-transform group-hover:scale-[1.03]"
      loading="lazy"
      onerror={onImgError}
    />
  </div>
  <div class="mt-2 truncate text-xs font-medium text-text-primary">{track.title}</div>
  <div class="truncate text-xs text-text-secondary">{track.artist_name}</div>
</button>

• Step 15.3: Run tests + commit

cd web && pnpm test src/lib/components/CompactTrackCard.test.ts

Expected: 2/2 PASS. Commit:

git add web/src/lib/components/CompactTrackCard.svelte \
        web/src/lib/components/CompactTrackCard.test.ts
git commit -m "feat(web): add CompactTrackCard for Most played rows"

---

Task 16 — <AlphabeticalGrid>

Files:

• Create: web/src/lib/components/AlphabeticalGrid.svelte

• Create: web/src/lib/components/AlphabeticalGrid.test.ts

• Step 16.1: Write failing test

Create web/src/lib/components/AlphabeticalGrid.test.ts:

import { describe, expect, test } from 'vitest';
import { render, screen } from '@testing-library/svelte';
import { createRawSnippet } from 'svelte';
import AlphabeticalGrid from './AlphabeticalGrid.svelte';

type Item = { id: string; key: string; label: string };

const items: Item[] = [
  { id: '1', key: 'A', label: 'Apple' },
  { id: '2', key: 'A', label: 'Avocado' },
  { id: '3', key: 'B', label: 'Banana' },
  { id: '4', key: 'D', label: 'Date' }   // skips C — divider must jump to D directly
];

describe('AlphabeticalGrid', () => {
  test('inserts a divider for each new key letter', () => {
    render(AlphabeticalGrid, {
      props: {
        items,
        getKey: (it: Item) => it.key,
        item: createRawSnippet((it: Item) => ({
          render: () => `<span>${it.label}</span>`
        }))
      }
    });
    // Three dividers (A, B, D); C is absent because no items use C.
    expect(screen.getByText('A')).toBeInTheDocument();
    expect(screen.getByText('B')).toBeInTheDocument();
    expect(screen.getByText('D')).toBeInTheDocument();
    expect(screen.queryByText('C')).not.toBeInTheDocument();
  });

  test('renders items in given order', () => {
    const { container } = render(AlphabeticalGrid, {
      props: {
        items,
        getKey: (it: Item) => it.key,
        item: createRawSnippet((it: Item) => ({
          render: () => `<span>${it.label}</span>`
        }))
      }
    });
    expect(container.textContent).toMatch(/A.*Apple.*Avocado.*B.*Banana.*D.*Date/s);
  });
});

NOTE: createRawSnippet is the Svelte 5 utility for synthesising snippets in tests; if it doesn't suit your renderer, swap to a wrapper component that exposes the snippet via <svelte:fragment>.

• Step 16.2: Run test to verify failure

cd web && pnpm test src/lib/components/AlphabeticalGrid.test.ts

Expected: FAIL.

• Step 16.3: Create the component

Create web/src/lib/components/AlphabeticalGrid.svelte:

<script lang="ts" generics="T">
  import type { Snippet } from 'svelte';

  let {
    items,
    getKey,
    item
  }: {
    items: T[];
    getKey: (it: T) => string;
    item: Snippet<[T]>;
  } = $props();

  // Compute the divider letter for each item; if it differs from the
  // previous item's letter, that index gets a divider above it.
  const segments = $derived.by(() => {
    const out: { divider: string | null; item: T }[] = [];
    let last: string | null = null;
    for (const it of items) {
      const k = (getKey(it) || '').charAt(0).toUpperCase();
      if (k !== last) {
        out.push({ divider: k, item: it });
        last = k;
      } else {
        out.push({ divider: null, item: it });
      }
    }
    return out;
  });
</script>

<div class="alpha-grid">
  {#each segments as seg, i (i)}
    {#if seg.divider}
      <div class="divider">
        <span class="letter">{seg.divider}</span>
        <span class="rule"></span>
      </div>
    {/if}
    <div class="cell">
      {@render item(seg.item)}
    </div>
  {/each}
</div>

<style>
  .alpha-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
    gap: 16px;
  }
  .divider {
    grid-column: 1 / -1;
    display: flex;
    align-items: center;
    gap: 12px;
    padding-top: 8px;
  }
  .letter {
    font-family: var(--fs-font-display);
    font-size: 24px;
    font-weight: 500;
    color: var(--fs-parchment);
  }
  .rule {
    flex: 1;
    height: 1px;
    background: var(--fs-pewter);
  }
</style>

• Step 16.4: Run tests + commit

cd web && pnpm test src/lib/components/AlphabeticalGrid.test.ts

Expected: 2/2 PASS. Commit:

git add web/src/lib/components/AlphabeticalGrid.svelte \
        web/src/lib/components/AlphabeticalGrid.test.ts
git commit -m "feat(web): add AlphabeticalGrid wrapper with letter dividers"

---

Task 17 — Home page rewrite (/+page.svelte)

Files:

• Modify: web/src/routes/+page.svelte (full rewrite)

• Modify: web/src/routes/artists.test.ts (assertions migrate)

• Step 17.1: Rewrite +page.svelte

Replace the entire contents of web/src/routes/+page.svelte:

<script lang="ts">
  import { createHomeQuery } from '$lib/api/home';
  import HorizontalScrollRow from '$lib/components/HorizontalScrollRow.svelte';
  import AlbumCard from '$lib/components/AlbumCard.svelte';
  import ArtistCard from '$lib/components/ArtistCard.svelte';
  import CompactTrackCard from '$lib/components/CompactTrackCard.svelte';
  import ApiErrorBanner from '$lib/components/ApiErrorBanner.svelte';
  import { useDelayed } from '$lib/utils/useDelayed.svelte';

  const queryStore = createHomeQuery();
  const query = $derived($queryStore);
  const data = $derived(query.data);

  const showSkeleton = useDelayed(() => query.isPending);

  // Each "Most played" row gets 25 of the 75 tracks (server returns up
  // to 75; rows 0/1/2 slice [0..25), [25..50), [50..75)).
  function chunk<T>(items: T[], size: number): T[][] {
    const out: T[][] = [];
    for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
    return out;
  }
</script>

<div class="space-y-8">
  {#if query.isError}
    <ApiErrorBanner error={query.error} onRetry={query.refetch} />
  {:else if showSkeleton.value && !data}
    <p class="text-text-secondary">Loading…</p>
  {:else if data}
    <!-- Recently added: 50 albums in 2 rows of 25 -->
    <section class="space-y-3">
      <header>
        <h2 class="font-display text-2xl font-medium text-text-primary">Recently added</h2>
      </header>
      {#if data.recently_added_albums.length === 0}
        <p class="text-text-secondary">Nothing added yet. Scan a folder via the server's config.</p>
      {:else}
        {#each chunk(data.recently_added_albums, 25) as row, i (i)}
          <HorizontalScrollRow items={row} ariaLabel="Recently added row {i + 1}">
            {#snippet item(album)}
              <div class="w-44"><AlbumCard {album} /></div>
            {/snippet}
          </HorizontalScrollRow>
        {/each}
      {/if}
    </section>

    <!-- Rediscover: albums + artists -->
    <section class="space-y-3">
      <header>
        <h2 class="font-display text-2xl font-medium text-text-primary">Rediscover</h2>
      </header>
      {#if data.rediscover_albums.length === 0 && data.rediscover_artists.length === 0}
        <p class="text-text-secondary">No forgotten favourites yet. Like some albums or artists to fill this in.</p>
      {:else}
        {#if data.rediscover_albums.length > 0}
          <HorizontalScrollRow items={data.rediscover_albums} ariaLabel="Rediscover albums">
            {#snippet item(album)}
              <div class="w-44"><AlbumCard {album} /></div>
            {/snippet}
          </HorizontalScrollRow>
        {/if}
        {#if data.rediscover_artists.length > 0}
          <HorizontalScrollRow items={data.rediscover_artists} ariaLabel="Rediscover artists">
            {#snippet item(artist)}
              <div class="w-36"><ArtistCard {artist} /></div>
            {/snippet}
          </HorizontalScrollRow>
        {/if}
      {/if}
    </section>

    <!-- Most played: 75 tracks in 3 rows of 25 -->
    <section class="space-y-3">
      <header>
        <h2 class="font-display text-2xl font-medium text-text-primary">Most played</h2>
      </header>
      {#if data.most_played_tracks.length === 0}
        <p class="text-text-secondary">No plays to draw from. Listen to something.</p>
      {:else}
        {#each chunk(data.most_played_tracks, 25) as row, i (i)}
          <HorizontalScrollRow items={row} ariaLabel="Most played row {i + 1}">
            {#snippet item(track, idx)}
              <CompactTrackCard
                {track}
                sectionTracks={row}
                index={idx}
              />
            {/snippet}
          </HorizontalScrollRow>
        {/each}
      {/if}
    </section>

    <!-- Last played artists -->
    <section class="space-y-3">
      <header>
        <h2 class="font-display text-2xl font-medium text-text-primary">Last played</h2>
      </header>
      {#if data.last_played_artists.length === 0}
        <p class="text-text-secondary">No recent plays.</p>
      {:else}
        <HorizontalScrollRow items={data.last_played_artists} ariaLabel="Last played artists">
          {#snippet item(artist)}
            <div class="w-36"><ArtistCard {artist} /></div>
          {/snippet}
        </HorizontalScrollRow>
      {/if}
    </section>
  {/if}
</div>

• Step 17.2: Update artists.test.ts to point at the new home behavior

Open web/src/routes/artists.test.ts. The existing tests assert the old library-list behavior of /. Either move them to a new library/artists.test.ts (Task 18 covers that page) or delete them outright in this step. Decision: delete this file in this task because the replacement tests live with /library/artists/+page.svelte.

git rm web/src/routes/artists.test.ts

• Step 17.3: Run frontend tests + check

cd web && pnpm check && pnpm test

Expected: all PASS. The new home page has no dedicated component test (see Task 22 for an integration smoke test); pnpm check confirms type correctness against the new query/types.

• Step 17.4: Commit

git add web/src/routes/+page.svelte
git rm web/src/routes/artists.test.ts
git commit -m "feat(web): rewrite / as home page composing 4 horizontal-scroll sections"

---

Task 18 — /library/artists page

Files:

• Create: web/src/routes/library/artists/+page.svelte

• Create: web/src/routes/library/artists/page.test.ts

• Step 18.1: Write the page

Create web/src/routes/library/artists/+page.svelte:

<script lang="ts">
  import { createArtistsQuery } from '$lib/api/queries';
  import ArtistCard from '$lib/components/ArtistCard.svelte';
  import AlphabeticalGrid from '$lib/components/AlphabeticalGrid.svelte';
  import ApiErrorBanner from '$lib/components/ApiErrorBanner.svelte';
  import { useDelayed } from '$lib/utils/useDelayed.svelte';

  const queryStore = $derived(createArtistsQuery('alpha'));
  const query = $derived($queryStore);
  const artists = $derived(query.data?.pages?.flatMap((p) => p.items) ?? []);
  const total = $derived(query.data?.pages?.[0]?.total ?? 0);
  const showSkeleton = useDelayed(() => query.isPending);
</script>

<div class="space-y-4">
  <header>
    <h1 class="font-display text-2xl font-medium text-text-primary">Artists</h1>
    {#if !query.isPending && !query.isError}
      <p class="text-sm text-text-secondary">
        {total} {total === 1 ? 'artist' : 'artists'}
      </p>
    {/if}
  </header>

  {#if query.isError}
    <ApiErrorBanner error={query.error} onRetry={query.refetch} />
  {:else if showSkeleton.value && artists.length === 0}
    <p class="text-text-secondary">Loading…</p>
  {:else if !query.isPending && total === 0}
    <p class="text-text-secondary">No artists yet — scan a library folder via the server's config.</p>
  {:else}
    <AlphabeticalGrid
      items={artists}
      getKey={(a) => a.sort_name || a.name}
    >
      {#snippet item(a)}
        <ArtistCard artist={a} />
      {/snippet}
    </AlphabeticalGrid>

    {#if query.hasNextPage}
      <button
        type="button"
        class="w-full rounded bg-surface py-2 text-sm hover:bg-surface-hover disabled:opacity-60"
        disabled={query.isFetchingNextPage}
        onclick={() => query.fetchNextPage()}
      >
        {query.isFetchingNextPage ? 'Loading…' : 'Load more'}
      </button>
    {:else if artists.length > 0}
      <p class="py-2 text-center text-sm text-text-secondary">End of library</p>
    {/if}
  {/if}
</div>

• Step 18.2: Add a smoke test

Create web/src/routes/library/artists/page.test.ts:

import { describe, expect, test, vi } from 'vitest';
import { render, screen } from '@testing-library/svelte';
import { readable } from 'svelte/store';

vi.mock('$lib/api/queries', () => ({
  createArtistsQuery: () => readable({
    data: { pages: [{
      items: [
        { id: 'a1', name: 'Alpha', sort_name: 'Alpha', album_count: 1, cover_url: '' },
        { id: 'b1', name: 'Beta',  sort_name: 'Beta',  album_count: 2, cover_url: '' }
      ],
      total: 2, limit: 50, offset: 0
    }] },
    isPending: false,
    isError: false,
    hasNextPage: false,
    isFetchingNextPage: false,
    refetch: () => {},
    fetchNextPage: () => {}
  })
}));
vi.mock('$lib/api/client', () => ({ api: { get: vi.fn() } }));
vi.mock('$lib/player/store.svelte', () => ({ playQueue: vi.fn() }));

import Page from './+page.svelte';

describe('/library/artists', () => {
  test('renders title + count + alphabetical dividers', () => {
    render(Page);
    expect(screen.getByRole('heading', { name: /artists/i })).toBeInTheDocument();
    expect(screen.getByText(/2 artists/)).toBeInTheDocument();
    expect(screen.getByText('A')).toBeInTheDocument();
    expect(screen.getByText('B')).toBeInTheDocument();
    expect(screen.getByText('Alpha')).toBeInTheDocument();
    expect(screen.getByText('Beta')).toBeInTheDocument();
  });
});

• Step 18.3: Run tests + commit

cd web && pnpm test src/routes/library/artists/page.test.ts

Expected: PASS. Commit:

git add web/src/routes/library/artists/
git commit -m "feat(web): add /library/artists wrapping-grid page"

---

Task 19 — /library/albums page

Files:

• Create: web/src/routes/library/albums/+page.svelte

• Create: web/src/routes/library/albums/page.test.ts

• Step 19.1: Write the page

Create web/src/routes/library/albums/+page.svelte:

<script lang="ts">
  import { createAlbumsAlphaInfiniteQuery } from '$lib/api/albums';
  import AlbumCard from '$lib/components/AlbumCard.svelte';
  import AlphabeticalGrid from '$lib/components/AlphabeticalGrid.svelte';
  import ApiErrorBanner from '$lib/components/ApiErrorBanner.svelte';
  import { useDelayed } from '$lib/utils/useDelayed.svelte';

  const queryStore = createAlbumsAlphaInfiniteQuery();
  const query = $derived($queryStore);
  const albums = $derived(query.data?.pages?.flatMap((p) => p.items) ?? []);
  const total = $derived(query.data?.pages?.[0]?.total ?? 0);
  const showSkeleton = useDelayed(() => query.isPending);
</script>

<div class="space-y-4">
  <header>
    <h1 class="font-display text-2xl font-medium text-text-primary">Albums</h1>
    {#if !query.isPending && !query.isError}
      <p class="text-sm text-text-secondary">
        {total} {total === 1 ? 'album' : 'albums'}
      </p>
    {/if}
  </header>

  {#if query.isError}
    <ApiErrorBanner error={query.error} onRetry={query.refetch} />
  {:else if showSkeleton.value && albums.length === 0}
    <p class="text-text-secondary">Loading…</p>
  {:else if !query.isPending && total === 0}
    <p class="text-text-secondary">No albums yet — scan a library folder via the server's config.</p>
  {:else}
    <AlphabeticalGrid
      items={albums}
      getKey={(a) => a.sort_title || a.title}
    >
      {#snippet item(album)}
        <AlbumCard {album} />
      {/snippet}
    </AlphabeticalGrid>

    {#if query.hasNextPage}
      <button
        type="button"
        class="w-full rounded bg-surface py-2 text-sm hover:bg-surface-hover disabled:opacity-60"
        disabled={query.isFetchingNextPage}
        onclick={() => query.fetchNextPage()}
      >
        {query.isFetchingNextPage ? 'Loading…' : 'Load more'}
      </button>
    {:else if albums.length > 0}
      <p class="py-2 text-center text-sm text-text-secondary">End of library</p>
    {/if}
  {/if}
</div>

• Step 19.2: Add a smoke test

Create web/src/routes/library/albums/page.test.ts:

import { describe, expect, test, vi } from 'vitest';
import { render, screen } from '@testing-library/svelte';
import { readable } from 'svelte/store';

vi.mock('$lib/api/albums', () => ({
  createAlbumsAlphaInfiniteQuery: () => readable({
    data: { pages: [{
      items: [
        { id: 'a1', title: 'Apple',  sort_title: 'Apple',
          artist_id: 'art-1', artist_name: 'X',
          track_count: 5, duration_sec: 100, cover_url: '/api/albums/a1/cover' },
        { id: 'b1', title: 'Banana', sort_title: 'Banana',
          artist_id: 'art-1', artist_name: 'X',
          track_count: 3, duration_sec: 50,  cover_url: '/api/albums/b1/cover' }
      ],
      total: 2, limit: 50, offset: 0
    }] },
    isPending: false,
    isError: false,
    hasNextPage: false,
    isFetchingNextPage: false,
    refetch: () => {},
    fetchNextPage: () => {}
  }),
  ALBUM_PAGE_SIZE: 50
}));
vi.mock('$lib/api/client', () => ({ api: { get: vi.fn() } }));
vi.mock('$lib/player/store.svelte', () => ({
  enqueueTracks: vi.fn(),
  playQueue: vi.fn()
}));
vi.mock('$lib/api/likes', () => ({
  createLikedIdsQuery: () => readable({
    data: { track_ids: [], album_ids: [], artist_ids: [] },
    isPending: false, isError: false
  }),
  likeEntity: vi.fn(),
  unlikeEntity: vi.fn()
}));

import Page from './+page.svelte';

describe('/library/albums', () => {
  test('renders title + count + alphabetical dividers', () => {
    render(Page);
    expect(screen.getByRole('heading', { name: /albums/i })).toBeInTheDocument();
    expect(screen.getByText(/2 albums/)).toBeInTheDocument();
    expect(screen.getByText('A')).toBeInTheDocument();
    expect(screen.getByText('B')).toBeInTheDocument();
    expect(screen.getByText('Apple')).toBeInTheDocument();
    expect(screen.getByText('Banana')).toBeInTheDocument();
  });
});

• Step 19.3: Run tests + commit

cd web && pnpm test src/routes/library/albums/page.test.ts

Expected: PASS. Commit:

git add web/src/routes/library/albums/
git commit -m "feat(web): add /library/albums wrapping-grid page"

---

Task 20 — Shell nav update + retire <ArtistRow>

Files:

• Modify: web/src/lib/components/Shell.svelte

• Modify: web/src/lib/components/Shell.test.ts

• Delete: web/src/lib/components/ArtistRow.svelte

• Delete: web/src/lib/components/ArtistRow.test.ts

• Modify: web/src/lib/components/LibrarySkeleton.svelte (optional cleanup — see Step 20.5)

• Step 20.1: Update Shell.svelte navItems

Modify web/src/lib/components/Shell.svelte — replace the navItems array:

  const navItems = [
    { href: '/',                label: 'Home' },
    { href: '/library/artists', label: 'Artists' },
    { href: '/library/albums',  label: 'Albums' },
    { href: '/library/liked',   label: 'Liked' },
    { href: '/library/hidden',  label: 'Hidden' },
    { href: '/search',          label: 'Search' },
    { href: '/discover',        label: 'Discover' },
    { href: '/requests',        label: 'Requests' },
    { href: '/playlists',       label: 'Playlists' },
    { href: '/settings',        label: 'Settings' }
  ];

• Step 20.2: Update Shell.test.ts assertions

Open web/src/lib/components/Shell.test.ts. Locate the assertion that lists nav items (search for Library) and replace with the new order:

test('renders nav items in expected order', () => {
  render(Shell, { props: { children } });
  const labels = ['Home', 'Artists', 'Albums', 'Liked', 'Hidden', 'Search',
                  'Discover', 'Requests', 'Playlists', 'Settings'];
  for (const label of labels) {
    expect(screen.getByRole('link', { name: label })).toBeInTheDocument();
  }
});

If the existing test does not assert the exact label list, add this test — preserving any existing tests in the file.

• Step 20.3: Audit <ArtistRow> usages and remove

Run:

cd web && grep -rln "ArtistRow" src/ --include="*.svelte" --include="*.ts"

Expected (after Task 17): only ArtistRow.svelte and ArtistRow.test.ts. If any other file imports ArtistRow, replace those imports with ArtistCard and adjust the call site (likely a <ArtistRow {artist} /> becomes <ArtistCard {artist} />). The migration is mechanical.

Then delete:

git rm web/src/lib/components/ArtistRow.svelte \
       web/src/lib/components/ArtistRow.test.ts

• Step 20.4: Run all frontend tests

cd web && pnpm check && pnpm test

Expected: all PASS. Type errors at this step usually mean a forgotten ArtistRow import; fix per Step 20.3.

• Step 20.5: Inspect LibrarySkeleton usage

Run:

cd web && grep -rln "LibrarySkeleton" src/ --include="*.svelte" --include="*.ts"

If the only remaining importers (after Tasks 17/18/19) use only the existing variant="grid" or variant="list" props, no change is needed — the skeleton was always extensible. Leave it. If a call site references the old variant="list" for a now-deleted page, delete that import.

• Step 20.6: Commit

git add web/src/lib/components/Shell.svelte \
        web/src/lib/components/Shell.test.ts
git rm web/src/lib/components/ArtistRow.svelte \
       web/src/lib/components/ArtistRow.test.ts
git commit -m "feat(web): update nav (Home/Artists/Albums); retire ArtistRow"

---

Verification (post-task-20)

After all tasks land, the following all-green checks confirm M6a is ready for PR:

• Backend full test pass

docker run --rm --network minstrel_minstrel \
  -v "$(pwd):/src" -w /src \
  -e MINSTREL_TEST_DATABASE_URL='postgres://minstrel:minstrel@postgres:5432/minstrel?sslmode=disable' \
  golang:1.23-bookworm \
  go test ./... -count=1

Expected: all PASS except the pre-existing internal/library/TestScanner_Integration flake (per project_scanner_flake.md memory).

• Frontend full test pass + typecheck

cd web && pnpm check && pnpm test && pnpm build

Expected: typecheck clean, all unit tests PASS, production build succeeds.

• Manual smoke

Start dev server (docker compose up -d + cd web && pnpm dev); log in; verify:

1. / renders all four sections; rows scroll independently with arrow buttons.
2. Hovering an album card reveals the play overlay; clicking it queues the album from track 1.
3. Hovering an artist card reveals the play overlay; clicking it shuffle-plays artist tracks.
4. Compact track cards click-play in section context.
5. Nav: clicking "Artists" goes to /library/artists (wrapping grid + dividers).
6. Nav: clicking "Albums" goes to /library/albums (wrapping grid + dividers).
7. Quarantined tracks for the test user are absent from "Most played" and from the artist-shuffle queue.

• Commit + push to dev branch

git push -u origin dev

• Open Forgejo PR via MCP (per project_no_github.md)

Use mcp__forgejo__pull_request_write with action=create, base=main, head=dev. Title: feat(m6a): home page redesign + library list relocation. Body summarises the slice and lists the verification steps above.

---

Notes for the implementer

• No DB migration. All sections derive from existing tables.
• Tests gated on MINSTREL_TEST_DATABASE_URL. Without it, integration tests skip cleanly.
• t.Context() is Go 1.24+; this repo runs Go 1.23. Always use context.Background() in tests.
• Forgejo only. No GitHub. Use the forgejo MCP for PR ops.
• TanStack v5 patterns. createInfiniteQuery for paged lists; createQuery for one-shots; staleTime: 60_000 on the home query.
• FabledSword tokens always. No raw hex in component styles. Use bg-surface, text-text-primary, border-border, text-accent, etc.
• Lucide icons. 16px/1px stroke for chrome buttons, 32px/1.5px for fallbacks/overlays.
• Sentence case copy. "Recently added", "Most played", not "Recently Added".
• No half-finished UI. Per the spec's "no in-between steps" rule, every surface added here ships finished.