yellowjacket/.planning/plans/completed/006-orientation-fixes.md

006 — Orientation fixes: knowing where you are and what you're looking at

Status: implemented Branch: main Created: 2026-08-11 Follows: 005-agent-development-harness

Problem

Six reports from using the app, which turned out to be one theme with six faces: the UI knew things it did not say.

1. Some track names in the track list were links, most were not. The rule (has both a release-group and a recording MBID) was invisible, so the list looked randomly broken.
2. Opening an album sometimes showed the full catalog tracklist and sometimes only the tracks the user owned, with nothing on screen distinguishing the two — or distinguishing either from "still fetching".
3. The same on artist pages: a discography that was the artist's, or a discography that was the user's shelf, rendered identically.
4. "Check now" on the requests list appeared to do nothing, because it honoured each request's retry backoff — a request searched an hour ago was not due, so a deliberate button press produced silence.
5. Pressing M muted playback and left the volume indicator unchanged, because mute does not change the volume number and VolumeChanged carried nothing else.
6. The home page did not exist. The sidebar had a Home item; it fell through to "Coming soon: home".

What shipped

Backend

• events.MuteChanged (bool), emitted alongside VolumeChanged so the UI has something to react to when silence is the only thing that changed. Player.Muted() for symmetry; MuteToggle now takes the speaker lock and refuses politely when no streamer exists.
• download.Reconciler.RunNow — a forced pass that ignores backoff, backed by a new ListWantedDownloadRequests query. RunOnce (the loop) still honours it: the backoff is a promise to the providers, not to the user, and a person pressing a button is the schedule. Summary gained Waiting and NoProviders so "nothing happened" can be reported with a reason.
• backend/home — the shelf builder, with queries in sql/queries/home.sql that return album ids only, joined back to GetAllAlbumsWithDetails in Go rather than restating the album projection six times. A shelf with nothing behind it is omitted.

Frontend

• explore-link.ts rewritten: a name always goes somewhere. No MBID means the library page for the same album/artist (both detail views already accept a local id), resolved through the library store, with an untagged track highlighted by title instead of by recording MBID. Links now fire on a genuine single click only — see below.
• <catalog-scope-notice> — one banner, four states (catalog, loading, library, unavailable), used by both detail pages. The album and artist pages grew an explicit catalogPending / catalogLoaded pair, because loadingReleases already meant "something is renderable" and a library stand-in satisfies that.
• Artist page: an empty BrowseReleaseGroups no longer wipes the library-hydrated discography — an empty catalog answer means "not indexed yet", not "released nothing".
• Downloads: a no-client banner, per-request "next check in …", honest idle summaries, and copy that says the retry schedule exists.
• <home-view>: shelves as horizontal rows; a cover opens the album, a play button plays it.

The one thing worth remembering

Making every track name a link broke double-click-to-play, and the e2e playback suite caught it: the title is the widest thing in a row, so the first click of the double-click landed on the link and navigated away. Fixed in one place — singleClick() in explore-link.ts holds the navigation for one double-click interval (250 ms) and drops it if a dblclick arrives, while leaving the dblclick itself to bubble to the row. Rows do not need to know links exist.

This is exactly the failure mode plan 005's e2e tier was built for; it was invisible before the change because the seeded fixture library has no MBIDs, so no track name was a link.

Verification

make lint (3 configs), make test (3 passes), make ui-test (329 passing, up from 313), make e2e (23 passing, up from 19 — four new home-page specs), tsc --noEmit, and manual verification of all six items in the running app via make dev-headless + playwright-cli.