All four collections were fetched at DOMContentLoaded and refetched on
every invalidation, whichever view was showing. On a 26 138-track
library the track list was 20.5 MB of that, and encoding it cost the
backend ~170 MB of transient allocation — paid by someone looking at
Home, which draws none of it.
- The store warms only albums, artists and genres, on idle after first
paint: 1.6 MB together, and what made those views instant.
- A nav item prefetches on hover and on keyboard focus, which is the
~100 ms before the click that a cold open would otherwise wait.
- An invalidation refetches what something had loaded, and nothing
else — a scan no longer loads the track list of a library whose
Tracks view nobody has opened.
- `index.html`'s first-paint `<track-list>` is `view-hidden`, and
`index.ts` no longer activates it: it is markup, not a decision about
which view the launch lands on, and activating it was what fetched
the whole list for a landing on Home. The track list itself loads on
view activation, which the shell drives.
Measured on 50 000 tracks: backend RSS at rest 543 → 296 MB, peak 571 →
296 MB, Go heap held 361 → 125 MB, JS heap 31.8 → 18 MB, binding bytes
at rest 35.9 → 12.1 MB, heap after a browse 36.5 → 22.7 MB. Tracks
first open 26 ms; slowest view open 57 ms.
Closes#280
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
Plans 013 and 014, the album page that prompted them, and the smaller
fixes they turned up. Changelog, largest first.
## The local library is shaped like files, not like MusicBrainz
`audio_files` carries its own tags and points at `albums` and
`artists`; `file_genres` is the one real many-to-many. `recordings`,
`release_group_recordings`, `artist_credit`, `artist_credit_artist`,
`recording_genres`, `release_groups` and `release_to_rg` are gone from
the local side, and with them a six-way join in every read, a
`MIN(release_group_id)` subquery in eleven queries and a
first-credited-artist subquery in nine. Measured on a real 25,966-file
library, every many-to-many that model expressed was 1:1 in the data.
- Ownership is a file. `GetFilePathsByRecordingMBIDs`,
`LibraryMBIDIndex.CheckMBIDs`, `collectLibraryEntities` and
`pruneStaleLocalCrossReferences` all join `audio_files`, so the 812
orphaned recordings, 216 release groups and 260 artists that library
carried are now structurally impossible.
- One projection: every track query selects from the `track_metadata`
view, one row type, one mapper. Nine hand-rolled copies had drifted
far enough to report different years on different screens.
- `library_id = 0` means every library, so each list query exists once
instead of scoped and unscoped with a branch at every call site.
- No migration chain. `sql/schemas/` is the one description of the
shape; `sql/migrations/`, `applyMigrations` and `schema_migrations`
are squashed away, along with the drift between them that had sqlc
generating against a stale schema.
- `database.InsertTestTrack` is the one test seeder; twenty test files
had been assembling the old FK chain each in its own order.
## The catalog stores its ids as bytes
`explore_index`'s three 36-char MBID columns and its entity-type text
are 16 raw bytes and a small integer. The table and its six indexes go
780 MB to 405 MB on a real 2,052,200-row catalog, which is why a fresh
install is ~0.6 GB rather than ~1.0 GB.
- `backend/explore/mbid.go` is the only place the encoding is known;
everything above it speaks dashed strings.
- `CHECK(length(mbid) = 16)` makes a stringly write fail at the insert
rather than silently returning no rows, since SQLite does not coerce
between TEXT and BLOB.
- The importer asks the artifact what encoding it carries and converts
on the way in, so the artifact already published keeps working and no
format bump is needed.
- `indexRowColumns`/`scanIndexRow` replace four copies of a 22-column
list, and `TestStoredEncodingRoundTrips` sweeps every read path.
## An album page that says how much of the album is yours
- One question, asked once: is there a file. `filePaths` is filled by a
single batched lookup when the tracklist settles, and the badge, the
Play count, the dimmed rows and every menu item read it — replacing
four claims of decreasing confidence that could show a green tick on
an album whose every action did nothing.
- Play, Play 7 of 12, or no play button at all.
- `total_tracks` on `explore_index` (~2 bytes over 400,677 release
groups) and on `audio_files` from tags that have always carried it:
a complete MBID-matched album now makes no catalog call at all, where
it used to spend the most expensive request the app makes.
- A merged cluster shows the running order the most releases agree on,
and the version list marks the release you own rather than standing a
synthetic entry in for it.
- `AlbumReleasesFailed`: a slow fetch is no longer reported as a failed
one by a 12-second timer.
- Rows not in the library are dimmed in place (with `aria-disabled`)
instead of the owned ones wearing a green tick and a legend.
## Caches and cover art get ceilings
- Only the three tiers of a cover are stored; the full-resolution copy
nothing rendered was 1,134 MB of a 1.4 GB covers directory.
- One artist portrait is downloaded and the rest are remembered as
URLs — 4.1 GB of a 5.3 GB cache was candidates no code path reads.
- `browsedArtBudget` and `httpCacheBudget` bound what an age cannot:
the same install held art for 5,770 artists in a 1,301-artist
library.
- `OrphanedArtistImagesJob` joined a bare MBID onto a sharded
directory, so it deleted the rows that were the only record of the
files it left behind. `explore.ArtistImageDir` is that layout's one
definition now.
## The autotag queue asks whether there is work
`tagging_items` was a row per album folder, not a queue, and no query
read the `tag_status` column that held the answer. The four queue
queries ask the files, which matters most where it is least visible:
`startPrefetch` was scoring every album in a tagged library against
MusicBrainz.
## Phantom playlist tracks resolve in place
An M3U8 imported before its files leaves phantom rows; they now match
by path and fall back to position, keep their place in the playlist
when resolved, and pair best-first so two phantoms cannot claim the
same file.
## Playing a track plays the list it is in
Double-click, and Play on a single row's menu, queue the list as
displayed with `startIndex` on that row — the album page and the track
list used to queue one track and discard the album around it. A
multi-row selection still plays exactly itself.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AfVYUVExXsx1nSWrXN8mAh
frontend/wailsjs/ is deleted and frontend/bindings/ takes its place —
a real TypeScript module tree nested by Go import path, generated by
wails3's static analyser rather than by building the app and running
it. The @go alias absorbs the constant prefix, so a call site imports
'@go/library/library.js' and the codemod over all 93 sites was a
specifier rewrite plus splitting @go/models' namespaces into one
import per package.
The 12 SetContext bindings and the fake `context` model are gone, as
Phase 2's ServiceStartup port promised: 272 methods across 12
services, none of them plumbing.
@runtime/runtime is now a local shim (src/wails/runtime.ts) over
@wailsio/runtime, so the 22 EventsOn imports are untouched. It
unwraps v3's WailsEvent into v2's callback shape, which is exact here:
nothing in backend/events passes more than one data argument, and v3
only packs arguments into a slice when there is more than one.
v3 tells the truth about two things v2 lied about, and that is most of
the diff. A Go nil slice really does arrive as JSON null, and a Go
named string type really is an enum; v2 typed them as T[] and string.
utils/binding.ts states the app's actual contract — an absent list is
an empty list — once, at the boundary where it is true, and also drops
the CancellablePromise the app never cancels. Four test fixtures
widen an enum field back to its value union.
Not done, and Phase 5's to fix: frontend/test/support/wails-fake.ts
still fakes window.go, which v3 does not have, so `make ui-test` is
broken and harness.test.ts fails to compile on EventsEmit. That test
also asserts v2 ordering that no longer holds — v3's Events.Emit calls
the backend and does not notify in-page listeners at all.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UDCbcCZQepnpSQYJ6SxxZm
RemoveFromLibrary deletes the audio_files rows the way the scan's own
orphan cleanup does and records each path in excluded_paths. The
exclusion is not an enhancement: without it the next scan finds the
file, sees no row and imports it again, so the button undoes itself.
The soft scan compares files on disk against rows in the database, so
surveyAudioFiles and countAudioFiles both take the exclusion set —
otherwise an excluded path makes the two disagree forever and queues a
full scan on every launch. Deleting a row cascades to queue_tracks, so
the removal calls the same CompactQueue hook RemoveLibrary does.
Also lands the requested badge: library-status-indicator is a button
again where it can act, utils/library-status.ts states once what owning
and wanting mean, and the long-declared queued state finally has a
producer.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UDCbcCZQepnpSQYJ6SxxZm
An event carries what a consumer needs so it never has to invalidate.
- `library-store` answers `TrackPlayCountChanged` by patching one
track, replacing the tracks array (consumers key memoized caches on
its identity) while sharing every unchanged Track — instead of
discarding four collections and refetching 25 MB per song.
- `playlist-store` answers `PlaylistTracksChanged` by refetching the
one playlist the event names, plus the summaries, since `UpdatedAt`
is a sort key. 2 668 kB and 172 ms for one heart, against 2.0 kB. It
falls back to a full invalidate only where a patch cannot be shown
to be equivalent: no id, a cold cache, an unknown id, or a fetch
already in flight. And a store with no subscriber fetches nothing —
the singleton's constructor used to put every track of every
playlist on the path to first paint for a view the user might never
open.
- `library-store` guards every fetch with a cache generation and holds
the request itself instead of deriving a promise from subscriber
notifications, which fixes the library-filter race and the
never-settling waiter together: they are the same bug seen from
either end.
- `explore-cache`'s two art caches are bounded, sharing one exported
cap constant — the artist photo's data URL is held by both, so
capping either alone frees nothing at all and reads as a fix that
did not work.
- `search-store` deliberately does *not* coalesce its notify: deferring
makes a subscriber that unsubscribes synchronously after a `setTerm`
miss the notification entirely, which is a semantic change rather
than an optimisation, and this is the store on the keystroke path.
- `selection-controller` retains its keys across a refetch rather than
clearing them, since they are file paths and those survive one, and
`getSelectedKeysOrdered()` gains an early exit. It stays a walk of
the list: an index goes stale on any re-sort, re-filter or refetch
while a file path survives all three, and 3 ms does not buy a
silently mis-ordered queue insert.
Autotag: detect "junk drawer" folders with no artist/album consensus
and split them into synthetic per-cluster groups instead of forcing
one match on an unrelated pile of tracks; repair tagging_items rows
left behind by a prior scan orphan-cleanup gap.
Explore: fix an exact artist-name search being drowned out by its own
catalog entries in intent-prior scoring, and prune stale in_library
bookkeeping left behind when a referenced library row is deleted.
Download: fix a multi-library regression where every import failed
with "no library root configured" — the importer resolved the
library root from a legacy single-library config field that nothing
populates in the current multi-library model. It now resolves the
destination library per-request from the request's own library_id.
Also widen the Soulseek search window (12s -> 20s), measured against
real request history to be missing available peers on live queries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2Agd9af5hE7qzti2ackiS
The HTTP endpoint approach still crashed due to Wails asset server
issues. Replaced with a pure frontend solution: searchLibraryCache()
does a substring match against the libraryStore's cached artists and
albums arrays. This is pure JS — zero Go calls, zero RPC, zero
network — guaranteed instant.
Results appear immediately as the user types. The full MB+LB search
pipeline still runs via Wails RPC and replaces the library matches
with richer results when done.
Added cachedArtists/cachedAlbums getters to LibraryStore for
synchronous read-only access to the already-loaded data.
Removed the /api/search-local HTTP handler from the backend.
- LibraryStore now listens for TrackMetadataChanged and invalidates all caches
- Track Details context menu item visible for any right-clicked track in all 4 views
- Removed selectionCount === 1 gate from track-list, queue-panel, cover-grid, playlist-details
- Queue store now uses queueMicrotask batching (matching library store pattern)
- Library store adds changeGeneration counter incremented only on actual data changes
- LibraryController checks changeGeneration before requestUpdate, skipping loading-only transitions
- Reduces unnecessary component re-renders during data loading cycles
- Library store notify() coalesces multiple calls per microtask tick into one subscriber notification
- Search input debounces store propagation by 150ms while keeping instant visual feedback
- Empty search input clears immediately for responsive UX
- Remove eagerFetch() call from LibraryStore constructor
- Add deferEagerFetch() that waits for DOMContentLoaded event
- App shell renders before backend data roundtrips begin
- All 4 data types (tracks, albums, artists, genres) still loaded eagerly
- invalidate() still calls eagerFetch() directly for post-scan refresh
album artist gets populated with artist as fallback (frontend also uses
this as display name fallback for albums). added scroll position
persistence when switching main views. also added frontend cache for
faster switching.
yonlu
logan