fix(metadata): read a WAV's tags out of its RIFF id3 chunk

tagwriter has always written a WAV's tags into a RIFF "id3 " chunk
correctly, and dhowden/tag -- which metadata.ExtractTags is built on --
has no RIFF reader at all.  So the app could not see tags it had just
written: editing tags on a WAV, autotagging a WAV folder or importing a
WAV download all appeared to succeed and changed nothing the library
could show, while the file on disk really was tagged and other players
read it.

backend/riff is a new package rather than a move into either half,
because tagwriter already imports metadata: reaching back for parseRIFF
is an import cycle, not merely the wrong direction.  backend/tagtotals
is the precedent.

Its two readers are deliberately different.  Parse holds every chunk in
memory, which is what rewriting a file needs -- and a WAV's audio *is*
a chunk, so doing that on the scan path would read every WAV in the
library in full.  ID3Chunk seeks over what it is not looking for.

The container is asked before tag.ReadFrom rather than after it fails,
because that library's last resort is an ID3v1 trailer and a WAV
carrying both would otherwise be read by the wrong one.  An untagged
WAV -- no chunk, an RF64 container, a tag with every frame cleared --
reads as empty metadata with no TagReadWarning: the scanner's filename
fallback is the right answer there, and a warning would report a fault
on a healthy file.

The gap was pinned by TestWAVTagsAreNotReadableYet, which failed the
moment the reader learned and said in its own comment what to update.
So it goes, TestFixturesMatchManifest no longer skips wav, and
totals_test.go's WAV case reads through metadata.ExtractTags like the
other three formats -- a round trip asserted through the writer's own
parser was a test of the writer, which is why nothing caught this.

Closes #104

.planning/NOTES.md

@@ -4912,52 +4912,3 @@ bridge leaves the wizard up with its "Get Started" button correctly
 disabled — it gates on a directory chosen *in the wizard*, and the
 existing-library check runs once, on mount. A reload clears it. Nothing
 is broken; it cost twenty minutes of believing a tap had been swallowed.
-
-## Art pop-in is measurable in a browser, if you count frames rather than milliseconds (measured 2026-08-24)
-
-#65 is an Android report ("scrolling through albums, the art pops in")
-and the desktop harness can measure it, which was not obvious: the
-first attempt waited 220 ms after each scroll jump and found **zero**
-blank covers on either build. The metric only discriminates at one and
-two animation frames after the jump, which is where a pop-in actually
-lives.
-
-Protocol, on `make dev-headless SEED=bulk` (4 988 albums), ten
-2 400px jumps of `.grid-scroll-container`, counting covers whose rect
-intersects the viewport with `naturalWidth === 0`:
-
-| build | blank at frame 1 | at frame 2 | at 50 ms |
-|---|---|---|---|
-| `main` | 254 / 258 | 214 / 258 | 0 |
-| `main`, second run | 254 / 258 | 190 / 258 | 0 |
-| prefetch | 117 / 258 | 77 / 258 | 0 |
-| prefetch, second run | 118 / 258 | 96 / 258 | 0 |
-
-Two things this protocol gets wrong if repeated carelessly. **A second
-run in the same browser session measures the HTTP cache**, not the
-build — the skill already warns about this for `make perf`, and it
-applies to any image measurement; every row above is a fresh
-`playwright-cli close` + `open`. And **the frontend is embedded**, so
-comparing builds is a `git stash` *and* a rebuild, not a stash.
-
-**The bulk library's covers are 300x300 and ~3.7 kB**, which is why
-both builds are clean by 50 ms here and why the phone's number cannot
-be inferred from this one — same caveat the skill already records
-about full-size artwork.
-
-**`rangeChanged` and `visibilityChanged` are different ranges**, and
-the difference is the whole of this fix's value.
-`@lit-labs/virtualizer` reports `_first`/`_last` (rendered, including
-the ~1000px overhang) on the former and `_firstVisible`/`_lastVisible`
-on the latter. Both grids listen to `visibilityChanged` for scroll
-persistence, which wants the visible range and is correct; a prefetch
-window measured from it lands mostly on cards that already exist.
-Anchored there, the component test could see only one row past the
-last rendered card.
-
-**`_overhang` is not configurable.** It is a `protected` field set to
-1000 in `BaseLayout` and read by every layout; there is no option on
-`grid()`/`flow()` and no property on the element. The issue's Direction
-("ask the virtualizer for a larger overscan") is therefore not
-available without patching a private, which is why the request is
-issued ahead of the element instead.

CLAUDE.md

@@ -2549,11 +2549,38 @@ Five things about it are load-bearing, and four of them fail silently:
   correctly. Confidently wrong is worse than absent here, which is the
   same rule `Known` exists for.
 
-One gap this did not close, and it is older: **`dhowden/tag` has no
-RIFF reader**, so nothing the tag writer puts in a WAV's `id3 ` chunk
-is visible to `metadata.ExtractTags` — not the totals and not the title
-either. `wav_test.go` reads that chunk itself, which is why no test
-ever noticed.
+One gap this did not close and #104 did: **`dhowden/tag` has no RIFF
+reader**, so nothing the tag writer put in a WAV's `id3 ` chunk was
+visible to `metadata.ExtractTags` — not the totals and not the title
+either, on files the app itself had just tagged. `wav_test.go` read
+that chunk itself, which is why no test noticed: a round trip asserted
+through the writer's own parser is a test of the writer.
+
+`backend/riff` is where the container is now read, and it is its own
+package because the alternative is an import cycle — `tagwriter`
+imports `metadata`, so `metadata` cannot reach back for `parseRIFF`.
+`backend/tagtotals` is the precedent.
+
+Three things about it are load-bearing. **The two readers are
+deliberately different**: `Parse` holds every chunk in memory, which is
+what rewriting a file needs, and a WAV's audio *is* a chunk — so the
+scan path uses `ID3Chunk`, which seeks over what it is not looking for.
+**The container decides, before `tag.ReadFrom` rather than after it
+fails**, because that library's last resort is an ID3v1 trailer and a
+WAV carrying both would otherwise be read by the wrong one. And **an
+untagged WAV is a file with no tags, not a file with a problem**: no
+chunk, an RF64 container or a tag holding no frames all read as empty
+metadata with no `TagReadWarning`, since the scanner's filename
+fallback is the right answer and a warning would put a fault on a file
+that has none.
+
+The gap was pinned by a test that said so, which failed the moment the
+reader learned and carried the instructions for what to update in its
+own comment. So it is deleted, `TestFixturesMatchManifest` no longer
+skips `wav`, and `totals_test.go`'s WAV case goes through
+`metadata.ExtractTags` like the other three formats. The fixture
+library's two WAV tracks scan with their tags and their cover now,
+which is a change to what every seeded tier sees.
 
 **The absence is what gets marked, not the presence.** The tracklist
 put a green tick against every owned track and a legend underneath
@@ -3240,46 +3267,6 @@ rather than searching it — the store replaces that array when its
 contents change and shares the unchanged members, which is the same
 signal `track-list`'s memoized caches key on.
 
