feat(explore): demote the album page's version selector to a disclosure

Choosing which pressing you are looking at is an advanced,
metadata-repair task, and it sat directly above the tracklist with a
heading, a `<select>` and a paragraph explaining how our clustering
picks a "standard version" by weighing release count, status and date.
That is a sentence about our own heuristic in the most valuable space
on the page.

It is now "Other versions of this album (N)" below the tracklist: a
real `<button aria-expanded aria-controls>` inside the heading that
names the section, with the body rendered unconditionally and toggled
with `hidden`, because `aria-controls` has to name an element that is
in the DOM. Both rules are `config-section`'s rather than new ones.
It is demoted, not removed — matching the wrong release is a real
problem and this is how it gets fixed.

**Two more blocks shared that slot and neither was guarded.** The
selector at least had `distinctTracklistCount() <= 1`; the
`Versions / Loading releases…` spinner and the `Versions / <error>`
block did not, so both took the primary position on every album
regardless of whether there was ever going to be a choice. The spinner
said what `renderTracklist` was already saying about the same fetch, so
it is gone. The error was the one `catalog-scope-notice` shows at the
top of the page with a retry — every path that sets `errorReleases`
also sets `catalogFailed`, the only route to `unavailable`.

That error is what made this a rewrite rather than a move.
`renderTracklist` returned `nothing` on `errorReleases` and leaned on
the selector's own block to have said it, and a control inside a
collapsed disclosure cannot be a page's error surface. The failure
belongs to the list that is missing because of it, so that is where it
is drawn.

**What must not be lost is which version is on screen.** The default is
what the header already describes, so saying it on every album would be
this issue's own complaint one size smaller. `defaultVersionKey` is the
test: a line appears above the tracklist only once someone has chosen
another, naming it and offering the way back. The ★ and the words "in
your library" survive unchanged inside the panel, and the panel does
not close when the selection changes — a panel that shuts on use cannot
be used twice.

The `<select>` also loses an `aria-label` of "Select release version"
that outranked its own visible `<label>Version</label>`, which is a
label not in the name.

Verified against the running app as well as the suite: the collapsed
page, the open panel, a chosen version and 390px width all read
correctly, and the shell still measures 390 in a 390 viewport.

Closes #17

.gitea/workflows/android-apk.yml

@@ -139,6 +139,23 @@ jobs:
             echo "skip=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+
+          # Nor is a prerelease, and this trigger is `v*`, which matches
+          # `v0.4.0-beta.1`.  Two reasons it is worst here.  The APK goes
+          # to the *generic* registry, which is readable without
+          # credentials so Obtainium can poll a plain URL — a beta would
+          # be offered to every device on it.  And the versionCode maths
+          # below splits on dots and would read "1" out of "0-beta",
+          # producing a code that is wrong rather than a build that
+          # fails: Android orders releases by that integer and refuses
+          # anything not greater than what is installed.
+          case "$v" in
+            *-*)
+              echo "v$v is a prerelease; not publishing an APK for it"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
           echo "skip=false" >> "$GITHUB_OUTPUT"
 
           # Android orders releases by an integer and refuses anything

.gitea/workflows/arch-package.yml

@@ -72,6 +72,22 @@ jobs:
             exit 0
           fi
 
+          # A prerelease is not a shipment either, and this trigger is
+          # `v*` — which matches `v0.4.0-beta.1`.  Nothing produces one
+          # today; the guard is here because the thing that would is
+          # semantic-release's `prerelease: true` channel, a one-line
+          # change in .releaserc.yml whose blast radius is four public
+          # package channels.  Same argument as release.yml's
+          # `chore(release):` guard: cheap, against something a future
+          # edit turns on somewhere else entirely.
+          case "$v" in
+            *-*)
+              echo "$v is a prerelease; not packaging it for pacman"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
           echo "skip=false" >> "$GITHUB_OUTPUT"
           echo "tag=$v"     >> "$GITHUB_OUTPUT"
           echo "building $v"

.gitea/workflows/desktop-assets.yml

@@ -95,6 +95,19 @@ jobs:
             exit 0
           fi
 
+          # Nor is a prerelease, and this trigger is `v*`, which matches
+          # `v0.4.0-beta.1`.  The mildest of the four — assets attach to
+          # the prerelease's own Gitea release and no package manager
+          # reads them — but four workflows sharing one trigger should
+          # share one answer about what a shipment is.
+          case "$v" in
+            *-*)
+              echo "$v is a prerelease; not attaching desktop assets"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
           echo "skip=false"   >> "$GITHUB_OUTPUT"
           echo "tag=$v"       >> "$GITHUB_OUTPUT"
           echo "version=${v#v}" >> "$GITHUB_OUTPUT"

.gitea/workflows/homebrew-formula.yml

@@ -56,6 +56,18 @@ jobs:
             echo "skip=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+
+          # Nor is a prerelease, and this trigger is `v*`, which matches
+          # `v0.4.0-beta.1`.  It matters most here of the four: the tap
+          # is public, and `brew upgrade` would offer a beta to everyone
+          # on it.
+          case "$VERSION" in
+            *-*)
+              echo "$TAG is a prerelease; not syncing it to a public tap"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
           echo "skip=false" >> "$GITHUB_OUTPUT"
 
           TARBALL="${SOURCE_TARBALL_BASE}/${TAG}.tar.gz"

.gitea/workflows/release.yml

@@ -1,11 +1,36 @@
 name: Release
 
 # The sixth workflow, and the one that decides whether the other three
-# run at all.  On every push to main it reads the Conventional Commits
-# since the last tag, and if any of them is releasable it writes the
-# changelog, pushes the tag, and creates the Gitea release whose body is
-# that changelog section.  The publishing workflows are keyed on `v*`, so
-# the tag push is what starts them.
+# run at all.  It reads the Conventional Commits since the last tag, and
+# if any of them is releasable it writes the changelog, pushes the tag,
+# and creates the Gitea release whose body is that changelog section.
+# The publishing workflows are keyed on `v*`, so the tag push is what
+# starts them.
+#
+# **It is triggered by hand, and there is deliberately no `push`
+# trigger.**  There was one, on `main`, which made the trigger "a PR was
+# merged" and nothing else: eight releases in twenty-two hours
+# (v0.0.1 -> v0.3.1) for one session's work, each fanning out to four
+# publishers on a runner with capacity 1, so ~40 packaging jobs shipped
+# three issues and ordinary PR CI queued behind them.  A version per
+# merged PR is a version per unit of *work*, not per *shipment*, and
+# pacman, Homebrew and Obtainium see every one.
+#
+# Nothing else had to change to batch them: semantic-release already
+# reads every commit since the last tag, so five fixes and two feats
+# become one minor release with all seven in the notes.  Release
+# frequency was only ever how often this file fired.
+#
+# This is the rule `index-artifact.yml` states and is the other instance
+# of: **a job that mutates state which cannot be rebuilt in ten minutes
+# is triggered deliberately, not by a push.**  A release here is a tag,
+# a Gitea release, an Arch package, a Homebrew formula, a signed APK and
+# desktop assets — and an Android version going backwards costs the user
+# their library (docs/android-release.md).
+#
+# A schedule was considered and rejected: a cron batches without anyone
+# having to remember, but it puts the decision back on a timer, which is
+# the thing being removed.
 #
 # **Why the tag is pushed with PACKAGE_TOKEN and not the Actions token.**
 # Gitea, like GitHub, does not start a workflow from a ref pushed by a
@@ -19,9 +44,12 @@ name: Release
 # instead.
 
 on:
-  push:
-    branches: [main]
   workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Report what would be released and stop"
+        required: false
+        default: "false"
 
 # Cutting a tag is not a thing to cancel halfway: a superseded run must
 # finish, not be killed between `git push --tags` and the release POST.
@@ -163,14 +191,32 @@ jobs:
       # been right, the tag would have been right, every job would have
       # been green, and the release body would have been empty.  Check the
       # notes, not the exit code, before moving any of these.
+      # The point of a manual trigger is deliberateness, and deliberate
+      # means being able to look before pulling the lever.  `--dry-run`
+      # reports the version and the notes and writes nothing: no tag, no
+      # release, no publishers.  `make release-dry` is the same answer
+      # locally; this is it from the runner, against the same commit and
+      # the same tag history, which is what actually decides.
       - name: Run semantic-release
         if: steps.guard.outputs.skip == 'false'
         working-directory: /src
+        env:
+          DRY_RUN: ${{ inputs.dry_run }}
         run: |
           set -eu
           git config user.name  "yellowjacket-ci"
           git config user.email "yj@yellowjacket.app"
 
+          # Anything but a literal "true" releases for real.  A typo in a
+          # dispatch box must not silently turn a shipment into a no-op
+          # that reports success — the failure worth avoiding is the one
+          # where nothing happens and the run is green.
+          dry=""
+          if [ "${DRY_RUN:-false}" = "true" ]; then
+            echo "DRY RUN — no tag will be pushed and no release created"
+            dry="--dry-run"
+          fi
+
           npx --yes \
             -p semantic-release@25 \
             -p @semantic-release/commit-analyzer@13 \
@@ -178,5 +224,5 @@ jobs:
             -p @semantic-release/changelog@7 \
             -p @semantic-release/exec@7 \
             -p conventional-changelog-conventionalcommits@9 \
-            semantic-release \
+            semantic-release $dry \
               --repository-url "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git"

.gitea/workflows/unclaim.yml

@@ -0,0 +1,107 @@
+name: Unclaim
+
+# A `Closes #N` footer in a commit body closes the issue on merge — and
+# leaves `Status/In Progress` on it, because Gitea's auto-close touches
+# state and nothing else.  So #100 was closed and simultaneously marked
+# as being actively worked on, and `scripts/issue.sh close` (which does
+# drop the label) is exactly the thing the footer exists to avoid
+# calling.
+#
+# **This hooks the close, not the merge.**  Stripping the label in the
+# PR would work and would be a per-PR habit; habits are what the footer
+# removed.  `issues: [closed]` covers every path an issue can close by —
+# the footer on merge, `issue.sh close`, someone clicking Close in the
+# web UI — and asks nothing of anyone at any of them.
+#
+# **Reopening deliberately does not restore it.**  Reopening says the
+# work was not finished, not that somebody is at a keyboard doing it
+# now; the claim gets re-made by whoever picks it up.
+#
+# **This is not instant, and should not be described as it.**  The
+# runner has capacity 1 and is shared with an index build that can hold
+# it for three hours, so a label tweak can queue behind one. Stale for
+# an afternoon beats stale forever, which is what it was.
+#
+# The audit that answers "is this still firing" stays in CLAUDE.md and
+# is one command:
+#
+#   ./scripts/issue.sh list --state closed --label "Status/In Progress"
+#
+# A workflow that silently stops working is the failure mode this whole
+# area has already produced once.
+
+on:
+  issues:
+    types: [closed]
+
+jobs:
+  unclaim:
+    runs-on: ubuntu-latest
+    container:
+      image: ubuntu:24.04
+
+    steps:
+      - name: Drop the claim label
+        # **Inside a container the act runner selects `sh`, not bash**, so
+        # `set -o pipefail` fails the job on its second line with "Illegal
+        # option" and the step never reaches the API.  `homebrew-formula.yml`
+        # carries the same `set -euo pipefail` without trouble because it
+        # runs with **no container**, on the host image where bash is the
+        # default — so "another workflow does it" is not evidence here.
+        shell: bash
+        env:
+          # The automatic Actions token, as release.yml uses for the
+          # floor tag.  It needs no more than write access to this repo.
+          TOKEN: ${{ secrets.GITEA_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          ISSUE: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+
+          # `ca-certificates` is named because `--no-install-recommends`
+          # skips it, and `ubuntu:24.04` ships no CA bundle of its own —
+          # so curl comes up unable to verify TLS against our own Gitea
+          # and fails with "error setting certificate file" (exit 77).
+          # Every other containerised workflow here spells it out for the
+          # same reason; this one did not, and cost a release cycle.
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends \
+            ca-certificates curl jq >/dev/null
+
+          label_id=$(
+            curl -sSf -H "Authorization: token $TOKEN" "$API/labels?limit=100" |
+              jq -r '.[] | select(.name == "Status/In Progress") | .id'
+          )
+
+          # The label not existing is a repo somebody reorganised, not a
+          # failure of this run — say so and stop, rather than failing a
+          # job on every close from then on.
+          if [ -z "$label_id" ]; then
+            echo "unclaim: no 'Status/In Progress' label in this repo; nothing to do"
+            exit 0
+          fi
+
+          # DELETE is idempotent here: an issue that never carried the
+          # label answers the same as one that did, which is what makes
+          # this safe to run on *every* close rather than only the ones
+          # that were claimed.
+          # The body is captured, not discarded, so a refusal is
+          # diagnosable from this log alone.  Whether the automatic
+          # token carries issue-write scope is still unproven, and
+          # "DELETE returned 403" without Gitea's own sentence costs
+          # another merge to find out which of the two it is.
+          body=$(mktemp)
+          code=$(
+            curl -sS -o "$body" -w '%{http_code}' -X DELETE \
+              -H "Authorization: token $TOKEN" \
+              "$API/issues/$ISSUE/labels/$label_id"
+          )
+
+          case "$code" in
+            204) echo "unclaim: #$ISSUE is closed and unclaimed" ;;
+            *)
+              echo "unclaim: DELETE returned $code for #$ISSUE" >&2
+              cat "$body" >&2
+              exit 1
+              ;;
+          esac

.pi/journal.md

@@ -1,118 +0,0 @@
-# Work log
-
-Temporal memory: what happened and what's next. Structure lives in
-`CLAUDE.md`, operational instructions in `.pi/skills/yellowjacket-dev/`,
-measured discoveries in `.planning/NOTES.md`. Don't duplicate those here.
-
-## Current state
-
-Plan 005 (agent development harness) is **complete — all seven
-phases**. Everything from phase 1 onward is still **uncommitted**: one
-large but coherent working-tree diff, nothing pushed.
-
-All four tiers verified green from a cold, cleaned state:
-`make ui-test` 313 passed, `make lint` 0 issues × 3 configurations,
-`make test` green × 3 passes, `make e2e` 19 passed. Both CI jobs
-verified green in a bare `ubuntu:24.04` container, including 19/19 on
-WebKit.
-
-**Committed and pushed** as `5ca6cad` (the harness) + `ccacd67` (a CI
-fix), and **green on the real runner**: job `check` ~4 min, job `e2e`
-~3 min with 19/19 chromium *and* 19/19 webkit. One commit rather than
-seven because the working tree was the end state, not per-phase
-snapshots — `Makefile`, `CLAUDE.md` and `lefthook.yml` are touched by
-nearly every phase, so a split would have been fabricated history.
-
-Still unverified, because no run has failed yet: the
-`actions/upload-artifact` step (`continue-on-error`, so it cannot mask
-a real failure) and whether pnpm honours `npm_config_store_dir` for
-store caching. Worth checking the next time a spec legitimately fails.
-
-- [ ] `gitea_ci`'s `job_logs` returns 404 on Gitea 1.27.1 — the endpoint
-      is not exposed. Logs come from the VPS instead: `zstdcat` the file
-      under `gitea/actions_log/<owner>/<repo>/<xx>/<task_id>.log.zst`,
-      and note `zstdcat` is not in the gitea container, so
-      `docker cp` it out first. Job status is `action_run_job.status`
-      (1 success, 2 failure, 4 skipped, 5 waiting, 6 running).
-      Probably belongs in the `gitea` skill, not here.
-
-Open items deliberately not fixed: WAV tags are write-only
-(`TestWAVTagsAreNotReadableYet`), `themeStore.loadFromBackend`'s failure
-handler cannot recover, `backend/playlist` has no CRUD suite.
-
-## Log
-
-### 2026-08-11 — cold skill run, then phase 7 (CI)
-
-- **Followed the skill cold first**, as the last session asked. It
-  works: app up from a wiped `.dev/`, an undocumented flow driven
-  (queue panel + shuffle, asserted on `QueueModeChanged`), stopped —
-  ~1 minute, no dead ends. One real config bug: `outputDir` in
-  `.playwright/cli.config.json` resolves against **cwd**, not the
-  config file's directory (only `initScript` does that), so snapshots
-  were landing above the repo and a *stale* one from the previous
-  session answered `ls -t` instead. That cost a DOM walk to disprove a
-  regression that did not exist. Four smaller doc gaps fixed
-  (`sandbox-seed` already runs `testdata`; `ui-setup`/`e2e-setup` were
-  undocumented prerequisites; `snapshot` prints a path; `dev-stop`
-  leaves the browser open), plus `dev-headless.sh`'s own banner, which
-  was suggesting the bare `window.go` call its next paragraph warns
-  against.
-- **Built both CI jobs as container scripts before writing any YAML**,
-  then transcribed the YAML back out and re-ran it to prove the
-  transcription. Push-and-see is a bad loop on a self-hosted runner.
-- **It found a real bug immediately**: `make lint` omitted
-  `webkit2_41` on all three passes, so it was linting configurations
-  nothing builds. Invisible on Arch (which still ships
-  `webkit2gtk-4.0.pc`), fatal on Ubuntu 24.04. Tag sets now match
-  `make test`.
-- **Both open decisions settled by measurement**: ALSA `null` PCM for
-  audio (no daemon; the elapsed clock really advances), dead-address
-  stub for the explore artifact (and setting it for the *app* run, not
-  just seeding, is worth 8x on suite wall clock). **WebKit is a
-  required step** — it had never been run anywhere, so one throwaway
-  container run replaced a coin flip with 19/19 at +11 s.
-
-### 2026-08-10 — phase 6, pi affordances
-
-- Added `.pi/skills/yellowjacket-dev/` as a directory rather than a flat
-  file: only the description is always in context, so `SKILL.md` stays
-  short enough that reading it whole is never a decision, and the deeper
-  material sits in `references/{harness,fixtures,ui-tier,schema-change}.md`.
-- Settled the CLAUDE.md-vs-skill split **grammatically, not topically**,
-  because a topical split is what rots — every new fact gets two
-  plausible homes. Three docs, three tenses: NOTES.md is past
-  (measured, dated, append-only), CLAUDE.md is present (what the system
-  is), the skill is imperative (what to run). A new paragraph's tense
-  decides where it goes.
-- The five gotchas (binding timeouts, first-run wizard, `pkill -f`,
-  seeds-by-running, WebKit-is-CI-only) went **inline in SKILL.md**, not
-  into a reference: you need them before the failure, not after.
-- Trimmed CLAUDE.md's "Fixtures and the headless harness" section by
-  about half — the command sequences and gotchas it was carrying are now
-  the skill's, and leaving both would have created exactly the duplicate
-  description this repo has a standing rule against.
-- Added `make skill-check` / `scripts/skill-check.sh` + a pre-commit
-  hook: every command in `.pi/**/*.md` must be a real `make` target, so
-  the Makefile stays the source of truth for invocation and a renamed
-  target fails a commit instead of misleading an agent later. Verified
-  it fails (it caught its own not-yet-created target) and passes.
-- Added the `/e2e` prompt template: promoting a hand-driven
-  `playwright-cli` session into a spec is a transcription with four
-  fixed substitutions (refs → testids, sleeps → `waitForEvent`, raw
-  `window.go` → `callBinding`, short fixture → `LONG_TRACK`), plus three
-  runs — pass, pass again, pass after a DB restore — because the usual
-  failure is a spec depending on state the hand-driving left behind.
-- One shell trap: under `set -euo pipefail`, `x="$(make -pqRr | …)"`
-  fails the whole assignment, because `make -q` exits non-zero when a
-  target is out of date and `pipefail` propagates it.
-
-### Earlier
-
-Phases 1–5 of plan 005: fixture generator and manifest, headless launch
-and seeds, the event bridge + `data-testid` pass + `backend/testctl` +
-`e2e/`, the Vitest component tier + `make bindings-check`, and the
-`events.Emit` wrapper with its in-process service-event tests. Recaps
-and the five "verified end to end" blocks are in
-`.planning/plans/active/005-agent-development-harness.md`; the lessons
-are in `.planning/NOTES.md`.

.planning/NOTES.md

@@ -3483,3 +3483,100 @@ public tap.
 
 A guard added today does not protect a tag that points at yesterday. When
 re-pointing a tag, check what the workflows looked like *there*.
+
+## A tag reader looks at exactly one spelling of "total" (measured 2026-08-18)
+
+Writing #16's totals means matching the reader, which is
+`dhowden/tag`, and it is narrower than the specs are:
+
+- **Vorbis (FLAC, OGG): `TRACKTOTAL` and `DISCTOTAL` only.**
+  `vorbis.go`'s `Track()` reads `tracknumber` and `tracktotal` and
+  nothing else, so `TOTALTRACKS` — which several taggers write and
+  which xiph lists — and a `1/12` packed into `TRACKNUMBER` both read
+  back as *no total*. They write successfully. Nothing errors.
+- **ID3v2 (MP3): `TRCK`/`TPOS` as `n/N`**, via `parseXofN`. That is one
+  frame carrying two facts, which is why `applyPositionFrame` reads the
+  existing frame before writing either half.
+- **WAV: nothing at all.** There is no RIFF reader in the module, so a
+  WAV's `id3 ` chunk is invisible to `metadata.ExtractTags` — every
+  field, not just the totals. Filed as #104.
+
+The general shape, and the reason this is written down: a tag written
+under a name the reader does not look at is indistinguishable from one
+never written. So the tests assert the round trip through
+`metadata.ExtractTags` — the reader the *scan* uses — rather than
+through the bytes the writer produced.
+
+## The published catalog artifact predates `total_tracks` (measured 2026-08-18)
+
+```
+$ curl -sSI .../generic/yellowjacket-core-index/latest/core-index.db.zst
+last-modified: Mon, 10 Aug 2026 04:38:16 GMT
+content-length: 75417037
+
+$ sqlite3 core-index.db \
+    "SELECT COUNT(*) FROM pragma_table_info('explore_index') WHERE name='total_tracks';"
+0
+$ sqlite3 core-index.db "SELECT COUNT(*) FROM explore_index;"
+1079667
+```
+
+The column landed in the schema on 2026-08-16; the artifact is from
+08-10, and `index-artifact.yml` is a weekly cron, not a push trigger.
+So `completenessAnswer()`'s catalog fallback answers 0 for **every**
+user today — the machinery is correct and `artifactHasTotals()` is
+doing precisely its job, there is just no data behind it. Same position
+the credit tables are in; both ride on the next publish (#88).
+
+The general point, which is why this is written down rather than just
+fixed: **a probe that makes a column optional also makes its absence
+silent.** `artifactHasTotals` and `artifactHasCredits` are both correct
+and both mean a feature can ship, pass every test, and produce nothing
+for anybody without a single failure anywhere. Checking the *published
+file* is one query and is not implied by any tick in CI.
+
+## "Do I own this" has two answers in the schema, and one of them is a flag (2026-08-19)
+
+Decided while doing #38, and it outlives it because every future
+catalog surface has to pick one.
+
+`explore_index` carries both `in_library` and `local_artist_id` /
+`local_release_group_id` / `local_recording_id`. They are written by
+the same pass (`collectLibraryEntities`), so on a healthy database they
+agree, and the code read them as an OR — `inLibrary || localId > 0` —
+at eight call sites.
+
+They are not the same kind of thing:
+
+- **`local_*_id` is a fact with an owner.** Every query that sets one
+  joins `audio_files`, and `pruneStaleLocalCrossReferences` clears it
+  with an existence test that is a file test in all three cases. It is
+  the same rule `explore-album-details`'s `filePaths` implements, one
+  layer down and computed once per scan.
+- **`in_library` is a ratchet.** `upsertBatch` raises it with
+  `MAX(in_library, excluded.in_library)` and the prune is the only
+  thing that lowers it — gated on the local id being non-null, so a row
+  holding the flag *without* an id is a fixed point nothing can clear.
+  Filed as #118; it still drives search scoring, the popularity-floor
+  bypass and two Explore shelves, so routing the UI around it was not a
+  fix.
+
+What made the choice concrete rather than theoretical: on
+`explore-artist-details` the *same card* used both. The context menu
+gated Play on `localId > 0`; the badge used `inLibrary`. An album with
+the flag and no local row drew a green tick saying it was in your
+library, offered no Play, and — the request item being gated on *not*
+owned — offered no way to ask for it either.
+
+The rejected alternative is worth keeping: batching a real file lookup
+per screenful, the way `credit-store` coalesces. It would have answered
+for **recordings** (`GetFilePathsByRecordingMBIDs`) and most of the
+cards on these surfaces are release groups, so it would have made track
+rows strong, left album cards exactly where they were, and cost a new
+store. The batch that *was* worth adding is a different question —
+`GetAlbumsCompleteness`, "how much of this album is here", which no
+per-card flag can answer at all.
+
+The general point: **two columns that agree today are not one column.**
+Which of them a new surface reads should be decided by which one has
+something that can un-set it.

.planning/audits/2026-08-11-ui/hands-on.md

@@ -13,7 +13,7 @@ reviews. Nothing was changed.
 
 Findings below are numbered `H-n` (hands-on) and cross-reference the
 static reports where they overlap. The reconciliation plan built from
-all four files is `.planning/plans/pending/007-ui-reconciliation.md`.
+all four files is `.planning/plans/completed/007-ui-reconciliation.md`.
 
 ---
 

.planning/plans/completed/012-api-call-audit.md

@@ -1,5 +1,7 @@
 # 012 — What we ask the network for, and what we already had
 
+> **Completed.** Findings 1, 2 and 4 shipped. Finding 3 — the bound-but-uncalled methods — is now **#86**.
+
 **Status:** all four findings fixed. Lint (3 configs), Go tests (3
 configs), `tsc` and 752 Vitest tests pass; **not driven against the
 real app**, so the numbers below are read off the code, not measured.

.planning/plans/completed/015-android-release-pipeline.md

@@ -1,5 +1,7 @@
 # 015 — Android release pipeline
 
+> **Completed.** The pipeline ships a signed APK from CI on every `v*` tag; `docs/android-release.md` is its operating document.
+
 Ship an Android APK from CI on every version tag, published to the Gitea
 generic package registry so Obtainium can poll a plain URL.
 

.planning/plans/completed/015-multi-artist-credits.md

@@ -1,5 +1,7 @@
 # 015 — Multi-artist credits, navigable
 
+> **Completed.** Phases 1, 2 and 4 shipped. Running the ingest against the real dump and publishing an artifact that carries credits is **#88**; Phase 3 (`file_artists`) is **#89**, blocked on it.
+
 ## The problem
 
 A track credited to more than one artist has exactly one navigable

.planning/plans/completed/016-android-feature-parity.md

@@ -1,5 +1,7 @@
 # 016 — What Android parity would actually take
 
+> **Completed.** Sections A, B1, B2 and B4 shipped. B3, writing tags on the device, is now **#87**; the device-found UI faults are #51–#72, sequenced by #73.
+
 > **Status: all of section A is done.** A1–A3 landed with "let the app
 > reach the user's music"; A4 (MediaSession, transport notification,
 > audio focus) landed with "survive the screen locking". The direction

.planning/plans/completed/autotag-v1.3.md

@@ -1,5 +1,7 @@
 # Autotag (v1.3) — MusicBrainz Autotagger
 
+> **Historical record.** Phases 008–010 shipped, and the scoring engine was subsequently overhauled (`recommend.go`, `rank.go`, `mixedbag.go`), which makes the 011/012 sections below stale in their details. What is actually left is **#90** (auto-accept and entry points) and **#91** (settings, and a way back from the dismissed file-write warning).
+
 The MusicBrainz autotagger, collectively **v1.3**. Builds on the explore-browser API client + cache foundation. Five sequential phases (008–012), each depending on the prior one.
 
 | Phase | Title | Status |

.planning/plans/pending/010-owned-album-catalog-offline.md

@@ -1,195 +0,0 @@
-# 010 — Owned albums, offline
-
-**Status:** not started — and **much smaller than when it was written**
-**Branch:** none yet
-**Created:** 2026-08-13
-**Depends on:** nothing
-**Related:** the `AlbumReleasesFailed` fix that prompted it, and the
-tag-derived completeness that landed after it (same session)
-
----
-
-## What already shipped, and what it leaves
-
-The common case is solved without this plan. `GetAlbumCompleteness`
-reads the "5/12" denominator off the files' own tags — persisted to
-`release_group_recordings.total_tracks`, having been extracted at every
-scan since forever and discarded — and an album that is **MBID-matched
-and complete** now opens with **no catalog call at all**. Identity from
-the MBID, tracklist from the tags; those were the two things the browse
-was being spent on.
-
-So the set this plan still has to serve is not "albums you own a track
-of". It is:
-
-- albums that are genuinely **incomplete** (the catalog is the only way
-  to say *which* tracks are missing — tags give the count, not the
-  names), and
-- albums whose tags **never declared a total**, where completeness is
-  unknowable locally and the catalog is the only source.
-
-On a well-tagged library that is a small minority, which changes the
-economics below considerably: the run is shorter, and the rate limiter
-contention that dominates this design is proportionally less severe.
-Re-measure before building — the answer may now be "the prefetch is
-enough".
-
----
-
-## The problem
-
-Opening an album detail page for an album **you already own** hits
-MusicBrainz. Every time it is not in the response cache, which for most
-of a library is every time, because nothing warms that cache except a
-capped prefetch on the artist page.
-
-The user's framing: *this is a classic example of an album we should
-have had locally.*
-
-## Why we do not have it, despite the discography backfill
-
-`BackfillLibraryDiscographies` / `EnsureArtistDiscography`
-(`backend/explore/searchindex.go:301`, `:397`) do less than the name
-suggests. Per artist, `indexOneArtist` fetches:
-
-- `fetchTopReleaseGroups` — capped at `indexMaxRGs` (50)
-- `fetchTopRecordings` — capped at `indexMaxRecs` (200)
-
-and writes them as **flat `explore_index` rows**. There is no release
-group → tracklist relation anywhere in the index, and no release-level
-rows at all. `explore_index` recordings carry `caa_release_mbid` and
-`release_name`, which name the release used for cover art — not a
-tracklist.
-
-So "we have full discographies for library artists" means *we know
-which albums the artist made, offline*. It has never meant we know
-what is on any of them.
-
-The only store of release-level catalog data in the app is `http_cache`
-under `mb:browse:releases:<rg>` (90-day TTL, `musicbrainz.go:27`),
-populated **only** by a live `BrowseReleases` with
-`Includes: ["recordings", "media"]` at `MaxLimit` — the most expensive
-call the app makes to MusicBrainz. It is warmed by exactly one thing:
-`PrefetchReleases` (`explore.go:746`), capped at 8, called only when an
-artist page renders.
-
-An album opened from the library grid therefore always browses live.
-
-## What to build
-
-**A post-scan backfill that warms the release cache for release groups
-that are owned but not known-complete** — bounded, resumable, and
-shaped exactly like `BackfillLibraryDiscographies`, which is the proven
-pattern for this in the codebase.
-
-The scoping rule is the user's and it is the right one: not "every
-album by every artist in the library" (50 release groups per artist,
-mostly never opened) but albums with owned tracks — narrowed further,
-now, to the ones a local answer cannot already cover. The query gains
-one clause: skip release groups whose `GetAlbumCompleteness` reports
-`complete`.
-
-Sketch:
-
-1. A query for release groups with ≥1 owned track and no warm release
-   cache entry. `release_groups.mbid` is the key; the owned-track join
-   is `audio_files → recordings → release_group_recordings`, the same
-   shape `unenrichedLibraryArtistMBIDs` already uses one table over.
-2. Order by owned-track count descending, so the albums the user has
-   most of are warmed first — same reasoning as the discography
-   backfill's ordering, same benefit if a run is cut short.
-3. Run through `releasesSF`, so it never double-fetches a release group
-   an interactive open is already handling.
-4. Bound a run (`discogBackfillMaxPerRun` has a value to copy) and make
-   it resumable: the resume marker is the response cache itself —
-   `BrowseReleasesCached` already answers "is this one done", so unlike
-   the discography path this needs **no new flag column**.
-5. Trigger it where `BackfillLibraryDiscographies` is triggered, and
-   register it with `jobs` so it has progress, pause and cancel like
-   every other long-running operation.
-
-### The rate limiter is the whole design constraint
-
-> **Update (2026-08-13): the priority half is built, and the sentence
-> below is wrong on a detail.** `e.mb` runs on `mbSearchLimiter`
-> (`NewRateLimiterBurst(3, 1)`); the 1 req/s `NewRateLimiter()` cited
-> here is the *artist image* limiter. Both are shared and both were
-> FIFO. `RateLimiter.WithBackgroundLane` + `WithBackgroundPriority(ctx)`
-> now make a marked caller yield to interactive work and pace at 1/s,
-> and `jobs.KindCatalogEnrich` + `startBackfillJob` give the existing
-> backfills progress and cancel. **"Do not start until the priority
-> question has an answer" is satisfied** — mark this backfill's context
-> and register it the way `BackfillLibraryDiscographies` now is.
-> `PrefetchReleases`' cap of 8 is still unrevisited.
-
-One shared `NewRateLimiter()` at 1 req/s (`explore.go:84`) serves this,
-`PrefetchReleases`, and every interactive browse. A backfill over a
-few thousand owned albums is *hours* of wall clock at that rate — which
-is fine for a background job, and not fine if it starves the album page
-the user is looking at right now.
-
-That is the real work in this plan, and it is not the query:
-
-- Interactive browses need to **jump the queue**. Today they cannot;
-  there is one limiter and it is FIFO.
-- `PrefetchReleases`' cap of 8 was sized when nothing else competed for
-  the limiter. Revisit it in the same change.
-- The 60 s fallback the `AlbumReleasesFailed` fix installed is sized
-  for today's contention. If a backfill can queue behind it, that
-  number is wrong again — which is an argument for priority, not for a
-  bigger number.
-
-Do not start the query until the priority question has an answer.
-
-## The alternative that was considered and rejected
-
-**Project release-group tracklists in the dump build and ship them in
-the artifact.** The data is there: `canonical_musicbrainz_data.csv`
-carries `release_mbid` *and* `recording_mbid`
-(`dumpcatalog.go:520`), and `release_to_rg` already maps release →
-release group. It is derivable from bytes the index build already
-streams, with no new API surface at all, and it would work offline on
-first launch with no per-user backfill.
-
-It is rejected **for this plan** because the artifact is built
-centrally and is byte-identical for every user, so "albums the user
-owns a track of" cannot be a filter on it. Shipping tracklists for the
-whole catalog means per-recording rows against a ~900 MB artifact
-budget (~426 B/row measured), and gating on a popularity floor means it
-is absent for exactly the obscure albums a local backfill would have
-covered.
-
-Worse than absent, in fact — and this is the argument that actually
-kills it. The floor is not one number over artists; it is a **per
-artist track budget** (`dumpcatalog.go:58-89`): 50 tracks for a tier-A
-artist, 25 for tier B, 12 for tier C. A projected tracklist would
-therefore be *whichever* of an album's tracks survived that budget,
-with nothing marking the rest as absent — so the album page would count
-owned against a truncated denominator and render "Play 7 of 9" for a
-twelve-track album. That is a confident lie, where the honest states
-this plan's alternative produces (complete / incomplete / unknown) are
-at worst silent.
-
-Note that `markLibraryArtists` (`dumpcatalog.go:246`) already grants
-every library artist full coverage — 500 tracks, 100 release groups —
-by reading the local library, so the per-user tailoring this option
-supposedly cannot have does exist in code. It is a no-op in the CI
-build (empty library), and reaching it means a **local** dump build:
-the ~205 GB, half-a-day download the entire artifact design exists to
-avoid. Whoever finds that function next should read this paragraph
-before getting excited about it.
-
-Worth revisiting if the artifact ever gains per-user tailoring, or if a
-measurement shows the row count is smaller than feared. Note it also
-yields the *canonical* tracklist rather than MusicBrainz's full version
-list, so the versions dropdown would still browse live when opened.
-
-## Done when
-
-- Opening an owned album that has never been opened before renders its
-  catalog tracklist with no network call, after one backfill run.
-- An interactive browse issued while the backfill is running is not
-  delayed by it.
-- The backfill appears in the jobs indicator, and can be paused and
-  cancelled there.
-- A second run after a completed one does approximately nothing.

.releaserc.yml

@@ -1,8 +1,19 @@
 # semantic-release configuration.
 #
-# Runs on pushes to main from .gitea/workflows/release.yml: determine the
-# version from the Conventional Commits since the last tag, write the
-# changelog, commit it, push the tag, and create the Gitea release.
+# Run by hand from .gitea/workflows/release.yml, which has no push
+# trigger: determine the version from the Conventional Commits since the
+# last tag, write the changelog, push the tag, and create the Gitea
+# release.  A release is a shipment rather than a merge, and the commits
+# accumulate until someone says so -- this file needs to know nothing
+# about that, because reading everything since the last tag is what it
+# already did.
+#
+# `branches` is main and only main.  A `prerelease: true` channel is the
+# obvious next edit here and is the one to think twice about: all four
+# publishing workflows trigger on `v*`, which matches `v0.4.0-beta.1`.
+# They carry a prerelease guard now, so the failure is a clean skip
+# rather than a beta in a public tap -- but they are four separate files
+# and this is the line that would turn them on.
 #
 # **There is no `@semantic-release/github` plugin here and there must not
 # be.** Gitea's API is `/api/v1` and is not GitHub's surface. The Gitea

