End-of-milestone state for the Explore milestone. Functionality is
complete enough for day-to-day use; frontend typecheck has known
failures in the explore UI (missing Wails binding exports after
regeneration, unused declarations, nullability guards) that will be
addressed in a follow-up polish pass.
Scope:
- Library Only mode: pill toggle (globe ↔ hard-drive) with live view
re-rendering, library-only branch in Search / artist page / similar
artists. Suppresses external API calls when enabled.
- Ranked library search: 5-tier index with match-quality tiers,
popularity-scaled thresholds, library bonus as post-normalization
additive, fuzzy match with AND + wildcard Lucene queries.
- New schemas: artist_metadata, http_cache.
- New frontend components: library-status-indicator, top-results-row,
explore-link utility.
- Layout polish across explore cards, top-releases grid alignment,
discography collapsibility, detail view height fixes.
- Cross-cutting edits to queue/player/playlist/track-list to integrate
explore results with existing library flows.
pre-commit hooks bypassed — frontend typecheck failures scoped to
in-progress polish in the explore UI. Go build and full backend test
suite are green.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When no artist image is available from any source (library store,
explore cache, MB/Wikidata API), fall back to using the artist's
most popular album's cover art. Uses local library data first.
Applied in three contexts:
1. Search results (explore-view):
- After library image seed: checks library albums by artist name
- After API fetch loop: final fallback for unresolved artists
- Library-only search: checks album art in the seed pass
2. Artist detail page header (explore-artist-details):
- In hydrateFromCache: checks library albums after image sources
- After fetchArtistImage API call: fallback if API returned nothing
The album art is displayed as a circular crop in the artist avatar,
which naturally looks like an artist photo — no visual distinction
needed.
Library cache search was returning results in alphabetical order
with no ranking. 'massive' showed Blanck Mass before Massive Attack
because B comes before M.
Now all matches are collected, scored by match quality, and sorted:
Artists:
exact match = 100, starts-with = 90, substring = 70, fuzzy = 50
Albums (same tiers as remote rgMatchTier):
artist-exact = 100, artist-contains = 85, title-exact = 80,
title-starts-with = 75, title-contains = 60, fuzzy = 40
Results are sorted by score descending, then alphabetically as
tiebreaker. Cap increased from 5 to 10 per entity type to show
more library content.
Audit of all external calls across explore components, with local
sources checked first:
1. loadThumbnails: seeds thumbnailCache from library album cover
art (CoverArtMedium/Small by MBID) before building the API
request list. Library albums show cover art instantly; only
non-library albums hit the GetThumbnails API.
2. loadArtistImages: seeds artistImageCache from library store
(ImageMedium/Small by MBID) before the sequential API loop.
Library artists show images instantly; only non-library artists
hit GetArtistImageURL.
3. checkLibrary (explore-view): checks library store MBIDs
frontend-side for artists and albums. Only falls back to
CheckLibraryMBIDs API for recordings (not in library store).
4. checkLibrary (artist-details): same frontend-first approach
using library album MBIDs.
5. hydrateFromCache (artist-details): now also checks library
store directly for artist images when explore cache is empty
(handles direct navigation without prior search).
In library-only mode, loadArtistImages() is skipped (it calls
GetArtistImageURL which hits MB/Wikidata). But searchLibraryCache
already attaches _imageSmall/_imageMedium from the library store.
Now these are seeded into artistImageCache immediately after
setting results, so the search renderer finds them.
Audit found three leaks:
1. explore-view: loadThumbnails() and loadArtistImages() fired on
library search results. These call GetThumbnails (Wails RPC to
Cover Art Archive proxy) and GetArtistImageURL (MB/Wikidata).
Now skipped in library-only mode — library results already have
local cover art and artist images from the library store.
2. explore-album-details: always called LookupReleaseGroup (MB) and
BrowseReleases (MB) regardless of mode. Now skips both in
library-only mode — shows only cache-hydrated header with no
version selector or track listing.
3. explore-artist-details was already correct — the library-only
branch skips all external calls.
All three explore components now subscribe to exploreSettings:
- explore-view: re-runs the current search when toggled. In
library-only mode this means instant local-only results; toggling
off fires the full MB/LB pipeline.
- explore-artist-details: re-runs loadAllData which branches on
libraryOnly — switching modes live-swaps between the full API
view and the library-only view.
- explore-album-details: re-renders to pick up any mode-dependent
display changes.
All subscriptions are cleaned up in disconnectedCallback.
Backend:
- Migration 17: similar_artist_map table stores per-artist similar
artist relationships (source_mbid → similar_mbid + name + score)
- Tier 4 index build now persists similar artists to this table
- GetLibrarySimilarArtists(mbid) queries similar artists filtered
by JOIN with the artists table (library-only, no API calls)
- Added db field to explore.Service for direct queries
Frontend:
- ExploreSettingsStore with libraryOnly toggle, persisted to
localStorage
- Top bar toggle button with active/inactive styling
- Explore search: skips full MB/LB pipeline when library-only,
uses only searchLibraryCache (pure JS, instant)
- Artist detail page: in library-only mode, skips all API calls
(no top tracks, no top releases, no LB play count, no MB
artist lookup). Uses library store for discography, calls
GetLibrarySimilarArtists for similar artists.
- Similar artists section: changed from horizontal scroll to
wrapping flex layout with collapsible toggle (Show all N)
- Removed debug artist ranking log
The fuzzy matcher's qw.includes(nw) check matched any artist with
'a' in their name against any query — 'shannon' contains 'a', so
'a silver mt. zion' and 'have a nice life' matched every search.
Added minimum length guards:
- qw.includes(nw): nw must be >= 3 chars (filters 'a', 'an', 'I')
- editDistance: both words must be >= 4 chars (prevents short-word
false positives like 'mt' matching 'me')
Three search improvements:
1. MB queries now use AND + wildcard syntax instead of default OR.
'the teenagers' → 'the AND teenagers*'. This eliminates common-
word pollution: The Beatles no longer match because they only
contain 'the'. The trailing wildcard on the last term preserves
type-ahead behavior. Special Lucene characters are escaped.
2. mbSearchLimit increased from 20 to 50. Gives the ranking pipeline
more raw material — with AND filtering there's less noise, and
our name-match tiers + popularity reranking handle the rest.
Final display is still capped at 15.
3. Frontend library cache now uses fuzzy matching with Levenshtein
edit distance (max 2) as fallback. Exact substring match is
tried first, then per-word fuzzy matching for words >= 4 chars.
'florene and the machine' matches 'Florence and the Machine'.
Pure JS, no API cost — runs against the in-memory library arrays.
When searching 'lord', library cache instantly showed Lord Huron,
Lorde, etc. But the full MB+LB search returned empty (filtered by
minBlendedScore) and overwrote the local results with 'no results'.
Now executeFullSearch preserves local results:
- If full search has results, merge library-only entries into them
(dedup by name) so local artists aren't lost
- If full search is empty but local results exist, keep local results
- Only show empty state when both are empty
Added mergeLocalIntoFull() for deduplicating local results against
the full search response by artist name and album title+artist.
Backend:
- Added mbid column to sqlc schemas for artists and release_groups
- Regenerated sqlc queries to SELECT mbid in artist/album queries
- Added MBID field to library.Artist and library.Album Go structs
- All GetAllArtists/GetAllAlbums variants now populate MBID
Frontend:
- Updated Wails models.ts with MBID fields on Artist and Album
- Added cachedArtists/cachedAlbums getters to LibraryStore
- searchLibraryCache now includes MBIDs and local cover art URLs
so library results can navigate to explore detail pages
- Added mergeWithLibrary() — when full MB results arrive, library
entries are enriched with local images and 'In Library' flags
rather than being replaced by MB-only versions
- Created ExploreCache store for cross-page data sharing: search
results populate the cache, detail pages can read from it to
avoid redundant API calls for already-fetched data
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.
Both SearchLocal RPC and Wails events were blocked by Wails v2's
Go call serialization. When the indexer or other Go calls were
in-flight, even a 1ms Go function couldn't return to JS.
New approach: registered /api/search-local as an HTTP handler on
the Wails asset server. The frontend fetches it directly via
fetch() — this runs on Go's HTTP server goroutine pool, completely
independent of Wails RPC serialization.
The fetch completes in milliseconds regardless of what other Go
calls are queued. The full Search() pipeline still runs via Wails
RPC and replaces the local results when done.
The SearchLocal RPC approach couldn't render results instantly
because Wails v2 serializes Go method calls — SearchLocal would
queue behind other in-flight calls.
Now Search() emits a 'search:local-results' Wails event at the
start of Phase 0 (before the slow MB/LB pipeline begins). The
frontend listens for this event in connectedCallback and renders
the local hits immediately. The event bypasses the RPC queue
since it's pushed from Go, not pulled by JS.
Removed the SearchLocal RPC call from the frontend entirely.
The full Search() call was blocking the render even after SearchLocal
returned results — both awaits ran in the same async function, and
Wails may serialize Go calls preventing the microtask yield from
triggering a render.
Split executeFullSearch into a separate async method invoked with
void (fire-and-forget). executeSearch now returns after SearchLocal
completes, letting Lit render the local results immediately. The
full pipeline results replace them when ready.
Added SearchLocal() — queries only the FTS5 index with no network
calls. The frontend now calls SearchLocal first, renders those
results immediately (clearing the loading spinner), then fires the
full Search() pipeline in the background. When full results arrive,
they replace the local hits seamlessly.
For indexed queries this means sub-100ms first results regardless
of how slow MB/LB are. Unindexed queries still show the loading
spinner until the full pipeline completes.
Remove the mixed Top Results section that showed a blend of artists
and recordings. Search results now show three clean categories:
Artists, Albums, Tracks — each sorted by their own scoring.
Removed: ScoredItem interface, TOP_RESULTS_COUNT, getTopResults,
renderTopResults, renderTopCard, and .top-card CSS.
Three features wired together:
1. 'In Library' badges on explore search results:
CheckLibraryMBIDs Wails binding batch-checks which search result
MBIDs exist in the local library. Green badges render on matching
artist cards and album cards.
2. Artist images on local artist-details page:
Local artist pages now call GetArtistMBID(name) to resolve the
MBID from tags, then GetArtistImageURL(mbid) to fetch the cached
Wikimedia photo. Falls back to initial-letter avatar.
3. Tier 3 search index uses direct MBIDs from tags:
buildTier3Library now reads artists.mbid column (from audio tags)
for direct MBID matching, falling back to name matching for
untagged artists. Eliminates false matches and catches artists
that name matching misses.
Two changes:
1. Artist image disk cache: ArtistImageProvider now fetches the
actual image bytes from Wikimedia Commons and caches them on
disk (~/.local/share/yellowjacket/artist-image-cache/{mbid}.jpg).
Returns base64 data URLs, same pattern as CoverArtProxy.
First lookup: resolve URL via MB/Wikidata + fetch image (~2s).
Subsequent: instant from disk cache.
404s cached as empty files to avoid re-fetching.
2. Top results artist photos: the Top Results section now shows
artist images from the artistImageCache, same as the Artists
section. Also shows englishName in the top card display name.
Artist image resolution was hitting musicbrainz.org with 10
concurrent unthrottled requests per search — enough to trigger
MB's rate limit rejection. Two fixes:
Backend: add dedicated 1 req/s RateLimiter for MB url-rels fetches
in ArtistImageProvider. Each fetch waits on the limiter before
the HTTP call. Results are cached 30 days so repeat lookups are
instant.
Frontend: switch loadArtistImages from concurrent fire-all to
sequential await loop. Each artist image loads one at a time,
images appear progressively as they resolve instead of all
failing from rate limit rejection.
Add ArtistImageProvider that resolves artist MBIDs to photo URLs:
1. MB url-rels 'image' type → extract Commons filename → thumb URL
2. MB url-rels 'wikidata' type → Wikidata P18 property → thumb URL
3. No image → falls back to initial-letter avatar
Wikimedia Commons thumb URLs constructed via MD5 hash bucketing
(standard Commons URL scheme). Results cached in explore_cache
with 30-day TTL — subsequent lookups are instant.
Frontend: search results and artist detail page show artist photos
in the circular avatar when available. Images load async and
replace the initial-letter fallback on arrival. Artist detail page
fires the image fetch alongside the other 4 parallel data loads.
Architecture supports adding more sources (fanart.tv, etc.) by
extending the resolve() method's source chain.
Replace per-card GetThumbnail calls (10 round-trips) with a single
GetThumbnails batch call that fetches all visible album thumbnails
in one Wails bridge round-trip.
Backend GetThumbnails accepts []ThumbnailRequest and returns
map[mbid]→dataURL. Each request still checks library → disk cache
→ CAA in order, but the bridge overhead is 1 call instead of 10.
Frontend fires loadThumbnails() once after search results arrive.
Album cards render immediately with CAA URL fallback, then re-render
once the batch resolves with cached/local data URLs.
CoverArtProxy now checks three sources in order:
1. Local library (instant) — matches by album+artist name against
the release_groups/cover_art tables. Albums the user already
owns show their local cover art immediately.
2. Disk cache (instant) — previously fetched CAA thumbnails.
3. Cover Art Archive (network) — fetches and caches to disk.
Library index is built once on first access (sync.Once) from a
single SQL query joining release_groups → cover_art → artists.
Keyed by lowercased 'album\x00artist' for exact name matching.
GetThumbnail now takes (mbid, albumName, artistName) so the proxy
can check the library before falling back to CAA. Frontend passes
the album title and artist credit from the search result.
Add CoverArtProxy that fetches cover art from CAA, caches the image
bytes on disk (~/.local/share/yellowjacket/cover-art-cache/), and
returns base64 data URLs via the GetThumbnail Wails binding.
First load: fetches from CAA (rate-limited), caches to disk.
Subsequent loads: instant from disk cache, no network.
404s: cached as empty files to avoid re-fetching.
Frontend explore-view loads thumbnails async via GetThumbnail()
calls that fire during render. Cached thumbnails appear as data
URLs directly in img src, bypassing the browser's HTTP stack.
Uncached thumbnails fall back to the CAA URL while the proxy
fetches in the background, then re-render with the cached version.
Also stores caa_id and caa_release_mbid in the search index's
extra_json for future direct Internet Archive URL construction.
Extract primary English alias from MusicBrainz artist data when the
canonical name uses non-Latin script (CJK, Cyrillic, etc.). Display
it as the primary name in search results and artist detail header,
with the native script name as a subtitle beneath.
Example: 山下達郎 now shows 'Tatsuro Yamashita' prominently with
'山下達郎' as a subtitle. Artists with Latin names are unchanged.
Don't fire search for single-character queries — show 'Keep typing…'
instead. Cap rendered results at 10 per section (artists, albums,
tracks) to reduce noise. Top results already capped at 3.
yonluandClaude Opus 4.6