-**And the right tier arriving late still reads as no art at all**, so
-the two grids ask for it before the card exists (#65).
-`utils/image-prefetch.ts` warms the images a scroll is about to reach,
-from `cover-grid`'s and `artists-view`'s virtualizers. Measured on the
-50 000-track bulk seed over ten 2 400px jumps: of 258 covers arriving
-in view, **254 were still blank one frame later and 214 two frames
-later**; with the prefetch, 117 and 77. Both builds are clean by 50 ms
-on a desktop with 3.7 kB fixture covers, which is where the reference
-device's slower engine and 27 kB covers spend their pop-in.
-
-Four things about it are load-bearing.
-
-**The overscan the obvious fix asks for does not exist.**
-`@lit-labs/virtualizer`'s `_overhang` is a hard-coded 1000px
-`protected` field on `BaseLayout` with no configuration surface, so
-raising it means monkey-patching a private. 1000px is about two
-screens on a 439px viewport, and the *image* cannot be requested until
-the card it lives in is rendered — which is what this asks for
-instead.
-
-**It hangs off `rangeChanged`, not `visibilityChanged`.** Those report
-different ranges: visibility is what is on screen, and the virtualizer
-has already rendered that 1000px past it. Anchored to the visible
-range the window is spent on cards that already exist and have already
-asked for their own art — measured as the difference between the
-prefetch reaching one row past the last card and reaching a full
-window past it.
-
-**It is not the `LRUMap` path, and saying so is the bound.** That
-ceiling holds Explore's base64 data URLs in JS; a library cover is a
-plain URL under `Cache-Control: immutable` (the filenames are content
-hashes), so what retains the bytes is the browser's own cache. What
-this module retains is the *set of URLs already asked for*, capped at
-512 and reported to `window.__yjCacheStats()` — 497 entries and 15 407
-chars after the run above.
-
-**The prefetch asks for what the card will draw.** `artists-view`'s
-tier ladder moved into `artistAvatarURL()` so the two cannot disagree;
-a second copy would be a warm cache for a tier nothing renders.
-
 **The same rule, on the selection path, was the worst stall in the
 app.** Five components turned selected file paths back into tracks with
 `filePaths.map(fp => tracks.find(…))`, so "Select all → Edit tags" at

backend/metadata/tags.go

@@ -74,6 +74,14 @@ func ExtractTags(path string) (*TrackMetadata, error) {
 
 // ExtractTagsFromReader reads metadata from an io.ReadSeeker.
 func ExtractTagsFromReader(r io.ReadSeeker) (*TrackMetadata, error) {
+	// The container decides, so this is asked before tag.ReadFrom and
+	// not after its failure: a WAV's tags live in a RIFF chunk that
+	// dhowden/tag cannot see, and its fallback -- an ID3v1 trailer --
+	// would otherwise outrank them.
+	if meta, ok := wavTags(r); ok {
+		return meta, nil
+	}
+
 	m, err := tag.ReadFrom(r)
 	if err != nil {
 		// No tags found is not necessarily an error - return empty metadata

backend/metadata/tags_wav.go

@@ -0,0 +1,68 @@
+package metadata
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+
+	"yellowjacket/backend/riff"
+)
+
+// wavTags reads the ID3v2 tag a WAV carries in its RIFF "id3 " chunk,
+// which is where backend/tagwriter puts it and where dhowden/tag --
+// having no RIFF reader at all -- cannot look.  Without this a WAV
+// scans as an untagged file however carefully it was tagged.
+//
+// ok is false when r is not a RIFF/WAVE container, and the read
+// position is restored either way so the caller can carry on.
+func wavTags(r io.ReadSeeker) (*TrackMetadata, bool) {
+	start, err := r.Seek(0, io.SeekCurrent)
+	if err != nil {
+		return nil, false
+	}
+
+	id3Data, chunkErr := riff.ID3Chunk(r)
+
+	if _, err := r.Seek(start, io.SeekStart); err != nil {
+		return nil, false
+	}
+
+	switch {
+	case chunkErr == nil:
+		return wavTagsFrom(id3Data), true
+
+	// Not ours to read: let the ordinary dispatch have the file.
+	case errors.Is(chunkErr, riff.ErrNotRIFF), errors.Is(chunkErr, riff.ErrNotWAVE):
+		return nil, false
+
+	// A RIFF container we cannot get a tag out of -- no chunk, an RF64
+	// file, a truncated header.  That is a file with no readable tags,
+	// which is what the scanner's filename fallback is for.
+	default:
+		return &TrackMetadata{}, true
+	}
+}
+
+// wavTagsFrom parses the bytes of a WAV's ID3v2 chunk.
+func wavTagsFrom(id3Data []byte) *TrackMetadata {
+	meta, err := extractID3v2Lenient(bytes.NewReader(id3Data))
+	if err != nil {
+		// A tag holding no frames is not a damaged tag: writing every
+		// field back out empty leaves one, and warning about it would
+		// put a fault on a file that has none.
+		if errors.Is(err, ErrTagsUnreadable) {
+			return &TrackMetadata{}
+		}
+
+		return &TrackMetadata{
+			TagReadWarning: fmt.Errorf("%w: %w", ErrTagsUnreadable, err),
+		}
+	}
+
+	// extractID3v2Lenient names MP3, being the recovery path for one.
+	meta.FileFormat = strings.ToUpper(strings.TrimPrefix(string(WAV), "."))
+
+	return meta
+}

backend/riff/riff.go

@@ -0,0 +1,183 @@
+// Package riff reads the chunk layout of a RIFF/WAVE container.
+//
+// It exists because both halves of WAV tagging need it and neither can
+// import the other: backend/tagwriter writes a WAV's tags into a RIFF
+// "id3 " chunk and already imports backend/metadata, which is what has
+// to read them back out.  backend/tagtotals is the precedent.
+//
+// The two readers here are deliberately different.  Parse holds every
+// chunk's data in memory, which is what rewriting a file needs; a WAV's
+// audio *is* the "data" chunk, so doing that on the scan path would
+// read every library file in full.  ID3Chunk seeks over what it is not
+// looking for instead.  Both walk the same headers.
+package riff
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// Sentinel errors describing a container this package will not read.
+var (
+	ErrRF64NotSupported = errors.New("RF64 files are not yet supported")
+	ErrNotRIFF          = errors.New("not a RIFF file")
+	ErrNotWAVE          = errors.New("not a WAVE file")
+	ErrNoID3Chunk       = errors.New("no ID3 chunk in RIFF file")
+)
+
+// Chunk holds a single RIFF sub-chunk (ID + raw data).
+type Chunk struct {
+	ID   [4]byte
+	Data []byte
+}
+
+// IsID3 reports whether id is that of an ID3v2 RIFF chunk.  Both
+// lowercase "id3 " and uppercase "ID3 " are accepted.
+func IsID3(id [4]byte) bool {
+	return strings.ToLower(string(id[:3])) == "id3"
+}
+
+// Parse reads every RIFF sub-chunk from r, in order, starting at the
+// reader's current position.  It rejects RF64 files and non-WAVE
+// containers with descriptive errors.  The parser is lenient: it
+// tolerates a missing final padding byte and ignores the declared
+// RIFF size.
+func Parse(r io.Reader) ([]Chunk, error) {
+	if err := readContainer(r); err != nil {
+		return nil, err
+	}
+
+	var chunks []Chunk
+
+	for {
+		id, size, err := nextHeader(r)
+		if errors.Is(err, io.EOF) {
+			break
+		}
+
+		if err != nil {
+			return nil, err
+		}
+
+		data := make([]byte, size)
+		if _, err := io.ReadFull(r, data); err != nil {
+			return nil, fmt.Errorf("read chunk data for %q: %w", id, err)
+		}
+
+		chunks = append(chunks, Chunk{ID: id, Data: data})
+
+		// Odd-length chunks have a padding byte.  Lenient: if the
+		// read fails (e.g. EOF), just break rather than error.
+		if size%2 != 0 {
+			var pad [1]byte
+
+			if _, err := r.Read(pad[:]); err != nil {
+				break
+			}
+		}
+	}
+
+	return chunks, nil
+}
+
+// ID3Chunk returns the payload of the ID3v2 chunk of the RIFF/WAVE
+// container at the reader's current position, seeking over every other
+// chunk rather than reading it.  It returns ErrNoID3Chunk when the
+// container carries no such chunk, and leaves the read position
+// unspecified either way.
+func ID3Chunk(r io.ReadSeeker) ([]byte, error) {
+	if err := readContainer(r); err != nil {
+		return nil, err
+	}
+
+	for {
+		id, size, err := nextHeader(r)
+		if errors.Is(err, io.EOF) {
+			return nil, ErrNoID3Chunk
+		}
+
+		if err != nil {
+			return nil, err
+		}
+
+		if !IsID3(id) {
+			// Odd-length chunks carry a padding byte.  Seeking past
+			// the end of the file is not an error; the next header
+			// read is what reports the end.
+			if _, err := r.Seek(int64(size)+int64(size%2), io.SeekCurrent); err != nil {
+				return nil, fmt.Errorf("skip chunk %q: %w", id, err)
+			}
+
+			continue
+		}
+
+		// Copied rather than allocated up front: a truncated file is
+		// free to declare a chunk larger than the whole of itself.
+		var data bytes.Buffer
+		if _, err := io.CopyN(&data, r, int64(size)); err != nil {
+			return nil, fmt.Errorf("read chunk data for %q: %w", id, err)
+		}
+
+		return data.Bytes(), nil
+	}
+}
+
+// readContainer consumes the 12-byte RIFF/WAVE header at the reader's
+// current position.
+func readContainer(r io.Reader) error {
+	var magic [4]byte
+	if _, err := io.ReadFull(r, magic[:]); err != nil {
+		return fmt.Errorf("read RIFF magic: %w", err)
+	}
+
+	if string(magic[:]) == "RF64" {
+		return ErrRF64NotSupported
+	}
+
+	if string(magic[:]) != "RIFF" {
+		return fmt.Errorf("%w: got %q", ErrNotRIFF, magic)
+	}
+
+	// Read (and discard) RIFF size — lenient, do not enforce.
+	var riffSize uint32
+	if err := binary.Read(r, binary.LittleEndian, &riffSize); err != nil {
+		return fmt.Errorf("read RIFF size: %w", err)
+	}
+
+	var form [4]byte
+	if _, err := io.ReadFull(r, form[:]); err != nil {
+		return fmt.Errorf("read WAVE form type: %w", err)
+	}
+
+	if string(form[:]) != "WAVE" {
+		return fmt.Errorf("%w: got %q", ErrNotWAVE, form)
+	}
+
+	return nil
+}
+
+// nextHeader reads one sub-chunk header.  It returns io.EOF once the
+// chunks are exhausted, including for a header cut short.
+func nextHeader(r io.Reader) ([4]byte, uint32, error) {
+	var id [4]byte
+
+	_, err := io.ReadFull(r, id[:])
+	if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
+		return id, 0, io.EOF
+	}
+
+	if err != nil {
+		return id, 0, fmt.Errorf("read chunk ID: %w", err)
+	}
+
+	var size uint32
+	if err := binary.Read(r, binary.LittleEndian, &size); err != nil {
+		return id, 0, fmt.Errorf("read chunk size for %q: %w", id, err)
+	}
+
+	return id, size, nil
+}

backend/riff/riff_test.go

@@ -0,0 +1,211 @@
+package riff_test
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"testing"
+
+	"yellowjacket/backend/riff"
+)
+
+// chunk is one sub-chunk to put in a test container.
+type chunk struct {
+	id   string
+	data []byte
+}
+
+// buildRIFF assembles a container from magic, form type and chunks,
+// padding odd-length chunks the way a writer must.
+func buildRIFF(magic, form string, chunks []chunk) []byte {
+	var body bytes.Buffer
+
+	body.WriteString(form)
+
+	for _, c := range chunks {
+		body.WriteString(c.id)
+		_ = binary.Write(&body, binary.LittleEndian, uint32(len(c.data)))
+		body.Write(c.data)
+
+		if len(c.data)%2 != 0 {
+			body.WriteByte(0)
+		}
+	}
+
+	var out bytes.Buffer
+
+	out.WriteString(magic)
+	_ = binary.Write(&out, binary.LittleEndian, uint32(body.Len()))
+	out.Write(body.Bytes())
+
+	return out.Bytes()
+}
+
+func TestID3Chunk_FindsTheTagPastTheAudio(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		chunks []chunk
+		want   string
+	}{
+		{
+			name: "after an odd-length chunk",
+			chunks: []chunk{
+				{id: "fmt ", data: make([]byte, 16)},
+				{id: "LIST", data: []byte("INFOodd")},
+				{id: "data", data: make([]byte, 200)},
+				{id: "id3 ", data: []byte("ID3vTAG")},
+			},
+			want: "ID3vTAG",
+		},
+		{
+			// The chunk ID is written both ways in the wild, and the
+			// writer accepts either, so the reader must too.
+			name: "uppercase ID3",
+			chunks: []chunk{
+				{id: "data", data: make([]byte, 8)},
+				{id: "ID3 ", data: []byte("upper")},
+			},
+			want: "upper",
+		},
+		{
+			name: "first chunk",
+			chunks: []chunk{
+				{id: "id3 ", data: []byte("first")},
+				{id: "data", data: make([]byte, 8)},
+			},
+			want: "first",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			r := bytes.NewReader(buildRIFF("RIFF", "WAVE", tc.chunks))
+
+			got, err := riff.ID3Chunk(r)
+			if err != nil {
+				t.Fatalf("ID3Chunk: %v", err)
+			}
+
+			if string(got) != tc.want {
+				t.Errorf("chunk data: got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestID3Chunk_RejectsWhatItCannotRead(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		bytes []byte
+		want  error
+	}{
+		{
+			name:  "no ID3 chunk",
+			bytes: buildRIFF("RIFF", "WAVE", []chunk{{id: "data", data: []byte{1, 2}}}),
+			want:  riff.ErrNoID3Chunk,
+		},
+		{
+			name:  "no chunks at all",
+			bytes: buildRIFF("RIFF", "WAVE", nil),
+			want:  riff.ErrNoID3Chunk,
+		},
+		{
+			name:  "not RIFF",
+			bytes: []byte("ID3\x03\x00\x00\x00\x00\x00\x00\x00\x00"),
+			want:  riff.ErrNotRIFF,
+		},
+		{
+			name:  "not WAVE",
+			bytes: buildRIFF("RIFF", "AVI ", []chunk{{id: "id3 ", data: []byte("x")}}),
+			want:  riff.ErrNotWAVE,
+		},
+		{
+			name:  "RF64",
+			bytes: buildRIFF("RF64", "WAVE", []chunk{{id: "id3 ", data: []byte("x")}}),
+			want:  riff.ErrRF64NotSupported,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := riff.ID3Chunk(bytes.NewReader(tc.bytes))
+			if !errors.Is(err, tc.want) {
+				t.Errorf("ID3Chunk error: got %v, want %v", err, tc.want)
+			}
+		})
+	}
+}
+
+// A file cut short mid-chunk is a file with no tag, not a reason to
+// allocate the size it claims: the declared size is four bytes any
+// truncation can leave saying 4 GB.
+func TestID3Chunk_ToleratesATruncatedFile(t *testing.T) {
+	t.Parallel()
+
+	full := buildRIFF("RIFF", "WAVE", []chunk{
+		{id: "data", data: make([]byte, 64)},
+		{id: "id3 ", data: []byte("tag")},
+	})
+
+	t.Run("cut inside the audio", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := riff.ID3Chunk(bytes.NewReader(full[:32]))
+		if !errors.Is(err, riff.ErrNoID3Chunk) {
+			t.Errorf("ID3Chunk error: got %v, want %v", err, riff.ErrNoID3Chunk)
+		}
+	})
+
+	t.Run("cut inside the tag", func(t *testing.T) {
+		t.Parallel()
+
+		if _, err := riff.ID3Chunk(bytes.NewReader(full[:len(full)-2])); err == nil {
+			t.Error("ID3Chunk: got nil error for a truncated tag chunk")
+		}
+	})
+}
+
+// Parse is the writer's half and reads every chunk into memory, which
+// is what preserving them needs.
+func TestParse_ReadsEveryChunkInOrder(t *testing.T) {
+	t.Parallel()
+
+	raw := buildRIFF("RIFF", "WAVE", []chunk{
+		{id: "fmt ", data: make([]byte, 16)},
+		{id: "LIST", data: []byte("INFOodd")},
+		{id: "id3 ", data: []byte("tag")},
+	})
+
+	chunks, err := riff.Parse(bytes.NewReader(raw))
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+
+	want := []string{"fmt ", "LIST", "id3 "}
+	if len(chunks) != len(want) {
+		t.Fatalf("chunk count: got %d, want %d", len(chunks), len(want))
+	}
+
+	for i, id := range want {
+		if got := string(chunks[i].ID[:]); got != id {
+			t.Errorf("chunk %d: got %q, want %q", i, got, id)
+		}
+	}
+
+	if !riff.IsID3(chunks[2].ID) || string(chunks[2].Data) != "tag" {
+		t.Errorf("id3 chunk: got %q", chunks[2].Data)
+	}
+
+	// The padding byte after an odd chunk is not part of its data.
+	if string(chunks[1].Data) != "INFOodd" {
+		t.Errorf("odd chunk data: got %q, want %q", chunks[1].Data, "INFOodd")
+	}
+}

backend/tagwriter/totals_test.go

@@ -13,9 +13,10 @@ import (
 // indistinguishable from never having written one.  So these assert the
 // round trip through the *reader the scan uses*, not the bytes.
 //
-// WAV is the exception and it is not this change's: dhowden/tag has no
-// RIFF reader at all, so metadata.ExtractTags cannot see a WAV's ID3
-// chunk -- which is why every other test here reads that chunk itself.
+// WAV was the exception until #104 -- dhowden/tag has no RIFF reader,
+// so metadata.ExtractTags could not see a WAV's ID3 chunk and this
+// case read the chunk itself, which is a test of the writer wearing
+// the shape of a round trip.  All four go through the scanner now.
 func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
 	t.Parallel()
 
@@ -91,7 +92,7 @@ func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
 		},
 		{
 			name: "wav",
-			read: readWavID3Tags,
+			read: viaScanner,
 			write: func(t *testing.T, dir string) string {
 				t.Helper()
 

backend/tagwriter/wav.go

@@ -8,116 +8,22 @@ import (
 	"io"
 	"log/slog"
 	"os"
-	"strings"
 
 	id3v2 "github.com/bogem/id3v2/v2"
 
 	"yellowjacket/backend/fileutil"
+	"yellowjacket/backend/riff"
 )
 
-// Sentinel errors for WAV RIFF operations.
-var (
-	errRF64NotSupported   = errors.New("RF64 files are not yet supported")
-	errNotRIFF            = errors.New("not a RIFF file")
-	errNotWAVE            = errors.New("not a WAVE file")
-	errFileTooLargeForWAV = errors.New("file too large for WAV format (>4GB)")
-)
-
-// riffChunk holds a single RIFF sub-chunk (ID + raw data).
-type riffChunk struct {
-	id   [4]byte
-	data []byte
-}
-
-// parseRIFF reads all RIFF sub-chunks from r.  It rejects RF64 files
-// and non-WAVE containers with descriptive errors.  The parser is
-// lenient on read: it tolerates missing padding bytes and ignores
-// the declared RIFF size.
-func parseRIFF(r io.ReadSeeker) ([]riffChunk, error) {
-	// Read 4-byte container magic.
-	var magic [4]byte
-	if _, err := io.ReadFull(r, magic[:]); err != nil {
-		return nil, fmt.Errorf("read RIFF magic: %w", err)
-	}
-
-	if string(magic[:]) == "RF64" {
-		return nil, errRF64NotSupported
-	}
-
-	if string(magic[:]) != "RIFF" {
-		return nil, fmt.Errorf("%w: got %q", errNotRIFF, magic)
-	}
-
-	// Read (and discard) RIFF size — lenient, do not enforce.
-	var riffSize uint32
-	if err := binary.Read(r, binary.LittleEndian, &riffSize); err != nil {
-		return nil, fmt.Errorf("read RIFF size: %w", err)
-	}
-
-	// Read 4-byte form type.
-	var form [4]byte
-	if _, err := io.ReadFull(r, form[:]); err != nil {
-		return nil, fmt.Errorf("read WAVE form type: %w", err)
-	}
-
-	if string(form[:]) != "WAVE" {
-		return nil, fmt.Errorf("%w: got %q", errNotWAVE, form)
-	}
-
-	// Read sub-chunks until EOF.
-	var chunks []riffChunk
-
-	for {
-		var chunkID [4]byte
-
-		_, err := io.ReadFull(r, chunkID[:])
-		if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
-			break
-		}
-
-		if err != nil {
-			return nil, fmt.Errorf("read chunk ID: %w", err)
-		}
-
-		var chunkSize uint32
-		if err := binary.Read(r, binary.LittleEndian, &chunkSize); err != nil {
-			return nil, fmt.Errorf("read chunk size for %q: %w", chunkID, err)
-		}
-
-		data := make([]byte, chunkSize)
-		if _, err := io.ReadFull(r, data); err != nil {
-			return nil, fmt.Errorf("read chunk data for %q: %w", chunkID, err)
-		}
-
-		chunks = append(chunks, riffChunk{id: chunkID, data: data})
-
-		// Odd-length chunks have a padding byte.  Lenient: if the
-		// read fails (e.g. EOF), just break rather than error.
-		if chunkSize%2 != 0 {
-			var pad [1]byte
-
-			if _, err := r.Read(pad[:]); err != nil {
-				break
-			}
-		}
-	}
-
-	return chunks, nil
-}
-
-// isID3ChunkID returns true if id represents an ID3v2 RIFF chunk.
-// Both lowercase "id3 " and uppercase "ID3 " are accepted.
-func isID3ChunkID(id [4]byte) bool {
-	s := strings.ToLower(string(id[:3]))
-
-	return s == "id3"
-}
+// errFileTooLargeForWAV is the one RIFF error that belongs to the
+// writer; reading rejects a container in backend/riff.
+var errFileTooLargeForWAV = errors.New("file too large for WAV format (>4GB)")
 
 // writeRIFF writes a complete RIFF/WAVE container to w, preserving
 // the given chunks in order and appending the id3Data as the final
 // "id3 " chunk.  Returns errFileTooLargeForWAV if the result would
 // exceed the 4 GB RIFF limit.
-func writeRIFF(w io.Writer, chunks []riffChunk, id3Data []byte) error {
+func writeRIFF(w io.Writer, chunks []riff.Chunk, id3Data []byte) error {
 	// Calculate total RIFF payload size:
 	//   4 bytes (WAVE form type)
 	// + for each preserved chunk: 8 (header) + len(data) + padding
@@ -125,7 +31,7 @@ func writeRIFF(w io.Writer, chunks []riffChunk, id3Data []byte) error {
 	riffPayload := uint64(4)
 
 	for _, c := range chunks {
-		sz := uint64(len(c.data))
+		sz := uint64(len(c.Data))
 		riffPayload += 8 + sz
 
 		if sz%2 != 0 {
@@ -162,7 +68,7 @@ func writeRIFF(w io.Writer, chunks []riffChunk, id3Data []byte) error {
 
 	// Write each preserved chunk.
 	for _, c := range chunks {
-		if err := writeChunk(w, c.id, c.data); err != nil {
+		if err := writeChunk(w, c.ID, c.Data); err != nil {
 			return err
 		}
 	}
@@ -225,7 +131,7 @@ func writeWavTags(
 		return fmt.Errorf("open wav for reading: %w", err)
 	}
 
-	allChunks, err := parseRIFF(f)
+	allChunks, err := riff.Parse(f)
 
 	// Close immediately — we need the handle released before
 	// AtomicWrite creates the replacement file.
@@ -237,13 +143,13 @@ func writeWavTags(
 
 	// Separate preserved chunks from existing ID3 data.
 	var (
-		preserved   []riffChunk
+		preserved   []riff.Chunk
 		existingID3 []byte
 	)
 
 	for _, c := range allChunks {
-		if isID3ChunkID(c.id) {
-			existingID3 = c.data
+		if riff.IsID3(c.ID) {
+			existingID3 = c.Data
 		} else {
 			preserved = append(preserved, c)
 		}

backend/tagwriter/wav_test.go

@@ -12,6 +12,7 @@ import (
 	id3v2 "github.com/bogem/id3v2/v2"
 
 	"yellowjacket/backend/metadata"
+	"yellowjacket/backend/riff"
 )
 
 // createTestWAV builds a minimal valid WAV file with an optional
@@ -270,6 +271,88 @@ func TestWriteWavTags_PartialUpdate(t *testing.T) {
 	assertStrField(t, "Composer", meta.Composer, "Original Composer")
 }
 
+// The writer has always been correct and the reader could not see it:
+// a WAV tagged by this app scanned as an untagged file, so editing
+// tags, autotagging a folder or importing a WAV download all appeared
+// to work and changed nothing the library could show (#104).  So this
+// asserts the write through metadata.ExtractTags -- the reader the
+// scan uses -- rather than through the id3 chunk.
+func TestWriteWavTags_ReadBackByTheScanner(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	path := createTestWAV(t, dir, "scanner.wav", nil)
+	art := tinyJPEG(t)
+
+	changes := TagChanges{
+		FieldTitle:       "Some Song",
+		FieldArtist:      "Some Artist",
+		FieldAlbum:       "Some Album",
+		FieldAlbumArtist: "Some Album Artist",
+		FieldGenre:       "Rock",
+		FieldYear:        2024,
+		FieldTrackNumber: 3,
+		FieldComposer:    "Some Composer",
+		FieldCoverArt:    art,
+	}
+
+	if err := writeWavTags(testLogger(), path, changes); err != nil {
+		t.Fatalf("writeWavTags: %v", err)
+	}
+
+	meta, err := metadata.ExtractTags(path)
+	if err != nil {
+		t.Fatalf("ExtractTags: %v", err)
+	}
+
+	if meta.TagReadWarning != nil {
+		t.Errorf("TagReadWarning: %v", meta.TagReadWarning)
+	}
+
+	assertStrField(t, "Title", meta.Title, "Some Song")
+	assertStrField(t, "Artist", meta.Artist, "Some Artist")
+	assertStrField(t, "Album", meta.Album, "Some Album")
+	assertStrField(t, "AlbumArtist", meta.AlbumArtist, "Some Album Artist")
+	assertStrField(t, "Genre", meta.Genre, "Rock")
+	assertStrField(t, "Composer", meta.Composer, "Some Composer")
+	assertStrField(t, "FileFormat", meta.FileFormat, "WAV")
+	assertIntField(t, "Year", meta.Year, 2024)
+	assertIntField(t, "TrackNumber", meta.TrackNumber, 3)
+
+	if !strings.HasPrefix(meta.TagFormat, "ID3v2") {
+		t.Errorf("TagFormat: got %q, want an ID3v2 version", meta.TagFormat)
+	}
+
+	if meta.Picture == nil {
+		t.Fatal("expected cover art, got nil")
+	}
+
+	if !bytes.Equal(meta.Picture.Data, art) {
+		t.Errorf("picture data mismatch: got %d bytes, want %d",
+			len(meta.Picture.Data), len(art))
+	}
+}
+
+// An untagged WAV is a file with no tags, not a file with a problem:
+// the scanner falls back to the filename and must not be handed a
+// warning to surface about it.
+func TestUntaggedWav_ReadsAsEmptyWithoutAWarning(t *testing.T) {
+	t.Parallel()
+
+	path := createTestWAV(t, t.TempDir(), "bare.wav", nil)
+
+	meta, err := metadata.ExtractTags(path)
+	if err != nil {
+		t.Fatalf("ExtractTags: %v", err)
+	}
+
+	if meta.TagReadWarning != nil {
+		t.Errorf("TagReadWarning: %v", meta.TagReadWarning)
+	}
+
+	assertStrField(t, "Title", meta.Title, "")
+}
+
 func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	t.Parallel()
 
@@ -282,7 +365,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 		t.Fatalf("open original: %v", err)
 	}
 
-	origChunks, err := parseRIFF(origFile)
+	origChunks, err := riff.Parse(origFile)
 	_ = origFile.Close()
 
 	if err != nil {
@@ -292,7 +375,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	// Record original chunk data by ID string.
 	origData := map[string][]byte{}
 	for _, c := range origChunks {
-		origData[string(c.id[:])] = c.data
+		origData[string(c.ID[:])] = c.Data
 	}
 
 	// Write a tag to trigger RIFF rewrite.
@@ -309,7 +392,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 		t.Fatalf("open after write: %v", err)
 	}
 
-	newChunks, err := parseRIFF(newFile)
+	newChunks, err := riff.Parse(newFile)
 	_ = newFile.Close()
 
 	if err != nil {
@@ -320,7 +403,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	origNonID3 := 0
 
 	for _, c := range origChunks {
-		if !isID3ChunkID(c.id) {
+		if !riff.IsID3(c.ID) {
 			origNonID3++
 		}
 	}
@@ -328,7 +411,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	newNonID3 := 0
 
 	for _, c := range newChunks {
-		if !isID3ChunkID(c.id) {
+		if !riff.IsID3(c.ID) {
 			newNonID3++
 		}
 	}
@@ -359,17 +442,17 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 // in chunks and its data matches want byte-for-byte.
 func checkChunkPreserved(
 	t *testing.T,
-	chunks []riffChunk,
+	chunks []riff.Chunk,
 	idStr string,
 	want []byte,
 ) {
 	t.Helper()
 
 	for _, c := range chunks {
-		if string(c.id[:]) == idStr {
-			if !bytes.Equal(c.data, want) {
+		if string(c.ID[:]) == idStr {
+			if !bytes.Equal(c.Data, want) {
 				t.Errorf("chunk %q data changed: got %d bytes, want %d",
-					idStr, len(c.data), len(want))
+					idStr, len(c.Data), len(want))
 			}
 
 			return
@@ -430,7 +513,7 @@ func TestWriteWavTags_RejectsRF64(t *testing.T) {
 	buf.WriteString("WAVE")
 
 	// Minimal ds64 chunk (required for RF64 but we just need
-	// enough bytes for parseRIFF to hit the RF64 rejection).
+	// enough bytes for riff.Parse to hit the RF64 rejection).
 	buf.WriteString("ds64")
 	_ = binary.Write(&buf, binary.LittleEndian, uint32(28)) //nolint:mnd
 	buf.Write(make([]byte, 28))                             //nolint:mnd
@@ -454,9 +537,12 @@ func TestWriteWavTags_RejectsRF64(t *testing.T) {
 
 // readWavID3Tags extracts ID3v2 metadata from a WAV file by parsing
 // the RIFF structure and reading the id3 chunk with bogem/id3v2.
-// dhowden/tag's ReadFrom does not support WAV files, and its
-// ReadID3v2Tags fails on empty tags (after clearing all frames).
-// Using bogem/id3v2.ParseReader handles all cases correctly.
+//
+// metadata.ExtractTags reads a WAV since #104 and is what the round
+// trips assert through.  This stays for the two cases that are about
+// the bytes rather than about the scan: a tag with every frame
+// cleared, which no reader reports as anything, and the chunk
+// preservation test, which is already parsing the container itself.
 func readWavID3Tags(
 	t *testing.T,
 	path string,
@@ -470,17 +556,17 @@ func readWavID3Tags(
 
 	defer func() { _ = f.Close() }()
 
-	chunks, err := parseRIFF(f)
+	chunks, err := riff.Parse(f)
 	if err != nil {
-		t.Fatalf("parseRIFF: %v", err)
+		t.Fatalf("riff.Parse: %v", err)
 	}
 
 	// Find the id3 chunk.
 	var id3Data []byte
 
 	for _, c := range chunks {
-		if isID3ChunkID(c.id) {
-			id3Data = c.data
+		if riff.IsID3(c.ID) {
+			id3Data = c.Data
 
 			break
 		}

frontend/src/components/artists-view/artists-view.ts

@@ -7,7 +7,6 @@ import {
 import '@lit-labs/virtualizer';
 import type {
     LitVirtualizer,
-    RangeChangedEvent,
     VisibilityChangedEvent,
 } from '@lit-labs/virtualizer';
 import { grid } from '@lit-labs/virtualizer/layouts/grid.js';
@@ -31,7 +30,6 @@ import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { ViewLifecycleMixin } from '@utils/view-lifecycle';
 import { RovingGridController } from '@utils/roving-grid';
-import { prefetchImageWindow } from '@utils/image-prefetch';
 
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
@@ -584,26 +582,6 @@ export class ArtistsView
      * Scroll position persistence
      * ================================================================ */
 
-    /**
-     * Warm the avatars just past the rendered range (#65).
-     *
-     * `rangeChanged` is the rendered range and `visibilityChanged` is
-     * what is on screen; the virtualizer has already drawn about
-     * 1000px past the latter, so that is the wrong anchor to measure a
-     * prefetch window from. It is deliberately outside the
-     * `restoringScroll` guard below: a restored scroll lands in the
-     * middle of the grid, which is exactly when nothing around it is
-     * cached.
-     */
-    private onRangeChanged = (e: RangeChangedEvent) => {
-        prefetchImageWindow(
-            this.cachedGridEntries,
-            e.first,
-            e.last,
-            (entry) => this.artistAvatarURL(entry.artist),
-        );
-    };
-
     /**
      * Save the first visible item index on scroll.
      */
@@ -1167,16 +1145,7 @@ export class ArtistsView
      * Helpers
      * ================================================================ */
 
-    /**
-     * The image this artist's card will draw, or `''` for the initial
-     * placeholder.
-     *
-     * Split out of `renderArtistAvatar` so the prefetch (#65) asks for
-     * exactly what the card is going to ask for — a second copy of the
-     * tier ladder would be a second thing to keep in step, and warming
-     * the wrong tier is a download that buys nothing.
-     */
-    private artistAvatarURL(artist: library.Artist): string {
+    private renderArtistAvatar(artist: library.Artist) {
         const needed = (this.imageSize ?? 176) * window.devicePixelRatio;
         let imageURL = '';
 
@@ -1203,12 +1172,6 @@ export class ArtistsView
             ) ?? '';
         }
 
-        return imageURL;
-    }
-
-    private renderArtistAvatar(artist: library.Artist) {
-        const imageURL = this.artistAvatarURL(artist);
-
         if (imageURL) {
             return html`<img
                 class="avatar-image"
@@ -1568,7 +1531,6 @@ export class ArtistsView
                     .keyFunction=${(entry: ArtistEntry) => entry.artist.ID}
                     .layout=${this.gridLayout}
                     @visibilityChanged=${this.onVisibilityChanged}
-                    @rangeChanged=${this.onRangeChanged}
                 ></lit-virtualizer>
             </div>
             ${this.renderContextMenu()}

frontend/src/components/cover-grid/cover-grid.ts

@@ -8,7 +8,6 @@ import {
 import '@lit-labs/virtualizer';
 import type {
     LitVirtualizer,
-    RangeChangedEvent,
     VisibilityChangedEvent,
 } from '@lit-labs/virtualizer';
 import { grid } from '@lit-labs/virtualizer/layouts/grid.js';
@@ -31,7 +30,6 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@components/playlist-picker/playlist-picker.js';
 import { loadTrackDetails } from '@utils/lazy-track-details.js';
 import { tracksByFilePath, tracksForPaths } from '@utils/track-index.js';
-import { prefetchImageWindow } from '@utils/image-prefetch.js';
 import type { TrackDetails } from '@components/track-details/track-details.js';
 import type { CoverArtUrls } from '@components/track-details/track-details.js';
 import { AlbumSelectionManager } from './album-selection.js';
@@ -910,31 +908,6 @@ export class CoverGrid
         );
     };
 
-    /**
-     * Warm the covers just past the rendered range (#65).
-     *
-     * `rangeChanged` rather than `visibilityChanged`, because the two
-     * report different ranges and only one of them is the right
-     * anchor: visibility is what is on screen, and the virtualizer has
-     * already rendered about 1000px past that. Measured from the
-     * visible range this would spend most of its window on cards that
-     * already exist and have already asked for their own art.
-     *
-     * The entry lists are memoized, so asking for one here costs a
-     * reference compare.
-     */
-    private onRangeChanged = (e: RangeChangedEvent) => {
-        const entries = this.splitMode
-            ? this.getBeforeEntries()
-            : this.buildGridEntries();
-
-        prefetchImageWindow(entries, e.first, e.last, (entry) =>
-            entry.album.CoverArtPath
-                ? this.getCoverUrl(entry.album)
-                : '',
-        );
-    };
-
     /* ====================================================================
      * Virtualizer items
      * ==================================================================== */
@@ -2028,7 +2001,6 @@ export class CoverGrid
                 @keydown=${this.onGridAlbumKeydown}
                 @contextmenu=${this.onGridAlbumContextMenu}
                 @visibilityChanged=${this.onVisibilityChanged}
-                @rangeChanged=${this.onRangeChanged}
             ></lit-virtualizer>
         `;
     }
@@ -2063,7 +2035,6 @@ export class CoverGrid
                 @keydown=${this.onGridAlbumKeydown}
                 @contextmenu=${this.onGridAlbumContextMenu}
                 @visibilityChanged=${this.onVisibilityChanged}
-                @rangeChanged=${this.onRangeChanged}
             ></lit-virtualizer>
 
             <album-dropdown

frontend/src/utils/image-prefetch.ts

@@ -1,156 +0,0 @@
-/**
- * Warm the browser's image cache for the cards a scroll is about to
- * reach.
- *
- * #65: album art pops in while scrolling. The rule this app already
- * follows is that a row image is `loading="lazy" decoding="async"` and
- * draws the smallest adequate tier, and both halves are in place —
- * `cover-grid.getCoverUrl()` and `artists-view`'s avatar both pick
- * `_sm`/`_md`/`_lg` from the card size and the device pixel ratio. What
- * is left is *when* the fetch starts: the grids are virtualized, so the
- * `<img>` does not exist at all until the virtualizer decides to render
- * its card, and only then can the browser ask for anything.
- *
- * The issue's Direction asks for a larger overscan, and that is not
- * available: `@lit-labs/virtualizer`'s `_overhang` is a hard-coded
- * 1000px `protected` field on `BaseLayout` with no configuration
- * surface, so raising it means monkey-patching a private. 1000px is
- * about two screens on the reference device's 439px viewport, which is
- * a fraction of a second at speed.
- *
- * So the request is issued ahead of the element instead. Cover art and
- * artist images are plain URLs served by `coverart.Handler` /
- * `explore`'s image handler under `Cache-Control: public,
- * max-age=31536000, immutable` — the filenames are content hashes — so
- * a prefetched image is a cache hit by the time the card is drawn, and
- * a second pass over the same rows costs nothing at all.
- *
- * Three things about it are load-bearing.
- *
- * **This is not the `LRUMap` path the issue's Findings warn about.**
- * That ceiling (`ARTIST_IMAGE_CACHE_LIMIT` and friends) bounds
- * Explore's base64 data URLs, which are held in JS. A library cover is
- * a URL, and what retains the bytes is the browser's own HTTP cache,
- * which evicts on its own terms. What this module retains is the *set
- * of URLs already asked for*, which is why that set has a cap and
- * reports itself to `window.__yjCacheStats()` — the measurement the
- * issue asks for.
- *
- * **A window is warmed on both sides of the rendered range.** The
- * event carries no direction, and scrolling back up needs the same
- * treatment; the rows behind are already in `requested` from the pass
- * that rendered them, so the backward half issues nothing in the
- * common case and is free.
- *
- * **An in-flight image is held.** `new Image().src = url` and drop it
- * is the usual idiom and usually survives, but "usually" is an engine
- * detail and the engine that matters here is a two-year-old WebView.
- * The element is kept until it loads or fails, and no longer — nothing
- * here holds a decoded bitmap on purpose.
- */
-
-import { registerCacheProbe } from './cache-stats.js';
-import { LRUMap } from './lru-map.js';
-
-/**
- * How many entries past each edge of the rendered range to warm.
- *
- * Entries rather than pixels, because that is what the event reports
- * and what the caller has an array of. Twelve rows on the phone's
- * two-column grid and four on a desktop's six, on top of the
- * virtualizer's own 1000px — enough to cover a flick, and bounded so a
- * fast scroll through 5 000 albums cannot ask for 5 000 covers.
- */
-export const PREFETCH_AHEAD = 24;
-
-/** Ceiling on the record of what has already been asked for. */
-export const PREFETCH_MEMORY = 512;
-
-/** URLs already requested; the value is a placeholder, the key is the record. */
-const requested = new LRUMap<string, true>(PREFETCH_MEMORY);
-
-/** Images still loading, held so the request cannot be collected. */
-const inFlight = new Set<HTMLImageElement>();
-
-registerCacheProbe('imagePrefetch', () => {
-    let chars = 0;
-
-    for (const url of requested.keys()) chars += url.length;
-
-    return { entries: requested.size, chars, limit: PREFETCH_MEMORY };
-});
-
-/** Whether this URL has already been asked for. */
-export function imagePrefetched(url: string): boolean {
-    return requested.has(url);
-}
-
-/**
- * Ask the browser for `url` unless it has already been asked for.
- * Returns whether a request was issued.
- */
-export function prefetchImage(url: string): boolean {
-    if (!url || requested.has(url)) return false;
-
-    requested.set(url, true);
-
-    const img = new Image();
-
-    inFlight.add(img);
-
-    const done = () => {
-        inFlight.delete(img);
-    };
-
-    img.addEventListener('load', done, { once: true });
-    img.addEventListener('error', done, { once: true });
-    img.decoding = 'async';
-    img.src = url;
-
-    return true;
-}
-
-/**
- * Warm the images either side of a virtualizer's rendered range.
- *
- * `first`/`last` are the indices the `visibilityChanged` event
- * reported; `urlOf` returns the image the card at that index will
- * draw, or `''` where it draws a placeholder. Returns how many
- * requests were issued, which is what a test can assert on and what
- * makes "a second run does approximately nothing" checkable.
- */
-export function prefetchImageWindow<T>(
-    items: readonly T[],
-    first: number,
-    last: number,
-    urlOf: (item: T) => string,
-    ahead: number = PREFETCH_AHEAD,
-): number {
-    if (items.length === 0 || first < 0 || last < first) return 0;
-
-    const from = Math.max(0, first - ahead);
-    const to = Math.min(items.length - 1, last + ahead);
-    let issued = 0;
-
-    // Forward first: it is the direction a scroll is usually going, so
-    // it is the half that has to win the race.
-    for (let i = last + 1; i <= to; i++) {
-        const item = items[i];
-
-        if (item !== undefined && prefetchImage(urlOf(item))) issued++;
-    }
-
-    for (let i = from; i < first; i++) {
-        const item = items[i];
-
-        if (item !== undefined && prefetchImage(urlOf(item))) issued++;
-    }
-
-    return issued;
-}
-
-/** Forget what has been asked for. For tests; the app never needs it. */
-export function resetImagePrefetch(): void {
-    requested.clear();
-    inFlight.clear();
-}

frontend/test/components/art-prefetch.test.ts

@@ -1,190 +0,0 @@
-/**
- * The grids ask for the art below the fold before the card exists
- * (#65).
- *
- * Reported as "scrolling through albums, the art pops in". The cards
- * already draw the smallest adequate tier and are already
- * `loading="lazy"`, so what was left is *when*: `<lit-virtualizer>`
- * renders about 1000px past the viewport and the `<img>` — and
- * therefore the request — does not exist until it does. On the
- * reference device that is about two screens.
- *
- * These assert the mechanism, since no tier here can photograph a
- * pop-in: that the rows past the rendered range are requested, that
- * the request is for the same tier the card will draw, and that the
- * window has an end — an unbounded prefetch of a 5 000-album library
- * is the failure this trades against.
- *
- * What is *not* asserted here is that a rendered card was never
- * prefetched. It often was, honestly: the grid lays out more than once
- * on mount, so a row warmed by the first pass is drawn by the second,
- * which is the whole point. The rule that a single pass skips its own
- * rendered range is `image-prefetch.test.ts`'s, where one call can be
- * looked at on its own.
- */
-import { describe, expect, it, beforeEach } from 'vitest';
-import type { LitElement } from 'lit';
-
-import '@components/cover-grid/cover-grid';
-import '@components/artists-view/artists-view';
-import { emit, stub, flush, resetHarness } from '@test/support/harness';
-import { Events } from '../../src/events';
-import { fixture, shadowAll } from '@test/support/render';
-import {
-  PREFETCH_AHEAD,
-  imagePrefetched,
-  resetImagePrefetch,
-} from '@utils/image-prefetch';
-
-/** Enough albums that the virtualizer's own window is nowhere near the end. */
-const ALBUMS = Array.from({ length: 400 }, (_, i) => {
-  const n = String(i + 1).padStart(4, '0');
-
-  return {
-    ID: i + 1,
-    Name: `Album ${n}`,
-    ArtistName: 'Aurora Fields',
-    Year: 2020,
-    CoverArtPath: `/covers/${n}.jpg`,
-    CoverArtSmall: `/covers/${n}_sm.jpg`,
-    CoverArtMedium: `/covers/${n}_md.jpg`,
-    CoverArtLarge: `/covers/${n}_lg.jpg`,
-  };
-});
-
-const ARTISTS = Array.from({ length: 400 }, (_, i) => {
-  const n = String(i + 1).padStart(4, '0');
-
-  return {
-    ID: i + 1,
-    Name: `Artist ${n}`,
-    AlbumCount: 2,
-    TrackCount: 9,
-    ImageSmall: `/artists/${n}_sm.jpg`,
-    ImageMedium: `/artists/${n}_md.jpg`,
-    ImageLarge: `/artists/${n}_lg.jpg`,
-  };
-});
-
-/** Give the virtualizer a viewport; a zero-height host renders nothing. */
-function sized(el: HTMLElement): void {
-  el.style.display = 'block';
-  el.style.height = '600px';
-  el.style.width = '900px';
-}
-
-async function settle(el: LitElement): Promise<void> {
-  await flush();
-  await el.updateComplete;
-  await new Promise((r) => setTimeout(r, 200));
-}
-
-/** The `src` of every card the grid actually rendered. */
-function renderedSources(el: LitElement, selector: string): string[] {
-  return shadowAll(el, selector)
-    .map((img) => (img as HTMLImageElement).getAttribute('src') ?? '')
-    .filter(Boolean);
-}
-
-/**
- * The last index the virtualizer has rendered, read off the cards
- * rather than counted: the rendered range is what the prefetch window
- * is measured from, and a count assumes it starts at 0 and has no
- * gaps.
- */
-function lastRenderedIndex(el: LitElement, selector: string): number {
-  const indices = shadowAll(el, selector).map((card) =>
-    Number(card.getAttribute('data-index')),
-  );
-
-  return Math.max(...indices);
-}
-
-/**
- * The tier the cards chose, read off a rendered card rather than
- * recomputed — the point of the assertion is that the prefetch and the
- * card agree, so deriving both from the same ladder here would prove
- * nothing.
- */
-function tierSuffix(src: string): string {
-  const m = /_(sm|md|lg)\.jpg$/.exec(src);
-
-  return m ? `_${m[1]}` : '';
-}
-
-beforeEach(() => {
-  resetHarness();
-  resetImagePrefetch();
-  localStorage.clear();
-  stub('library.Library.GetAlbums', ALBUMS);
-  stub('library.Library.GetArtists', ARTISTS);
-  stub('library.Library.GetTracks', []);
-  stub('library.Library.GetGenres', []);
-  emit(Events.LibraryScanComplete);
-});
-
-describe('the albums grid warms the covers below the fold', () => {
-  it('asks for the covers past the rendered range, in the tier the card draws', async () => {
-    const el = await fixture<LitElement>('cover-grid');
-
-    sized(el);
-    await settle(el);
-
-    const rendered = renderedSources(el, 'img.cover-image');
-
-    expect(rendered.length).toBeGreaterThan(0);
-
-    const tier = tierSuffix(rendered[0]!);
-    const url = (index: number) =>
-      `/covers/${String(index + 1).padStart(4, '0')}${tier}.jpg`;
-
-    // The grid starts at the top and never scrolls here, so the whole
-    // window lies past the last card drawn.
-    const last = lastRenderedIndex(el, '.album-card');
-
-    expect(imagePrefetched(url(last + 1))).toBe(true);
-    expect(imagePrefetched(url(last + PREFETCH_AHEAD))).toBe(true);
-  });
-
-  it('stops at the end of the window rather than warming the library', async () => {
-    const el = await fixture<LitElement>('cover-grid');
-
-    sized(el);
-    await settle(el);
-
-    const rendered = renderedSources(el, 'img.cover-image');
-    const tier = tierSuffix(rendered[0]!);
-    const url = (index: number) =>
-      `/covers/${String(index + 1).padStart(4, '0')}${tier}.jpg`;
-
-    // Not "exactly `last + PREFETCH_AHEAD`": the grid lays out more
-    // than once on mount and each pass warms a window from wherever
-    // the rendered range was then, so the reachable set is a few
-    // windows wide. The property that matters is that it is a window
-    // at all rather than the library.
-    expect(imagePrefetched(url(399))).toBe(false);
-    expect(window.__yjCacheStats?.()['imagePrefetch']?.entries ?? 0)
-      .toBeLessThan(ALBUMS.length / 2);
-  });
-});
-
-describe('the artists grid warms its avatars the same way', () => {
-  it('asks for the avatars past the rendered range', async () => {
-    const el = await fixture<LitElement>('artists-view');
-
-    sized(el);
-    await settle(el);
-
-    const rendered = renderedSources(el, 'img.avatar-image');
-
-    expect(rendered.length).toBeGreaterThan(0);
-
-    const tier = tierSuffix(rendered[0]!);
-    const last = lastRenderedIndex(el, '.artist-card');
-    const url = (index: number) =>
-      `/artists/${String(index + 1).padStart(4, '0')}${tier}.jpg`;
-
-    expect(imagePrefetched(url(last + 1))).toBe(true);
-    expect(imagePrefetched(url(399))).toBe(false);
-  });
-});

frontend/test/support/pixel.svg

@@ -1,2 +0,0 @@
-<!-- A real, servable image for the prefetch tests: one transparent pixel. -->
-<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"></svg>

frontend/test/utils/image-prefetch.test.ts

@@ -1,113 +0,0 @@
-/**
- * What the grids ask for ahead of the scroll (#65).
- *
- * The virtualizer renders about 1000px past its viewport and nothing
- * else can be asked for, because the `<img>` does not exist until the
- * card does — two screens on the reference device, which is a fraction
- * of a second at speed. `prefetchImageWindow` issues the request
- * before the element, so the assertions here are about *which* rows
- * are asked for, that none is asked for twice, and that a request is
- * really made rather than merely recorded.
- */
-import { describe, expect, it, beforeEach } from 'vitest';
-
-import {
-  PREFETCH_MEMORY,
-  imagePrefetched,
-  prefetchImage,
-  prefetchImageWindow,
-  resetImagePrefetch,
-} from '@utils/image-prefetch';
-
-/** A hundred cards, each with its own cover URL. */
-const CARDS = Array.from({ length: 100 }, (_, i) => ({ url: `/covers/${i}_sm.jpg` }));
-
-const urlOf = (card: { url: string }) => card.url;
-
-beforeEach(() => {
-  resetImagePrefetch();
-});
-
-describe('warming the images a scroll is about to reach', () => {
-  it('asks for the rows just past the rendered range, and no further', () => {
-    const issued = prefetchImageWindow(CARDS, 40, 50, urlOf, 3);
-
-    // Three past each edge: 51-53 and 37-39.
-    expect(issued).toBe(6);
-    expect(imagePrefetched('/covers/51_sm.jpg')).toBe(true);
-    expect(imagePrefetched('/covers/53_sm.jpg')).toBe(true);
-    expect(imagePrefetched('/covers/54_sm.jpg')).toBe(false);
-    expect(imagePrefetched('/covers/39_sm.jpg')).toBe(true);
-    expect(imagePrefetched('/covers/37_sm.jpg')).toBe(true);
-    expect(imagePrefetched('/covers/36_sm.jpg')).toBe(false);
-  });
-
-  it('leaves the rendered rows alone — they have their own <img>', () => {
-    prefetchImageWindow(CARDS, 40, 50, urlOf, 3);
-
-    expect(imagePrefetched('/covers/45_sm.jpg')).toBe(false);
-  });
-
-  it('asks for nothing twice, so a scroll back over the same rows is free', () => {
-    prefetchImageWindow(CARDS, 40, 50, urlOf, 3);
-
-    expect(prefetchImageWindow(CARDS, 40, 50, urlOf, 3)).toBe(0);
-  });
-
-  it('clamps at both ends of the list', () => {
-    // At the top of a five-item list nothing precedes the range, and
-    // the tail runs out after two.
-    expect(prefetchImageWindow(CARDS.slice(0, 5), 0, 2, urlOf, 10)).toBe(2);
-  });
-
-  it('asks for nothing when the virtualizer reports an empty range', () => {
-    // `visibilityChanged` reports -1/-1 before anything is laid out.
-    expect(prefetchImageWindow(CARDS, -1, -1, urlOf)).toBe(0);
-  });
-
-  it('skips a card that draws a placeholder rather than an image', () => {
-    expect(prefetchImageWindow(CARDS, 40, 50, () => '', 3)).toBe(0);
-  });
-
-  it('really issues the request, rather than only recording it', async () => {
-    // A served file, so the load succeeds and the resource timing entry
-    // is unambiguous; the query string keeps it distinct per run.
-    const url = `/test/support/pixel.svg?prefetch=${Date.now()}`;
-    const href = new URL(url, location.href).href;
-
-    expect(prefetchImage(url)).toBe(true);
-
-    for (let i = 0; i < 100; i++) {
-      if (performance.getEntriesByName(href).length > 0) break;
-
-      await new Promise((r) => setTimeout(r, 20));
-    }
-
-    expect(performance.getEntriesByName(href)).toHaveLength(1);
-    expect(prefetchImage(url)).toBe(false);
-    expect(performance.getEntriesByName(href)).toHaveLength(1);
-  });
-
-  it('reports what it is holding, with its cap, to the cache stats', () => {
-    prefetchImageWindow(CARDS, 40, 50, urlOf, 3);
-
-    const stat = window.__yjCacheStats?.()['imagePrefetch'];
-
-    expect(stat).toBeTruthy();
-    expect(stat!.entries).toBe(6);
-    expect(stat!.limit).toBe(PREFETCH_MEMORY);
-    // It holds URLs, not images — the bytes are the browser's cache.
-    expect(stat!.chars).toBe(6 * '/covers/51_sm.jpg'.length);
-  });
-
-  it('keeps its record bounded, so a 50 000-album scroll cannot grow it', () => {
-    const many = Array.from(
-      { length: PREFETCH_MEMORY * 2 },
-      (_, i) => ({ url: `/covers/bulk-${i}_sm.jpg` }),
-    );
-
-    prefetchImageWindow(many, 0, 0, urlOf, many.length);
-
-    expect(window.__yjCacheStats?.()['imagePrefetch']?.entries).toBe(PREFETCH_MEMORY);
-  });
-});

internal/testfixtures/fixtures_test.go

@@ -30,12 +30,6 @@ func TestFixturesMatchManifest(t *testing.T) {
 	m := testfixtures.Load(t)
 
 	for _, want := range m.Tracks {
-		// WAV tags are write-only today; see
-		// TestWAVTagsAreNotReadableYet.
-		if want.Format == "wav" {
-			continue
-		}
-
 		t.Run(want.Path, func(t *testing.T) {
 			t.Parallel()
 
@@ -161,39 +155,6 @@ func TestDuplicateFixturesAreIndistinguishable(t *testing.T) {
 	}
 }
 
-// TestWAVTagsAreNotReadableYet pins a known gap rather than hiding it.
-//
-// backend/tagwriter writes WAV tags into a RIFF "id3 " chunk, but
-// backend/metadata reads through dhowden/tag, which recognises MP3,
-// FLAC, OGG, MP4 and DSF and has no RIFF parser at all.  So every tag
-// the app writes to a WAV is invisible to the app that wrote it, and
-// WAV tracks always scan in as untitled.
-//
-// The fixtures are tagged correctly on disk, so when the reader learns
-// to unwrap the RIFF chunk this test starts failing — which is the
-// point.  Delete it then and drop the "wav" skip in
-// TestFixturesMatchManifest.
-func TestWAVTagsAreNotReadableYet(t *testing.T) {
-	t.Parallel()
-
-	m := testfixtures.Load(t)
-
-	for _, path := range m.Case(t, testfixtures.CaseWAVTracks) {
-		got, err := metadata.ExtractTags(path)
-		if err != nil {
-			t.Fatalf("extract tags from %s: %v", path, err)
-		}
-
-		if got.Title != "" {
-			t.Errorf(
-				"%s: WAV tags are now readable (%q) — good news; "+
-					"see this test's comment for what to update",
-				filepath.Base(path), got.Title,
-			)
-		}
-	}
-}
-
 func assertTag(t *testing.T, field string, want testfixtures.Track, got string) {
 	t.Helper()