CHANGELOG.md

@@ -5,15 +5,20 @@ The changelog is the releases page:
 <https://git.ljones.me/yonlu/yellowjacket/releases>
 
 Every release there is generated from the Conventional Commits it
-contains, by `.gitea/workflows/release.yml` on merge to `main`. Each one
-carries its notes as its body, grouped by change type, with a link to the
-commit behind every line.
+contains, by `.gitea/workflows/release.yml`. Each one carries its notes
+as its body, grouped by change type, with a link to the commit behind
+every line.
+
+That workflow is **run by hand**, so a release holds everything merged
+since the last one rather than one PR's worth. It used to fire on every
+push to `main`, which made a version per merged PR (issue #115).
 
 **This file is not generated and is not a copy of that.** `main` is a
 protected branch, so nothing pushes a changelog commit back to it — and a
 file that claimed to be a changelog while silently never updating would
-be worse than no file at all. `make release-dry` prints what the next
-merge would release.
+be worse than no file at all. `make release-dry` prints what a release
+run would cut right now, and the workflow's own `dry_run` input answers
+the same question from CI.
 
 History before `v0.0.1` is in `git log`. The versions before it were cut
 by hand and are not on the releases page; the entries this file used to

CLAUDE.md

@@ -6,16 +6,121 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 YellowJacket is a cross-platform desktop music player built with Go (backend) and TypeScript/Lit (frontend), using the Wails framework to bridge them. It supports MP3, FLAC, OGG Vorbis, and WAV playback.
 
+## Issues
+
+**The tracker is the source of truth for what is wanted and what is
+already being worked on**, and it is shared with a collaborator who
+cannot see this session. `scripts/issue.sh` is the whole interface to
+it (`list`, `mine`, `search`, `show`, `new`, `claim`, `unclaim`,
+`comment`, `close`, `label`, `depends`, `labels`); it needs a
+`GITEA_TOKEN` with `write:issue`.
+
+**Search the tracker before starting any work, and claim what you
+find.** Fifty-odd issues make that a real lookup rather than a
+formality. `./scripts/issue.sh search <terms>` covers open and closed —
+closed matters, because "that was fixed three weeks ago" is the
+cheapest possible answer.
+
+**Claiming happens before the first edit, not before the commit.** The
+whole point is that the collaborator can see the work is taken *while
+it is being done*, so `claim` sets the assignee, applies
+`Status/In Progress` and posts a comment naming the branch and the
+approach — all three, or none. It refuses outright if somebody else
+already holds it, and that refusal is the feature: talk to them rather
+than working around it.
+
+**If no issue covers the work, open one first.** The issue exists
+before the branch does. That is what makes the tracker a description
+of the project rather than a description of the past.
+
+**Findings get filed.** A bug tripped over while doing something else
+is an issue with a reproduction, not a sentence in a chat message
+nobody can search. So is a piece of work deliberately not done — the
+issue is where "we decided not to, and here is why" survives.
+
+Four conventions are already established and are not up for
+reinvention:
+
+- **The labels are a taxonomy**, not tags: `Kind/*`, `Area/*`,
+  `Priority/*`, `Platform/*`, plus `Reviewed/Confirmed` (the code was
+  read and the defect confirmed) and the `Status/*` family. `Status/*`
+  and `Reviewed/*` are **exclusive scopes** — one of each at most, so
+  applying a second replaces the first.
+- **#73 is the roadmap.** It states the order the backlog should be
+  worked in and the soft relations that are not expressible as
+  blockers. Picking work off the open list by eye when a meta issue
+  states the sequence is how the sequence stops meaning anything.
+- **Hard blockers are real Gitea dependencies**, which render on the
+  issue itself, and the blocked issue carries `Status/Blocked`.
+- **A PR body carries a commit-to-issue table, the verification
+  actually run, and a `Closes` list** — PR #83 is the shape. That list
+  is for whoever reads the PR; what actually closes an issue is the
+  footer below.
+
+**The closing keyword goes in the commit body, one issue per line.**
+
+```
+docs: delete four documents that contradict the code
+
+<body>
+
+Closes #98
+```
+
+**Gitea parses commit messages that reach `main`; it does not parse the
+PR body**, which only closes anything if the merge happens to copy it
+into the merge commit. Both halves of that were measured. #83's merge
+commit carried `Closes #9, #13, #14, …` and closed **five of ten** — a
+comma list is partially matched. #93's merge commit body was one
+`Reviewed-on:` trailer, so #92 stayed open behind a perfectly correct
+`Closes` line in the PR description.
+
+A footer costs nothing elsewhere: Conventional Commits allows one,
+`scripts/commit-check.sh` only regexes the subject, and
+semantic-release reads the type from the subject — so this changes no
+release decision. The rule that the issue number stays out of the
+**subject** is unaffected, and was never about the body.
+
+**Check it anyway.** A squash, or a merge message edited by hand,
+still drops the footer. `./scripts/issue.sh list --state open` after a
+merge, looking for what you just shipped; `./scripts/issue.sh close
+<n>` for whatever did not take, with a comment naming the commit.
+
+**Unclaiming is automatic, and it is hooked to the close rather than
+to the merge.** Gitea's auto-close changes state and nothing else, so a
+footer left `Status/In Progress` on a closed issue — #100 was closed
+and marked as being actively worked on at the same time.
+`.gitea/workflows/unclaim.yml` runs on `issues: [closed]`, which covers
+the footer, `issue.sh close` and a click in the web UI alike; stripping
+the label in the PR instead would have been a per-PR habit, and habits
+are what the footer removed. It is not instant — the runner has
+capacity 1 — and reopening deliberately does not restore the label.
+`./scripts/issue.sh list --state closed --label "Status/In Progress"`
+is how you find out it has stopped firing.
+
 ## Planning
 
-Active and historical plans live in `.planning/`:
+`.planning/` is **design documents and measured history**, not a queue
+— the queue is the tracker, and a plan file that describes work nobody
+has started is a second, staler answer to "what are we doing next".
 
-- `.planning/NOTES.md` — gotchas, deferred items, open architecture questions, the "we already considered and rejected" list.
-- `.planning/plans/active/` — work currently in progress (read first).
-- `.planning/plans/pending/` — sequenced future work.
-- `.planning/plans/completed/` — one concise recap per shipped milestone.
+- `.planning/NOTES.md` — gotchas, measured facts, open architecture
+  questions, and the "we already considered and rejected" list. Dated,
+  because several are properties of someone else's server. **This is
+  where a decision reached on an issue gets written down** when it
+  outlives the issue.
+- `.planning/plans/completed/` — one recap per shipped milestone, kept
+  for the arguments in it. Where a plan shipped incompletely, its
+  header says which issue carries the remainder.
+- `.planning/audits/` — the read-only audits that produced the
+  reconciliation plans. Historical evidence; not a backlog.
+- `.planning/plans/active/` — a multi-phase design document for work
+  **in flight**, linked from the issue that tracks it. Empty is the
+  normal state. There is no `pending/`: a plan nobody is executing is
+  an issue.
 
-Numbering is sequential and stable across status moves (a plan keeps its `NNN-` prefix as it migrates between `pending → active → completed`). Abandoned plans are deleted; paused work stays in `pending/`.
+Numbering is sequential and stable across status moves (a plan keeps
+its `NNN-` prefix). Abandoned plans are deleted.
 
 ## Commands
 
@@ -1343,6 +1448,52 @@ is therefore **reported at runtime** to `window.__yjIconMisses` and
 drawn as a fallback — an e2e sweep asserts there are none — since a
 missing icon used to be impossible, the CDN having had everything.
 
+**What each icon *means* is a second table, and it is
+`utils/icon-language.ts`.** Bundling answers "does this name resolve";
+nothing answered "does this name mean what the one next to it means",
+and a wrong-but-real icon renders perfectly. So `plus` came to mean add
+to the queue, add to a playlist, make a new playlist **and** you do not
+own this — the first two *adjacent in the same context menu* — while
+`list` meant the queue, the Playlists destination and adding to the
+queue.
+
+The rule the table is built on: **an icon names the noun it acts on,
+not the verb.** "Add to queue" and "add to playlist" are one verb on
+two nouns, so the noun is what has to differ — which is why adding to a
+playlist wears the Playlists destination's own icon, and why the queue
+got `bars-staggered` and stopped wearing Playlists'. `plus` keeps the
+one meaning it is unambiguous about, making something that is not there
+yet.
+
+Four things about it are load-bearing:
+
+- **The request toggle is one glyph in two weights**
+  (`regular/bookmark` → `solid/bookmark`), because two states of a
+  toggle have to read as each other's opposite and a plus against a
+  bookmark does not. The pair was *already in the app and already
+  right* on `explore-album-details`'s "Request this" button while the
+  badge forty pixels away showed a plus — `utils/library-status.ts`'s
+  fault one layer down, having made the two agree on what wanting means
+  and left them disagreeing on what it looks like.
+- **Downloads keeps the solid bookmark, deliberately.** That is the
+  same word twice, not two words: the badge says "this is on your
+  list" and the nav item is that list.
+- **`icon-language.test.ts` sweeps the source**, because the rule is
+  about every call site and checking one checks nothing — the same
+  shape as `TestNoDirectRuntimeEmits`. It reads every `src/**/*.ts` as
+  raw text and fails on a literal `name="plus"` or `icon: 'list'`
+  outside the table, and its **first assertion is that it read
+  anything at all**, since a sweep over an empty glob passes.
+- **It also asserts every `ICON_*` is bundled**, which closes the loop
+  the runtime cannot: `bookmark-check` is Font Awesome **Pro** and sat
+  on `explore-artist-details`'s Follow button, drawn for every followed
+  artist as a circled question mark. `offline-icons.spec.ts` sweeps
+  `__yjIconMisses` and could not see it, because no spec had ever
+  followed an artist — the same fault `requested-badge.spec.ts` was
+  written for, one component over, still live. A name computed from
+  state was only checkable from the state; now it is checkable from the
+  table.
+
 **An album page says how much of the album is yours.**
 `explore-album-details` is a *catalog* page and there is no
 library-side album detail page at all, so the album on it may be
@@ -1442,11 +1593,55 @@ shape as the encoding probe beside it.
 
 What neither side can give is *which* tracks are missing, only how many
 — so an incomplete album still browses, and that is now the exception
-rather than every album load. Two smaller consequences: existing databases
-read "unknown" until a rescan repopulates the column (which degrades to
-exactly the old behaviour, so nothing breaks), and our own `tagwriter`
-writes track and disc *numbers* but not totals, so autotagging a folder
-currently degrades the field this rests on.
+rather than every album load. One smaller consequence: existing databases
+read "unknown" until a rescan repopulates the column, which degrades to
+exactly the old behaviour, so nothing breaks.
+
+**And our own writers declare the total, because for a long time they
+did not.** `tagwriter` wrote track and disc *numbers* and dropped the
+totals, so autotagging an album actively **erased** the evidence this
+rests on: the release became MBID-matched — a green tick — while the
+field `GetAlbumCompleteness` reads stayed absent, which is exactly the
+"2 of 10 tracks, reported as in your library" the report described.
+`FieldTotalTracks` / `FieldTotalDiscs` are written by the autotag apply
+pass and by the download importer, and `dbsync` persists the track
+total to the row so the album page agrees with the file without waiting
+for a rescan.
+
+Five things about it are load-bearing, and four of them fail silently:
+
+- **The total is per *disc*, not per release**, because that is what
+  the tag form declares and what `GetAlbumCompleteness` **sums** per
+  disc — a release total written on every file multiplies a two-disc
+  album's expectation by two, and no library can then satisfy it.
+  `backend/tagtotals` is that derivation, once, because the two callers
+  must not import each other or the writer.
+- **The Vorbis names are `TRACKTOTAL` and `DISCTOTAL` and no other
+  spelling.** `dhowden/tag`'s Vorbis reader looks at exactly those two
+  keys, so a perfectly reasonable `TOTALTRACKS`, or a `1/12` inside
+  `TRACKNUMBER`, is written successfully and reads back as no total at
+  all. The tests assert the round trip through the reader the *scan*
+  uses rather than through the bytes, for that reason.
+- **ID3's number and total share one frame**, so writing either alone
+  has to read the other off the existing tag or it silently discards
+  it. A total with no number is not written: `/12` is what a reader
+  parses as track 0.
+- **The totals are written unconditionally, not on a diff.** The case
+  this exists for is a file that declares *no* total, which compares
+  equal to nothing and is exactly what a "only if it changed" guard
+  skips.
+- **A single-track download must not be totalled.** A `RecordingMBID`
+  anchor resolves `Expected` to that one track, so the same code would
+  tag a track off a twelve-track album "1 of 1" — and a declared total
+  outranks the catalog total that would otherwise have answered
+  correctly. Confidently wrong is worse than absent here, which is the
+  same rule `Known` exists for.
+
+One gap this did not close, and it is older: **`dhowden/tag` has no
+RIFF reader**, so nothing the tag writer puts in a WAV's `id3 ` chunk
+is visible to `metadata.ExtractTags` — not the totals and not the title
+either. `wav_test.go` reads that chunk itself, which is why no test
+ever noticed.
 
 **The absence is what gets marked, not the presence.** The tracklist
 put a green tick against every owned track and a legend underneath
@@ -1463,6 +1658,59 @@ not about plumbing — it says rows may be missing from the page
 altogether, which nothing on screen can show. (`explore-artist-details`
 still uses `loading`; it has no equivalent per-row signal.)
 
+**And that treatment is the app's, not the page's.**
+`utils/ownership.ts` is the rule written once, because it was written
+at eight call sites and so none of them had the whole of it: Explore's
+cards, `top-results-row` and the artist page's three card shapes all
+mixed owned and unowned with a small badge as the only difference, and
+the badge on the *owned* ones was a green tick — the mark on the common
+case this tracklist removed. Owned is plain and draws no badge at all;
+unowned is dimmed, says so in its accessible name, and keeps its
+request affordance; a partly-held album says how partly.
+
+Four things about it are load-bearing.
+
+**Ownership is `localId`, and `inLibrary` is deliberately not
+consulted.** The album page answers with `filePaths`, a real file per
+displayed track, and a card grid cannot afford that — but it does not
+need to, because `explore_index.local_*_id` is built by
+`collectLibraryEntities` from queries that every one join `audio_files`
+and cleared by `pruneStaleLocalCrossReferences`, whose existence test
+is a file test in all three cases. That is the same "ownership is a
+file" rule computed once per scan instead of once per screenful.
+`in_library` is written by the same pass, so the two agree in a healthy
+database, but it is a one-way ratchet
+(`MAX(in_library, excluded.in_library)`) whose only clearing pass is
+gated on a non-null local id: it cannot be un-set on its own (#118).
+One is a fact with an owner; the other is a flag that happens to agree.
+Both `explore-view` and `explore-artist-details` additionally kept a
+`libraryMBIDs` set that accumulated every MBID ever seen with the flag
+and cleared it never, in views that never unmount; both are gone.
+
+**The two answers used to sit on one card.**
+`renderReleaseMenuItems` gates Play on `release.localId > 0` while the
+badge used `inLibrary`, so an album with the flag and no local row drew
+a tick saying it was in your library, offered no Play, and — the
+request item being gated on *not* owned — offered no way to ask for it
+either. Any new surface that asks the question twice will reproduce it.
+
+**`aria-disabled` goes on rows and not on cards.** An unowned *row*
+cannot be activated; an unowned *card* still navigates to the catalog
+page for it, which is a perfectly good thing to do with something you
+do not own. The accessible name carries the state either way, which is
+why it is one helper and not a class.
+
+**The count is batched, not looked up.** `store/completeness-store.ts`
+is `credit-store` one question over: `request()` is per-card and
+coalesces a screenful into one `GetAlbumsCompleteness`, absence is
+cached as an answer (or the albums with no totals re-ask forever), and
+the whole cache is dropped on a scan, a retag or a removal rather than
+aged. `library-status.ts`'s `albumBadgeFor` is where that meets
+`Known`: a total that was never declared is a plain `in-library`, never
+a ring at 0%. One consequence in the badge itself — a `partial` badge
+is *actionable*, and a control named after its action alone dropped the
+count from the one state the ring exists for, so its name is both.
+
 **A partly-owned album draws the release, not the part.** Once the tags
 say nine of twelve, `buildLibraryEntry` shows the *catalog's* twelve
 with three dimmed, rather than the nine on disk — the missing tracks
@@ -1474,6 +1722,32 @@ side-effect worth knowing: this is what finally makes `ownership()`
 say something true here, since counting the displayed tracklist of a
 library-only entry could only ever produce "9 of 9".
 
+**And it can be asked, because the rule alone reaches too few albums.**
+That guard depends on two inputs the user does not control: the files
+declaring a per-disc total, and the catalog's own `total_tracks`. Where
+neither says — which is a great deal of any library, and *every* library
+until an artifact carrying the column is published — a partly-owned
+album showed only the tracks on disk with nothing to say the rest
+existed. `renderTracklistScope()` is the explicit route: a
+"Show the whole album" switch that flips the synthetic "Your Library"
+entry between the local files and the release, which is the rendering
+the page could already do and could only be *triggered* automatically.
+
+Three things about it are load-bearing. **`showFullTracklist` is a
+tri-state**, `null` meaning "follow the automatic rule": the rule is
+right when it fires and the switch has to be able to agree with the page
+it sits on rather than starting out contradicting it, which a plain
+boolean would need recomputed every time the completeness answer moved
+underneath it. **`fullReleaseCluster()` falls back to the
+highest-scoring cluster**, because `findLibraryCluster` is a guess over
+the `inLibrary` flags and returns *nothing* when none are set — which is
+exactly the untagged library the switch exists for, so without the
+fallback the control would be absent precisely where it is needed. And
+**it is shown only where it can change what is on screen**: against the
+library entry, with a release to switch to, and only when the two
+tracklists differ — the same test the version dropdown answers, one
+control over.
+
 **A dropdown is only a choice if the choices differ.** The version
 selector tested `versionEntries.length`, but a release group routinely
 has several releases — reissues, regional pressings, a remaster — whose
@@ -2066,23 +2340,75 @@ branch** (`enable_push: false`, an empty push whitelist, and `CI / check*`
 the pre-receive hook. This file said otherwise for a long time. Tags are
 *not* protected, which is what lets `release.yml` push one.
 
+**A branch answers a claimed issue** — see "Issues" above. The commit
+grammar is unchanged and is load-bearing for a different reason
+(semantic-release reads it), so the issue number lives in the branch
+name and the PR body rather than in the commit subject.
+
+**A batch of small fixes can be one PR**, which is what #83 did: eight
+branches preserved as merges under one integration branch, so
+authorship survives and the batch lands as one release rather than
+eight. The cost is that its `Closes` list has to be checked afterwards
+— it half-worked.
+
 Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pre-push runs the full test suite.
 
 ## CI
 
-Seven workflows in `.gitea/workflows/`. Five of them package and
+Eight workflows in `.gitea/workflows/`. Five of them package and
 publish (`arch-package`, `homebrew-formula`, `index-artifact`,
 `android-apk`, `desktop-assets`); `release.yml` decides *whether* four of
-those run at all; only `ci.yml` gates, and it is the one to look at when
+those run at all; `unclaim.yml` is housekeeping on the tracker and
+touches no code; only `ci.yml` gates, and it is the one to look at when
 deciding whether a push was healthy.
 
-**`release.yml` is the entry point for all of it.** On every push to
-`main` it reads the Conventional Commits since the last tag and, if any
+**`release.yml` is the entry point for all of it, and it is triggered by
+hand.** It reads the Conventional Commits since the last tag and, if any
 is releasable, writes the changelog, pushes the tag and creates the Gitea
 release whose body is that changelog section. `arch-package`,
 `homebrew-formula`, `android-apk` and `desktop-assets` are all keyed on
-`v*`, so **the tag push is what starts them** — nothing is released by
-hand any more.
+`v*`, so **the tag push is what starts them** — the version, the notes
+and the packaging are still nobody's manual work; *when* is the only
+decision left to a person.
+
+**It used to fire on every push to `main`, which made the trigger "a PR
+was merged".** That is a version per unit of *work* rather than per
+*shipment*: eight releases in twenty-two hours (`v0.0.1` → `v0.3.1`) for
+one session, each fanning out to four publishers on a runner with
+capacity 1 — ~40 packaging jobs to ship three issues, with ordinary PR CI
+queued behind them. Nothing else had to change to batch them, because
+**semantic-release already reads every commit since the last tag**: five
+`fix`es and two `feat`s become one minor release with all seven in the
+notes. Release frequency was only ever how often the workflow fired.
+
+This is the same rule `index-artifact.yml` states — *a job that mutates
+state which cannot be rebuilt in ten minutes is triggered deliberately,
+not by a push* — and the two are now the only workflows with no push
+trigger. A schedule was considered and rejected: a cron batches without
+anyone having to remember, but it puts the decision back on a timer,
+which is the thing being removed. A `beta` integration branch was
+considered and rejected too (#115): it relocates the trigger rather than
+removing one, needs a second protected branch carrying the same required
+checks, and *adds* a full `check` + `e2e` run per batch on the very
+runner whose queue is the complaint.
+
+**`dry_run` is why the manual trigger is usable.** The point of pulling
+a lever by hand is being able to look first, so the dispatch takes a
+flag that runs `semantic-release --dry-run`: the version and the notes,
+no tag, no release, no publishers. Anything but the literal string
+`true` releases for real — a typo in a dispatch box must not silently
+turn a shipment into a green no-op.
+
+**A prerelease tag is not a shipment, and all four publishers now say
+so.** Their trigger is `v*`, which matches `v0.4.0-beta.1`; they guarded
+`v0.0.0` and nothing else. Nothing produces a prerelease today — the
+guard is there because the thing that would is `prerelease: true` in
+`.releaserc.yml`, one line whose blast radius is a public Homebrew tap
+and a credential-free APK registry that Obtainium polls. `android-apk`
+is the worst of the four twice over, since its `versionCode` maths
+splits on dots and would read `1` out of `0-beta` — a wrong number
+rather than a failed build, and Android refuses anything not greater
+than what is installed.
 
 Four things about it are load-bearing:
 

Makefile

@@ -192,15 +192,21 @@ skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md
 commit-check: ## Fail if a commit subject is not a Conventional Commit
 	@./scripts/commit-check.sh $(if $(RANGE),--range $(RANGE))
 
-# What a merge to main would release, without releasing it.  Reads the
-# same .releaserc.yml CI does, so "why did that not cut a version" is
-# answerable locally instead of by pushing and watching.  Needs no
-# credentials: --dry-run neither tags nor publishes.
+# What running the release workflow now would ship, without shipping it.
+# Reads the same .releaserc.yml CI does, so "why did that not cut a
+# version" is answerable locally instead of by pushing and watching.
+# Needs no credentials: --dry-run neither tags nor publishes.
+#
+# release.yml is dispatch-only, so this answers the question that
+# actually gets asked now -- what has accumulated since the last tag --
+# rather than what one merge would have done.  The workflow's own
+# `dry_run` input is the same answer from the runner, against whatever
+# main points at rather than the working tree.
 #
 # The pins must stay identical to release.yml's, which is where the note
 # on holding the conventionalcommits preset at 9 lives -- at 10 the
 # release notes come out empty with everything green.
-release-dry: ## Print the version a merge to main would release
+release-dry: ## Print the version a release run would cut right now
 	@npx --yes \
 		-p semantic-release@25 \
 		-p @semantic-release/commit-analyzer@13 \

README.md

@@ -106,5 +106,8 @@ make dev          # run with hot-reload
 make build-prod   # produce a release binary
 ```
 
-More detail for contributors lives in
-[`docs/dev/overview.md`](./docs/dev/overview.md) and [`CLAUDE.md`](./CLAUDE.md).
+More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
+architecture, the conventions and the reasons behind them. What is
+being worked on is [the issue
+tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
+roadmap.

backend/autotag/apply.go

@@ -8,6 +8,7 @@ import (
 	"log/slog"
 
 	"yellowjacket/backend/database/sql/sqlcgen"
+	"yellowjacket/backend/tagtotals"
 )
 
 // TagChanges mirrors tagwriter.TagChanges — redefined here so the
@@ -28,6 +29,8 @@ const (
 	FieldYear        = "year"
 	FieldTrackNumber = "track_number"
 	FieldDiscNumber  = "disc_number"
+	FieldTotalTracks = "total_tracks"
+	FieldTotalDiscs  = "total_discs"
 	FieldCoverArt    = "cover_art"
 )
 
@@ -418,5 +421,32 @@ func buildChanges(
 		changes[FieldDiscNumber] = track.DiscNumber
 	}
 
+	// The totals are what says "2 of 10" rather than a bare tick, and
+	// dropping them here is what made autotagging an album *erase* the
+	// evidence: the release becomes MBID-matched while the field
+	// GetAlbumCompleteness reads stays absent.
+	//
+	// They are written unconditionally where the candidate has a
+	// tracklist, not only when they differ from the local value, because
+	// the common case is a file that declares no total at all -- which
+	// compares equal to nothing and would be skipped by a diff guard.
+	if tracks, discs := tagtotals.For(
+		candidatePositions(cand), track.DiscNumber,
+	); tracks > 0 {
+		changes[FieldTotalTracks] = tracks
+		changes[FieldTotalDiscs] = discs
+	}
+
 	return changes
 }
+
+// candidatePositions is the candidate's tracklist as bare positions.
+func candidatePositions(cand Candidate) []tagtotals.Position {
+	out := make([]tagtotals.Position, 0, len(cand.Tracks))
+
+	for _, t := range cand.Tracks {
+		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
+	}
+
+	return out
+}

backend/autotag/buildchanges_test.go

@@ -0,0 +1,90 @@
+package autotag
+
+import "testing"
+
+// Autotagging an album used to *erase* the evidence that says "2 of 10":
+// the release became MBID-matched while the totals the files declared
+// went unwritten, so the album page showed a plain tick.  These pin the
+// two halves of the fix that are easy to get wrong silently.
+func TestBuildChanges_Totals(t *testing.T) {
+	t.Parallel()
+
+	twoDiscs := Candidate{
+		Tracks: []CandidateTrack{
+			{DiscNumber: 1, Position: 1},
+			{DiscNumber: 1, Position: 2},
+			{DiscNumber: 2, Position: 1},
+			{DiscNumber: 2, Position: 2},
+			{DiscNumber: 2, Position: 3},
+		},
+	}
+
+	tests := []struct {
+		name       string
+		cand       Candidate
+		local      LocalTrack
+		track      CandidateTrack
+		wantTracks any
+		wantDiscs  any
+	}{
+		{
+			// The common case, and the one a diff guard would skip: the
+			// file declares no total at all, so the total "has not
+			// changed" and would never be written.
+			name: "a file with no total gets one",
+			cand: Candidate{Tracks: []CandidateTrack{
+				{Position: 1}, {Position: 2}, {Position: 3},
+			}},
+			local:      LocalTrack{TrackNumber: 1},
+			track:      CandidateTrack{Position: 1},
+			wantTracks: 3,
+			wantDiscs:  1,
+		},
+		{
+			// 5 here would be the release's track count.  Summed once
+			// per disc by GetAlbumCompleteness that claims a ten-track
+			// expectation for a five-track album, which no library can
+			// ever satisfy.
+			name:       "a multi-disc release totals the track's own disc",
+			cand:       twoDiscs,
+			local:      LocalTrack{},
+			track:      CandidateTrack{DiscNumber: 2, Position: 1},
+			wantTracks: 3,
+			wantDiscs:  2,
+		},
+		{
+			name:       "the other disc gets its own total",
+			cand:       twoDiscs,
+			local:      LocalTrack{},
+			track:      CandidateTrack{DiscNumber: 1, Position: 1},
+			wantTracks: 2,
+			wantDiscs:  2,
+		},
+		{
+			// A candidate with no tracklist knows nothing, and writing
+			// a zero would claim it did.
+			name:       "a candidate with no tracklist writes no total",
+			cand:       Candidate{},
+			local:      LocalTrack{},
+			track:      CandidateTrack{Position: 1},
+			wantTracks: nil,
+			wantDiscs:  nil,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			changes := buildChanges(tc.local, tc.cand, tc.track)
+
+			if got := changes[FieldTotalTracks]; got != tc.wantTracks {
+				t.Errorf("%s: got %v, want %v", FieldTotalTracks, got, tc.wantTracks)
+			}
+
+			if got := changes[FieldTotalDiscs]; got != tc.wantDiscs {
+				t.Errorf("%s: got %v, want %v", FieldTotalDiscs, got, tc.wantDiscs)
+			}
+		})
+	}
+}

backend/autotagservice/fieldnames_test.go

@@ -0,0 +1,38 @@
+package autotagservice
+
+import (
+	"testing"
+
+	"yellowjacket/backend/autotag"
+	"yellowjacket/backend/tagwriter"
+)
+
+// twAdapter passes the diff map through unchanged, so autotag's field
+// constants and tagwriter's are the same keys written down twice --
+// deliberately, to keep autotag out of the write pipeline's import
+// graph.  A key that drifts does not fail to compile and does not fail
+// to write: the writer simply finds no entry under the name it looks
+// for, and the field is silently dropped.  That is what this pins, and
+// this package is the one place that imports both.
+func TestAutotagAndTagwriterAgreeOnFieldNames(t *testing.T) {
+	t.Parallel()
+
+	pairs := map[string][2]string{
+		"title":        {autotag.FieldTitle, tagwriter.FieldTitle},
+		"artist":       {autotag.FieldArtist, tagwriter.FieldArtist},
+		"album":        {autotag.FieldAlbum, tagwriter.FieldAlbum},
+		"album artist": {autotag.FieldAlbumArtist, tagwriter.FieldAlbumArtist},
+		"year":         {autotag.FieldYear, tagwriter.FieldYear},
+		"track number": {autotag.FieldTrackNumber, tagwriter.FieldTrackNumber},
+		"disc number":  {autotag.FieldDiscNumber, tagwriter.FieldDiscNumber},
+		"total tracks": {autotag.FieldTotalTracks, tagwriter.FieldTotalTracks},
+		"total discs":  {autotag.FieldTotalDiscs, tagwriter.FieldTotalDiscs},
+		"cover art":    {autotag.FieldCoverArt, tagwriter.FieldCoverArt},
+	}
+
+	for name, pair := range pairs {
+		if pair[0] != pair[1] {
+			t.Errorf("%s: autotag says %q, tagwriter says %q", name, pair[0], pair[1])
+		}
+	}
+}

backend/database/sql/queries/albums.sql

@@ -135,3 +135,49 @@ SELECT
     ) AS INTEGER) AS known
 FROM audio_files a
 WHERE a.album_id = sqlc.arg(album_id);
+
+-- name: GetAlbumsCompleteness :many
+-- The same question as GetAlbumCompleteness, asked of a screenful of
+-- albums at once.
+--
+-- A card grid cannot afford one query per card, and the answer it wants
+-- is the one thing a badge cannot guess: an album held 9 tracks of 12
+-- must show the count, never a bare tick.  So this is one query for the
+-- whole grid, asked only of the cards that have a local album id.
+--
+-- It is two grouping levels rather than the single-album form's
+-- correlated subqueries, because a correlated subquery in the FROM
+-- clause is not something SQLite will reliably do -- and because the
+-- slice may only be spelled once, or sqlc expands it twice with
+-- independently numbered placeholders.
+--
+-- The per-disc level is where the meaning is, and it is the same
+-- meaning as the single-album query.  `owned` counts DISTINCT track
+-- numbers within a disc (this app detects duplicates, and counting two
+-- files of track 3 twice would report a short album as complete), with
+-- a file that declares no track number falling back to its own id
+-- because three untagged files are three tracks and not one.
+-- `expected` takes each disc's declared total and sums over discs,
+-- since a total is declared per disc and a release total written on
+-- every file of a two-disc album would double its expectation.  A disc
+-- whose files declared nothing contributes a NULL that SUM ignores,
+-- and `known` is what says the album is therefore unanswerable.
+WITH per_disc AS (
+    SELECT
+        album_id AS album_id,
+        COUNT(DISTINCT COALESCE(CAST(track_number AS TEXT), 'f' || id))
+            AS owned_on_disc,
+        MAX(total_tracks) AS disc_total,
+        SUM(CASE WHEN total_tracks IS NULL THEN 1 ELSE 0 END)
+            AS discs_without_a_total
+    FROM audio_files
+    WHERE album_id IN (sqlc.slice('album_ids'))
+    GROUP BY album_id, COALESCE(disc_number, 1)
+)
+SELECT
+    CAST(album_id AS INTEGER) AS album_id,
+    CAST(SUM(owned_on_disc) AS INTEGER) AS owned,
+    CAST(COALESCE(SUM(disc_total), 0) AS INTEGER) AS expected,
+    CAST(SUM(discs_without_a_total) = 0 AS INTEGER) AS known
+FROM per_disc
+GROUP BY album_id;

backend/database/sql/sqlcgen/albums.sql.go

@@ -8,6 +8,7 @@ package sqlcgen
 import (
 	"context"
 	"database/sql"
+	"strings"
 )
 
 const deleteAlbum = `-- name: DeleteAlbum :exec
@@ -234,6 +235,98 @@ func (q *Queries) GetAlbumsByArtistName(ctx context.Context, arg GetAlbumsByArti
 	return items, nil
 }
 
+const getAlbumsCompleteness = `-- name: GetAlbumsCompleteness :many
+WITH per_disc AS (
+    SELECT
+        album_id AS album_id,
+        COUNT(DISTINCT COALESCE(CAST(track_number AS TEXT), 'f' || id))
+            AS owned_on_disc,
+        MAX(total_tracks) AS disc_total,
+        SUM(CASE WHEN total_tracks IS NULL THEN 1 ELSE 0 END)
+            AS discs_without_a_total
+    FROM audio_files
+    WHERE album_id IN (/*SLICE:album_ids*/?)
+    GROUP BY album_id, COALESCE(disc_number, 1)
+)
+SELECT
+    CAST(album_id AS INTEGER) AS album_id,
+    CAST(SUM(owned_on_disc) AS INTEGER) AS owned,
+    CAST(COALESCE(SUM(disc_total), 0) AS INTEGER) AS expected,
+    CAST(SUM(discs_without_a_total) = 0 AS INTEGER) AS known
+FROM per_disc
+GROUP BY album_id
+`
+
+type GetAlbumsCompletenessRow struct {
+	AlbumID  int64
+	Owned    int64
+	Expected int64
+	Known    int64
+}
+
+// The same question as GetAlbumCompleteness, asked of a screenful of
+// albums at once.
+//
+// A card grid cannot afford one query per card, and the answer it wants
+// is the one thing a badge cannot guess: an album held 9 tracks of 12
+// must show the count, never a bare tick.  So this is one query for the
+// whole grid, asked only of the cards that have a local album id.
+//
+// It is two grouping levels rather than the single-album form's
+// correlated subqueries, because a correlated subquery in the FROM
+// clause is not something SQLite will reliably do -- and because the
+// slice may only be spelled once, or sqlc expands it twice with
+// independently numbered placeholders.
+//
+// The per-disc level is where the meaning is, and it is the same
+// meaning as the single-album query.  `owned` counts DISTINCT track
+// numbers within a disc (this app detects duplicates, and counting two
+// files of track 3 twice would report a short album as complete), with
+// a file that declares no track number falling back to its own id
+// because three untagged files are three tracks and not one.
+// `expected` takes each disc's declared total and sums over discs,
+// since a total is declared per disc and a release total written on
+// every file of a two-disc album would double its expectation.  A disc
+// whose files declared nothing contributes a NULL that SUM ignores,
+// and `known` is what says the album is therefore unanswerable.
+func (q *Queries) GetAlbumsCompleteness(ctx context.Context, albumIds []sql.NullInt64) ([]GetAlbumsCompletenessRow, error) {
+	query := getAlbumsCompleteness
+	var queryParams []interface{}
+	if len(albumIds) > 0 {
+		for _, v := range albumIds {
+			queryParams = append(queryParams, v)
+		}
+		query = strings.Replace(query, "/*SLICE:album_ids*/?", strings.Repeat(",?", len(albumIds))[1:], 1)
+	} else {
+		query = strings.Replace(query, "/*SLICE:album_ids*/?", "NULL", 1)
+	}
+	rows, err := q.db.QueryContext(ctx, query, queryParams...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []GetAlbumsCompletenessRow
+	for rows.Next() {
+		var i GetAlbumsCompletenessRow
+		if err := rows.Scan(
+			&i.AlbumID,
+			&i.Owned,
+			&i.Expected,
+			&i.Known,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const getAlbumsWithPendingReleaseMBID = `-- name: GetAlbumsWithPendingReleaseMBID :many
 SELECT id, pending_release_mbid FROM albums
 WHERE pending_release_mbid IS NOT NULL AND pending_release_mbid != ''

backend/download/importer.go

@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"
 
+	"yellowjacket/backend/tagtotals"
 	"yellowjacket/backend/tagwriter"
 )
 
@@ -275,6 +276,25 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 		changes[tagwriter.FieldDiscNumber] = p.Track.DiscNumber
 	}
 
+	// An imported file should arrive knowing how much of the album it
+	// is one of, or the album reads as "in your library" from its first
+	// imported track onward.
+	//
+	// A *track* download is the case this must not touch: a
+	// RecordingMBID anchor resolves Expected to exactly that one track,
+	// so totalling it would write "1 of 1" onto a track off a
+	// twelve-track album -- a confident lie, and one that outranks the
+	// catalog's own total, which is the fallback that would otherwise
+	// have answered correctly.
+	if dl.RecordingMBID == "" {
+		if tracks, discs := tagtotals.For(
+			expectedPositions(dl.Expected), p.Track.DiscNumber,
+		); tracks > 0 {
+			changes[tagwriter.FieldTotalTracks] = tracks
+			changes[tagwriter.FieldTotalDiscs] = discs
+		}
+	}
+
 	if err := i.tags.WriteUntrackedFileTags(p.Source, changes); err != nil {
 		return fmt.Errorf("write tags: %w", err)
 	}
@@ -282,6 +302,18 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 	return nil
 }
 
+// expectedPositions is the download's resolved tracklist as bare
+// positions.
+func expectedPositions(expected []ExpectedTrack) []tagtotals.Position {
+	out := make([]tagtotals.Position, 0, len(expected))
+
+	for _, t := range expected {
+		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
+	}
+
+	return out
+}
+
 // destinationFor computes a file's library path from the template.
 func (i *Importer) destinationFor(
 	p plannedFile,

backend/download/importer_test.go

@@ -446,3 +446,77 @@ func keysOf(m map[string]tagwriter.TagChanges) []string {
 
 	return out
 }
+
+// An imported album should arrive knowing its own size, or the album
+// page reads "in your library" from its first imported track onward --
+// which is the badge complaint this exists to answer.
+func TestImportWritesTheAlbumTotals(t *testing.T) {
+	t.Parallel()
+
+	f := newImportFixture(t,
+		"01 - Airbag.flac",
+		"02 - Paranoid Android.flac",
+		"03 - Subterranean Homesick Alien.flac",
+		"04 - Exit Music (For a Film).flac",
+	)
+
+	if _, err := f.importer.Import(
+		context.Background(),
+		fourTrackDownload(),
+		Result{Dir: f.dir, Files: f.files},
+		ImportOptions{LibraryRoot: f.root, WriteTags: true},
+	); err != nil {
+		t.Fatalf("Import: %v", err)
+	}
+
+	changes := f.tags.writes["01 - Airbag.flac"]
+	if changes == nil {
+		t.Fatal("no tag write recorded for the first track")
+	}
+
+	if got := changes[tagwriter.FieldTotalTracks]; got != 4 {
+		t.Errorf("%s: got %v, want 4", tagwriter.FieldTotalTracks, got)
+	}
+
+	if got := changes[tagwriter.FieldTotalDiscs]; got != 1 {
+		t.Errorf("%s: got %v, want 1", tagwriter.FieldTotalDiscs, got)
+	}
+}
+
+// A RecordingMBID anchor resolves Expected to exactly the one track it
+// asked for, so totalling it would tag a track off a twelve-track album
+// as "1 of 1" -- worse than saying nothing, because a declared total
+// outranks the catalog total that would have answered correctly.
+func TestImportWritesNoTotalsForATrackDownload(t *testing.T) {
+	t.Parallel()
+
+	f := newImportFixture(t, "01 - Airbag.flac")
+
+	dl := Download{
+		ID:            "dl-track",
+		LibraryID:     1,
+		RecordingMBID: "mbid-recording",
+		Artist:        "Radiohead",
+		Album:         "OK Computer",
+		Expected:      []ExpectedTrack{{Position: 1, Title: "Airbag"}},
+	}
+
+	if _, err := f.importer.Import(
+		context.Background(),
+		dl,
+		Result{Dir: f.dir, Files: f.files},
+		ImportOptions{LibraryRoot: f.root, WriteTags: true},
+	); err != nil {
+		t.Fatalf("Import: %v", err)
+	}
+
+	changes := f.tags.writes["01 - Airbag.flac"]
+	if changes == nil {
+		t.Fatal("no tag write recorded")
+	}
+
+	if _, ok := changes[tagwriter.FieldTotalTracks]; ok {
+		t.Errorf("%s written for a single-track download: %v",
+			tagwriter.FieldTotalTracks, changes[tagwriter.FieldTotalTracks])
+	}
+}

backend/download/reconcile.go

@@ -310,15 +310,35 @@ func (r *Reconciler) run(ctx context.Context, force bool) (Summary, error) {
 
 	summary.Synced = r.syncExternalLists(ctx)
 
-	attempted, started, err := r.attemptDue(ctx, force)
-	if err != nil {
-		return summary, err
+	// Nothing is searched for when there is nothing to search with, and
+	// the point is what that *does not* do to the list.
+	//
+	// Attempting anyway is not merely wasted work: every request comes
+	// back "no download clients are enabled", which RecordAttempt writes
+	// down as an attempt and schedules a retry for -- so a user who has
+	// deliberately built a wanted list with no client watched their
+	// requests accrue failures and announce "next check in 6 hours"
+	// about a check that cannot happen. Wanting something without a way
+	// to fetch it is a supported thing to do; being told it is being
+	// looked for is a lie.
+	//
+	// Everything above this line still runs: an artist subscription
+	// still expands, and a request the user satisfied by some other
+	// route -- ripped, bought, copied in -- is still retired, because
+	// neither needs a provider.
+	summary.NoProviders = len(r.manager.enabledProviders()) == 0
+
+	if !summary.NoProviders {
+		attempted, started, err := r.attemptDue(ctx, force)
+		if err != nil {
+			return summary, err
+		}
+
+		summary.Attempted = attempted
+		summary.Started = started
 	}
 
-	summary.Attempted = attempted
-	summary.Started = started
 	summary.Waiting = r.countWaiting(ctx)
-	summary.NoProviders = len(r.manager.enabledProviders()) == 0
 
 	r.logger.Info(
 		"reconciled request list",

backend/download/reconcile_test.go

@@ -453,6 +453,15 @@ func TestReconcileRespectsBatchSize(t *testing.T) {
 	f := newReconcileFixture(t)
 	ctx := context.Background()
 
+	// A client that searches and finds nothing. The batch size is about
+	// how many requests one pass *searches for*, which only means
+	// anything when there is something to search with -- a pass with no
+	// provider now attempts nothing at all, deliberately.
+	f.manager.installProvider(
+		Config{ID: 1, Priority: 50},
+		NewFakeProvider(1, "finds-nothing", Caps{CanSearch: true}),
+	)
+
 	f.reconciler.SetBatch(2)
 
 	for _, mbid := range []string{"rg-1", "rg-2", "rg-3", "rg-4"} {
@@ -593,3 +602,72 @@ func TestSummaryReportsNoProviders(t *testing.T) {
 		t.Error("summary did not report that no download client is enabled")
 	}
 }
+
+// ...and it does not search, which is the part the user sees.
+//
+// Attempting with no provider fails every request with "no download
+// clients are enabled", and RecordAttempt writes that down as an
+// attempt and schedules a retry -- so a wanted list built deliberately
+// without a client accrued failures and announced "next check in 6
+// hours" about a check that cannot happen. Wanting something with no
+// way to fetch it is supported; being told it is being looked for is
+// a lie.
+func TestNoProvidersMeansNoAttempt(t *testing.T) {
+	t.Parallel()
+
+	f := newReconcileFixture(t)
+	ctx := context.Background()
+
+	id, err := f.store.AddRequest(ctx, Request{
+		MBID:      "rg-1",
+		Entity:    EntityReleaseGroup,
+		LibraryID: 1,
+		Title:     "OK Computer",
+	})
+	if err != nil {
+		t.Fatalf("AddRequest: %v", err)
+	}
+
+	f.catalog.tracklists["rg-1"] = fourTrackDownload().Expected
+
+	summary, err := f.reconciler.RunNow(ctx)
+	if err != nil {
+		t.Fatalf("RunNow: %v", err)
+	}
+
+	if summary.Attempted != 0 {
+		t.Errorf("attempted %d requests with no client to search with, want 0",
+			summary.Attempted)
+	}
+
+	// The list still knows what is on it: "nothing happened" has to be
+	// reportable as "nothing was searched for, of the one thing you
+	// want" rather than as silence.
+	if summary.Waiting != 1 {
+		t.Errorf("summary reported %d waiting, want 1", summary.Waiting)
+	}
+
+	req, err := f.store.GetRequest(ctx, id)
+	if err != nil {
+		t.Fatalf("GetRequest: %v", err)
+	}
+
+	if req.Attempts != 0 {
+		t.Errorf("attempts = %d, want 0: a pass that could not search did not",
+			req.Attempts)
+	}
+
+	if req.LastError != "" {
+		t.Errorf("lastError = %q, want empty: the request did not fail, it "+
+			"was never tried", req.LastError)
+	}
+
+	// A new request is due immediately (next_try_at is set to now on
+	// insert), so the fault is not the presence of a time -- it is a
+	// time pushed into the future by a failed attempt, which is what the
+	// UI renders as "next check in 6 hours".
+	if req.NextTryAt.After(time.Now().Add(time.Minute)) {
+		t.Errorf("next try scheduled for %v: a check that cannot happen was "+
+			"put on the clock", req.NextTryAt)
+	}
+}

backend/explore/explore.go

@@ -2212,6 +2212,7 @@ func (e *Service) gatherTopCandidates(
 				ArtistType: a.Type,
 				Country:    a.Country,
 				InLibrary:  a.InLibrary,
+				LocalID:    a.LocalID,
 			},
 			category:     "artist",
 			qualityScore: quality,
@@ -2243,6 +2244,7 @@ func (e *Service) gatherTopCandidates(
 				ArtistType: a.Type,
 				Country:    a.Country,
 				InLibrary:  a.InLibrary,
+				LocalID:    a.LocalID,
 			},
 			category:     "artist",
 			qualityScore: quality,
@@ -2275,6 +2277,7 @@ func (e *Service) gatherTopCandidates(
 				PrimaryType:  rg.PrimaryType,
 				Year:         year,
 				InLibrary:    rg.InLibrary,
+				LocalID:      rg.LocalID,
 			},
 			category:     "release_group",
 			qualityScore: quality,
@@ -2320,6 +2323,7 @@ func (e *Service) gatherTopCandidates(
 				PrimaryType:  rg.PrimaryType,
 				Year:         year,
 				InLibrary:    rg.InLibrary,
+				LocalID:      rg.LocalID,
 			},
 			category:     "release_group",
 			qualityScore: quality,
@@ -2347,6 +2351,7 @@ func (e *Service) gatherTopCandidates(
 				CAAReleaseMBID: r.CAAReleaseMBID,
 				ReleaseName:    r.ReleaseName,
 				InLibrary:      r.InLibrary,
+				LocalID:        r.LocalID,
 			},
 			category:     "recording",
 			qualityScore: quality,
@@ -2403,6 +2408,7 @@ func (e *Service) gatherTopCandidates(
 				CAAReleaseMBID: r.CAAReleaseMBID,
 				ReleaseName:    r.ReleaseName,
 				InLibrary:      r.InLibrary,
+				LocalID:        r.LocalID,
 			},
 			category:     "recording",
 			qualityScore: quality,
@@ -2425,6 +2431,7 @@ func (e *Service) gatherTopCandidates(
 					ArtistType: m.ArtistType,
 					Country:    m.Country,
 					InLibrary:  m.InLibrary || m.LocalArtistID > 0,
+					LocalID:    m.LocalArtistID,
 				},
 				category:     "artist",
 				qualityScore: quality,
@@ -2445,6 +2452,7 @@ func (e *Service) gatherTopCandidates(
 					PrimaryType:  m.PrimaryType,
 					Year:         year,
 					InLibrary:    m.InLibrary || m.LocalReleaseGroupID > 0,
+					LocalID:      m.LocalReleaseGroupID,
 				},
 				category:     "release_group",
 				qualityScore: quality,
@@ -2459,6 +2467,7 @@ func (e *Service) gatherTopCandidates(
 					ArtistMBID:   m.ArtistMBID,
 					Length:       m.Duration,
 					InLibrary:    m.InLibrary || m.LocalRecordingID > 0,
+					LocalID:      m.LocalRecordingID,
 				},
 				category:     "recording",
 				qualityScore: quality,

backend/explore/types.go

@@ -41,7 +41,16 @@ type TopResult struct {
 	ReleaseGroupMBID string `json:"releaseGroupMbid,omitempty"`
 	ReleaseName      string `json:"releaseName,omitempty"`
 	// Library status — populated from index cross-reference columns.
-	InLibrary bool `json:"inLibrary"`
+	//
+	// LocalID is the one the cards read.  It is the local row behind
+	// this entity — an album, a file, an artist — and it is set and
+	// cleared by a test against `audio_files`, so it means "there is
+	// something of mine here".  InLibrary is written by the same pass
+	// but is a one-way ratchet the prune can only clear alongside a
+	// local id, so it is the weaker of the two and stays for scoring
+	// (`fwInLibrary`), which is where an approximate answer is fine.
+	InLibrary bool  `json:"inLibrary"`
+	LocalID   int64 `json:"localId,omitempty"`
 }
 
 // MBArtist is a Wails-friendly projection of a MusicBrainz artist.

backend/library/completeness_test.go

@@ -232,3 +232,112 @@ func TestGetAlbumCompleteness_EmptyAlbum(t *testing.T) {
 		t.Errorf("empty album reported %+v, want zero and unknown", got)
 	}
 }
+
+// The batch and the single-album query are two spellings of one
+// question, and the thing worth pinning is that they never disagree.
+//
+// They are genuinely different SQL — the single-album form is
+// correlated subqueries over one album, the batch is two grouping
+// levels over a slice — so the risk is not a typo but a drift in
+// meaning: a disc's total counted once per file, a duplicate counted
+// twice, a disc with no total silently covered by one that had one.
+// Every shape the table above cares about is staged here at once,
+// because a batch that is only ever asked about one album is not being
+// asked the question that can go wrong.
+func TestGetAlbumsCompletenessAgreesWithTheSingleAlbumQuery(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	shapes := map[int][]track{
+		1: disc(1, 100, 12, 12),
+		2: disc(1, 200, 9, 12),
+		3: disc(1, 300, 13, 12),
+		4: {{recordingID: 400, disc: 1, number: 1}},
+		5: append(disc(1, 500, 10, 10), disc(2, 600, 2, 5)...),
+		6: append(
+			disc(1, 700, 10, 10),
+			track{recordingID: 750, disc: 2, number: 1},
+		),
+		7: append(
+			disc(1, 800, 5, 6),
+			track{recordingID: 899, disc: 1, number: 3, total: 6},
+		),
+	}
+
+	ids := make([]int64, 0, len(shapes))
+
+	for albumID, tracks := range shapes {
+		stageAlbum(t, lib, albumID, tracks)
+		ids = append(ids, albumIDFor(t, lib, albumID))
+	}
+
+	batch, err := lib.GetAlbumsCompleteness(ids)
+	if err != nil {
+		t.Fatalf("GetAlbumsCompleteness: %v", err)
+	}
+
+	if len(batch) != len(ids) {
+		t.Fatalf("batch answered for %d albums, want %d", len(batch), len(ids))
+	}
+
+	for _, id := range ids {
+		one, err := lib.GetAlbumCompleteness(id)
+		if err != nil {
+			t.Fatalf("GetAlbumCompleteness(%d): %v", id, err)
+		}
+
+		if got := batch[id]; got != one {
+			t.Errorf("album %d: batch says %+v, single says %+v", id, got, one)
+		}
+	}
+}
+
+// An album with no files is absent from the batch, not zeroed.
+//
+// "I have none of this" and "I have no idea" are the third state Known
+// exists to keep apart, and a caller reading a missing key gets nothing
+// rather than a confident zero it would have to know to distrust.
+func TestGetAlbumsCompletenessOmitsAnAlbumWithNoFiles(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	stageAlbum(t, lib, 1, disc(1, 100, 3, 3))
+
+	held := albumIDFor(t, lib, 1)
+
+	got, err := lib.GetAlbumsCompleteness([]int64{held, 4242})
+	if err != nil {
+		t.Fatalf("GetAlbumsCompleteness: %v", err)
+	}
+
+	if _, ok := got[4242]; ok {
+		t.Errorf("an album with no files answered %+v, want absent", got[4242])
+	}
+
+	if !got[held].Complete {
+		t.Errorf("held album reported %+v, want complete", got[held])
+	}
+}
+
+// A caller with nothing to ask about must not issue a query at all —
+// sqlc's empty-slice branch rewrites the placeholder to NULL, which is
+// a perfectly valid query returning nothing, so this is about the round
+// trip rather than the answer.
+func TestGetAlbumsCompletenessAsksNothingForAnEmptyList(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	for _, ids := range [][]int64{nil, {}, {0}, {-1, 0}} {
+		got, err := lib.GetAlbumsCompleteness(ids)
+		if err != nil {
+			t.Fatalf("GetAlbumsCompleteness(%v): %v", ids, err)
+		}
+
+		if len(got) != 0 {
+			t.Errorf("GetAlbumsCompleteness(%v) = %+v, want empty", ids, got)
+		}
+	}
+}

backend/library/query.go

@@ -244,6 +244,65 @@ func (l *Library) GetAlbumCompleteness(albumID int64) (AlbumCompleteness, error)
 	}, nil
 }
 
+// GetAlbumsCompleteness answers the same question for a screenful of
+// albums in one query, keyed by album id.
+//
+// A card grid asks this about every card that has a local album behind
+// it, and one query per card is how a grid of fifty albums becomes
+// fifty round trips. The answer matters there for the reason it
+// matters on the album page: an album held 9 tracks of 12 has to show
+// the count, and a bare tick saying "in your library" is the complaint
+// this whole rule came from.
+//
+// An album with no row in the result is one with no files, and it is
+// absent rather than zeroed — "I have none of this" and "I have no
+// idea" are the same third state `Known` exists to keep apart, and a
+// caller reading a missing key gets nothing rather than a confident 0.
+func (l *Library) GetAlbumsCompleteness(
+	albumIDs []int64,
+) (map[int64]AlbumCompleteness, error) {
+	out := make(map[int64]AlbumCompleteness, len(albumIDs))
+
+	if len(albumIDs) == 0 {
+		return out, nil
+	}
+
+	keys := make([]sql.NullInt64, 0, len(albumIDs))
+
+	for _, id := range albumIDs {
+		if id <= 0 {
+			continue
+		}
+
+		keys = append(keys, sql.NullInt64{Int64: id, Valid: true})
+	}
+
+	if len(keys) == 0 {
+		return out, nil
+	}
+
+	rows, err := l.db.ReadQueries.GetAlbumsCompleteness(l.ctx, keys)
+	if err != nil {
+		l.logger.Error("could not get album completeness in batch",
+			"albums", len(keys), "error", err)
+
+		return nil, fmt.Errorf("could not get album completeness: %w", err)
+	}
+
+	for _, row := range rows {
+		known := row.Known != 0 && row.Expected > 0
+
+		out[row.AlbumID] = AlbumCompleteness{
+			Owned:    int(row.Owned),
+			Expected: int(row.Expected),
+			Known:    known,
+			Complete: known && row.Owned >= row.Expected,
+		}
+	}
+
+	return out, nil
+}
+
 // GetAlbumTracks returns one album's tracks in disc/track order.
 func (l *Library) GetAlbumTracks(albumID, libraryID int64) ([]Track, error) {
 	rows, err := l.db.ReadQueries.GetTracksByAlbum(

backend/mediacontrols/mpris_linux.go

@@ -279,17 +279,19 @@ func (h *MPRISHandler) enqueue(fn func()) {
 	}
 }
 
-// UpdateMetadata pushes track metadata to D-Bus.
-func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
-	h.mu.Lock()
-	h.trackID++
-	tid := h.trackID
-	h.mu.Unlock()
-
-	m := map[string]interface{}{
+// metadataMap builds the org.mpris.MediaPlayer2.Player Metadata value
+// for one track.
+//
+// It is separated from UpdateMetadata, which needs a live D-Bus
+// connection, so the map's contents can be asserted on: this file is
+// behind a build tag and everything in it that touches h is reachable
+// only from a session bus, which is the same reason the Android
+// contract lives in an untagged androidpayload.go.
+func metadataMap(meta Metadata, trackID uint64) map[string]any {
+	m := map[string]any{
 		"mpris:trackid": dbus.ObjectPath(
 			fmt.Sprintf(
-				"/org/yellowjacket/Track/%d", tid,
+				"/org/yellowjacket/Track/%d", trackID,
 			),
 		),
 	}
@@ -306,16 +308,45 @@ func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
 		m["xesam:album"] = meta.Album
 	}
 
+	// Always present, even with nothing to point at.
+	//
+	// Every other key here can be omitted safely because a client
+	// reading the map sees a track with no title or no album and
+	// renders it that way. Art is different: KDE's applet (and
+	// others) treat an *absent* mpris:artUrl as "no news about the
+	// art" and keep drawing whatever the last track had, so playing
+	// something with no cover left the previous album's sleeve on
+	// screen — which reads as the wrong track playing rather than as
+	// missing artwork.
+	//
+	// An empty string is the honest answer and is what the spec's
+	// "URI" type degrades to; a client that cannot load it falls back
+	// to its own placeholder, which is the behaviour wanted.
+	artURL := ""
 	if meta.ArtFilePath != "" {
-		m["mpris:artUrl"] = "file://" + meta.ArtFilePath
+		artURL = "file://" + meta.ArtFilePath
 	}
 
+	m["mpris:artUrl"] = artURL
+
 	if meta.DurationSec > 0 {
 		m["mpris:length"] = int64(
 			meta.DurationSec,
 		) * usPerSec
 	}
 
+	return m
+}
+
+// UpdateMetadata pushes track metadata to D-Bus.
+func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
+	h.mu.Lock()
+	h.trackID++
+	tid := h.trackID
+	h.mu.Unlock()
+
+	m := metadataMap(meta, tid)
+
 	h.enqueue(func() {
 		h.props.SetMust(playerIf, "Metadata", m)
 	})

backend/mediacontrols/mpris_linux_test.go

@@ -0,0 +1,86 @@
+//go:build linux && !android
+
+package mediacontrols
+
+import "testing"
+
+// The one key that must be present even when it is empty.
+//
+// Everything else in the map may be omitted, because a client reading
+// it renders a track with no title as a track with no title. Art is
+// different: KDE's applet treats an *absent* mpris:artUrl as no news
+// about the art and keeps drawing the last one it saw, so a track with
+// no cover wore the previous album's sleeve — which reads as the wrong
+// track playing rather than as missing artwork.
+func TestMetadataMapAlwaysCarriesArtURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		meta Metadata
+		want string
+	}{
+		{
+			name: "no art at all",
+			meta: Metadata{Title: "Blue in Green"},
+			want: "",
+		},
+		{
+			name: "art on disk",
+			meta: Metadata{
+				Title:       "Blue in Green",
+				ArtFilePath: "/covers/kind-of-blue_lg.jpg",
+			},
+			want: "file:///covers/kind-of-blue_lg.jpg",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			m := metadataMap(tt.meta, 1)
+
+			got, ok := m["mpris:artUrl"]
+			if !ok {
+				t.Fatal("mpris:artUrl is absent; it must always be sent")
+			}
+
+			if got != tt.want {
+				t.Errorf("mpris:artUrl = %v, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// The trackid has to change between tracks or a client is entitled to
+// treat the metadata as describing the same track it already has.
+func TestMetadataMapTrackIDVaries(t *testing.T) {
+	t.Parallel()
+
+	first := metadataMap(Metadata{Title: "A"}, 1)["mpris:trackid"]
+	second := metadataMap(Metadata{Title: "B"}, 2)["mpris:trackid"]
+
+	if first == second {
+		t.Errorf("trackid did not change: %v", first)
+	}
+}
+
+// The optional keys stay optional — this is what makes artUrl's
+// always-present treatment a deliberate exception rather than drift.
+func TestMetadataMapOmitsEmptyOptionalFields(t *testing.T) {
+	t.Parallel()
+
+	m := metadataMap(Metadata{}, 1)
+
+	for _, key := range []string{
+		"xesam:title",
+		"xesam:artist",
+		"xesam:album",
+		"mpris:length",
+	} {
+		if _, ok := m[key]; ok {
+			t.Errorf("%s is present for an empty Metadata", key)
+		}
+	}
+}

backend/queue/emit.go

@@ -81,6 +81,7 @@ func (q *Queue) emitTracksModified(
 			Index:        index,
 			Positions:    positions,
 			CurrentIndex: q.currentIndex,
+			Source:       q.source,
 		},
 	)
 }

backend/queue/emit_test.go

@@ -219,6 +219,56 @@ func TestEmit_AddTrackSendsDeltaNotSnapshot(t *testing.T) {
 	}
 }
 
+// The append clears the source, and the delta is the only event those
+// paths emit — so if it does not carry the source, the frontend keeps
+// the label it was last given and goes on offering a link back to an
+// album the queue no longer holds until something forces a full state.
+func TestEmit_AppendDeltaCarriesClearedSource(t *testing.T) {
+	t.Parallel()
+
+	q, db, rec := setupRecordedQueue(t)
+	paths := seedAudioFiles(t, db, 4)
+
+	q.SetQueue(
+		paths[:3], 0, false,
+		Source{Type: "album", ID: 1, Label: "Abbey Road"},
+	)
+
+	if _, ok := rec.Wait(events.QueueChanged, waitFor); !ok {
+		t.Fatalf("no QueueChanged after SetQueue; got %v", rec.Names())
+	}
+
+	rec.Reset()
+	q.AddTrack(paths[3])
+
+	if got := modifiedOf(t, rec).Source; got != (Source{}) {
+		t.Errorf("delta source = %+v, want zero value", got)
+	}
+}
+
+// And a delta that did not clear it still reports the source it has,
+// or the frontend would drop a perfectly good label on every removal.
+func TestEmit_NonAppendDeltaCarriesSource(t *testing.T) {
+	t.Parallel()
+
+	q, db, rec := setupRecordedQueue(t)
+	paths := seedAudioFiles(t, db, 4)
+
+	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
+	q.SetQueue(paths, 0, false, album)
+
+	if _, ok := rec.Wait(events.QueueChanged, waitFor); !ok {
+		t.Fatalf("no QueueChanged after SetQueue; got %v", rec.Names())
+	}
+
+	rec.Reset()
+	q.RemoveTrack(3)
+
+	if got := modifiedOf(t, rec).Source; got != album {
+		t.Errorf("delta source = %+v, want %+v", got, album)
+	}
+}
+
 func TestEmit_RemoveTracksReportsPositions(t *testing.T) {
 	t.Parallel()
 

backend/queue/queue.go

@@ -156,12 +156,21 @@ type PlaybackFailure struct {
 }
 
 // TracksModified is the payload for the QueueTracksModified event.
+//
+// Source is carried because an append is exactly what can *invalidate*
+// it: a queue built from one album stops being that album the moment a
+// track from somewhere else is added to it. The delta is the only event
+// those paths emit, so without this the frontend would keep the label
+// it was last given and go on saying "Playing from" an album that is no
+// longer what is queued — an event carrying what its consumer needs, so
+// nothing has to invalidate anything.
 type TracksModified struct {
 	Action       string  `json:"action"`
 	Tracks       []Track `json:"tracks,omitempty"`
 	Index        int     `json:"index"`
 	Positions    []int   `json:"positions,omitempty"`
 	CurrentIndex int     `json:"currentIndex"`
+	Source       Source  `json:"source"`
 }
 
 // Queue manages an ordered list of tracks for playback.
@@ -455,6 +464,8 @@ func (q *Queue) AddTrack(filePath string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistAddTrack(track)
 	q.persistState()
 	q.emitTracksModified(
@@ -505,6 +516,8 @@ func (q *Queue) AddTracks(filePaths []string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistAddTracks(newTracks)
 	q.persistState()
 	q.emitTracksModified(
@@ -563,6 +576,8 @@ func (q *Queue) InsertNextTracks(filePaths []string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistInsertTracks(newTracks, insertPos)
 	q.persistState()
 	q.emitTracksModified(
@@ -613,6 +628,8 @@ func (q *Queue) InsertNext(filePath string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistInsertTracks([]Track{track}, insertPos)
 	q.persistState()
 	q.emitTracksModified(
@@ -680,6 +697,8 @@ func (q *Queue) InsertTracksAt(filePaths []string, index int) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistInsertTracks(newTracks, index)
 	q.persistState()
 	q.emitTracksModified(
@@ -1537,6 +1556,31 @@ func (q *Queue) reindexPositions() {
 	}
 }
 
+// dropSource forgets which collection the queue was built from.
+//
+// A Source is a claim that everything queued came from one album,
+// playlist, genre or artist, and the frontend renders it as a
+// "Playing from X" link back to that page. Adding or inserting a track
+// makes the claim false — the queue is now that album *plus* something
+// else — so every path that does so calls this.
+//
+// It was set by SetQueue and cleared in exactly one place, Clear, so a
+// label survived every append. It is persisted too (source_type /
+// source_id / source_label on the queue state row), which is what made
+// a wrong label outlive the session that earned it: an album queued on
+// Monday, added to on Tuesday, still offered a link back to that album
+// on Friday.
+//
+// Removing, reordering and shuffling deliberately do not call this. A
+// queue with a track taken out of it, or played in another order, is
+// still that album — the link still goes somewhere true. Only the
+// arrival of a track from elsewhere makes it a lie.
+//
+// The caller must hold q.mu.
+func (q *Queue) dropSource() {
+	q.source = Source{}
+}
+
 // commitMutation persists the current queue state after a mutation.
 // When reindex is true, track positions are renumbered first.
 // The caller must hold q.mu.

backend/queue/queue_test.go

@@ -126,6 +126,117 @@ func TestClear_ResetsSource(t *testing.T) {
 	}
 }
 
+// A queue built from one album stops being that album the moment a
+// track from somewhere else joins it, so every path that adds one
+// drops the source. Before this, SetQueue was the only writer and
+// Clear the only clearer, so "Playing from Abbey Road" outlived every
+// append — and, being persisted, every restart too.
+func TestAppendPathsDropSource(t *testing.T) {
+	t.Parallel()
+
+	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
+
+	tests := []struct {
+		name   string
+		append func(q *Queue, paths []string)
+	}{
+		{
+			name: "AddTrack",
+			append: func(q *Queue, paths []string) {
+				q.AddTrack(paths[5])
+			},
+		},
+		{
+			name: "AddTracks",
+			append: func(q *Queue, paths []string) {
+				q.AddTracks(paths[5:7])
+			},
+		},
+		{
+			name: "InsertNext",
+			append: func(q *Queue, paths []string) {
+				q.InsertNext(paths[5])
+			},
+		},
+		{
+			name: "InsertNextTracks",
+			append: func(q *Queue, paths []string) {
+				q.InsertNextTracks(paths[5:7])
+			},
+		},
+		{
+			name: "InsertTracksAt",
+			append: func(q *Queue, paths []string) {
+				q.InsertTracksAt(paths[5:7], 1)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			q, db := setupTestQueue(t)
+			paths := seedAudioFiles(t, db, 8)
+
+			q.SetQueue(paths[:5], 0, false, album)
+
+			if got := q.GetState().Source; got != album {
+				t.Fatalf("source before append: got %+v, want %+v", got, album)
+			}
+
+			tt.append(q, paths)
+
+			if got := q.GetState().Source; got != (Source{}) {
+				t.Errorf(
+					"source after %s: got %+v, want zero value",
+					tt.name, got,
+				)
+			}
+		})
+	}
+}
+
+// Removing and reordering deliberately do not drop it: a queue with a
+// track taken out of it is still that album, and the link still goes
+// somewhere true.
+func TestRemoveAndMoveKeepSource(t *testing.T) {
+	t.Parallel()
+
+	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
+
+	t.Run("RemoveTrack", func(t *testing.T) {
+		t.Parallel()
+
+		q, db := setupTestQueue(t)
+		paths := seedAudioFiles(t, db, 5)
+
+		q.SetQueue(paths, 0, false, album)
+		q.RemoveTrack(3)
+
+		if got := q.GetState().Source; got != album {
+			t.Errorf("source after RemoveTrack: got %+v, want %+v", got, album)
+		}
+	})
+
+	t.Run("MoveQueueTracks", func(t *testing.T) {
+		t.Parallel()
+
+		q, db := setupTestQueue(t)
+		paths := seedAudioFiles(t, db, 5)
+
+		q.SetQueue(paths, 0, false, album)
+		q.MoveQueueTracks([]int{0}, 3)
+
+		if got := q.GetState().Source; got != album {
+			t.Errorf(
+				"source after MoveQueueTracks: got %+v, want %+v",
+				got, album,
+			)
+		}
+	})
+}
+
 func TestSetQueue_WithStartIndex(t *testing.T) {
 	t.Parallel()
 

backend/smartplaylist/smartplaylist.go

@@ -28,6 +28,7 @@ var (
 	errUnsupportedOp    = errors.New("unsupported operator")
 	errInvalidSortField = errors.New("invalid sort field: not in allowed field list")
 	errNotNumeric       = errors.New("value must be numeric")
+	errInvalidMatch     = errors.New("match must be \"all\" or \"any\"")
 )
 
 // Rule represents a single filter condition for a smart playlist.
@@ -37,13 +38,45 @@ type Rule struct {
 	Value    string `json:"value"`
 }
 
+// MatchType decides how a rule set's conditions combine.
+//
+// The rules used to be joined with " AND " and nothing else, so a
+// playlist could only ever narrow: "jazz released after 1960" was
+// expressible and "jazz or blues" was not, which is most of what
+// anyone reaches for a second rule to say.
+type MatchType string
+
+const (
+	// MatchAll requires every rule to hold — the historical behaviour,
+	// and what an empty match means so that every rule set written
+	// before this existed keeps the meaning it was saved with.
+	MatchAll MatchType = "all"
+	// MatchAny requires at least one rule to hold.
+	MatchAny MatchType = "any"
+)
+
+// joiner returns the SQL keyword that combines two conditions.
+// An unrecognised value cannot reach here — ParseRuleSet rejects one
+// — so the default is about the empty string, which is every rule set
+// saved before this field existed.
+func (m MatchType) joiner() string {
+	if m == MatchAny {
+		return " OR "
+	}
+
+	return " AND "
+}
+
 // RuleSet holds the complete filter configuration for a smart
 // playlist, including optional sort and limit.
 type RuleSet struct {
-	Rules     []Rule `json:"rules"`
-	Limit     int    `json:"limit,omitempty"`
-	SortField string `json:"sort_field,omitempty"`
-	SortDir   string `json:"sort_dir,omitempty"`
+	Rules []Rule `json:"rules"`
+	// Match is "all" or "any"; empty means "all". It is omitempty so
+	// an untouched playlist's stored JSON does not change shape.
+	Match     MatchType `json:"match,omitempty"`
+	Limit     int       `json:"limit,omitempty"`
+	SortField string    `json:"sort_field,omitempty"`
+	SortDir   string    `json:"sort_dir,omitempty"`
 }
 
 // fieldMap maps user-facing rule field names to track_metadata column
@@ -116,7 +149,12 @@ const genreDelimiter = "||"
 // slice of rules. It is a pure function — no database access needed.
 // Returns the clause (without the leading "WHERE"), the parameter
 // args, and any validation error.
-func BuildWhereClause(rules []Rule) (string, []any, error) {
+//
+// match decides how the conditions combine; an empty match is MatchAll,
+// which is what every rule set saved before the field existed means.
+func BuildWhereClause(
+	rules []Rule, match MatchType,
+) (string, []any, error) {
 	if len(rules) == 0 {
 		return "", nil, nil
 	}
@@ -179,7 +217,28 @@ func BuildWhereClause(rules []Rule) (string, []any, error) {
 		args = append(args, condArgs...)
 	}
 
-	return strings.Join(conditions, " AND "), args, nil
+	// Under OR, each condition is parenthesised; under AND it is not.
+	//
+	// The asymmetry is deliberate rather than an omission. AND is the
+	// tighter operator in SQL, so an OR-join has to protect any
+	// condition that contains a top-level AND of its own or the halves
+	// come apart: `days_since_played less_than` is
+	// `last_played IS NOT NULL AND <expr> < ?`, which read without
+	// brackets under an OR-join happens to still parse correctly and
+	// would stop doing so the moment a condition grows a top-level OR.
+	// Bracketing under AND would be a no-op semantically and would
+	// rewrite the clause every existing test pins, so the brackets go
+	// exactly where they change something.
+	if match == MatchAny {
+		bracketed := make([]string, len(conditions))
+		for i, cond := range conditions {
+			bracketed[i] = "(" + cond + ")"
+		}
+
+		conditions = bracketed
+	}
+
+	return strings.Join(conditions, match.joiner()), args, nil
 }
 
 // validateOperator checks that the operator is valid for the field
@@ -599,7 +658,7 @@ func Evaluate(
 	start := time.Now()
 	logger := db.Logger()
 
-	where, args, err := BuildWhereClause(ruleSet.Rules)
+	where, args, err := BuildWhereClause(ruleSet.Rules, ruleSet.Match)
 	if err != nil {
 		return nil, fmt.Errorf(
 			"smart playlist rule error: %w", err,
@@ -1036,6 +1095,16 @@ func ParseRuleSet(jsonStr string) (RuleSet, error) {
 		)
 	}
 
+	// A match nobody recognises would otherwise fall through to AND,
+	// which is a playlist quietly returning the wrong tracks rather
+	// than refusing to be saved. This is the only place a rule set
+	// enters the backend, so it is the only place that has to ask.
+	if rs.Match != "" && rs.Match != MatchAll && rs.Match != MatchAny {
+		return RuleSet{}, fmt.Errorf(
+			"%w: %q", errInvalidMatch, rs.Match,
+		)
+	}
+
 	return rs, nil
 }
 

backend/smartplaylist/smartplaylist_test.go

@@ -1,6 +1,7 @@
 package smartplaylist
 
 import (
+	"errors"
 	"strings"
 	"testing"
 
@@ -170,7 +171,7 @@ func TestBuildWhereClause_TextIs(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -189,7 +190,7 @@ func TestBuildWhereClause_TextIsNot(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is_not", Value: "Queen"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -209,7 +210,7 @@ func TestBuildWhereClause_TextContains(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "contains", Value: "Black"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -231,7 +232,7 @@ func TestBuildWhereClause_TextDoesNotContain(t *testing.T) {
 			Field: "title", Operator: "does_not_contain",
 			Value: "Black",
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -251,7 +252,7 @@ func TestBuildWhereClause_TextStartsWith(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "starts_with", Value: "Back"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -270,7 +271,7 @@ func TestBuildWhereClause_TextEndsWith(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "ends_with", Value: "Black"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -292,7 +293,7 @@ func TestBuildWhereClause_TextIsAnyOf(t *testing.T) {
 			Field: "artist", Operator: "is_any_of",
 			Value: `["Queen","AC/DC"]`,
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -312,7 +313,7 @@ func TestBuildWhereClause_NumericIs(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "is", Value: "1980"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -331,7 +332,7 @@ func TestBuildWhereClause_NumericIsNot(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "is_not", Value: "1980"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -350,7 +351,7 @@ func TestBuildWhereClause_NumericGreaterThan(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "greater_than", Value: "2000"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -369,7 +370,7 @@ func TestBuildWhereClause_NumericLessThan(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "less_than", Value: "1980"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -391,7 +392,7 @@ func TestBuildWhereClause_NumericBetween(t *testing.T) {
 			Field: "year", Operator: "between",
 			Value: "1975,1985",
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -414,7 +415,7 @@ func TestBuildWhereClause_NumericBetweenJSON(t *testing.T) {
 			Field: "year", Operator: "between",
 			Value: `["1975","1985"]`,
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -434,7 +435,7 @@ func TestBuildWhereClause_GenreIsProducesSubquery(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "is", Value: "Rock"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -466,7 +467,7 @@ func TestBuildWhereClause_GenreIsNotProducesSubquery(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "is_not", Value: "Rock"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -495,7 +496,7 @@ func TestBuildWhereClause_GenreIsAnyOfProducesSubquery(t *testing.T) {
 			Field: "genre", Operator: "is_any_of",
 			Value: `["Rock","Pop"]`,
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -524,7 +525,7 @@ func TestBuildWhereClause_GenreContainsUsesSubquery(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "contains", Value: "Rock"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -557,7 +558,7 @@ func TestBuildWhereClause_MultipleRulesAND(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{Field: "year", Operator: "greater_than", Value: "1975"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -572,6 +573,110 @@ func TestBuildWhereClause_MultipleRulesAND(t *testing.T) {
 	}
 }
 
+func TestBuildWhereClause_MultipleRulesOR(t *testing.T) {
+	t.Parallel()
+
+	clause, args, err := BuildWhereClause([]Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{Field: "year", Operator: "greater_than", Value: "1975"},
+	}, MatchAny)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	want := "(artist_name = ? COLLATE NOCASE) OR (year > ?)"
+	if clause != want {
+		t.Errorf("clause = %q, want %q", clause, want)
+	}
+
+	if len(args) != 2 || args[0] != "Queen" || args[1] != int64(1975) {
+		t.Errorf("args = %v, want [Queen 1975]", args)
+	}
+}
+
+// An empty match is what every rule set saved before the field existed
+// carries, and it has to keep meaning AND — a playlist silently
+// widening to OR on upgrade is the whole risk of adding this field.
+func TestBuildWhereClause_EmptyMatchIsAll(t *testing.T) {
+	t.Parallel()
+
+	rules := []Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{Field: "year", Operator: "greater_than", Value: "1975"},
+	}
+
+	empty, _, err := BuildWhereClause(rules, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	all, _, err := BuildWhereClause(rules, MatchAll)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if empty != all {
+		t.Errorf("empty match = %q, want the same as MatchAll %q",
+			empty, all)
+	}
+}
+
+// A condition carrying its own top-level AND is what makes the
+// bracketing under OR load-bearing: `days_since_played less_than`
+// is two predicates, and both belong to the same rule.
+func TestBuildWhereClause_ORBracketsCompoundCondition(t *testing.T) {
+	t.Parallel()
+
+	clause, _, err := BuildWhereClause([]Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{
+			Field:    "days_since_played",
+			Operator: "less_than",
+			Value:    "30",
+		},
+	}, MatchAny)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !strings.Contains(clause, "(last_played IS NOT NULL AND") {
+		t.Errorf(
+			"compound condition is not bracketed under OR: %q",
+			clause,
+		)
+	}
+}
+
+func TestParseRuleSet_RejectsUnknownMatch(t *testing.T) {
+	t.Parallel()
+
+	_, err := ParseRuleSet(`{"rules":[],"match":"either"}`)
+	if err == nil {
+		t.Fatal("expected an error for an unknown match type")
+	}
+
+	if !errors.Is(err, errInvalidMatch) {
+		t.Errorf("err = %v, want errInvalidMatch", err)
+	}
+}
+
+func TestParseRuleSet_AcceptsAnyAndAll(t *testing.T) {
+	t.Parallel()
+
+	for _, want := range []MatchType{MatchAll, MatchAny} {
+		rs, err := ParseRuleSet(
+			`{"rules":[],"match":"` + string(want) + `"}`,
+		)
+		if err != nil {
+			t.Fatalf("match %q: unexpected error: %v", want, err)
+		}
+
+		if rs.Match != want {
+			t.Errorf("match = %q, want %q", rs.Match, want)
+		}
+	}
+}
+
 func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 	t.Parallel()
 
@@ -581,7 +686,7 @@ func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 			Field: "genre", Operator: "does_not_contain",
 			Value: "Punk",
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -609,7 +714,7 @@ func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 func TestBuildWhereClause_EmptyRules(t *testing.T) {
 	t.Parallel()
 
-	clause, args, err := BuildWhereClause(nil)
+	clause, args, err := BuildWhereClause(nil, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -631,7 +736,7 @@ func TestBuildWhereClause_InvalidField(t *testing.T) {
 			Field: "nonexistent", Operator: "is",
 			Value: "anything",
 		},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal("expected error for invalid field, got nil")
 	}
@@ -654,7 +759,7 @@ func TestBuildWhereClause_InvalidOperatorForNumeric(t *testing.T) {
 
 	_, _, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "contains", Value: "1980"},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal(
 			"expected error for text operator on numeric field",
@@ -676,7 +781,7 @@ func TestBuildWhereClause_InvalidOperatorForText(t *testing.T) {
 			Field: "artist", Operator: "greater_than",
 			Value: "Queen",
 		},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal(
 			"expected error for numeric operator on text field",
@@ -723,6 +828,80 @@ func TestEvaluate_TextIs(t *testing.T) {
 	}
 }
 
+// Two rules that share no track at all: under AND this is empty, and
+// under OR it is the union. Before Match existed only the first was
+// expressible, so a playlist could only ever narrow — "jazz or blues"
+// had no way to be said.
+func TestEvaluate_MatchAnyUnionsWhereMatchAllIntersects(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	seedSmartPlaylistData(t, db)
+
+	// Queen has two tracks; Beyoncé has one; no track is by both.
+	rules := []Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{Field: "artist", Operator: "is", Value: "Beyoncé"},
+	}
+
+	all, err := Evaluate(db, RuleSet{Rules: rules, Match: MatchAll})
+	if err != nil {
+		t.Fatalf("Evaluate(all): %v", err)
+	}
+
+	if len(all) != 0 {
+		t.Errorf("match=all returned %d tracks, want 0", len(all))
+	}
+
+	either, err := Evaluate(db, RuleSet{Rules: rules, Match: MatchAny})
+	if err != nil {
+		t.Fatalf("Evaluate(any): %v", err)
+	}
+
+	if len(either) != 3 {
+		t.Fatalf("match=any returned %d tracks, want 3", len(either))
+	}
+
+	for _, tr := range either {
+		if tr.ArtistName != "Queen" && tr.ArtistName != "Beyoncé" {
+			t.Errorf(
+				"track %q has artist %q, want Queen or Beyoncé",
+				tr.TrackName, tr.ArtistName,
+			)
+		}
+	}
+}
+
+// An empty match is what every playlist saved before the field existed
+// carries, and it has to keep meaning AND all the way through Evaluate
+// — a stored playlist silently widening on upgrade is the only real
+// risk in adding this.
+func TestEvaluate_EmptyMatchStillIntersects(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	seedSmartPlaylistData(t, db)
+
+	tracks, err := Evaluate(db, RuleSet{
+		Rules: []Rule{
+			{Field: "artist", Operator: "is", Value: "Queen"},
+			{Field: "year", Operator: "greater_than", Value: "1979"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("Evaluate: %v", err)
+	}
+
+	// Only "Another One Bites the Dust" (Queen, 1980) satisfies both.
+	if len(tracks) != 1 {
+		t.Fatalf("got %d tracks, want 1", len(tracks))
+	}
+
+	if want := "Another One Bites the Dust"; tracks[0].TrackName != want {
+		t.Errorf("got %q, want %q", tracks[0].TrackName, want)
+	}
+}
+
 // TestEvaluate_ArtworkEnrichment verifies the presentation-only
 // cover-art and MusicBrainz-ID fields are attached to matched tracks
 // by the batched fetchArtwork pass (they are no longer part of the
@@ -1340,7 +1519,7 @@ func TestSQLInjection_FieldName(t *testing.T) {
 			Field:    "title; DROP TABLE playlists",
 			Operator: "is", Value: "x",
 		},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal(
 			"expected error for injected field name, got nil",

backend/tagtotals/tagtotals.go

@@ -0,0 +1,56 @@
+// Package tagtotals derives the totals a tag's "5/12" form declares.
+//
+// It exists because the two writers that know a release's full
+// tracklist -- the autotag apply pass and the download importer --
+// must not import each other or the tag writer, and because getting
+// the denominator wrong is invisible: a total that is too large marks
+// a complete album incomplete forever, and nothing fails.
+package tagtotals
+
+// Position is one track's place in a release.  A zero Disc means the
+// release did not say, which is disc 1.
+type Position struct {
+	Disc  int
+	Track int
+}
+
+// For returns the totals to write on a file sitting on disc `disc`:
+// how many tracks that disc has, and how many discs the release has.
+//
+// The track total is **per disc** and not the release's track count,
+// because that is what the tag form means and what
+// GetAlbumCompleteness sums -- summing a release total once per disc
+// would multiply a two-disc album's expectation by two.
+//
+// Tracks are counted by distinct position rather than by row: a
+// tracklist that lists a position twice is a defect in the source, and
+// counting it twice would put an album permanently out of reach of its
+// own total.
+func For(all []Position, disc int) (tracks, discs int) {
+	disc = normaliseDisc(disc)
+
+	seenTracks := make(map[int]struct{}, len(all))
+	seenDiscs := make(map[int]struct{}, 1)
+
+	for _, p := range all {
+		d := normaliseDisc(p.Disc)
+		seenDiscs[d] = struct{}{}
+
+		if d != disc || p.Track <= 0 {
+			continue
+		}
+
+		seenTracks[p.Track] = struct{}{}
+	}
+
+	return len(seenTracks), len(seenDiscs)
+}
+
+// normaliseDisc treats an undeclared disc as disc 1.
+func normaliseDisc(d int) int {
+	if d <= 0 {
+		return 1
+	}
+
+	return d
+}

backend/tagtotals/tagtotals_test.go

@@ -0,0 +1,92 @@
+package tagtotals_test
+
+import (
+	"testing"
+
+	"yellowjacket/backend/tagtotals"
+)
+
+func TestFor(t *testing.T) {
+	t.Parallel()
+
+	singleDisc := []tagtotals.Position{
+		{Disc: 0, Track: 1}, {Disc: 0, Track: 2}, {Disc: 0, Track: 3},
+	}
+
+	twoDiscs := []tagtotals.Position{
+		{Disc: 1, Track: 1},
+		{Disc: 1, Track: 2},
+		{Disc: 2, Track: 1},
+		{Disc: 2, Track: 2},
+		{Disc: 2, Track: 3},
+	}
+
+	tests := []struct {
+		name       string
+		all        []tagtotals.Position
+		disc       int
+		wantTracks int
+		wantDiscs  int
+	}{
+		{
+			name: "a single-disc release totals its own tracks",
+			all:  singleDisc, disc: 0, wantTracks: 3, wantDiscs: 1,
+		},
+		{
+			// An undeclared disc is disc 1, on both sides of the
+			// question -- a file tagged "disc 1" and a tracklist that
+			// declares no disc describe the same disc.
+			name: "an undeclared disc is disc 1",
+			all:  singleDisc, disc: 1, wantTracks: 3, wantDiscs: 1,
+		},
+		{
+			// The whole point: 5 here would be the release's track
+			// count, which summed once per disc claims a ten-track
+			// expectation for a five-track album.
+			name: "a multi-disc release totals the file's own disc",
+			all:  twoDiscs, disc: 2, wantTracks: 3, wantDiscs: 2,
+		},
+		{
+			name: "the other disc gets its own total",
+			all:  twoDiscs, disc: 1, wantTracks: 2, wantDiscs: 2,
+		},
+		{
+			// A disc the tracklist does not mention cannot be totalled,
+			// and 0 is how the caller is told to write nothing.
+			name: "a disc with no tracks totals nothing",
+			all:  twoDiscs, disc: 3, wantTracks: 0, wantDiscs: 2,
+		},
+		{
+			name: "an empty tracklist totals nothing",
+			all:  nil, disc: 1, wantTracks: 0, wantDiscs: 0,
+		},
+		{
+			// A source that lists a position twice would otherwise put
+			// the album permanently one track short of its own total.
+			name: "a repeated position counts once",
+			all: []tagtotals.Position{
+				{Disc: 1, Track: 1}, {Disc: 1, Track: 1}, {Disc: 1, Track: 2},
+			},
+			disc: 1, wantTracks: 2, wantDiscs: 1,
+		},
+		{
+			name: "a track with no position is not counted",
+			all: []tagtotals.Position{
+				{Disc: 1, Track: 0}, {Disc: 1, Track: 1},
+			},
+			disc: 1, wantTracks: 1, wantDiscs: 1,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			tracks, discs := tagtotals.For(tc.all, tc.disc)
+			if tracks != tc.wantTracks || discs != tc.wantDiscs {
+				t.Errorf("For(%v, %d) = (%d, %d), want (%d, %d)",
+					tc.all, tc.disc, tracks, discs, tc.wantTracks, tc.wantDiscs)
+			}
+		})
+	}
+}

backend/tagwriter/dbsync.go

@@ -183,6 +183,15 @@ func syncDatabase(
 		discNum = toNullInt64(v)
 	}
 
+	// The completeness evidence.  Without this the row keeps whatever
+	// the last scan read while the file on disk now declares a total,
+	// so the album stays "unknown" until a full rescan -- which is the
+	// state the report describes.
+	totalTracks := old.TotalTracks
+	if v, ok := asInt(params.changes[FieldTotalTracks]); ok {
+		totalTracks = toNullInt64(v)
+	}
+
 	composer := old.Composer
 	if v, ok := params.changes[FieldComposer].(string); ok {
 		composer = v
@@ -207,7 +216,7 @@ func syncDatabase(
 		AlbumID:            albumID,
 		TrackNumber:        trackNum,
 		DiscNumber:         discNum,
-		TotalTracks:        old.TotalTracks,
+		TotalTracks:        totalTracks,
 		Year:               year,
 		Composer:           composer,
 		Comment:            old.Comment,

backend/tagwriter/flac.go

@@ -101,6 +101,11 @@ func applyFlacTextChanges(cmt *flacvorbis.MetaDataBlockVorbisComment, changes Ta
 		{FieldYear, flacvorbis.FIELD_DATE, true},
 		{FieldTrackNumber, flacvorbis.FIELD_TRACKNUMBER, true},
 		{FieldDiscNumber, "DISCNUMBER", true},
+		// TRACKTOTAL/DISCTOTAL and no other spelling: dhowden/tag's
+		// Vorbis reader looks at exactly these two keys, so TOTALTRACKS
+		// or a "1/12" inside TRACKNUMBER reads back as no total at all.
+		{FieldTotalTracks, "TRACKTOTAL", true},
+		{FieldTotalDiscs, "DISCTOTAL", true},
 		{FieldComposer, "COMPOSER", false},
 	}
 

backend/tagwriter/mp3.go

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"os"
 	"strconv"
+	"strings"
 
 	id3v2 "github.com/bogem/id3v2/v2"
 
@@ -66,17 +67,10 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 		tag.SetYear(strconv.Itoa(v))
 	}
 
-	if v, ok := asInt(changes[FieldTrackNumber]); ok {
-		trckID := tag.CommonID("Track number/Position in set")
-		tag.DeleteFrames(trckID)
-		tag.AddTextFrame(trckID, id3v2.EncodingUTF8, strconv.Itoa(v))
-	}
-
-	if v, ok := asInt(changes[FieldDiscNumber]); ok {
-		tposID := tag.CommonID("Part of a set")
-		tag.DeleteFrames(tposID)
-		tag.AddTextFrame(tposID, id3v2.EncodingUTF8, strconv.Itoa(v))
-	}
+	applyPositionFrame(tag, "Track number/Position in set", changes,
+		FieldTrackNumber, FieldTotalTracks)
+	applyPositionFrame(tag, "Part of a set", changes,
+		FieldDiscNumber, FieldTotalDiscs)
 
 	if v, ok := changes[FieldComposer].(string); ok {
 		tag.DeleteFrames("TCOM")
@@ -90,6 +84,64 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 	}
 }
 
+// applyPositionFrame writes an ID3v2 position frame (TRCK or TPOS) in
+// the "n/N" form the readers parse.
+//
+// The number and the total are separate diff entries and either may be
+// absent, so the frame's *existing* value is the base: writing a total
+// alone must not discard the number that is already there, and writing
+// a number alone must not discard a total the file already declared.
+// A total with no number at all is not written, since "/12" says
+// nothing a reader can use.
+func applyPositionFrame(
+	tag *id3v2.Tag, description string, changes TagChanges, numKey, totalKey string,
+) {
+	_, hasNum := changes[numKey]
+	_, hasTotal := changes[totalKey]
+
+	if !hasNum && !hasTotal {
+		return
+	}
+
+	frameID := tag.CommonID(description)
+
+	num, total := parseXofN(
+		strings.TrimRight(tag.GetTextFrame(frameID).Text, "\x00 \t\n\r"),
+	)
+
+	if v, ok := asInt(changes[numKey]); ok {
+		num = v
+	}
+
+	if v, ok := asInt(changes[totalKey]); ok {
+		total = v
+	}
+
+	if num <= 0 {
+		return
+	}
+
+	value := strconv.Itoa(num)
+	if total > 0 {
+		value += "/" + strconv.Itoa(total)
+	}
+
+	tag.DeleteFrames(frameID)
+	tag.AddTextFrame(frameID, id3v2.EncodingUTF8, value)
+}
+
+// parseXofN splits an ID3v2 "n/N" position value.  A bare "n" yields a
+// zero total, and anything unparseable yields zeros — the same reading
+// dhowden/tag gives the frame.
+func parseXofN(s string) (int, int) {
+	numText, totalText, _ := strings.Cut(s, "/")
+
+	num, _ := strconv.Atoi(strings.TrimSpace(numText))
+	total, _ := strconv.Atoi(strings.TrimSpace(totalText))
+
+	return num, total
+}
+
 // applyCoverArtChanges handles the FieldCoverArt entry in the diff map.
 //
 //   - []byte with len > 0: embed the given image as front cover.

backend/tagwriter/ogg_vorbis.go

@@ -166,6 +166,8 @@ var oggFieldMappings = []struct { //nolint:gochecknoglobals // field mapping tab
 	{FieldYear, "DATE", true},
 	{FieldTrackNumber, "TRACKNUMBER", true},
 	{FieldDiscNumber, "DISCNUMBER", true},
+	{FieldTotalTracks, "TRACKTOTAL", true},
+	{FieldTotalDiscs, "DISCTOTAL", true},
 	{FieldComposer, "COMPOSER", false},
 }
 

backend/tagwriter/pipeline_test.go

@@ -333,3 +333,31 @@ func TestWriteTrackTags_DBSync(t *testing.T) {
 		t.Error("expected FTS5 result for 'New Title'")
 	}
 }
+
+// The row is what the album page reads, and it is only refreshed by a
+// scan.  Leaving total_tracks at whatever the last scan saw means an
+// album autotagged just now stays "unknown" -- a plain tick on an album
+// the user holds two tracks of -- until a full rescan happens to run.
+func TestWriteTrackTags_PersistsTheTotal(t *testing.T) {
+	db := database.NewTestDB(t)
+	dir := t.TempDir()
+	trackID := seedTestTrack(t, db, createPipelineTestMP3(t, dir))
+
+	tw := NewTagWriter(testLogger(), db, &mockPlayer{}, &mockPipelineLocker{})
+
+	if err := tw.WriteTrackTags(trackID, TagChanges{
+		FieldTrackNumber: 2,
+		FieldTotalTracks: 10,
+	}); err != nil {
+		t.Fatalf("WriteTrackTags: %v", err)
+	}
+
+	af, err := db.Queries.GetAudioFile(context.Background(), trackID)
+	if err != nil {
+		t.Fatalf("get audio file: %v", err)
+	}
+
+	if !af.TotalTracks.Valid || af.TotalTracks.Int64 != 10 {
+		t.Errorf("total_tracks: got %v, want 10", af.TotalTracks)
+	}
+}

backend/tagwriter/tagwriter.go

@@ -26,6 +26,15 @@ const (
 	FieldDiscNumber  = "disc_number"
 	FieldComposer    = "composer"
 	FieldCoverArt    = "cover_art" // []byte for set, nil for clear
+
+	// FieldTotalTracks is how many tracks are on *this file's disc*, not
+	// in the whole release.  That is what the "5/12" form declares and
+	// what GetAlbumCompleteness sums per disc; a release total written
+	// here would multiply the expectation by the number of discs.
+	FieldTotalTracks = "total_tracks"
+
+	// FieldTotalDiscs is how many discs the release has.
+	FieldTotalDiscs = "total_discs"
 )
 
 // AudioFormat represents a supported audio file format.

backend/tagwriter/totals_test.go

@@ -0,0 +1,199 @@
+package tagwriter
+
+import (
+	"path/filepath"
+	"testing"
+
+	"yellowjacket/backend/metadata"
+)
+
+// The totals are the evidence GetAlbumCompleteness reads, and every way
+// of getting them wrong is silent: a tag written under a name the
+// reader does not look at reads back as no total at all, which is
+// indistinguishable from never having written one.  So these assert the
+// round trip through the *reader the scan uses*, not the bytes.
+//
+// WAV is the exception and it is not this change's: dhowden/tag has no
+// RIFF reader at all, so metadata.ExtractTags cannot see a WAV's ID3
+// chunk -- which is why every other test here reads that chunk itself.
+func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
+	t.Parallel()
+
+	changes := TagChanges{
+		FieldTitle:       "Some Song",
+		FieldTrackNumber: 2,
+		FieldTotalTracks: 10,
+		FieldDiscNumber:  1,
+		FieldTotalDiscs:  2,
+	}
+
+	viaScanner := func(t *testing.T, path string) *metadata.TrackMetadata {
+		t.Helper()
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		return meta
+	}
+
+	tests := []struct {
+		name  string
+		write func(t *testing.T, dir string) string
+		read  func(t *testing.T, path string) *metadata.TrackMetadata
+	}{
+		{
+			name: "mp3",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := createTestMP3(t, dir, "totals.mp3", nil)
+				if err := writeMp3Tags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeMp3Tags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "flac",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := filepath.Join(dir, "totals.flac")
+				makeMinimalFLAC(t, path)
+
+				if err := writeFlacTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeFlacTags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "ogg",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := filepath.Join(dir, "totals.ogg")
+				createTestOGG(t, path)
+
+				if err := writeOggTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeOggTags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "wav",
+			read: readWavID3Tags,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := createTestWAV(t, dir, "totals.wav", nil)
+
+				if err := writeWavTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeWavTags: %v", err)
+				}
+
+				return path
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			meta := tc.read(t, tc.write(t, t.TempDir()))
+
+			assertIntField(t, "TrackNumber", meta.TrackNumber, 2)
+			assertIntField(t, "TotalTracks", meta.TotalTracks, 10)
+			assertIntField(t, "DiscNumber", meta.DiscNumber, 1)
+			assertIntField(t, "TotalDiscs", meta.TotalDiscs, 2)
+		})
+	}
+}
+
+// A number and a total are separate diff entries, so writing one must
+// not discard the other.  For ID3v2 they share a single "n/N" frame,
+// which is the only place this can go wrong -- and it goes wrong by
+// silently zeroing a total the file already declared.
+func TestWriteMp3Totals_PartialUpdateKeepsTheOtherHalf(t *testing.T) {
+	t.Parallel()
+
+	t.Run("writing the number keeps the total", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "seeded.mp3", TagChanges{
+			FieldTrackNumber: 2,
+			FieldTotalTracks: 10,
+		})
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTrackNumber: 4,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 4)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 10)
+	})
+
+	t.Run("writing the total keeps the number", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "seeded.mp3", TagChanges{
+			FieldTrackNumber: 7,
+		})
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTotalTracks: 12,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 7)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 12)
+	})
+
+	// "/12" says nothing a reader can use, and dhowden/tag reads it as
+	// track 0 -- which the scan would store as a real track number.
+	t.Run("a total with no number writes nothing", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "bare.mp3", nil)
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTotalTracks: 12,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 0)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 0)
+	})
+}

backend/tagwriter/wav_test.go

@@ -522,19 +522,20 @@ func readWavID3Tags(
 		}
 	}
 
-	// Track number (TRCK).
+	// Track number and total (TRCK), disc number and total (TPOS).
+	// Both carry the "n/N" form, so they are read the way a reader
+	// reads them rather than with Atoi -- which sees "2/10" as 0.
 	trckID := parsed.CommonID("Track number/Position in set")
 	if frames := parsed.GetFrames(trckID); len(frames) > 0 {
 		if tf, ok := frames[0].(id3v2.TextFrame); ok {
-			meta.TrackNumber = atoiSafe(tf.Text)
+			meta.TrackNumber, meta.TotalTracks = parseXofN(tf.Text)
 		}
 	}
 
-	// Disc number (TPOS).
 	tposID := parsed.CommonID("Part of a set")
 	if frames := parsed.GetFrames(tposID); len(frames) > 0 {
 		if tf, ok := frames[0].(id3v2.TextFrame); ok {
-			meta.DiscNumber = atoiSafe(tf.Text)
+			meta.DiscNumber, meta.TotalDiscs = parseXofN(tf.Text)
 		}
 	}
 

docs/android-release.md

@@ -7,12 +7,22 @@ which is what lets Obtainium poll a plain URL with no token. It also
 attaches the same file to the Gitea release, which is what a person
 looking at the release page downloads.
 
-**Tags are not pushed by hand any more.** `.gitea/workflows/release.yml`
-reads the Conventional Commits on every merge to `main`, decides the
-version, and pushes the tag this workflow is keyed on — so releasing the
-APK means merging a `fix:` or `feat:` commit, not running `git tag`. The
-`workflow_dispatch` path below remains, for rebuilding a tag that already
-exists.
+**Tags are not pushed by hand any more, but releasing is a decision.**
+`.gitea/workflows/release.yml` reads the Conventional Commits since the
+last tag, decides the version, and pushes the tag this workflow is keyed
+on — so releasing the APK means **running that workflow**, not running
+`git tag`. It has no push trigger: merging a `fix:` or `feat:` used to
+be enough and produced a version per merged PR (issue #115). Run it with
+`dry_run` first to see what the accumulated commits would ship. The
+`workflow_dispatch` path below is a different thing and remains, for
+rebuilding a tag that already exists.
+
+**A prerelease tag is skipped here**, cleanly. This workflow triggers on
+`v*`, which matches `v0.4.0-beta.1`, and it is the one where that would
+hurt most: the APK goes to the credential-free generic registry that
+Obtainium polls, and the `versionCode` maths below splits on dots — it
+would read `1` out of `0-beta` and produce a wrong number rather than a
+failed build.
 
 ## The 1.x installs cannot be upgraded to 0.0.x
 

docs/dev/config-suggestions.md

@@ -1,194 +0,0 @@
-# Config Improvement Suggestions
-
-Remaining suggestions for improving the configuration system in YellowJacket.
-
-## 2. Thread Safety Concerns
-
-The current `Config` struct lacks synchronization:
-- `Load()` and `Save()` can race with concurrent reads
-- `handleConfigUpdate()` in library mutates `l.conf.DirectoryPath` without locks
-
-**Suggestion:** Add a `sync.RWMutex` to protect config access, especially if config is read during scans.
-
-```go
-type Config struct {
-    mu       sync.RWMutex
-    ctx      context.Context
-    logger   *slog.Logger
-    // ...
-}
-
-func (c *Config) Load() error {
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    // ...
-}
-```
-
-## 3. Nil Safety in Validation
-
-In `config.go`, validation only runs if `c.Library != nil`, but `handleConfigPost` dereferences `postedConfig.Library` without checking for nil:
-
-```go
-if postedConfig.Library != nil {
-    c.Library = postedConfig.Library
-    // ...
-}
-```
-
-**Status:** Partially addressed in the event refactor, but consider adding explicit nil checks in `Validate()` as well.
-
-## 4. Inconsistent Error Handling on HTTP Responses
-
-In `httphandler.go:28-31`, `WriteHeader` is called *after* rendering the error template, which won't work as expected (headers must be set before writing body):
-
-```go
-c.formSubmitError(err.Error()).Render(r.Context(), w)
-w.WriteHeader(http.StatusInternalServerError)  // Too late!
-```
-
-**Fix:** Set the status code before rendering:
-
-```go
-w.WriteHeader(http.StatusInternalServerError)
-c.formSubmitError(err.Error()).Render(r.Context(), w)
-```
-
-## 5. Make `scanWorkerCount` Configurable
-
-There's a TODO at `library.go:289`:
-```go
-// TODO: make configurable via Config.
-var scanWorkerCount = goruntime.NumCPU()
-```
-
-**Suggestion:** Add this to `library.Config`:
-
-```go
-type Config struct {
-    DirectoryPath Directory `form:"Directory" schema:"directory,required"`
-    ScanWorkers   int       `form:"ScanWorkers" schema:"scan_workers"`
-}
-```
-
-Then in `NewLibrary()` or `Scan()`:
-
-```go
-workers := l.conf.ScanWorkers
-if workers <= 0 {
-    workers = goruntime.NumCPU()
-}
-```
-
-## 6. Consider Config Defaults
-
-Currently if no config exists, an empty one is saved. Consider providing sensible defaults (e.g., common music directories like `~/Music`).
-
-```go
-func (c *Config) setDefaults() {
-    if c.Library == nil {
-        c.Library = &library.Config{}
-    }
-    if c.Library.DirectoryPath == "" {
-        // Try common music directories
-        home, _ := os.UserHomeDir()
-        musicDir := filepath.Join(home, "Music")
-        if info, err := os.Stat(musicDir); err == nil && info.IsDir() {
-            c.Library.DirectoryPath = library.Directory(musicDir)
-        }
-    }
-}
-```
-
-## 7. Config Reload/Watch Capability
-
-The config is only loaded at startup. Consider adding:
-- File watcher for external config changes (using `fsnotify`)
-- Explicit reload method callable from UI
-
-```go
-func (c *Config) Watch() error {
-    watcher, err := fsnotify.NewWatcher()
-    if err != nil {
-        return err
-    }
-    
-    go func() {
-        for event := range watcher.Events {
-            if event.Op&fsnotify.Write == fsnotify.Write {
-                c.Load()
-                // Emit event for listeners
-            }
-        }
-    }()
-    
-    return watcher.Add(c.filePath)
-}
-```
-
-## 8. Validation Should Return Structured Errors
-
-Currently validation returns combined errors. Consider returning a structured validation result that the UI can map to specific fields for better user feedback.
-
-```go
-type ValidationError struct {
-    Field   string
-    Message string
-}
-
-type ValidationResult struct {
-    Valid  bool
-    Errors []ValidationError
-}
-
-func (c *Config) ValidateStructured() ValidationResult {
-    var result ValidationResult
-    result.Valid = true
-    
-    if c.Library != nil {
-        if err := c.Library.Validate(); err != nil {
-            result.Valid = false
-            result.Errors = append(result.Errors, ValidationError{
-                Field:   "Library.DirectoryPath",
-                Message: err.Error(),
-            })
-        }
-    }
-    
-    return result
-}
-```
-
-## 9. Use Standard Library for Config Paths
-
-The path construction in `system/userdata.go` doesn't respect `$XDG_CONFIG_HOME` on Linux or use the standard Go `os.UserConfigDir()`.
-
-**Current implementation:**
-```go
-case "linux":
-    return fmt.Sprintf("/home/%s/%s/yellowjacket", username, unixSubdirs[dt]), nil
-```
-
-**Suggested improvement:**
-```go
-func GetUserConfigDirPath() (string, error) {
-    baseDir, err := os.UserConfigDir()  // Respects XDG_CONFIG_HOME
-    if err != nil {
-        return "", fmt.Errorf("could not get user config directory: %w", err)
-    }
-    
-    path := filepath.Join(baseDir, "yellowjacket")
-    
-    if err := os.MkdirAll(path, 0o755); err != nil {
-        return "", fmt.Errorf("could not create config directory: %w", err)
-    }
-    
-    return path, nil
-}
-```
-
-This approach:
-- Respects `$XDG_CONFIG_HOME` on Linux
-- Uses proper macOS paths (`~/Library/Application Support`)
-- Uses `%AppData%` on Windows
-- Is more portable and follows platform conventions

docs/dev/overview.md

@@ -1,53 +0,0 @@
-# Development Overview
-
-YellowJacket is a moderately complex application. This document gives an overview of how development of it works.
-
-## Logical Breakdown
-
-YellowJacket can be thought about in a heirarchy of logical modules and components. The borders of these logical sections are mostly represented in the code and directory structure as well.
-
-- Frontend
-  - UI Components (see [Lit](###lit-web-components))
-- Backend
-  - App
-    - Asset Handler
-    - Logging
-    - System
-  - Player
-  - Library
-  - Config
-  - Database
-    - Queries (see [sqlc](###sqlc))
-
-## Dependencies
-
-YellowJacket uses many tools and libraries to provide its functionality. 
-This section lists each of these dependencies and explains how they are used.
-
-### [Wails](https://wails.io)
-
-Used to create desktop apps with Go and web technologies.
-
-### [SQLite](https://github.com/mattn/go-sqlite3?tab=readme-ov-file#go-sqlite3)
-
-Used for local database.
-
-### [sqlc](https://sqlc.dev/)
-
-Used to generate Go code from SQL.
-
-### [Templ](https://templ.guide/)
-
-Used to generate HTML templates with Go code.
-
-### [Beep](https://github.com/gopxl/beep?tab=readme-ov-file#beep)
-
-Used for audio playback.
-
-### [Lit Web Components](https://lit.dev/)
-
-Used for dynamic/reactive frontend components.
-
-### [HTMX](https://htmx.org/)
-
-Used for requesting HTML fragments from the backend and rendering them on the frontend.

e2e/specs/queue-toggle-state.spec.ts

@@ -0,0 +1,66 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * The queue button says whether the queue is open.
+ *
+ * It used to look identical in both states, so the only way to tell
+ * what pressing it would do was to look at the other side of the window
+ * and infer it — and for anyone not looking at all there was nothing to
+ * infer from: no `aria-expanded`, no `aria-controls`, no pressed state.
+ *
+ * The state is reflected *from the panel*, not kept beside the click,
+ * because the button is not the only thing that opens the queue —
+ * `now-playing-view` sets the same attribute, since it hides the bar
+ * this button lives in. A flag maintained by the click handler would be
+ * right until something else opened the panel and then quietly wrong,
+ * which is the second test here.
+ */
+test.describe('the queue toggle', () => {
+  test('reports open and closed, and names what it controls', async ({
+    app,
+  }) => {
+    const toggle = app.locator('#queue-button');
+
+    await expect(toggle).toHaveAttribute('aria-controls', 'queue-panel');
+    await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+
+    await toggle.click();
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+    // The state is not only in the accessibility tree: a control that
+    // announces a state it does not draw is half a fix.
+    //
+    // Background rather than colour, because the pointer is still on
+    // the button after the click and `:hover` paints it the same accent
+    // the open state does -- so a colour comparison here passes on the
+    // broken build and proves nothing.
+    const [open, closed] = await toggle.evaluate((el) => {
+      const now = getComputedStyle(el).backgroundColor;
+
+      el.setAttribute('aria-expanded', 'false');
+      const shut = getComputedStyle(el).backgroundColor;
+
+      el.setAttribute('aria-expanded', 'true');
+
+      return [now, shut];
+    });
+
+    expect(open).not.toBe(closed);
+
+    await toggle.click();
+    await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  test('follows the panel when something else opens it', async ({ app }) => {
+    const toggle = app.locator('#queue-button');
+
+    await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+
+    // Exactly what `now-playing-view`'s queue button does.
+    await app.evaluate(() =>
+      document.getElementById('queue-panel')?.setAttribute('open', ''),
+    );
+
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  });
+});

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

@@ -431,8 +431,17 @@ export interface TopResult {
 
     /**
      * Library status — populated from index cross-reference columns.
+     * 
+     * LocalID is the one the cards read.  It is the local row behind
+     * this entity — an album, a file, an artist — and it is set and
+     * cleared by a test against `audio_files`, so it means "there is
+     * something of mine here".  InLibrary is written by the same pass
+     * but is a one-way ratchet the prune can only clear alongside a
+     * local id, so it is the weaker of the two and stays for scoring
+     * (`fwInLibrary`), which is where an approximate answer is fine.
      */
     "inLibrary": boolean;
+    "localId"?: number;
 }
 
 /**

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

@@ -98,6 +98,26 @@ export function GetAlbumsByArtist(artist: string, libraryID: number): $Cancellab
     return $Call.ByID(1456840721, artist, libraryID);
 }
 
+/**
+ * GetAlbumsCompleteness answers the same question for a screenful of
+ * albums in one query, keyed by album id.
+ * 
+ * A card grid asks this about every card that has a local album behind
+ * it, and one query per card is how a grid of fifty albums becomes
+ * fifty round trips. The answer matters there for the reason it
+ * matters on the album page: an album held 9 tracks of 12 has to show
+ * the count, and a bare tick saying "in your library" is the complaint
+ * this whole rule came from.
+ * 
+ * An album with no row in the result is one with no files, and it is
+ * absent rather than zeroed — "I have none of this" and "I have no
+ * idea" are the same third state `Known` exists to keep apart, and a
+ * caller reading a missing key gets nothing rather than a confident 0.
+ */
+export function GetAlbumsCompleteness(albumIDs: number[] | null): $CancellablePromise<{ [_ in `${number}`]?: $models.AlbumCompleteness } | null> {
+    return $Call.ByID(531636827, albumIDs);
+}
+
 /**
  * GetAllLibrariesWithTrackCounts lists the libraries and their sizes.
  */

frontend/index.css

@@ -207,6 +207,17 @@ body div.sidebar {
         color: var(--yj-accent, #ffd43b);
     }
 
+    /* An open queue is a state this button can be in, and it used to
+       look exactly like the closed one -- so the only way to tell what
+       pressing it would do was to look at the other side of the window
+       and infer it. `aria-expanded` is the same fact for anyone not
+       looking at all, and it points at the panel it controls. */
+    #queue-button[aria-expanded='true'] {
+        color: var(--yj-accent, #ffd43b);
+        background: var(--yj-bg-overlay, #404040);
+        border-radius: 4px;
+    }
+
     #queue-button.drag-over {
         color: var(--yj-accent, #ffd43b);
         outline: 2px dashed var(--yj-accent, #ffd43b);

frontend/index.html

@@ -37,8 +37,12 @@
     <footer class="bottom-bar">
         <now-playing></now-playing>
         <audio-player></audio-player>
-        <button aria-label="Toggle queue" id="queue-button">
-            <wa-icon name="list"></wa-icon>
+        <button aria-label="Toggle queue" aria-controls="queue-panel" aria-expanded="false"
+            id="queue-button">
+            <!-- ICON_QUEUE in src/utils/icon-language.ts, written out
+                 because this file has no module scope. It was `list`,
+                 which is the Playlists destination's icon. -->
+            <wa-icon name="bars-staggered"></wa-icon>
         </button>
     </footer>
     <!-- The phone's primary navigation, hidden above 600px by

frontend/index.ts

@@ -521,6 +521,28 @@ if (queueButton && queuePanel) {
         }
     });
 
+    // The button says whether the panel is open, and it learns that
+    // from the panel rather than from its own click handler.
+    //
+    // It is not the only thing that opens the queue -- `now-playing-view`
+    // sets the same attribute, because it hides the bar this button
+    // lives in -- so a state kept beside the click would be right until
+    // something else opened the panel and then quietly wrong. The panel's
+    // `open` attribute is the one fact; this reflects it.
+    const reflectQueueState = () => {
+        queueButton.setAttribute(
+            'aria-expanded',
+            String(queuePanel.hasAttribute('open')),
+        );
+    };
+
+    new MutationObserver(reflectQueueState).observe(queuePanel, {
+        attributes: true,
+        attributeFilter: ['open'],
+    });
+
+    reflectQueueState();
+
     // ---------------------------------------------------------------
     // Queue button as drop target (when queue panel is closed)
     // ---------------------------------------------------------------

frontend/src/assets/icons/fa/solid/bars-staggered.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.3.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2026 Fonticons, Inc. --><path fill="currentColor" d="M0 96C0 78.3 14.3 64 32 64l384 0c17.7 0 32 14.3 32 32s-14.3 32-32 32L32 128C14.3 128 0 113.7 0 96zM64 256c0-17.7 14.3-32 32-32l384 0c17.7 0 32 14.3 32 32s-14.3 32-32 32L96 288c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32L32 448c-17.7 0-32-14.3-32-32s14.3-32 32-32l384 0c17.7 0 32 14.3 32 32z"/></svg>

frontend/src/components/artists-view/artists-view.ts

@@ -37,6 +37,10 @@ import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js'
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@components/playlist-picker/playlist-picker.js';
 import { dict, list } from '@utils/binding';
+import {
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 
 /** Pixels to change card width per scroll tick. */
 const ZOOM_STEP = 16;
@@ -1371,7 +1375,7 @@ export class ArtistsView
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_QUEUE}
                                   ></wa-icon>
                                   Add to Queue
                               </wa-dropdown-item>
@@ -1407,7 +1411,7 @@ export class ArtistsView
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_PLAYLIST}
                                   ></wa-icon>
                                   Add to Playlist
                                   <span

frontend/src/components/audio-player/seekbar/seek-bar.ts

@@ -68,6 +68,29 @@ export class SeekBar extends LitElement {
       align-items: center;
     }
 
+    /* The clocks must not resize as they count.
+
+       Two things move them, and they need different answers. Digits in
+       a proportional font are different widths, so 1:11 is narrower
+       than 4:08 and the bar breathed once a second -- that is what
+       tabular figures fix. The character *count* changes too, at the
+       hundredth minute and whenever the right-hand clock is toggled to
+       remaining and grows a minus sign, and a figure width cannot fix
+       that -- so each clock also reserves the widest string this track
+       can put in it. The budget is per track rather than a constant
+       because reserving six characters on every track would push the
+       slider in by a character at each end for nothing. */
+    #seek-bar-container small,
+    .time-toggle {
+      font-variant-numeric: tabular-nums;
+      flex: 0 0 auto;
+      min-width: calc(var(--yj-clock-chars, 5) * 1ch);
+    }
+
+    #seek-bar-container small {
+      text-align: left;
+    }
+
     .time-toggle {
       background: none;
       border: none;
@@ -76,6 +99,9 @@ export class SeekBar extends LitElement {
       font: inherit;
       font-size: var(--wa-font-size-s, 0.875rem);
       cursor: pointer;
+      /* One more for the minus sign the remaining form carries. */
+      min-width: calc((var(--yj-clock-chars, 5) + 1) * 1ch);
+      text-align: right;
     }
 
     .time-toggle:hover,
@@ -219,8 +245,19 @@ export class SeekBar extends LitElement {
       : formatSeconds(this.trackLength);
     const rightTime = this.hasTrack ? rightLabel : '--:--';
 
+    // The widest string either clock can hold for *this* track. The
+    // duration is the longest elapsed value there can be, so its length
+    // is the budget; `--:--` is five, which is also the floor.
+    const clockChars = Math.max(
+      5,
+      this.hasTrack ? formatSeconds(this.trackLength).length : 0,
+    );
+
     return html`
-      <div id="seek-bar-container">
+      <div
+        id="seek-bar-container"
+        style="--yj-clock-chars: ${clockChars}"
+      >
         <small data-testid="elapsed-time">${elapsedTime}</small>
         <wa-slider
           label="Seek"

frontend/src/components/bottom-nav/bottom-nav.ts

@@ -6,6 +6,7 @@ import type WaDrawer from '@awesome.me/webawesome/dist/components/drawer/drawer.
 import { designTokens } from '../../styles/tokens.css';
 import '../sidebar/app-sidebar.js';
 import { nameDialog } from '@utils/name-dialog';
+import { ICON_PLAYLIST } from '@utils/icon-language';
 
 type View = 'home' | 'albums' | 'tracks' | 'playlists';
 
@@ -138,7 +139,7 @@ export class BottomNav extends LitElement {
         { id: 'home', label: 'Home', icon: 'house' },
         { id: 'albums', label: 'Albums', icon: 'compact-disc' },
         { id: 'tracks', label: 'Tracks', icon: 'music' },
-        { id: 'playlists', label: 'Playlists', icon: 'list' },
+        { id: 'playlists', label: 'Playlists', icon: ICON_PLAYLIST },
     ];
 
     override connectedCallback() {

frontend/src/components/cover-grid/cover-grid-styles.ts

@@ -111,13 +111,32 @@ const gridStyles = css`
         scale: 0.95;
     }
 
+    /* Title and year on one line, and only the title truncates.
+
+       The year used to be part of the same run of text, so it was the
+       first thing an ellipsis ate: a card wide enough for a long album
+       name never showed its year, and browsing by year showed years
+       only for the albums with short names -- the sort said one thing
+       and the cards showed another.
+
+       A flex row rather than a second line, because the card's height
+       is what the virtualizer measures rows by. */
     .album-name {
         font-size: var(--album-name-font, 14px);
         font-weight: 400;
         color: var(--yj-text-primary, #fff);
+        display: flex;
+        justify-content: center;
+        align-items: baseline;
+        gap: 0.35em;
+        min-width: 0;
+    }
+
+    .album-title {
         white-space: nowrap;
         overflow: hidden;
         text-overflow: ellipsis;
+        min-width: 0;
     }
 
     .artist-name {
@@ -131,6 +150,8 @@ const gridStyles = css`
 
     .album-year {
         color: var(--yj-text-tertiary, #888);
+        flex: 0 0 auto;
+        white-space: nowrap;
     }
 
     /* ========================================

frontend/src/components/cover-grid/cover-grid.ts

@@ -76,6 +76,10 @@ import type {
     SortDirection,
 } from './cover-grid-types.js';
 import { list } from '@utils/binding';
+import {
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 
 @customElement('cover-grid')
 export class CoverGrid
@@ -1902,10 +1906,10 @@ export class CoverGrid
                         class="album-name"
                         title="${album.Name}"
                     >
-                        ${album.Name}${album.Year
-                ? html`
-                              <span class="album-year">
-                                  (${album.Year})</span
+                        <span class="album-title">${album.Name}</span
+                        >${album.Year
+                ? html`<span class="album-year"
+                                  >(${album.Year})</span
                               >`
                 : nothing}
                     </div>
@@ -2123,7 +2127,7 @@ export class CoverGrid
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_QUEUE}
                                   ></wa-icon>
                                   Add to Queue
                               </wa-dropdown-item>
@@ -2156,7 +2160,7 @@ export class CoverGrid
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_PLAYLIST}
                                   ></wa-icon>
                                    Add to Playlist
                                    <span

frontend/src/components/downloads-view/downloads-view.ts

@@ -512,7 +512,9 @@ export class DownloadsView extends ViewLifecycleMixin(LitElement) {
                         ${request.artist ? `${request.artist} — ` : ''}${request.title ||
                         request.mbid}
                     </div>
-                    <div class="detail">${requestDetail(request, this.nowMs)}</div>
+                    <div class="detail">
+                        ${requestDetail(request, this.nowMs, this.canDownload)}
+                    </div>
                 </div>
                 <div class="actions">
                     ${request.state === 'satisfied'
@@ -706,10 +708,20 @@ export class DownloadsView extends ViewLifecycleMixin(LitElement) {
  * looked for rather than as an error, because that is what it is — the
  * retry is already scheduled and there is nothing for the user to do.
  */
-function requestDetail(request: Request, nowMs: number): string {
+function requestDetail(
+    request: Request,
+    nowMs: number,
+    canDownload: boolean,
+): string {
     if (request.state === 'satisfied') return 'In your library';
     if (request.state === 'paused') return 'Paused — not being looked for';
 
+    // With no client there is no search and no retry clock — the
+    // backend stopped scheduling one — so a row must not imply either.
+    // "Queued" and "next check in 6 hours" are both promises nothing is
+    // in a position to keep.
+    if (!canDownload) return 'On your list — no download client to search with';
+
     if (request.attempts === 0) return 'Queued — not searched for yet';
 
     const tries = `Searched ${request.attempts} time${request.attempts === 1 ? '' : 's'}`;

frontend/src/components/explore-album-details/explore-album-details.ts

@@ -2,6 +2,8 @@ import { LitElement, html, css, nothing } from 'lit';
 import { customElement, property, state, query } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { designTokens } from '../../styles/tokens.css';
+import { srOnly } from '../../styles/sr-only.css';
+import { unownedLabel, unownedStyles } from '@utils/ownership';
 import {
     LookupReleaseGroup,
     BrowseReleases,
@@ -51,6 +53,12 @@ import { dictByName } from '@utils/binding';
 import type { TrackDetails } from '@components/track-details/track-details.js';
 import { showTrackDetailsForPath } from '@utils/track-details-opener.js';
 import '@components/playlist-picker/playlist-picker.js';
+import {
+    ICON_CAN_REQUEST,
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+    ICON_REQUESTED,
+} from '@utils/icon-language';
 
 /**
  * The region the album header's own failures are rendered in.
@@ -190,8 +198,49 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
     @state() private versionEntries: VersionEntry[] = [];
     /** Currently-selected dropdown entry (by VersionEntry.key). */
     @state() private selectedVersionKey: string = '';
+
+    /**
+     * The key `buildClusters` defaulted to, kept so the page can tell
+     * "this is what we picked for you" from "you went and chose this".
+     *
+     * Only the second needs saying out loud. With the selector demoted
+     * to a disclosure below the tracklist, a chosen version is the one
+     * case where the list on screen is not the one the header
+     * describes, and nothing else on the page would say so.
+     */
+    @state() private defaultVersionKey: string = '';
+
+    /**
+     * Whether the "Other versions" disclosure is open.
+     *
+     * Collapsed by default — choosing which pressing you are looking at
+     * is a metadata-repair task and does not belong above the
+     * tracklist. It is deliberately *not* closed when the selection
+     * changes: the user opened it to change something, and a panel that
+     * shuts on use cannot be used twice.
+     */
+    @state() private versionsOpen = false;
     @state() private coverArtURL = '';
 
+    /**
+     * Whether to draw the whole release rather than only the files on
+     * disk — `null` while nobody has said, which is the automatic rule
+     * (`buildLibraryEntry`: show the release once the tags say the album
+     * is incomplete).
+     *
+     * It is a *tri-state* on purpose. The automatic rule is right when
+     * it fires and the switch has to be able to agree with it, or the
+     * control would start out contradicting the page it is sitting on;
+     * a plain boolean would need its default recomputed every time the
+     * completeness answer changed underneath it.
+     *
+     * The rule alone was not enough, which is the report: it depends on
+     * the files declaring a per-disc total, so a library whose tags
+     * never said sat permanently on "only my tracks" with no way to ask
+     * for the rest — and no way to tell that there was a rest.
+     */
+    @state() private showFullTracklist: boolean | null = null;
+
     /**
      * The local album's own tracks — the authoritative answer to "what
      * is actually on disk," independent of `this.releases`, which
@@ -289,6 +338,8 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         designTokens,
         exploreLinkStyles,
         contextMenuStyles,
+        srOnly,
+        unownedStyles,
         css`
             :host {
                 display: flex;
@@ -494,7 +545,93 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                 flex-shrink: 0;
             }
 
-            /* ── Version selector ── */
+            /* ── Other versions (a disclosure, below the tracklist) ── */
+            .versions {
+                margin-top: 24px;
+                border-top: 1px solid
+                    var(--yj-border-subtle, rgba(255, 255, 255, 0.08));
+                padding-top: 8px;
+            }
+
+            /* The heading exists so the section is reachable by heading
+             * navigation; the button inside it is the control. Its own
+             * type scale is the section header's, reduced — this is a
+             * footnote to the page, not a peer of the tracklist. */
+            .versions-heading {
+                margin: 0;
+                font-size: var(--yj-text-sm);
+                font-weight: 500;
+            }
+
+            .versions-toggle {
+                display: flex;
+                align-items: center;
+                gap: 8px;
+                width: 100%;
+                padding: 8px 2px;
+                background: none;
+                border: none;
+                color: var(--yj-text-secondary, #b3b3b3);
+                font: inherit;
+                text-align: left;
+                cursor: pointer;
+            }
+
+            .versions-toggle:hover {
+                color: var(--yj-text-primary, #fff);
+            }
+
+            .versions-toggle:focus-visible {
+                outline: 2px solid var(--yj-accent-text, #ffd43b);
+                outline-offset: 2px;
+                border-radius: 4px;
+            }
+
+            .versions-toggle wa-icon {
+                font-size: var(--yj-icon-xs, 11px);
+                transition: transform 0.2s ease;
+            }
+
+            .versions-toggle[aria-expanded='false'] wa-icon {
+                transform: rotate(-90deg);
+            }
+
+            .versions-intro {
+                margin: 0 0 10px;
+                font-size: var(--yj-text-xs);
+                color: var(--yj-text-tertiary, #888);
+                line-height: 1.4;
+            }
+
+            /* A line above the tracklist, and only after a deliberate
+             * choice — see renderChosenVersion. */
+            .chosen-version {
+                margin: 0 0 10px;
+                font-size: var(--yj-text-sm);
+                color: var(--yj-text-secondary, #b3b3b3);
+            }
+
+            .chosen-version strong {
+                color: var(--yj-text-primary, #fff);
+                font-weight: 600;
+            }
+
+            .chosen-version-reset {
+                background: none;
+                border: none;
+                padding: 0;
+                font: inherit;
+                color: var(--yj-accent-text, #ffd43b);
+                text-decoration: underline;
+                cursor: pointer;
+            }
+
+            .chosen-version-reset:focus-visible {
+                outline: 2px solid var(--yj-accent-text, #ffd43b);
+                outline-offset: 2px;
+                border-radius: 2px;
+            }
+
             .version-selector {
                 display: flex;
                 flex-direction: column;
@@ -557,6 +694,19 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
             }
 
             /* ── Tracklist ── */
+            .tracklist-scope {
+                display: flex;
+                align-items: center;
+                flex-wrap: wrap;
+                gap: 6px 12px;
+                margin-bottom: 8px;
+            }
+
+            .tracklist-scope-hint {
+                font-size: var(--yj-text-xs);
+                color: var(--yj-text-tertiary, #888);
+            }
+
             .tracklist {
                 display: flex;
                 flex-direction: column;
@@ -647,49 +797,30 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                 white-space: nowrap;
             }
 
-            /* A track the library does not have, on the pattern a
-             * streaming service uses for something it cannot play: the
-             * row stays, dimmed, so the album reads as the album rather
-             * than as the subset that happens to be here.
-             *
-             * The dimming is a colour, so it cannot be the only signal
-             * — the row also carries aria-disabled, which is what
-             * reaches anyone not seeing it.  Secondary rather than
-             * tertiary because the row's hover background is
-             * bgOverlay, which tertiary does not clear. */
-            .track-row.unowned .track-title {
-                color: var(--yj-text-secondary, #b3b3b3);
-                font-weight: 400;
-            }
+            /* The dimming itself is unownedStyles, from
+             * utils/ownership.ts, imported above.  It was written here
+             * first — this tracklist is where the treatment came from —
+             * and moved out when seven other surfaces had to draw the
+             * same thing, because two of them would otherwise have
+             * ended up drawing it slightly differently.  (No backticks or
+             * apostrophes-as-quotes here: this is inside a tagged
+             * template literal.) */
 
-            /* The request control is only offered where there is
-             * something to request, and only when the row is being
-             * attended to — a column of plus signs down a mostly-owned
-             * album is the clutter the green ticks were.
+            /* The request control is offered on every row that has
+             * something to request, and is not revealed on hover.
              *
-             * Hidden with opacity, never display:none or visibility,
-             * so it keeps its place in the layout (rows do not reflow
-             * as the pointer moves) and stays in the tab order and the
-             * accessibility tree.  focus-within is what makes it
-             * reachable without a mouse: tabbing to the button reveals
-             * it, and the row's own focus reveals it before you get
-             * there. */
+             * It used to be transparent until the row was hovered or
+             * focused, on the reasoning that a column of plus signs
+             * down a mostly-owned album is clutter. That reasoning was
+             * inherited from the green ticks it replaced and does not
+             * survive the rule those were removed for: a tick marked
+             * the *common* case, while this marks the rows that are
+             * **not** here. A mark on the exception is the information
+             * on this page — and one that appears only under the
+             * pointer cannot be seen, counted, or reached by anyone
+             * driving this with a finger. */
             .track-row .track-request {
                 flex-shrink: 0;
-                opacity: 0;
-                transition: opacity 0.12s ease;
-            }
-
-            .track-row:hover .track-request,
-            .track-row:focus-within .track-request,
-            .track-row .track-request:focus-visible {
-                opacity: 1;
-            }
-
-            @media (prefers-reduced-motion: reduce) {
-                .track-row .track-request {
-                    transition: none;
-                }
             }
         `,
     ];
@@ -720,14 +851,28 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
 
         // The download button only appears once a client is connected,
         // so this tracks the provider list rather than assuming.
+        //
+        // The `requestUpdate` is what makes the *tracklist's* badges
+        // move.  Both assignments below are reactive fields, so Lit
+        // repaints when either changes — but a track request changes
+        // neither: `canDownload` is about providers and `isRequested`
+        // is about this album's own release group.  Each row's badge
+        // reads `libraryStatusFor(false, track.mbid)` at render time,
+        // which is a dependency on the store that Lit cannot see, so
+        // clicking one filed the request and left the plus exactly
+        // where it was.  The other three hosts rendering these badges
+        // (`explore-artist-details`, `explore-view`, `top-results-row`)
+        // have always asked for the repaint here; this one did not.
         this.downloadUnsub = downloadStore.subscribe(() => {
             this.canDownload = downloadStore.available;
             this.syncRequested();
+            this.requestUpdate();
         });
 
         void downloadStore.init().then(() => {
             this.canDownload = downloadStore.available;
             this.syncRequested();
+            this.requestUpdate();
         });
 
         void this.resolveTargetLibraryId();
@@ -911,6 +1056,9 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         this.releases = [];
         this.versionEntries = [];
         this.selectedVersionKey = '';
+        this.defaultVersionKey = '';
+        this.versionsOpen = false;
+        this.showFullTracklist = null;
         this.localTracks = [];
         this.filePaths = new Map();
         this.askedFor = new Set();
@@ -1601,6 +1749,14 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
             || standardEntry?.key
             || this.versionEntries[0]?.key
             || '';
+
+        // Recorded here rather than derived later: this is the one
+        // place that knows what "the version we picked" means, and
+        // recomputing the preference order at the render site would be
+        // a second copy of it.  `handleTracklistScopeChange` rebuilds
+        // through here too, so the switch does not read as a choice of
+        // version.
+        this.defaultVersionKey = this.selectedVersionKey;
     }
 
     /**
@@ -1814,17 +1970,23 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
             // Guarded on `known` rather than on "fewer tracks than the
             // cluster", which would swap in a catalog tracklist for
             // every album whose tags simply never declared a total.
+            //
+            // And guarded on the *user's* answer first, because the
+            // automatic rule can only fire where the tags declared a
+            // total: an album that says nothing is not an album that is
+            // complete, and it used to be shown as one.
             const answer = this.completenessAnswer();
-            const incomplete = answer?.known && !answer.complete;
 
-            if (incomplete) {
-                const fullRelease = this.findLibraryCluster(clusters);
+            if (this.showFullTracklist ?? (answer?.known && !answer.complete)) {
+                const fullRelease = this.fullReleaseCluster(clusters);
 
                 if (fullRelease) {
                     return {
                         key: 'synthetic:library',
                         label: 'Your Library',
-                        sublabel: `${answer?.owned ?? 0} of ${answer?.expected ?? 0} tracks · ${this.clusterLabel(fullRelease)}`,
+                        sublabel: answer?.known
+                            ? `${answer.owned} of ${answer.expected} tracks · ${this.clusterLabel(fullRelease)}`
+                            : `${this.clusterLabel(fullRelease)} · full tracklist`,
                         group: 'aggregate',
                         syntheticKind: 'library',
                         tracks: fullRelease.representative.tracks ?? [],
@@ -1858,6 +2020,25 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         };
     }
 
+    /**
+     * The release to draw when the whole album is wanted rather than
+     * the files on disk.
+     *
+     * `findLibraryCluster` is the right answer where it has one — the
+     * release the user's tracks overlap most — but it is a guess over
+     * the `inLibrary` flags and returns nothing at all when none of
+     * them are set, which is every untagged library. Falling back to
+     * the highest-scoring cluster is what makes the switch work there;
+     * that is the same release the page would call "Standard", and the
+     * sublabel names it either way rather than leaving the user to
+     * wonder whose tracklist they are reading.
+     */
+    private fullReleaseCluster(
+        clusters: ReleaseCluster[],
+    ): ReleaseCluster | undefined {
+        return this.findLibraryCluster(clusters) ?? clusters[0];
+    }
+
     /**
      * Fallback only: used when there's no local album to anchor on
      * (see `buildLibraryEntry`). Finds the cluster with the highest
@@ -2234,8 +2415,10 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                     entity-type="album"
                     @catalog-retry=${this.retryCatalog}
                 ></catalog-scope-notice>
-                ${this.renderVersionSelector()}
+                ${this.renderChosenVersion()}
+                ${this.renderTracklistScope()}
                 ${this.renderTracklist()}
+                ${this.renderVersionSelector()}
             </div>
             <track-details></track-details>
         `;
@@ -2375,7 +2558,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                     data-testid="album-queue"
                     @click=${() => this.queueOwned()}
                 >
-                    <wa-icon slot="start" name="list"></wa-icon>
+                    <wa-icon slot="start" name=${ICON_QUEUE}></wa-icon>
                     Add to queue
                 </wa-button>
                 ${partial
@@ -2678,7 +2861,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                      of the same Free glyph carry the toggle instead. -->
                 <wa-icon
                     slot="start"
-                    name=${this.isRequested ? 'solid/bookmark' : 'regular/bookmark'}
+                    name=${this.isRequested ? ICON_REQUESTED : ICON_CAN_REQUEST}
                 ></wa-icon>
                 ${this.isRequested ? 'Requested' : 'Request this'}
             </wa-button>
@@ -2886,26 +3069,81 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
 
     /* ── Version Selector (R025, R026, R027) ── */
 
+    /**
+     * Which pressing is on screen — said only when the user chose it.
+     *
+     * The selector is a disclosure below the tracklist now, so nothing
+     * above the list names the version it came from. That is right for
+     * the default, which is what the header already describes; it is
+     * wrong the moment someone picks a different one, because then the
+     * tracklist and the page disagree and the control that explains it
+     * is off the bottom of the screen.
+     *
+     * `defaultVersionKey` is the whole test. A quiet line that appears
+     * on every album would be the thing this issue removed, one size
+     * smaller.
+     */
+    private renderChosenVersion() {
+        if (this.loadingReleases || this.errorReleases) return nothing;
+        if (!this.selectedVersionKey) return nothing;
+        if (this.selectedVersionKey === this.defaultVersionKey) return nothing;
+
+        const current = this.currentVersion();
+
+        if (!current) return nothing;
+
+        return html`
+            <p class="chosen-version">
+                Showing <strong>${current.label}</strong> —
+                ${current.sublabel}.
+                <button
+                    type="button"
+                    class="chosen-version-reset"
+                    @click=${this.resetVersion}
+                >
+                    Use the default version
+                </button>
+            </p>
+        `;
+    }
+
+    /** Back to what `buildClusters` picked, without opening the panel. */
+    private resetVersion = () => {
+        if (!this.defaultVersionKey) return;
+
+        this.selectedVersionKey = this.defaultVersionKey;
+    };
+
+    /**
+     * "Other versions" — a disclosure, below the tracklist.
+     *
+     * Choosing which pressing you are looking at is an advanced,
+     * metadata-repair task, and it used to sit directly above the
+     * tracklist with a heading and a paragraph of prose explaining our
+     * clustering heuristic. It is not removed — matching the wrong
+     * release is a real problem and this is how it gets fixed — it is
+     * demoted (#17).
+     *
+     * Two things about the shape are load-bearing, and both are
+     * `config-section`'s rules rather than new ones. The header is a
+     * real `<button aria-expanded aria-controls>` inside the heading
+     * that names the section, so it is reachable by Tab and by heading
+     * navigation alike. And the body **renders unconditionally and is
+     * toggled with `hidden`**, because `aria-controls` has to name an
+     * element that is in the DOM.
+     *
+     * The loading and error states this used to own are gone rather
+     * than moved. Both were unguarded, so they took the primary slot on
+     * every album regardless of whether there was ever going to be a
+     * choice: the spinner said the same thing `renderTracklist` was
+     * already saying about the same fetch, and the error is the one
+     * `catalog-scope-notice` shows at the top of the page with a retry
+     * — every path that sets `errorReleases` also sets `catalogFailed`,
+     * which is the only route to `unavailable`. What the tracklist does
+     * with a failure is now the tracklist's own business.
+     */
     private renderVersionSelector() {
-        if (this.loadingReleases) {
-            return html`
-                <section>
-                    <h3 class="section-header">Versions</h3>
-                    <div class="section-loading">Loading releases\u2026</div>
-                </section>
-            `;
-        }
-        if (this.errorReleases) {
-            return html`
-                <section>
-                    <h3 class="section-header">Versions</h3>
-                    <div class="section-error">
-                        <wa-icon name="triangle-exclamation"></wa-icon>
-                        ${this.errorReleases}
-                    </div>
-                </section>
-            `;
-        }
+        if (this.loadingReleases || this.errorReleases) return nothing;
 
         // A dropdown is only a choice if the choices differ. Counting
         // *entries* is the wrong test: a release group routinely has
@@ -2916,7 +3154,9 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         //
         // Distinct *tracklists* is the real question, and it is already
         // computed: clusters are keyed by tracklist fingerprint.
-        if (this.distinctTracklistCount() <= 1) return nothing;
+        const choices = this.distinctTracklistCount();
+
+        if (choices <= 1) return nothing;
 
         const aggregateEntries = this.versionEntries.filter(
             (e) => e.group === 'aggregate',
@@ -2926,35 +3166,59 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         );
 
         return html`
-            <div class="version-selector">
-                <div class="version-selector-row">
-                    <label for="version-select">Version</label>
-                    <select
-                        id="version-select"
-                        @change=${this.handleVersionChange}
-                        aria-label="Select release version"
+            <section class="versions">
+                <h3 class="versions-heading">
+                    <button
+                        type="button"
+                        class="versions-toggle"
+                        aria-expanded=${this.versionsOpen ? 'true' : 'false'}
+                        aria-controls="versions-body"
+                        @click=${this.toggleVersions}
                     >
-                        ${aggregateEntries.length > 0
-                            ? html`
-                                  <optgroup label="Aggregate">
-                                      ${aggregateEntries.map((e) =>
-                                          this.renderVersionOption(e),
-                                      )}
-                                  </optgroup>
-                              `
-                            : nothing}
-                        <optgroup label="Versions">
-                            ${clusterEntries.map((e) =>
-                                this.renderVersionOption(e),
-                            )}
-                        </optgroup>
-                    </select>
+                        <wa-icon name="chevron-down" aria-hidden="true"></wa-icon>
+                        Other versions of this album (${choices})
+                    </button>
+                </h3>
+                <div id="versions-body" ?hidden=${!this.versionsOpen}>
+                    <p class="versions-intro">
+                        A release group can have several pressings with
+                        different tracklists. Pick another if the one
+                        above does not match your copy.
+                    </p>
+                    <div class="version-selector">
+                        <div class="version-selector-row">
+                            <label for="version-select">Version</label>
+                            <select
+                                id="version-select"
+                                @change=${this.handleVersionChange}
+                            >
+                                ${aggregateEntries.length > 0
+                                    ? html`
+                                          <optgroup label="Aggregate">
+                                              ${aggregateEntries.map((e) =>
+                                                  this.renderVersionOption(e),
+                                              )}
+                                          </optgroup>
+                                      `
+                                    : nothing}
+                                <optgroup label="Versions">
+                                    ${clusterEntries.map((e) =>
+                                        this.renderVersionOption(e),
+                                    )}
+                                </optgroup>
+                            </select>
+                        </div>
+                        ${this.renderVersionMeta()}
+                    </div>
                 </div>
-                ${this.renderVersionMeta()}
-            </div>
+            </section>
         `;
     }
 
+    private toggleVersions = () => {
+        this.versionsOpen = !this.versionsOpen;
+    };
+
     /**
      * One option in the version list.
      *
@@ -3033,24 +3297,127 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
 
     /* ── Tracklist ── */
 
+    /**
+     * "Show the whole album" — the switch between the files on disk and
+     * the release they are part of.
+     *
+     * The page could already draw the full release with the missing
+     * rows dimmed, and did so automatically once the tags said the
+     * album was incomplete. What it could not do was be *asked*: where
+     * the files declare no per-disc total and the catalog has none
+     * either, the rule never fires, so a partly-owned album showed only
+     * the tracks the user had and nothing said the rest existed.
+     *
+     * Three things about when it appears, all of them the same rule —
+     * a control that cannot change what is on screen is worse than no
+     * control, which is what the version dropdown's own guard is for:
+     *
+     * - Only against the synthetic "Your Library" entry. Every other
+     *   entry *is* a catalog tracklist already.
+     * - Only when a catalog release exists to switch to.
+     * - Only when the two differ. A complete album's release has the
+     *   same rows as its files, so the switch would redraw the same
+     *   list and read as broken.
+     */
+    private renderTracklistScope() {
+        const current = this.currentVersion();
+
+        if (current?.syntheticKind !== 'library') return nothing;
+        if (this.localTracks.length === 0) return nothing;
+
+        const full = this.fullReleaseCluster(this.clustersOf(this.versionEntries));
+        const fullCount = full?.representative.tracks?.length ?? 0;
+
+        if (fullCount === 0 || fullCount <= this.localTracks.length) {
+            return nothing;
+        }
+
+        const showing = current.tracks.length > this.localTracks.length;
+
+        return html`
+            <div class="tracklist-scope">
+                <wa-switch
+                    size="small"
+                    ?checked=${showing}
+                    @change=${this.handleTracklistScopeChange}
+                >
+                    Show the whole album
+                </wa-switch>
+                <span class="tracklist-scope-hint">
+                    ${showing
+                        ? `${this.localTracks.length} of ${fullCount} tracks are in your library`
+                        : `${fullCount - this.localTracks.length} more tracks are on this release`}
+                </span>
+            </div>
+        `;
+    }
+
+    /**
+     * The clusters behind the current entries.
+     *
+     * `buildClusters` computes them and keeps only the entries, so this
+     * recovers them rather than storing the array twice — two copies of
+     * a list rebuilt on four different events is how they come to
+     * disagree.
+     */
+    private clustersOf(entries: VersionEntry[]): ReleaseCluster[] {
+        return entries
+            .filter((e) => e.group === 'cluster')
+            .map((e) => e.cluster)
+            .filter((c): c is ReleaseCluster => !!c);
+    }
+
+    private handleTracklistScopeChange = (e: Event) => {
+        this.showFullTracklist = (e.target as HTMLInputElement).checked;
+
+        // The entries are derived, so the switch rebuilds them rather
+        // than patching the one it changed. `buildClusters` re-defaults
+        // the selection, which lands back on "Your Library" — the only
+        // entry this control is ever shown against.
+        this.buildClusters();
+    };
+
+    /**
+     * The heading is there and is not drawn.
+     *
+     * A list of numbered titles with durations under an album's cover
+     * does not need a word above it saying what it is — it was the
+     * only thing on this page labelling something already obvious. But
+     * the section is a landmark and the page's heading structure runs
+     * through it, so what goes is the *ink*, not the element: a reader
+     * jumping by heading still finds the tracklist.
+     */
     private renderTracklist() {
         if (this.loadingReleases) {
             return html`
                 <section>
-                    <h3 class="section-header">Tracklist</h3>
+                    <h3 class="sr-only">Tracklist</h3>
                     <div class="section-loading">Loading tracks\u2026</div>
                 </section>
             `;
         }
         if (this.errorReleases) {
-            // Error already shown in version selector section
-            return nothing;
+            // The failure belongs to the list that is missing because
+            // of it. This used to return `nothing` and lean on the
+            // version selector's own error block to have said it, which
+            // is precisely the coupling that made demoting the selector
+            // a rewrite rather than a move: a control in a collapsed
+            // disclosure cannot be the page's error surface.
+            return html`
+                <section>
+                    <h3 class="sr-only">Tracklist</h3>
+                    <div class="section-error">
+                        <wa-icon name="triangle-exclamation"></wa-icon>
+                        ${this.errorReleases}
+                    </div>
+                </section>
+            `;
         }
         const current = this.currentVersion();
         if (!current) {
             return html`
                 <section>
-                    <h3 class="section-header">Tracklist</h3>
+                    <h3 class="sr-only">Tracklist</h3>
                     <div class="section-error">
                         <wa-icon name="triangle-exclamation"></wa-icon>
                         No release data available.
@@ -3063,7 +3430,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         if (tracks.length === 0) {
             return html`
                 <section>
-                    <h3 class="section-header">Tracklist</h3>
+                    <h3 class="sr-only">Tracklist</h3>
                     <div
                         style="color: var(--yj-text-tertiary, #888); font-size: var(--yj-text-md)"
                     >
@@ -3079,7 +3446,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
 
         return html`
             <section>
-                <h3 class="section-header">Tracklist</h3>
+                <h3 class="sr-only">Tracklist</h3>
                 <div class="tracklist">
                     ${discNumbers.map((discNum) => {
                         const discTracks = discMap.get(discNum) ?? [];
@@ -3115,7 +3482,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                                         aria-disabled=${owned ? 'false' : 'true'}
                                         aria-label=${owned
                                             ? `Play “${track.title}”`
-                                            : `${track.title} — not in your library`}
+                                            : unownedLabel(track.title, 'track')}
                                         @dblclick=${() => this.onTrackRowDblClick(track)}
                                         @contextmenu=${(e: MouseEvent) => this.onTrackContextMenu(e, track)}
                                         @keydown=${(e: KeyboardEvent) => this.onTrackRowKeydown(e, track)}
@@ -3186,7 +3553,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                                             @click=${() => this.onContextMenuAction('add-to-queue')}
                                             @mouseenter=${() => this.ctxMenu.closePlaylistSubmenu()}
                                         >
-                                            <wa-icon slot="icon" name="plus"></wa-icon>
+                                            <wa-icon slot="icon" name=${ICON_QUEUE}></wa-icon>
                                             Add to Queue
                                         </wa-dropdown-item>
                                         <wa-dropdown-item
@@ -3205,7 +3572,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                                                 this.openPlaylistSubmenu();
                                             }}
                                         >
-                                            <wa-icon slot="icon" name="plus"></wa-icon>
+                                            <wa-icon slot="icon" name=${ICON_PLAYLIST}></wa-icon>
                                             Add to Playlist
                                             <span class="submenu-arrow">&#9654;</span>
                                         </wa-dropdown-item>

frontend/src/components/explore-artist-details/explore-artist-details.ts

@@ -39,7 +39,17 @@ import { EventsOn } from '@runtime/runtime';
 import { Events } from '../../events';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '../library-status-indicator/library-status-indicator.js';
-import { libraryStatusFor, toggleRequest } from '@utils/library-status';
+import {
+    albumBadgeFor,
+    libraryStatusFor,
+    toggleRequest,
+} from '@utils/library-status';
+import {
+    isOwned,
+    ownershipLabel,
+    unownedStyles,
+} from '@utils/ownership';
+import { completenessStore } from '@store/completeness-store';
 import '../catalog-scope-notice/catalog-scope-notice.js';
 import type { CatalogScope } from '../catalog-scope-notice/catalog-scope-notice.js';
 import { queueStore } from '../../store/queue-store';
@@ -59,6 +69,12 @@ import { dict, dictByName } from '@utils/binding';
 import type { TrackDetails } from '@components/track-details/track-details.js';
 import { showTrackDetailsForPath } from '@utils/track-details-opener.js';
 import '@components/playlist-picker/playlist-picker.js';
+import {
+    ICON_CAN_REQUEST,
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+    ICON_REQUESTED,
+} from '@utils/icon-language';
 
 /* ── Constants ── */
 
@@ -172,7 +188,6 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
     @state() private discoRowSize = 5;
     private discoObserver?: ResizeObserver;
     @state() private similarExpanded = false;
-    private libraryMBIDs = new Set<string>();
 
     /* ── Release prefetch ── */
 
@@ -251,6 +266,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
         designTokens,
         exploreLinkStyles,
         contextMenuStyles,
+        unownedStyles,
         css`
             :host {
                 display: flex;
@@ -989,6 +1005,9 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
     /** Unsubscribe handle for the requests list. */
     private unsubRequests: (() => void) | null = null;
 
+    /** Unsubscribes the "how much of this album is here" repaint. */
+    private unsubCompleteness: (() => void) | null = null;
+
     override connectedCallback() {
         super.connectedCallback();
         if (this.artistMBID || this.localArtistId) {
@@ -1001,6 +1020,12 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
         this.unsubRequests = downloadStore.subscribe(() => this.requestUpdate());
         void downloadStore.init().then(() => this.requestUpdate());
 
+        // The count behind a partly-held album lands a frame after the
+        // cards do, since the store batches a screenful into one query.
+        this.unsubCompleteness = completenessStore.subscribe(() =>
+            this.requestUpdate(),
+        );
+
         // A background discography fetch (top tracks / top releases for an
         // artist that wasn't indexed yet) finished — re-fetch those two
         // sections, once per artist, so they fill in without the initial
@@ -1039,6 +1064,8 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
         super.disconnectedCallback();
         this.unsubRequests?.();
         this.unsubRequests = null;
+        this.unsubCompleteness?.();
+        this.unsubCompleteness = null;
         this.unsubDiscogReady?.();
         this.unsubSimilarReady?.();
         if (this.discogFallbackTimer) clearTimeout(this.discogFallbackTimer);
@@ -1567,10 +1594,6 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                 this.catalogPending = false;
             }
 
-            // Populate libraryMBIDs from the inLibrary flag (already
-            // set by the backend via local_release_group_id cross-ref).
-            this.checkLibrary();
-
             // Batch-resolve cover art for discography (lower priority — loaded after top sections).
             void this.batchResolveThumbnails(
                 rgs?.map((r) => ({ mbid: r.mbid, albumName: r.title, artistName: r.artistCredit }))
@@ -1897,23 +1920,6 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
         }
     }
 
-    private checkLibrary() {
-        // Backend now populates `inLibrary` directly on each MBReleaseGroup
-        // via the local_release_group_id cross-reference column.  Just read it.
-        let updated = false;
-
-        for (const rg of this.releaseGroups) {
-            if (rg.mbid && rg.inLibrary && !this.libraryMBIDs.has(rg.mbid)) {
-                this.libraryMBIDs.add(rg.mbid);
-                updated = true;
-            }
-        }
-
-        if (updated) {
-            this.requestUpdate();
-        }
-    }
-
     /* ── Playback ── */
 
     /**
@@ -2009,11 +2015,14 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
 
     /**
      * File path for one top track, resolved by recording MBID — the
-     * same key `inLibrary`/`localId` were set from. Works whether or
-     * not the containing release itself matched a local album.
+     * same key `localId` was set from. Works whether or not the
+     * containing release itself matched a local album.
+     *
+     * Gated on the same answer the row is drawn from, or a row drawn
+     * dimmed and `aria-disabled` would still try to play and fail.
      */
     private async trackFilePath(track: LBTopRecording): Promise<string | null> {
-        if (!(track.inLibrary || track.localId) || !track.recordingMbid) return null;
+        if (!isOwned(track) || !track.recordingMbid) return null;
 
         const libraryID = libraryStore.getSelectedLibraryId() ?? 0;
         const byMBID = await dictByName(
@@ -2057,7 +2066,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
     }
 
     private isTrackOwned(track: LBTopRecording): boolean {
-        return Boolean(track.inLibrary || track.localId);
+        return isOwned(track);
     }
 
     private onTrackRowDblClick(track: LBTopRecording): void {
@@ -2100,7 +2109,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
             mbid: rg.releaseGroupMbid || '',
             localId: rg.localId ?? 0,
             title: rg.title,
-            owned: Boolean(rg.inLibrary || rg.localId),
+            owned: isOwned(rg),
         };
     }
 
@@ -2120,10 +2129,12 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
             mbid: isLocal ? '' : rg.mbid || '',
             localId: Number.isFinite(localId) ? localId : 0,
             title: rg.title,
-            owned:
-                this.libraryMBIDs.has(rg.mbid) ||
-                Boolean(rg.inLibrary) ||
-                localId > 0,
+            // The same answer the menu gates Play on, which is the
+            // point: this used to be `inLibrary` too, so a card could
+            // report itself owned, be offered no Play (that item is
+            // gated on the local id) and be offered no request either
+            // (that one is gated on *not* owned).
+            owned: localId > 0,
         };
     }
 
@@ -2674,7 +2685,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                           @click=${() => this.onContextMenuAction('add-to-queue')}
                           @mouseenter=${() => this.ctxMenu.closePlaylistSubmenu()}
                       >
-                          <wa-icon slot="icon" name="plus"></wa-icon>
+                          <wa-icon slot="icon" name=${ICON_QUEUE}></wa-icon>
                           Add to Queue
                       </wa-dropdown-item>
                       <wa-dropdown-item
@@ -2693,7 +2704,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                               void this.openPlaylistSubmenu(true);
                           }}
                       >
-                          <wa-icon slot="icon" name="plus"></wa-icon>
+                          <wa-icon slot="icon" name=${ICON_PLAYLIST}></wa-icon>
                           Add to Playlist
                           <span class="submenu-arrow">&#9654;</span>
                       </wa-dropdown-item>
@@ -2737,7 +2748,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                           Play
                       </wa-dropdown-item>
                       <wa-dropdown-item @click=${() => void this.onReleaseAction('add-to-queue')}>
-                          <wa-icon slot="icon" name="plus"></wa-icon>
+                          <wa-icon slot="icon" name=${ICON_QUEUE}></wa-icon>
                           Add to Queue
                       </wa-dropdown-item>
                       <wa-dropdown-item @click=${() => void this.onReleaseAction('play-next')}>
@@ -2751,7 +2762,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                       <wa-dropdown-item @click=${() => void this.onReleaseRequestToggle()}>
                           <wa-icon
                               slot="icon"
-                              name=${requested ? 'xmark' : 'bookmark'}
+                              name=${requested ? ICON_REQUESTED : ICON_CAN_REQUEST}
                           ></wa-icon>
                           ${requested ? 'Cancel Request' : 'Request This'}
                       </wa-dropdown-item>
@@ -2789,9 +2800,15 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                     appearance=${request ? 'filled' : 'outlined'}
                     @click=${() => void this.toggleFollow(request?.id)}
                 >
+                    <!-- This was bookmark-check, which is not in
+                         names.txt and so has rendered the missing-icon
+                         fallback — a circled question mark — on every
+                         followed artist since it was written. A
+                         backtick around that name would end this
+                         template literal, which is why there is none. -->
                     <wa-icon
                         slot="start"
-                        name=${request ? 'bookmark-check' : 'bookmark'}
+                        name=${request ? ICON_REQUESTED : ICON_CAN_REQUEST}
                     ></wa-icon>
                     ${request ? 'Following' : 'Follow for new releases'}
                 </wa-button>
@@ -2932,15 +2949,20 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                                 <div class="top-section-col top-section-col-tracks">
                                     <h3 class="section-header">Top Tracks</h3>
                                     <div class="track-list">
-                                        ${tracks.map(
-                                            (t, i) => html`
+                                        ${tracks.map((t, i) => {
+                                            const owned = this.isTrackOwned(t);
+
+                                            return html`
                                                 <div
-                                                    class=${classMap({ 'track-item': true, owned: this.isTrackOwned(t) })}
+                                                    class=${classMap({
+                                                        'track-item': true,
+                                                        owned,
+                                                        unowned: !owned,
+                                                    })}
                                                     tabindex="0"
                                                     role="button"
-                                                    aria-label=${this.isTrackOwned(t)
-                                                        ? `Play “${t.trackName}”`
-                                                        : `${t.trackName} — not in your library`}
+                                                    aria-disabled=${owned ? 'false' : 'true'}
+                                                    aria-label=${ownershipLabel(owned, 'Play', t.trackName, 'track')}
                                                     @dblclick=${() => this.onTrackRowDblClick(t)}
                                                     @contextmenu=${(e: MouseEvent) => this.onTrackContextMenu(e, t)}
                                                     @keydown=${(e: KeyboardEvent) => this.onTrackRowKeydown(e, t)}
@@ -2965,16 +2987,18 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                                                     <span class="track-listens">
                                                         ${formatListenCount(t.totalListenCount)} plays
                                                     </span>
-                                                    <library-status-indicator
-                                                        status=${libraryStatusFor(Boolean(t.inLibrary || t.localId), t.recordingMbid)}
-                                                        entity-type="track"
-                                                        label=${t.trackName}
-                                                        request-mbid=${t.recordingMbid}
-                                                        request-artist=${t.artistName ?? ''}
-                                                    ></library-status-indicator>
+                                                    ${owned
+                                                        ? nothing
+                                                        : html`<library-status-indicator
+                                                              status=${libraryStatusFor(false, t.recordingMbid)}
+                                                              entity-type="track"
+                                                              label=${t.trackName}
+                                                              request-mbid=${t.recordingMbid}
+                                                              request-artist=${t.artistName ?? ''}
+                                                          ></library-status-indicator>`}
                                                 </div>
-                                            `,
-                                        )}
+                                            `;
+                                        })}
                                     </div>
                                     ${canExpandTracks
                                         ? html`
@@ -3045,10 +3069,16 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
     private renderTopReleaseCard(rg: LBTopReleaseGroup) {
         const artURL = this.thumbnailURLs.get(rg.releaseGroupMbid) || '';
         const target = this.topReleaseTarget(rg);
+        const owned = target.owned;
+        const badge = albumBadgeFor(
+            { localId: target.localId },
+            rg.releaseGroupMbid,
+        );
 
         return html`
             <div
-                class="top-release-card"
+                class=${classMap({ 'top-release-card': true, unowned: !owned })}
+                aria-label=${ownershipLabel(owned, 'Album', rg.title, 'album')}
                 @click=${() => this.navigateToTopRelease(rg)}
                 role="button"
                 tabindex="0"
@@ -3080,14 +3110,18 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                         <div class="top-release-meta-text">
                             ${rg.date ? html`<span>${extractYear(rg.date)}</span>` : nothing}
                         </div>
-                        <library-status-indicator
-                            status=${libraryStatusFor(Boolean(rg.inLibrary || rg.localId), rg.releaseGroupMbid)}
-                            entity-type="album"
-                            label=${rg.title}
-                            request-mbid=${rg.releaseGroupMbid}
-                            request-artist=${this.artist?.name ?? ''}
-                            size="18"
-                        ></library-status-indicator>
+                        ${badge.status === 'in-library'
+                            ? nothing
+                            : html`<library-status-indicator
+                                  status=${badge.status}
+                                  owned=${badge.owned}
+                                  expected=${badge.expected}
+                                  entity-type="album"
+                                  label=${rg.title}
+                                  request-mbid=${rg.releaseGroupMbid}
+                                  request-artist=${this.artist?.name ?? ''}
+                                  size="18"
+                              ></library-status-indicator>`}
                     </div>
                 </div>
             </div>
@@ -3177,14 +3211,15 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
     private renderAlbumCard(rg: MBReleaseGroup) {
         const artURL = this.thumbnailURLs.get(rg.mbid) || '';
         const year = extractYear(rg.firstReleaseDate);
-        const inLibrary = this.libraryMBIDs.has(rg.mbid) || Boolean(rg.inLibrary);
-        const status = libraryStatusFor(inLibrary, rg.mbid);
 
         const target = this.albumTarget(rg);
+        const owned = target.owned;
+        const badge = albumBadgeFor({ localId: target.localId }, target.mbid);
 
         return html`
             <div
-                class="album-card"
+                class=${classMap({ 'album-card': true, unowned: !owned })}
+                aria-label=${ownershipLabel(owned, 'Album', rg.title, 'album')}
                 @click=${() => this.navigateToAlbum(rg)}
                 role="button"
                 tabindex="0"
@@ -3213,13 +3248,17 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                     <div class="album-meta-text">
                         ${year ? html`<span>${year}</span>` : nothing}
                     </div>
-                    <library-status-indicator
-                        status=${status}
-                        entity-type="album"
-                        label=${rg.title}
-                        request-mbid=${rg.mbid}
-                        request-artist=${this.artist?.name ?? ''}
-                    ></library-status-indicator>
+                    ${badge.status === 'in-library'
+                        ? nothing
+                        : html`<library-status-indicator
+                              status=${badge.status}
+                              owned=${badge.owned}
+                              expected=${badge.expected}
+                              entity-type="album"
+                              label=${rg.title}
+                              request-mbid=${rg.mbid}
+                              request-artist=${this.artist?.name ?? ''}
+                          ></library-status-indicator>`}
                 </div>
             </div>
         `;

frontend/src/components/explore-view/explore-view.ts

@@ -1,5 +1,11 @@
 import { avatarBackground } from '@utils/avatar-color';
-import { libraryStatusFor } from '@utils/library-status';
+import { albumBadgeFor, libraryStatusFor } from '@utils/library-status';
+import {
+    isOwned,
+    ownershipLabel,
+    unownedStyles,
+} from '@utils/ownership';
+import { completenessStore } from '@store/completeness-store';
 import { downloadStore } from '@store/download-store';
 import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state, query as litQuery } from 'lit/decorators.js';
@@ -36,6 +42,7 @@ import '@awesome.me/webawesome/dist/components/popup/popup.js';
 import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import { dict, dictByName } from '@utils/binding';
+import { ICON_QUEUE } from '@utils/icon-language';
 
 /** The region explore's own action failures (play/queue) are rendered in. */
 export const ExploreRegion = 'explore';
@@ -170,7 +177,6 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
     private searchDebounceTimer?: ReturnType<typeof setTimeout>;
     private thumbnailCache = new LRUMap<string, string>(THUMBNAIL_CACHE_LIMIT);
     private artistImageCache = new LRUMap<string, string>(ARTIST_IMAGE_CACHE_LIMIT);
-    private libraryMBIDs = new Set<string>();
 
     constructor() {
         super();
@@ -225,6 +231,7 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
         srOnly,
         exploreLinkStyles,
         contextMenuStyles,
+        unownedStyles,
         css`
             :host {
                 display: block;
@@ -811,6 +818,13 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
         // Explore should not pay for it.
         this.whileActive(downloadStore.subscribe(() => this.requestUpdate()));
         void downloadStore.init().then(() => this.requestUpdate());
+
+        // How much of an owned album is here arrives a frame after the
+        // cards do — the store coalesces a screenful into one query —
+        // so a card that turns out to be 9 of 12 repaints when the
+        // answer lands rather than showing a plain tick until something
+        // else happens to re-render the grid.
+        this.whileActive(completenessStore.subscribe(() => this.requestUpdate()));
     }
 
     /** A debounced search that lands after the user has left the page is
@@ -1082,7 +1096,6 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                 this.results?.artists ?? [],
                 this.results?.releaseGroups ?? [],
             );
-            this.checkLibrary();
         } catch (err) {
             if (version !== this.searchVersion) return;
 
@@ -1228,8 +1241,11 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
         void this.playAlbum(rg, false);
     }
 
-    private onRecordingRowDblClick(r: { mbid: string; inLibrary: boolean; localId?: number }): void {
-        if (!r.inLibrary && !r.localId) return;
+    // The same answer the row is drawn from. It used to accept
+    // `inLibrary` as well, so a row drawn dimmed and `aria-disabled`
+    // would still try to play and fail with a notification.
+    private onRecordingRowDblClick(r: { mbid: string; localId?: number }): void {
+        if (!isOwned(r)) return;
 
         void this.playRecording(r.mbid);
     }
@@ -1342,7 +1358,7 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                                             Play
                                         </wa-dropdown-item>
                                         <wa-dropdown-item @click=${() => this.onContextMenuAction('add-to-queue')}>
-                                            <wa-icon slot="icon" name="plus"></wa-icon>
+                                            <wa-icon slot="icon" name=${ICON_QUEUE}></wa-icon>
                                             Add to Queue
                                         </wa-dropdown-item>
                                         <wa-dropdown-item @click=${() => this.onContextMenuAction('play-next')}>
@@ -1664,42 +1680,6 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
         }
     }
 
-    /**
-     * Check which result MBIDs exist in the local library.
-     */
-    private checkLibrary() {
-        if (!this.results) return;
-
-        // Backend now populates `inLibrary` directly on each MB result
-        // via the local_*_id cross-reference columns.  Just read those.
-        let updated = false;
-
-        for (const a of this.results.artists ?? []) {
-            if (a.mbid && a.inLibrary && !this.libraryMBIDs.has(a.mbid)) {
-                this.libraryMBIDs.add(a.mbid);
-                updated = true;
-            }
-        }
-
-        for (const rg of this.results.releaseGroups ?? []) {
-            if (rg.mbid && rg.inLibrary && !this.libraryMBIDs.has(rg.mbid)) {
-                this.libraryMBIDs.add(rg.mbid);
-                updated = true;
-            }
-        }
-
-        for (const r of this.results.recordings ?? []) {
-            if (r.mbid && r.inLibrary && !this.libraryMBIDs.has(r.mbid)) {
-                this.libraryMBIDs.add(r.mbid);
-                updated = true;
-            }
-        }
-
-        if (updated) {
-            this.requestUpdate();
-        }
-    }
-
     /* ── Navigation ── */
 
     private navigateToArtist(artist: MBArtist) {
@@ -2106,12 +2086,16 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                     : nothing}
                 <div class="horizontal-row">
                     ${artists.map((a) => {
+                        const owned = isOwned(a);
+                        const name = a.englishName || a.name;
+
                         return html`
                             <div
-                                class="artist-card"
+                                class=${classMap({ 'artist-card': true, unowned: !owned })}
                                 @click=${() => this.navigateToArtist(a)}
                                 role="button"
                                 tabindex="0"
+                                aria-label=${ownershipLabel(owned, 'Artist', name, 'artist')}
                                 @keydown=${(e: KeyboardEvent) => {
                                     if (e.key === 'Enter' || e.key === ' ') {
                                         e.preventDefault();
@@ -2170,11 +2154,17 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                         const artURL = this.thumbnailCache.get(rg.mbid) || '';
                         const year = extractYear(rg.firstReleaseDate);
 
-                        const owned = Boolean(rg.localId);
+                        const owned = isOwned(rg);
+                        const badge = albumBadgeFor(rg, rg.mbid);
 
                         return html`
                             <div
-                                class=${classMap({ 'album-card': true, owned })}
+                                class=${classMap({
+                                    'album-card': true,
+                                    owned,
+                                    unowned: !owned,
+                                })}
+                                aria-label=${ownershipLabel(owned, 'Album', rg.title, 'album')}
                                 @click=${() => this.navigateToAlbum(rg)}
                                 @dblclick=${() => this.onAlbumCardDblClick(rg)}
                                 @contextmenu=${(e: MouseEvent) =>
@@ -2227,13 +2217,17 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                                             : nothing}
                                         ${year ? html`<span>${year}</span>` : nothing}
                                     </div>
-                                    <library-status-indicator
-                                        status=${libraryStatusFor(this.libraryMBIDs.has(rg.mbid) || Boolean(rg.inLibrary), rg.mbid)}
-                                        entity-type="album"
-                                        label=${rg.title}
-                                        request-mbid=${rg.mbid}
-                                        request-artist=${rg.artistCredit ?? ''}
-                                    ></library-status-indicator>
+                                    ${badge.status === 'in-library'
+                                        ? nothing
+                                        : html`<library-status-indicator
+                                              status=${badge.status}
+                                              owned=${badge.owned}
+                                              expected=${badge.expected}
+                                              entity-type="album"
+                                              label=${rg.title}
+                                              request-mbid=${rg.mbid}
+                                              request-artist=${rg.artistCredit ?? ''}
+                                          ></library-status-indicator>`}
                                 </div>
                             </div>
                         `;
@@ -2248,12 +2242,20 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
             <section>
                 <h3 class="section-header">Tracks</h3>
                 <div class="track-list">
-                    ${recordings.map(
-                        (r) => html`
+                    ${recordings.map((r) => {
+                        const owned = isOwned(r);
+
+                        return html`
                             <div
-                                class=${classMap({ 'track-item': true, owned: Boolean(r.inLibrary || r.localId) })}
+                                class=${classMap({
+                                    'track-item': true,
+                                    owned,
+                                    unowned: !owned,
+                                })}
                                 role="button"
                                 tabindex="0"
+                                aria-disabled=${owned ? 'false' : 'true'}
+                                aria-label=${ownershipLabel(owned, 'Play', r.title, 'track')}
                                 @dblclick=${() => this.onRecordingRowDblClick(r)}
                                 @contextmenu=${(e: MouseEvent) =>
                                     this.onExploreContextMenu(e, {
@@ -2290,16 +2292,18 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                                         ? html`<span class="track-duration">${formatDuration(r.length)}</span>`
                                         : nothing}
                                 </div>
-                                <library-status-indicator
-                                    status=${libraryStatusFor(this.libraryMBIDs.has(r.mbid) || Boolean(r.inLibrary), r.mbid)}
-                                    entity-type="track"
-                                    label=${r.title}
-                                    request-mbid=${r.mbid}
-                                    request-artist=${r.artistCredit ?? ''}
-                                ></library-status-indicator>
+                                ${owned
+                                    ? nothing
+                                    : html`<library-status-indicator
+                                          status=${libraryStatusFor(false, r.mbid)}
+                                          entity-type="track"
+                                          label=${r.title}
+                                          request-mbid=${r.mbid}
+                                          request-artist=${r.artistCredit ?? ''}
+                                      ></library-status-indicator>`}
                             </div>
-                        `,
-                    )}
+                        `;
+                    })}
                 </div>
             </section>
         `;

frontend/src/components/genres-view/genres-view.ts

@@ -35,6 +35,10 @@ import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js'
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@components/playlist-picker/playlist-picker.js';
 import { dictByName } from '@utils/binding';
+import {
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 
 /** Pixels to change card width per scroll tick. */
 const ZOOM_STEP = 16;
@@ -1211,7 +1215,7 @@ export class GenresView
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_QUEUE}
                                   ></wa-icon>
                                   Add to Queue
                               </wa-dropdown-item>
@@ -1257,7 +1261,7 @@ export class GenresView
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_PLAYLIST}
                                   ></wa-icon>
                                   Add to Playlist
                                   <span

frontend/src/components/library-status-indicator/library-status-indicator.ts

@@ -4,6 +4,11 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { toggleRequest } from '@utils/library-status';
 import { notificationStore } from '@store/notification-store';
 import { describeError } from '@utils/describe-error';
+import {
+    ICON_CAN_REQUEST,
+    ICON_IN_LIBRARY,
+    ICON_REQUESTED,
+} from '@utils/icon-language';
 
 /**
  * Library status for an entity (artist, album, or track).
@@ -248,18 +253,25 @@ export class LibraryStatusIndicator extends LitElement {
      * hourglass says "wait, this is under way", which overstates what a
      * request is: nothing may be downloading, nothing may ever be found,
      * and the user can leave one sitting on the list indefinitely. A
-     * bookmark says the honest thing — it is on your list — and reads as
-     * the opposite of the plus that put it there, which is what a
-     * toggle's two states have to do.
+     * bookmark says the honest thing — it is on your list.
+     *
+     * The *other* state is the outline of that same bookmark, not a
+     * plus. Two states of one toggle have to read as each other's
+     * opposite, and a plus and a bookmark do not — this badge showed a
+     * plus on the same page as a "Request this" button already using
+     * the outline/solid pair, forty pixels away. That is the fault
+     * `utils/library-status.ts` was written for, one layer down: it
+     * made the two agree on what wanting *means* and left them
+     * disagreeing on what it looks like.
      */
     private iconName(): string {
         switch (this.status) {
             case 'in-library':
-                return 'check';
+                return ICON_IN_LIBRARY;
             case 'queued':
-                return 'bookmark';
+                return ICON_REQUESTED;
             default:
-                return 'plus';
+                return ICON_CAN_REQUEST;
         }
     }
 
@@ -285,9 +297,23 @@ export class LibraryStatusIndicator extends LitElement {
         // row to one and nothing to the other, and "Add … to library"
         // was the old button's promise written into the copy.
         if (this.actionable) {
-            return this.status === 'queued'
-                ? `Cancel the request for ${kind}${name}`
-                : `Request ${kind}${name}`;
+            if (this.status === 'queued') {
+                return `Cancel the request for ${kind}${name}`;
+            }
+
+            // A partly-held album is actionable *and* has a count, and
+            // the count does not survive being named after the action
+            // alone. The `partial` case below says why it matters — a
+            // ring says "some" to a sighted user and nothing to anyone
+            // else — and that argument does not stop applying because
+            // the badge became clickable. This branch used to say only
+            // "Request album X", so the one state the ring exists for
+            // was the one state whose name did not mention it.
+            if (this.status === 'partial') {
+                return `Request the rest of ${kind}${name} — ${this.owned} of ${this.expected} tracks are in your library`;
+            }
+
+            return `Request ${kind}${name}`;
         }
 
         switch (this.status) {

frontend/src/components/now-playing-view/now-playing-view.ts

@@ -14,6 +14,7 @@ import { creditStore } from '@store/credit-store';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { designTokens } from '../../styles/tokens.css';
 import { srOnly } from '../../styles/sr-only.css';
+import { ICON_QUEUE } from '@utils/icon-language';
 
 /**
  * What is playing, at the size a phone has room for (plan 016 B2,
@@ -339,7 +340,7 @@ export class NowPlayingView extends LitElement {
                     aria-label="Show the queue"
                     @click=${this.openQueue}
                 >
-                    <wa-icon name="list"></wa-icon>
+                    <wa-icon name=${ICON_QUEUE}></wa-icon>
                 </button>
             </header>
         `;

frontend/src/components/playlist-details/playlist-details.ts

@@ -70,6 +70,10 @@ import {
 } from '@utils/explore-link';
 import { designTokens } from '../../styles/tokens.css';
 import { list } from '@utils/binding';
+import {
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 
 /** One playlist row: the track and its position in the *playlist*,
  *  which is not its position in the filtered view. */
@@ -1358,7 +1362,7 @@ export class PlaylistDetails
                 </button>
                 <div class="playlist-avatar">
                     <wa-icon
-                        name="list"
+                        name=${ICON_PLAYLIST}
                     ></wa-icon>
                 </div>
                 <div class="playlist-info">
@@ -1665,7 +1669,7 @@ export class PlaylistDetails
                                   >
                                       <wa-icon
                                           slot="icon"
-                                          name="plus"
+                                          name=${ICON_QUEUE}
                                       ></wa-icon>
                                       Add to Queue
                                   </wa-dropdown-item>
@@ -1720,7 +1724,7 @@ export class PlaylistDetails
                                   >
                                       <wa-icon
                                           slot="icon"
-                                          name="plus"
+                                          name=${ICON_PLAYLIST}
                                       ></wa-icon>
                                       Add to Playlist
                                       <span

frontend/src/components/playlist-picker/playlist-picker.ts

@@ -18,6 +18,7 @@ import { notificationStore } from '@store/notification-store';
 import { describeError } from '@utils/describe-error';
 import type { DuplicateTracksDialog } from '@components/duplicate-tracks-dialog/duplicate-tracks-dialog.js';
 import { list } from '@utils/binding';
+import { ICON_NEW } from '@utils/icon-language';
 
 /**
  * A reusable playlist picker that displays existing playlists
@@ -307,7 +308,7 @@ export class PlaylistPicker extends LitElement {
                       `
                     : nothing}
                 <wa-dropdown-item @click=${this.handleShowCreate}>
-                    <wa-icon slot="icon" name="plus"></wa-icon>
+                    <wa-icon slot="icon" name=${ICON_NEW}></wa-icon>
                     New Playlist
                 </wa-dropdown-item>
             </div>

frontend/src/components/playlist-view/playlist-view.ts

@@ -37,6 +37,10 @@ import { ViewLifecycleMixin } from '@utils/view-lifecycle';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import '@components/duplicate-tracks-dialog/duplicate-tracks-dialog.js';
 import type { DuplicateTracksDialog } from '@components/duplicate-tracks-dialog/duplicate-tracks-dialog.js';
+import {
+    ICON_NEW,
+    ICON_PLAYLIST,
+} from '@utils/icon-language';
 
 const SCROLL_DEBOUNCE_MS = 100;
 
@@ -1496,7 +1500,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                         @dragleave=${this.onNewButtonDragLeave}
                         @drop=${this.onNewButtonDrop}
                     >
-                        <wa-icon name="plus"></wa-icon>
+                        <wa-icon name=${ICON_NEW}></wa-icon>
                         New Playlist
                     </button>
                     <button
@@ -1641,10 +1645,10 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                 >
                     <div class="drop-zone-icon">
                         <wa-icon
-                            name="plus"
+                            name=${ICON_NEW}
                         ></wa-icon>
                     </div>
-                    <wa-icon name="list"></wa-icon>
+                    <wa-icon name=${ICON_PLAYLIST}></wa-icon>
                     <p>No playlists yet</p>
                     <p style="font-size: 12px;">
                         Create a playlist or drop
@@ -1666,7 +1670,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                 >
                     <div class="drop-zone-icon">
                         <wa-icon
-                            name="plus"
+                            name=${ICON_NEW}
                         ></wa-icon>
                     </div>
                     <p>
@@ -1701,7 +1705,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                 >
                     <div class="drop-zone-icon">
                         <wa-icon
-                            name="plus"
+                            name=${ICON_NEW}
                         ></wa-icon>
                     </div>
                 </li>

frontend/src/components/queue-panel/queue-panel.ts

@@ -60,6 +60,11 @@ import {
     trackLink,
     exploreLinkStyles,
 } from '@utils/explore-link';
+import {
+    ICON_NEW,
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 /** Above this many tracks, clearing the queue asks first. */
 const CLEAR_CONFIRM_THRESHOLD = 20;
 
@@ -1755,7 +1760,7 @@ export class QueuePanel
                             title="Add queue to playlist"
                         >
                             <wa-icon
-                                name="plus"
+                                name=${ICON_PLAYLIST}
                             ></wa-icon>
                         </button>
                     </div>
@@ -1794,11 +1799,11 @@ export class QueuePanel
                         ? html`<div class="empty-state">
                               <div class="drop-zone-icon">
                                   <wa-icon
-                                      name="plus"
+                                      name=${ICON_NEW}
                                   ></wa-icon>
                               </div>
                               <wa-icon
-                                  name="list"
+                                  name=${ICON_QUEUE}
                               ></wa-icon>
                               <p>Queue is empty</p>
                               <p style="font-size: 12px;">
@@ -1875,7 +1880,7 @@ export class QueuePanel
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_PLAYLIST}
                                   ></wa-icon>
                                   Add to Playlist
                                   <span

frontend/src/components/sidebar/app-sidebar.ts

@@ -4,6 +4,10 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { designTokens } from '../../styles/tokens.css';
 
 import type { DragActiveDetail } from '@utils/drag-controller';
+import {
+    ICON_PLAYLIST,
+    ICON_REQUESTED,
+} from '@utils/icon-language';
 
 type View = 'home' | 'playlists' | 'artists' | 'genres' | 'albums' | 'tracks' | 'explore' | 'downloads' | 'autotag' | 'jobs' | 'settings';
 
@@ -197,13 +201,13 @@ export class AppSidebar extends LitElement {
 
     private navItems: NavItem[] = [
         { id: 'home', label: 'Home', icon: 'house' },
-        { id: 'playlists', label: 'Playlists', icon: 'list' },
+        { id: 'playlists', label: 'Playlists', icon: ICON_PLAYLIST },
         { id: 'artists', label: 'Artists', icon: 'user-group' },
         { id: 'genres', label: 'Genres', icon: 'masks-theater' },
         { id: 'albums', label: 'Albums', icon: 'compact-disc' },
         { id: 'tracks', label: 'Tracks', icon: 'music' },
         { id: 'explore', label: 'Explore', icon: 'globe' },
-        { id: 'downloads', label: 'Downloads', icon: 'bookmark' },
+        { id: 'downloads', label: 'Downloads', icon: ICON_REQUESTED },
         { id: 'autotag', label: 'Autotag', icon: 'tag' },
         { id: 'jobs', label: 'Jobs', icon: 'list-check' },
         { id: 'settings', label: 'Settings', icon: 'gear' },

frontend/src/components/smart-playlist-details/smart-playlist-details.ts

@@ -61,6 +61,10 @@ import {
 import '@components/smart-playlist-editor/smart-playlist-editor.js';
 import { designTokens } from '../../styles/tokens.css';
 import { list } from '@utils/binding';
+import {
+    ICON_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 
 
 /**
@@ -1481,7 +1485,7 @@ export class SmartPlaylistDetails
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_QUEUE}
                                   ></wa-icon>
                                   Add to Queue
                               </wa-dropdown-item>
@@ -1521,7 +1525,7 @@ export class SmartPlaylistDetails
                               >
                                   <wa-icon
                                       slot="icon"
-                                      name="plus"
+                                      name=${ICON_PLAYLIST}
                                   ></wa-icon>
                                   Add to Playlist
                                   <span

frontend/src/components/smart-playlist-editor/smart-playlist-editor.ts

@@ -193,6 +193,10 @@ export class SmartPlaylistEditor extends LitElement {
     // ── Internal state ──────────────────────────────────────────────
 
     @state() private ruleRows: RuleRow[] = [emptyRule()];
+    /** Whether every rule must hold or any one of them. Mirrors the
+     *  backend's `match`; 'all' is the default and the only thing a
+     *  playlist saved before this existed can have meant. */
+    @state() private matchType: 'all' | 'any' = 'all';
     @state() private limit = 0;
     @state() private sortField = 'random';
     @state() private sortDir = '';
@@ -224,6 +228,19 @@ export class SmartPlaylistEditor extends LitElement {
                 flex-shrink: 0;
             }
 
+            .match-row {
+                display: flex;
+                align-items: center;
+                gap: 6px;
+                font-size: var(--yj-text-sm);
+                color: var(--yj-text-secondary, #b3b3b3);
+                flex-wrap: wrap;
+            }
+
+            .match-select {
+                min-width: 72px;
+            }
+
             .rule-row {
                 display: grid;
                 grid-template-columns: 160px 140px 1fr 28px;
@@ -511,6 +528,10 @@ export class SmartPlaylistEditor extends LitElement {
             );
 
             this.ruleRows = rows.length > 0 ? rows : [emptyRule()];
+            // A playlist saved before this field existed has no match
+            // and means "all" — the backend reads an empty match the
+            // same way, so an upgrade cannot widen anyone's playlist.
+            this.matchType = parsed.match === 'any' ? 'any' : 'all';
             this.limit = parsed.limit ?? 0;
             this.sortField = parsed.sort_field || 'random';
             this.sortDir = parsed.sort_dir ?? '';
@@ -551,6 +572,7 @@ export class SmartPlaylistEditor extends LitElement {
 
         return JSON.stringify({
             rules,
+            match: this.matchType,
             limit: this.limit || 0,
             sort_field: this.sortField || '',
             sort_dir: this.sortDir || '',
@@ -630,6 +652,11 @@ export class SmartPlaylistEditor extends LitElement {
         this.onRulesChanged();
     }
 
+    private updateMatchType(value: string) {
+        this.matchType = value === 'any' ? 'any' : 'all';
+        this.onRulesChanged();
+    }
+
     private updateSortField(value: string) {
         this.sortField = value;
         if (!value) this.sortDir = '';
@@ -731,6 +758,7 @@ export class SmartPlaylistEditor extends LitElement {
     override render() {
         return html`
             <div class="rule-rows">
+                ${this.renderMatchType()}
                 ${this.ruleRows.map((row, index) =>
                     this.renderRuleRow(row, index),
                 )}
@@ -743,6 +771,46 @@ export class SmartPlaylistEditor extends LitElement {
         `;
     }
 
+    /**
+     * Whether every rule has to hold, or any one of them.
+     *
+     * It is a sentence with a control in the middle rather than a
+     * labelled field, because the two readings differ by one word and
+     * that word is the whole of the setting — "Match **all** of the
+     * following rules" says what the list below it means in a way a
+     * select labelled "Match" beside a list does not.
+     *
+     * Hidden while there is one rule: with nothing to combine, all and
+     * any are the same query, and a control whose two settings cannot
+     * differ is a question the user has no way to answer wrongly and
+     * no reason to answer at all.
+     */
+    private renderMatchType() {
+        if (this.ruleRows.length < 2) return nothing;
+
+        return html`
+            <div class="match-row">
+                <span>Match</span>
+                <select
+                    class="match-select"
+                    aria-label="Match all or any of the following rules"
+                    @change=${(e: Event) =>
+                        this.updateMatchType(
+                            (e.target as HTMLSelectElement).value,
+                        )}
+                >
+                    <option value="all" ?selected=${this.matchType === 'all'}>
+                        all
+                    </option>
+                    <option value="any" ?selected=${this.matchType === 'any'}>
+                        any
+                    </option>
+                </select>
+                <span>of the following rules</span>
+            </div>
+        `;
+    }
+
     private renderRuleRow(row: RuleRow, index: number) {
         const isBetween = row.operator === 'between';
         const operators = row.field ? getOperatorsForField(row.field) : [];

frontend/src/components/top-results-row/top-results-row.ts

@@ -11,8 +11,16 @@ import '../library-status-indicator/library-status-indicator.js';
 import type { LibraryStatus } from '../library-status-indicator/library-status-indicator.js';
 import { creditLink, exploreLinkStyles } from '../../utils/explore-link';
 import { creditStore } from '@store/credit-store';
-import { libraryStatusFor } from '../../utils/library-status';
+import { albumBadgeFor, libraryStatusFor } from '../../utils/library-status';
+import {
+    isOwned,
+    ownershipLabel,
+    unownedStyles,
+    type OwnableKind,
+} from '../../utils/ownership';
+import { completenessStore } from '../../store/completeness-store';
 import { downloadStore } from '../../store/download-store';
+import { classMap } from 'lit/directives/class-map.js';
 
 /** Format milliseconds as m:ss. */
 function formatDuration(ms: number | undefined): string {
@@ -65,6 +73,9 @@ export class TopResultsRow extends LitElement {
     /** Unsubscribes the credit-arrival repaint. */
     private creditsUnsub?: () => void;
 
+    /** Unsubscribes the "how much of this album is here" repaint. */
+    private unsubCompleteness?: () => void;
+
     override connectedCallback(): void {
         super.connectedCallback();
 
@@ -74,6 +85,9 @@ export class TopResultsRow extends LitElement {
         this.unsubRequests = downloadStore.subscribe(() =>
             this.requestUpdate(),
         );
+        this.unsubCompleteness = completenessStore.subscribe(() =>
+            this.requestUpdate(),
+        );
     }
 
     override disconnectedCallback(): void {
@@ -81,12 +95,15 @@ export class TopResultsRow extends LitElement {
         this.creditsUnsub = undefined;
         this.unsubRequests?.();
         this.unsubRequests = undefined;
+        this.unsubCompleteness?.();
+        this.unsubCompleteness = undefined;
         super.disconnectedCallback();
     }
 
     static override styles = [
         designTokens,
         exploreLinkStyles,
+        unownedStyles,
         css`
             :host {
                 display: block;
@@ -289,23 +306,41 @@ export class TopResultsRow extends LitElement {
               ? r.year || ''
               : formatDuration(r.length) || '';
 
-        const status: LibraryStatus = libraryStatusFor(
-            Boolean(r.inLibrary),
-            r.mbid,
-        );
-        const entityType: 'artist' | 'album' | 'track' =
+        const entityType: OwnableKind =
             r.entityType === 'artist'
                 ? 'artist'
                 : r.entityType === 'release_group'
                   ? 'album'
                   : 'track';
 
+        // Ownership is the local row, not the catalog's flag — see
+        // `utils/ownership.ts`. An album additionally says *how much*
+        // of it is here, which is the one thing a tick cannot.
+        const owned = isOwned(r);
+        const badge =
+            entityType === 'album'
+                ? albumBadgeFor(r, r.mbid)
+                : {
+                      status: libraryStatusFor(owned, r.mbid) as LibraryStatus,
+                      owned: 0,
+                      expected: 0,
+                  };
+
+        // A card navigates whether or not the entity is owned, so it is
+        // not `aria-disabled` the way an unplayable track row is — the
+        // name is what carries the state to anyone not seeing the
+        // dimming.
         return html`
             <div
-                class="card"
+                class=${classMap({ card: true, unowned: !owned })}
                 role="button"
                 tabindex="0"
-                aria-label=${`${badgeLabel(r.entityType)}: ${r.name}`}
+                aria-label=${ownershipLabel(
+                    owned,
+                    `${badgeLabel(r.entityType)}:`,
+                    r.name,
+                    entityType,
+                )}
                 @click=${() => this.handleClick(r)}
                 @keydown=${(e: KeyboardEvent) => {
                     if (e.key !== 'Enter' && e.key !== ' ') return;
@@ -345,10 +380,12 @@ export class TopResultsRow extends LitElement {
                             : nothing}
                     </div>
                 </div>
-                ${isArtist
+                ${isArtist || badge.status === 'in-library'
                     ? nothing
                     : html`<library-status-indicator
-                        status=${status}
+                        status=${badge.status}
+                        owned=${badge.owned}
+                        expected=${badge.expected}
                         entity-type=${entityType}
                         label=${r.name}
                         request-mbid=${r.mbid}

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

@@ -74,6 +74,10 @@ import { tracksByFilePath, tracksForPaths } 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_PLAYLIST,
+    ICON_QUEUE,
+} from '@utils/icon-language';
 
 const COLUMN_STORAGE_KEY = 'track-list-column-widths';
 const SORT_FIELD_KEY = 'track-list-sort-field';
@@ -2342,7 +2346,7 @@ export class TrackList
                   @click=${() => this.onContextMenuAction('add-to-queue')}
                   @mouseenter=${() => this.ctxMenu.closePlaylistSubmenu()}
                 >
-                  <wa-icon slot="icon" name="plus"></wa-icon>
+                  <wa-icon slot="icon" name=${ICON_QUEUE}></wa-icon>
                   Add to Queue
                 </wa-dropdown-item>
                 <wa-dropdown-item
@@ -2364,7 +2368,7 @@ export class TrackList
                         void this.ctxMenu.showPlaylistSubmenu(this.selection.getSelectedKeysOrdered());
                     }}
                 >
-                  <wa-icon slot="icon" name="plus"></wa-icon>
+                  <wa-icon slot="icon" name=${ICON_PLAYLIST}></wa-icon>
                   Add to Playlist
                   <span class="submenu-arrow">&#9654;</span>
                 </wa-dropdown-item>

frontend/src/icons/names.txt

@@ -24,6 +24,7 @@ solid/arrows-rotate
 solid/arrow-up-short-wide
 solid/backward-step
 solid/bars
+solid/bars-staggered
 regular/bookmark
 solid/bookmark
 solid/box-open

frontend/src/store/completeness-store.ts

@@ -0,0 +1,208 @@
+/**
+ * How much of an album is here, keyed by local album id.
+ *
+ * The album page has always been able to say "9 of 12"; a card could
+ * not, so an album held two tracks of ten wore a plain green tick on
+ * every grid in the app — which is the complaint the badge-accuracy
+ * issue was filed about, one surface over. A ring with a count needs a
+ * numerator and a denominator per album, and one `GetAlbumCompleteness`
+ * per card is fifty round trips for a grid of fifty.
+ *
+ * So this is `credit-store` one question over, and for the same three
+ * reasons.
+ *
+ * **The lookup is batched and coalesced across callers.** `request()`
+ * is per-card, cheap and safe to call from a render: it collects into a
+ * pending set and flushes once on the next frame, which turns a
+ * screenful into exactly one `GetAlbumsCompleteness`. A frame rather
+ * than a microtask because the point is to collect every card an update
+ * pass renders, and those do not land inside one microtask checkpoint.
+ *
+ * **Absence is cached as an answer.** An album with no files at all is
+ * omitted by the backend deliberately — "I have none of this" and "I
+ * have no idea" are the third state `known` exists to keep apart — so a
+ * miss stored as a hit would re-ask about it forever. What is cached is
+ * *asked*, and the unknown answer is a first-class value.
+ *
+ * **It is invalidated rather than aged.** Completeness is a fact about
+ * files on disk, and the two events that change it — a scan finishing
+ * and tags being rewritten — are exactly the ones `library-store`
+ * already discards everything on. `TracksRemovedFromLibrary` is the
+ * third: it changes a numerator without a rescan.
+ */
+
+import { GetAlbumsCompleteness } from '@go/library/library.js';
+import type * as library from '@go/library/models.js';
+import { EventsOn } from '@runtime/runtime';
+import { Events } from '../events';
+import { LRUMap } from '../utils/lru-map';
+import { compact } from '../utils/binding';
+import { registerCacheProbe } from '../utils/cache-stats';
+
+/**
+ * Entries retained. Four small numbers each, so the bound is about
+ * unbounded growth rather than bytes — and it is set well above any one
+ * grid, since a cap below the visible count evicts cards that are still
+ * on screen and the re-render fetches them straight back.
+ */
+export const COMPLETENESS_CACHE_LIMIT = 20_000;
+
+/** What the app asks of a cached entry. */
+export type Completeness = library.AlbumCompleteness;
+
+/**
+ * The answer for an album nobody has a file of.
+ *
+ * Not a zero-of-zero: `known` false is what every consumer already
+ * reads as "say nothing", and it is the same value the album page's
+ * `completenessAnswer()` treats as unknowable.
+ */
+const NOTHING_HERE: Completeness = {
+    owned: 0,
+    expected: 0,
+    known: false,
+    complete: false,
+} as Completeness;
+
+class CompletenessStore {
+    private cache = new LRUMap<number, Completeness>(COMPLETENESS_CACHE_LIMIT);
+
+    /** Ids with a request in flight, so a re-render does not refetch. */
+    private inFlight = new Set<number>();
+
+    private listeners = new Set<() => void>();
+
+    /** Collected by request(), flushed as one batch on the next frame. */
+    private pending = new Set<number>();
+
+    private flushHandle: number | null = null;
+
+    constructor() {
+        registerCacheProbe('albumCompleteness', () => ({
+            entries: this.cache.size,
+            chars: this.cache.size * 4,
+            limit: COMPLETENESS_CACHE_LIMIT,
+        }));
+
+        EventsOn(Events.LibraryScanComplete, () => this.invalidate());
+        EventsOn(Events.TrackMetadataChanged, () => this.invalidate());
+        EventsOn(Events.TracksRemovedFromLibrary, () => this.invalidate());
+    }
+
+    /**
+     * Subscribe to "some answers arrived".
+     *
+     * Deliberately not per-album, for `credit-store`'s reason: a grid
+     * fetches its cards in one call and re-renders once, so a
+     * fine-grained signal would buy nothing and cost a listener a card.
+     */
+    subscribe(fn: () => void): () => void {
+        this.listeners.add(fn);
+
+        return () => this.listeners.delete(fn);
+    }
+
+    /** The answer for one album, or undefined until it has been asked. */
+    get(albumID: number | undefined | null): Completeness | undefined {
+        if (!albumID || albumID <= 0) return undefined;
+
+        return this.cache.get(albumID);
+    }
+
+    /**
+     * Ask about one album, joining whatever batch is forming.
+     *
+     * Safe from inside a render: a set insert and a scheduled flush,
+     * with anything cached or in flight dropped. It does not loop —
+     * after a flush every id asked for is cached, so the re-render's
+     * requests are all dropped and nothing notifies again.
+     */
+    request(albumID: number | undefined | null): void {
+        if (!albumID || albumID <= 0) return;
+        if (this.cache.has(albumID)) return;
+        if (this.inFlight.has(albumID)) return;
+        if (this.pending.has(albumID)) return;
+
+        this.pending.add(albumID);
+
+        if (this.flushHandle !== null) return;
+
+        this.flushHandle = requestAnimationFrame(() => {
+            this.flushHandle = null;
+
+            const batch = [...this.pending];
+
+            this.pending.clear();
+
+            void this.ensure(batch);
+        });
+    }
+
+    /**
+     * Ask and read in one call, for use inside a template.
+     *
+     * A getter with a side effect, deliberately — `credit-store` makes
+     * the same trade and for the same reason: the alternative is every
+     * call site writing `request(x)` beside `get(x)` and one of them
+     * eventually forgetting, which renders a permanently unknown
+     * completeness that looks exactly like an album with no totals.
+     */
+    completeness(albumID: number | undefined | null): Completeness | undefined {
+        this.request(albumID);
+
+        return this.get(albumID);
+    }
+
+    /** Fetch for a list, skipping anything known or already in flight. */
+    async ensure(albumIDs: readonly number[]): Promise<void> {
+        const wanted = new Set<number>();
+
+        for (const id of albumIDs) {
+            if (!id || id <= 0) continue;
+            // `has` rather than `get`: probing must not mark an entry
+            // recently-used, or scrolling past a card would keep it
+            // alive ahead of one actually being rendered.
+            if (this.cache.has(id)) continue;
+            if (this.inFlight.has(id)) continue;
+
+            wanted.add(id);
+        }
+
+        if (wanted.size === 0) return;
+
+        const batch = [...wanted];
+
+        for (const id of batch) this.inFlight.add(id);
+
+        try {
+            const found = compact(await GetAlbumsCompleteness(batch));
+
+            for (const id of batch) {
+                this.cache.set(id, found[String(id)] ?? NOTHING_HERE);
+            }
+
+            this.notify();
+        } catch (err) {
+            // A count is an enrichment: without it a card shows the
+            // plain "you have this", which is what it showed before and
+            // is a weaker answer rather than a broken one.
+            console.error('Failed to load album completeness', err);
+        } finally {
+            for (const id of batch) this.inFlight.delete(id);
+        }
+    }
+
+    /** Drop everything: the files on disk changed. */
+    invalidate(): void {
+        this.cache = new LRUMap<number, Completeness>(
+            COMPLETENESS_CACHE_LIMIT,
+        );
+        this.notify();
+    }
+
+    private notify(): void {
+        for (const fn of this.listeners) fn();
+    }
+}
+
+export const completenessStore = new CompletenessStore();

frontend/src/store/queue-store.ts

@@ -57,6 +57,12 @@ interface TracksModified {
   index: number;
   positions?: number[];
   currentIndex: number;
+  /** The queue's source *after* the mutation. An append clears it
+   *  backend-side — a queue built from one album is not that album
+   *  once a track from elsewhere joins it — and this delta is the
+   *  only event those paths emit, so the label would otherwise keep
+   *  pointing at a collection the queue no longer holds. */
+  source?: QueueSource;
 }
 
 type Subscriber = () => void;
@@ -198,6 +204,7 @@ class QueueStore {
     }
 
     this.state.currentIndex = delta.currentIndex;
+    this.state.source = delta.source ?? EMPTY_QUEUE_SOURCE;
   }
 
   // ===================================================================

frontend/src/utils/icon-language.ts

@@ -0,0 +1,100 @@
+/**
+ * What each icon in this app means, once.
+ *
+ * The set was a mix: `plus` meant "add to the queue", "add to a
+ * playlist", "make a new playlist" and "you do not own this" — the
+ * first two *adjacent in the same context menu* — while `list` meant
+ * the queue, the Playlists destination, and (in `queue-panel` alone)
+ * adding to the queue. Two icons carrying seven meanings between them
+ * is not a vocabulary, and a user cannot learn one that says four
+ * things.
+ *
+ * The rule these are chosen by: **an icon names the noun it acts on,
+ * not the verb.** "Add to queue" and "add to playlist" are the same
+ * verb on different nouns, so the noun is what has to differ — which is
+ * also why adding to a playlist wears the Playlists destination's own
+ * icon rather than a generic plus. `plus` survives for exactly the one
+ * thing it is unambiguous about, making something that did not exist.
+ *
+ * Import these rather than writing a name inline. A literal string is
+ * how the last set drifted, and nothing catches it: a wrong-but-real
+ * icon renders perfectly.
+ */
+
+/** Start playing this now. */
+export const ICON_PLAY = 'play';
+
+/** Start playing this now, in a shuffled order. */
+export const ICON_SHUFFLE = 'shuffle';
+
+/**
+ * The queue, and putting something into it.
+ *
+ * One glyph for the noun and the action, so the button that opens the
+ * queue and the menu item that adds to it are visibly the same subject.
+ * The queue used to wear `list`, which is the Playlists destination.
+ */
+export const ICON_QUEUE = 'bars-staggered';
+
+/** Put this next in the queue rather than at the end. */
+export const ICON_PLAY_NEXT = 'forward-step';
+
+/**
+ * A playlist, and adding something to one.
+ *
+ * The same icon as the Playlists destination in the sidebar, which is
+ * the point: the menu item says where the thing is going.
+ */
+export const ICON_PLAYLIST = 'list';
+
+/**
+ * Make a new thing that did not exist — a playlist, a rule, a library.
+ *
+ * This is the only meaning `plus` keeps. It used to carry four.
+ */
+export const ICON_NEW = 'plus';
+
+/**
+ * The request ("want") toggle, as an outline/solid pair.
+ *
+ * Two states of one control have to read as each other's opposite,
+ * which a plus and a bookmark do not. The pair was already in the app
+ * and already correct — `explore-album-details`'s "Want this" button
+ * has used it since it was written, and `favorites-controller` uses the
+ * same shape for `regular/heart` → `heart` — while the badge forty
+ * pixels away showed a plus for the same state.
+ *
+ * That is `utils/library-status.ts`'s fault one layer down: it made the
+ * two surfaces agree on *what wanting means* and left them disagreeing
+ * on what it looks like.
+ */
+export const ICON_CAN_REQUEST = 'regular/bookmark';
+export const ICON_REQUESTED = 'solid/bookmark';
+
+/**
+ * You have this.
+ *
+ * Deliberately not drawn on the common case — see the tracklist, where
+ * absence is what gets marked. This is for the places that answer the
+ * question directly, like the badge on a catalog card.
+ */
+export const ICON_IN_LIBRARY = 'check';
+
+/**
+ * Something is being fetched right now.
+ *
+ * Distinct from `ICON_REQUESTED`: a request may sit on the list
+ * forever without anything happening, which is exactly why the badge's
+ * "queued" state stopped being an hourglass.
+ */
+export const ICON_DOWNLOADING = 'download';
+
+/**
+ * Take this away.
+ *
+ * One icon for removing from a playlist, from the queue and from the
+ * library, because the difference that matters is stated in the words
+ * beside it and in the confirmation — "Remove from Library" says in its
+ * impact line that the files are not deleted.
+ */
+export const ICON_REMOVE = 'trash';

frontend/src/utils/library-status.ts

@@ -1,7 +1,9 @@
+import { completenessStore } from '@store/completeness-store';
 import { downloadStore } from '@store/download-store';
 import { libraryStore } from '@store/library-store';
 import type * as download from '@go/download/models.js';
 import type { LibraryStatus } from '../components/library-status-indicator/library-status-indicator';
+import { isOwned, type Ownable } from './ownership';
 
 /**
  * What the tick/hourglass/plus badge should say about one entity.
@@ -46,6 +48,61 @@ export function libraryStatusFor(
     return 'not-in-library';
 }
 
+/**
+ * Everything a badge needs about one entity, decided in one place.
+ *
+ * `status` is the state; `owned`/`expected` are the counts behind
+ * `partial` and are zero for every other state, which is what the badge
+ * requires — it documents that a caller with no total must not pass a
+ * ring at 0%.
+ */
+export interface BadgeState {
+    status: LibraryStatus;
+    owned: number;
+    expected: number;
+}
+
+/**
+ * What the badge on an album card should say.
+ *
+ * Three rules, and the middle one is the whole point of this issue.
+ *
+ * **Ownership is the local album id**, per `utils/ownership.ts` — a
+ * file, not the catalog's `inLibrary` ratchet.
+ *
+ * **A partly-held album says how partly.** The count comes from
+ * `completenessStore`, which batches a screenful into one query;
+ * reading it is what asks for it. Before this, an album held 2 tracks
+ * of 10 wore the same green tick as one held whole on every grid in
+ * the app.
+ *
+ * **A total that was never declared is not a total of zero.** Where
+ * `known` is false — most of an untagged library, and every album until
+ * a rescan repopulates `audio_files.total_tracks` — this is a plain
+ * `in-library` and says nothing, which is the rule the badge's own
+ * documentation states and the reason `Known` exists at all.
+ */
+export function albumBadgeFor(
+    album: Ownable | null | undefined,
+    mbid?: string | null,
+): BadgeState {
+    if (!isOwned(album)) {
+        return { status: libraryStatusFor(false, mbid), owned: 0, expected: 0 };
+    }
+
+    const held = completenessStore.completeness(album?.localId);
+
+    if (held?.known && !held.complete) {
+        return {
+            status: 'partial',
+            owned: held.owned,
+            expected: held.expected,
+        };
+    }
+
+    return { status: 'in-library', owned: 0, expected: 0 };
+}
+
 /** What a badge can ask for. Artists are deliberately absent: a
  *  discography subscription is `explore-artist-details`'s Follow
  *  button, which can say what it is committing to. */

frontend/src/utils/ownership.ts

@@ -0,0 +1,134 @@
+/**
+ * What "I do not own this" looks like, and how the app decides it.
+ *
+ * The rule the user asked for, in their words: *owned content is the
+ * default, normal, unadorned presentation; unowned content is what gets
+ * marked*. `explore-album-details` implemented it for one tracklist —
+ * dimmed in place, `aria-disabled` because dimming is a colour and
+ * cannot be the only signal, and nothing at all drawn on the owned rows
+ * — and every other catalog surface still mixed the two with a small
+ * badge as the only difference. This is that rule, written once, so
+ * eight surfaces cannot each keep their own version of it.
+ *
+ * ## Ownership is a file, and `localId` is the flag that says so
+ *
+ * The album page answers "do I own this row" with `filePaths`, a map
+ * from a displayed track to a real file. A card grid cannot afford a
+ * lookup per card — and does not need one, because the answer is
+ * already on every model.
+ *
+ * `explore_index.local_artist_id` / `local_release_group_id` /
+ * `local_recording_id` are built by `collectLibraryEntities` from
+ * queries that every one join `audio_files`, and cleared by
+ * `pruneStaleLocalCrossReferences` whose existence test is a file test
+ * in all three cases. That is the same "ownership is a file" rule,
+ * computed once per scan instead of once per screenful.
+ *
+ * **`inLibrary` is the weaker one and is deliberately not consulted.**
+ * It is written by the same pass, so today the two agree — but it is a
+ * one-way ratchet (`in_library = MAX(in_library, excluded.in_library)`)
+ * whose only clearing pass is gated on a non-null `local_*_id`, so it
+ * cannot be un-set on its own. One of the two is a fact with an owner;
+ * the other is a flag that happens to agree with it.
+ *
+ * The divergence was observable before this: both `explore-view` and
+ * `explore-artist-details` kept a `libraryMBIDs` set that accumulated
+ * every MBID ever seen with `inLibrary` and cleared it never, in a view
+ * that never unmounts. And on one artist-detail card the two answers
+ * were used side by side — the context menu gated Play on
+ * `localId > 0` while the badge said "in your library" from
+ * `inLibrary`, so a card could claim to be owned, offer no Play, and
+ * (the request item being gated on *not* owned) offer no way to ask for
+ * it either.
+ */
+
+import { css } from 'lit';
+
+/** Anything a card or row can be drawn from, as far as this is concerned. */
+export interface Ownable {
+    /** The local row id behind this entity: an album, a file, an artist. */
+    localId?: number | null;
+}
+
+/**
+ * Whether there is something of the user's behind this entity.
+ *
+ * Deliberately narrow: a local id and nothing else. Passing the model
+ * straight in is the point — a call site that has to remember which of
+ * two fields to read is a call site that will eventually read the other
+ * one, which is exactly how the two answers came to sit on one card.
+ */
+export function isOwned(entity: Ownable | null | undefined): boolean {
+    return (entity?.localId ?? 0) > 0;
+}
+
+/** The kinds of thing a catalog surface can draw. */
+export type OwnableKind = 'album' | 'track' | 'artist';
+
+/**
+ * The sentence an unowned thing says, once.
+ *
+ * It reaches whoever is not seeing the dimming, so it has to name the
+ * thing as well as the state — "not in your library" alone, repeated
+ * down a grid, identifies nothing. The em dash matches the album
+ * tracklist's existing phrasing, which is where this came from.
+ */
+export function unownedLabel(name: string, kind: OwnableKind): string {
+    return `${name} — not in your library, ${
+        kind === 'artist' ? 'browsing the catalog' : 'available to request'
+    }`;
+}
+
+/**
+ * The accessible name for a card or row, owned or not.
+ *
+ * `activates` is what the thing does when it is yours: "Play", "Album",
+ * whatever the surface's own verb is. An unowned one does not get that
+ * verb, because it cannot do it.
+ */
+export function ownershipLabel(
+    owned: boolean,
+    activates: string,
+    name: string,
+    kind: OwnableKind,
+): string {
+    return owned ? `${activates} ${name}` : unownedLabel(name, kind);
+}
+
+/**
+ * The dimming, shared so it cannot drift across surfaces.
+ *
+ * Two things about it are load-bearing.
+ *
+ * **The text dims to a token, not with `opacity`.** `theme-store`'s
+ * ramps are checked by `theme-contrast.test.ts` against every surface
+ * text can sit on; an opacity multiplier is outside that check and
+ * would quietly drop a dimmed title under 4.5:1 on the light ramps.
+ * Secondary rather than tertiary for the reason the album tracklist
+ * gives: these rows and cards have a `bgOverlay` hover background,
+ * which tertiary does not clear.
+ *
+ * **Only the artwork takes an `opacity`.** A cover is not text, so it
+ * is outside the contrast rule entirely, and it is the part of a card
+ * that carries the most weight — dimming it is what makes a grid read
+ * as catalog at a glance rather than needing the badge to be found.
+ */
+export const unownedStyles = css`
+    .unowned .album-title,
+    .unowned .track-title,
+    .unowned .card-name,
+    .unowned .top-release-title,
+    .unowned .artist-name {
+        color: var(--yj-text-secondary, #b3b3b3);
+        font-weight: 400;
+    }
+
+    .unowned .album-art-container,
+    .unowned .top-release-art,
+    .unowned .track-art,
+    .unowned .card-image,
+    .unowned .card-image-placeholder,
+    .unowned .artist-avatar {
+        opacity: 0.55;
+    }
+`;

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

@@ -0,0 +1,87 @@
+/**
+ * The year on an album card survives a long album name.
+ *
+ * The year used to be part of the same run of text as the title, inside
+ * one `text-overflow: ellipsis` box — so it was the first thing the
+ * ellipsis ate. A card wide enough for a long name never showed its
+ * year at all, which means sorting the grid *by year* showed years only
+ * for the albums with short names: the sort said one thing and the
+ * cards showed another.
+ *
+ * The fix is a flex row in which only the title truncates, rather than
+ * a second line, because the card's height is what the virtualizer
+ * measures rows by.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+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';
+
+const LONG =
+  'The Rise and Fall of a Midwest Princess in the Key of Everything';
+
+/** Long names throughout: the fault only shows on a card under
+ *  pressure, and a grid of "Album 3" proves nothing. */
+const ALBUMS = Array.from({ length: 12 }, (_, i) => ({
+  ID: i + 1,
+  Name: `${LONG} ${i + 1}`,
+  ArtistName: 'Aurora Fields',
+  Year: 2019 + (i % 5),
+}));
+
+/** Give the virtualizer a viewport; a zero-height host renders nothing. */
+function sized(el: HTMLElement): void {
+  el.style.display = 'block';
+  el.style.height = '600px';
+  el.style.width = '900px';
+}
+
+async function settle(el: LitElement): Promise<void> {
+  await flush();
+  await el.updateComplete;
+  await new Promise((r) => setTimeout(r, 80));
+}
+
+describe('the album card’s year', () => {
+  beforeEach(() => {
+    resetHarness();
+    stub('library.Library.GetAlbums', ALBUMS);
+    stub('library.Library.GetTracks', []);
+    emit(Events.LibraryScanComplete);
+  });
+
+  it('is rendered on every card, however long the name', async () => {
+    const el = await fixture<LitElement>('cover-grid');
+
+    sized(el);
+    await settle(el);
+
+    const cards = shadowAll(el, '.album-card');
+    const years = shadowAll(el, '.album-year');
+
+    expect(cards.length).toBeGreaterThan(0);
+    expect(years).toHaveLength(cards.length);
+    expect(years.every((y) => /^\(\d{4}\)$/.test(y.textContent!.trim()))).toBe(
+      true,
+    );
+  });
+
+  it('is not what the ellipsis eats', async () => {
+    const el = await fixture<LitElement>('cover-grid');
+
+    sized(el);
+    await settle(el);
+
+    const year = shadowAll(el, '.album-year')[0]!;
+    const title = shadowAll(el, '.album-title')[0]!;
+
+    // The title is the box that gives way...
+    expect(title.scrollWidth).toBeGreaterThan(title.clientWidth);
+    // ...and the year keeps every pixel it asked for.
+    expect(year.clientWidth).toBeGreaterThan(0);
+    expect(year.scrollWidth).toBeLessThanOrEqual(year.clientWidth + 1);
+  });
+});

frontend/test/components/album-full-tracklist.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Asking to see the whole album.
+ *
+ * The page could already draw the full release with the missing rows
+ * dimmed, and did so automatically once the tags said the album was
+ * incomplete. What it could not do was be *asked*: the rule depends on
+ * the files declaring a per-disc total, so where they declare none —
+ * which is a great deal of any library — a partly-owned album showed
+ * only the tracks on disk and nothing said the rest existed.
+ *
+ * The switch is the explicit route. Its rules are all one rule: a
+ * control that cannot change what is on screen is worse than no
+ * control, which is the same test the version dropdown answers.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import { page } from 'vitest/browser';
+import type { LitElement } from 'lit';
+
+import '@components/explore-album-details/explore-album-details';
+import { stub, flush, resetHarness } from '@test/support/harness';
+import { fixture, shadow, shadowAll } from '@test/support/render';
+
+const MBID = 'rg-0001';
+
+function track(n: number, owned = false) {
+  return {
+    position: n,
+    discNumber: 1,
+    title: `Track ${n}`,
+    length: 200000,
+    mbid: `rec-${n}`,
+    inLibrary: owned,
+  };
+}
+
+function release(mbid: string, date: string, trackCount: number, owned = 0) {
+  return {
+    mbid,
+    title: 'Glass Harbour',
+    date,
+    status: 'Official',
+    tracks: Array.from({ length: trackCount }, (_, i) =>
+      track(i + 1, i < owned),
+    ),
+  };
+}
+
+/** Local files with no recording MBIDs — an untagged rip, which is the
+ * case the automatic rule cannot see. */
+function localTracks(count: number) {
+  return Array.from({ length: count }, (_, i) => ({
+    TrackName: `Track ${i + 1}`,
+    TrackNumber: i + 1,
+    DiscNumber: 1,
+    TrackLength: '210000',
+    RecordingMBID: '',
+  }));
+}
+
+const UNKNOWN = { owned: 0, expected: 0, known: false, complete: false };
+
+async function albumWith(
+  releases: unknown[],
+  completeness: Record<string, unknown>,
+  local: unknown[] = [],
+): Promise<LitElement> {
+  stub('explore.Service.BrowseReleases', releases);
+  stub('library.Library.GetAlbumCompleteness', completeness);
+  stub('library.Library.GetAlbumTracks', local);
+
+  const el = await fixture<LitElement>('explore-album-details', {
+    releaseGroupMBID: MBID,
+    localAlbumId: 7,
+    albumName: 'Glass Harbour',
+  });
+
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+const scopeSwitch = (el: LitElement) => shadow(el, '.tracklist-scope wa-switch');
+
+async function toggle(el: LitElement) {
+  const sw = scopeSwitch(el) as HTMLInputElement | null;
+  if (!sw) throw new Error('no tracklist scope switch on the page');
+
+  sw.checked = !sw.checked;
+  sw.dispatchEvent(new Event('change'));
+
+  await flush();
+  await el.updateComplete;
+}
+
+describe('the "show the whole album" switch', () => {
+  beforeEach(() => {
+    resetHarness();
+    stub('explore.Service.LookupReleaseGroup', {
+      mbid: MBID,
+      title: 'Glass Harbour',
+      artistCredit: 'Tideline',
+    });
+    stub('explore.Service.GetThumbnail', '');
+    stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+    stub('library.Library.GetFilePathsByRecordingMBIDs', {});
+  });
+
+  /**
+   * The report, exactly: two tracks on disk, twelve on the release,
+   * and nothing to say so because the tags declared no total.
+   */
+  it('reveals the rest of the release when the total is unknown', async () => {
+    const el = await albumWith(
+      [release('rel-1', '2019-04-01', 12, 2)],
+      UNKNOWN,
+      localTracks(2),
+    );
+
+    expect(shadowAll(el, '.track-row')).toHaveLength(2);
+
+    await toggle(el);
+
+    const rows = shadowAll(el, '.track-row');
+    expect(rows).toHaveLength(12);
+    // Nothing resolves to a file, so every row is marked unowned —
+    // the dimming is the signal, and it is not this switch's job to
+    // invent ownership it cannot prove.
+    expect(rows.filter((r) => r.classList.contains('unowned'))).toHaveLength(12);
+  });
+
+  /** And back again — a switch that only goes one way is a button. */
+  it('goes back to the files on disk', async () => {
+    const el = await albumWith(
+      [release('rel-1', '2019-04-01', 12, 2)],
+      UNKNOWN,
+      localTracks(2),
+    );
+
+    await toggle(el);
+    expect(shadowAll(el, '.track-row')).toHaveLength(12);
+
+    await toggle(el);
+    expect(shadowAll(el, '.track-row')).toHaveLength(2);
+  });
+
+  /**
+   * The automatic rule still fires, and the control has to agree with
+   * the page it is sitting on rather than starting out contradicting
+   * it. This is what the tri-state is for.
+   */
+  it('starts checked when the tags already said the album is short', async () => {
+    stub(
+      'library.Library.GetFilePathsByRecordingMBIDs',
+      Object.fromEntries(
+        Array.from({ length: 9 }, (_, i) => [
+          `rec-${i + 1}`,
+          [`/music/0${i + 1}.mp3`],
+        ]),
+      ),
+    );
+
+    const el = await albumWith(
+      [release('rel-1', '2019-04-01', 12, 9)],
+      { owned: 9, expected: 12, known: true, complete: false },
+      localTracks(9),
+    );
+
+    expect(shadowAll(el, '.track-row')).toHaveLength(12);
+    expect((scopeSwitch(el) as HTMLInputElement).checked).toBe(true);
+  });
+
+  /** And the user outranks it: turning it off asks for the files. */
+  it('lets the automatic answer be overridden', async () => {
+    const el = await albumWith(
+      [release('rel-1', '2019-04-01', 12, 9)],
+      { owned: 9, expected: 12, known: true, complete: false },
+      localTracks(9),
+    );
+
+    await toggle(el);
+
+    expect(shadowAll(el, '.track-row')).toHaveLength(9);
+  });
+
+  /**
+   * A control the accessibility tree cannot name is not a control, and
+   * this app has shipped that fault twice — `wa-slider` pointed
+   * `aria-labelledby` at an empty internal label, and `config-field`
+   * rendered a `<label>` as a sibling with no `for`.
+   *
+   * `wa-switch` gets it right for a *different* reason than either:
+   * its `<input role="switch">` sits inside a native `<label>` that also
+   * holds the `<slot>`, so the name is computed across the flattened
+   * tree from light-DOM text. That is worth an assertion rather than an
+   * assumption — and it has to be the browser's own answer, since
+   * querying shadow roots cannot compute a name.
+   */
+  it('is named for anyone not looking at it', async () => {
+    await albumWith(
+      [release('rel-1', '2019-04-01', 12, 2)],
+      UNKNOWN,
+      localTracks(2),
+    );
+
+    await expect
+      .element(page.getByRole('switch', { name: 'Show the whole album' }))
+      .toBeInTheDocument();
+  });
+
+  describe('is absent where it could not change anything', () => {
+    it('when the album is entirely owned', async () => {
+      // Ten files, a ten-track release: the switch would redraw the
+      // same list, which reads as broken.
+      const el = await albumWith(
+        [release('rel-1', '2019-04-01', 10, 10)],
+        { owned: 10, expected: 10, known: true, complete: true },
+        localTracks(10),
+      );
+
+      expect(scopeSwitch(el)).toBeNull();
+    });
+
+    it('when there is no catalog release to switch to', async () => {
+      const el = await albumWith([], UNKNOWN, localTracks(4));
+
+      expect(scopeSwitch(el)).toBeNull();
+    });
+
+    it('when the album is not in the library at all', async () => {
+      // Every entry here is already a catalog tracklist; there is no
+      // "only my tracks" to go back to.
+      const el = await albumWith([release('rel-1', '2019-04-01', 12)], UNKNOWN);
+
+      expect(scopeSwitch(el)).toBeNull();
+    });
+  });
+});

frontend/test/components/album-request-badge-visibility.test.ts

@@ -0,0 +1,97 @@
+/**
+ * The request badge on an unowned row is there without being hovered.
+ *
+ * It used to be transparent until the row was hovered or focused, on
+ * the reasoning that a column of plus signs down a mostly-owned album
+ * is clutter. That reasoning came from the green ticks it replaced and
+ * does not survive the rule those were removed for: a tick marked the
+ * **common** case, while this marks the rows that are *not* here. A
+ * mark on the exception is the information on this page, and one that
+ * exists only under the pointer cannot be seen, counted, or reached by
+ * anyone driving the app with a finger.
+ *
+ * That the badge *repaints* when clicked is the other half of #33 and
+ * is covered by `album-track-request.test.ts`.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/explore-album-details/explore-album-details';
+import { stub, flush, resetHarness } from '@test/support/harness';
+import { fixture, shadowAll } from '@test/support/render';
+
+function track(n: number, owned: boolean) {
+  return {
+    position: n,
+    discNumber: 1,
+    title: `Track ${n}`,
+    length: 200000,
+    mbid: `mbid-${n}`,
+    inLibrary: owned,
+  };
+}
+
+/** An album with one owned track and one that is not here. */
+async function albumWithAnUnownedTrack(): Promise<LitElement> {
+  const el = await fixture<LitElement>('explore-album-details', {
+    albumName: 'Glass Harbour',
+    releaseGroupMBID: 'rg-1',
+  });
+
+  stub('library.Library.GetFilePathsByRecordingMBIDs', {
+    'mbid-1': ['/music/mbid-1.mp3'],
+  });
+
+  Object.assign(el, {
+    versionEntries: [
+      {
+        key: 'v1',
+        label: '2019',
+        sublabel: '2 tracks',
+        tracks: [track(1, true), track(2, false)],
+      },
+    ],
+    selectedVersionKey: 'v1',
+    loadingReleases: false,
+    loadingInfo: false,
+  });
+  el.requestUpdate();
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+const badges = (el: LitElement) =>
+  shadowAll(el, 'library-status-indicator.track-request');
+
+describe('the tracklist’s request badge', () => {
+  beforeEach(() => {
+    resetHarness();
+    stub('library.Library.GetFilePathsByRecordingMBIDs', {});
+    stub('library.Library.GetFilePathsByAlbums', {});
+    stub('library.Library.GetAlbumTracks', []);
+    stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+    stub('download.Service.ProviderKinds', []);
+    stub('download.Service.ListProviders', []);
+    stub('download.Service.ListDownloads', []);
+    stub('download.Service.ListRequests', []);
+  });
+
+  it('is visible without a pointer anywhere near it', async () => {
+    const el = await albumWithAnUnownedTrack();
+    const [badge] = badges(el);
+
+    expect(badge).toBeTruthy();
+    // Computed opacity rather than the absence of a rule, because the
+    // rule could come back under a different selector.
+    expect(getComputedStyle(badge!).opacity).toBe('1');
+  });
+
+  it('is still only on the rows with something to request', async () => {
+    // Always-visible is not the same as everywhere: an owned track has
+    // nothing left to ask for, and a badge on it would be the column of
+    // green ticks this page deliberately stopped drawing.
+    expect(badges(await albumWithAnUnownedTrack())).toHaveLength(1);
+  });
+});

frontend/test/components/album-track-request.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Issue #33: "Want track" filed the request and left the badge alone.
+ *
+ * The tracklist's badges read `libraryStatusFor(false, track.mbid)` at
+ * render time, which is a dependency on `downloadStore` that Lit cannot
+ * see. `explore-album-details` did subscribe to that store, but its
+ * callback only assigned `canDownload` and `isRequested` — neither of
+ * which a *track* request changes — so nothing in the component's
+ * reactive state moved and the page never re-rendered. The request was
+ * real, the plus stayed a plus, and clicking again cancelled it.
+ *
+ * The other three hosts rendering these badges (`explore-artist-
+ * details`, `explore-view`, `top-results-row`) have always asked for
+ * the repaint in the same place, which is what made this one look
+ * correct on inspection.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/explore-album-details/explore-album-details';
+import type { Request } from '@store/download-store';
+import { Events } from '../../src/events';
+import { stub, flush, resetHarness, emit } from '@test/support/harness';
+import { fixture, shadowAll } from '@test/support/render';
+
+type RequestOverrides = Partial<Omit<Request, 'state' | 'entity'>> & {
+  state?: `${Request['state']}`;
+  entity?: `${Request['entity']}`;
+};
+
+function request(overrides: RequestOverrides): Request {
+  return {
+    id: 1,
+    mbid: 'mbid-1',
+    entity: 'recording',
+    libraryId: 1,
+    artist: 'An Artist',
+    title: 'Track 1',
+    scope: 'future',
+    secondary: false,
+    state: 'wanted',
+    attempts: 0,
+    ...overrides,
+  } as Request;
+}
+
+/** Put a request list into the store the way the backend does. */
+async function withRequests(rows: Request[]): Promise<void> {
+  stub('download.Service.ListRequests', rows);
+  emit(Events.RequestsChanged);
+  await flush();
+}
+
+function track(n: number) {
+  return {
+    position: n,
+    discNumber: 1,
+    title: `Track ${n}`,
+    length: 200000,
+    mbid: `mbid-${n}`,
+    inLibrary: false,
+  };
+}
+
+/** An unowned catalog tracklist, which is the only case with badges:
+ *  an owned row renders none, there being nothing left to ask for. */
+async function withTracklist(count: number): Promise<LitElement> {
+  const el = await fixture<LitElement>('explore-album-details', {
+    albumName: 'Glass Harbour',
+  });
+
+  Object.assign(el, {
+    versionEntries: [
+      {
+        key: 'v1',
+        label: '2019',
+        sublabel: `${count} tracks`,
+        tracks: Array.from({ length: count }, (_, i) => track(i + 1)),
+      },
+    ],
+    selectedVersionKey: 'v1',
+    loadingReleases: false,
+    loadingInfo: false,
+  });
+  el.requestUpdate();
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+/** The status of each track badge, in tracklist order. */
+function badgeStatuses(el: LitElement): string[] {
+  return shadowAll(el, 'library-status-indicator.track-request').map(
+    (b) => b.getAttribute('status') ?? '',
+  );
+}
+
+describe('the album tracklist’s request badges', () => {
+  beforeEach(async () => {
+    resetHarness();
+    stub('library.Library.GetFilePathsByRecordingMBIDs', {});
+    stub('library.Library.GetFilePathsByAlbums', {});
+    stub('library.Library.GetAlbumTracks', []);
+    stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+    await withRequests([]);
+  });
+
+  it('starts as a plus on every unowned row', async () => {
+    const el = await withTracklist(3);
+
+    expect(badgeStatuses(el)).toEqual([
+      'not-in-library',
+      'not-in-library',
+      'not-in-library',
+    ]);
+  });
+
+  it('repaints the row whose track has been requested', async () => {
+    const el = await withTracklist(3);
+
+    await withRequests([request({ mbid: 'mbid-2' })]);
+    await el.updateComplete;
+
+    // Only the requested row moves. A request is by MBID, so the two
+    // rows either side of it are still a plus.
+    expect(badgeStatuses(el)).toEqual([
+      'not-in-library',
+      'queued',
+      'not-in-library',
+    ]);
+  });
+
+  it('repaints again when the request is cancelled', async () => {
+    const el = await withTracklist(3);
+
+    await withRequests([request({ mbid: 'mbid-2' })]);
+    await el.updateComplete;
+
+    await withRequests([]);
+    await el.updateComplete;
+
+    expect(badgeStatuses(el)).toEqual([
+      'not-in-library',
+      'not-in-library',
+      'not-in-library',
+    ]);
+  });
+});

frontend/test/components/album-tracklist-heading.test.ts

@@ -0,0 +1,89 @@
+/**
+ * The tracklist's own heading.
+ *
+ * A list of numbered titles with durations, under the album's cover, is
+ * the one thing on this page that did not need a word above it saying
+ * what it was — "TRACKLIST" labelled the only thing already obvious.
+ *
+ * What goes is the *ink*, not the element. The section is a landmark
+ * and the page's heading structure runs through it, so a reader moving
+ * by heading still has to be able to find it, and it is hidden the way
+ * `sr-only` hides things: `clip-path`, never `display: none`, which
+ * would take it out of the accessibility tree along with the layout.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/explore-album-details/explore-album-details';
+import { stub, flush, resetHarness } from '@test/support/harness';
+import { fixture, shadowAll } from '@test/support/render';
+
+function track(n: number) {
+  return {
+    position: n,
+    discNumber: 1,
+    title: `Track ${n}`,
+    length: 200000,
+    mbid: `mbid-${n}`,
+    inLibrary: true,
+  };
+}
+
+async function albumPage(): Promise<LitElement> {
+  const el = await fixture<LitElement>('explore-album-details', {
+    albumName: 'Glass Harbour',
+    releaseGroupMBID: 'rg-1',
+  });
+
+  Object.assign(el, {
+    versionEntries: [
+      {
+        key: 'v1',
+        label: '2019',
+        sublabel: '2 tracks',
+        tracks: [track(1), track(2)],
+      },
+    ],
+    selectedVersionKey: 'v1',
+    loadingReleases: false,
+    loadingInfo: false,
+  });
+  el.requestUpdate();
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+const tracklistHeading = (el: LitElement) =>
+  shadowAll(el, 'h3').find((h) => h.textContent?.trim() === 'Tracklist');
+
+describe('the album tracklist heading', () => {
+  beforeEach(() => {
+    resetHarness();
+    stub('library.Library.GetFilePathsByRecordingMBIDs', {});
+    stub('library.Library.GetFilePathsByAlbums', {});
+    stub('library.Library.GetAlbumTracks', []);
+    stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+    stub('download.Service.ProviderKinds', []);
+    stub('download.Service.ListProviders', []);
+    stub('download.Service.ListDownloads', []);
+    stub('download.Service.ListRequests', []);
+  });
+
+  it('is still in the tree', async () => {
+    expect(tracklistHeading(await albumPage())).toBeTruthy();
+  });
+
+  it('takes up no room on the page', async () => {
+    const heading = tracklistHeading(await albumPage())!;
+    const box = heading.getBoundingClientRect();
+
+    expect(box.width).toBeLessThanOrEqual(1);
+    expect(box.height).toBeLessThanOrEqual(1);
+    // Hidden by clipping, not by removal: display:none and
+    // visibility:hidden both take it out of the accessibility tree.
+    expect(getComputedStyle(heading).display).not.toBe('none');
+    expect(getComputedStyle(heading).visibility).not.toBe('hidden');
+  });
+});

frontend/test/components/album-version-demotion.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Choosing a pressing is a repair job, not the album page's headline.
+ *
+ * The version selector sat directly above the tracklist with a heading,
+ * a `<select>` and a paragraph explaining how our clustering picks a
+ * "standard version" — the most valuable space on the page spent on a
+ * control a normal user never touches (#17). Two more blocks shared
+ * that slot and were not even guarded by "is there a choice": a
+ * `Versions / Loading releases…` spinner about the same fetch
+ * `renderTracklist` was already reporting, and a `Versions / <error>`
+ * block duplicating what `catalog-scope-notice` shows at the top of the
+ * page with a retry.
+ *
+ * What is pinned here is the demotion and the three things that must
+ * survive it: the control is still reachable, the page still says which
+ * version you are looking at once you have chosen one, and a failed
+ * fetch still says so somewhere a collapsed panel is not.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+import { page } from 'vitest/browser';
+
+import '@components/explore-album-details/explore-album-details';
+import { stub, stubFailure, flush, resetHarness } from '@test/support/harness';
+import { fixture, shadow, shadowAll } from '@test/support/render';
+
+const MBID = 'rg-0001';
+
+function track(n: number) {
+  return {
+    position: n,
+    discNumber: 1,
+    title: `Track ${n}`,
+    length: 200000,
+    mbid: `rec-${n}`,
+    inLibrary: false,
+  };
+}
+
+function release(mbid: string, date: string, trackCount: number) {
+  return {
+    mbid,
+    title: 'Glass Harbour',
+    date,
+    status: 'Official',
+    tracks: Array.from({ length: trackCount }, (_, i) => track(i + 1)),
+  };
+}
+
+const UNKNOWN = { owned: 0, expected: 0, known: false, complete: false };
+
+/** Two releases whose tracklists genuinely differ, so there is a choice. */
+const TWO = [release('rel-1', '2019-04-01', 10), release('rel-2', '2020-09-01', 14)];
+
+async function album(releases: unknown[] = TWO): Promise<LitElement> {
+  stub('explore.Service.BrowseReleases', releases);
+  stub('library.Library.GetAlbumCompleteness', UNKNOWN);
+  stub('library.Library.GetAlbumTracks', []);
+
+  const el = await fixture<LitElement>('explore-album-details', {
+    releaseGroupMBID: MBID,
+    localAlbumId: 7,
+    albumName: 'Glass Harbour',
+  });
+
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+/** Positions of two selectors within the shadow root, in document order. */
+function order(el: Element, first: string, second: string): [number, number] {
+  const all = [...(el.shadowRoot?.querySelectorAll('*') ?? [])];
+  const a = all.findIndex((n) => n.matches(first));
+  const b = all.findIndex((n) => n.matches(second));
+
+  return [a, b];
+}
+
+beforeEach(() => {
+  resetHarness();
+  stub('explore.Service.LookupReleaseGroup', {
+    mbid: MBID,
+    title: 'Glass Harbour',
+    artistCredit: 'Tideline',
+  });
+  stub('explore.Service.GetThumbnail', '');
+  stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+  stub('library.Library.GetFilePathsByRecordingMBIDs', {});
+});
+
+describe('the version selector is no longer the headline', () => {
+  it('renders after the tracklist, not before it', async () => {
+    const el = await album();
+    const [tracklist, versions] = order(el, '.tracklist', '.versions');
+
+    expect(tracklist).toBeGreaterThan(-1);
+    expect(versions).toBeGreaterThan(tracklist);
+  });
+
+  it('starts collapsed', async () => {
+    const el = await album();
+
+    expect(shadow(el, '#versions-body')?.hasAttribute('hidden')).toBe(true);
+  });
+
+  /**
+   * `aria-controls` has to name an element that is in the DOM, so the
+   * body renders unconditionally and is toggled with `hidden` — the
+   * rule `config-section` states and the reason a conditional body
+   * would be wrong here too.
+   */
+  it('keeps the panel in the DOM while it is shut', async () => {
+    const el = await album();
+
+    expect(shadow(el, '#versions-body')).not.toBeNull();
+    expect(
+      shadow(el, '.versions-toggle')?.getAttribute('aria-controls'),
+    ).toBe('versions-body');
+  });
+
+  /**
+   * The browser's own answer: a disclosure that cannot be tabbed to is
+   * the fault `config-section` shipped for every setting in the app,
+   * and a shadow-root query cannot tell you a control has a name.
+   */
+  it('is a named, expandable button', async () => {
+    await album();
+
+    await expect
+      .element(
+        page.getByRole('button', { name: /Other versions of this album \(2\)/ }),
+      )
+      .toBeInTheDocument();
+  });
+
+  it('opens when the button is pressed', async () => {
+    const el = await album();
+    const toggle = shadow<HTMLButtonElement>(el, '.versions-toggle');
+
+    expect(toggle?.getAttribute('aria-expanded')).toBe('false');
+
+    toggle?.click();
+    await el.updateComplete;
+
+    expect(toggle?.getAttribute('aria-expanded')).toBe('true');
+    expect(shadow(el, '#versions-body')?.hasAttribute('hidden')).toBe(false);
+  });
+
+  it('says nothing at all when there is only one tracklist', async () => {
+    const el = await album([release('rel-1', '2019-04-01', 10)]);
+
+    expect(shadow(el, '.versions')).toBeNull();
+  });
+});
+
+describe('the two blocks that shared that slot', () => {
+  /**
+   * The spinner was unguarded, so `Versions / Loading releases…` took
+   * the primary position on *every* album load — including the ones
+   * that would never offer a choice — beside `renderTracklist`'s own
+   * "Loading tracks…" about the same fetch.
+   */
+  it('no longer reports the same fetch twice while loading', async () => {
+    stub('library.Library.GetAlbumCompleteness', UNKNOWN);
+    stub('library.Library.GetAlbumTracks', []);
+    stub('explore.Service.BrowseReleases', () => new Promise(() => {}));
+
+    const el = await fixture<LitElement>('explore-album-details', {
+      releaseGroupMBID: MBID,
+      albumName: 'Glass Harbour',
+    });
+
+    const loading = shadowAll(el, '.section-loading');
+
+    expect(loading).toHaveLength(1);
+    expect(loading[0]?.textContent).toContain('Loading tracks');
+  });
+
+  /**
+   * A failed browse must still be visible, and it cannot be visible
+   * from inside a collapsed disclosure. It belongs to the list that is
+   * missing because of it — `renderTracklist` used to return `nothing`
+   * here and lean on the selector's own error block, which is exactly
+   * the coupling that made this a rewrite rather than a move.
+   */
+  it('reports a failed fetch in the tracklist, once', async () => {
+    stub('library.Library.GetAlbumCompleteness', UNKNOWN);
+    stub('library.Library.GetAlbumTracks', []);
+    stubFailure('explore.Service.BrowseReleases', 'the catalog said no');
+
+    const el = await fixture<LitElement>('explore-album-details', {
+      releaseGroupMBID: MBID,
+      albumName: 'Glass Harbour',
+    });
+
+    await flush();
+    await el.updateComplete;
+
+    const errors = shadowAll(el, '.section-error');
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.textContent).toContain('versions');
+    expect(shadow(el, '.versions')).toBeNull();
+  });
+});
+
+describe('which version is on screen', () => {
+  /**
+   * The default is what the header already describes, so a line saying
+   * so on every album would be the thing this issue removed, one size
+   * smaller.
+   */
+  it('is not stated while the page picked it', async () => {
+    const el = await album();
+
+    expect(shadow(el, '.chosen-version')).toBeNull();
+  });
+
+  /**
+   * The moment someone chooses another, the tracklist and the header
+   * disagree — and the control that explains it is now off the bottom
+   * of the page.
+   */
+  it('is stated above the tracklist once the user chooses', async () => {
+    const el = await album();
+    const select = shadow<HTMLSelectElement>(el, '#version-select')!;
+    const other = [...select.options].find((o) => o.value !== select.value)!;
+
+    select.value = other.value;
+    select.dispatchEvent(new Event('change'));
+    await el.updateComplete;
+
+    const line = shadow(el, '.chosen-version');
+
+    expect(line).not.toBeNull();
+
+    const [chosen, tracklist] = order(el, '.chosen-version', '.tracklist');
+
+    expect(chosen).toBeGreaterThan(-1);
+    expect(tracklist).toBeGreaterThan(chosen);
+  });
+
+  it('offers a way back, which clears the line', async () => {
+    const el = await album();
+    const select = shadow<HTMLSelectElement>(el, '#version-select')!;
+    const first = select.value;
+    const other = [...select.options].find((o) => o.value !== first)!;
+
+    select.value = other.value;
+    select.dispatchEvent(new Event('change'));
+    await el.updateComplete;
+
+    shadow<HTMLButtonElement>(el, '.chosen-version-reset')?.click();
+    await el.updateComplete;
+
+    expect(shadow<HTMLSelectElement>(el, '#version-select')?.value).toBe(first);
+    expect(shadow(el, '.chosen-version')).toBeNull();
+  });
+
+  /** A panel that shuts on use cannot be used twice. */
+  it('leaves the disclosure open after a choice', async () => {
+    const el = await album();
+
+    shadow<HTMLButtonElement>(el, '.versions-toggle')?.click();
+    await el.updateComplete;
+
+    const select = shadow<HTMLSelectElement>(el, '#version-select')!;
+    const other = [...select.options].find((o) => o.value !== select.value)!;
+
+    select.value = other.value;
+    select.dispatchEvent(new Event('change'));
+    await el.updateComplete;
+
+    expect(shadow(el, '#versions-body')?.hasAttribute('hidden')).toBe(false);
+  });
+});

frontend/test/components/chrome.test.ts

@@ -19,6 +19,11 @@ import {
   update,
   visual,
 } from '@test/support/render';
+import {
+  ICON_CAN_REQUEST,
+  ICON_IN_LIBRARY,
+  ICON_REQUESTED,
+} from '@utils/icon-language';
 
 describe('<app-sidebar>', () => {
   it('renders a testid per destination, which is how e2e navigates', async () => {
@@ -154,9 +159,20 @@ describe('<library-status-indicator>', () => {
   it('defaults to "not in library"', async () => {
     const el = await fixture('library-status-indicator');
 
-    expect(shadow(el, 'wa-icon')?.getAttribute('name')).toBe('plus');
+    expect(shadow(el, 'wa-icon')?.getAttribute('name')).toBe(ICON_CAN_REQUEST);
   });
 
+  /**
+   * Named from the vocabulary rather than written out, or this test
+   * pins the glyphs *against* the table it is supposed to follow —
+   * which is what it did: it asserted `plus` for the un-owned state,
+   * the same glyph two adjacent menu items were using for two other
+   * meanings, and passing was the reason nobody looked.
+   *
+   * What is still worth asserting is that the three differ, which is
+   * the property the states need and the one the table cannot state
+   * about itself here.
+   */
   it('uses a distinct glyph per state', async () => {
     const glyphs: (string | null | undefined)[] = [];
 
@@ -166,7 +182,8 @@ describe('<library-status-indicator>', () => {
       glyphs.push(shadow(el, 'wa-icon')?.getAttribute('name'));
     }
 
-    expect(glyphs).toEqual(['check', 'bookmark', 'plus']);
+    expect(glyphs).toEqual([ICON_IN_LIBRARY, ICON_REQUESTED, ICON_CAN_REQUEST]);
+    expect(new Set(glyphs).size).toBe(3);
   });
 
   it('phrases its label around the entity it describes', async () => {

frontend/test/components/downloads-no-client.test.ts

@@ -0,0 +1,90 @@
+/**
+ * What a wanted list says when there is nothing to search with.
+ *
+ * Wanting something without a download client is a supported thing to
+ * do — the list is kept, and it starts moving when a client is added.
+ * What was not supported was the app *claiming to be looking*: every
+ * pass attempted each request, failed it with "no download clients are
+ * enabled", recorded that as an attempt and scheduled a retry, so a row
+ * read "Searched 3 times, no download clients are enabled · next check
+ * in 6 hours" about a check that could not happen.
+ *
+ * The backend half is `TestNoProvidersMeansNoAttempt`. This is the row.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/downloads-view/downloads-view';
+import { stub, emit, flush, resetHarness } from '@test/support/harness';
+import { Events } from '../../src/events';
+import { fixture, shadowAll } from '@test/support/render';
+
+/** A request that has been tried and is waiting on a retry — the shape
+ *  a list with a client in it produces. */
+const WAITING = {
+  id: 1,
+  mbid: 'rg-1',
+  entity: 'release-group',
+  libraryId: 1,
+  artist: 'Aurora Fields',
+  title: 'Glass Harbour',
+  state: 'wanted',
+  attempts: 3,
+  lastError: 'no source has it yet',
+  nextTryAt: new Date(Date.now() + 6 * 3600_000).toISOString(),
+};
+
+const PROVIDER = {
+  id: 1,
+  kind: 'slskd',
+  name: 'Sound',
+  enabled: true,
+  priority: 50,
+};
+
+/**
+ * The download store is a singleton whose `init()` runs once per
+ * session, so a second mount does not re-read the provider list. The
+ * event is how the app itself learns a client was added, and is what
+ * makes this test independent of which case ran first.
+ */
+async function view(providers: unknown[]): Promise<LitElement> {
+  stub('download.Service.ListProviders', providers);
+
+  const el = await fixture<LitElement>('downloads-view');
+
+  emit(Events.DownloadProvidersChanged);
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+const details = (el: LitElement) =>
+  shadowAll(el, '.detail').map((d) => d.textContent!.trim());
+
+describe('a request row with no download client', () => {
+  beforeEach(() => {
+    resetHarness();
+    stub('download.Service.ProviderKinds', []);
+    stub('download.Service.ListProviders', []);
+    stub('download.Service.ListDownloads', []);
+    stub('download.Service.ListRequests', [WAITING]);
+  });
+
+  it('does not promise a check that cannot happen', async () => {
+    const el = await view([]);
+
+    expect(details(el)).toHaveLength(1);
+    expect(details(el)[0]).toBe(
+      'On your list — no download client to search with',
+    );
+    expect(details(el)[0]).not.toMatch(/next check/);
+  });
+
+  it('reports the retry schedule again once a client exists', async () => {
+    const el = await view([PROVIDER]);
+
+    expect(details(el)[0]).toMatch(/next check/);
+  });
+});

frontend/test/components/icon-language.test.ts

@@ -0,0 +1,140 @@
+/**
+ * The icon vocabulary is one table, and nothing writes around it.
+ *
+ * A wrong-but-real icon name renders perfectly: no error, no fallback,
+ * no failing assertion anywhere. That is how `plus` came to mean "add
+ * to the queue", "add to a playlist", "make a new playlist" and "you do
+ * not own this" — the first two adjacent in the same context menu —
+ * while `list` meant the queue, the Playlists destination *and* adding
+ * to the queue.
+ *
+ * `src/icons/index.ts` catches a name that is not *bundled*. Nothing
+ * catches a name that is bundled and means something else, so this
+ * sweeps the source for the governed ones. It is the same shape as
+ * `TestNoDirectRuntimeEmits` and `TestNoWritesOnTheReadPool` in the
+ * backend, and exists for the same reason: the rule is about every call
+ * site, so checking one is checking nothing.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { bundledIconNames } from '../../src/icons';
+import * as icons from '@utils/icon-language';
+
+/** Every component source, as text. */
+const SOURCES = import.meta.glob<string>('../../src/**/*.ts', {
+  eager: true,
+  query: '?raw',
+  import: 'default',
+});
+
+/**
+ * The names that carry a meaning the table owns.
+ *
+ * Deliberately not every bundled name. `check` is `ICON_IN_LIBRARY`
+ * here and also the "Copied" confirmation in `job-log-view`, which is
+ * a different, perfectly good meaning — governing it would force a
+ * false rename. What belongs on this list is a name that was actually
+ * overloaded.
+ */
+const GOVERNED = [
+  'plus',
+  'list',
+  'bookmark',
+  'solid/bookmark',
+  'regular/bookmark',
+  'bars-staggered',
+];
+
+/** The one file allowed to say them, plus its own test. */
+const DEFINITION = /icon-language\.(ts|test\.ts)$/;
+
+describe('the icon vocabulary', () => {
+  /**
+   * A sweep over nothing passes. This is the assertion that makes the
+   * rest of the file mean something, and it is the first thing that
+   * breaks if the glob pattern stops matching after a move.
+   */
+  it('actually reads the source', () => {
+    const paths = Object.keys(SOURCES);
+
+    expect(paths.length).toBeGreaterThan(100);
+    expect(paths.some((p) => p.endsWith('/track-list.ts'))).toBe(true);
+    expect(SOURCES[paths[0]!]).toContain('import');
+  });
+
+  it.each(GOVERNED)('is not written around for %s', (name) => {
+    const offenders: string[] = [];
+
+    for (const [path, source] of Object.entries(SOURCES)) {
+      if (DEFINITION.test(path)) continue;
+
+      // Both spellings: an icon in a template, and an icon name in a
+      // data table (which is how the sidebar and bottom-nav carry
+      // theirs).
+      const literal = new RegExp(
+        `(name="${name}"|icon: '${name}'|name=\\$\\{[^}]*'${name}')`,
+      );
+
+      if (literal.test(source)) offenders.push(path);
+    }
+
+    expect(offenders).toEqual([]);
+  });
+
+  /**
+   * A meaning with no icon behind it is the state the badge's `queued`
+   * spent a year in — declared, styled, and produced by nothing.
+   */
+  it('gives every meaning a name', () => {
+    const values = Object.entries(icons).filter(([k]) => k.startsWith('ICON_'));
+
+    expect(values.length).toBeGreaterThan(0);
+
+    for (const [key, value] of values) {
+      expect(`${key}=${value}`).toMatch(/^ICON_[A-Z_]+=[a-z]+[a-z/-]*$/);
+    }
+  });
+
+  /**
+   * Every name in the table is a name the app actually ships.
+   *
+   * This is the loop the vocabulary closes. A name that is not bundled
+   * renders a circled question mark and reports itself to
+   * `__yjIconMisses` — at *runtime*, from a state something has to
+   * reach first. `bookmark-check` is Font Awesome **Pro**, and it was
+   * on `explore-artist-details`'s Follow button, drawn for every
+   * followed artist, invisible to `offline-icons.spec.ts` because no
+   * spec had ever followed one. Reaching the state is no longer how
+   * this is found.
+   */
+  it('names only icons that are bundled', () => {
+    const bundled = new Set(bundledIconNames());
+    const missing = Object.entries(icons)
+      .filter(([k]) => k.startsWith('ICON_'))
+      .filter(([, v]) => !bundled.has(v as string))
+      .map(([k, v]) => `${k} (${v})`);
+
+    expect(missing).toEqual([]);
+  });
+
+  /**
+   * The two states of the request toggle have to be the same glyph in
+   * two weights, or they do not read as each other's opposite — which
+   * is what a plus against a bookmark was.
+   */
+  it('makes the request toggle an outline/solid pair', () => {
+    expect(icons.ICON_CAN_REQUEST).toBe(`regular/${icons.ICON_REQUESTED.replace('solid/', '')}`);
+  });
+
+  /**
+   * The queue and the Playlists destination wore the same icon, and
+   * "add to queue" and "add to playlist" sat next to each other wearing
+   * a third same one. Whatever the table says, these three have to
+   * differ from each other.
+   */
+  it('keeps the queue, playlists and creating something apart', () => {
+    const three = [icons.ICON_QUEUE, icons.ICON_PLAYLIST, icons.ICON_NEW];
+
+    expect(new Set(three).size).toBe(3);
+  });
+});

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

@@ -77,3 +77,30 @@ describe('the library status badge', () => {
     expect(name).toContain('Glass Harbour');
   });
 });
+
+/**
+ * A partly-held album is the one state that is *actionable and
+ * counted*: there are tracks left to ask for, so the badge is a button
+ * — and a control is named after what activating it does, which is how
+ * the count came to be dropped from exactly the state the ring exists
+ * for. Both, or the ring says "some" to an eye and nothing to anyone
+ * else.
+ */
+describe('a partial badge that can act', () => {
+  it('names the action and keeps the count', async () => {
+    const el = await fixture('library-status-indicator', {
+      status: 'partial',
+      owned: 9,
+      expected: 12,
+      entityType: 'album',
+      label: 'Glass Harbour',
+      requestMbid: 'rg-1',
+    });
+
+    const name = shadow(el, '.badge')?.getAttribute('aria-label') ?? '';
+
+    expect(shadow(el, 'button.badge')).not.toBeNull();
+    expect(name).toContain('Request the rest of');
+    expect(name).toContain('9 of 12');
+  });
+});

frontend/test/components/transport.test.ts

@@ -227,6 +227,41 @@ describe('<seek-bar>', () => {
     expect(text(el, '[data-testid="remaining-time"]')).toBe('01:30');
   });
 
+  it('keeps the slider still as the clocks count', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 31 });
+    await flush();
+    await el.updateComplete;
+
+    const slider = () =>
+      shadow(el, 'wa-slider')!.getBoundingClientRect();
+    const before = slider();
+
+    // 1:11 against 4:08 is the reported jitter: different digits, and
+    // in a proportional font different widths. Toggling the right-hand
+    // clock is the other half -- the minus sign is a whole character.
+    for (const positionSeconds of [8, 71, 88]) {
+      emit(Events.PlaybackPositionChanged, {
+        positionSeconds,
+        trackLength: 90,
+        trackChangeId: 31,
+        seq: positionSeconds,
+        playing: true,
+      });
+      await flush();
+      await el.updateComplete;
+
+      expect(slider().width).toBeCloseTo(before.width, 1);
+      expect(slider().left).toBeCloseTo(before.left, 1);
+    }
+
+    await click(el, '[data-testid="remaining-time"]');
+    await el.updateComplete;
+
+    expect(slider().width).toBeCloseTo(before.width, 1);
+  });
+
   it('renders the position the backend reports rather than its own count', async () => {
     const el = await fixture('seek-bar');