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

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>
                     `}