Merge pull request 'Multi-value genres for FLAC/Ogg/MP4, readable tinted and error text, no missing-track seeds' (#143) from dev into main

internal/db/dbq/system_playlists.sql.go

@@ -452,6 +452,7 @@ SELECT COALESCE(
        FROM tracks t
        JOIN albums a ON a.id = t.album_id
       WHERE t.artist_id = $2
+        AND t.missing_since IS NULL  -- #2701: the play branch filters; this one must too
       ORDER BY a.release_date DESC NULLS LAST,
                t.disc_number NULLS LAST,
                t.track_number NULLS LAST,
@@ -497,6 +498,7 @@ alltime AS (
 liked AS (
     SELECT gl.track_id AS id, 0::bigint AS c, 2 AS tier
       FROM general_likes gl
+      JOIN tracks t ON t.id = gl.track_id AND t.missing_since IS NULL
      WHERE gl.user_id = $1
 ),
 chosen AS (
@@ -526,6 +528,10 @@ SELECT id
 // Widened from a hard 7-day window, which made For-You disappear
 // after a week of not listening and never recover on a self-hosted
 // library with sparse history.
+// A likes-only read still joins tracks: a like outlives its file, and a
+// seed whose file is gone points For You at something the user can't hear
+// (#2701). The other two tiers get the same filter from their play_events
+// join.
 func (q *Queries) PickTopPlayedTracksForUser(ctx context.Context, userID pgtype.UUID) ([]pgtype.UUID, error) {
 	rows, err := q.db.Query(ctx, pickTopPlayedTracksForUser, userID)
 	if err != nil {

internal/db/queries/system_playlists.sql

@@ -161,9 +161,14 @@ alltime AS (
        AND pe.was_skipped = false
      GROUP BY t.id
 ),
+-- A likes-only read still joins tracks: a like outlives its file, and a
+-- seed whose file is gone points For You at something the user can't hear
+-- (#2701). The other two tiers get the same filter from their play_events
+-- join.
 liked AS (
     SELECT gl.track_id AS id, 0::bigint AS c, 2 AS tier
       FROM general_likes gl
+      JOIN tracks t ON t.id = gl.track_id AND t.missing_since IS NULL
      WHERE gl.user_id = $1
 ),
 chosen AS (
@@ -201,6 +206,7 @@ SELECT COALESCE(
        FROM tracks t
        JOIN albums a ON a.id = t.album_id
       WHERE t.artist_id = $2
+        AND t.missing_since IS NULL  -- #2701: the play branch filters; this one must too
       ORDER BY a.release_date DESC NULLS LAST,
                t.disc_number NULLS LAST,
                t.track_number NULLS LAST,

internal/library/genre.go

@@ -32,11 +32,25 @@ func extractGenres(meta tag.Metadata, rs io.ReadSeeker) (genres []string, fellBa
 		// No frame at all is the common case for untagged files, and
 		// dhowden/tag will have nothing either — not worth flagging.
 		fellBack = meta.Genre() != ""
-	default:
-		// Vorbis comments (FLAC/OGG/Opus) and MP4 atoms don't go through
-		// dhowden's welding path, so its value is already a faithful read of
-		// the primary genre. Multi-value handling for those containers is a
-		// separate, unproven concern — see #2500.
+	case tag.VORBIS, tag.MP4:
+		// dhowden/tag keeps only the last of a repeated field here (#2500):
+		// see vorbisgenre.go and mp4genre.go.
+		var values []string
+		var err error
+		switch {
+		case meta.Format() == tag.MP4:
+			values, err = readMP4GenreValues(rs)
+		case meta.FileType() == tag.OGG:
+			values, err = readOggGenreValues(rs)
+		default:
+			values, err = readFLACGenreValues(rs)
+		}
+		if err == nil && len(values) > 0 {
+			return normaliseGenres(values), false
+		}
+		// err == nil with no values: the file declares no genre of its own
+		// (or, for MP4, only the numeric gnre atom, which dhowden resolves).
+		fellBack = err != nil && meta.Genre() != ""
 	}
 	return normaliseGenres([]string{meta.Genre()}), fellBack
 }

internal/library/mp4genre.go

@@ -0,0 +1,168 @@
+package library
+
+import (
+	"encoding/binary"
+	"errors"
+	"io"
+	"strings"
+)
+
+// MP4 has the same gap as Vorbis comments (#2500). A tag writer stores several
+// genres as several "data" atoms inside one ©gen atom (mutagen and Picard do),
+// or occasionally as repeated ©gen atoms. dhowden/tag keeps atoms in a map keyed
+// by name (mp4.go: m.data[name] = data), so one value survives either way.
+//
+// Path to the values: moov > udta > meta > ilst > ©gen > data. A file that
+// carries only the numeric "gnre" atom has no ©gen; this reader returns
+// (nil, nil) for it, and extractGenres falls back to dhowden/tag, which resolves
+// gnre to a name.
+
+// maxMP4GenreAtomSize caps how much of one ©gen atom is buffered. Genre text is
+// bytes; the cap only stops a corrupt size from making the scanner allocate.
+const maxMP4GenreAtomSize = 1 << 20
+
+var errMalformedAtom = errors.New("library: malformed MP4 atom")
+
+type mp4Atom struct {
+	kind        string
+	body, limit int64 // body start and end offsets in the file
+}
+
+// readMP4Atom reads the atom header at pos, which must lie within [pos, limit).
+func readMP4Atom(rs io.ReadSeeker, pos, limit int64) (mp4Atom, error) {
+	if _, err := rs.Seek(pos, io.SeekStart); err != nil {
+		return mp4Atom{}, err
+	}
+	var hdr [8]byte
+	if _, err := io.ReadFull(rs, hdr[:]); err != nil {
+		return mp4Atom{}, errMalformedAtom
+	}
+	size := int64(binary.BigEndian.Uint32(hdr[0:4]))
+	hdrLen := int64(8)
+	switch size {
+	case 0: // runs to the end of the enclosing atom
+		size = limit - pos
+	case 1: // 64-bit size follows the type
+		var large [8]byte
+		if _, err := io.ReadFull(rs, large[:]); err != nil {
+			return mp4Atom{}, errMalformedAtom
+		}
+		size = int64(binary.BigEndian.Uint64(large[:]))
+		hdrLen = 16
+	}
+	if size < hdrLen || size > limit-pos {
+		return mp4Atom{}, errMalformedAtom
+	}
+	return mp4Atom{kind: string(hdr[4:8]), body: pos + hdrLen, limit: pos + size}, nil
+}
+
+// findMP4Child returns the first child of the given kind in [start, end).
+func findMP4Child(rs io.ReadSeeker, start, end int64, kind string) (mp4Atom, bool, error) {
+	for pos := start; pos+8 <= end; {
+		a, err := readMP4Atom(rs, pos, end)
+		if err != nil {
+			return mp4Atom{}, false, err
+		}
+		if a.kind == kind {
+			return a, true, nil
+		}
+		pos = a.limit
+	}
+	return mp4Atom{}, false, nil
+}
+
+// readMP4GenreValues returns every ©gen value, in file order. rs is seeked
+// as needed, so it is safe to call after dhowden/tag has consumed the reader.
+func readMP4GenreValues(rs io.ReadSeeker) ([]string, error) {
+	end, err := rs.Seek(0, io.SeekEnd)
+	if err != nil {
+		return nil, err
+	}
+	// moov may sit after mdat; walking headers and seeking past bodies finds
+	// it either way without reading the audio.
+	cur := mp4Atom{body: 0, limit: end}
+	for _, kind := range []string{"moov", "udta", "meta"} {
+		next, found, err := findMP4Child(rs, cur.body, cur.limit, kind)
+		if err != nil {
+			return nil, errNoGenreFrame
+		}
+		if !found {
+			return nil, nil // no iTunes metadata at all
+		}
+		cur = next
+	}
+	// meta is a "full box" with four bytes of version and flags before its
+	// children in the ISO layout. QuickTime-style files omit them, so the
+	// first child (hdlr) starts straight away. Look before skipping.
+	if _, err := rs.Seek(cur.body, io.SeekStart); err != nil {
+		return nil, errNoGenreFrame
+	}
+	var peek [8]byte
+	if _, err := io.ReadFull(rs, peek[:]); err != nil {
+		return nil, errNoGenreFrame
+	}
+	if string(peek[4:8]) != "hdlr" {
+		cur.body += 4
+	}
+	ilst, found, err := findMP4Child(rs, cur.body, cur.limit, "ilst")
+	if err != nil {
+		return nil, errNoGenreFrame
+	}
+	if !found {
+		return nil, nil
+	}
+
+	var out []string
+	for pos := ilst.body; pos+8 <= ilst.limit; {
+		a, err := readMP4Atom(rs, pos, ilst.limit)
+		if err != nil {
+			return nil, errNoGenreFrame
+		}
+		pos = a.limit
+		if a.kind != "\xa9gen" {
+			continue
+		}
+		n := a.limit - a.body
+		if n > maxMP4GenreAtomSize {
+			return nil, errNoGenreFrame
+		}
+		if _, err := rs.Seek(a.body, io.SeekStart); err != nil {
+			return nil, errNoGenreFrame
+		}
+		body := make([]byte, n)
+		if _, err := io.ReadFull(rs, body); err != nil {
+			return nil, errNoGenreFrame
+		}
+		values, ok := mp4DataValues(body)
+		if !ok {
+			return nil, errNoGenreFrame
+		}
+		out = append(out, values...)
+	}
+	return out, nil
+}
+
+// mp4DataValues reads the "data" atoms in a ©gen body. Each is: size, "data",
+// a 4-byte type indicator (1 = UTF-8 text), a 4-byte locale, then the value.
+// Atoms of other types carry no text and are skipped.
+func mp4DataValues(b []byte) ([]string, bool) {
+	var out []string
+	for len(b) >= 8 {
+		size := binary.BigEndian.Uint32(b[0:4])
+		if size < 8 || uint64(size) > uint64(len(b)) {
+			return nil, false
+		}
+		atom := b[:size]
+		b = b[size:]
+		if string(atom[4:8]) != "data" || len(atom) < 16 {
+			continue
+		}
+		if binary.BigEndian.Uint32(atom[8:12])&0x00FFFFFF != 1 {
+			continue
+		}
+		if v := strings.TrimSpace(string(atom[16:])); v != "" {
+			out = append(out, v)
+		}
+	}
+	return out, true
+}

internal/library/scanner.go

@@ -60,7 +60,11 @@ var audioExtensions = map[string]bool{
 //	   (#5241). Lidarr names albums by release group, not by the release id
 //	   albums.mbid holds, so re-acquisition and request completion need it for
 //	   the albums already in the library, not only for files added from now on.
-const tagReadVersion int16 = 3
+//	4: every value of a repeated genre field is read for FLAC, Ogg Vorbis, Opus
+//	   and MP4 (#2500). dhowden/tag kept only the last, and 3,658 of the
+//	   operator's 4,092 FLACs declare more than one, so most of their genres
+//	   were never stored.
+const tagReadVersion int16 = 4
 
 type Stats struct {
 	Scanned int `json:"scanned"`

internal/library/vorbisgenre.go

@@ -0,0 +1,214 @@
+package library
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"io"
+	"strings"
+)
+
+// Why this file exists: Vorbis comments (FLAC, Ogg Vorbis, Opus) say a field
+// has several values by repeating it:
+//
+//	GENRE=Boom Bap
+//	GENRE=Downtempo
+//
+// dhowden/tag stores comments in a map keyed by field name
+// (vorbis.go: m.c[strings.ToLower(k)] = v), so each repeat overwrites the last
+// and only the final value survives. On the operator's library that was 3,658
+// of 4,092 FLAC files: Kupla's Life Forms declares eight genres and was stored
+// as "Instrumental Hip Hop" alone (#2500). Nothing looked corrupt; the other
+// seven were simply never seen by browse or the taste profile.
+//
+// The comment block is read here directly, as the ID3v2 genre frame is in
+// id3v2genre.go. Every other field still comes from dhowden/tag.
+
+// maxVorbisCommentSize caps a comment block or packet. Comments are kilobytes;
+// an embedded METADATA_BLOCK_PICTURE can take them to a few megabytes. The cap
+// only stops a corrupt length from making the scanner allocate wildly.
+const maxVorbisCommentSize = 16 << 20
+
+var errMalformedComment = errors.New("library: malformed Vorbis comment")
+
+// readFLACGenreValues returns every GENRE value in a FLAC file's comment block.
+// (nil, nil) means the file is readable and declares no genre. rs is seeked to
+// the start, so it is safe to call after dhowden/tag has consumed the reader.
+func readFLACGenreValues(rs io.ReadSeeker) ([]string, error) {
+	if _, err := rs.Seek(0, io.SeekStart); err != nil {
+		return nil, err
+	}
+	var magic [4]byte
+	if _, err := io.ReadFull(rs, magic[:]); err != nil {
+		return nil, errNoGenreFrame
+	}
+	// Some taggers prepend an ID3v2 tag to a FLAC. The FLAC stream starts after it.
+	if string(magic[:3]) == "ID3" {
+		var rest [6]byte
+		if _, err := io.ReadFull(rs, rest[:]); err != nil {
+			return nil, errNoGenreFrame
+		}
+		size := syncsafeInt(rest[2:6])
+		if size < 0 {
+			return nil, errNoGenreFrame
+		}
+		skip := int64(10 + size)
+		if rest[1]&0x10 != 0 {
+			skip += 10 // 2.4 footer
+		}
+		if _, err := rs.Seek(skip, io.SeekStart); err != nil {
+			return nil, errNoGenreFrame
+		}
+		if _, err := io.ReadFull(rs, magic[:]); err != nil {
+			return nil, errNoGenreFrame
+		}
+	}
+	if string(magic[:]) != "fLaC" {
+		return nil, errNoGenreFrame
+	}
+
+	for {
+		var hdr [4]byte
+		if _, err := io.ReadFull(rs, hdr[:]); err != nil {
+			return nil, errNoGenreFrame
+		}
+		last := hdr[0]&0x80 != 0
+		blockType := hdr[0] & 0x7F
+		size := int64(hdr[1])<<16 | int64(hdr[2])<<8 | int64(hdr[3])
+		switch blockType {
+		case 4: // VORBIS_COMMENT
+			body := make([]byte, size)
+			if _, err := io.ReadFull(rs, body); err != nil {
+				return nil, errNoGenreFrame
+			}
+			return vorbisCommentGenres(body)
+		case 127: // invalid by spec; nothing after it can be trusted
+			return nil, errNoGenreFrame
+		}
+		if last {
+			return nil, nil // no comment block at all
+		}
+		if _, err := rs.Seek(size, io.SeekCurrent); err != nil {
+			return nil, errNoGenreFrame
+		}
+	}
+}
+
+// readOggGenreValues returns every GENRE value in an Ogg Vorbis or Opus file.
+// The comments are the stream's second packet, which can span several pages
+// when it carries cover art, so pages are reassembled until it is complete.
+// Only the first logical stream is read; pages of any other are skipped.
+func readOggGenreValues(rs io.ReadSeeker) ([]string, error) {
+	if _, err := rs.Seek(0, io.SeekStart); err != nil {
+		return nil, err
+	}
+	br := bufio.NewReader(rs)
+	var (
+		serial    uint32
+		haveFirst bool
+		packet    []byte
+		packetIdx int
+	)
+	for {
+		var hdr [27]byte
+		if _, err := io.ReadFull(br, hdr[:]); err != nil {
+			return nil, errNoGenreFrame
+		}
+		if string(hdr[0:4]) != "OggS" {
+			return nil, errNoGenreFrame
+		}
+		pageSerial := binary.LittleEndian.Uint32(hdr[14:18])
+		segments := make([]byte, hdr[26])
+		if _, err := io.ReadFull(br, segments); err != nil {
+			return nil, errNoGenreFrame
+		}
+		if !haveFirst {
+			serial, haveFirst = pageSerial, true
+		}
+		if pageSerial != serial {
+			var n int64
+			for _, l := range segments {
+				n += int64(l)
+			}
+			if _, err := io.CopyN(io.Discard, br, n); err != nil {
+				return nil, errNoGenreFrame
+			}
+			continue
+		}
+		for _, l := range segments {
+			if len(packet)+int(l) > maxVorbisCommentSize {
+				return nil, errNoGenreFrame
+			}
+			seg := make([]byte, l)
+			if _, err := io.ReadFull(br, seg); err != nil {
+				return nil, errNoGenreFrame
+			}
+			packet = append(packet, seg...)
+			if l == 255 {
+				continue // the packet carries on in the next segment
+			}
+			if packetIdx == 1 {
+				return oggCommentGenres(packet)
+			}
+			packetIdx++
+			packet = packet[:0]
+		}
+	}
+}
+
+// oggCommentGenres strips the codec's comment-packet prefix. Ogg FLAC and Speex
+// are rare enough to leave to dhowden/tag.
+func oggCommentGenres(packet []byte) ([]string, error) {
+	switch {
+	case bytes.HasPrefix(packet, []byte("\x03vorbis")):
+		return vorbisCommentGenres(packet[7:])
+	case bytes.HasPrefix(packet, []byte("OpusTags")):
+		return vorbisCommentGenres(packet[8:])
+	}
+	return nil, errNoGenreFrame
+}
+
+// vorbisCommentGenres reads a comment block (vendor string, then a count of
+// length-prefixed "KEY=value" entries, little-endian lengths throughout) and
+// returns the GENRE values in file order. Field names are case-insensitive by
+// spec. Anything after the last entry, such as Vorbis's framing bit, is ignored.
+func vorbisCommentGenres(b []byte) ([]string, error) {
+	next := func() ([]byte, bool) {
+		if len(b) < 4 {
+			return nil, false
+		}
+		n := binary.LittleEndian.Uint32(b)
+		if uint64(n) > uint64(len(b)-4) {
+			return nil, false
+		}
+		field := b[4 : 4+n]
+		b = b[4+n:]
+		return field, true
+	}
+	if _, ok := next(); !ok { // vendor string
+		return nil, errMalformedComment
+	}
+	if len(b) < 4 {
+		return nil, errMalformedComment
+	}
+	count := binary.LittleEndian.Uint32(b)
+	b = b[4:]
+	var out []string
+	// Each entry costs at least four bytes, so a corrupt count runs out of
+	// input long before it runs up a loop.
+	for i := uint32(0); i < count; i++ {
+		field, ok := next()
+		if !ok {
+			return nil, errMalformedComment
+		}
+		key, value, found := strings.Cut(string(field), "=")
+		if !found || !strings.EqualFold(key, "GENRE") {
+			continue
+		}
+		if value = strings.TrimSpace(value); value != "" {
+			out = append(out, value)
+		}
+	}
+	return out, nil
+}

internal/library/vorbisgenre_test.go

@@ -0,0 +1,288 @@
+package library
+
+import (
+	"bytes"
+	"encoding/binary"
+	"strings"
+	"testing"
+
+	"github.com/dhowden/tag"
+)
+
+// vorbisComment builds a comment block: vendor, count, then each "KEY=value".
+func vorbisComment(fields ...string) []byte {
+	var b bytes.Buffer
+	vendor := "minstrel-test"
+	_ = binary.Write(&b, binary.LittleEndian, uint32(len(vendor)))
+	b.WriteString(vendor)
+	_ = binary.Write(&b, binary.LittleEndian, uint32(len(fields)))
+	for _, f := range fields {
+		_ = binary.Write(&b, binary.LittleEndian, uint32(len(f)))
+		b.WriteString(f)
+	}
+	return b.Bytes()
+}
+
+// buildFLAC assembles a STREAMINFO block and a comment block, optionally
+// behind an ID3v2 tag the way some taggers write them.
+func buildFLAC(withID3 bool, fields ...string) []byte {
+	var b bytes.Buffer
+	if withID3 {
+		pad := make([]byte, 20)
+		b.WriteString("ID3")
+		b.Write([]byte{4, 0, 0})
+		b.Write(synchsafeBytes(len(pad)))
+		b.Write(pad)
+	}
+	b.WriteString("fLaC")
+	b.Write([]byte{0x00, 0, 0, 34}) // STREAMINFO, not last
+	b.Write(make([]byte, 34))
+	vc := vorbisComment(fields...)
+	b.Write([]byte{0x84, byte(len(vc) >> 16), byte(len(vc) >> 8), byte(len(vc))}) // last, type 4
+	b.Write(vc)
+	return b.Bytes()
+}
+
+// oggCRC is the Ogg page checksum: CRC-32, polynomial 0x04c11db7, no
+// reflection, zero initial value. dhowden/tag verifies it, so the end-to-end
+// tests need real pages.
+func oggCRC(p []byte) uint32 {
+	var crc uint32
+	for _, c := range p {
+		crc ^= uint32(c) << 24
+		for i := 0; i < 8; i++ {
+			if crc&0x80000000 != 0 {
+				crc = crc<<1 ^ 0x04c11db7
+			} else {
+				crc <<= 1
+			}
+		}
+	}
+	return crc
+}
+
+// buildOgg lays packets out as Ogg pages for one logical stream, splitting a
+// packet across pages when it needs more than 255 lacing values.
+func buildOgg(serial uint32, packets ...[]byte) []byte {
+	var out bytes.Buffer
+	var seq uint32
+	for _, p := range packets {
+		var lacing []byte
+		for n := len(p); ; n -= 255 {
+			if n >= 255 {
+				lacing = append(lacing, 255)
+				continue
+			}
+			lacing = append(lacing, byte(n))
+			break
+		}
+		continued := false
+		for off := 0; len(lacing) > 0; {
+			segs := lacing
+			if len(segs) > 255 {
+				segs = segs[:255]
+			}
+			lacing = lacing[len(segs):]
+			n := 0
+			for _, s := range segs {
+				n += int(s)
+			}
+			var page bytes.Buffer
+			page.WriteString("OggS")
+			page.WriteByte(0)
+			flags := byte(0)
+			if continued {
+				flags |= 0x01
+			}
+			if seq == 0 {
+				flags |= 0x02
+			}
+			page.WriteByte(flags)
+			page.Write(make([]byte, 8)) // granule position
+			_ = binary.Write(&page, binary.LittleEndian, serial)
+			_ = binary.Write(&page, binary.LittleEndian, seq)
+			page.Write(make([]byte, 4)) // checksum, filled below
+			page.WriteByte(byte(len(segs)))
+			page.Write(segs)
+			page.Write(p[off : off+n])
+			raw := page.Bytes()
+			binary.LittleEndian.PutUint32(raw[22:26], oggCRC(raw))
+			out.Write(raw)
+			off += n
+			seq++
+			continued = true
+		}
+	}
+	return out.Bytes()
+}
+
+func vorbisIdent() []byte { return append([]byte("\x01vorbis"), make([]byte, 23)...) }
+
+// mp4Box wraps children in an atom of the given kind.
+func mp4Box(kind string, children ...[]byte) []byte {
+	body := bytes.Join(children, nil)
+	b := make([]byte, 8, 8+len(body))
+	binary.BigEndian.PutUint32(b, uint32(8+len(body)))
+	copy(b[4:], kind)
+	return append(b, body...)
+}
+
+func mp4Text(value string) []byte {
+	return mp4Box("data", []byte{0, 0, 0, 1, 0, 0, 0, 0}, []byte(value))
+}
+
+// buildMP4 places the ©gen atoms under moov/udta/meta/ilst. isoMeta adds the
+// four version/flags bytes ISO files carry before meta's children.
+func buildMP4(isoMeta bool, genAtoms ...[]byte) []byte {
+	ilst := mp4Box("ilst", append([][]byte{mp4Box("\xa9nam", mp4Text("A Song"))}, genAtoms...)...)
+	hdlr := mp4Box("hdlr", make([]byte, 25))
+	var meta []byte
+	if isoMeta {
+		meta = mp4Box("meta", []byte{0, 0, 0, 0}, hdlr, ilst)
+	} else {
+		meta = mp4Box("meta", hdlr, ilst)
+	}
+	ftyp := mp4Box("ftyp", []byte("M4A \x00\x00\x00\x00M4A mp42isom"))
+	mdat := mp4Box("mdat", make([]byte, 64))
+	// moov after mdat, as many encoders write it.
+	return bytes.Join([][]byte{ftyp, mdat, mp4Box("moov", mp4Box("udta", meta))}, nil)
+}
+
+var lifeForms = []string{
+	"Boom Bap", "Downtempo", "Hip Hop", "Instrumental",
+	"Lo-Fi", "Lo-Fi Hip Hop", "Chillwave", "Instrumental Hip Hop",
+}
+
+func genreFields(values ...string) []string {
+	out := make([]string, len(values))
+	for i, v := range values {
+		out[i] = "GENRE=" + v
+	}
+	return out
+}
+
+// The #2500 regression, shaped like the operator's Kupla - Life Forms files:
+// eight GENRE fields, of which dhowden/tag keeps the last.
+func TestExtractGenres_FLACRepeatedFields(t *testing.T) {
+	data := buildFLAC(false, append([]string{"TITLE=Eons"}, genreFields(lifeForms...)...)...)
+	rs := bytes.NewReader(data)
+	meta, err := tag.ReadFrom(rs)
+	if err != nil {
+		t.Fatalf("tag.ReadFrom: %v", err)
+	}
+	// Confirm the upstream behaviour this fix exists for is still present.
+	if got := meta.Genre(); got != "Instrumental Hip Hop" {
+		t.Logf("note: dhowden/tag no longer keeps only the last GENRE (got %q)", got)
+	}
+	genres, fellBack := extractGenres(meta, rs)
+	if fellBack {
+		t.Error("fellBack = true, want false")
+	}
+	if !equalStrings(genres, lifeForms) {
+		t.Errorf("genres = %q, want %q", genres, lifeForms)
+	}
+}
+
+func TestReadFLACGenreValues(t *testing.T) {
+	tests := []struct {
+		name string
+		data []byte
+		want []string
+		err  bool
+	}{
+		{"field names are case-insensitive", buildFLAC(false, "genre=Shoegaze", "Genre=Dream Pop"), []string{"Shoegaze", "Dream Pop"}, false},
+		{"behind an ID3v2 tag", buildFLAC(true, "GENRE=Jazz", "GENRE=Bop"), []string{"Jazz", "Bop"}, false},
+		{"no genre is not an error", buildFLAC(false, "TITLE=x"), nil, false},
+		{"empty values dropped", buildFLAC(false, "GENRE= ", "GENRE=Rock"), []string{"Rock"}, false},
+		{"a key that only starts with GENRE", buildFLAC(false, "GENRES=Rock", "GENRE=Jazz"), []string{"Jazz"}, false},
+		{"not a FLAC", []byte("RIFF....WAVEfmt "), nil, true},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := readFLACGenreValues(bytes.NewReader(tc.data))
+			if (err != nil) != tc.err {
+				t.Fatalf("err = %v, want error: %v", err, tc.err)
+			}
+			if !equalStrings(got, tc.want) {
+				t.Errorf("got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestReadFLACGenreValues_TruncatedCommentIsAnError(t *testing.T) {
+	data := buildFLAC(false, "GENRE=Jazz", "GENRE=Bop")
+	if _, err := readFLACGenreValues(bytes.NewReader(data[:len(data)-2])); err == nil {
+		t.Error("err = nil for a cut-off comment block")
+	}
+}
+
+func TestExtractGenres_OggVorbisRepeatedFields(t *testing.T) {
+	comment := append([]byte("\x03vorbis"), vorbisComment(genreFields("Shoegaze", "Dream Pop")...)...)
+	comment = append(comment, 1) // framing bit
+	rs := bytes.NewReader(buildOgg(7, vorbisIdent(), comment))
+	meta, err := tag.ReadFrom(rs)
+	if err != nil {
+		t.Fatalf("tag.ReadFrom: %v", err)
+	}
+	genres, fellBack := extractGenres(meta, rs)
+	if fellBack || !equalStrings(genres, []string{"Shoegaze", "Dream Pop"}) {
+		t.Errorf("genres = %q (fellBack %v), want [Shoegaze Dream Pop]", genres, fellBack)
+	}
+}
+
+func TestReadOggGenreValues_Opus(t *testing.T) {
+	head := append([]byte("OpusHead"), make([]byte, 11)...)
+	tags := append([]byte("OpusTags"), vorbisComment(genreFields("Ambient", "Drone")...)...)
+	got, err := readOggGenreValues(bytes.NewReader(buildOgg(3, head, tags)))
+	if err != nil || !equalStrings(got, []string{"Ambient", "Drone"}) {
+		t.Errorf("got %q, %v; want [Ambient Drone]", got, err)
+	}
+}
+
+// Cover art makes the comment packet span pages. A reader that stopped at the
+// first page boundary would read a truncated block.
+func TestReadOggGenreValues_PacketSpansPages(t *testing.T) {
+	fields := append([]string{"METADATA_BLOCK_PICTURE=" + strings.Repeat("A", 70000)}, genreFields("Jazz", "Bop")...)
+	comment := append([]byte("\x03vorbis"), vorbisComment(fields...)...)
+	got, err := readOggGenreValues(bytes.NewReader(buildOgg(9, vorbisIdent(), comment)))
+	if err != nil || !equalStrings(got, []string{"Jazz", "Bop"}) {
+		t.Errorf("got %q, %v; want [Jazz Bop]", got, err)
+	}
+}
+
+func TestReadMP4GenreValues(t *testing.T) {
+	tests := []struct {
+		name string
+		data []byte
+		want []string
+	}{
+		{"several data atoms in one ©gen", buildMP4(true, mp4Box("\xa9gen", mp4Text("Hip Hop"), mp4Text("Lo-Fi"))), []string{"Hip Hop", "Lo-Fi"}},
+		{"repeated ©gen atoms", buildMP4(true, mp4Box("\xa9gen", mp4Text("Hip Hop")), mp4Box("\xa9gen", mp4Text("Lo-Fi"))), []string{"Hip Hop", "Lo-Fi"}},
+		{"QuickTime meta without version bytes", buildMP4(false, mp4Box("\xa9gen", mp4Text("Jazz"), mp4Text("Bop"))), []string{"Jazz", "Bop"}},
+		{"no ©gen is not an error", buildMP4(true), nil},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := readMP4GenreValues(bytes.NewReader(tc.data))
+			if err != nil {
+				t.Fatalf("err = %v", err)
+			}
+			if !equalStrings(got, tc.want) {
+				t.Errorf("got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestExtractGenres_MP4MultiValue(t *testing.T) {
+	rs := bytes.NewReader(buildMP4(true, mp4Box("\xa9gen", mp4Text("Hip Hop"), mp4Text("Lo-Fi"))))
+	meta, err := tag.ReadFrom(rs)
+	if err != nil {
+		t.Fatalf("tag.ReadFrom: %v", err)
+	}
+	genres, fellBack := extractGenres(meta, rs)
+	if fellBack || !equalStrings(genres, []string{"Hip Hop", "Lo-Fi"}) {
+		t.Errorf("genres = %q (fellBack %v), want [Hip Hop Lo-Fi]", genres, fellBack)
+	}
+}

internal/playlists/seed_missing_db_test.go

@@ -0,0 +1,85 @@
+package playlists_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+func likeTrack(t *testing.T, pool *pgxpool.Pool, userID, trackID pgtype.UUID) {
+	t.Helper()
+	if _, err := pool.Exec(context.Background(),
+		`INSERT INTO general_likes (user_id, track_id) VALUES ($1, $2)`,
+		userID, trackID); err != nil {
+		t.Fatalf("like track: %v", err)
+	}
+}
+
+func markMissing(t *testing.T, pool *pgxpool.Pool, trackID pgtype.UUID) {
+	t.Helper()
+	if _, err := pool.Exec(context.Background(),
+		`UPDATE tracks SET missing_since = now() WHERE id = $1`, trackID); err != nil {
+		t.Fatalf("mark missing: %v", err)
+	}
+}
+
+// TestPickTopPlayedTracksForUser_LikedTierSkipsMissing: with no plays, For
+// You seeds from likes. A liked track whose file is gone is not a seed (#2701).
+func TestPickTopPlayedTracksForUser_LikedTierSkipsMissing(t *testing.T) {
+	pool := newPool(t)
+	u := seedUser(t, pool, "seedmissing")
+	present := seedTrack(t, pool, "Present", "Seed Artist A")
+	gone := seedTrack(t, pool, "Gone", "Seed Artist B")
+	likeTrack(t, pool, u.ID, present.ID)
+	likeTrack(t, pool, u.ID, gone.ID)
+	markMissing(t, pool, gone.ID)
+
+	seeds, err := dbq.New(pool).PickTopPlayedTracksForUser(context.Background(), u.ID)
+	if err != nil {
+		t.Fatalf("pick seeds: %v", err)
+	}
+	if len(seeds) != 1 || seeds[0] != present.ID {
+		t.Fatalf("seeds = %v, want only the present liked track %v", seeds, present.ID)
+	}
+}
+
+// TestPickTopPlayedTrackForArtistByUser_FallbackSkipsMissing: with no plays,
+// Songs-like seeds from the artist's newest album. When that album's track is
+// missing, the seed comes from the next album rather than the missing file.
+func TestPickTopPlayedTrackForArtistByUser_FallbackSkipsMissing(t *testing.T) {
+	pool := newPool(t)
+	ctx := context.Background()
+	u := seedUser(t, pool, "songslikemissing")
+	older := seedTrack(t, pool, "Older", "Songs Like Artist")
+	newerAlbum := seedAlbumForArtist(t, pool, "Newer Album", older.ArtistID)
+	newer := seedTrackForArtist(t, pool, "Newer", newerAlbum, older.ArtistID)
+	if _, err := pool.Exec(ctx, `UPDATE albums SET release_date = '2010-01-01' WHERE id = $1`, older.AlbumID); err != nil {
+		t.Fatalf("date older album: %v", err)
+	}
+	if _, err := pool.Exec(ctx, `UPDATE albums SET release_date = '2020-01-01' WHERE id = $1`, newerAlbum); err != nil {
+		t.Fatalf("date newer album: %v", err)
+	}
+
+	q := dbq.New(pool)
+	args := dbq.PickTopPlayedTrackForArtistByUserParams{UserID: u.ID, ArtistID: older.ArtistID}
+	got, err := q.PickTopPlayedTrackForArtistByUser(ctx, args)
+	if err != nil {
+		t.Fatalf("pick seed: %v", err)
+	}
+	if got != newer.ID {
+		t.Fatalf("before marking: seed = %v, want the newest album's track %v", got, newer.ID)
+	}
+
+	markMissing(t, pool, newer.ID)
+	got, err = q.PickTopPlayedTrackForArtistByUser(ctx, args)
+	if err != nil {
+		t.Fatalf("pick seed: %v", err)
+	}
+	if got != older.ID {
+		t.Fatalf("after marking: seed = %v, want the present older track %v", got, older.ID)
+	}
+}

web/scripts/check-tint-contrast.js

@@ -0,0 +1,110 @@
+// Finds a hue painted as TEXT on a tint of itself (#3150). The tint sits close
+// to the surface under it, so the raw hue on it measures 1.6–2.4:1 against
+// AA's 4.5. The fix is the hue's -fg partner (tokens.json colors.fg), mixed
+// toward parchment: accent-fg on an accent tint measures 5.03.
+//
+// Two spellings are checked:
+//   Tailwind  one class string holding both `bg-X-tint` / `bg-X/NN` and `text-X`
+//   CSS       one rule block holding both a `color-mix(… var(--fs-X) N%,
+//             transparent)` background and `color: var(--fs-X)`
+//
+// A pair split across two strings (a tint in one class: directive, the text
+// in another) is not seen. The lookbehind on `color:` keeps border-color and
+// outline-color out: a border is a graphic with a 3:1 floor, not text.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export const HUES = {
+  accent: 'accent-fg',
+  warning: 'warning-fg',
+  error: 'error-fg',
+  info: 'info-fg',
+  moss: 'success-fg'
+};
+
+// The quoted string around index i. Read outward from the tint class rather
+// than pairing every quote in the file, which an apostrophe in prose
+// ("Couldn't") throws out of step.
+function enclosingString(source, i) {
+  const start = Math.max(...['"', "'", '`'].map((q) => source.lastIndexOf(q, i)));
+  if (start < 0) return '';
+  const end = source.indexOf(source[start], i);
+  return end < 0 ? '' : source.slice(start, end + 1);
+}
+
+/** Tailwind class strings that put text-X on a bg-X tint. */
+export function findTailwind(source) {
+  const found = [];
+  for (const hue of Object.keys(HUES)) {
+    const tint = new RegExp(`(?<=^|[\\s'"\`])bg-${hue}(?:-tint|/\\d+)(?=$|[\\s'"\`])`, 'g');
+    const text = new RegExp(`(?:^|[\\s'"\`])text-${hue}(?=$|[\\s'"\`])`);
+    for (const m of source.matchAll(tint)) {
+      if (text.test(enclosingString(source, m.index))) {
+        found.push({ hue, index: m.index, fix: `text-${hue === 'moss' ? 'success' : hue}-fg` });
+      }
+    }
+  }
+  return found;
+}
+
+/** CSS rule blocks that put color: var(--fs-X) on a color-mix tint of X. */
+export function findCss(source) {
+  const found = [];
+  for (const m of source.matchAll(/\{([^{}]*)\}/g)) {
+    for (const hue of Object.keys(HUES)) {
+      const tint = new RegExp(
+        `background(?:-color)?\\s*:\\s*color-mix\\(\\s*in srgb\\s*,\\s*var\\(--fs-${hue}\\)\\s*\\d+%\\s*,\\s*transparent\\s*\\)`
+      );
+      const text = new RegExp(`(?<![-\\w])color\\s*:\\s*var\\(--fs-${hue}\\)`);
+      if (tint.test(m[1]) && text.test(m[1])) {
+        found.push({ hue, index: m.index, fix: `var(--fs-${HUES[hue]})` });
+      }
+    }
+  }
+  return found;
+}
+
+// Hues that fail AA as text even on a plain surface, so the raw hue is never
+// text at all: error measures 2.64:1 on slate and 3.23 on iron in dark mode,
+// against 4.5; error-fg measures 5.30 at worst. A border or outline in the
+// hue is a graphic with a 3:1 floor and stays allowed.
+export const TEXT_NEVER_RAW = ['error'];
+
+/** Raw text-X classes and color: var(--fs-X) for the hues above. */
+export function findRawText(source) {
+  const found = [];
+  for (const hue of TEXT_NEVER_RAW) {
+    const patterns = [
+      [new RegExp(`(?<=^|[\\s'"\`:])text-${hue}(?=$|[\\s'"\`=])`, 'g'), `text-${hue}-fg`],
+      [new RegExp(`(?<![-\\w])color\\s*:\\s*var\\(--fs-${hue}\\)`, 'g'), `var(--fs-${HUES[hue]})`]
+    ];
+    for (const [re, fix] of patterns) {
+      for (const m of source.matchAll(re)) found.push({ hue, index: m.index, fix });
+    }
+  }
+  return found;
+}
+
+function lineOf(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+function* walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) yield* walk(path);
+    else if (/\.(svelte|ts|js|css)$/.test(name) && !/\.test\.(ts|js)$/.test(name)) yield path;
+  }
+}
+
+/** Every violation under root, as "path:line hue → fix". */
+export function scan(root, base = root) {
+  const out = [];
+  for (const path of walk(root)) {
+    const source = readFileSync(path, 'utf8');
+    for (const f of [...findTailwind(source), ...findCss(source), ...findRawText(source)]) {
+      out.push(`${relative(base, path)}:${lineOf(source, f.index)} ${f.hue} → ${f.fix}`);
+    }
+  }
+  return out;
+}

web/scripts/check-tint-contrast.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { findCss, findRawText, findTailwind, scan } from './check-tint-contrast.js';
+
+const web = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('hue-on-own-tint check (#3150)', () => {
+  test('no source paints a hue as text on a tint of itself', () => {
+    expect(scan(resolve(web, 'src'), web)).toEqual([]);
+  });
+
+  describe('Tailwind', () => {
+    test('finds text-X on bg-X-tint and bg-X/NN in one class string', () => {
+      expect(findTailwind(`class="rounded bg-accent-tint px-2 text-accent"`)).toHaveLength(1);
+      expect(findTailwind(`'bg-error/15 text-error'`)).toHaveLength(1);
+      expect(findTailwind("`bg-moss/10 text-moss`")[0].fix).toBe('text-success-fg');
+    });
+
+    test('a class string spanning lines is one string', () => {
+      expect(findTailwind(`class="bg-accent-tint\n  text-accent"`)).toHaveLength(1);
+    });
+
+    test('an apostrophe earlier in the file does not hide a pair', () => {
+      expect(
+        findTailwind(`<p>Couldn't add</p>\n<span class={on ? 'bg-accent-tint text-accent' : ''}>`)
+      ).toHaveLength(1);
+    });
+
+    test('passes the -fg partner, another hue, and a tint with no hue text', () => {
+      expect(findTailwind(`"bg-accent-tint text-accent-fg"`)).toEqual([]);
+      expect(findTailwind(`"bg-accent-tint text-error"`)).toEqual([]);
+      expect(findTailwind(`"bg-accent-tint text-text-primary"`)).toEqual([]);
+      expect(findTailwind(`"text-accent"`)).toEqual([]);
+    });
+  });
+
+  describe('raw error text, on any surface', () => {
+    test('finds text-error, class:text-error and color: var(--fs-error)', () => {
+      expect(findRawText(`<p class="text-sm text-error">x</p>`)).toHaveLength(1);
+      expect(findRawText(`<div class:text-error={bad}>`)).toHaveLength(1);
+      expect(findRawText(`.msg { color: var(--fs-error); }`)[0].fix).toBe('var(--fs-error-fg)');
+    });
+
+    test('passes error-fg, and error as a border or outline', () => {
+      expect(findRawText(`<p class="text-error-fg">x</p>`)).toEqual([]);
+      expect(findRawText(`<div class="border-error" class:border-error={bad}>`)).toEqual([]);
+      expect(findRawText(`.a { border-color: var(--fs-error); outline-color: var(--fs-error); }`)).toEqual([]);
+    });
+  });
+
+  describe('CSS', () => {
+    const tinted = (color) =>
+      `.pill { background: color-mix(in srgb, var(--fs-warning) 15%, transparent); ${color} }`;
+
+    test('finds color: var(--fs-X) on a color-mix tint of X', () => {
+      expect(findCss(tinted('color: var(--fs-warning);'))).toHaveLength(1);
+      expect(findCss(tinted('color: var(--fs-warning);'))[0].fix).toBe('var(--fs-warning-fg)');
+    });
+
+    test('passes the -fg partner and border or outline colours', () => {
+      expect(findCss(tinted('color: var(--fs-warning-fg);'))).toEqual([]);
+      expect(findCss(tinted('border-color: var(--fs-warning);'))).toEqual([]);
+      expect(findCss(tinted('outline-color: var(--fs-warning);'))).toEqual([]);
+    });
+
+    test('a tint and a colour in different rules are not a pair', () => {
+      expect(
+        findCss(
+          `.a { background: color-mix(in srgb, var(--fs-accent) 15%, transparent); }\n.b { color: var(--fs-accent); }`
+        )
+      ).toEqual([]);
+    });
+  });
+});

web/scripts/tokens-to-css.js

@@ -19,6 +19,14 @@ export function emit(tokens) {
   for (const [name, value] of Object.entries(tokens.colors.flat)) {
     lines.push(`  --fs-${name}: ${value};`);
   }
+  // The house -fg tokens (FabledSword, 2026-08-27; #3150): a hue as TEXT on a
+  // tint of itself, mixed toward parchment. Parchment inverts in light mode,
+  // so one declaration lightens the text on dark surfaces and darkens it on
+  // light ones. Declared on :root, the element data-theme is set on, so the
+  // var()s resolve against that mode's parchment.
+  for (const [name, value] of Object.entries(tokens.colors.fg ?? {})) {
+    lines.push(`  --fs-${name}: ${value};`);
+  }
   for (const [name, value] of Object.entries(tokens.radii)) {
     lines.push(`  --fs-radius-${name}: ${value};`);
   }

web/scripts/tokens-to-css.test.js

@@ -5,7 +5,8 @@ const sample = {
   colors: {
     dark:  { obsidian: '#000', parchment: '#FFF' },
     light: { obsidian: '#FFF', parchment: '#000' },
-    flat:  { accent: '#4A6B5C', 'on-action': '#E8E4D8' }
+    flat:  { accent: '#4A6B5C', 'on-action': '#E8E4D8' },
+    fg:    { 'accent-fg': 'color-mix(in srgb, var(--fs-accent) 45%, var(--fs-parchment))' }
   },
   radii: { sm: '4px' },
   fontStacks: {
@@ -40,4 +41,13 @@ describe('tokens-to-css emit()', () => {
     expect(css).toContain('--fs-radius-sm: 4px;');
     expect(css).toContain("--fs-font-display: 'Fraunces', serif;");
   });
+
+  test('emits the -fg tokens in :root, not the light block', () => {
+    const css = emit(sample);
+    const root = css.match(/:root \{([\s\S]*?)\}/);
+    expect(root).not.toBeNull();
+    expect(root[1]).toContain('--fs-accent-fg: color-mix(in srgb, var(--fs-accent) 45%, var(--fs-parchment));');
+    const light = css.match(/\[data-theme="light"\] \{([\s\S]*?)\}/);
+    expect(light[1]).not.toContain('-fg');
+  });
 });

web/src/lib/components/DiscoverResultCard.svelte

@@ -169,7 +169,7 @@
     font-size: 11px;
     line-height: 14px;
     background: color-mix(in srgb, var(--fs-accent) 15%, transparent);
-    color: var(--fs-accent);
+    color: var(--fs-accent-fg);
   }
   /* Muted rather than accented: a parked card should recede, not compete
      with the live suggestions around it. Same geometry as .kept-pill so the

web/src/lib/components/FlagPopover.svelte

@@ -79,7 +79,7 @@
     ></textarea>
   </label>
   {#if error}
-    <p class="mt-2 text-xs text-error">Couldn't save flag — {error}</p>
+    <p class="mt-2 text-xs text-error-fg">Couldn't save flag — {error}</p>
   {/if}
   <div class="mt-3 flex justify-end gap-2">
     <button

web/src/lib/components/PlayerBar.svelte

@@ -184,7 +184,7 @@
               aria-pressed={player.shuffle}
               onclick={toggleShuffle}
               class="flex h-8 w-8 items-center justify-center rounded-full transition-colors {player.shuffle
-                ? 'bg-accent-tint text-accent'
+                ? 'bg-accent-tint text-accent-fg'
                 : 'text-text-secondary hover:bg-surface-hover hover:text-text-primary'}"
             >
               <Shuffle size={16} strokeWidth={1.5} />
@@ -194,7 +194,7 @@
               aria-label={repeatLabel}
               onclick={cycleRepeat}
               class="flex h-8 w-8 items-center justify-center rounded-full transition-colors {player.repeat !== 'off'
-                ? 'bg-accent-tint text-accent'
+                ? 'bg-accent-tint text-accent-fg'
                 : 'text-text-secondary hover:bg-surface-hover hover:text-text-primary'}"
             >
               {#if player.repeat === 'one'}
@@ -209,7 +209,7 @@
               aria-label={player.queueDrawerOpen ? 'Close queue' : 'Open queue'}
               aria-pressed={player.queueDrawerOpen}
               class="flex h-8 w-8 items-center justify-center rounded-full transition-colors {player.queueDrawerOpen
-                ? 'bg-accent-tint text-accent'
+                ? 'bg-accent-tint text-accent-fg'
                 : 'text-text-secondary hover:bg-surface-hover hover:text-text-primary'}"
             >
               <ListMusic size={16} strokeWidth={1.5} />
@@ -392,7 +392,7 @@
         aria-pressed={player.shuffle}
         onclick={toggleShuffle}
         class="flex h-9 w-9 items-center justify-center rounded-full transition-colors {player.shuffle
-          ? 'bg-accent-tint text-accent'
+          ? 'bg-accent-tint text-accent-fg'
           : 'text-text-secondary hover:bg-surface-hover hover:text-text-primary'}"
       >
         <Shuffle size={18} strokeWidth={1.5} />
@@ -402,7 +402,7 @@
         aria-label={repeatLabel}
         onclick={cycleRepeat}
         class="flex h-9 w-9 items-center justify-center rounded-full transition-colors {player.repeat !== 'off'
-          ? 'bg-accent-tint text-accent'
+          ? 'bg-accent-tint text-accent-fg'
           : 'text-text-secondary hover:bg-surface-hover hover:text-text-primary'}"
       >
         {#if player.repeat === 'one'}
@@ -417,7 +417,7 @@
         aria-label={player.queueDrawerOpen ? 'Close queue' : 'Open queue'}
         aria-pressed={player.queueDrawerOpen}
         class="flex h-9 w-9 items-center justify-center rounded-full transition-colors {player.queueDrawerOpen
-          ? 'bg-accent-tint text-accent'
+          ? 'bg-accent-tint text-accent-fg'
           : 'text-text-secondary hover:bg-surface-hover hover:text-text-primary'}"
       >
         <ListMusic size={18} strokeWidth={1.5} />

web/src/lib/components/StatusPill.svelte

@@ -37,18 +37,18 @@
   }
   .pill[data-tone='warning'] {
     background: color-mix(in srgb, var(--fs-warning) 15%, transparent);
-    color: var(--fs-warning);
+    color: var(--fs-warning-fg);
   }
   .pill[data-tone='info'] {
     background: color-mix(in srgb, var(--fs-info) 15%, transparent);
-    color: var(--fs-info);
+    color: var(--fs-info-fg);
   }
   .pill[data-tone='success'] {
     background: color-mix(in srgb, var(--fs-moss) 15%, transparent);
-    color: var(--fs-moss);
+    color: var(--fs-success-fg);
   }
   .pill[data-tone='error'] {
     background: color-mix(in srgb, var(--fs-error) 15%, transparent);
-    color: var(--fs-error);
+    color: var(--fs-error-fg);
   }
 </style>

web/src/lib/components/ToastHost.svelte

@@ -15,7 +15,7 @@
       class:border-border={toast.value.variant === 'info'}
       class:text-text-primary={toast.value.variant === 'info'}
       class:border-error={toast.value.variant === 'error'}
-      class:text-error={toast.value.variant === 'error'}
+      class:text-error-fg={toast.value.variant === 'error'}
     >
       {toast.value.message}
     </div>

web/src/lib/styles/tokens.generated.css

@@ -15,6 +15,11 @@
   --fs-info: #3D5A6E;
   --fs-accent: #4A6B5C;
   --fs-on-action: #E8E4D8;
+  --fs-accent-fg: color-mix(in srgb, var(--fs-accent) 45%, var(--fs-parchment));
+  --fs-success-fg: color-mix(in srgb, var(--fs-moss) 45%, var(--fs-parchment));
+  --fs-warning-fg: color-mix(in srgb, var(--fs-warning) 50%, var(--fs-parchment));
+  --fs-error-fg: color-mix(in srgb, var(--fs-error) 50%, var(--fs-parchment));
+  --fs-info-fg: color-mix(in srgb, var(--fs-info) 50%, var(--fs-parchment));
   --fs-radius-sm: 4px;
   --fs-radius-md: 8px;
   --fs-radius-lg: 12px;

web/src/lib/styles/tokens.json

@@ -27,6 +27,13 @@
       "info": "#3D5A6E",
       "accent": "#4A6B5C",
       "on-action": "#E8E4D8"
+    },
+    "fg": {
+      "accent-fg": "color-mix(in srgb, var(--fs-accent) 45%, var(--fs-parchment))",
+      "success-fg": "color-mix(in srgb, var(--fs-moss) 45%, var(--fs-parchment))",
+      "warning-fg": "color-mix(in srgb, var(--fs-warning) 50%, var(--fs-parchment))",
+      "error-fg": "color-mix(in srgb, var(--fs-error) 50%, var(--fs-parchment))",
+      "info-fg": "color-mix(in srgb, var(--fs-info) 50%, var(--fs-parchment))"
     }
   },
   "radii": { "sm": "4px", "md": "8px", "lg": "12px", "xl": "16px" },

web/src/routes/admin/diagnostics/+page.svelte

@@ -325,7 +325,7 @@
 
   <!-- Timeline -->
   {#if diagQuery.isError}
-    <p class="text-error">Couldn't load: {errMessage(diagQuery.error)}</p>
+    <p class="text-error-fg">Couldn't load: {errMessage(diagQuery.error)}</p>
   {:else if diagQuery.isPending}
     <p class="text-text-secondary">Loading…</p>
   {:else if rows.length === 0}

web/src/routes/admin/duplicates/+page.svelte

@@ -138,7 +138,7 @@
         <h2 class="font-display text-2xl font-medium text-text-primary">Duplicates</h2>
         {#if total > 0}
           <span
-            class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent"
+            class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent-fg"
             data-testid="duplicates-count-pill"
           >
             {total}
@@ -188,7 +188,7 @@
   {#if query.isPending}
     <p class="text-text-secondary">Loading duplicates…</p>
   {:else if query.isError}
-    <p class="text-error">Couldn't load the duplicates report.</p>
+    <p class="text-error-fg">Couldn't load the duplicates report.</p>
   {:else if groups.length === 0}
     <!-- Three states all show zero groups and mean different things. Telling
          them apart is what stops an empty page reading as a broken feature. -->
@@ -302,7 +302,7 @@
                       <!-- The proposed copy to keep, with the rule that chose it.
                            A default the merge will let the operator override. -->
                       <span
-                        class="shrink-0 rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent"
+                        class="shrink-0 rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent-fg"
                         data-testid="survivor-badge"
                         title="Proposed to keep: {group.survivor_reason}"
                       >

web/src/routes/admin/integrations/+page.svelte

@@ -463,7 +463,7 @@
         {/each}
       </select>
       {#if testListErrors.quality_profiles}
-        <p class="mt-1 text-xs text-error">
+        <p class="mt-1 text-xs text-error-fg">
           Couldn't fetch quality profiles — {testListErrors.quality_profiles}
         </p>
       {/if}
@@ -481,7 +481,7 @@
         {/each}
       </select>
       {#if testListErrors.metadata_profiles}
-        <p class="mt-1 text-xs text-error">
+        <p class="mt-1 text-xs text-error-fg">
           Couldn't fetch metadata profiles — {testListErrors.metadata_profiles}
         </p>
       {/if}
@@ -501,7 +501,7 @@
         {/each}
       </select>
       {#if testListErrors.root_folders}
-        <p class="mt-1 text-xs text-error">
+        <p class="mt-1 text-xs text-error-fg">
           Couldn't fetch root folders — {testListErrors.root_folders}
         </p>
       {/if}
@@ -513,11 +513,11 @@
           Connected — Lidarr {testResult.version}
         </p>
       {:else}
-        <p class="text-sm text-error">Connection failed — {testResult.error}</p>
+        <p class="text-sm text-error-fg">Connection failed — {testResult.error}</p>
       {/if}
     {/if}
     {#if saveError}
-      <p class="text-sm text-error">Save failed — {saveError}</p>
+      <p class="text-sm text-error-fg">Save failed — {saveError}</p>
     {/if}
 
     <div class="flex items-center gap-2 pt-2">
@@ -625,7 +625,7 @@
                     OK{coverTestResults[provider.id].duration_ms ? ` (${coverTestResults[provider.id].duration_ms}ms)` : ''}
                   </p>
                 {:else}
-                  <p class="text-sm text-error">
+                  <p class="text-sm text-error-fg">
                     Failed — {coverTestResults[provider.id].error}
                   </p>
                 {/if}
@@ -722,7 +722,7 @@
                     OK{tagTestResults[provider.id].duration_ms ? ` (${tagTestResults[provider.id].duration_ms}ms)` : ''}
                   </p>
                 {:else}
-                  <p class="text-sm text-error">
+                  <p class="text-sm text-error-fg">
                     Failed — {tagTestResults[provider.id].error}
                   </p>
                 {/if}
@@ -837,7 +837,7 @@
     class="mt-3 w-full rounded-md border border-border bg-background px-3 py-2 font-mono text-sm text-text-primary placeholder:text-text-muted focus:outline-none focus:ring-2 focus:ring-accent"
   />
   {#if disconnectError}
-    <p class="mt-2 text-sm text-error">Disconnect failed — {disconnectError}</p>
+    <p class="mt-2 text-sm text-error-fg">Disconnect failed — {disconnectError}</p>
   {/if}
   <div class="mt-5 flex justify-end gap-2">
     <button

web/src/routes/admin/missing-files/+page.svelte

@@ -53,7 +53,7 @@
       <h2 class="font-display text-2xl font-medium text-text-primary">Missing files</h2>
       {#if total > 0}
         <span
-          class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent"
+          class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent-fg"
           data-testid="missing-count-pill"
         >
           {total}
@@ -74,7 +74,7 @@
   {#if query.isPending}
     <p class="text-text-secondary">Checking what's missing…</p>
   {:else if query.isError}
-    <p class="text-error">Couldn't load the missing-files list.</p>
+    <p class="text-error-fg">Couldn't load the missing-files list.</p>
   {:else if groups.length === 0}
     <!-- Empty state explains the feature, not just the emptiness: an operator
          who has never seen this page shouldn't have to guess what would put a

web/src/routes/admin/playback-errors/+page.svelte

@@ -167,7 +167,7 @@
       </p>
     </div>
     {#if !query.isPending && !query.isError && !resolved}
-      <span class="rounded-full bg-accent/15 px-3 py-1 text-sm text-accent">
+      <span class="rounded-full bg-accent/15 px-3 py-1 text-sm text-accent-fg">
         {rows.length} unresolved
       </span>
     {/if}
@@ -197,7 +197,7 @@
   </div>
 
   {#if query.isError}
-    <p class="text-error">Couldn't load: {errMessage(query.error)}</p>
+    <p class="text-error-fg">Couldn't load: {errMessage(query.error)}</p>
   {:else if query.isPending}
     <p class="text-text-secondary">Loading…</p>
   {:else if rows.length === 0}
@@ -220,7 +220,7 @@
                 {kindLabel(r.kind)}
               </span>
               {#if resolved && r.resolution}
-                <span class="rounded bg-accent/15 px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-accent">
+                <span class="rounded bg-accent/15 px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-accent-fg">
                   {resolutionLabel(r.resolution)}
                 </span>
               {/if}

web/src/routes/admin/quarantine/+page.svelte

@@ -150,7 +150,7 @@
       <h2 class="font-display text-2xl font-medium text-text-primary">Quarantine</h2>
       {#if totalReports > 0}
         <span
-          class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent"
+          class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent-fg"
           data-testid="report-count-pill"
         >
           {totalReports}
@@ -163,7 +163,7 @@
   {#if query.isPending}
     <p class="text-text-secondary">Reading the queue…</p>
   {:else if query.isError}
-    <p class="text-error">Couldn't load the quarantine queue.</p>
+    <p class="text-error-fg">Couldn't load the quarantine queue.</p>
   {:else if rows.length === 0}
     <p class="text-text-secondary">Nothing to triage right now.</p>
   {:else}
@@ -356,7 +356,7 @@
       />
     </label>
     {#if deleteLidarrError}
-      <p class="mt-3 text-sm text-error" data-testid="delete-lidarr-error">
+      <p class="mt-3 text-sm text-error-fg" data-testid="delete-lidarr-error">
         {deleteLidarrError}
       </p>
     {/if}
@@ -392,6 +392,6 @@
     font-size: 11px;
     line-height: 14px;
     background: color-mix(in srgb, var(--fs-accent) 15%, transparent);
-    color: var(--fs-accent);
+    color: var(--fs-accent-fg);
   }
 </style>

web/src/routes/admin/requests/+page.svelte

@@ -183,7 +183,7 @@
             {tab.label}
             {#if isActive}
               <span
-                class="ml-1.5 inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent"
+                class="ml-1.5 inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent-fg"
                 data-testid="active-tab-count"
               >
                 {rows.length}
@@ -198,7 +198,7 @@
   {#if query.isPending}
     <p class="text-text-secondary">Reading the queue…</p>
   {:else if query.isError}
-    <p class="text-error">Couldn't load requests.</p>
+    <p class="text-error-fg">Couldn't load requests.</p>
   {:else if rows.length === 0}
     <p class="text-text-secondary">Nothing here.</p>
   {:else}
@@ -377,7 +377,7 @@
     font-size: 11px;
     line-height: 14px;
     background: color-mix(in srgb, var(--fs-accent) 15%, transparent);
-    color: var(--fs-accent);
+    color: var(--fs-accent-fg);
     text-transform: capitalize;
   }
 </style>

web/src/routes/admin/users/+page.svelte

@@ -229,7 +229,7 @@
     {#if usersQuery.isPending}
       <p class="text-text-secondary">Reading users…</p>
     {:else if usersQuery.isError}
-      <p class="text-error">Couldn't load users.</p>
+      <p class="text-error-fg">Couldn't load users.</p>
     {:else if users.length === 0}
       <p class="text-text-secondary">No users yet.</p>
     {:else}
@@ -274,7 +274,7 @@
                 <span class="text-base font-medium text-text-primary">{u.username}</span>
                 {#if u.is_admin}
                   <span
-                    class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent"
+                    class="inline-flex items-center rounded-full bg-accent-tint px-2 py-0.5 text-xs text-accent-fg"
                     data-testid="admin-badge"
                   >admin</span>
                 {/if}
@@ -318,7 +318,7 @@
     {#if invitesQuery.isPending}
       <p class="text-text-secondary">Reading invites…</p>
     {:else if invitesQuery.isError}
-      <p class="text-error">Couldn't load invites.</p>
+      <p class="text-error-fg">Couldn't load invites.</p>
     {:else if invites.length === 0}
       <p class="text-sm text-text-secondary">No active invites.</p>
     {:else}

web/src/routes/library/hidden/+page.svelte

@@ -100,6 +100,6 @@
     font-size: 11px;
     line-height: 14px;
     background: color-mix(in srgb, var(--fs-accent) 15%, transparent);
-    color: var(--fs-accent);
+    color: var(--fs-accent-fg);
   }
 </style>

web/src/routes/requests/+page.svelte

@@ -160,7 +160,7 @@
     font-size: 11px;
     line-height: 14px;
     background: color-mix(in srgb, var(--fs-accent) 15%, transparent);
-    color: var(--fs-accent);
+    color: var(--fs-accent-fg);
     text-transform: capitalize;
   }
 </style>

web/src/test-utils/appModuleMocks.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test, vi } from 'vitest';
+import { goto } from '$app/navigation';
+import { page } from '$app/state';
+
+// Guards the suite-wide $app mocks in vitest.setup.ts (#3943). If they are
+// removed, tests that never mock $app themselves go back to loading
+// SvelteKit's client runtime, which fails at module load on some CI runs.
+describe('suite-wide SvelteKit app-module mocks', () => {
+  test('$app/navigation is the mock, not the client runtime', () => {
+    expect(vi.isMockFunction(goto)).toBe(true);
+  });
+
+  test('$app/state gives a page at the root URL', () => {
+    expect(page.url.pathname).toBe('/');
+  });
+});

web/tailwind.config.js

@@ -25,11 +25,14 @@ export default {
         },
         accent: {
           DEFAULT: 'var(--fs-accent)',
-          tint: 'color-mix(in srgb, var(--fs-accent) 12%, transparent)'
+          tint: 'color-mix(in srgb, var(--fs-accent) 12%, transparent)',
+          // Accent TEXT on an accent tint (#3150). The raw accent on its own
+          // tint measures 1.97:1 at worst; this measures 5.03.
+          fg: 'var(--fs-accent-fg)'
         },
-        warning: 'var(--fs-warning)',
-        error: 'var(--fs-error)',
-        info: 'var(--fs-info)'
+        warning: { DEFAULT: 'var(--fs-warning)', fg: 'var(--fs-warning-fg)' },
+        error: { DEFAULT: 'var(--fs-error)', fg: 'var(--fs-error-fg)' },
+        info: { DEFAULT: 'var(--fs-info)', fg: 'var(--fs-info-fg)' }
       },
       borderRadius: {
         sm: 'var(--fs-radius-sm)',

web/vitest.setup.ts

@@ -15,6 +15,51 @@ vi.mock('@tanstack/svelte-query', async (orig) => {
   return { ...actual, useQueryClient: () => ({ invalidateQueries: vi.fn() }) };
 });
 
+// Default SvelteKit app-module mocks for the whole suite (#3943). Without
+// them, any page or component that reaches $app/navigation or $app/state —
+// the home page does, through AlbumCard → AlbumMenu — loads SvelteKit's
+// client runtime, whose $app/paths reads __SVELTEKIT_PAYLOAD__ at module
+// load. That global only exists when the kit plugin's define reaches the
+// module, which it does not reliably under vitest: page.test.ts failed to
+// load on one CI run and passed on the re-run of the same commit (#374
+// was the same class). Stubbing the modules keeps every test off the
+// client bootstrap. Tests that assert on goto or need a particular URL
+// still mock per file (pageUrlModule in test-utils/mocks/appState.ts),
+// and per-file mocks win over these.
+vi.mock('$app/navigation', () => ({
+  goto: vi.fn(() => Promise.resolve()),
+  invalidate: vi.fn(() => Promise.resolve()),
+  invalidateAll: vi.fn(() => Promise.resolve()),
+  preloadData: vi.fn(() => Promise.resolve()),
+  preloadCode: vi.fn(() => Promise.resolve()),
+  beforeNavigate: vi.fn(),
+  afterNavigate: vi.fn(),
+  onNavigate: vi.fn(),
+  pushState: vi.fn(),
+  replaceState: vi.fn(),
+  disableScrollHandling: vi.fn()
+}));
+vi.mock('$app/state', () => ({
+  page: {
+    url: new URL('http://localhost/'),
+    params: {},
+    route: { id: null },
+    status: 200,
+    error: null,
+    data: {},
+    form: null,
+    state: {}
+  },
+  navigating: null,
+  updated: { current: false, check: () => Promise.resolve(false) }
+}));
+vi.mock('$app/paths', () => ({
+  base: '',
+  assets: '',
+  resolve: (path: string) => path,
+  asset: (path: string) => path
+}));
+
 // Node 25 ships a partial localStorage global that lacks getItem/setItem/clear
 // unless launched with --localstorage-file. jsdom sees Node's global and skips
 // installing its own. Replace with an in-memory Storage-compatible polyfill so