perf(library): send the track list as a dictionary-encoded column table

GetTracks answered with one JSON object per track: 20.5 MB at 26k
tracks, ~350 bytes a row of repeated key names, four cover URLs that
are identical across an album, and the album, artist and genre strings
repeated on every track. Encoding it was ~170 MB of transient Go
allocation, and parsing it the WebView's memory peak.

GetTrackTable replaces it: one array per column, every repeated
string stored once and sent as an index, genre lists interned, and only
the fields the Tracks view reads. LastPlayed and the three larger cover
tiers are left to the details dialog, which now fetches whole tracks by
path. Each row still goes through trackFromRow, so this is an encoding
of the one projection, not a second one. 167 bytes a track against 929
in the test library; a Go test holds it under a quarter of the object
encoding, and a Vitest test reads the Go columns and the generated
Track interface and fails if they drift.

An empty library is now an empty table rather than the "no tracks in
library" error the old binding returned.

Closes #281

.pi/skills/yellowjacket-dev/references/android-tier.md

@@ -647,7 +647,7 @@ window.__yj = { call(name, args) {
 That turns the device into a tier that can be *driven* rather than only
 looked at — `__yj.call("player.Player.LoadFile", [path])` and
 `__yj.call("library.Library.AddLibrary", ["/sdcard/Music/..."])` are how
-#53 was measured. Names are the Go ones (`GetTracks`, not
+#53 was measured. Names are the Go ones (`GetTrackTable`, not
 `GetAllTracks`); an unknown one comes back as a plain
 `unknown bound method name`, so a wrong guess is loud.
 

backend/library/query.go

@@ -2,7 +2,6 @@ package library
 
 import (
 	"database/sql"
-	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -18,8 +17,6 @@ import (
 // searchTrackLimit bounds an FTS search's result set.
 const searchTrackLimit = 500
 
-var errNoTracksInLibrary = errors.New("no tracks in library")
-
 // Track is one audio file with everything a list needs to draw it.
 type Track struct {
 	TrackName        string
@@ -169,30 +166,6 @@ func (l *Library) GetTrackMBIDs(filePath string) TrackMBIDs {
 	}
 }
 
-// GetTracks returns every track in a library, or in all of them when
-// libraryID is 0.
-//
-// The library id is a parameter rather than a second method because the
-// two used to be separate queries, separate bindings and a branch at
-// every call site - and the scoped form costs nothing (measured: 23 ms
-// against 21 ms over 26k rows).
-func (l *Library) GetTracks(libraryID int64) ([]Track, error) {
-	rows, err := l.db.ReadQueries.GetTracks(l.ctx, libraryID)
-	if err != nil {
-		l.logger.Error("could not retrieve audio files", "error", err)
-
-		return nil, fmt.Errorf("could not get tracks: %w", err)
-	}
-
-	l.logger.Info("audio file list", "count", len(rows), "libraryID", libraryID)
-
-	if len(rows) == 0 {
-		return nil, errNoTracksInLibrary
-	}
-
-	return tracksFromRows(rows), nil
-}
-
 // pathLookupChunk bounds the paths bound into one IN (...) query, well
 // under SQLite's bind-variable limit.
 const pathLookupChunk = 500

backend/library/scan_fixtures_test.go

@@ -58,15 +58,15 @@ func TestScan_FixtureLibraryLeavesNothingBehind(t *testing.T) {
 		t.Skip("fixture library is empty; run make testdata")
 	}
 
-	tracks, err := lib.GetTracks(0)
+	table, err := lib.GetTrackTable(0)
 	if err != nil {
-		t.Fatalf("GetTracks: %v", err)
+		t.Fatalf("GetTrackTable: %v", err)
 	}
 
 	// One track per file: the projection cannot multiply rows, because
 	// there is no join table left to multiply them.
-	if int64(len(tracks)) != files {
-		t.Errorf("GetTracks returned %d rows for %d files", len(tracks), files)
+	if int64(len(table.FilePath)) != files {
+		t.Errorf("GetTrackTable returned %d rows for %d files", len(table.FilePath), files)
 	}
 
 	// Nothing shared outlives what refers to it.

backend/library/tracktable.go

@@ -0,0 +1,190 @@
+package library
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// TrackTable is every track in a library as the Tracks view uses it:
+// one array per column, and every repeated string stored once (#281).
+//
+// GetTracks used to answer with one object per track, which at 26 138
+// tracks was 20.5 MB of JSON — ~350 bytes a row of key names, four
+// cover URLs identical across an album, and artist, album and genre
+// strings repeated on every track of the album.  Encoding it cost the
+// backend ~170 MB of transient allocation and parsing it was the
+// WebView's peak.  Here the keys appear once, a repeated string is a
+// small integer, and the columns the Tracks view does not read are not
+// sent at all: LastPlayed and the three larger cover tiers belong to
+// the details dialog, which fetches whole tracks by path.
+//
+// The projection is still trackFromRow's — each row goes through it —
+// so this is an encoding of a Track, never a second description of
+// one.  frontend/src/utils/track-table.ts is the only decoder.
+type TrackTable struct {
+	// Strings holds every distinct string value; a string column holds
+	// indexes into it.  Index 0 is always "".
+	Strings []string `json:"strings"`
+	// GenreSets holds every distinct genre list, as indexes into
+	// Strings; Genre holds an index into it per track.
+	GenreSets [][]uint32 `json:"genreSets"`
+
+	FilePath         []string `json:"filePath"`
+	TrackName        []uint32 `json:"trackName"`
+	ArtistName       []uint32 `json:"artistName"`
+	Album            []uint32 `json:"album"`
+	Composer         []uint32 `json:"composer"`
+	FileType         []uint32 `json:"fileType"`
+	Genre            []uint32 `json:"genre"`
+	ArtistMBID       []uint32 `json:"artistMbid"`
+	ReleaseGroupMBID []uint32 `json:"releaseGroupMbid"`
+	RecordingMBID    []uint32 `json:"recordingMbid"`
+	CoverArtSmall    []uint32 `json:"coverArtSmall"`
+
+	// LengthMs is Track.TrackLength as the number it encodes.
+	LengthMs    []int64 `json:"lengthMs"`
+	TrackNumber []int64 `json:"trackNumber"`
+	DiscNumber  []int64 `json:"discNumber"`
+	Year        []int64 `json:"year"`
+	SampleRate  []int64 `json:"sampleRate"`
+	BitDepth    []int64 `json:"bitDepth"`
+	Channels    []int64 `json:"channels"`
+	Bitrate     []int64 `json:"bitrate"`
+	FileSize    []int64 `json:"fileSize"`
+	PlayCount   []int64 `json:"playCount"`
+}
+
+// trackTableBuilder interns strings and genre lists while rows are
+// appended.
+type trackTableBuilder struct {
+	table   TrackTable
+	strings map[string]uint32
+	genres  map[string]uint32
+}
+
+func newTrackTableBuilder(capacity int) *trackTableBuilder {
+	b := &trackTableBuilder{
+		strings: map[string]uint32{"": 0},
+		genres:  map[string]uint32{},
+	}
+
+	t := &b.table
+	t.Strings = []string{""}
+	t.FilePath = make([]string, 0, capacity)
+
+	for _, col := range b.stringColumns() {
+		*col = make([]uint32, 0, capacity)
+	}
+
+	for _, col := range b.intColumns() {
+		*col = make([]int64, 0, capacity)
+	}
+
+	t.Genre = make([]uint32, 0, capacity)
+
+	return b
+}
+
+// stringColumns are the interned columns, in one place so the builder
+// cannot allocate one and forget to fill it.
+func (b *trackTableBuilder) stringColumns() []*[]uint32 {
+	t := &b.table
+
+	return []*[]uint32{
+		&t.TrackName, &t.ArtistName, &t.Album, &t.Composer, &t.FileType,
+		&t.ArtistMBID, &t.ReleaseGroupMBID, &t.RecordingMBID, &t.CoverArtSmall,
+	}
+}
+
+func (b *trackTableBuilder) intColumns() []*[]int64 {
+	t := &b.table
+
+	return []*[]int64{
+		&t.LengthMs, &t.TrackNumber, &t.DiscNumber, &t.Year, &t.SampleRate,
+		&t.BitDepth, &t.Channels, &t.Bitrate, &t.FileSize, &t.PlayCount,
+	}
+}
+
+func (b *trackTableBuilder) intern(s string) uint32 {
+	if i, ok := b.strings[s]; ok {
+		return i
+	}
+
+	i := uint32(len(b.table.Strings)) //nolint:gosec // bounded by the row count
+
+	b.table.Strings = append(b.table.Strings, s)
+	b.strings[s] = i
+
+	return i
+}
+
+func (b *trackTableBuilder) internGenres(genres []string) uint32 {
+	key := strings.Join(genres, genreDelimiter)
+
+	if i, ok := b.genres[key]; ok {
+		return i
+	}
+
+	set := make([]uint32, len(genres))
+	for j, g := range genres {
+		set[j] = b.intern(g)
+	}
+
+	i := uint32(len(b.table.GenreSets)) //nolint:gosec // bounded by the row count
+
+	b.table.GenreSets = append(b.table.GenreSets, set)
+	b.genres[key] = i
+
+	return i
+}
+
+func (b *trackTableBuilder) add(tr Track) error {
+	lengthMs, err := strconv.ParseInt(tr.TrackLength, 10, 64)
+	if err != nil {
+		return fmt.Errorf("track %q length %q: %w", tr.FilePath, tr.TrackLength, err)
+	}
+
+	t := &b.table
+	t.FilePath = append(t.FilePath, tr.FilePath)
+
+	strs := []string{
+		tr.TrackName, tr.ArtistName, tr.Album, tr.Composer, tr.FileType,
+		tr.ArtistMBID, tr.ReleaseGroupMBID, tr.RecordingMBID, tr.CoverArtSmall,
+	}
+	for i, col := range b.stringColumns() {
+		*col = append(*col, b.intern(strs[i]))
+	}
+
+	ints := []int64{
+		lengthMs, tr.TrackNumber, tr.DiscNumber, tr.Year, tr.SampleRate,
+		tr.BitDepth, tr.Channels, tr.Bitrate, tr.FileSize, tr.PlayCount,
+	}
+	for i, col := range b.intColumns() {
+		*col = append(*col, ints[i])
+	}
+
+	t.Genre = append(t.Genre, b.internGenres(tr.Genre))
+
+	return nil
+}
+
+// GetTrackTable returns every track in a library, or in all of them
+// when libraryID is 0, as a TrackTable.  An empty library is an empty
+// table, not an error.
+func (l *Library) GetTrackTable(libraryID int64) (TrackTable, error) {
+	rows, err := l.db.ReadQueries.GetTracks(l.ctx, libraryID)
+	if err != nil {
+		return TrackTable{}, fmt.Errorf("could not get tracks: %w", err)
+	}
+
+	b := newTrackTableBuilder(len(rows))
+
+	for i := range rows {
+		if err := b.add(trackFromRow(rows[i])); err != nil {
+			return TrackTable{}, err
+		}
+	}
+
+	return b.table, nil
+}

backend/library/tracktable_test.go

@@ -0,0 +1,198 @@
+package library
+
+import (
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"testing"
+
+	"yellowjacket/backend/database"
+)
+
+// seedTableLibrary seeds n albums of perAlbum tracks each, with a cover
+// on every album, so the table has the repetition it exists to remove.
+func seedTableLibrary(t *testing.T, lib *Library, albums, perAlbum int) {
+	t.Helper()
+
+	for a := range albums {
+		for n := range perAlbum {
+			database.InsertTestTrack(t, lib.db, database.TestTrack{
+				FilePath: fmt.Sprintf(
+					"/music/artist-%d/album-%d/%02d - Some Track Title.flac", a%7, a, n+1,
+				),
+				Title:         fmt.Sprintf("Some Track Title %d", n+1),
+				Artist:        fmt.Sprintf("Artist %d", a%7),
+				ArtistMBID:    fmt.Sprintf("0b7a8d2e-0000-4000-8000-%012d", a%7),
+				Album:         fmt.Sprintf("Album Name %d", a),
+				AlbumMBID:     fmt.Sprintf("1c7a8d2e-0000-4000-8000-%012d", a),
+				RecordingMBID: fmt.Sprintf("2d7a8d2e-0000-4000-8000-%012d", a*100+n),
+				Genres:        []string{"Ambient", fmt.Sprintf("Genre %d", a%3)},
+				TrackNumber:   int64(n + 1),
+				DiscNumber:    1,
+				Year:          2000 + int64(a%20),
+				LengthMs:      200_000 + int64(n),
+				PlayCount:     int64(n),
+			})
+		}
+
+		res, err := lib.db.ExecContext(
+			"INSERT INTO cover_art (file_path, mime_type) VALUES (?, 'image/jpeg')",
+			fmt.Sprintf("/data/covers/%064d.jpg", a),
+		)
+		if err != nil {
+			t.Fatalf("seed cover: %v", err)
+		}
+
+		coverID, _ := res.LastInsertId()
+
+		if _, err := lib.db.ExecContext(
+			"UPDATE albums SET cover_art_id = ? WHERE name = ?",
+			coverID, fmt.Sprintf("Album Name %d", a),
+		); err != nil {
+			t.Fatalf("seed album cover: %v", err)
+		}
+	}
+}
+
+// decodeTable is the Go mirror of frontend/src/utils/track-table.ts,
+// for asserting the encoding loses nothing it claims to carry.
+func decodeTable(t *testing.T, tbl TrackTable) []Track {
+	t.Helper()
+
+	str := func(col []uint32, i int) string { return tbl.Strings[col[i]] }
+	tracks := make([]Track, len(tbl.FilePath))
+
+	for i := range tracks {
+		var genres []string
+		for _, g := range tbl.GenreSets[tbl.Genre[i]] {
+			genres = append(genres, tbl.Strings[g])
+		}
+
+		tracks[i] = Track{
+			FilePath:         tbl.FilePath[i],
+			TrackName:        str(tbl.TrackName, i),
+			ArtistName:       str(tbl.ArtistName, i),
+			Album:            str(tbl.Album, i),
+			Composer:         str(tbl.Composer, i),
+			FileType:         str(tbl.FileType, i),
+			ArtistMBID:       str(tbl.ArtistMBID, i),
+			ReleaseGroupMBID: str(tbl.ReleaseGroupMBID, i),
+			RecordingMBID:    str(tbl.RecordingMBID, i),
+			CoverArtSmall:    str(tbl.CoverArtSmall, i),
+			Genre:            genres,
+			TrackLength:      strconv.FormatInt(tbl.LengthMs[i], 10),
+			TrackNumber:      tbl.TrackNumber[i],
+			DiscNumber:       tbl.DiscNumber[i],
+			Year:             tbl.Year[i],
+			SampleRate:       tbl.SampleRate[i],
+			BitDepth:         tbl.BitDepth[i],
+			Channels:         tbl.Channels[i],
+			Bitrate:          tbl.Bitrate[i],
+			FileSize:         tbl.FileSize[i],
+			PlayCount:        tbl.PlayCount[i],
+		}
+	}
+
+	return tracks
+}
+
+// #281: the table is an encoding of trackFromRow's Track, minus the
+// fields the Tracks view does not read.  Decoding it must give back
+// exactly that, row for row.
+func TestTrackTableRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+	seedTableLibrary(t, lib, 6, 4)
+
+	tbl, err := lib.GetTrackTable(0)
+	if err != nil {
+		t.Fatalf("GetTrackTable: %v", err)
+	}
+
+	rows, err := lib.db.ReadQueries.GetTracks(lib.ctx, 0)
+	if err != nil {
+		t.Fatalf("GetTracks: %v", err)
+	}
+
+	if len(rows) != 24 || len(tbl.FilePath) != len(rows) {
+		t.Fatalf("table has %d rows, query %d, want 24", len(tbl.FilePath), len(rows))
+	}
+
+	got := decodeTable(t, tbl)
+
+	for i, row := range rows {
+		want := trackFromRow(row)
+		// Not carried: the details dialog fetches these by path.
+		want.LastPlayed, want.CoverArtPath, want.CoverArtMedium, want.CoverArtLarge = "", "", "", ""
+
+		if fmt.Sprintf("%+v", got[i]) != fmt.Sprintf("%+v", want) {
+			t.Fatalf("row %d:\n got %+v\nwant %+v", i, got[i], want)
+		}
+	}
+
+	// It was the cover, genre and name repetition that was paid for; a
+	// table that interned nothing would still round-trip.
+	if len(tbl.GenreSets) != 3 {
+		t.Errorf("genre sets = %d, want 3 distinct lists", len(tbl.GenreSets))
+	}
+
+	if a, b := tbl.CoverArtSmall[0], tbl.CoverArtSmall[1]; a != b || tbl.Strings[a] == "" {
+		t.Errorf("two tracks of one album hold cover indexes %d and %d", a, b)
+	}
+}
+
+// The point of the table, pinned: the same rows encode to a fraction of
+// the object-per-track JSON they replace.  A new column has to fit
+// under this or raise it on purpose.
+func TestTrackTableSizeBudget(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+	seedTableLibrary(t, lib, 40, 10)
+
+	tbl, err := lib.GetTrackTable(0)
+	if err != nil {
+		t.Fatalf("GetTrackTable: %v", err)
+	}
+
+	rows, err := lib.db.ReadQueries.GetTracks(lib.ctx, 0)
+	if err != nil {
+		t.Fatalf("GetTracks: %v", err)
+	}
+
+	asTable, err := json.Marshal(tbl)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	asObjects, err := json.Marshal(tracksFromRows(rows))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	perTrack := len(asTable) / len(rows)
+	ratio := float64(len(asTable)) / float64(len(asObjects))
+
+	t.Logf("table %d B (%d B/track), objects %d B, ratio %.2f",
+		len(asTable), perTrack, len(asObjects), ratio)
+
+	if ratio > 0.25 {
+		t.Errorf("table is %.0f%% of the object encoding, budget 25%%", ratio*100)
+	}
+}
+
+func TestTrackTableEmptyLibraryIsAnAnswer(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	tbl, err := lib.GetTrackTable(0)
+	if err != nil {
+		t.Fatalf("an empty library is an empty table, not an error: %v", err)
+	}
+
+	if len(tbl.FilePath) != 0 || len(tbl.Strings) != 1 {
+		t.Errorf("empty table = %+v", tbl)
+	}
+}

e2e/perf/measure.mjs

@@ -224,7 +224,13 @@ async function measureStartup(page) {
 			scriptBytesBeforePaint,
 			requests: res.length,
 			crossOriginRequests: crossOrigin.length,
-			crossOriginHosts: [...new Set(crossOrigin.map((u) => new URL(u).host))],
+			crossOriginHosts: [...new Set(crossOrigin.map((u) => {
+				try {
+					return new URL(u).host;
+				} catch {
+					return u;
+				}
+			}))],
 		};
 	});
 
@@ -337,7 +343,8 @@ async function measureTrackChange(page) {
 
 		await ev.call('queue.Queue.Clear', [], 10000).catch(() => {});
 
-		const tracks = await ev.call('library.Library.GetAllTracks', [], 60000);
+		// The columnar list (#281): only the paths are needed here.
+		const tracks = ((await ev.call('library.Library.GetTrackTable', [0], 60000))?.filePath ?? []).map((FilePath) => ({ FilePath }));
 		const paths = (tracks ?? []).slice(0, 4).map((t) => t.FilePath);
 		if (paths.length < 2) return { error: 'library too small to measure' };
 
@@ -435,7 +442,8 @@ async function measureFavouriteToggle(page) {
 		const ev = window.__yjEvents;
 		const perf = window.__yjPerf;
 
-		const tracks = await ev.call('library.Library.GetAllTracks', [], 60000);
+		// The columnar list (#281): only the paths are needed here.
+		const tracks = ((await ev.call('library.Library.GetTrackTable', [0], 60000))?.filePath ?? []).map((FilePath) => ({ FilePath }));
 		const paths = (tracks ?? []).map((t) => t.FilePath);
 		if (paths.length < per * count) {
 			return { error: `library too small: ${paths.length} tracks` };
@@ -671,7 +679,8 @@ async function measurePlaylistOpen(page, client) {
 		let pl = (existing ?? []).find((p) => (p.Name ?? p.name) === name);
 
 		if (!pl) {
-			const tracks = await ev.call('library.Library.GetAllTracks', [], 60000);
+			// The columnar list (#281): only the paths are needed here.
+		const tracks = ((await ev.call('library.Library.GetTrackTable', [0], 60000))?.filePath ?? []).map((FilePath) => ({ FilePath }));
 			const paths = (tracks ?? []).map((t) => t.FilePath);
 
 			if (paths.length < n) return { error: `library too small: ${paths.length}` };
@@ -1600,7 +1609,8 @@ async function measurePlayerBarPass(page) {
 		// Stage a loaded track.  Deliberately the same first tracks the
 		// track-change measurement already played, so this warms no cover
 		// art that a later measurement counts requests for.
-		const tracks = await ev.call('library.Library.GetAllTracks', [], 60000);
+		// The columnar list (#281): only the paths are needed here.
+		const tracks = ((await ev.call('library.Library.GetTrackTable', [0], 60000))?.filePath ?? []).map((FilePath) => ({ FilePath }));
 		const paths = (tracks ?? []).slice(0, 4).map((t) => t.FilePath);
 
 		if (paths.length < 2) return { error: 'library too small to measure' };
@@ -2000,7 +2010,11 @@ function compare(a, b) {
 		const p = resolve(OUT_DIR, `${l}.json`);
 		if (!existsSync(p)) throw new Error(`no measurement labelled '${l}' at ${p}`);
 
-		return JSON.parse(readFileSync(p, 'utf8'));
+		try {
+			return JSON.parse(readFileSync(p, 'utf8'));
+		} catch (err) {
+			throw new Error(`measurement '${l}' at ${p} is not valid JSON: ${err.message}`);
+		}
 	};
 
 	console.log(table([load(a), load(b)]));

e2e/specs/phone-now-playing.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, libraryTracks } from '../support/fixtures.js';
 
 /**
  * Now Playing on a short screen (#51).
@@ -57,19 +57,15 @@ const REFLOW_AT = 500;
 
 /** Put a track in the player, so the view has art and names to lay out. */
 async function stageATrack(page: Page): Promise<void> {
-  await page.evaluate(async () => {
-    const tracks = (await window.__yjEvents.call(
-      'library.Library.GetTracks',
-      [0],
-      10_000,
-    )) as { FilePath: string }[];
+  const paths = (await libraryTracks(page)).slice(0, 4).map((t) => t.FilePath);
 
+  await page.evaluate(async (paths) => {
     await window.__yjEvents.call(
       'queue.Queue.SetQueue',
-      [tracks.slice(0, 4).map((t) => t.FilePath), 0, false, { type: '', id: 0, label: '' }],
+      [paths, 0, false, { type: '', id: 0, label: '' }],
       10_000,
     );
-  });
+  }, paths);
 }
 
 /** Open the full-screen view and wait for the shell to say so. */

e2e/specs/phone-progress-line.spec.ts

@@ -1,4 +1,5 @@
 import {
+  libraryTracks,
   test,
   expect,
   callBinding,
@@ -49,11 +50,7 @@ async function rectOf(app: Page, selector: string): Promise<Rect | null> {
  * three rectangles.
  */
 async function play(app: Page): Promise<void> {
-  const tracks = await callBinding<{ FilePath: string; TrackName: string }[]>(
-    app,
-    'library.Library.GetTracks',
-    [0],
-  );
+  const tracks = await libraryTracks(app);
 
   // `TrackName`, not `Title`: that is what the library model calls it.
   const long = tracks.find((t) => t.TrackName === LONG_TRACK);

e2e/specs/phone-shell.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect, LONG_TRACK } from '../support/fixtures.js';
+import { test, expect, LONG_TRACK, libraryTracks } from '../support/fixtures.js';
 
 /**
  * The phone shell (plan 016 B2, phase 1).
@@ -235,15 +235,8 @@ test.describe('the shell on a phone', () => {
     // nothing in particular and picked a 2-second track, which had
     // finished before the assertions ran. The placeholder check below
     // is what actually holds the property this test needs.
-    const started = await app.evaluate(async (longTitle) => {
-      const tracks = (await window.__yjEvents.call(
-        'library.Library.GetTracks',
-        [0],
-        10_000,
-      )) as { FilePath: string; TrackName: string }[];
-
-      const bare = tracks.find((t) => t.TrackName === longTitle);
-
+    const bare = (await libraryTracks(app)).find((t) => t.TrackName === LONG_TRACK);
+    const started = await app.evaluate(async (bare) => {
       if (!bare) return null;
 
       await window.__yjEvents.call(
@@ -254,7 +247,7 @@ test.describe('the shell on a phone', () => {
       await window.__yjEvents.call('queue.Queue.Play', [], 5_000);
 
       return bare.TrackName;
-    }, LONG_TRACK);
+    }, bare);
 
     expect(started).toBe(LONG_TRACK);
 

e2e/specs/queue-reorder.spec.ts

@@ -1,4 +1,5 @@
 import {
+  libraryTracks,
   test,
   expect,
   callBinding,
@@ -30,18 +31,7 @@ async function order(app: Page): Promise<string[]> {
 }
 
 async function queueFourAndOpen(app: Page): Promise<string[]> {
-  const paths: string[] = await app.evaluate(async () => {
-    // One argument, and 0 means every library: the scoped and
-    // unscoped list queries collapsed into one when the schema did
-    // (plan 013 R3), so `GetTracks()` no longer exists to call.
-    const tracks = await window.__yjEvents.call(
-      'library.Library.GetTracks',
-      [0],
-      10_000,
-    );
-
-    return (tracks as { FilePath: string }[]).slice(0, 4).map((t) => t.FilePath);
-  });
+  const paths = (await libraryTracks(app)).slice(0, 4).map((t) => t.FilePath);
 
   await callBinding(app, 'queue.Queue.SetQueue', [paths, 0, false, NO_QUEUE_SOURCE]);
 

e2e/specs/queue-selection.spec.ts

@@ -1,4 +1,5 @@
 import {
+  libraryTracks,
   test,
   expect,
   callBinding,
@@ -86,15 +87,11 @@ const selected = (app: Page) =>
  * is read back.
  */
 async function queueSixAndOpen(app: Page): Promise<void> {
-  const paths = await app.evaluate(async (longTitle) => {
-    // `TrackName`, not `Title`: the library model names it after the
-    // tag, and the *queue* is what calls it `title`.
-    const tracks = (await window.__yjEvents.call(
-      'library.Library.GetTracks',
-      [0],
-      10_000,
-    )) as { FilePath: string; TrackName: string; Album: string }[];
-
+  // `TrackName`, not `Title`: the library model names it after the
+  // tag, and the *queue* is what calls it `title`.
+  const tracks = await libraryTracks(app);
+  const longTitle = LONG_TRACK;
+  const paths = (() => {
     const long = tracks.find((t) => t.TrackName === longTitle);
 
     /**
@@ -131,7 +128,7 @@ async function queueSixAndOpen(app: Page): Promise<void> {
       long!.FilePath,
       ...rest.slice(3).map((t) => t.FilePath),
     ];
-  }, LONG_TRACK);
+  })();
 
   await callBinding(app, 'queue.Queue.SetQueue', [
     paths,

e2e/support/fixtures.ts

@@ -96,6 +96,36 @@ export async function callBinding<T = unknown>(
   ) as Promise<T>;
 }
 
+/** A library track as the specs use it: the path and its names. */
+export interface LibraryTrack {
+  FilePath: string;
+  TrackName: string;
+  Album: string;
+}
+
+/**
+ * Every track in the library, in the order the backend lists them.
+ *
+ * The list arrives as a columnar `TrackTable` since #281 (repeated
+ * strings sent once, as indexes into `strings`), so it cannot be read
+ * as an array of tracks any more. This reads the three columns the
+ * specs use; `frontend/src/utils/track-table.ts` is the real decoder.
+ */
+export async function libraryTracks(page: Page): Promise<LibraryTrack[]> {
+  const t = await callBinding<{
+    strings: string[];
+    filePath: string[];
+    trackName: number[];
+    album: number[];
+  }>(page, 'library.Library.GetTrackTable', [0]);
+
+  return (t.filePath ?? []).map((FilePath, i) => ({
+    FilePath,
+    TrackName: t.strings[t.trackName[i]!] ?? '',
+    Album: t.strings[t.album[i]!] ?? '',
+  }));
+}
+
 /**
  * The binding calls the *app* made, newest last, as `pkg.Type.Method`.
  *

frontend/bindings/yellowjacket/backend/library/index.ts

@@ -18,5 +18,6 @@ export type {
     ScanMetrics,
     ScanWarning,
     Track,
-    TrackMBIDs
+    TrackMBIDs,
+    TrackTable
 } from "./models.js";

frontend/bindings/yellowjacket/backend/library/library.ts

@@ -203,16 +203,12 @@ export function GetTrackMBIDs(filePath: string): $CancellablePromise<$models.Tra
 }
 
 /**
- * GetTracks returns every track in a library, or in all of them when
- * libraryID is 0.
- * 
- * The library id is a parameter rather than a second method because the
- * two used to be separate queries, separate bindings and a branch at
- * every call site - and the scoped form costs nothing (measured: 23 ms
- * against 21 ms over 26k rows).
+ * GetTrackTable returns every track in a library, or in all of them
+ * when libraryID is 0, as a TrackTable.  An empty library is an empty
+ * table, not an error.
  */
-export function GetTracks(libraryID: number): $CancellablePromise<$models.Track[] | null> {
-    return $Call.ByID(933082923, libraryID);
+export function GetTrackTable(libraryID: number): $CancellablePromise<$models.TrackTable> {
+    return $Call.ByID(1179690926, libraryID);
 }
 
 /**

frontend/bindings/yellowjacket/backend/library/models.ts

@@ -239,3 +239,60 @@ export interface TrackMBIDs {
     "releaseGroupMbid": string;
     "artistMbid": string;
 }
+
+/**
+ * TrackTable is every track in a library as the Tracks view uses it:
+ * one array per column, and every repeated string stored once (#281).
+ * 
+ * GetTracks used to answer with one object per track, which at 26 138
+ * tracks was 20.5 MB of JSON — ~350 bytes a row of key names, four
+ * cover URLs identical across an album, and artist, album and genre
+ * strings repeated on every track of the album.  Encoding it cost the
+ * backend ~170 MB of transient allocation and parsing it was the
+ * WebView's peak.  Here the keys appear once, a repeated string is a
+ * small integer, and the columns the Tracks view does not read are not
+ * sent at all: LastPlayed and the three larger cover tiers belong to
+ * the details dialog, which fetches whole tracks by path.
+ * 
+ * The projection is still trackFromRow's — each row goes through it —
+ * so this is an encoding of a Track, never a second description of
+ * one.  frontend/src/utils/track-table.ts is the only decoder.
+ */
+export interface TrackTable {
+    /**
+     * Strings holds every distinct string value; a string column holds
+     * indexes into it.  Index 0 is always "".
+     */
+    "strings": string[] | null;
+
+    /**
+     * GenreSets holds every distinct genre list, as indexes into
+     * Strings; Genre holds an index into it per track.
+     */
+    "genreSets": (number[] | null)[] | null;
+    "filePath": string[] | null;
+    "trackName": number[] | null;
+    "artistName": number[] | null;
+    "album": number[] | null;
+    "composer": number[] | null;
+    "fileType": number[] | null;
+    "genre": number[] | null;
+    "artistMbid": number[] | null;
+    "releaseGroupMbid": number[] | null;
+    "recordingMbid": number[] | null;
+    "coverArtSmall": number[] | null;
+
+    /**
+     * LengthMs is Track.TrackLength as the number it encodes.
+     */
+    "lengthMs": number[] | null;
+    "trackNumber": number[] | null;
+    "discNumber": number[] | null;
+    "year": number[] | null;
+    "sampleRate": number[] | null;
+    "bitDepth": number[] | null;
+    "channels": number[] | null;
+    "bitrate": number[] | null;
+    "fileSize": number[] | null;
+    "playCount": number[] | null;
+}

frontend/src/components/track-list/columns.ts

@@ -1,4 +1,4 @@
-import type * as library from '@go/library/models.js';
+import type { ListTrack } from '@utils/track-table';
 import {
     formatSampleRate,
     formatBitDepth,
@@ -45,7 +45,7 @@ export interface ColumnDef {
      */
     configurable?: boolean;
     /** Extracts the display value from a track. */
-    accessor: (track: library.Track) => string;
+    accessor: (track: ListTrack) => string;
     /** Default CSS width (used when no saved width exists). */
     defaultWidth: string;
     /** Text alignment. Defaults to left. */
@@ -60,15 +60,15 @@ export interface ColumnDef {
      * needs it, which is why it is optional rather than a second
      * required parameter on all of them.
      */
-    renderCell?: (track: library.Track, term?: string) => unknown;
+    renderCell?: (track: ListTrack, term?: string) => unknown;
     /**
      * Comparison function for sorting two tracks by this column.
      * Returns negative if a < b, positive if a > b, zero if equal.
      * If omitted the column is not sortable.
      */
     comparator?: (
-        a: library.Track,
-        b: library.Track,
+        a: ListTrack,
+        b: ListTrack,
     ) => number;
 }
 
@@ -79,7 +79,7 @@ export const COLUMN_DEFS: Record<string, ColumnDef> = {
         label: 'Art',
         accessor: () => '',
         defaultWidth: '36px',
-        renderCell: (track: library.Track) => {
+        renderCell: (track: ListTrack) => {
             // `perf.M3`. This rendered `CoverArtPath` — the *original*
             // embedded artwork, commonly 1500×1500 and several hundred
             // kB — scaled by CSS into a 24 px box, while the 100 px
@@ -90,10 +90,10 @@ export const COLUMN_DEFS: Record<string, ColumnDef> = {
             // `cover-grid.getCoverUrl()` has picked the right tier all
             // along; this is the same rule for a much smaller box, with
             // the two attributes that keep the decode off the scroll
-            // path.
-            const src = track.CoverArtSmall
-                || track.CoverArtMedium
-                || track.CoverArtPath;
+            // path. The list carries only this tier (#281): every tier
+            // is derived from the same file, so it is set whenever any
+            // of them would be.
+            const src = track.CoverArtSmall;
 
             if (!src) return nothing;
 

frontend/src/components/track-list/search-ranking.ts

@@ -1,4 +1,4 @@
-import type * as library from '@go/library/models.js';
+import type { ListTrack } from '@utils/track-table';
 import { html } from 'lit';
 import type { TemplateResult } from 'lit';
 
@@ -99,7 +99,7 @@ function matchQuality(
  *                   fields are always included on top of these.
  */
 function scoreTrack(
-    track: library.Track,
+    track: ListTrack,
     termLower: string,
     columns: ColumnDef[],
 ): number {
@@ -147,7 +147,7 @@ function scoreTrack(
 
 /** A track paired with its relevance score. */
 export interface RankedTrack {
-    track: library.Track;
+    track: ListTrack;
     score: number;
 }
 
@@ -166,10 +166,10 @@ export interface RankedTrack {
  *          `scores` (Map of FilePath → relevance score).
  */
 export function rankTracks(
-    tracks: library.Track[],
+    tracks: ListTrack[],
     term: string,
     activeColumns: ColumnDef[],
-): { tracks: library.Track[]; scores: Map<string, number> } {
+): { tracks: ListTrack[]; scores: Map<string, number> } {
     const termLower = term.toLowerCase();
     const ranked: RankedTrack[] = [];
 
@@ -188,7 +188,7 @@ export function rankTracks(
     // Sort descending by score (highest relevance first).
     ranked.sort((a, b) => b.score - a.score);
 
-    const result: library.Track[] = [];
+    const result: ListTrack[] = [];
     const scores = new Map<string, number>();
 
     for (const r of ranked) {

frontend/src/components/track-list/track-list.ts

@@ -1,5 +1,5 @@
-import * as library from '@go/library/models.js';
-import { LitElement, html, svg, css, nothing } from 'lit';
+import type { ListTrack } from '@utils/track-table';
+import { LitElement, html, svg, css, nothing, type TemplateResult } from 'lit';
 import { designTokens } from '../../styles/tokens.css';
 import { srOnly } from '../../styles/sr-only.css';
 import {
@@ -80,11 +80,10 @@ import { describeError } from '@utils/describe-error';
 import { notificationStore } from '@store/notification-store';
 import { confirmAction } from '@components/confirm-dialog/confirm-dialog';
 import { RemoveFromLibrary } from '@go/library/library.js';
-import { loadTrackDetails } from '@utils/lazy-track-details.js';
-import { tracksByFilePath, tracksForPaths } from '@utils/track-index.js';
+import { showTrackDetailsForPath, showBatchTrackDetailsForPaths } from '@utils/track-details-opener.js';
+import { tracksByFilePath } from '@utils/track-index.js';
 import '@components/playlist-picker/playlist-picker.js';
 import type { TrackDetails } from '@components/track-details/track-details.js';
-import type { CoverArtUrls } from '@components/track-details/track-details.js';
 import {
     ICON_PLAY,
     ICON_PLAYLIST,
@@ -155,7 +154,7 @@ export class TrackList
      * parent is responsible for reloading when data changes.
      */
     @property({ type: Array, attribute: false })
-    externalTracks?: library.Track[];
+    externalTracks?: ListTrack[];
 
     /**
      * What a host embedding this list (e.g. `genre-details`) should say
@@ -199,7 +198,7 @@ export class TrackList
     private lastSearchTerm = '';
 
     /** Tracks the store's cached array reference to detect refreshes. */
-    private lastTracksRef: library.Track[] | null =
+    private lastTracksRef: ListTrack[] | null =
         null;
 
     /**
@@ -242,7 +241,7 @@ export class TrackList
     }
 
     @state()
-    private tracks: library.Track[] = [];
+    private tracks: ListTrack[] = [];
 
     @query('#context-menu')
     private contextMenuPopup!: MenuSurface;
@@ -269,16 +268,16 @@ export class TrackList
     private lastActiveTrackPath: string | null = null;
 
     // -- Memoisation caches for filtered / sorted tracks --
-    private cachedFilteredTracks: library.Track[] = [];
-    private cachedSortedTracks: library.Track[] = [];
+    private cachedFilteredTracks: ListTrack[] = [];
+    private cachedSortedTracks: ListTrack[] = [];
     private cachedRelevanceScores = new Map<
         string,
         number
     >();
-    private prevFilterTracks: library.Track[] = [];
+    private prevFilterTracks: ListTrack[] = [];
     private prevFilterTerm = '';
     private prevFilterColIds = '';
-    private prevSortFiltered: library.Track[] = [];
+    private prevSortFiltered: ListTrack[] = [];
     private prevSortField: string | null = null;
     private prevSortDir: SortDirection = 'asc';
 
@@ -523,7 +522,7 @@ export class TrackList
         }
     }
 
-    private computeFilteredTracks(): library.Track[] {
+    private computeFilteredTracks(): ListTrack[] {
         const term = this.searchCtrl.term;
 
         if (!term) {
@@ -543,7 +542,7 @@ export class TrackList
         return result.tracks;
     }
 
-    private computeSortedTracks(): library.Track[] {
+    private computeSortedTracks(): ListTrack[] {
         const tracks = this.cachedFilteredTracks;
         const hasSearch =
             this.cachedRelevanceScores.size > 0;
@@ -1734,7 +1733,7 @@ export class TrackList
      */
     private resolveTrackFromEvent(
         e: Event,
-    ): { track: library.Track; index: number } | null {
+    ): { track: ListTrack; index: number } | null {
         const row = (e.target as HTMLElement).closest(
             '.track-row',
         ) as HTMLElement | null;
@@ -1875,7 +1874,7 @@ export class TrackList
 
     private onTrackRowClick(
         e: MouseEvent,
-        track: library.Track,
+        track: ListTrack,
         index: number,
     ) {
         // Clicking is also how the keyboard's starting point is chosen:
@@ -1884,7 +1883,7 @@ export class TrackList
         this.selection.handleItemClick(e, track.FilePath, index);
     }
 
-    private onTrackRowDblClick(_track: library.Track, index: number) {
+    private onTrackRowDblClick(_track: ListTrack, index: number) {
         this.selection.clear();
         this.playFromRow(index);
     }
@@ -1925,7 +1924,7 @@ export class TrackList
         );
     }
 
-    private onTrackContextMenu(e: MouseEvent, track: library.Track) {
+    private onTrackContextMenu(e: MouseEvent, track: ListTrack) {
         e.preventDefault();
         e.stopPropagation();
 
@@ -1939,7 +1938,7 @@ export class TrackList
 
     private onTrackDragStart = (
         e: DragEvent,
-        track: library.Track,
+        track: ListTrack,
     ) => {
         // Gather file paths: all selected if this track is selected,
         // otherwise just the dragged track.
@@ -2129,74 +2128,24 @@ export class TrackList
         this.ctxMenu.close();
     }
 
+    // The list's rows do not carry what the dialog shows (#281), so
+    // the dialog gets whole tracks by path, like every other opener.
     private async openTrackDetails(filePath: string) {
-        const track = tracksByFilePath(this.tracks).get(
+        await showTrackDetailsForPath(
+            () => this.trackDetailsDialog,
             filePath,
-        );
-
-        if (!track) return;
-
-        const ready = await loadTrackDetails(
             () => void this.openTrackDetails(filePath),
         );
-
-        if (!ready) return;
-
-        const coverArt = track.CoverArtPath
-            ? {
-                coverArtPath: track.CoverArtPath,
-                coverArtSmall: track.CoverArtSmall,
-                coverArtMedium: track.CoverArtMedium,
-                coverArtLarge: track.CoverArtLarge,
-            }
-            : undefined;
-
-        this.trackDetailsDialog?.show(
-            track,
-            coverArt,
-        );
     }
 
     private async openBatchTrackDetails(
         filePaths: string[],
     ) {
-        const tracks = tracksForPaths(
-            this.tracks,
+        await showBatchTrackDetailsForPaths(
+            () => this.trackDetailsDialog,
             filePaths,
-        );
-
-        if (tracks.length === 0) return;
-
-        const ready = await loadTrackDetails(
             () => void this.openBatchTrackDetails(filePaths),
         );
-
-        if (!ready) return;
-
-        // Use cover art from the first track. If all tracks share
-        // the same album, they share the same art.
-        const first = tracks[0]!;
-        let coverArt: CoverArtUrls | null = null;
-        let coverArtMixed = false;
-
-        const albumNames = new Set(tracks.map((t) => t.Album));
-
-        if (albumNames.size === 1 && first.CoverArtPath) {
-            coverArt = {
-                coverArtPath: first.CoverArtPath,
-                coverArtSmall: first.CoverArtSmall,
-                coverArtMedium: first.CoverArtMedium,
-                coverArtLarge: first.CoverArtLarge,
-            };
-        } else if (albumNames.size > 1) {
-            coverArtMixed = true;
-        }
-
-        this.trackDetailsDialog?.showBatch(
-            tracks,
-            coverArt,
-            coverArtMixed,
-        );
     }
 
     // =================================================================
@@ -2274,7 +2223,7 @@ export class TrackList
         this.saveSortPreferences();
     }
 
-    private isActiveTrack(track: library.Track): boolean {
+    private isActiveTrack(track: ListTrack): boolean {
         const currentTrack = this.player.currentTrack;
 
         if (!currentTrack) return false;
@@ -2283,9 +2232,9 @@ export class TrackList
     }
 
     private renderTrackRow = (
-        track: library.Track,
+        track: ListTrack,
         index: number,
-    ): unknown => {
+    ): TemplateResult => {
         const active = this.isActiveTrack(track);
         const selected = this.selection.isSelected(
             track.FilePath,
@@ -2568,7 +2517,7 @@ export class TrackList
                         scroller
                         .items=${visibleTracks}
                         .renderItem=${this.renderTrackRow}
-                        .keyFunction=${(track: library.Track) => track.FilePath}
+                        .keyFunction=${(track: ListTrack) => track.FilePath}
                         .layout=${this.rowLayout}
                       ></lit-virtualizer>
                     `}

frontend/src/store/controllers/library-controller.ts

@@ -1,6 +1,7 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
 import type * as library from '@go/library/models.js';
 import { libraryStore } from '../library-store';
+import type { ListTrack } from '@utils/track-table';
 
 type ViewName = 'tracks' | 'albums' | 'artists' | 'genres';
 
@@ -55,7 +56,7 @@ export class LibraryController implements ReactiveController {
     // DATA ACCESS
     // ===================================================================
 
-    async getTracks(): Promise<library.Track[]> {
+    async getTracks(): Promise<ListTrack[]> {
         return libraryStore.getTracks();
     }
 
@@ -85,7 +86,7 @@ export class LibraryController implements ReactiveController {
         );
     }
 
-    get cachedTracks(): library.Track[] | null {
+    get cachedTracks(): ListTrack[] | null {
         return libraryStore.getCachedTracks();
     }
 

frontend/src/store/library-store.ts

@@ -1,6 +1,6 @@
 import { EventsOn } from '@runtime/runtime';
 import {
-    GetTracks,
+    GetTrackTable,
     GetAlbums,
     GetArtists,
     GetGenres,
@@ -9,6 +9,7 @@ import {
 } from '@go/library/library.js';
 import type * as library from '@go/library/models.js';
 import { list } from '@utils/binding';
+import { decodeTrackTable, type ListTrack } from '@utils/track-table';
 import { Events } from '../events';
 
 type ViewName = 'tracks' | 'albums' | 'artists' | 'genres';
@@ -28,7 +29,7 @@ const COVER_SIZE_DEFAULT = 176;
 const COVER_SIZE_KEY = 'cover-grid-size';
 
 class LibraryStore {
-    private tracks: library.Track[] | null = null;
+    private tracks: ListTrack[] | null = null;
     private albums: library.Album[] | null = null;
     private artists: library.Artist[] | null = null;
     private genres: library.GenreWithCount[] | null = null;
@@ -214,18 +215,18 @@ class LibraryStore {
         }
     }
 
-    async getTracks(): Promise<library.Track[]> {
+    async getTracks(): Promise<ListTrack[]> {
         if (this.tracks !== null) {
             return this.tracks;
         }
 
-        const pending = this.pending<library.Track[]>('tracks');
+        const pending = this.pending<ListTrack[]>('tracks');
 
         if (pending) return pending;
 
         return this.track(
             'tracks',
-            list(GetTracks(this.libraryFilter())),
+            GetTrackTable(this.libraryFilter()).then(decodeTrackTable),
             (tracks) => {
                 this.tracks = tracks;
             },
@@ -341,7 +342,7 @@ class LibraryStore {
     // Synchronous access for controllers that need current cached values.
     // ===================================================================
 
-    getCachedTracks(): library.Track[] | null {
+    getCachedTracks(): ListTrack[] | null {
         return this.tracks;
     }
 
@@ -520,10 +521,11 @@ class LibraryStore {
     private applyPlayCount(payload: unknown): void {
         if (this.tracks === null) return;
 
+        // The list does not carry LastPlayed (#281); trackCache patches
+        // it on the whole tracks the details dialog reads.
         const p = payload as {
             filePath?: string;
             playCount?: number;
-            lastPlayed?: string;
         } | null;
 
         if (!p?.filePath) return;
@@ -536,14 +538,10 @@ class LibraryStore {
 
         if (existing === undefined) return;
 
-        const patched = Object.assign(
-            Object.create(Object.getPrototypeOf(existing) as object),
-            existing,
-            {
-                PlayCount: p.playCount ?? existing.PlayCount,
-                LastPlayed: p.lastPlayed ?? existing.LastPlayed,
-            },
-        ) as library.Track;
+        const patched: ListTrack = {
+            ...existing,
+            PlayCount: p.playCount ?? existing.PlayCount,
+        };
 
         this.tracks = [
             ...this.tracks.slice(0, idx),

frontend/src/utils/binding.ts

@@ -79,6 +79,14 @@ export function compact<V>(
     return out;
 }
 
+/**
+ * listField is list for a slice that arrived as a *field* of a struct
+ * rather than as a return value — a column of `TrackTable`, say.
+ */
+export function listField<T>(field: T[] | null | undefined): T[] {
+    return field ?? [];
+}
+
 /**
  * value awaits a binding whose result is used as-is, dropping only the
  * cancellation the app never asks for.

frontend/src/utils/track-index.ts

@@ -20,22 +20,22 @@
  * given array and never again.
  */
 
-import type * as library from '@go/library/models.js';
+/** Anything keyed by file path: a whole track, or the list's row. */
+interface HasFilePath {
+    FilePath: string;
+}
 
-const byArray = new WeakMap<
-    readonly library.Track[],
-    Map<string, library.Track>
->();
+const byArray = new WeakMap<readonly HasFilePath[], Map<string, HasFilePath>>();
 
 /** The lookup for `tracks`, built once per array identity. */
-export function tracksByFilePath(
-    tracks: readonly library.Track[],
-): Map<string, library.Track> {
-    let map = byArray.get(tracks);
+export function tracksByFilePath<T extends HasFilePath>(
+    tracks: readonly T[],
+): Map<string, T> {
+    let map = byArray.get(tracks) as Map<string, T> | undefined;
 
     if (map) return map;
 
-    map = new Map<string, library.Track>();
+    map = new Map<string, T>();
 
     for (const track of tracks) {
         // First wins: a duplicate path would be the same file, and
@@ -49,12 +49,12 @@ export function tracksByFilePath(
 }
 
 /** Resolve file paths to tracks, dropping any that are not present. */
-export function tracksForPaths(
-    tracks: readonly library.Track[],
+export function tracksForPaths<T extends HasFilePath>(
+    tracks: readonly T[],
     filePaths: readonly string[],
-): library.Track[] {
+): T[] {
     const byPath = tracksByFilePath(tracks);
-    const result: library.Track[] = [];
+    const result: T[] = [];
 
     for (const filePath of filePaths) {
         const track = byPath.get(filePath);

frontend/src/utils/track-table.ts

@@ -0,0 +1,128 @@
+/**
+ * Decode the backend's `TrackTable` into the rows the Tracks view uses.
+ *
+ * The table is one array per column with every repeated string sent
+ * once (#281): ~167 bytes a track against the ~800 of the object-per-
+ * track JSON it replaced. This is its only decoder, and
+ * `backend/library/tracktable.go` its only encoder.
+ *
+ * Decoding builds plain objects of the same shape as before, so the
+ * filter, sort and selection code did not have to change — but every
+ * occurrence of a repeated string is now the *same* string, and every
+ * track with one genre list shares the array, which is part of why the
+ * JS heap shrinks along with the payload. Shared means read-only: no
+ * caller mutates a row's `Genre`.
+ */
+
+import type * as library from '@go/library/models.js';
+import { listField } from '@utils/binding';
+
+/**
+ * A track as the list carries it. The fields left out are the details
+ * dialog's, which reads whole tracks by path from `trackCache`.
+ */
+export type ListTrack = Omit<
+    library.Track,
+    'LastPlayed' | 'CoverArtPath' | 'CoverArtMedium' | 'CoverArtLarge'
+>;
+
+/** The `Track` fields a `ListTrack` does not carry. */
+export const LIST_TRACK_OMITS = [
+    'LastPlayed',
+    'CoverArtPath',
+    'CoverArtMedium',
+    'CoverArtLarge',
+] as const;
+
+/** A table whose columns disagree in length is a broken encoder, not data. */
+export class TrackTableError extends Error {}
+
+export function decodeTrackTable(table: library.TrackTable): ListTrack[] {
+    const strings = listField(table.strings);
+    const filePath = listField(table.filePath);
+    const n = filePath.length;
+
+    const str = (col: number[] | null, name: string): string[] => {
+        const idx = listField(col);
+
+        if (idx.length !== n) throw mismatch(name, idx.length, n);
+
+        return idx.map((i) => {
+            const s = strings[i];
+
+            if (s === undefined) throw new TrackTableError(`${name}: string ${i} out of range`);
+
+            return s;
+        });
+    };
+    const num = (col: number[] | null, name: string): number[] => {
+        const v = listField(col);
+
+        if (v.length !== n) throw mismatch(name, v.length, n);
+
+        return v;
+    };
+
+    const genreSets = listField(table.genreSets).map((set) =>
+        listField(set).map((i) => strings[i] ?? ''),
+    );
+    const genre = num(table.genre, 'genre');
+
+    const trackName = str(table.trackName, 'trackName');
+    const artistName = str(table.artistName, 'artistName');
+    const album = str(table.album, 'album');
+    const composer = str(table.composer, 'composer');
+    const fileType = str(table.fileType, 'fileType');
+    const artistMbid = str(table.artistMbid, 'artistMbid');
+    const releaseGroupMbid = str(table.releaseGroupMbid, 'releaseGroupMbid');
+    const recordingMbid = str(table.recordingMbid, 'recordingMbid');
+    const coverArtSmall = str(table.coverArtSmall, 'coverArtSmall');
+    const lengthMs = num(table.lengthMs, 'lengthMs');
+    const trackNumber = num(table.trackNumber, 'trackNumber');
+    const discNumber = num(table.discNumber, 'discNumber');
+    const year = num(table.year, 'year');
+    const sampleRate = num(table.sampleRate, 'sampleRate');
+    const bitDepth = num(table.bitDepth, 'bitDepth');
+    const channels = num(table.channels, 'channels');
+    const bitrate = num(table.bitrate, 'bitrate');
+    const fileSize = num(table.fileSize, 'fileSize');
+    const playCount = num(table.playCount, 'playCount');
+
+    const rows: ListTrack[] = new Array<ListTrack>(n);
+
+    for (let i = 0; i < n; i++) {
+        const g = genreSets[genre[i]!];
+
+        if (g === undefined) throw new TrackTableError(`genre: set ${genre[i]} out of range`);
+
+        rows[i] = {
+            FilePath: filePath[i]!,
+            TrackName: trackName[i]!,
+            ArtistName: artistName[i]!,
+            Album: album[i]!,
+            Composer: composer[i]!,
+            FileType: fileType[i]!,
+            Genre: g,
+            ArtistMBID: artistMbid[i]!,
+            ReleaseGroupMBID: releaseGroupMbid[i]!,
+            RecordingMBID: recordingMbid[i]!,
+            CoverArtSmall: coverArtSmall[i]!,
+            TrackLength: String(lengthMs[i]!),
+            TrackNumber: trackNumber[i]!,
+            DiscNumber: discNumber[i]!,
+            Year: year[i]!,
+            SampleRate: sampleRate[i]!,
+            BitDepth: bitDepth[i]!,
+            Channels: channels[i]!,
+            Bitrate: bitrate[i]!,
+            FileSize: fileSize[i]!,
+            PlayCount: playCount[i]!,
+        };
+    }
+
+    return rows;
+}
+
+function mismatch(name: string, got: number, want: number): TrackTableError {
+    return new TrackTableError(`${name}: ${got} values for ${want} tracks`);
+}

frontend/test/components/album-card-year.test.ts

@@ -19,6 +19,7 @@ import '@components/cover-grid/cover-grid';
 import { emit, stub, flush, resetHarness } from '@test/support/harness';
 import { Events } from '../../src/events';
 import { fixture, shadowAll } from '@test/support/render';
+import { trackTable } from '@test/support/track-table';
 
 const LONG =
   'The Rise and Fall of a Midwest Princess in the Key of Everything';
@@ -49,7 +50,7 @@ describe('the album card’s year', () => {
   beforeEach(() => {
     resetHarness();
     stub('library.Library.GetAlbums', ALBUMS);
-    stub('library.Library.GetTracks', []);
+    stub('library.Library.GetTrackTable', trackTable([]));
     emit(Events.LibraryScanComplete);
   });
 

frontend/test/components/album-dropdown.test.ts

@@ -22,6 +22,7 @@ import '@components/cover-grid/cover-grid';
 import { emit, stub, flush, resetHarness } from '@test/support/harness';
 import { Events } from '../../src/events';
 import { fixture, shadow, shadowAll } from '@test/support/render';
+import { trackTable } from '@test/support/track-table';
 
 /**
  * Enough albums to fill more than one row.
@@ -82,7 +83,7 @@ describe('the album dropdown', () => {
   beforeEach(() => {
     resetHarness();
     stub('library.Library.GetAlbums', ALBUMS);
-    stub('library.Library.GetTracks', []);
+    stub('library.Library.GetTrackTable', trackTable([]));
     stub('library.Library.GetAlbumTracks', TRACKS);
     stub('library.Library.GetAlbumTracks', TRACKS);
     emit(Events.LibraryScanComplete);
@@ -155,7 +156,7 @@ describe('the albums grid scrolls', () => {
   beforeEach(() => {
     resetHarness();
     stub('library.Library.GetAlbums', ALBUMS);
-    stub('library.Library.GetTracks', []);
+    stub('library.Library.GetTrackTable', trackTable([]));
     emit(Events.LibraryScanComplete);
   });
 

frontend/test/components/aria-tail.test.ts

@@ -20,6 +20,7 @@ import { emit, stub, flush, resetHarness } from '@test/support/harness';
 import { Events } from '../../src/events';
 import { fixture, shadow, shadowAll } from '@test/support/render';
 import { searchStore } from '@store/search-store';
+import { trackTable } from '@test/support/track-table';
 
 /**
  * The searchable columns' accessors read these fields and call
@@ -76,7 +77,7 @@ describe('the track list says how it is sorted', () => {
   beforeEach(async () => {
     resetHarness();
     searchStore.setTerm('');
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     stub('library.Library.GetAlbums', []);
     emit(Events.LibraryScanComplete);
   });
@@ -132,7 +133,7 @@ describe('the track list has a voice for its own state', () => {
   });
 
   it('announces the result of a search that matches nothing', async () => {
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     emit(Events.LibraryScanComplete);
 
     const el = await fixture<LitElement>('track-list');
@@ -163,7 +164,7 @@ describe('a selectable grid is a listbox, not a row of buttons', () => {
     searchStore.setTerm('');
     stub('library.Library.GetArtists', ARTISTS);
     stub('library.Library.GetGenres', GENRES);
-    stub('library.Library.GetTracks', []);
+    stub('library.Library.GetTrackTable', trackTable([]));
     stub('library.Library.GetAlbums', []);
     emit(Events.LibraryScanComplete);
   });
@@ -197,7 +198,7 @@ describe('a clipped value is readable somewhere', () => {
   beforeEach(async () => {
     resetHarness();
     searchStore.setTerm('');
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     stub('library.Library.GetAlbums', []);
     emit(Events.LibraryScanComplete);
   });
@@ -240,7 +241,7 @@ describe('the playing row is more than a colour', () => {
   beforeEach(async () => {
     resetHarness();
     searchStore.setTerm('');
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     stub('library.Library.GetAlbums', []);
     emit(Events.LibraryScanComplete);
   });

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

@@ -35,6 +35,7 @@ import {
   imagePrefetched,
   resetImagePrefetch,
 } from '@utils/image-prefetch';
+import { trackTable } from '@test/support/track-table';
 
 /** Enough albums that the virtualizer's own window is nowhere near the end. */
 const ALBUMS = Array.from({ length: 400 }, (_, i) => {
@@ -118,7 +119,7 @@ beforeEach(() => {
   localStorage.clear();
   stub('library.Library.GetAlbums', ALBUMS);
   stub('library.Library.GetArtists', ARTISTS);
-  stub('library.Library.GetTracks', []);
+  stub('library.Library.GetTrackTable', trackTable([]));
   stub('library.Library.GetGenres', []);
   emit(Events.LibraryScanComplete);
 });

frontend/test/components/card-grid-repaint.test.ts

@@ -29,6 +29,7 @@ import '@components/genres-view/genres-view';
 import { emit, stub, flush, resetHarness } from '@test/support/harness';
 import { Events } from '../../src/events';
 import { fixture, shadowAll } from '@test/support/render';
+import { trackTable } from '@test/support/track-table';
 
 const ARTISTS = [
   { ID: 1, Name: 'Alpha', AlbumCount: 2, TrackCount: 9 },
@@ -58,7 +59,7 @@ describe('a card grid shows its selection', () => {
     resetHarness();
     stub('library.Library.GetArtists', ARTISTS);
     stub('library.Library.GetGenres', GENRES);
-    stub('library.Library.GetTracks', []);
+    stub('library.Library.GetTrackTable', trackTable([]));
     stub('library.Library.GetAlbums', []);
     // The views read through LibraryController, whose cache is only
     // primed by a scan-complete; without it they render nothing and the

frontend/test/components/chrome.test.ts

@@ -191,7 +191,7 @@ describe('<library-filter>', () => {
     select?.dispatchEvent(new Event('change'));
     await flush();
 
-    expect(lastArgs('library.Library.GetTracks')).toEqual([8]);
+    expect(lastArgs('library.Library.GetTrackTable')).toEqual([8]);
   });
 
   it('picks up a library added while it was on screen', async () => {

frontend/test/components/detail-touch-targets.test.ts

@@ -72,7 +72,7 @@ function boxOf(el: Element | null | undefined): { w: number; h: number } {
 describe('the way out of a detail view', () => {
   beforeEach(() => {
     for (const path of [
-      'library.Library.GetTracks',
+      'library.Library.GetTrackTable',
       'library.Library.GetAlbums',
       'library.Library.GetArtists',
       'library.Library.GetGenres',

frontend/test/components/empty-states.test.ts

@@ -11,11 +11,12 @@ import '@components/track-list/track-list';
 import { Events } from '../../src/events';
 import { emit, stub, stubFailure, flush, resetHarness } from '@test/support/harness';
 import { fixture, shadow, text } from '@test/support/render';
+import { trackTable } from '@test/support/track-table';
 
 /** Drop the library store's cache so the list has to fetch. */
 async function emptyLibrary(): Promise<void> {
   resetHarness();
-  stub('library.Library.GetTracks', []);
+  stub('library.Library.GetTrackTable', trackTable([]));
   stub('library.Library.GetAlbums', []);
   stub('library.Library.GetArtists', []);
   stub('library.Library.GetGenres', []);
@@ -40,7 +41,7 @@ describe('<track-list> empty, loading and failed', () => {
   });
 
   it('says the query failed, and offers to try again', async () => {
-    stubFailure('library.Library.GetTracks', 'sql: database is locked');
+    stubFailure('library.Library.GetTrackTable', 'sql: database is locked');
     emit(Events.LibraryScanComplete);
     await flush();
 

frontend/test/components/keyboard-reach.test.ts

@@ -14,6 +14,7 @@ import '@components/track-list/track-list';
 import { stub, emit, flush } from '@test/support/harness';
 import { Events } from '../../src/events';
 import { fixture, shadow, shadowAll, update } from '@test/support/render';
+import { trackTable } from '@test/support/track-table';
 
 /** Two fixture tracks, enough to move a focus ring between. */
 const TRACKS = [
@@ -78,7 +79,7 @@ describe('<queue-panel> when closed', () => {
 
 describe('<track-list> roving tabindex', () => {
   beforeEach(() => {
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
   });
 
   it('offers exactly one tab stop, however many rows there are', async () => {

frontend/test/components/library-status.test.ts

@@ -31,6 +31,7 @@ import {
   stubFailure,
 } from '@test/support/harness';
 import { fixture, shadow, shadowAll, update } from '@test/support/render';
+import { trackTable } from '@test/support/track-table';
 
 const SEARCH = 'explore.Service.SearchLocal';
 
@@ -133,7 +134,7 @@ describe('<explore-view> badges', () => {
     stub('explore.Service.GetArtistImageURL', '');
     stub('explore.Service.GetExploreShelves', { shelves: [], state: 'ready' });
     stub('library.Library.GetAlbums', []);
-    stub('library.Library.GetTracks', []);
+    stub('library.Library.GetTrackTable', trackTable([]));
     await withRequests([]);
   });
 

frontend/test/components/list-render-cost.test.ts

@@ -48,21 +48,12 @@ describe('the track list Art column', () => {
     ]).toEqual(['lazy', 'async']);
   });
 
-  it('falls back through the tiers rather than rendering nothing', () => {
-    const onlyOriginal = cell('albumArt', {
-      CoverArtPath: '/covers/abc.jpg',
-      CoverArtSmall: '',
-      CoverArtMedium: '',
-    }).querySelector('img');
-
-    expect(onlyOriginal?.getAttribute('src')).toBe('/covers/abc.jpg');
-  });
-
+  // There is no fallback through the larger tiers any more: the list
+  // carries only the small one (#281), and the backend derives every
+  // tier from the same file, so it is set whenever any of them is.
   it('renders nothing at all when there is no art', () => {
     const none = cell('albumArt', {
-      CoverArtPath: '',
       CoverArtSmall: '',
-      CoverArtMedium: '',
     });
 
     expect(none.querySelector('img')).toBeNull();

frontend/test/components/smoke.test.ts

@@ -117,7 +117,7 @@ const TAGS = [
  */
 function stubEmptyBackend(): void {
   const emptyLists = [
-    'library.Library.GetTracks',
+    'library.Library.GetTrackTable',
     'library.Library.GetAlbums',
     'library.Library.GetArtists',
     'library.Library.GetGenres',

frontend/test/components/touch-selection.test.ts

@@ -24,6 +24,7 @@ import '@components/selection-bar/selection-bar';
 import { calls, flush, resetHarness, stub } from '@test/support/harness';
 import { fixture, shadow, shadowAll } from '@test/support/render';
 import { installTouchGestures, LONG_PRESS_MS } from '@utils/touch-gestures';
+import { trackTable } from '@test/support/track-table';
 
 const HELD = LONG_PRESS_MS + 120;
 
@@ -117,7 +118,7 @@ function rows(el: HTMLElement): HTMLElement[] {
 describe('a finger on a track row', () => {
   beforeEach(() => {
     resetHarness();
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     stub('library.Library.GetAllLibrariesWithTrackCounts', []);
     stub('config.Config.GetShortcuts', {});
     stub('queue.Queue.SetQueue', null);
@@ -320,7 +321,7 @@ describe('<selection-bar>', () => {
 describe('a tap on a name inside a row', () => {
   beforeEach(() => {
     resetHarness();
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     stub('library.Library.GetAllLibrariesWithTrackCounts', []);
     stub('config.Config.GetShortcuts', {});
     stub('queue.Queue.SetQueue', null);

frontend/test/components/touch-swipe.test.ts

@@ -33,6 +33,7 @@ import '@components/track-list/track-list';
 import { calls, flush, resetHarness, stub } from '@test/support/harness';
 import { fixture, shadow, shadowAll } from '@test/support/render';
 import { installTouchGestures } from '@utils/touch-gestures';
+import { trackTable } from '@test/support/track-table';
 
 const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
@@ -125,7 +126,7 @@ function threshold(row: HTMLElement): number {
 describe('a finger swiped right across a track row', () => {
   beforeEach(() => {
     resetHarness();
-    stub('library.Library.GetTracks', TRACKS);
+    stub('library.Library.GetTrackTable', trackTable(TRACKS));
     stub('library.Library.GetAllLibrariesWithTrackCounts', []);
     stub('config.Config.GetShortcuts', {});
     stub('queue.Queue.SetQueue', null);

frontend/test/components/view-lifecycle.test.ts

@@ -231,7 +231,7 @@ const CACHED_VIEWS = [
  *  binding resolves undefined, which is not what Go sends. */
 function stubEmptyBackend(): void {
   for (const path of [
-    'library.Library.GetTracks',
+    'library.Library.GetTrackTable',
     'library.Library.GetAlbums',
     'library.Library.GetArtists',
     'library.Library.GetGenres',

frontend/test/setup.ts

@@ -35,7 +35,7 @@ const importTimeDefaults: Array<[string, unknown]> = [
   // libraryStore and playlistStore fetch eagerly at import. Left
   // unstubbed they would cache `undefined` — not the empty list Go
   // sends — and every consumer would then crash on `.length`.
-  ['library.Library.GetTracks', []],
+  ['library.Library.GetTrackTable', { strings: [''] }],
   ['library.Library.GetAlbums', []],
   ['library.Library.GetArtists', []],
   ['library.Library.GetGenres', []],

frontend/test/stores/library-store.test.ts

@@ -19,10 +19,11 @@ import {
   lastArgs,
   resetHarness,
 } from '@test/support/harness';
+import { trackTable } from '@test/support/track-table';
 
 const TRACKS = [
-  { ID: 1, Title: 'One', FilePath: '/a.mp3', PlayCount: 0, LastPlayed: '' },
-  { ID: 2, Title: 'Two', FilePath: '/b.mp3', PlayCount: 4, LastPlayed: 'x' },
+  { TrackName: 'One', FilePath: '/a.mp3', PlayCount: 0 },
+  { TrackName: 'Two', FilePath: '/b.mp3', PlayCount: 4 },
 ];
 const ALBUMS = [{ ID: 1, Name: 'Album', ArtistName: 'Artist' }];
 const OTHER_ALBUMS = [{ ID: 2, Name: 'Other', ArtistName: 'Other Artist' }];
@@ -33,15 +34,10 @@ const LIBRARIES = [{ id: 7, name: 'Music' }, { id: 8, name: 'Field' }];
 /** Stub every read binding the store can reach. Unstubbed bindings
  *  resolve undefined, which the store would cache as if it were data. */
 function stubReads(): void {
-  stub('library.Library.GetTracks', TRACKS);
+  stub('library.Library.GetTrackTable', trackTable(TRACKS));
   stub('library.Library.GetAlbums', ALBUMS);
   stub('library.Library.GetArtists', ARTISTS);
   stub('library.Library.GetGenres', GENRES);
-  stub('library.Library.GetTracks', TRACKS);
-  stub('library.Library.GetAlbums', ALBUMS);
-  stub('library.Library.GetArtists', ARTISTS);
-  stub('library.Library.GetGenres', GENRES);
-  stub('library.Library.GetAlbumsByArtist', ALBUMS);
   stub('library.Library.GetAlbumsByArtist', ALBUMS);
   stub('library.Library.GetAllLibrariesWithTrackCounts', LIBRARIES);
 }
@@ -69,7 +65,7 @@ describe('library store: caching', () => {
   it('serves a second read from cache without touching the backend', async () => {
     await libraryStore.getTracks();
 
-    expect(calls('library.Library.GetTracks')).toHaveLength(0);
+    expect(calls('library.Library.GetTrackTable')).toHaveLength(0);
   });
 
   it('deduplicates concurrent first reads into one backend call', async () => {
@@ -88,11 +84,11 @@ describe('library store: caching', () => {
 
   it('exposes cached collections synchronously once loaded', () => {
     expect([
-      libraryStore.getCachedTracks(),
+      libraryStore.getCachedTracks()?.map((t) => t.FilePath),
       libraryStore.getCachedAlbums(),
       libraryStore.cachedArtists,
       libraryStore.getCachedGenres(),
-    ]).toEqual([TRACKS, ALBUMS, ARTISTS, GENRES]);
+    ]).toEqual([['/a.mp3', '/b.mp3'], ALBUMS, ARTISTS, GENRES]);
   });
 
   it('refetches everything when a scan completes', async () => {
@@ -103,7 +99,7 @@ describe('library store: caching', () => {
       'library.Library.GetAlbums',
       'library.Library.GetArtists',
       'library.Library.GetGenres',
-      'library.Library.GetTracks',
+      'library.Library.GetTrackTable',
     ]);
   });
 
@@ -111,7 +107,7 @@ describe('library store: caching', () => {
     emit(Events.TrackMetadataChanged, { filePath: '/a.mp3' });
     await flush();
 
-    expect(calls('library.Library.GetTracks')).toHaveLength(1);
+    expect(calls('library.Library.GetTrackTable')).toHaveLength(1);
   });
 
   /*
@@ -140,10 +136,11 @@ describe('library store: caching', () => {
     it('patches the one track it names', () => {
       const tracks = libraryStore.getCachedTracks();
 
+      // LastPlayed is not on the list's rows (#281); trackCache
+      // patches it on whole tracks.
       expect(tracks?.[0]).toMatchObject({
         FilePath: '/a.mp3',
         PlayCount: 9,
-        LastPlayed: '2026-08-11 10:00:00',
       });
     });
 
@@ -192,7 +189,7 @@ describe('library store: caching', () => {
     });
 
     it('does not refetch the tracks', () => {
-      expect(calls('library.Library.GetTracks')).toHaveLength(0);
+      expect(calls('library.Library.GetTrackTable')).toHaveLength(0);
     });
 
     it('splices the removed track out in place', () => {
@@ -258,7 +255,7 @@ describe('library store: library filter', () => {
     libraryStore.setSelectedLibrary(7);
     await flush();
 
-    expect(lastArgs('library.Library.GetTracks')).toEqual([7]);
+    expect(lastArgs('library.Library.GetTrackTable')).toEqual([7]);
   });
 
   it('ignores a redundant selection instead of invalidating', async () => {
@@ -304,12 +301,12 @@ describe('library store: a fetch that is overtaken', () => {
 
   it('serves the library that is selected, not the one that was in flight', async () => {
     const pending: Array<{ id: number; resolve: (v: unknown) => void }> = [];
-    const byLibrary = (id: number) => [{ ID: id, Title: `Library ${id}` }];
+    const byLibrary = (id: number) => trackTable([{ FilePath: `/lib-${id}.mp3` }]);
 
     // Only the track fetch is held open; the other three settle at once,
     // so the test is about the overtaking and nothing else.
     stub(
-      'library.Library.GetTracks',
+      'library.Library.GetTrackTable',
       (id: number) =>
         new Promise((resolve) => {
           pending.push({ id, resolve });
@@ -327,11 +324,13 @@ describe('library store: a fetch that is overtaken', () => {
     pending.find((p) => p.id === 8)?.resolve(byLibrary(8));
     await flush();
 
-    expect(libraryStore.getCachedTracks()).toEqual(byLibrary(8));
+    expect(libraryStore.getCachedTracks()?.map((t) => t.FilePath)).toEqual([
+      '/lib-8.mp3',
+    ]);
   });
 
   it('settles the waiters when the fetch they are waiting on fails', async () => {
-    stubFailure('library.Library.GetTracks', 'sql: database is locked');
+    stubFailure('library.Library.GetTrackTable', 'sql: database is locked');
     // Invalidation drops the cache and starts the fetch that fails.
     emit(Events.LibraryScanComplete);
 

frontend/test/support/track-table.ts

@@ -0,0 +1,86 @@
+/**
+ * Encode test tracks as the backend's `TrackTable` (#281), so a stub of
+ * `library.Library.GetTrackTable` can be written as a list of tracks.
+ *
+ * Test fixtures are partial tracks; a missing field encodes as the
+ * zero value Go would have sent. The encoding mirrors
+ * `backend/library/tracktable.go` closely enough to exercise the real
+ * decoder: shared string table with "" at 0, genre lists interned.
+ */
+import type * as library from '@go/library/models.js';
+
+/** A fixture: any subset of a track's fields, loosely typed as fixtures are. */
+type PartialTrack = { FilePath: string } & Record<string, unknown>;
+
+const STRING_COLS = [
+  ['trackName', 'TrackName'],
+  ['artistName', 'ArtistName'],
+  ['album', 'Album'],
+  ['composer', 'Composer'],
+  ['fileType', 'FileType'],
+  ['artistMbid', 'ArtistMBID'],
+  ['releaseGroupMbid', 'ReleaseGroupMBID'],
+  ['recordingMbid', 'RecordingMBID'],
+  ['coverArtSmall', 'CoverArtSmall'],
+] as const;
+
+const INT_COLS = [
+  ['trackNumber', 'TrackNumber'],
+  ['discNumber', 'DiscNumber'],
+  ['year', 'Year'],
+  ['sampleRate', 'SampleRate'],
+  ['bitDepth', 'BitDepth'],
+  ['channels', 'Channels'],
+  ['bitrate', 'Bitrate'],
+  ['fileSize', 'FileSize'],
+  ['playCount', 'PlayCount'],
+] as const;
+
+export function trackTable(tracks: readonly PartialTrack[]): library.TrackTable {
+  const strings = [''];
+  const index = new Map<string, number>([['', 0]]);
+  const intern = (s: string | undefined): number => {
+    const v = s ?? '';
+    let i = index.get(v);
+
+    if (i === undefined) {
+      i = strings.length;
+      strings.push(v);
+      index.set(v, i);
+    }
+
+    return i;
+  };
+
+  const genreSets: number[][] = [];
+  const genreIndex = new Map<string, number>();
+  const table: Record<string, unknown> = {
+    strings,
+    genreSets,
+    filePath: tracks.map((t) => t.FilePath),
+    lengthMs: tracks.map((t) => Number(t['TrackLength'] ?? 0) || 0),
+    genre: tracks.map((t) => {
+      const genres = (t['Genre'] as string[] | null | undefined) ?? [];
+      const key = genres.join('\u0000');
+      let i = genreIndex.get(key);
+
+      if (i === undefined) {
+        i = genreSets.length;
+        genreSets.push(genres.map(intern));
+        genreIndex.set(key, i);
+      }
+
+      return i;
+    }),
+  };
+
+  for (const [col, field] of STRING_COLS) {
+    table[col] = tracks.map((t) => intern(t[field] as string | undefined));
+  }
+
+  for (const [col, field] of INT_COLS) {
+    table[col] = tracks.map((t) => (t[field] as number | undefined) ?? 0);
+  }
+
+  return table as unknown as library.TrackTable;
+}

frontend/test/utils/track-table.test.ts

@@ -0,0 +1,134 @@
+/**
+ * `decodeTrackTable` is the only reader of the backend's columnar track
+ * list (#281). The encoder is Go and the row type is TypeScript, so the
+ * last block reads both sides' declarations and fails if a column is
+ * added on one and not the other.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  decodeTrackTable,
+  LIST_TRACK_OMITS,
+  TrackTableError,
+} from '@utils/track-table';
+import { trackTable } from '@test/support/track-table';
+
+const FIXTURE = [
+  {
+    FilePath: '/m/a/1.flac',
+    TrackName: 'One',
+    ArtistName: 'Artist',
+    Album: 'Album',
+    Genre: ['Ambient', 'Drone'],
+    TrackLength: '215000',
+    TrackNumber: 1,
+    CoverArtSmall: '/covers/x_sm.jpg',
+    PlayCount: 3,
+  },
+  {
+    FilePath: '/m/a/2.flac',
+    TrackName: 'Two',
+    ArtistName: 'Artist',
+    Album: 'Album',
+    Genre: ['Ambient', 'Drone'],
+    TrackLength: '1000',
+    TrackNumber: 2,
+    CoverArtSmall: '/covers/x_sm.jpg',
+  },
+];
+
+describe('decodeTrackTable', () => {
+  it('gives back each track it was given', () => {
+    const [a, b] = decodeTrackTable(trackTable(FIXTURE));
+
+    expect(a).toMatchObject({
+      FilePath: '/m/a/1.flac',
+      TrackName: 'One',
+      Album: 'Album',
+      Genre: ['Ambient', 'Drone'],
+      TrackLength: '215000',
+      TrackNumber: 1,
+      PlayCount: 3,
+      Composer: '',
+    });
+    expect(b).toMatchObject({ TrackName: 'Two', TrackLength: '1000', PlayCount: 0 });
+  });
+
+  it('shares one genre list between tracks that have the same one', () => {
+    const [a, b] = decodeTrackTable(trackTable(FIXTURE));
+
+    expect(a!.Genre).toBe(b!.Genre);
+  });
+
+  it('decodes an empty library to no rows', () => {
+    expect(decodeTrackTable(trackTable([]))).toEqual([]);
+  });
+
+  it('refuses a table whose columns disagree in length', () => {
+    const broken = trackTable(FIXTURE);
+
+    (broken as unknown as { album: number[] }).album = [1];
+
+    expect(() => decodeTrackTable(broken)).toThrow(TrackTableError);
+  });
+
+  it('refuses a string index past the table', () => {
+    const broken = trackTable(FIXTURE);
+
+    (broken as unknown as { album: number[] }).album = [1, 999];
+
+    expect(() => decodeTrackTable(broken)).toThrow(/out of range/);
+  });
+});
+
+/** The generated Track interface and the Go encoder, as text. */
+const MODELS = Object.values(
+  import.meta.glob<string>('../../bindings/yellowjacket/backend/library/models.ts', {
+    eager: true,
+    query: '?raw',
+    import: 'default',
+  }),
+)[0] ?? '';
+const ENCODER = Object.values(
+  import.meta.glob<string>('../../../backend/library/tracktable.go', {
+    eager: true,
+    query: '?raw',
+    import: 'default',
+  }),
+)[0] ?? '';
+
+function interfaceKeys(source: string, name: string): string[] {
+  const body = source.split(`export interface ${name} {`)[1]?.split('\n}')[0] ?? '';
+
+  return [...body.matchAll(/^\s+"(\w+)"\??:/gm)].map((m) => m[1]!);
+}
+
+describe('the list row and the Go table agree', () => {
+  const trackKeys = interfaceKeys(MODELS, 'Track');
+  const tableKeys = [...ENCODER.matchAll(/json:"(\w+)"/g)].map((m) => m[1]!);
+
+  it('read both declarations', () => {
+    expect(trackKeys.length).toBeGreaterThan(20);
+    expect(tableKeys.length).toBeGreaterThan(20);
+  });
+
+  it('decodes every Track field the list keeps, and only those', () => {
+    const decoded = Object.keys(decodeTrackTable(trackTable(FIXTURE))[0]!).sort();
+    const omitted = new Set<string>(LIST_TRACK_OMITS);
+
+    expect(decoded).toEqual(trackKeys.filter((k) => !omitted.has(k)).sort());
+  });
+
+  it('has a column for every field it decodes', () => {
+    // Columns are the field names in lower camel case, except the two
+    // that are not columns of a field and the length, which is sent as
+    // the number it encodes.
+    const columns = new Set(tableKeys.filter((k) => !['strings', 'genreSets'].includes(k)));
+    const expected = trackKeys
+      .filter((k) => !(LIST_TRACK_OMITS as readonly string[]).includes(k))
+      .map((k) => (k === 'TrackLength' ? 'lengthMs' : k[0]!.toLowerCase() + k.slice(1)))
+      .map((k) => k.replace(/MBID$/, 'Mbid'));
+
+    expect([...columns].sort()).toEqual(expected.sort());
+  });
+});