docs(jobs): the phone's band, and why it is in flow

CLAUDE.md's jobs section said the header indicator is "the one view of
everything at once, from every page"; that is now true on a desktop
only, and the band is the phone's half.

NOTES.md takes the measurement that decided the shape -- an overlay
band at 424x439 is a lid, not a notification -- and the corollary about
which tier can see it: ui-test, tsc, lint and the Go suite all passed
on the broken version, and what failed was three e2e specs that have
nothing to do with jobs. Run the suite, not the spec you wrote.

.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/skills/yellowjacket-dev/SKILL.md

@@ -195,6 +195,12 @@ Two rules about climbing:
 - **Do not write an e2e spec first.** Drive the flow by hand, then
   promote it with `/e2e`. Specs written blind assert on selectors that
   do not exist.
+- **Not every view has a nav item.** Since #25 the destinations are
+  configurable, Autotag is hidden by default and Downloads is absent
+  until a download client exists — so `getByTestId('nav-<view>')` waits
+  30 s for a locator that will never resolve. `navigateTo(page, view)`
+  (`e2e/support/fixtures.ts`) dispatches the app's own `navigate` event.
+  Click the nav item when the *nav* is what the spec is about.
 
 Before a commit, the gate is `make lint`, `make test`, `make ui-test`,
 `make bindings-check`, `make css-check` and — from `frontend/` —

.pi/skills/yellowjacket-dev/references/android-tier.md

@@ -194,9 +194,13 @@ like the app's fault and none is:
 |---|---|---|
 | x86_64 | modernc's raw `lstat` vs seccomp | SIGSYS, syscall 6 |
 | arm64, translated | Go reads `ID_AA64ISAR0_EL1` | SIGILL |
-| arm64, real device | — | unverified, still |
+| arm64, real device | **runs** (2026-08-20) | — |
 
-**A physical arm64 device remains the only verification path.**
+**A physical arm64 device remains the only verification path**, and it
+has now been walked: a Light Phone III (TLP301, Android 14 / SDK 34,
+arm64-v8a, WebView Chrome 113 at 424x439). The app builds, installs,
+launches and stays up; `make android-smoke SECONDS=60` passes on it.
+What that run *found* is the lifecycle fault below.
 
 ### What was fixed to get here
 
@@ -210,6 +214,11 @@ no-op. `backend/system` gained no import of the Wails application
 package, which matters for the same reason `backend/events` is split by
 the `indexbuild` tag.
 
+**And `main()` is now latched to one run per process** (#52). That is
+the second `os.Exit(1)` in this file's history and it had the same
+signature as the first, which is the argument for #160: both were named
+exactly by an `slog` line that went to `/dev/null`.
+
 ### What is still not done
 
 The shell is still a desktop shell, and the x86_64 half of the APK is
@@ -249,10 +258,25 @@ one.
 `build/android/Taskfile.yml` ships more than the Makefile wraps, and
 they are the right thing to reach for when you want something one-off:
 
+> **These four were unsafe until #159 and are now the way in.** All of
+> them began with `adb uninstall {{.APP_ID}}`, where `APP_ID` defaulted
+> to `app.yellowjacket` — the **release** id — while `run` and
+> `run:device` build the **debug** variant, whose id is
+> `app.yellowjacket.dev`. So they uninstalled the user's app, taking
+> the library with it, installed a different package, and then failed
+> to launch the one they had removed.
+>
+> They share `scripts/android-deploy.sh` now, which **never**
+> uninstalls (`install -r`, and a changed signing certificate is
+> reported with the command rather than acted on), reads the package id
+> back out of the built APK, and refuses a target that is not the kind
+> the task names. There is nothing left to avoid; the manual sequence
+> below is kept because it is still the smallest thing that works.
+
 ```
 wails3 task android:run              # debug build + emulator install + launch
-wails3 task android:run:device       # same, first connected physical device
-wails3 task android:deploy-device    # production APK to a device
+wails3 task android:run:device       # debug build + install + launch on a phone
+wails3 task android:deploy-device    # release build, same
 wails3 task android:bundle:fat       # AAB, for a Play Store upload
 wails3 task android:studio           # open build/android/ in Android Studio
 wails3 task android:device:list
@@ -260,6 +284,16 @@ wails3 task android:logs:all
 wails3 task android:clean
 ```
 
+**`run` and `deploy-emulator` mean the emulator, and now say so to
+adb.** They used a bare `adb install`, which with exactly one device
+attached picks that device whatever it is — so with a phone plugged in
+and no emulator running, the task whose summary reads "in the Android
+Emulator" installed on the phone. They pass `--target emulator` and
+refuse with `make android-emulator` as the remedy.
+
+**`DEVICE_ID=<serial>` still names a device, and several attached
+devices is now an error rather than a silent pick of the first.**
+
 Two are deliberately **not** wrapped. `android:logs` greps logcat for
 `(Wails|yellowjacket)`, which catches the `WailsBridge` tag but misses
 the app's own process tag (`app.yellowjacket` — lowercase, so `Wails`
@@ -269,16 +303,51 @@ instead. And `ensure-emulator` boots whatever `-list-avds | tail -1`
 returns, with no pidfile and no boot wait, so it cannot be stopped or
 sequenced.
 
-## The identity is declared twice
+## The identity is read back from the APK
 
+It used to be **declared twice**, and that is what #159 was.
 `applicationId` in `build/android/app/build.gradle` is what Gradle
-installs. `APP_ID` in `build/android/Taskfile.yml` is what every
-adb-driven task uninstalls, launches and filters. **Nothing enforces
-that they agree**, and `ANDROID.md`'s advice to set `APP_ID` in
-`build/config.yml` does not work in beta.8 — `wails3 task` never reads
-that file (verified with `--dry`), and even when set it feeds only the
-adb commands, never Gradle. Change both or the official `run`/`deploy`
-tasks address a package that is not installed.
+installs; `APP_ID` in `build/android/Taskfile.yml` was what every
+adb-driven task uninstalled, launched and filtered, and nothing
+enforced that they agree. They did not: the debug buildType carries
+`applicationIdSuffix ".dev"`, so every task that assembles a debug APK
+addressed the release id. This file flagged the hazard for five phases
+and it cashed out twice — once as a wrong `am start`, once as an
+uninstall of the user's library.
+
+**`scripts/android-pkgid.sh` is the one answer now.** It prints the
+package id an APK declares (`aapt2 dump packagename`, falling back to
+`aapt dump badging`), and the deploy path installs and launches *that*.
+The APK is the authority because the task that installs it has just
+built it: whatever Gradle resolved the applicationId to, suffixes and
+flavours included, is in the file, and no default can disagree with it.
+An APK it cannot read is a hard failure, never a fallback to a written
+down default — guessing is the bug.
+
+**`APP_ID` survives as an assertion, not a setting**, and has no
+default. `wails3 task android:run APP_ID=app.yellowjacket` says "this
+build had better declare that id" and is refused, naming both, *before*
+anything is installed or a device is even chosen. It could never have
+been a setting: `ANDROID.md`'s advice to put it in `build/config.yml`
+does not work in beta.8 — `wails3 task` never reads that file (verified
+with `--dry`) — and even when set it fed only the adb commands, never
+Gradle.
+
+`scripts/android-emulator.sh` derives `PKG` the same way, from
+`bin/yellowjacket.apk` when one is built, so `make android-install`,
+`android-launch`, `android-logs` and `android-smoke` follow whichever
+variant is actually in `bin/`. `YJ_ANDROID_PKG` still overrides, and
+the old literal survives only for a tree with no APK built yet.
+
+**The uninstall is gone and is not coming back.** It existed to make
+the bare `install` on the next line work at all — without `-r` Android
+refuses an install over an existing package — so `install -r` removes
+the *reason* for it rather than merely removing it. What is left is the
+one case an uninstall really is the remedy, a changed signing
+certificate, and that is exactly the case where performing it silently
+costs the user their library. So it is named and not done, which is the
+answer `scripts/android-emulator.sh` had already reached for
+`make android-install`.
 
 Related, and it will bite once: the launcher activity is
 `com.wails.app.MainActivity` and the applicationId is
@@ -287,6 +356,27 @@ resolves the leading dot against the *applicationId* and fails with a
 class-not-found that reads like a broken build. Always the
 fully-qualified form.
 
+**`wails3 task android:run:device` is the way to put a debug build on a
+real device**, since #159. What #52 used, before it was safe, was the
+longer form, and it is still the smallest thing that works if you want
+no script between you and adb:
+
+```bash
+wails3 task android:build ARCH=arm64 && wails3 task android:assemble:apk
+adb install -r bin/yellowjacket.apk      # -r, never uninstall
+adb shell am start -n app.yellowjacket.dev/com.wails.app.MainActivity
+```
+
+The id in that last line is the one thing to keep an eye on by hand —
+`./scripts/android-pkgid.sh bin/yellowjacket.apk` is what the tasks ask,
+and it is a good habit before any `am start` written out in full.
+
+`YJ_ANDROID_PKG=app.yellowjacket.dev` still overrides what
+`scripts/android-emulator.sh` — and therefore `make android-smoke`,
+`android-logs`, `android-launch` — addresses, but it is rarely needed
+now: that default is read from `bin/yellowjacket.apk`, so it already
+follows whichever variant was built last.
+
 ## What only a device can answer
 
 The emulator cannot run this app (three separate reasons, none of them
@@ -311,6 +401,91 @@ system bars, the back gesture, focus and audio interruptions,
 permission dialogs, the keyboard — not about what the app draws. The
 drawing is what the other five tiers already cover.
 
+**The third such fault was the activity lifecycle** (#52), and it is
+the one to re-check after touching `main()`, `WailsBridge` or
+`MainActivity`. Android destroys and recreates an activity **without
+restarting the process**, and Wails' `nativeInit` — which
+`MainActivity.onCreate` calls — runs `go mainFunc()` every time. So
+Go's `main()` ran again on a live app, `app.Run()` refused (`a.starting`
+is still true behind Android's `select{}`), and the `os.Exit(1)` under
+it took the healthy first app down with it.
+
+### The lifecycle check, and how to trigger it on demand
+
+This is the regression guard for #52 on this tier, because no other
+tier runs `main()` on Android at all. The Go-side guard
+(`TestMainClaimsBeforeItDoesAnything`) catches work creeping above the
+latch; only the device catches the latch not working.
+
+**Trigger a relaunch with a configuration change the manifest does not
+declare.** `AndroidManifest.xml` lists
+`orientation|screenSize|keyboardHidden|uiMode`, so those are handled
+in-place and are *not* triggers. `fontScale` is not listed, and it is a
+one-liner:
+
+```bash
+adb shell settings put system font_scale 1.15   # restore the old value after
+```
+
+That is the same in-process destroy/recreate that "Don't keep
+activities", a locale change and a memory trim produce, but on demand.
+
+**"Don't keep activities" is the report's own lever and did not work on
+this device**: `settings put global always_finish_activities 1` reads
+back as `1`, `am set-always-finish-activities` does not exist on this
+build, and the activity was never finished on backgrounding. Do not
+spend an afternoon on it; use the config change.
+
+**The assertion is the pid, and the tell is two bridge inits in one.**
+
+```bash
+adb logcat -d | grep -E "Wails bridge initialized|has died|finishDrawing of relaunch"
+```
+
+Healthy is one pid appearing twice — the process surviving the
+recreation:
+
+```
+I/WailsBridge(28420): Wails bridge initialized
+I/WailsBridge(28420): Wails bridge initialized     <- same pid, recreated
+```
+
+Broken is that pair followed within a second by:
+
+```
+I/WindowManager: finishDrawing of relaunch: Window{...MainActivity} 603ms
+I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
+W/ActivityTaskManager: Force removing ActivityRecord{...}: app died, no saved state
+```
+
+Two things about reading that. **`has died: fg  TOP` is not a memory
+kill** — the system does not reclaim the foreground process, so this is
+the app leaving of its own accord. And there is **no crash record
+anywhere**: `logcat -b crash` is empty, no `AndroidRuntime`, no
+`libc: Fatal signal`, no tombstone. That is the `os.Exit` signature,
+and it is why "the system killed it" is the wrong first hypothesis.
+
+**Surviving is only half of it — check the recreated WebView is still
+wired to the running app.** A plausible-looking fix (making
+`WailsBridge.initialized` static, so the second `nativeInit` is skipped)
+keeps the process alive and silently breaks this, because `nativeInit`
+is also what re-points the JNI reference at the new bridge. Go would go
+on executing JavaScript against the destroyed activity's WebView: the
+app opens, renders, and never receives another backend event.
+
+Ask the page, after a relaunch and a resume:
+
+```bash
+make android-inspect
+make android-eval EXPR='(()=>{window.__probe=[];const o=window._wails.dispatchWailsEvent.bind(window._wails);window._wails.dispatchWailsEvent=(e)=>{window.__probe.push(e&&e.name);return o(e)};return "ok"})()'
+# background and foreground the app, then:
+make android-eval EXPR='JSON.stringify(window.__probe)'
+```
+
+A healthy build answers with events from the live services —
+`["IndexStatusChanged","JobsChanged","JobsChanged","android:storageAccess"]`.
+`[]` means the bridge reference is stale.
+
 ## Asking the device, not just looking at it
 
 A real phone can be inspected, and that turns this tier from "reported
@@ -340,6 +515,75 @@ Four things about it, each of which costs an hour if met cold:
   script. Plug in over USB for anything longer than a couple of probes.
 - **The socket name carries the pid**, which changes on every launch, so
   it is resolved rather than remembered.
+- **A reinstall resets the runtime permissions**, and the grant dialog
+  is a separate activity that takes focus — so the app is up, `am start`
+  reports "delivered to currently running top-most instance", and
+  `pidof` is empty because it never got to the foreground.
+  `dumpsys window | grep mCurrentFocus` naming
+  `GrantPermissionsActivity` is the tell. `adb shell pm grant
+  app.yellowjacket.dev android.permission.READ_MEDIA_AUDIO` (and
+  `POST_NOTIFICATIONS`) ahead of the launch skips it.
+
+### Calling a binding on the device
+
+**The runtime call does not go over HTTP on Android**, and this is worth
+knowing before an hour is spent on it. The WebView cannot deliver a
+`fetch()` POST body to `shouldInterceptRequest`, so v3 routes runtime
+calls through the `addJavascriptInterface` bridge instead: the
+@wailsio/runtime installs a `customTransport` that calls
+`window.wails.invokeAsync(id, payload)` and receives the answer on
+`window._wailsAndroidCallback`. Two consequences:
+
+- **`.playwright/init-events.js` does not transfer to the device.** Its
+  outbound half hooks `fetch`, which sees nothing here, and its
+  `call()` posts to `/wails/runtime`, which answers
+  `Invalid runtime call: missing object value` — the interceptor got the
+  URL with no body. Its *inbound* half is still right, because
+  `dispatchWailsEvent` is the entry point in every mode.
+- **Hooking `fetch` from an eval is too late anyway**, on any platform:
+  the bundle captured its reference at module scope, so a wrapper
+  installed afterwards records nothing. That is why the harness is an
+  `initScript` and not a step in a spec.
+
+What works is to borrow the bridge, chaining the runtime's own callback
+so its pending calls still resolve:
+
+```js
+const pending = new Map();
+const prev = window._wailsAndroidCallback;
+window._wailsAndroidCallback = (id, response, error) => {
+  if (!pending.has(id)) return prev && prev(id, response, error);
+  const p = pending.get(id); pending.delete(id);
+  const env = JSON.parse(response || "{}");
+  return env.ok ? p.resolve(env.data ?? env.text) : p.reject(new Error(env.error));
+};
+window.__yj = { call(name, args) {
+  return new Promise((resolve, reject) => {
+    const id = "yj" + Math.random().toString(36).slice(2);
+    pending.set(id, { resolve, reject });
+    window.wails.invokeAsync(id, JSON.stringify({
+      object: 0, method: 0, windowName: "",
+      args: { "call-id": id, methodName: "yellowjacket/backend/" + name, args: args || [] },
+      clientId: window._wails.clientId,
+    }));
+  });
+} };
+```
+
+That turns the device into a tier that can be *driven* rather than only
+looked at — `__yj.call("player.Player.LoadFile", [path])` and
+`__yj.call("library.Library.AddLibrary", ["/sdcard/Music/..."])` are how
+#53 was measured. Names are the Go ones (`GetTracks`, not
+`GetAllTracks`); an unknown one comes back as a plain
+`unknown bound method name`, so a wrong guess is loud.
+
+**Getting audio onto the phone**: `adb push` into
+`/sdcard/Android/data/<pkg>/files/` looks like it works and then the
+files are not there — scoped storage. `/sdcard/Music/...` plus
+`pm grant … READ_MEDIA_AUDIO` does work, and `AddLibrary` takes the
+plain path. The generated fixtures are **~2 seconds** each, which is
+fine for a scan and useless for watching a seek bar, so synthesise a
+long one: `ffmpeg -f lavfi -i sine=frequency=440:duration=240`.
 
 **And the reason to bother: the phone is an engine, not a screen.** The
 first device here renders in **Chrome 113** at 424x439 CSS px. Every

.planning/NOTES.md

@@ -3483,3 +3483,870 @@ 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.
+
+## The queue panel was a column that could not afford to be one (measured 2026-08-19)
+
+Plan 018, issue #24. Measured against the running app (`make
+dev-headless SEED=default`, Chromium) on Playlists, sweeping the
+viewport with the queue open and closed. Main panel width, and how much
+of the page header survived:
+
+| viewport | sidebar | main (queue open) | actions clipped |
+|---|---|---|---|
+| 1280×800 | 200 | 759 | — |
+| 1000×700 | 200 | 479 | 2 of 3 |
+| **900×600** | 200 | **379** | all three |
+| 800×600 | 56 | 423 | all three |
+| 390×780 | — | **69** | all three |
+| 320×600 | — | **0** | all three |
+| 800×600 | 56 | 744 *(closed)* | New Smart Playlist, 158/162px |
+
+Five things came out of it that the issue did not say.
+
+- **The header clips at the enforced minimum with the queue closed.**
+  800×600 is the only size this app promises, and "New Smart Playlist"
+  loses 4px of its 162 there. The queue makes it dramatic; it is not
+  the cause.
+- **900×600 is worse than 800×600.** `AUTO_COLLAPSE_VIEWPORT` collapses
+  the sidebar *below* 900, so the main panel is 843px at 899 and 700px
+  at 900. **The worst desktop case is the top of the Compact band, not
+  the enforced floor** — so every viewport list that stopped at "the
+  minimum" was missing its own worst case. `layout-overflow.spec.ts`
+  carries 900 now.
+- **At 320px the main panel was 0px.** The panel is `flex-shrink: 0` in
+  the flow of `.content-area`, so an open queue is paid for by the
+  content rather than covering it. Not degraded — gone. That is the
+  measurement #55 wanted and did not have.
+- **Only Playlists overflows.** All ten primary views swept at 900×600
+  and 390×780; every other header reports `scrollWidth ==
+  clientWidth`, and Albums at 390 renders title, count and sort legibly
+  (checked on a screenshot, not just the number). So #69 is one view's
+  action set — three text buttons totalling 390px — and not a systemic
+  header failure.
+- **Both reasons in `MinWidth`'s comment had expired.** The subtitle is
+  `display: none` from 899 down, and the sidebar host is
+  `overflow-y: auto` (at 600×460, `scrollHeight` 434 against a 332px
+  client, Settings reachable after scrolling). The floor is right; its
+  stated defence was two mechanisms that can no longer happen, which is
+  worse than either answer because nobody can argue with it.
+
+**A correction worth keeping, because it nearly went in the plan.** My
+first probe for the sidebar's scroller searched
+`shadowRoot.querySelectorAll('*')` and reported "no scroller — items
+are unreachable", which reads exactly like a live Settings-unreachable
+bug. The scroller is the **host**, and a host is not inside its own
+shadow root. CLAUDE.md was right and the probe was wrong.
+
+**And one claim in the plan's first draft was too strong**: that the
+overlay "removes the desktop half of #69". After phase 2, at 900×600,
+open and closed are now *identical* (main 700, one action clipped)
+where open used to be main 379 with all three clipped. The queue's
+contribution is gone; the header's own overflow remains and is still a
+live defect at a supported size.
+
+### The mode cannot be a media query
+
+The panel is drag-resizable 200–500px and persisted, so a viewport
+breakpoint assumes the default 320 and is wrong by up to 180px for a
+user who widened it — in the direction that hurts, since a wider queue
+is exactly when the content can least afford it. It is computed from
+`.content-area`'s width instead (which already accounts for the
+sidebar's collapse), and the component test that matters widens the
+panel at a *fixed* parent width and asserts the flip.
+
+The floor (480) is a judgement, and the measurement is why: there is no
+cliff. The track list rescales its columns continuously — 213px down to
+124px between main widths of 900 and 544, `rowOverflow=0` at every step
+— and the album grid steps 3 columns to 2 somewhere between 564 and 644
+without breaking. So 480 is anchored at both ends instead: it keeps the
+default 1100px window inline, and puts every measured-broken case on
+the overlay side.
+
+The scrim is perceptible but subtle on a dark ramp, which is worth
+knowing before someone "fixes" it as broken: sampled from screenshots at
+900×600, the main panel's background goes 33,37,41 → 18,20,23 and a
+row's text 242 → 133. It covers the content area only — not the sidebar
+or the transport — because the queue is not modal.
+
+## No test tier can see a `hover:` media query (measured 2026-08-19)
+
+Gating an affordance on `(hover: hover) and (pointer: fine)` — #68's fix
+for the play button that flashed on a long-press — is invisible to both
+browser tiers, in *different* ways, and neither of them fails.
+
+- **`make ui-test`**: CDP's `Emulation.setEmulatedMedia` with a `hover`
+  feature does not reach the tier's iframe. The call succeeds and
+  `matchMedia('(hover: hover)')` still answers `true` afterwards. So
+  there is no way to render a component as a phone would and read the
+  computed style.
+- **`make e2e`**: both projects are desktop (`Desktop Chrome`,
+  `Desktop Safari`), and the phone specs reach phone *width* with
+  `setViewportSize`, which changes no media feature but `width`. So the
+  phone specs run with `hover: hover` and the gate is never exercised.
+
+What does work, and what the fix was verified with, is a second browser
+context under a device descriptor: `chromium.newContext(devices['Pixel
+5'])` reports `hover=false pointer:fine=false` and the button computes
+`display: none`, against `flex` at 1440px. That is a one-off script, not
+a spec — `isMobile` is Chromium-only, so it cannot become an e2e project
+without losing the WebKit half.
+
+`hover-affordance.test.ts` therefore asserts the *parsed stylesheet* —
+that the reveal rule sits inside the media query — which catches the
+regression that actually threatens it: someone hoisting the rule back out
+as a tidy-up, a change nothing on a desktop renders differently.
+
+Related: a width-gated decision **is** testable at both tiers, which is
+why #61's phone mini player is a `matchMedia` stub in the component test
+and needs nothing special.
+
+## A default that is an *absent* key survives an existing seed (2026-08-19)
+
+The skill warns that a seed freezes every default it has already
+persisted, so changing one in `backend/config` is invisible against an
+existing `YJ_HOME` while CI, which seeds by running the app, tests the
+new one. That warning is about defaults stored as *values*.
+
+#25's Autotag-hidden default is stored as the **absence of a key**:
+`GeneralConfig.ViewVisibility` is a map, an id it does not mention takes
+`backend/config.Views`' answer, and only what the user changed is ever
+written. So a seed built before the feature existed showed the new
+default immediately — verified against `.dev/seeds/default.tar`, whose
+`config.toml` has no `[General.ViewVisibility]` table at all, and whose
+sidebar came up without Autotag on the first launch of the new binary.
+After toggling it on and off again the file carries exactly one line,
+`autotag = false`.
+
+The general form is worth keeping: **a default expressed as a zero value
+needs a re-seed to observe; a default expressed as an absent key does
+not**, and it needs no migration for existing installs either. It is the
+same property that makes removing a view later free (an unknown key is
+dropped on load), which is what the `#25 → #27` ordering on #73 rests on.
+
+## A spec cannot assume a destination has a nav item (2026-08-19)
+
+Since #25, `getByTestId('nav-<view>')` is not a reliable way to reach a
+view: Autotag is hidden by default and Downloads is absent without a
+download client, so four existing specs failed on a 30 s timeout waiting
+for a locator that will never resolve. `navigateTo(page, view)` in
+`e2e/support/fixtures.ts` dispatches the app's own `navigate` event
+instead, which is what every nav item, card and detail view dispatches —
+so it is the mechanism and not a test-only door.
+
+Use the nav item when the *nav* is the subject, and `navigateTo` when
+the view is.
+
+## `config-section .header` is ambiguous once a job exists (2026-08-19)
+
+#27 embeds `<job-panel>` inside four Settings sections, and a panel with
+any job in it also mounts a `job-details-drawer` — whose own header
+carries the class `.header`. So `config-page config-section .header`,
+which `settings-reach.spec.ts` had used since plan 007, resolves to two
+elements and fails Playwright's strict mode the moment a scan has run.
+
+Two things follow. A spec asserting on a section's *disclosure* should
+locate it by role and name (`getByRole('button', {name: heading})`) or
+scope per section and take `.first()`, not by that class. And this is a
+worked example of the more general trap: a class name is not a
+selector's contract, and a component that embeds another inherits its
+class names into every ancestor query.
+
+It also only appears in a suite that has *done* something — the
+sections are empty on a fresh app, so this cannot be reproduced by
+opening Settings and looking.
+
+**And it appears on the second engine, not the first.** CI runs
+chromium then webkit against **one app**, so a spec that scans in the
+chromium pass leaves a finished job the webkit pass then trips over.
+Three specs used that selector; two failed locally and the third
+(`failure-voice.spec.ts`) was green on chromium and red on webkit in
+the same run. Reproducing it locally is running the suite twice against
+one `make dev-headless` — which is worth doing for any change that
+leaves state behind, since it is the only place a cross-engine order
+dependency shows up.
+
+## `scrollWidth` counts the left padding and not the right (measured 2026-08-20)
+
+The obvious predicate for "does this flex row fit" is
+`el.scrollWidth <= el.clientWidth`, and on a box with symmetric gutters
+it **under-reports by one gutter**. `scrollWidth` is the extent of the
+scrollable content area, which includes `padding-left` and excludes
+`padding-right`; `clientWidth` includes both. So a child may end up to
+`padding-right` past where content is allowed to go while the box
+reports a perfect fit.
+
+Measured on the top bar (`padding: 0 2em`) at 700x600 with a long-titled
+scan staged: `clientWidth 700`, `scrollWidth 700` — and
+`job-indicator`'s right edge at 700 against a content edge of 668, i.e.
+sitting in the whole right gutter. `#143`'s first fix passed its own
+measurement and left the indicator visibly jammed against the window
+edge.
+
+The predicate `services/top-bar-fit.ts` uses instead is the one its
+spec asserts: no in-flow child's rect outside the parent's *content*
+box, both edges, with half a pixel of slack for fractional flex widths.
+
+This is the same family as #69's title trap — the measurement easiest to
+reach for is the one that cannot see the failure — and it is worth
+knowing before writing the next one of these: **the fit test and the
+assertion that proves it should be the same test.** It was found only
+because `top-bar-fit.spec.ts` measures per child rather than asserting
+on the container, which is exactly why #69 needed
+`header-action-overflow.spec.ts`.
+
+## The top bar's overflow is 11px idle and 262px while working (measured 2026-08-20)
+
+#143 was filed as "11px at 600x600" and re-measured as 171. Both are the
+same defect seen with different jobs running: `job-indicator` is
+`hidden` when idle, ~144px wide showing "Scanning Music", and **235px**
+showing a real library's scan title ("Scanning Music from the external
+drive"), because the label is capped at 12rem and gets there.
+
+Swept against the running app with that job staged, `header.top-bar`
+client vs scroll:
+
+| width | idle | with the long-titled scan |
+|---|---|---|
+| 320, 390, 599 | fits | fits (the phone rules drop the filter and the label) |
+| 600 | 611 | **862** |
+| 700 | fits | 862 |
+| 800 | fits | 862 |
+| 899 | fits | 899 (fits) |
+| 900 | fits | 946 |
+| 1100, 1440 | fits | fits |
+
+Two things worth keeping. The band is **600–610 idle and 600–900 while
+working**, so "a narrow corner" and "the header is crowded from 900
+down" are both true and the difference is entirely what is in flight —
+which is the case a seeded, settled app can never show you. And 899
+fits while 900 does not, because `nav-history` appears at 900: the worst
+width for the header is not the narrowest one, the same way 900 rather
+than 800 is the worst width for the content area.
+
+Staging it is `/__test/emit` with a `JobsChanged` snapshot; a job with
+`state: "running"` never completes, so it stays up until an empty
+snapshot is emitted, which is what makes an idle re-measurement look
+like the fix not working.
+
+## Two repaint mechanisms, and neither is pinned alone (measured 2026-08-20)
+
+`CLAUDE.md` already states the rule — *a virtualized list repaints only
+when you tell it to, and the accidental way you were telling it may be
+the thing you are about to delete* — found in `artists-view` and
+`genres-view`. `queue-panel` is a second instance with numbers, and the
+numbers are the part worth keeping.
+
+It repaints its rows **two** ways:
+
+- `onSelectionChanged()` calls `virtualizer.requestUpdate()`, which is
+  the intended one and the one `track-list` has always had;
+- `.keyFunction=${(track) => track.id}` is a **per-render arrow**, so it
+  is a changed property on every host update and repaints the rows by
+  itself.
+
+Removing *either* alone changes nothing observable. That is why #43
+could not be settled by reading the code: the hypothesis in its Findings
+(the repaint is missing) was checkable, false, and would have looked
+identical either way.
+
+Removing **both** does not break selection either — it delays it. Time
+from click to `aria-selected`, three clicks each:
+
+| build | ms to highlight |
+|---|---|
+| healthy | 5, 16, 17 |
+| both mechanisms removed | 134, 3,866, 5,816 |
+
+The highlight arrives on whatever unrelated render happens next (the
+player's 1 Hz position report is the usual candidate). **Four seconds is
+indistinguishable from broken to a user, and invisible to a spec** —
+`expect.poll`'s default 5 s timeout passes the degraded build on every
+assertion. `queue-selection.spec.ts` bounds its selection assertions at
+500 ms for that reason, which is ~30x the healthy case and an order of
+magnitude under the degraded one.
+
+The general form, for the next spec about anything push-driven: **a poll
+generous enough to be stable is generous enough to miss a latency
+regression entirely.** If "late" is a failure mode worth having, the
+timeout has to say so.
+
+## A hit-scan says how much of a row is not selectable (measured 2026-08-20)
+
+`explore-link` stops the click's propagation on purpose — "the row must
+not also treat it as a selection" — so a click on a track, album or
+artist *name* navigates and selects nothing. That is app-wide and
+deliberate, and the useful question about any given list is how much of
+its row it costs.
+
+Asking `elementFromPoint` what is under each x across a row, at three
+heights:
+
+| list | link coverage |
+|---|---|
+| queue panel | 12% |
+| track list | 21% |
+
+This killed a fix in progress. #43 reads as "selection is broken in the
+queue panel, and fine in the track list", the obvious mechanism is that
+the queue's narrow rows are mostly name, and it is **wrong**: the panel
+is *less* link-covered than the list it is being compared against. The
+scan takes a minute and is worth running before demoting anybody's links
+— `explore-album-details`'s tracklist (number / title / artist /
+duration) is the one that plausibly *is* mostly link, and is the one
+#5 is about to add selection to.
+
+## A layout is still moving when a guard says it has arrived (measured 2026-08-20)
+
+`album-dropdown.spec.ts` failed with `Expected 80, Received 10` twice
+over two sessions, and #133 already strengthened its guard from
+"scrollable at all" to "has at least the range the assertion needs".
+That was necessary and could not be sufficient, and the reason is
+structural rather than a matter of thresholds: **a guard and the write
+it guards are separate CDP round trips**, so the page is free to
+re-lay-out between them. Polling harder cannot close a window between
+two moments; only removing the window can.
+
+Measured directly, sampling `scrollHeight - clientHeight` on
+`.grid-scroll-container` every frame across a 1440x900 → 900x600 resize,
+three runs:
+
+| t (ms) | range |
+|---|---|
+| 0 | 0 |
+| 1 | **88** |
+| 8–14 | 330 (settled) |
+
+88 satisfies a guard asking for 80 and is not the settled value, so the
+guard can pass while the grid is one layout pass from done. Under
+full-suite load the transient is worse — the observed failure had 10 —
+which is why it shows up on the second run of a suite and not in ten
+consecutive runs of the file alone (0/10 both before and after the fix).
+
+The shape to write instead: **one page-side call that performs the
+action and returns what it observes**, with `expect.poll` retrying
+*that*. `scrollTo()` sets `scrollTop` and returns `scrollTop`, so the
+assertion is about what the grid did rather than about what it was
+ready to do. `layout-overflow.spec.ts`'s sidebar probe already had the
+fused half and was missing the retry; it has both now.
+
+Worth generalising: a spec that resizes and then measures is asserting
+about a moving target for the next dozen frames. Fuse, then poll.
+
+## "The first N tracks" is not a way to ask for an ordinary one (2026-08-20)
+
+`queue-selection.spec.ts` staged its queue from the first few rows of
+`library.Library.GetTracks(0)` and clicked a track *name*, which
+`explore-link` routes to that track's **album** page. Four tracks in the
+fixture library have no album at all — `01 Tone A`, `02 Tone B`,
+`Title Only`, `no-tags-at-all` — and a name with nothing to route to
+renders as **plain text**, not as a link.
+
+Two things follow, and the second is the sharper one.
+
+**The order is the scan's.** `GetTracks` returns `audio_files.id` order,
+i.e. the order the scan inserted rows, which depends on concurrency and
+directory traversal. Locally the first eight are all from two proper
+albums, so the spec passed twice over; CI rebuilds its seed with a real
+scan, got a different eight, and failed on both engines. This is the
+same family as "a seed freezes every default it has already persisted" —
+the fixture library is not a list, it is a *set* with an incidental
+order, and no spec should depend on that order.
+
+**A loose locator hid it.** The row was located with
+`.locator('.explore-link').first()`, and a row has two — the title and
+the artist. When the title is plain text, `first()` silently resolves to
+the **artist** link, so the click went somewhere real and the assertion
+was about a destination the test had not exercised. `.track-title
+.explore-link` is the locator that says which one it means; the loose
+one turned a fixture problem into a mystery.
+
+The general rule for this repo's fixture library: it is deliberately
+full of edge cases (untagged, unicode, duplicates, extremes), so a spec
+that wants an *ordinary* track has to **say so** — filter on the
+property it depends on rather than slicing.
+## A nested rule starting with an element name is dropped on the phone (2026-08-20)
+
+`CLAUDE.md` records that the device renders in **Chrome 113**, which
+does not have relaxed CSS nesting (Chrome 120). The consequence is
+sharper than "some syntax is unavailable": a nested rule whose selector
+begins with a bare identifier is not a parse error you would notice, it
+is **silently dropped**.
+
+Three such rules were live in `frontend/index.css`, all inside
+`.bottom-bar`, and all therefore dead on the phone and only on the
+phone:
+
+```css
+.bottom-bar {
+    #track-info { p { … } }   /* the metadata's ellipsis */
+    now-playing { overflow: hidden; }
+    audio-player { margin: 0.5em 1em; }
+}
+```
+
+The first is the interesting one: it is the *ellipsis* on the bottom
+bar's track title and artist, so on the device that text has never
+truncated — the same class of fault as `now-playing`'s marquee, whose
+`text-overflow` sat on the wrong box and had never produced an ellipsis
+in any mode. Both are invisible to every assertion and visible in a
+screenshot.
+
+`& p`, `& now-playing`, `& audio-player` are valid in both, so the fix
+is one character per rule. What is worth keeping is the rule of thumb:
+**inside a nested block, always write `&`** — and note that a rule
+inside `@media` is *not* nested, so `@media … { bottom-nav { … } }`
+elsewhere in that file is fine and needs nothing.
+
+`make css-check` does not catch this (it looks for backticks that end a
+tagged template early). Filed as an issue: the check is the natural
+place for it, being the same shape of trap — a silent, phone-only,
+screenshot-only failure.
+
+## Centring a bar costs the control in the middle of it (measured 2026-08-20)
+
+#23 asks for the transport centred in the bottom bar. The obvious
+implementation — make the outer two grid tracks the same width, so the
+middle is centred by construction — is right, and the first cut of it
+was a regression, because "the same width" was taken to mean *the
+metadata's* width on both sides.
+
+Measured at 800px, with the seek bar's own track:
+
+| layout | seek track | transport column |
+|---|---|---|
+| `320px 1fr auto` (before) | 257 | 407 |
+| both sides `--now-playing-width` | **61** | 179 |
+| both sides `min(--now-playing-width, 25%)` | 246 | 364 |
+
+At 200% text the middle row is worse still: 130 before, **0** with the
+uncapped sides. Centring is free at 1440 and expensive at 800, so a
+change checked only at a comfortable width looks perfect.
+
+The general form: **a symmetric layout reserves space on the side that
+does not need it.** The right-hand group here is ~141px (volume plus
+the queue button) and was being given 320 to keep the arithmetic
+symmetric. Cap the side tracks against the *bar*, not against their
+content, and the middle gets the difference.
+
+The spec that pins this is two assertions, not one, and that split is
+deliberate: an uncapped build is *perfectly centred* and fails only the
+seek-bar width, so a spec asserting centring alone would have passed
+the regression.
+
+## The phone's way into Now Playing was under the artwork (measured 2026-08-20)
+
+`phone-shell.spec.ts`'s "opens the full-screen now playing" failed in CI
+on both engines, three times across two branches that could not have
+caused it, and passed on re-run each time. It was filed as a flake
+(#150). It is not one: **it depends on which track is playing.**
+
+`.expand` — the phone's only route into `<now-playing-view>` — is
+`position: absolute; inset: 0` inside `.cover-art-wrapper`, and
+`.cover-art` is a **later sibling**. Both have `z-index: auto`, so they
+tie on paint order and the later one wins. With an `<img>` that costs
+nothing; with no artwork the placeholder `wa-icon` renders and takes
+every click aimed at the button underneath it.
+
+Measured at 390px with `elementFromPoint` at the button's centre:
+
+| playing track | hit test |
+|---|---|
+| has artwork | `button.expand` |
+| no artwork | **`wa-icon`** |
+| no artwork, with `z-index: 1` | `button.expand` |
+
+So on a phone, the only way into the full-screen player stopped working
+whenever the current song had no cover — and this has nothing to do with
+the fixture: any library has untagged files.
+
+Three things worth keeping.
+
+**"Flaky in CI" was the wrong diagnosis and it cost three cycles.** The
+spec starts the *first* row of the track list, so which track it plays
+is the order the scan inserted rows in — the same root cause as #156,
+one spec over. A test whose subject is a hit test has to *choose* the
+case that breaks it.
+
+**The first two hypotheses were both wrong, and both were plausible.**
+A custom element's upgrade replacing its own contents, and the cover
+preview's `mouseenter` opening a popup under the pointer. Neither
+survived contact with `elementFromPoint`, which took a minute and would
+have saved the other two cycles.
+
+**And the spec that pins it needs the 90-second track**, because a
+2-second one finishes before the assertions run — the trap
+`fixtures.ts` already documents. Note the filter that does *not* work:
+`library.Track.CoverArt` is empty for all 31 fixture rows, so "the
+first track with no cover art" selects nothing in particular. The
+placeholder's presence is asserted instead, which is the property the
+test actually depends on.
+
+## An activity recreation kills the process, deterministically (measured 2026-08-20)
+
+#52's report was "sometimes crashes or restarts when reopened after
+running in the background". Measured on a real device, the *fault* is
+not intermittent at all — only its trigger is.
+
+Device: Light Phone III (TLP301), Android 14 / SDK 34, arm64-v8a,
+WebView **Chrome 113** at 424x439 CSS px. Debug build
+(`app.yellowjacket.dev`), installed beside the released `v0.3.1` with
+`install -r`.
+
+**Conditional on the activity actually being recreated in a live
+process, the process died 8 times out of 8** — 3 by hand, then 5/5 in a
+scripted loop. The runs where it survived were runs where no recreation
+happened (one `Wails bridge initialized` in the log rather than two), so
+they are inconclusive rather than passes; a harness that does not check
+for the second init reports those as green and reads as flakiness.
+After the fix: 5/5 recreations survived, plus 6 background/foreground
+cycles and 3 interleaved recreations on one pid.
+
+The mechanism is three log lines:
+
+```
+12:47:56.159 I/WailsBridge(22956): Wails bridge initialized
+12:48:38.898 I/WailsBridge(22956): Wails bridge initialized   <- same pid
+12:48:39.357 I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
+```
+
+`nativeInit` runs `go mainFunc()` on every activity creation; the second
+`main()` reaches `app.Run()`, which refuses because `a.starting` is
+still true behind Android's `select{}`, and `os.Exit(1)` takes the whole
+process — including the healthy first app — with it.
+
+Four things worth keeping:
+
+- **`has died: fg  TOP` is not a memory kill.** The system does not
+  reclaim the foreground process. This reads as "the OS killed us",
+  which is the wrong hypothesis and the reason the issue sat unverified.
+- **There is no crash record of any kind**: `logcat -b crash` empty, no
+  `AndroidRuntime`, no `libc: Fatal signal`, no tombstone. `os.Exit` is
+  not a crash. The one line that named the fault —
+  `slog.Error("application error", "err", ...)`, carrying
+  `"application is running or a previous run has failed"` — went to
+  `/dev/null`. That is #160.
+- **"Don't keep activities" does not work on this device.**
+  `settings put global always_finish_activities 1` reads back as `1`,
+  `am set-always-finish-activities` does not exist on this build, and
+  the activity was never finished on backgrounding. The report's own
+  suggested lever is a dead end here. What *does* work, deterministically
+  and in one line, is a configuration change the manifest does not
+  declare: `adb shell settings put system font_scale 1.15`
+  (`AndroidManifest.xml` declares `orientation|screenSize|
+  keyboardHidden|uiMode`, so none of those are triggers).
+- **Surviving is only half the property.** The recreated WebView has to
+  still be wired to the running app, which was verified by hooking
+  `window._wails.dispatchWailsEvent` and backgrounding/foregrounding:
+  `["IndexStatusChanged","JobsChanged","JobsChanged",
+  "android:storageAccess"]`. The tempting Java-side fix — making
+  `WailsBridge.initialized` static — passes the pid check and fails
+  this one, because `nativeInit` is also what re-points the JNI
+  reference at the new bridge.
+
+## The Taskfile's device tasks uninstall the released app (2026-08-20)
+
+`android:run:device` builds the **debug** variant
+(`applicationIdSuffix ".dev"`) and then runs
+`adb uninstall {{.APP_ID}}`, where `APP_ID` defaults to
+`app.yellowjacket` — the **release** id. So it deletes the user's
+installed app and its library, installs a different package, and then
+fails to launch the one it removed. `deploy-device` carries the same
+uninstall. Filed as #159; `android-tier.md` had been recommending
+`run:device` as the way onto a device.
+
+This is the hazard that file already names — "The identity is declared
+twice ... **Nothing enforces that they agree**" — reached by a second
+route: the two ids differ not because someone edited one, but because
+the debug buildType suffixes it.
+
+## The uninstall was there to make a bare `install` work (measured 2026-08-20)
+
+Fixing #159 turned up *why* the `adb uninstall` was in all four tasks,
+which the issue does not say and which decides whether it can simply be
+deleted. The line under it was `adb install`, with **no `-r`** — and
+Android refuses an install over an existing package without it. So the
+uninstall was not a deliberate clean-slate step; it was the price of
+the missing flag, paid on every run, and `install -r` removes the
+reason for it rather than merely removing it.
+
+That matters because "should the uninstall go at all" looked like a
+trade — drop it and a signing-certificate change fails with
+`INSTALL_FAILED_UPDATE_INCOMPATIBLE` instead of being handled. It is
+not a trade: nothing else was relying on it. The certificate case is
+reported with the command to run, which is what
+`scripts/android-emulator.sh` already did for `make android-install`,
+so this is one existing judgement applied consistently rather than a
+new one.
+
+## `wails3 task android:run` installs on a phone (measured 2026-08-20)
+
+The emulator tasks (`run`, `deploy-emulator`) used a bare `adb install`
+with no `-s`. adb with exactly one device attached uses that device
+whatever kind it is, so with a phone plugged in and no emulator
+running, the task whose summary reads "in the Android Emulator"
+installed on the phone — and, before #159 was fixed, ran
+`adb uninstall app.yellowjacket` against it first. The reported data
+loss was reachable from the *emulator* task, which is not what the
+issue describes and is worse, because nothing in the name warns you.
+
+Measured after the fix, phone attached and emulator stopped:
+
+```
+$ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk --target emulator
+android-deploy: no emulator target is online.
+    LP3LHMA531900746	device
+    Start one with:  make android-emulator
+```
+
+The general form: **a task that names a target has to say so to adb.**
+The device tasks always filtered on `$1 !~ /^emulator-/`; the emulator
+tasks filtered on nothing at all.
+
+## The package id can be read back, and costs nothing (2026-08-20)
+
+`aapt2 dump packagename <apk>` answers in one word and ~40 ms, from
+`$ANDROID_HOME/build-tools/*/aapt2` (versioned, so resolved not
+pinned); `aapt dump badging` is the fallback for older build-tools and
+is what #159's own measurement used. That is cheap enough to do on
+every deploy, which is what makes "the two ids agree by construction"
+affordable rather than aspirational — the alternative considered was
+giving the debug-flavoured tasks `APP_ID` + `.dev`, which is one line
+and leaves the class of bug alive for the next flavour or suffix.
+
+The guard runs **before** a target is chosen, deliberately: it is a
+question about the artifact, so it can be exercised with nothing
+plugged in, and a build whose id is wrong should be refused whether or
+not there is anything to install it onto. That is what let the negative
+test run safely with the user's phone attached:
+
+```
+$ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk \
+      --target device --expect app.yellowjacket
+android-pkgid: refusing to act on a package this APK does not declare.
+    the APK declares:  app.yellowjacket.dev
+    the task expects:  app.yellowjacket
+rc=2
+```
+
+That is exactly #159's configuration — debug APK, release id, real
+device — refused with no adb call made.
+
+## `make android-emulator`'s boot wait can be satisfied by a phone (2026-08-20)
+
+Noticed while booting the emulator for #159's verification, with a
+phone also attached. `scripts/android-emulator.sh start` reported
+`waiting for boot ok / android 14` about **eight seconds** after
+launching the emulator, which had not appeared in `adb devices` yet —
+`pick_device`'s last resort is "exactly one device online", and at that
+moment the one online device was the phone. So it waited for the
+phone's boot, found it long since booted, and returned. The emulator
+took another ~10 s to come up.
+
+Harmless here (the emulator was up before anything used it) and a
+straightforward race otherwise: `start` should wait for a device that
+is an emulator, not for whatever `pick_device` returns. Filed as #162.
+
+## The Android runtime transport is not HTTP (measured 2026-08-20)
+
+Found while trying to drive the phone for #53. `wails3` routes runtime
+calls through `addJavascriptInterface` on Android, not through
+`/wails/runtime` — the WebView cannot deliver a `fetch()` POST body to
+`shouldInterceptRequest`, which the v3 source says in as many words
+(`application_android.go`, "The Android transport"). The runtime
+installs a `customTransport` over `window.wails.invokeAsync(id,
+payload)` and takes the answer on `window._wailsAndroidCallback`.
+
+Two things follow, and both cost time before the source was read:
+
+- **`.playwright/init-events.js` does not transfer to the device.** Its
+  outbound half hooks `fetch`; a POST to `/wails/runtime` answers
+  `Invalid runtime call: missing object value`, which reads like a
+  wrong payload shape and is actually the interceptor receiving a URL
+  with no body at all. The payload shape was right the whole time. Its
+  *inbound* half is still correct, because `dispatchWailsEvent` is the
+  entry point in every mode.
+- **Hooking `fetch` from an `eval` is too late on any platform.** The
+  bundle captured its reference at module scope, so a wrapper installed
+  afterwards records nothing — which is exactly why the harness is an
+  `initScript`. Measured: zero calls captured while the app was
+  demonstrably making them.
+
+The working recipe is in `android-tier.md`; it chains the runtime's own
+callback rather than replacing it, so its pending calls still resolve.
+This is what makes the device a tier that can be *driven*.
+
+## #53's frontend is byte-identical to the build it was reported against (2026-08-20)
+
+`git diff v0.3.1 HEAD -- frontend/src/components/audio-player/seekbar/
+frontend/src/store/player-store.ts` is **empty**; the whole diff in that
+area is `backend/player/`. The phone carries the released `v0.3.1`, so
+whatever #53 saw, the component was not what changed — and v0.4.0 is
+where the player audit (#122–#127) landed.
+
+Measured on that phone, current `main`, with a synthesised 4-minute
+track: the Now Playing seek bar tracks correctly when mounted
+mid-playback (`seekValue` 28 of 240), when the view is opened before
+playback starts, after a tap on the track, and across an activity
+recreation (same pid, bar resumes at 30 → 35). The issue's stated
+symptom did not reproduce in any of them.
+
+Reverting **only** `backend/player/` to v0.3.1 — the frontend and
+everything else at HEAD — does reproduce a real position defect on the
+same device: six seconds into a 20-second file with no database row,
+played after a 240-second one, the bar read **01:27 of 240**. That is
+#125's stale `trackLengthMs` ("cleared only by UnloadTrack, so a file
+with no row inherited the previous track's duration"), and it is fixed
+at HEAD. Note the *shape* of it: the fraction is roughly right and the
+absolute numbers are wrong, so it presents as a clock that lies rather
+than as a handle that will not move.
+
+The one-line experiment is worth remembering: v0.3.1's `backend/player`
+compiles against HEAD with a single shim
+(`SetPlaybackFinishedHandler` gained a `srcErr error` parameter), which
+makes "did the backend fix cause this" a ten-minute question instead of
+a full checkout.
+
+## An overlay band is not a notification, it is a lid (measured 2026-08-20)
+
+#62 asks for background jobs to become "a notification" on the phone,
+and the app has exactly one notification surface, so the first version
+of the fix put `<job-panel>` in `notification-host`'s band — which is
+`position: fixed` under the header. It renders correctly, it is on top,
+it is inside the viewport, and it is unusable.
+
+At the device's 424x439 viewport a **compact** panel showing two active
+jobs is ~216px — half the screen — drawn over the content, with
+`pointer-events: auto` so it swallows every tap underneath. Nothing in
+the component tier could see it. The e2e suite could: four specs failed,
+and *none* of them was about jobs — two `phone-shell` journeys into the
+full-screen Now Playing and `header-action-overflow`'s phone case, all
+three because the band was intercepting taps meant for the app.
+
+`<job-band>` is in the shell's grid instead, as a row between the top
+bar and the main panel, so it **pushes**. That is #24's one sentence
+("no action is ever unreachable at any supported size") deciding a
+layout question: a band that hides the app in order to say the app is
+busy has traded the popover's fault for a worse one.
+
+Two things fell out of it worth keeping:
+
+- **A finished row in flow is furniture.** The overlay could afford to
+  keep terminal jobs around; a row that holds the content down after
+  the work is done cannot. `job-panel` grew `active-only` for the band,
+  and Settings keeps finished rows because that is where "did the last
+  scan work" is asked.
+- **`job-row` already had the right density.** `variant="compact"` is
+  described in its own source as "the popover density", which is
+  exactly what the band is replacing — 216px against 259px for the
+  same two jobs, and no per-job statistics that a phone has no room
+  for.
+
+## The e2e suite is the tier that sees a shell regression (2026-08-20)
+
+Worth stating because it decided how #62 was verified. The change is
+one component, one stylesheet and one line of `index.html`; `make
+ui-test` (955 tests) passed on the broken overlay version and so did
+`tsc`, `lint` and the whole Go suite. The failure was three specs that
+have nothing to do with jobs, failing on `click()` timeouts.
+
+The corollary for anything that draws over the shell: **run the whole
+e2e suite, not the spec you wrote.** A spec written for a feature
+asserts the feature works; what a new overlay breaks is everything
+else, and only the suite is looking at that.

.planning/plans/completed/018-supported-sizes-and-the-queue-model.md

@@ -0,0 +1,327 @@
+# 018 — Supported sizes, and what the queue panel is
+
+**Issue:** #24 (`Area/Shell-Nav`, `Priority/High`, `Reviewed/Confirmed`)
+**Unblocks:** #55 (queue as a screen) — a real Gitea dependency
+**Relates:** #69 (page-header overflow), #12 (mini-player), #51 (small-screen umbrella)
+**Status:** complete — #24 shipped as PR #132, and the matrix's last
+unkept promise closed with #69.
+
+#73 puts this first in Phase 2 and hangs the rest of the phase off it,
+so the decision has to be written down and arguable before any CSS
+moves. This document is the decision. Everything below the matrix is
+either a measurement or an argument for one of the four choices #24
+asks for.
+
+---
+
+## What is actually wrong, measured
+
+Against the running app (`make dev-headless SEED=default`, Chromium),
+Playlists, sweeping the viewport with the queue open and closed. The
+number that matters is how much of the page header survives.
+
+| viewport | sidebar | queue | main panel | header needs | actions clipped |
+|---|---|---|---|---|---|
+| 1280×800 | 200 | open 321 | 759 | 759 | — |
+| 1000×700 | 200 | open 321 | 479 | 747 | New Playlist, New Smart Playlist |
+| **900×600** | 200 | open 321 | **379** | 747 | **all three** |
+| 800×600 | 56 | open 321 | 423 | 747 | all three |
+| 700×600 | 56 | open 321 | 323 | 747 | all three |
+| 390×780 | — | open 321 | **69** | 747 | all three |
+| 320×600 | — | open 321 | **0** | 747 | all three |
+| 900×600 | 200 | closed | 700 | 747 | New Smart Playlist |
+| **800×600** | 56 | closed | 744 | 747 | **New Smart Playlist (158/162px)** |
+| 320×600 | — | closed | 320 | 747 | all three |
+
+Five things in that table are not in the issue.
+
+**The header clips at the supported minimum with the queue closed.**
+At 800×600 — the size `backend/config/window.go` enforces and the only
+size this app *promises* — "New Smart Playlist" loses 4px of its 162.
+#24 reads as a queue-panel bug; the queue makes it dramatic, but the
+header overflows on its own at the minimum window.
+
+**900×600 is worse than 800×600, because the sidebar expands at 900.**
+`AUTO_COLLAPSE_VIEWPORT` collapses the sidebar to icons *below* 900, so
+at 899px the main panel is 843px and at 900px it is 700px. The worst
+desktop case is therefore not the minimum window; it is the pixel
+immediately above the collapse. Anything that tests "the minimum" and
+stops has not tested the worst case, which is what
+`layout-overflow.spec.ts` does today.
+
+**At phone widths the queue is not a drawer, it is an amputation.**
+`queue-panel`'s host is `flex-shrink: 0; width: 0`, going to
+`width: var(--queue-width, 320px)` under `[open]` — it is *in the flow*
+of `.content-area`, so it takes its width from the main panel rather
+than covering it. At 390px that leaves 69px of the page; at 320px it
+leaves **0px**, and the app is not degraded but gone. This is the
+measurement #55 needs and did not have.
+
+**Only Playlists overflows.** Sweeping all ten primary views at 900×600
+and at 390×780, every other header reports `scrollWidth ==
+clientWidth`, and Albums at 390px renders title, count and sort
+legibly (checked on a screenshot, not just the number). #69 is
+therefore one view's action set — three text buttons totalling 390px —
+and not a systemic header failure, though the *rule* still belongs in
+`page-header`.
+
+**Both reasons in `MinWidth`'s comment are stale.** It says the floor is
+800×600 because "below ~780 the header's subtitle wraps" and "below
+~600 tall the eleven sidebar items no longer fit". The subtitle is
+`display: none` below 900 (index.css), and the sidebar host is
+`overflow-y: auto` — at 600×460 its `scrollHeight` is 434 against a
+332px client, and Settings is reachable after scrolling. Neither
+mechanism can happen any more. That does not mean the floor should
+move; it means its stated reason no longer supports it, which is worse
+than either answer.
+
+*(Care needed: my first probe for the sidebar scroller searched
+`shadowRoot.querySelectorAll('*')` and reported "items are
+unreachable", because the scroller is the **host** and a host is not in
+its own shadow root. The claim in CLAUDE.md is correct.)*
+
+---
+
+## Decision 1 — the supported size matrix
+
+Three bands. Two of them already exist and are already argued; what is
+new is that they are written down as a *promise*, and that the queue is
+part of it.
+
+| band | width | navigation | queue | promise |
+|---|---|---|---|---|
+| **Phone** | < 600 | `bottom-nav` + drawer | overlay, full width | reflows; nothing needs sideways scrolling; fits 320px |
+| **Compact** | 600 – 899 | icon sidebar | overlay + scrim | nothing is clipped or unreachable at any width in the band |
+| **Desktop** | ≥ 900 | labelled sidebar | inline where it fits (see decision 2), else overlay | as Compact |
+
+And one promise across all three: **no action is ever unreachable.**
+That is the sentence #69 asks for and it is the one the matrix exists
+to make checkable.
+
+**400% zoom** keeps the meaning it already has: WCAG 1.4.10 names 320px
+as the reflow target, the phone band covers it, and
+`layout-overflow.spec.ts` already asserts a 320px viewport needs no
+sideways scrolling. What changes is that the *queue* must be part of
+that assertion — it is not today, and with the queue open at 320px the
+main panel is 0px wide, which no current test can see.
+
+**The window minimum stays 800×600**, and its comment gets the real
+reason. The old mechanisms are gone, but the floor is still where the
+Compact band's chrome stops being comfortable, and lowering it would
+mean promising the desktop layout at sizes where only the phone layout
+works. The interesting consequence is decision 4.
+
+---
+
+## Decision 2 — the queue is an overlay when it cannot afford to be a column
+
+**The rule.** The queue panel renders inline — in the flow, as today —
+only while
+
+```
+viewport − sidebar − queueWidth ≥ 480
+```
+
+and as an overlay with a scrim otherwise.
+
+**Why it cannot be a media query**, which is the load-bearing half:
+the queue's width is *user state*. It is drag-resizable between 200 and
+500px and persisted (`--queue-width`, `MIN_WIDTH`/`MAX_WIDTH` in
+`queue-panel.ts`). A breakpoint at a fixed viewport width silently
+assumes the default 320, and is wrong by 180px for a user who has
+dragged the panel wide — in the direction that hurts, since a wider
+queue is exactly when the content can least afford it. So the mode is
+computed from the measured widths and published as an attribute, the
+way `data-active-view` already is, and the CSS keys off that.
+
+**Why 480, honestly.** There is no cliff to derive it from. The track
+list rescales its columns continuously — at main widths from 900 down
+to 544 its `--grid-cols` shrink from 213px to 124px with
+`rowOverflow=0` throughout — and the album grid steps 3 columns to 2
+somewhere between 564 and 644 without breaking. So this is a judgement,
+anchored on two things: it keeps the *default* window (1100 wide, main
+= 580) inline, because the inline queue is a desktop affordance people
+choose and turning it into an overlay for the common case would be a
+regression in feel; and it puts every case measured as broken —
+900×600 at main=379, and every phone width — on the overlay side.
+1024×768 lands at main=504 and stays inline.
+
+**The scrim is the other half of the issue's complaint** ("make the
+queue obviously an overlay *over* the content so it reads as something
+to close"). An overlay queue gets a scrim, closes on scrim click and on
+Escape, and returns focus to `#queue-button`.
+
+**What must not change**: #55's Direction is explicit — one component,
+two mount points, do not fork it. The overlay is a *presentation* of
+the same `queue-panel`, so the roving tab stop, Alt+Arrow reorder, drag
+reorder, selection semantics and the `virtualizer.requestUpdate()` on
+selection and current-track change all come along untouched. This
+decision deliberately stops short of #55's detail-view mount, but it is
+the shape that makes it possible, and it unblocks it.
+
+---
+
+## Decision 3 — #69 is its own PR, and here is the finding that decides it
+
+`page-header` **cannot collapse its own actions**, and that is not an
+effort estimate but a fact about the API. Actions arrive through
+`<slot name="actions">` as arbitrary light-DOM markup — Playlists slots
+a `<div class="header-actions">` of three `<button>`s with click
+handlers, drag handlers and a conditional class. A component cannot
+move another component's light-DOM children into a dropdown and keep
+their behaviour; there is nothing generic to render as a menu item.
+
+So the overflow rule needs an *actions API* — hosts declaring
+`{icon, label, handler, priority}` data that `page-header` can render
+either as buttons or as menu items — which is a change to all three
+hosts that slot actions, not a rule added in one place. That is a
+different piece of work from this one, it is independently verifiable,
+and the desktop half of #69's symptom is removed by decision 2 anyway
+(the queue stops eating the header's width).
+
+It therefore stays #69, gets the finding above recorded on it, and
+follows immediately after this. What *this* plan owes it is the
+promise in the matrix — no action unreachable at any supported size —
+and the measurement that the only offender today is Playlists.
+
+**And the promise is not kept yet, which is the honest version of a
+claim this document made in its first draft.** "Decision 2 removes the
+desktop half of #69's symptom" was too strong. Measured after phase 2,
+at 900×600 on Playlists:
+
+| | before | after |
+|---|---|---|
+| queue open | main 379px, **all three** actions clipped | main 700px, **one** clipped |
+| queue closed | main 700px, one clipped | unchanged |
+
+So the queue's *contribution* is gone — open and closed are now
+identical, which is the whole of what this decision owed — and the
+residual "New Smart Playlist: 114/162px" is the header overflowing on
+its own, at a size the queue never touched. #69 is still a live defect
+at a supported size, and the matrix's promise is what will close it.
+
+---
+
+## Decision 4 — a very small window becomes the phone layout, not the mini-player
+
+#24 asks whether a very small window should switch to the mini-player
+(#12) "or simply refuse to go there". Both options in the question are
+worse than the one the codebase already has.
+
+**#12 is a second window, not a mode.** Its findings say so: v3
+supports multiple windows, `AlwaysOnTop` is a window *option*, and the
+frontend would need an entry branch mounting only the mini-player root
+for a second window loading the same bundle. Turning the main window
+into a mini-player at some width conflates the two: it would throw away
+the user's navigation state on a resize, and it puts the MPRIS question
+(#12's own open question — media controls are process-level and must
+not be per-window) on a code path that a drag can trigger by accident.
+
+**And "refuses" is unnecessary, because the reflow already exists.**
+The phone band is real, tested, and reached by width alone — a desktop
+window narrowed below 600px already gets `bottom-nav` and the phone
+shell. That is a better answer than refusing: it is strictly more
+usable than a hard minimum, it costs nothing new, and it is the same
+code Android runs, so it stays exercised.
+
+So: the main window reflows and never becomes a mini-player; #12 stays
+a separate always-on-top window and is not blocked by, or coupled to,
+this decision. The window minimum stays 800×600 for the reason in
+decision 1 — but the phone band is what happens below it, not a
+refusal, which is why the minimum is a comfort floor rather than a
+correctness one.
+
+---
+
+## Phases
+
+1. **This document**, linked from #24, with the matrix reported on the
+   issue and #55 told whether it is unblocked. *(no code)* — **done**
+2. **The queue's overlay mode** — computed mode attribute, scrim,
+   Escape and scrim-click close, focus return. The inline path is
+   unchanged above the threshold. — **done**
+3. **The window minimum's comment** — replace both stale reasons with
+   the measured ones. No value change. — **done**
+4. **Verification**, below. Including the specs that must change
+   because they assert the old behaviour. — **done**
+
+#69 follows as its own branch; #55 became unblocked at phase 2.
+
+## What landed, measured
+
+Main panel width with the queue open, before and after:
+
+| viewport | before | after | mode |
+|---|---|---|---|
+| 1280×800 | 759 | 759 | inline |
+| 1100×720 (default window) | 579 | 579 | inline |
+| 1024×768 | 503 | 503 | inline |
+| 900×600 | **379** | **700** | overlay |
+| 800×600 | 423 | 744 | overlay |
+| 390×780 | **69** | **390** | overlay |
+| 320×600 | **0** | **320** | overlay |
+
+The scrim is perceptible but subtle on a dark ramp, which is worth
+knowing before someone "fixes" it: sampled from the screenshots at
+900×600, the main panel's background goes 33,37,41 → 18,20,23 and a
+row's text 242 → 133. It covers the **content area only** — not the
+sidebar or the transport — on purpose: the queue is not modal, and
+leaving the navigation live means the scrim reads as "this is over the
+content" (which is what #24 asked for) without pretending the rest of
+the app is unavailable.
+
+## What #69 did with the promise, and one thing this plan got wrong
+
+#69 landed on its own branch as decision 3 said it would, and the
+matrix's *no action is ever unreachable at any supported size* is now
+kept rather than promised. Measured on Playlists, actions clipped:
+
+| viewport | before #24 | after #24 | after #69 |
+|---|---|---|---|
+| 900×600, queue open | all three | one (114/162px) | none |
+| 900×600, queue closed | one | one | none |
+| 800×600, queue closed | one (158/162px) | one | none |
+| 390×780 | all three | all three | none |
+| 320×600 | all three | all three | none |
+
+The shape was the one decision 3 predicted — an actions API first, an
+overflow rule second — and all three hosts that slot actions migrated.
+
+**What this document got wrong is smaller and worth keeping.** Decision
+1 says the header's minimum is a *comfort* floor and that only the
+queue and the actions compete for the header's width. They are not the
+only two: every child of that flex row was `flex-shrink: 0`, so
+whatever came last lost, and the actions come last. At 320px the sort
+control alone is 172px of the header — so with every action already
+collapsed into the menu, the *menu button* was 76px off the right edge.
+The promise was still broken with nothing left to collapse.
+
+That is why #69 also had to decide what gives way: the title (which the
+navigation also states) and, below 600px, the word "Sort:" (which the
+direction arrow implies). Neither is an action, which is the rule the
+matrix actually encodes — **an action is a capability and everything
+else on that row is a label.**
+
+## Verification, and what each tier cannot see
+
+- `make ui-test` — the queue panel's mode logic is component-tier
+  work and belongs there. It **cannot** see the shell: the threshold is
+  computed from the sidebar and viewport, which do not exist in that
+  tier.
+- `make e2e` — `layout-overflow.spec.ts` gains the queue-open case at
+  every band (it has none today, which is why main=0px at 320px has
+  never failed anything) and **gains 900×600**, since the minimum is
+  not the worst case. `queue-toggle-state.spec.ts` and
+  `phone-shell.spec.ts` both touch the panel and must be re-read before
+  editing.
+- **Screenshots at every band, read by a human.** This is not optional
+  here: `layout-overflow.spec.ts` asserts the *shell* needs no sideways
+  scrolling and passes on a build whose album header clips its own
+  buttons (measured this session at 390px; filed on #66). Clipping
+  *inside* a component is invisible to it, and clipping is this issue.
+- `make ui-visual` **cannot help at all** — the component tier renders
+  the token fallbacks, because the theme only reaches `:root` in the
+  real app.
+- Accessible names via `page.getByRole(...)`, never a shadow-root
+  query. A drawer with a scrim is exactly the shape that grows a
+  nameless control, and this repo has shipped one three times.

.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

@@ -85,8 +85,18 @@ release decision. The rule that the issue number stays out of the
 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.
-`close` also drops `Status/In Progress`, because a claim outlives the
-work if nothing takes the label off.
+
+**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
 
@@ -307,6 +317,60 @@ stacking dialogs. Window state moved off that path entirely, onto a
 window still exists and `OnShutdown` has neither a context nor a
 window.
 
+**An activity is a view onto the process, and `main()` runs once per
+process.** On Android the Wails entry point is `nativeInit`, which
+`MainActivity.onCreate` calls — and it does two things: it re-points the
+native library's global JNI reference at the calling `WailsBridge`, and
+it runs `go mainFunc()`. Android destroys and recreates an activity
+**without restarting the process** (a configuration change the manifest
+does not declare, memory pressure, or every background under "Don't keep
+activities"), so `main()` ran again on a live app. `application.New`
+returns the *existing* app rather than building a second one,
+`app.Run()` then refuses — `a.starting` is still true, because Android's
+`platformRun` is `select{}` and never returns — and the `os.Exit(1)`
+under that error took the **first**, healthy app down with it: its
+database, its queue, and the audio a `mediaPlayback` foreground service
+was holding the process alive to play. `mainStarted` latches it, first
+statement in `main()`.
+
+Four things about it are load-bearing.
+
+**The answer to "restore the session or cold-start" is settled by
+playback, not by preference.** The audio lives in the Go process, so a
+cold start on every activity recreation would stop the music mid-song —
+which is the exact thing the foreground service exists to prevent. The
+activity is a view; the app is the process. The frontend already
+cooperates, because a recreated WebView loads the page fresh and fetches
+its state from a backend that never went away.
+
+**Returning early is not a degraded mode, and that is why the latch is
+in Go rather than in Java.** The obvious fix — making
+`WailsBridge.initialized` `static`, so the second `nativeInit` is
+skipped — keeps the process alive and silently breaks the app, because
+skipping `nativeInit` skips the reference re-point too: Go would keep
+executing JavaScript against the *destroyed* activity's WebView, and the
+app would open, render, and never receive another backend event. The
+latch lets `nativeInit` do its first job and declines only its second.
+
+**`ServiceShutdown` has never run on Android**, and nothing should be
+built on the assumption that it will. `App.Quit()` reaches an
+`androidApp.destroy()` that is an empty method, and `Run()`'s deferred
+`shutdownServices()` cannot fire behind `select{}`. Durability on this
+platform is the persist writers, which submit on every mutation rather
+than at exit — which is also why `MainActivity.onDestroy` no longer
+calls `bridge.shutdown()`: the activity going away is not the app
+shutting down, and there is no callback for the process going away
+because Android simply kills it.
+
+**No tier here can see any of this**, so the guard is split. A source
+sweep (`TestMainClaimsBeforeItDoesAnything`) asserts the latch is the
+*first* statement of `main()` — the failure it exists for is not
+deletion, which is loud, but a line creeping in above it, since a second
+`NewYellowJacketApp` opens the SQLite database again on every
+recreation. The rest is a documented device check in
+`.pi/skills/yellowjacket-dev/references/android-tier.md`, with the
+logcat signature and a one-line way to force a recreation.
+
 `internalServiceMethods` auto-excludes `ServiceStartup`,
 `ServiceShutdown`, `ServiceName` and `ServeHTTP` from bindings, so this
 shape **removed** 12 spurious bindings and the bogus `context` model
@@ -504,6 +568,63 @@ rather than renaming them.
   the autotag apply are registered; anything that is not registered has
   none of that, which is exactly how the three gaps the audit found
   came about.
+
+  **Its rows are shown where the work is started, not on a page of
+  their own.** #27 folded the Jobs destination away, and the shape it
+  folded into is `<job-panel kinds="…">` embedded four times — scans in
+  Settings → Libraries, index and enrichment in Settings → Search
+  Index, downloads under the download clients, the autotag apply in
+  `autotag-view`. One "Background jobs" section in Settings was the
+  obvious reading of the report and is the tab again under another
+  name.
+
+  Four things about it are load-bearing. **Four of the five kinds
+  already had a home** that showed their work — the tier list, the
+  download list, the apply ring — and what none of them had is the
+  *generic* affordances, so the panel carries pause, cancel, Details
+  and the log to each rather than replacing what is there. **The
+  controls are `applyJobControl`**, not a reimplementation, which is
+  what keeps the "you will discard hours of downloading" confirmation
+  alive: it is keyed on `KindIndexBuild` inside the shared handler, and
+  a host drawing its own buttons would drop it silently. **A panel with
+  nothing to say is `hidden`**, host margin included, because an idle
+  panel in four places is four pieces of furniture describing an
+  absence. And **there is no "Clear finished"** in it, because
+  `ClearFinishedJobs` is global — a Clear under Libraries would discard
+  the index build's history too; a finished row dismisses itself.
+
+  The header `job-indicator` is still the one view of everything at
+  once, from every page — **on a desktop.** One consequence worth
+  knowing before writing a spec: a section holding a `job-panel` also
+  holds a `job-details-drawer`, whose own header carries `.header` — so
+  `config-section .header` is ambiguous the moment a job exists.
+
+  **Below 600px that indicator stands down and `<job-band>` takes
+  over** (#62), because a popover is a *disclosure* and background work
+  is the one thing a phone should not make you open something to see —
+  and because #57 deletes the bar it is anchored to and is blocked on
+  it having somewhere else to live. The band is the same `job-panel`,
+  so `applyJobControl` and its index-build confirmation come along
+  rather than being reimplemented; `kinds="*"` is how it says "every
+  kind", which is what the indicator was for.
+
+  Three things about it are load-bearing. **It is in the layout, not
+  over it**, as its own grid row above the main panel: the first
+  version put it in `notification-host`'s fixed band, which reads fine
+  in a screenshot and is unusable — at 424×439 a compact panel is
+  ~200px of a 439px screen and it *covers* what is under it, which four
+  e2e specs caught by failing on taps it was intercepting. **It shows
+  active work only** (`active-only`), because in flow a finished row is
+  furniture that keeps the content pushed down after the work is done;
+  finished rows stay where the work was started, which is #27's rule.
+  And **it renders nothing above 600px**, from `matchMedia` rather than
+  a media query, because that decides whether the element *exists* —
+  Settings already holds four `job-panel`s and a fifth answering for
+  every kind is `bottom-nav`'s "resolved to 2 elements" trap again.
+  `index.css` keeps it `display: none` outside the phone for a second
+  reason: an in-flow grid child with no named area is auto-placed into
+  one of the shell's rows, which is what the skip link is absolutely
+  positioned to avoid.
 - `config` — TOML-based settings. Settings page uses HTMX + templ for server-rendered HTML fragments.
 - `playlist` / `smartplaylist` — Playlist CRUD and rule-based smart playlists.
 - `mediacontrols` — OS media controls behind one `Handler`: MPRIS over
@@ -935,13 +1056,167 @@ change at all.
 
 Two rules hold it up. The **first** navigation *replaces* the launch
 entry rather than pushing one, or every launch costs a back press before
-the app will close. And the in-app back buttons (`navigate-back`, fired
+the app will close. **There are two launch navigations**, which is what
+defeated that rule for five phases: the eager `navigate → home` at the
+foot of `index.ts` and the configured page `GetDefaultPage()` resolves
+to later. Only the first replaced, so a fresh session was already one
+entry deep, the first back press replayed home over home, and on Android
+`canGoBack()` was true so the press that should have exited the app did
+nothing (#142). The landing-page navigation carries `_replace`, honoured
+only while still at index 0 — past that the user has navigated during
+the backend call, and a slow answer must not overwrite an entry they
+made. And the in-app back buttons (`navigate-back`, fired
 by the detail views and `now-playing-view`) go through `history.back()`
 rather than a stack of their own: the old `navStack` is **deleted**, not
 kept beside it, because two stacks is precisely how a view's own back
 button and the phone's gesture come to disagree about what one press
 means.
 
+**And there is one statement of which view is active**, for the same
+reason: `popstate` calls `handleNavigate()` directly and dispatches no
+`navigate`, so the two nav components — which learned the active view
+from that event — kept highlighting the view the user had just *left*.
+`store/active-view-store.ts` is the shell saying where the user is, and
+both navs read it through `ActiveViewController` rather than holding an
+`activeView` of their own.
+
+Four things about it are load-bearing.
+
+**"Please go to X" and "the active view is now X" are different
+statements**, and only the first existed — dispatched from 28 call
+sites across 18 files. A re-dispatch from inside `handleNavigate` is
+not the fix and cannot be: that function is the `document` listener for
+`navigate`, so it is an infinite loop.
+
+**It is a store rather than an event, because a component that mounts
+after a navigation still has to know.** `bottom-nav`'s "More" drawer
+creates its `<app-sidebar>` on open, and that copy had heard no
+`navigate` at all — standing on Albums, the drawer opened highlighting
+Home. An event has no answer for a listener that was not there.
+
+**A detail view is not a view here**, so the destination it was opened
+from stays lit. `app-sidebar` did that by accident (it guarded on
+`navItems.some(...)`, so an unmatched name left its highlight alone)
+and `bottom-nav` had no such guard and so lit *nothing* — which is why
+one looked right and the other looked broken on the same screen.
+Whether a view is primary is the shell's fact: `view in VIEW_TAGS` is
+passed to `setView`, never re-derived, because a second copy of that
+list is a second thing to forget.
+
+**Nothing is lit until the shell has navigated.** The store starts
+empty rather than defaulting to `home`, which is what `app-sidebar`'s
+field used to do to match the landing view — a default that is correct
+only while `GetDefaultPage()` agrees with it.
+
+**Back and forward are chrome, and the depth is the shell's own
+count.** `<nav-history>` in the top bar is #6: the stack was always
+global — every navigation is an entry and `popstate` restores any of
+them in either direction — so what was missing was an affordance, since
+the only way back was a detail view's own button, which leaves the
+screen with the view it belongs to. The buttons dispatch
+`navigate-back` / `navigate-forward` and the shell owns both guards,
+for the reason the old `navStack` was deleted: a second caller reaching
+for `history` is how two stacks come to disagree.
+
+Three things about it are load-bearing. **Forward is not back
+negated**, so the single `pushedEntries` counter could not express it —
+`popstate` carries no direction and fires identically both ways, so a
+counter decremented on every pop reads a forward as a second back. Each
+entry carries its index (`yjIdx`) and the shell keeps the current one
+and a high-water mark; that also survives a jump of more than one,
+which `history.go(-n)` and a long-press on a browser's back button both
+produce. **A control that cannot act is `disabled` here**, which is the
+documented exception to `library-status-indicator`'s rule: the two are
+a pair whose positions the user learns, and hiding one moves the other
+under the cursor. And **it stands down below 900px** — the top bar is
+what runs out of room first below that (it already overflows 600px by
+11px, #143), and nothing becomes unreachable: `nav.back` / `nav.forward`
+(`Alt+Left` / `Alt+Right`, the browser's own combination, and clear of
+the bare arrows that seek) are global at every width, and the phone has
+the platform's gesture.
+
+The assertion is `aria-current="page"`, in
+`e2e/specs/back-navigation.spec.ts`. That file existed throughout the
+bug, covered exactly these journeys, and asserted only
+`data-active-view` — the shell's own bookkeeping, which was right the
+whole way through — so it was green on the broken build. Same trap as
+`layout-overflow.spec.ts` and `page-header`: a spec named for the
+behaviour, measuring the plumbing.
+
+**Which destinations exist is configuration, and hiding one takes away
+the nav item and nothing else.** Eleven sidebar entries is more than
+most libraries need (#25), so each is toggleable from Settings →
+Navigation, Autotag is off until asked for, and Downloads is absent
+until there is a client to download with — a destination for a feature
+that cannot work is worse than none. `navigate` still resolves a hidden
+view, which is not a nicety: detail views navigate into these and the
+launch page is one of them. Nothing needed a special case for the
+highlight either, because the paragraph above moved that onto
+`active-view-store`: the sidebar asks `isActive(id)` per *rendered*
+item, so a hidden view lights nothing exactly as a detail view does.
+
+Five things about it are load-bearing.
+
+**The stored shape is a map keyed by view id, and an absent key means
+that view's own default** (`backend/config.Views`). That is what makes
+this need no migration in either direction, and it is the polarity rule
+`AllowMeteredCatalogDownload` states: the zero value is the intended
+answer. A `HiddenViews []string` cannot express "Autotag off by
+default" at all — its zero value is *hide nothing* — and a struct with
+a boolean per view turns a view that later stops existing into stored
+garbage. Here an unknown key is dropped on load and a view added later
+gets its own default rather than being invisible or forcibly visible.
+It is also what makes #73's `#25 → #27` order safe rather than
+backwards: when Jobs folds into Settings, `jobs = true` in somebody's
+config is a key nothing asks about.
+
+**Two states the user could not get out of are refused, in the config
+and not in the checkbox.** Settings is never hideable and the launch
+page is not hideable while it is the launch page. `config.toml` is
+hand-editable, so a disabled checkbox is the affordance and
+`SetViewVisible` is the rule — an app that can be locked out of its own
+Settings by a typo in TOML is a support problem nobody can debug
+remotely. On *load* the launch page is instead un-hidden rather than
+refused: there is nobody to tell, and the honest reading of "my launch
+page is Autotag" is that this user wants Autotag, not that their launch
+page should be silently reset to something they did not choose.
+
+**Downloads is gated at the nav and not in the config**, on
+`downloadStore.available`, so switching it on in Settings still means
+what it says once a client exists and the tab appears without a restart
+(#37's rule). `available` is false until the providers have loaded,
+which makes the item *appear* on a fresh launch rather than appearing
+and then vanishing.
+
+**The tab bar honours the toggles too, and the reason is local rather
+than a general rule about phones.** `PHONE_COLUMN_IDS` is the precedent
+for "what a phone shows is a different question", and it would apply —
+except that `bottom-nav`'s "More" opens the *same* `<app-sidebar>`,
+which filters, so an unfiltered bar would contradict its own drawer one
+tap away. Which four tabs is still plan 016's committed subset; this
+only removes from it, and "More" is never filtered because it is how
+everything else stays reachable.
+
+**A retired destination is the one shape this does not make free.** An
+absent visibility key takes its default and an unknown one is dropped,
+but `DefaultPage` is a *value*: a launch page naming a view that no
+longer exists fails validation, and on the load path that means the app
+refuses to start for whoever had it selected. `RetiredViews` is that
+list, and `ApplyDefaults` treats a retired name as a zero value while
+an unknown-but-not-retired one still errors — a typo is worth being
+told about. #27 retiring `jobs` is its first entry.
+
+**The list of destinations is `services/view-meta.ts`**, on
+`shortcut-meta.ts`'s pattern, because #25 gave it a second reader:
+Settings renders a toggle per view and needs the same labels in the
+same order. Which views exist and what an unconfigured install shows is
+Go's (`backend/config.Views`, which `DefaultPage`'s validation reads
+too, so the launchable set is not a second list); how they are *drawn*
+is the frontend's, beside the rest of the icon vocabulary. The binding
+returns the **resolved** map for every view, so the frontend holds no
+copy of the defaults — which would be the copy that shipped in the
+binary rather than the one being edited.
+
 **A primary view is cached, not unmounted.** `index.ts` keeps every
 primary view in the DOM and toggles a `.view-hidden` class, because that
 is what preserves `scrollTop` across navigation — so
@@ -1318,6 +1593,164 @@ is 32px each. Which four is plan 016's committed subset, and everything
 else — Settings included, because a phone still needs it — is behind
 "More".
 
+**There are three supported size bands, and the queue is part of the
+promise.** Plan 018 (#24) wrote them down: **Phone** below 600 (bottom
+nav, reflows, fits 320px exactly), **Compact** 600–899 (icon sidebar),
+**Desktop** from 900 (labelled sidebar) — plus one sentence across all
+three, *no action is ever unreachable at any supported size*. The bands
+themselves already existed; what was new is that they are a promise and
+that the queue panel is inside it.
+
+**The top bar decides what it can afford, and what it gives up is never
+an action.** Its five children do not fit at the bottom of the Compact
+band: the bar was 611px inside a 600px viewport idle and **862px while
+a scan ran**, because `job-indicator` is `hidden` when idle and 235px
+wide showing a real library's scan title (#143). So `services/
+top-bar-fit.ts` is `page-header`'s treatment one bar up — a
+ResizeObserver, every pass starting from all-visible, hiding the
+lowest-priority child until it fits.
+
+Five things about it are load-bearing.
+
+**It is measured rather than breakpointed for a reason specific to this
+bar**: three of its five children are as wide as their *content* — the
+library filter is a `<select>` sized by the longest library name, the
+indicator by the running job's title, the search box by its view-scoped
+placeholder — so any width picked is right for one library, one job and
+one view. Swept with a long-titled scan staged, the bar overflowed at
+**every** width from 600 to 899 *and* at 900 where `nav-history`
+appears, while 899 fits; a breakpoint fixing "600 to 610" would have
+fixed whichever case happened to be idle when it was measured.
+
+**What yields is decided by the promise above, which rules out the two
+cheapest answers.** Hiding the library filter takes away an action —
+`library-filter` is the only control in the app that calls
+`setSelectedLibrary` — so it trades this promise for the same promise
+(#148 is the phone already doing that). Collapsing the search box to an
+icon is what #57 wants and #57 is blocked behind #62, so building it
+here is building it without the thing that blocks it. The two that
+yield are the two that are **not** actions: the wordmark, which the
+window's own title bar repeats and which #48 wants down to "YJ" at
+every width anyway, and then the job indicator's *label*, leaving the
+ring — which is not a new judgement, since the component already drops
+it below 600px and its `sr-only` live region is what announces the
+state either way.
+
+**The wordmark yields its width, not its existence.** The collapsed
+rule is visually-hidden rather than `display: none`, because that `h1`
+is the document's top-level heading as well as the brand.
+
+**"Fits" is the children against the content box, and `scrollWidth`
+cannot express it.** `scrollWidth` counts a box's left padding and not
+its right, so with 2em gutters it under-reports by 32px: the first fix
+read `700/700` — a perfect fit — with the indicator sitting in the
+whole right gutter. Same family as #69's title trap, and found only
+because `top-bar-fit.spec.ts` measures **per child**, which is what
+`layout-overflow.spec.ts` cannot do and why that spec was green
+throughout the defect.
+
+And **the bar does not resize when a job starts**, which is the case the
+whole thing is for — a ResizeObserver on the header alone never fires,
+so every element child is observed too.
+
+**The bottom bar is three columns whose outer two are the same width,
+and that is what "centred" means.** It was `320px 1fr auto`, so the
+transport sat in the middle of the space the metadata and the queue
+button did not use — its centre was ~140px right of the window's at
+every size (#23). The outer tracks are now the same expression, so the
+middle one is centred by construction rather than by arithmetic that
+has to be redone whenever a control joins the bar.
+
+Four things about it are load-bearing.
+
+**The side width is the metadata's, capped at a quarter of the bar**,
+and the cap is not tidiness — it was measured as a regression first.
+Reserving the full `--now-playing-width` on *both* sides costs the
+transport twice: at 800px the outer pair wanted 640 of 800 and the seek
+bar's track fell from **257px to 61px**, and to 0 at 200% text. The
+control you drag was being squeezed to centre the buttons above it.
+With the cap it is 246px at 800, which is parity with the uncentred
+layout.
+
+**The cap is a `min()` rather than a breakpoint** because
+`--now-playing-width` is *user state* — the metadata panel has a drag
+handle — and the same reasoning the queue panel's overlay mode uses
+applies: a rule that assumed the default 320 would be wrong by whatever
+the user dragged. Tying both sides to that variable is also what keeps
+the handle meaningful; a plain `1fr … 1fr` would centre the transport
+just as well and silently make dragging a no-op.
+
+**The volume moved out of `audio-player` and into the bar** (#42),
+because the transport column has to hold the transport and nothing
+else or "centred" means centred with a slider bolted to one side. It
+lives in `.bar-end` with the queue button — one cell, not two columns,
+since the centring compares *columns* and a separate volume track would
+make the outer pair unequal by whatever the slider measures.
+
+And **the slider is inline by default, with the popup as a setting**
+whose stored flag names the *popup*: `backend/config`'s polarity rule,
+where the zero value has to be the intended answer, so an existing
+`config.toml` with no key gets the new default without a migration.
+Inline, the icon becomes the mute toggle and is named after that action
+rather than after the state, because with the slider beside it there is
+nothing left to disclose. It stands down below 600px whatever the
+setting says — that is about the platform rather than preference, and
+is why `mediacontrols`' Android handler implements no volume callback.
+
+**900 is the worst desktop width, not the 800×600 minimum.** The
+sidebar collapses to icons *below* 900, so the main panel is 843px at
+899 and 700px at 900 — the narrowest content area any desktop width
+produces is at the top of the Compact band, not at the enforced floor.
+Every viewport list that stopped at "the minimum" was therefore missing
+its own worst case, which is why `layout-overflow.spec.ts` carries 900
+now. And **both reasons in `MinWidth`'s comment had expired** — the
+subtitle is `display: none` from 899 down and the sidebar host scrolls
+(`overflow-y: auto`; at 600×460 its `scrollHeight` is 434 against a
+332px client) — so 800×600 is a *comfort* floor for desktop chrome and
+not a correctness one. Below it the phone layout takes over, which is
+also why a very small window reflows rather than becoming a
+mini-player: **#12 is a second always-on-top window, not a mode of this
+one**, and making it a mode would discard navigation state on a resize
+and put the process-level MPRIS question on a path a drag can trigger.
+
+**The queue panel is a column only while the content can spare the
+width, and that cannot be a media query.** In flow the host is
+`flex-shrink: 0`, so an open queue is paid for by the main panel: it
+left 379px at 900×600 (with all three of the Playlists header's actions
+clipped), 69px at 390, and **0px** at 320 — the content was not
+degraded but gone. It goes to an overlay with a scrim when
+`available - panelWidth < 480`, where `available` is
+`.content-area`'s width and therefore already accounts for the
+sidebar's collapse.
+
+Four things about it are load-bearing. **The mode is computed, not
+breakpointed**, because the panel's width is user state — drag-resizable
+200–500px and persisted — so a viewport breakpoint silently assumes the
+default 320 and is wrong by up to 180px in the direction that hurts;
+widening the panel at a fixed window size must flip it, and
+`queue-overlay-mode.test.ts` is written around exactly that. **480 is a
+judgement and says so**: there is no cliff to derive it from (the track
+list rescales continuously, 213px to 124px columns with no row
+overflow), so it is anchored to keep the default 1100px window inline
+and put every measured-broken case on the overlay side. **The scrim
+covers the content area only** — not the sidebar or the transport —
+because the queue is not modal, and it is subtle on a dark ramp by
+arithmetic rather than by accident (33,37,41 → 18,20,23). And **the
+overlay is a presentation, not a fork**: #55 asks for one component
+with two mount points, so the roving tab stop, Alt+Arrow reorder, drag
+reorder, selection semantics and `virtualizer.requestUpdate()` all come
+along untouched. Escape closes it and returns focus, and is attached
+only while the overlay is up — it is a dismissal, not a shortcut, which
+is why it is not a panel-scoped binding.
+
+What this does **not** fix is `page-header` overflowing on its own:
+at 900×600 "New Smart Playlist" is still clipped to 114 of 162px with
+the queue *closed*. That is #69, and it cannot be fixed in
+`page-header` alone — actions arrive through `<slot name="actions">` as
+arbitrary light-DOM markup with their own handlers, so collapsing them
+into a "More actions" menu needs an actions *API* (data, not markup)
+across all three hosts that slot them.
+
 **The phone section of `index.css` is last on purpose.** A media query
 adds no specificity, so a `@media (max-width: 599px)` block placed
 above the plain rules it overrides loses to them — which is how phase 1
@@ -1438,6 +1871,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
@@ -1537,11 +2016,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
@@ -1558,6 +2081,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
@@ -1569,6 +2145,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
@@ -1739,6 +2341,79 @@ that corrects itself a moment later is worse than saying nothing. And
 the field, the direction and their persistence, so the control cannot
 disagree with the list.
 
+**And an action is data, on that same rule: the header decides what
+fits, the host decides what happens.** Playlists slotted three buttons
+totalling 390px into a header that gets 700px at 900×600, so "New Smart
+Playlist" rendered **114 of its 162px** with the queue closed — and on a
+phone none of them could be reached at all, which is what #69 reported.
+A host passes `PageAction[]` (`{id, label, icon, onSelect, priority,
+drop?}`) and `page-header` renders each one as a button or as an item in
+one "More actions" menu.
+
+**It could not have been a rule added in one place**, and that is a fact
+about the API rather than an effort estimate: actions used to arrive
+through `<slot name="actions">` as arbitrary light-DOM markup, and a
+component cannot move another component's light-DOM children into a
+dropdown and keep their behaviour — there is nothing generic in markup
+to render as a menu item. The slot survives for markup a data list
+cannot express, at the stated cost that **a slotted action does not
+collapse** and must therefore fit at 800×600.
+
+Six things about it are load-bearing:
+
+- **The fit is measured, never breakpointed.** A ResizeObserver drives
+  it, and each pass starts from *all visible* and hides the
+  lowest-priority action until it fits — so the collapsed set is a pure
+  function of the current width rather than of how the window got
+  there. A rule that only ever added to the set would never give a
+  button back, and one that adjusted by a step would need a hysteresis
+  band to stop it oscillating on the pixel where a button exactly fits.
+- **"Fits" means nothing is clipped, which is not the same as the
+  header not overflowing.** The title can ellipsis, and the moment it
+  can it absorbs the pressure: `scrollWidth` reports a header that fits
+  perfectly while the heading reads "Playlis…". That is this bug moved
+  from the button to the title, invisible to the same measurement that
+  missed it the first time — so the heading's own truncation counts as
+  not fitting, and an action is collapsed before the title gives way.
+  Below that, at 320px, the title *is* what yields: the navigation also
+  says which page you are on, and an action has nowhere else to be said.
+- **The measurement flips `hidden` on the rendered nodes rather than
+  re-rendering between steps.** Reading `scrollWidth` forces layout,
+  which is the point; awaiting a Lit update between steps instead lets
+  the intermediate all-visible state paint, so the fix would flash the
+  overflow it exists to prevent.
+- **Priority is what a *capability* costs, not what a button is worth.**
+  New Playlist is highest because it is the **drop target** and a closed
+  menu cannot be one; that is also why `PageAction.drop` carries the
+  host's own `dragover`/`dragleave`/`drop` handlers rather than the
+  header owning a notion of dropping, and why the affordance is simply
+  absent from the overflow rather than approximated there.
+- **`aria-controls` names a panel that is always in the DOM** —
+  `config-section`'s rule, and `wa-popup` hides it when inactive — and
+  the keyboard model is `MenuKeyboard`, shared with every other menu in
+  the app so this is not a second one.
+- **It is checked per button, because `layout-overflow.spec.ts` cannot
+  see this.** That spec asserts the *shell* needs no sideways
+  scrolling and passed on the broken build; clipping *inside* a
+  component is invisible to it, which is exactly why the defect
+  survived a spec named for it.
+  `e2e/specs/header-action-overflow.spec.ts` measures each button
+  against its header at 900×600, 800×600, 390×780 and 320×600, and
+  asserts buttons **plus** menu account for every declared action —
+  without that half it would pass vacuously on a build that renders no
+  actions at all.
+
+One thing it deliberately does **not** grow is a phone mode for the
+actions. `PHONE_COLUMN_IDS` is the precedent for "what is drawn and
+what can be sorted are different questions", but it exists because the
+track list's columns cannot be derived from a width; these can, and a
+second declaration of what a phone shows is a second thing to keep in
+step. What the header *does* state at phone width is one word: below
+600px the sort control's "Sort:" label is visually hidden — 172px of a
+320px header for a label the adjacent direction arrow implies — and it
+stays in the accessibility tree, because it is the select's accessible
+name and hiding it outright is `config-field`'s bug one component over.
+
 **The header search box is view-scoped, and now says so.** It sits in
 the app header and reads as global; typing `tide` on Playlists answered
 "No playlists match your search" with three *Tideline* tracks in the
@@ -2128,6 +2803,23 @@ Pre-commit hooks verify generated code is fresh — always run `make generate` a
   mistyped `feat` ships a minor version. `make release-dry` answers "what
   would this merge release" without pushing.
 
+  **The analyzer reads the type and ignores the scope, so a CI-only change
+  is `ci:` and never `fix(ci):`.** The scope is decoration; `fix` is a
+  patch whatever is in the brackets. Two commits touching nothing but
+  `.gitea/workflows/unclaim.yml` were written `fix(ci):` and cut `v0.2.1`
+  and `v0.2.2` — real releases, published to Arch, Homebrew and the APK
+  registry, containing no user-facing change. They were left in place
+  rather than deleted, because a version that vanishes is worse for
+  whoever pulled it than one that turns out to be empty.
+
+  **The blast radius is bigger than the version number**, which is what
+  makes this worth a paragraph. A merge to `main` starts two workflows;
+  if `release.yml` then pushes a tag, that tag push starts **four more**
+  (`arch-package`, `homebrew-formula`, `android-apk`, `desktop-assets`) —
+  on a runner with capacity 1, where the APK build alone is tens of
+  minutes. `make release-dry` before merging is how you find out, and it
+  is cheaper than every one of those.
+
   **`@semantic-release/github` is not in that config and must not be.**
   Gitea's API is `/api/v1` and is not GitHub's surface, so
   `@semantic-release/exec` calls `scripts/gitea-release.sh` instead — one
@@ -2176,19 +2868,60 @@ Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pr
 
 ## 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 \

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/autotag/recommend.go

@@ -17,6 +17,34 @@ const (
 	RecommendationStrong Recommendation = "strong"
 )
 
+// ConfidentTier is the tier at which this package considers a match
+// good enough to act on without being asked to look.
+//
+// It exists as a name rather than as `== RecommendationStrong` at
+// each call site because two features read it and they must not
+// disagree about what "high confidence" means: the album page tells
+// the user unprompted that the autotagger has a match (#28), and
+// strict auto-accept will rewrite the files without asking (#90).
+// A page that says "we are sure" about something the auto-accept
+// pass would decline is the app contradicting itself.
+//
+// What the two do *not* share is everything else. Surfacing a match
+// is a suggestion with a confirm dialog behind it; auto-accept is an
+// irreversible on-disk rewrite, and #90 gates it on further
+// conditions this tier cannot express — exact track count, every
+// title matching, lengths within a couple of seconds, no cover
+// replacement, no MBID conflict. So this is the floor both stand on,
+// not the whole of either test.
+const ConfidentTier = RecommendationStrong
+
+// Confident reports whether a tier clears ConfidentTier.
+//
+// A comparison rather than an equality, so adding a tier above
+// "strong" later does not silently stop qualifying.
+func Confident(r Recommendation) bool {
+	return recommendationRank(r) >= recommendationRank(ConfidentTier)
+}
+
 const (
 	// Absolute score tiers.
 	strongScoreThresh = 0.90

backend/autotag/recommend_test.go

@@ -168,3 +168,34 @@ func TestRecommend_LocalCandidatesWithoutRGMBIDCompareByTitle(t *testing.T) {
 		t.Errorf("different-title rival: Recommend = %q, want medium", got)
 	}
 }
+
+// The tier both features stand on is one name, checked here rather
+// than assumed at two call sites.
+//
+// #28 renders "we have a match for this album" on the album page and
+// #90 will rewrite files without asking; a page that claims confidence
+// the auto-accept pass would decline is the app contradicting itself.
+// What they do not share is everything else — auto-accept adds gates
+// this tier cannot express — so this pins the floor, not the whole of
+// either test.
+func TestConfidentIsTheOneSharedFloor(t *testing.T) {
+	t.Parallel()
+
+	if ConfidentTier != RecommendationStrong {
+		t.Errorf("ConfidentTier = %q, want strong", ConfidentTier)
+	}
+
+	for _, tc := range []struct {
+		rec  Recommendation
+		want bool
+	}{
+		{RecommendationNone, false},
+		{RecommendationLow, false},
+		{RecommendationMedium, false},
+		{RecommendationStrong, true},
+	} {
+		if got := Confident(tc.rec); got != tc.want {
+			t.Errorf("Confident(%q) = %v, want %v", tc.rec, got, tc.want)
+		}
+	}
+}

backend/autotagservice/albummatch.go

@@ -0,0 +1,145 @@
+package autotagservice
+
+import (
+	"database/sql"
+	"fmt"
+
+	"yellowjacket/backend/autotag"
+)
+
+// AlbumMatchView is "the autotagger already has a confident match for
+// the album you are looking at".
+//
+// It is deliberately not a score. The album page renders a suggestion,
+// and a suggestion has to be actionable: which release, what it is
+// called, and whether acting on it here would do the whole album or
+// only part of it.
+type AlbumMatchView struct {
+	// GroupKey is the tagging group the actions operate on.
+	GroupKey string `json:"groupKey"`
+
+	// Recommendation is the tier, as a string, for a caller that
+	// wants to render the strength rather than trust the filter.
+	Recommendation string `json:"recommendation"`
+
+	// Score is the top candidate's raw score, 0..1.
+	Score float64 `json:"score"`
+
+	// ReleaseMBID is the release Apply would write.
+	ReleaseMBID string `json:"releaseMbid"`
+
+	// Title and ArtistCredit name that release, so the banner can say
+	// what it is offering rather than "a match".
+	Title        string `json:"title"`
+	ArtistCredit string `json:"artistCredit"`
+
+	// TrackCount is the group's local track count.
+	TrackCount int64 `json:"trackCount"`
+
+	// GroupCount is how many tagging groups this album spans.
+	//
+	// More than one means a multi-disc album (one group per disc), and
+	// it is the reason this is a field rather than an implementation
+	// detail: applying "the album" from a single button would retag
+	// one disc of three and leave the folder holding a mix of old and
+	// new tags. The caller offers review instead.
+	GroupCount int `json:"groupCount"`
+}
+
+// MatchForAlbum answers "does the autotagger have something confident
+// to say about this album", for the album detail page.
+//
+// Three things about it are load-bearing.
+//
+// **It costs no MusicBrainz request.** Everything it needs is already
+// on disk: `tagging_items` carries the top score and release from the
+// background prefetch, and `tagging_candidates` durably holds the
+// scored list. The rate limiters here are shared with every page the
+// user can open, so a lookup that fires on page load must not join
+// that queue — which also means this returns nothing for a folder
+// nobody has scored yet, rather than scoring it now. That is the
+// right trade: the prefetch will get to it, and a page that silently
+// spends a minute of somebody's MusicBrainz budget to draw a banner
+// is worse than a page that says nothing.
+//
+// **The tier is computed, not read.** `tagging_items.score` is the raw
+// number and `Recommend` is what turns it into a claim — capping it
+// for an ambiguous runner-up, an incomplete alignment or a folder too
+// small to corroborate itself. Filtering on the raw score would
+// promise confidence the scorer had explicitly withheld.
+//
+// **Nothing is said about an album the user has already answered
+// for.** Only a `pending` group qualifies: `confirmed` covers both a
+// finished apply and an explicit "leave as is", and `skipped` is the
+// user saying not now. Re-offering either is nagging, and "leave as
+// is" would be actively wrong to argue with.
+func (s *Service) MatchForAlbum(albumID int64) (*AlbumMatchView, error) {
+	if albumID <= 0 {
+		return nil, nil //nolint:nilnil // "no album" is not an error.
+	}
+
+	rows, err := s.db.Queries.GetTaggingItemsForAlbum(
+		s.ctx, sql.NullInt64{Int64: albumID, Valid: true},
+	)
+	if err != nil {
+		return nil, fmt.Errorf("tagging items for album: %w", err)
+	}
+
+	pending := rows[:0:0]
+
+	for _, row := range rows {
+		if row.Status == "pending" {
+			pending = append(pending, row)
+		}
+	}
+
+	if len(pending) == 0 {
+		return nil, nil //nolint:nilnil // nothing to say is not an error.
+	}
+
+	// Rows arrive best-score-first, so the first pending one is the
+	// group worth describing. On a multi-disc album that is one disc
+	// of several and GroupCount says so.
+	best := pending[0]
+
+	cands := s.lookupCachedCandidates(best.GroupKey)
+	if len(cands) == 0 {
+		return nil, nil //nolint:nilnil // not scored yet; see the doc comment.
+	}
+
+	locals, err := s.scorer.LocalTracksForGroup(s.ctx, best.GroupKey)
+	if err != nil {
+		return nil, fmt.Errorf("local tracks for group: %w", err)
+	}
+
+	group := autotag.Group{
+		AlbumName:   best.AlbumName,
+		AlbumArtist: best.AlbumArtist,
+		Tracks:      locals,
+		Synthetic:   best.Synthetic != 0,
+	}
+
+	rec := autotag.Recommend(group, cands)
+	if !autotag.Confident(rec) {
+		return nil, nil //nolint:nilnil // not confident enough to interrupt.
+	}
+
+	top := cands[0]
+
+	// The release the banner names must be the release Apply would
+	// write. Apply with an empty MBID takes the top cached candidate,
+	// which is what this reads — but it is passed explicitly anyway,
+	// so a rescore between the page rendering and the user clicking
+	// cannot swap the album out from under a button they have already
+	// read.
+	return &AlbumMatchView{
+		GroupKey:       best.GroupKey,
+		Recommendation: string(rec),
+		Score:          top.Score,
+		ReleaseMBID:    top.ReleaseMBID,
+		Title:          top.Title,
+		ArtistCredit:   top.ArtistCredit,
+		TrackCount:     best.TrackCount,
+		GroupCount:     len(pending),
+	}, nil
+}

backend/autotagservice/albummatch_test.go

@@ -0,0 +1,320 @@
+package autotagservice
+
+import (
+	"encoding/json"
+	"testing"
+
+	"yellowjacket/backend/autotag"
+	"yellowjacket/backend/database"
+)
+
+// seedAlbumGroup writes one album's files, its tagging item and the
+// durable candidate blob the prefetch would have left behind.
+//
+// The candidate list is what a real one looks like in the two ways
+// that decide the tier: a per-track alignment for every local track,
+// and a runner-up far enough away not to count as ambiguity.
+func seedAlbumGroup(
+	t *testing.T,
+	db *database.DB,
+	groupKey string,
+	tracks int,
+	status string,
+	score float64,
+) int64 {
+	t.Helper()
+
+	for i := 1; i <= tracks; i++ {
+		database.InsertTestTrack(t, db, database.TestTrack{
+			FilePath:    filePathFor(groupKey, i),
+			Title:       titleFor(i),
+			Artist:      "Tideline",
+			Album:       "Glass Harbour",
+			AlbumArtist: "Tideline",
+			TrackNumber: int64(i),
+			LengthMs:    200000,
+			LibraryID:   0,
+			GroupKey:    groupKey,
+		})
+	}
+
+	if _, err := db.ExecContext(`
+		INSERT INTO tagging_items
+		    (group_key, library_id, track_count, album_name, album_artist,
+		     disc_number, status, score, best_match_release_mbid)
+		VALUES (?, 0, ?, 'Glass Harbour', 'Tideline', 0, ?, ?, 'rel-1')
+	`, groupKey, tracks, status, score); err != nil {
+		t.Fatalf("insert tagging item: %v", err)
+	}
+
+	var albumID int64
+	if err := db.QueryRowWriter(
+		`SELECT album_id FROM audio_files WHERE group_key = ? LIMIT 1`, groupKey,
+	).Scan(&albumID); err != nil {
+		t.Fatalf("read album id: %v", err)
+	}
+
+	return albumID
+}
+
+func filePathFor(groupKey string, n int) string {
+	return "/music/" + groupKey + "/0" + string(rune('0'+n)) + ".mp3"
+}
+
+func titleFor(n int) string {
+	return "Track " + string(rune('0'+n))
+}
+
+// storeCandidates writes the durable blob GetCandidates would have
+// cached, with `top` as the winning score.
+func storeCandidates(
+	t *testing.T, db *database.DB, groupKey string, tracks int, top float64,
+) {
+	t.Helper()
+
+	aligns := make([]autotag.TrackAlignment, 0, tracks)
+	for i := range tracks {
+		aligns = append(aligns, autotag.TrackAlignment{
+			Status:     autotag.AlignmentMatched,
+			LocalIndex: i,
+		})
+	}
+
+	cands := []autotag.Candidate{
+		{
+			ReleaseMBID:      "rel-1",
+			ReleaseGroupMBID: "rg-1",
+			Title:            "Glass Harbour",
+			ArtistCredit:     "Tideline",
+			TrackCount:       tracks,
+			Alignments:       aligns,
+			Score:            top,
+		},
+		{
+			ReleaseMBID:      "rel-2",
+			ReleaseGroupMBID: "rg-2",
+			Title:            "Something Else",
+			ArtistCredit:     "Another Band",
+			TrackCount:       tracks,
+			Score:            0.40,
+		},
+	}
+
+	blob, err := json.Marshal(cands)
+	if err != nil {
+		t.Fatalf("marshal candidates: %v", err)
+	}
+
+	if _, err := db.ExecContext(
+		`INSERT INTO tagging_candidates (group_key, candidates) VALUES (?, ?)`,
+		groupKey, string(blob),
+	); err != nil {
+		t.Fatalf("insert candidates: %v", err)
+	}
+}
+
+// A confident match is what the album page exists to surface.
+func TestMatchForAlbumSurfacesAConfidentMatch(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	albumID := seedAlbumGroup(t, db, "grp-1", 8, "pending", 0.95)
+	storeCandidates(t, db, "grp-1", 8, 0.95)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got == nil {
+		t.Fatal("no match returned for a strong candidate")
+	}
+
+	if got.Recommendation != string(autotag.RecommendationStrong) {
+		t.Errorf("recommendation = %q, want strong", got.Recommendation)
+	}
+
+	// The release named is the release Apply would write — the page
+	// must not offer one album and tag another.
+	if got.ReleaseMBID != "rel-1" || got.Title != "Glass Harbour" {
+		t.Errorf("named %q/%q, want rel-1/Glass Harbour", got.ReleaseMBID, got.Title)
+	}
+
+	if got.GroupCount != 1 {
+		t.Errorf("groupCount = %d, want 1", got.GroupCount)
+	}
+}
+
+// The tier is computed from the candidates, not read off the raw
+// score — a high number the scorer would have capped must not reach
+// the page as confidence it withheld.
+func TestMatchForAlbumDoesNotTrustTheStoredScore(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	// Two tracks: below the evidence floor, so `Recommend` caps this
+	// at medium however well it scores.
+	albumID := seedAlbumGroup(t, db, "grp-2", 2, "pending", 0.99)
+	storeCandidates(t, db, "grp-2", 2, 0.99)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got != nil {
+		t.Errorf("surfaced %+v for a two-track folder, want nothing", got)
+	}
+}
+
+// A weak match is not worth interrupting for.
+func TestMatchForAlbumStaysQuietBelowTheTier(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	albumID := seedAlbumGroup(t, db, "grp-3", 8, "pending", 0.60)
+	storeCandidates(t, db, "grp-3", 8, 0.60)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got != nil {
+		t.Errorf("surfaced %+v for a 0.60 match, want nothing", got)
+	}
+}
+
+// An album the user has already answered for is not re-offered.
+//
+// `confirmed` covers both a finished apply and an explicit "leave as
+// is", and arguing with the second would be actively wrong.
+func TestMatchForAlbumRespectsAnAnswerAlreadyGiven(t *testing.T) {
+	t.Parallel()
+
+	for _, status := range []string{"confirmed", "skipped", "matched"} {
+		t.Run(status, func(t *testing.T) {
+			t.Parallel()
+
+			db := database.NewTestDB(t)
+			svc := newTestService(t, db)
+
+			albumID := seedAlbumGroup(t, db, "grp-"+status, 8, status, 0.95)
+			storeCandidates(t, db, "grp-"+status, 8, 0.95)
+
+			got, err := svc.MatchForAlbum(albumID)
+			if err != nil {
+				t.Fatalf("MatchForAlbum: %v", err)
+			}
+
+			if got != nil {
+				t.Errorf("surfaced %+v for a %s group, want nothing", got, status)
+			}
+		})
+	}
+}
+
+// A folder nobody has scored yet says nothing, rather than scoring it
+// now: the MusicBrainz limiter is shared with every page the user can
+// open, and this runs on page load.
+func TestMatchForAlbumMakesNoNetworkCallForAnUnscoredFolder(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	// No storeCandidates: the prefetch has not reached this folder.
+	albumID := seedAlbumGroup(t, db, "grp-4", 8, "pending", 0.95)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got != nil {
+		t.Errorf("surfaced %+v with no cached candidates, want nothing", got)
+	}
+}
+
+// A multi-disc album is several groups, and the count is what stops
+// the page offering one button that would retag one disc of two.
+func TestMatchForAlbumCountsEveryGroupOfTheAlbum(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	albumID := seedAlbumGroup(t, db, "grp-d1", 8, "pending", 0.95)
+	storeCandidates(t, db, "grp-d1", 8, 0.95)
+
+	// Disc two: same album row, its own folder and tagging group.
+	for i := 1; i <= 6; i++ {
+		database.InsertTestTrack(t, db, database.TestTrack{
+			FilePath:    filePathFor("grp-d2", i),
+			Title:       titleFor(i),
+			Artist:      "Tideline",
+			Album:       "Glass Harbour",
+			AlbumArtist: "Tideline",
+			TrackNumber: int64(i),
+			DiscNumber:  2,
+			LengthMs:    200000,
+			LibraryID:   0,
+			GroupKey:    "grp-d2",
+		})
+	}
+
+	if _, err := db.ExecContext(`
+		INSERT INTO tagging_items
+		    (group_key, library_id, track_count, album_name, album_artist,
+		     disc_number, status, score)
+		VALUES ('grp-d2', 0, 6, 'Glass Harbour', 'Tideline', 2, 'pending', 0.93)
+	`); err != nil {
+		t.Fatalf("insert disc two: %v", err)
+	}
+
+	storeCandidates(t, db, "grp-d2", 6, 0.93)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got == nil {
+		t.Fatal("no match returned")
+	}
+
+	if got.GroupCount != 2 {
+		t.Errorf("groupCount = %d, want 2", got.GroupCount)
+	}
+
+	// Best-first: the 0.95 disc is the one described.
+	if got.GroupKey != "grp-d1" {
+		t.Errorf("described %q, want the higher-scoring grp-d1", got.GroupKey)
+	}
+}
+
+// An album with no local files at all — a pure catalog page — is not
+// a question this can answer.
+func TestMatchForAlbumSaysNothingWithoutAnAlbum(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	for _, id := range []int64{0, -1, 4242} {
+		got, err := svc.MatchForAlbum(id)
+		if err != nil {
+			t.Fatalf("MatchForAlbum(%d): %v", id, err)
+		}
+
+		if got != nil {
+			t.Errorf("MatchForAlbum(%d) = %+v, want nil", id, got)
+		}
+	}
+}

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/config/config.go

@@ -544,7 +544,7 @@ func (c *Config) SetDefaultPage(page string) error {
 		c.General.ApplyDefaults()
 	}
 
-	c.General.DefaultPage = DefaultPage(page)
+	c.General.DefaultPage = View(page)
 
 	if err := c.General.Validate(); err != nil {
 		return fmt.Errorf(
@@ -666,6 +666,124 @@ func (c *Config) SetAllowMeteredCatalogDownload(allow bool) error {
 	return nil
 }
 
+// GetPopupVolume reports whether the bottom bar's volume control is a
+// click-to-open popup rather than an inline slider (#42).
+func (c *Config) GetPopupVolume() bool {
+	if c.General == nil {
+		return false
+	}
+
+	return c.General.PopupVolume
+}
+
+// SetPopupVolume saves the volume control's presentation.
+//
+// Nothing to validate: both values are legal at every width, and the
+// frontend additionally stands the inline slider down below the phone
+// breakpoint whatever this says, because that is about room rather than
+// about preference.
+func (c *Config) SetPopupVolume(popup bool) error {
+	if c.General == nil {
+		c.General = &GeneralConfig{}
+		c.General.ApplyDefaults()
+	}
+
+	c.General.PopupVolume = popup
+
+	if err := c.Save(); err != nil {
+		return fmt.Errorf(
+			"could not save config: %w", err,
+		)
+	}
+
+	events.Emit(
+		c.ctx,
+		events.GeneralConfigChanged,
+		map[string]any{
+			"PopupVolume": popup,
+		},
+	)
+
+	c.logger.Info("volume control presentation updated", "popup", popup)
+
+	return nil
+}
+
+// GetViewVisibility reports which primary views the sidebar should
+// show, answered for every known view rather than only the ones the
+// config mentions -- so the frontend filters on a value and never has
+// to hold a second copy of the defaults.
+func (c *Config) GetViewVisibility() map[string]bool {
+	if c.General == nil {
+		general := &GeneralConfig{}
+		general.ApplyDefaults()
+
+		return general.ResolvedViewVisibility()
+	}
+
+	return c.General.ResolvedViewVisibility()
+}
+
+// SetViewVisible shows or hides one primary view.
+//
+// Two refusals, both about a state the user cannot get out of from the
+// UI they would be left with: Settings is never hideable, and the
+// launch page is never hideable while it is the launch page (change it
+// first). Hiding a view does not make it unreachable -- `navigate`
+// still resolves it, which detail views depend on -- it only takes the
+// nav item away.
+func (c *Config) SetViewVisible(view string, visible bool) error {
+	spec, known := LookupView(view)
+	if !known {
+		return fmt.Errorf("%w: %q", errUnknownView, view)
+	}
+
+	if c.General == nil {
+		c.General = &GeneralConfig{}
+		c.General.ApplyDefaults()
+	}
+
+	if !visible {
+		if !spec.Hideable {
+			return fmt.Errorf("%w: %q", errViewNotHideable, view)
+		}
+
+		if spec.ID == c.General.DefaultPage {
+			return fmt.Errorf("%w: %q", errViewIsLaunchPage, view)
+		}
+	}
+
+	if c.General.ViewVisibility == nil {
+		c.General.ViewVisibility = make(map[string]bool, len(Views))
+	}
+
+	c.General.ViewVisibility[view] = visible
+
+	if err := c.General.Validate(); err != nil {
+		return fmt.Errorf("invalid view visibility: %w", err)
+	}
+
+	if err := c.Save(); err != nil {
+		return fmt.Errorf("could not save config: %w", err)
+	}
+
+	events.Emit(
+		c.ctx,
+		events.GeneralConfigChanged,
+		map[string]any{
+			"ViewVisibility": c.General.ResolvedViewVisibility(),
+		},
+	)
+
+	c.logger.Info(
+		"view visibility updated",
+		"view", view,
+		"visible", visible,
+	)
+
+	return nil
+}
+
 // GetTrackListColumns returns the configured track-list columns.
 func (c *Config) GetTrackListColumns() []tracklist.Column {
 	if c.TrackList == nil {

backend/config/emit_test.go

@@ -188,3 +188,43 @@ func TestEmit_FavoritesChangeCarriesFullConfig(t *testing.T) {
 		}
 	}
 }
+
+// TestEmit_PopupVolumeRoundTripsAndDefaultsToInline pins both halves of
+// #42's storage decision.
+//
+// The **default** is the load-bearing one: inline is what a fresh
+// install and an existing `config.toml` with no such key must both
+// produce, which is why the field names the popup rather than the
+// inline slider. A flag spelled the other way round would default to
+// false, hand every existing install the popup this issue exists to
+// stop being the only option, and need a migration to say otherwise.
+func TestEmit_PopupVolumeRoundTripsAndDefaultsToInline(t *testing.T) {
+	t.Parallel()
+
+	conf, rec := setupRecordedConfig(t)
+
+	if conf.GetPopupVolume() {
+		t.Error("a config with no PopupVolume key wants the popup, want inline")
+	}
+
+	if err := conf.SetPopupVolume(true); err != nil {
+		t.Fatalf("SetPopupVolume: %v", err)
+	}
+
+	if !conf.GetPopupVolume() {
+		t.Error("GetPopupVolume = false after setting it true")
+	}
+
+	data := payloadMap(t, rec, events.GeneralConfigChanged)
+	if data["PopupVolume"] != true {
+		t.Errorf("PopupVolume = %v, want true", data["PopupVolume"])
+	}
+
+	if err := conf.SetPopupVolume(false); err != nil {
+		t.Fatalf("SetPopupVolume(false): %v", err)
+	}
+
+	if conf.GetPopupVolume() {
+		t.Error("GetPopupVolume = true after setting it false")
+	}
+}

backend/config/general.go

@@ -5,27 +5,13 @@ import (
 	"fmt"
 )
 
-// DefaultPage identifies which view the app opens to on launch.
-type DefaultPage string
-
-// Valid DefaultPage values, matching the frontend's top-level route ids.
-const (
-	DefaultPageHome      DefaultPage = "home"
-	DefaultPageTracks    DefaultPage = "tracks"
-	DefaultPageAlbums    DefaultPage = "albums"
-	DefaultPageArtists   DefaultPage = "artists"
-	DefaultPageGenres    DefaultPage = "genres"
-	DefaultPagePlaylists DefaultPage = "playlists"
-	DefaultPageExplore   DefaultPage = "explore"
-	DefaultPageDownloads DefaultPage = "downloads"
-	DefaultPageAutotag   DefaultPage = "autotag"
-	DefaultPageJobs      DefaultPage = "jobs"
-)
-
 // DefaultDefaultPage is the launch page for a fresh install.
-const DefaultDefaultPage = DefaultPageHome
+const DefaultDefaultPage = ViewHome
 
-var errUnknownDefaultPage = errors.New("unknown default page")
+var (
+	errUnknownDefaultPage = errors.New("unknown default page")
+	errViewCannotLaunch   = errors.New("view cannot be the launch page")
+)
 
 // QueueFallback identifies what plays, if anything, once the queue
 // runs out with nothing left to auto-advance to.
@@ -46,18 +32,52 @@ var errUnknownQueueFallback = errors.New("unknown queue fallback")
 // GeneralConfig holds general application preferences that don't
 // belong to a more specific subsystem.
 type GeneralConfig struct {
-	DefaultPage   DefaultPage   `toml:"DefaultPage"`
+	DefaultPage   View          `toml:"DefaultPage"`
 	QueueFallback QueueFallback `toml:"QueueFallback"`
+	// ViewVisibility says which sidebar destinations are shown, keyed by
+	// view id.
+	//
+	// **An absent key means that view's own default** (`Views`), and that
+	// is the whole reason this is a map rather than a `HiddenViews
+	// []string` or a struct of booleans. A list's zero value is "hide
+	// nothing", which cannot express Autotag being off by default without
+	// a migration; a struct field for a view that later stops existing is
+	// stored garbage somebody has to deprecate. Here a view added later
+	// gets its own default rather than being invisible or forcibly
+	// visible, an unknown key is dropped on load, and no install needs
+	// migrating in either direction. Same polarity rule as
+	// AllowMeteredCatalogDownload: the zero value is the intended answer.
+	ViewVisibility map[string]bool `toml:"ViewVisibility"`
 	// AllowMeteredCatalogDownload permits the ~0.6 GB Explore catalog to
 	// be fetched on a connection the platform calls cellular. It defaults
 	// to false, which is the whole point: the zero value is the safe one,
 	// so an existing config with no such key refuses by default rather
 	// than needing a migration to become careful.
 	AllowMeteredCatalogDownload bool `toml:"AllowMeteredCatalogDownload"`
+	// PopupVolume draws the bottom bar's volume as a click-to-open popup
+	// instead of a slider that is always there (#42).
+	//
+	// The polarity is the rule this file already states twice: **the
+	// zero value is the intended answer**. Inline is the new default, so
+	// the flag has to name the *other* choice — an `InlineVolume bool`
+	// would default to false and give every existing install the popup
+	// this issue exists to stop being the only option, and would need a
+	// migration to say otherwise.
+	PopupVolume bool `toml:"PopupVolume"`
 }
 
 // ApplyDefaults fills zero-value fields with sensible defaults.
+//
+// A launch page naming a *retired* view is treated as a zero value
+// rather than as an error, because the alternative is an app that will
+// not start for anyone who had that page selected when it was removed.
+// An unknown-but-not-retired name still fails Validate: that is a typo,
+// and telling someone about it is the useful answer.
 func (c *GeneralConfig) ApplyDefaults() {
+	if _, retired := RetiredViews[c.DefaultPage]; retired {
+		c.DefaultPage = ""
+	}
+
 	if c.DefaultPage == "" {
 		c.DefaultPage = DefaultDefaultPage
 	}
@@ -71,15 +91,17 @@ func (c *GeneralConfig) ApplyDefaults() {
 func (c *GeneralConfig) Validate() error {
 	c.ApplyDefaults()
 
-	switch c.DefaultPage {
-	case DefaultPageHome, DefaultPageTracks, DefaultPageAlbums, DefaultPageArtists,
-		DefaultPageGenres, DefaultPagePlaylists, DefaultPageExplore, DefaultPageDownloads,
-		DefaultPageAutotag, DefaultPageJobs:
-		// Valid.
-	default:
+	spec, known := LookupView(string(c.DefaultPage))
+	if !known {
 		return fmt.Errorf("%w: %q", errUnknownDefaultPage, c.DefaultPage)
 	}
 
+	if !spec.CanLaunch {
+		return fmt.Errorf("%w: %q", errViewCannotLaunch, c.DefaultPage)
+	}
+
+	c.normalizeViewVisibility()
+
 	switch c.QueueFallback {
 	case QueueFallbackStop, QueueFallbackFavorites, QueueFallbackDynamicMix:
 		// Valid.
@@ -89,3 +111,51 @@ func (c *GeneralConfig) Validate() error {
 
 	return nil
 }
+
+// normalizeViewVisibility drops what the stored map may not say, and
+// repairs the one invariant the shell depends on.
+//
+// Three things are dropped or forced, and all three are reachable only
+// from a hand-edited config or from a version that knew different
+// views: an unknown id (a view removed since, e.g. when #27 folds Jobs
+// into Settings) says nothing to anybody; a view that is not Hideable
+// cannot be false; and **the launch page is always visible**, because
+// otherwise an install lands on a page with no nav item pointing at it.
+//
+// That last one is a *repair* here and an *error* at the setter
+// (SetViewVisible), deliberately. On load there is nobody to tell and
+// the honest reading of "my launch page is Autotag" is that this user
+// wants Autotag, so it is un-hidden rather than the launch page being
+// silently reset to something they did not choose. At the setter the
+// user is right there and can act, so it refuses and says why.
+func (c *GeneralConfig) normalizeViewVisibility() {
+	for id := range c.ViewVisibility {
+		spec, known := LookupView(id)
+		if !known || !spec.Hideable {
+			delete(c.ViewVisibility, id)
+		}
+	}
+
+	if visible, ok := c.ViewVisibility[string(c.DefaultPage)]; ok && !visible {
+		c.ViewVisibility[string(c.DefaultPage)] = true
+	}
+}
+
+// ResolvedViewVisibility answers for every known view, so no caller has
+// to know the defaults -- the frontend included, which is why the
+// binding returns this rather than the stored map.
+func (c *GeneralConfig) ResolvedViewVisibility() map[string]bool {
+	resolved := make(map[string]bool, len(Views))
+
+	for _, v := range Views {
+		visible := v.VisibleByDefault
+
+		if stored, ok := c.ViewVisibility[string(v.ID)]; ok && v.Hideable {
+			visible = stored
+		}
+
+		resolved[string(v.ID)] = visible
+	}
+
+	return resolved
+}

backend/config/views.go

@@ -0,0 +1,103 @@
+package config
+
+import "errors"
+
+var (
+	errUnknownView      = errors.New("unknown view")
+	errViewNotHideable  = errors.New("view cannot be hidden")
+	errViewIsLaunchPage = errors.New("view is the launch page")
+)
+
+// View identifies one of the shell's primary destinations -- the
+// things the sidebar lists and `index.ts` knows as `VIEW_TAGS`.
+type View string
+
+// The primary views, in no particular order: the sidebar owns the order
+// it draws them in, because that is presentation.
+const (
+	ViewHome      View = "home"
+	ViewPlaylists View = "playlists"
+	ViewArtists   View = "artists"
+	ViewGenres    View = "genres"
+	ViewAlbums    View = "albums"
+	ViewTracks    View = "tracks"
+	ViewExplore   View = "explore"
+	ViewDownloads View = "downloads"
+	ViewAutotag   View = "autotag"
+	ViewSettings  View = "settings"
+)
+
+// RetiredViews are destinations that used to exist and no longer do.
+//
+// A *visibility* entry for a removed view needs no such list: it is a
+// key in a map, and an unknown key is dropped on load. A `DefaultPage`
+// is a **value**, and an unknown one fails validation -- which on the
+// load path means the app refuses to start rather than a setting being
+// ignored. So the one shape that cannot be retired for free is named
+// here and reset to the default instead.
+//
+// `jobs` was folded into Settings by #27: library scans under
+// Libraries, index work under Search Index, downloads under the
+// download clients, and the autotag apply into the Autotag view.
+var RetiredViews = map[View]struct{}{
+	"jobs": {},
+}
+
+// ViewSpec is what the backend knows about a destination. The label and
+// the icon are deliberately absent: those are presentation, they live
+// beside the rest of the app's icon vocabulary in
+// `frontend/src/utils/icon-language.ts`, and a Go copy of them would be
+// a second thing to keep in step for nothing.
+type ViewSpec struct {
+	// ID is the view name the frontend navigates by.
+	ID View
+	// VisibleByDefault is what an install gets when the config says
+	// nothing about this view -- which is every install until somebody
+	// changes it, and every view added after this one shipped.
+	VisibleByDefault bool
+	// Hideable is false for Settings alone. It is a property of the
+	// view rather than a check in the setter because `config.toml` is
+	// hand-editable, and an app that can be locked out of its own
+	// Settings by a typo is a support problem nobody can debug
+	// remotely.
+	Hideable bool
+	// CanLaunch reports whether the view may be the launch page.
+	// Settings is the only one that may not, which is the shape the
+	// DefaultPage enum already had.
+	CanLaunch bool
+}
+
+// Views is the one list of primary destinations, in the order Settings
+// offers them.
+//
+// It is the single source for three things that used to be written down
+// separately: which views exist, which of them may be the launch page
+// (`DefaultPage`'s validation reads it), and what an unconfigured
+// install shows.
+//
+// Autotag is the one view hidden by default: it rewrites tags on disk,
+// which is not what most libraries want on day one, and #25 asks for it
+// to be turned on deliberately.
+var Views = []ViewSpec{
+	{ID: ViewHome, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewPlaylists, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewArtists, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewGenres, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewAlbums, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewTracks, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewExplore, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewDownloads, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewAutotag, VisibleByDefault: false, Hideable: true, CanLaunch: true},
+	{ID: ViewSettings, VisibleByDefault: true, Hideable: false, CanLaunch: false},
+}
+
+// LookupView returns the spec for a view id.
+func LookupView(id string) (ViewSpec, bool) {
+	for _, v := range Views {
+		if string(v.ID) == id {
+			return v, true
+		}
+	}
+
+	return ViewSpec{}, false
+}

backend/config/views_test.go

@@ -0,0 +1,307 @@
+package config
+
+import (
+	"errors"
+	"log/slog"
+	"path/filepath"
+	"testing"
+)
+
+// newViewTestConfig builds a Config backed by a temp file, which is all
+// SetViewVisible needs: it saves and emits, and the emit is a no-op
+// without a running app.
+func newViewTestConfig(t *testing.T) *Config {
+	t.Helper()
+
+	c := &Config{
+		logger:   slog.Default(),
+		filePath: filepath.Join(t.TempDir(), "config.toml"),
+	}
+
+	// Load a file that is not there: that is what marks the config
+	// loaded, without which Save refuses on the *second* write.
+	if err := c.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	return c
+}
+
+// A view the config says nothing about takes its own default, which is
+// what makes this need no migration in either direction: an existing
+// install gets Autotag hidden without a key, and a view added later
+// gets its own answer rather than the list's.
+func TestViewVisibilityDefaults(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{}
+	general.ApplyDefaults()
+
+	resolved := general.ResolvedViewVisibility()
+
+	if len(resolved) != len(Views) {
+		t.Fatalf("resolved %d views, want %d", len(resolved), len(Views))
+	}
+
+	if resolved[string(ViewAutotag)] {
+		t.Error("autotag should be hidden by default")
+	}
+
+	for _, v := range Views {
+		if v.ID == ViewAutotag {
+			continue
+		}
+
+		if !resolved[string(v.ID)] {
+			t.Errorf("%s should be visible by default", v.ID)
+		}
+	}
+}
+
+// A stored answer wins over the default, in both directions -- turning
+// Autotag on is the whole user-facing point.
+func TestViewVisibilityStoredWins(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{
+		ViewVisibility: map[string]bool{
+			string(ViewAutotag): true,
+			string(ViewExplore): false,
+		},
+	}
+	general.ApplyDefaults()
+
+	resolved := general.ResolvedViewVisibility()
+
+	if !resolved[string(ViewAutotag)] {
+		t.Error("autotag was switched on and should be visible")
+	}
+
+	if resolved[string(ViewExplore)] {
+		t.Error("explore was switched off and should be hidden")
+	}
+}
+
+// A key for a view that no longer exists is discarded rather than
+// migrated. This is the property the #25-before-#27 ordering rests on:
+// when Jobs folds into Settings, `jobs = true` in somebody's config is
+// a key nothing asks about, not a cleanup task.
+func TestValidateDropsUnknownAndUnhideableViews(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{
+		ViewVisibility: map[string]bool{
+			"a-view-that-was-removed": true,
+			string(ViewSettings):      false,
+			string(ViewAutotag):       true,
+		},
+	}
+
+	if err := general.Validate(); err != nil {
+		t.Fatalf("Validate() error: %v", err)
+	}
+
+	if _, ok := general.ViewVisibility["a-view-that-was-removed"]; ok {
+		t.Error("an unknown view id should be dropped on load")
+	}
+
+	if _, ok := general.ViewVisibility[string(ViewSettings)]; ok {
+		t.Error("settings is not hideable and should not be stored")
+	}
+
+	if !general.ResolvedViewVisibility()[string(ViewSettings)] {
+		t.Error("settings must resolve visible whatever the file said")
+	}
+}
+
+// On load there is nobody to tell, so a launch page hidden by a
+// hand-edited file is un-hidden rather than the launch page being
+// reset to something the user did not choose.
+func TestValidateRevealsAHiddenLaunchPage(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{
+		DefaultPage: ViewAutotag,
+		ViewVisibility: map[string]bool{
+			string(ViewAutotag): false,
+		},
+	}
+
+	if err := general.Validate(); err != nil {
+		t.Fatalf("Validate() error: %v", err)
+	}
+
+	if !general.ResolvedViewVisibility()[string(ViewAutotag)] {
+		t.Error("the launch page must be visible")
+	}
+}
+
+// A launch page naming a view that no longer exists resets to the
+// default instead of failing validation, which on the load path would
+// mean the app refusing to start for whoever had it selected.
+//
+// This is the one shape #25's storage decision does *not* make free: a
+// visibility entry is a key and an unknown key is dropped, but a launch
+// page is a value.
+func TestARetiredLaunchPageFallsBackToTheDefault(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{DefaultPage: "jobs"}
+
+	if err := general.Validate(); err != nil {
+		t.Fatalf("Validate() error: %v", err)
+	}
+
+	if general.DefaultPage != DefaultDefaultPage {
+		t.Errorf("DefaultPage = %q, want %q", general.DefaultPage, DefaultDefaultPage)
+	}
+}
+
+// A name that is merely wrong is still an error: that is a typo, and
+// saying so is more useful than ignoring it.
+func TestAnUnknownLaunchPageIsStillAnError(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{DefaultPage: "nonsense"}
+
+	if err := general.Validate(); !errors.Is(err, errUnknownDefaultPage) {
+		t.Fatalf("Validate() error = %v, want errUnknownDefaultPage", err)
+	}
+}
+
+// A retired view is not a view, so nothing offers it and nothing
+// resolves it -- the visibility map included.
+func TestARetiredViewIsGone(t *testing.T) {
+	t.Parallel()
+
+	for id := range RetiredViews {
+		if _, ok := LookupView(string(id)); ok {
+			t.Errorf("%s is retired but still in Views", id)
+		}
+
+		general := &GeneralConfig{}
+		general.ApplyDefaults()
+
+		if _, ok := general.ResolvedViewVisibility()[string(id)]; ok {
+			t.Errorf("%s is retired but still resolves a visibility", id)
+		}
+	}
+}
+
+// Settings may not be the launch page, which is the shape the old
+// DefaultPage enum had and is now read off the same table.
+func TestValidateRejectsAnUnlaunchablePage(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{DefaultPage: ViewSettings}
+
+	err := general.Validate()
+	if !errors.Is(err, errViewCannotLaunch) {
+		t.Fatalf("Validate() error = %v, want errViewCannotLaunch", err)
+	}
+}
+
+// At the setter the user is present and can act, so the two states
+// they could not get out of are refused rather than repaired.
+func TestSetViewVisibleRefusals(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		view    string
+		visible bool
+		want    error
+	}{
+		{"settings is never hideable", string(ViewSettings), false, errViewNotHideable},
+		{"the launch page is not hideable", string(ViewHome), false, errViewIsLaunchPage},
+		{"an unknown view is not a setting", "nonsense", false, errUnknownView},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			c := newViewTestConfig(t)
+
+			err := c.SetViewVisible(tt.view, tt.visible)
+			if !errors.Is(err, tt.want) {
+				t.Fatalf("SetViewVisible() error = %v, want %v", err, tt.want)
+			}
+		})
+	}
+}
+
+// Showing a view is never refused, including Settings and the launch
+// page -- there is no state to be stuck in.
+func TestSetViewVisibleShowsAnything(t *testing.T) {
+	t.Parallel()
+
+	c := newViewTestConfig(t)
+
+	for _, v := range Views {
+		if err := c.SetViewVisible(string(v.ID), true); err != nil {
+			t.Fatalf("SetViewVisible(%q, true) error: %v", v.ID, err)
+		}
+	}
+
+	if !c.GetViewVisibility()[string(ViewAutotag)] {
+		t.Error("autotag was switched on and should be visible")
+	}
+}
+
+// The stored map survives a save/load round trip, which is what a
+// map-valued TOML key is worth checking for.
+func TestViewVisibilityRoundTrips(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "config.toml")
+
+	original := &Config{logger: slog.Default(), filePath: path}
+	if err := original.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	if err := original.SetViewVisible(string(ViewAutotag), true); err != nil {
+		t.Fatalf("SetViewVisible() error: %v", err)
+	}
+
+	if err := original.SetViewVisible(string(ViewExplore), false); err != nil {
+		t.Fatalf("SetViewVisible() error: %v", err)
+	}
+
+	loaded := &Config{logger: slog.Default(), filePath: path}
+	if err := loaded.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	resolved := loaded.GetViewVisibility()
+
+	if !resolved[string(ViewAutotag)] {
+		t.Error("autotag should have loaded as visible")
+	}
+
+	if resolved[string(ViewExplore)] {
+		t.Error("explore should have loaded as hidden")
+	}
+}
+
+// Every view the shell can launch into is a view the sidebar can show,
+// or an install could land on a page with no nav item and no setting
+// pointing at it.
+func TestEveryLaunchableViewIsAView(t *testing.T) {
+	t.Parallel()
+
+	for _, v := range Views {
+		if !v.CanLaunch {
+			continue
+		}
+
+		if !v.Hideable {
+			continue
+		}
+
+		if _, ok := LookupView(string(v.ID)); !ok {
+			t.Errorf("%s is launchable but not a known view", v.ID)
+		}
+	}
+}

backend/config/window.go

@@ -13,13 +13,31 @@ const (
 	// enforces this at runtime; it is also the floor below which a
 	// reported size is treated as bogus and not persisted.
 	//
-	// 800x600 is where the shell was measured to still work, rather
-	// than a round number: below ~780 the header's subtitle wraps and
-	// pushes the title out of the 4em top bar, and below ~600 tall the
-	// eleven sidebar items no longer fit at once.  The previous
-	// 512x384 was aspirational — at 700x480 the sidebar overflowed
-	// behind the player bar with no scroll and Settings and Jobs could
-	// not be reached at all.
+	// **Both reasons this comment used to give have expired**, and the
+	// value is right for a third one.  It said the floor was 800x600
+	// because "below ~780 the header's subtitle wraps and pushes the
+	// title out of the 4em top bar" and "below ~600 tall the eleven
+	// sidebar items no longer fit at once".  Neither mechanism can
+	// happen now: the subtitle is display:none from 899px down
+	// (index.css), and the sidebar host is overflow-y:auto — measured
+	// at 600x460, its scrollHeight is 434 against a 332px client and
+	// Settings is reachable after scrolling.  A floor defended by two
+	// mechanisms that no longer exist is a number nobody can argue
+	// with, which is worse than either answer.
+	//
+	// It stays 800x600 because that is where the *desktop* chrome
+	// stops being comfortable — the Compact band of plan 018's size
+	// matrix (#24) — and not because the app breaks below it.  It does
+	// not: under 600px wide the phone layout takes over (bottom-nav,
+	// no sidebar) and the shell fits 320px exactly, which is what
+	// makes this a comfort floor rather than a correctness one, and
+	// why a very small window reflows instead of becoming a
+	// mini-player (#12 is a second always-on-top window, not a mode of
+	// this one).
+	//
+	// The previous 512x384 was aspirational — at 700x480 the sidebar
+	// overflowed behind the player bar with no scroll and Settings and
+	// Jobs could not be reached at all.
 	MinWidth = 800
 	// MinHeight is the smallest allowed window height in pixels.
 	MinHeight = 600

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/queries/tagging_items.sql

@@ -342,3 +342,35 @@ WHERE ti.status = 'pending'
   )
 ORDER BY ti.group_key
 LIMIT 1;
+
+-- name: GetTaggingItemsForAlbum :many
+-- Every tagging group holding a file of this album.
+--
+-- The join is `audio_files.group_key`, not a key derived from the
+-- album's folder path: a group carved out of a mixed-bag folder by
+-- SplitMixedFolder is keyed on its tags rather than on a directory,
+-- so a path-derived key finds nothing for exactly the messiest
+-- libraries this is meant to help.
+--
+-- Usually one row. A multi-disc album is one group per disc, which
+-- the caller has to know about rather than average over -- applying
+-- to "the album" would silently retag one disc of three.
+SELECT
+  ti.group_key,
+  ti.status,
+  ti.score,
+  ti.best_match_release_mbid,
+  ti.track_count,
+  ti.album_name,
+  ti.album_artist,
+  ti.synthetic
+FROM tagging_items ti
+WHERE ti.group_key IN (
+    SELECT DISTINCT af.group_key
+    FROM audio_files af
+    WHERE af.album_id = sqlc.arg(album_id) AND af.group_key != ''
+  )
+  AND ti.cleared_at IS NULL
+-- Best first, with an unscored group last rather than first: NULL
+-- sorts low in SQLite and DESC would put it at the top.
+ORDER BY ti.score IS NULL, ti.score DESC, ti.group_key;

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/database/sql/sqlcgen/tagging_items.sql.go

@@ -231,6 +231,82 @@ func (q *Queries) GetTaggingItem(ctx context.Context, groupKey string) (TaggingI
 	return i, err
 }
 
+const getTaggingItemsForAlbum = `-- name: GetTaggingItemsForAlbum :many
+SELECT
+  ti.group_key,
+  ti.status,
+  ti.score,
+  ti.best_match_release_mbid,
+  ti.track_count,
+  ti.album_name,
+  ti.album_artist,
+  ti.synthetic
+FROM tagging_items ti
+WHERE ti.group_key IN (
+    SELECT DISTINCT af.group_key
+    FROM audio_files af
+    WHERE af.album_id = ?1 AND af.group_key != ''
+  )
+  AND ti.cleared_at IS NULL
+ORDER BY ti.score IS NULL, ti.score DESC, ti.group_key
+`
+
+type GetTaggingItemsForAlbumRow struct {
+	GroupKey             string
+	Status               string
+	Score                sql.NullFloat64
+	BestMatchReleaseMbid sql.NullString
+	TrackCount           int64
+	AlbumName            string
+	AlbumArtist          string
+	Synthetic            int64
+}
+
+// Every tagging group holding a file of this album.
+//
+// The join is `audio_files.group_key`, not a key derived from the
+// album's folder path: a group carved out of a mixed-bag folder by
+// SplitMixedFolder is keyed on its tags rather than on a directory,
+// so a path-derived key finds nothing for exactly the messiest
+// libraries this is meant to help.
+//
+// Usually one row. A multi-disc album is one group per disc, which
+// the caller has to know about rather than average over -- applying
+// to "the album" would silently retag one disc of three.
+// Best first, with an unscored group last rather than first: NULL
+// sorts low in SQLite and DESC would put it at the top.
+func (q *Queries) GetTaggingItemsForAlbum(ctx context.Context, albumID sql.NullInt64) ([]GetTaggingItemsForAlbumRow, error) {
+	rows, err := q.db.QueryContext(ctx, getTaggingItemsForAlbum, albumID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []GetTaggingItemsForAlbumRow
+	for rows.Next() {
+		var i GetTaggingItemsForAlbumRow
+		if err := rows.Scan(
+			&i.GroupKey,
+			&i.Status,
+			&i.Score,
+			&i.BestMatchReleaseMbid,
+			&i.TrackCount,
+			&i.AlbumName,
+			&i.AlbumArtist,
+			&i.Synthetic,
+		); 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 listAudioFilesInTaggingGroup = `-- name: ListAudioFilesInTaggingGroup :many
 SELECT
   af.id,

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/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/prune_test.go

@@ -82,6 +82,100 @@ func TestPruneStaleLocalCrossReferences(t *testing.T) {
 	}
 }
 
+// TestPruneClearsInLibraryWithNoLocalID covers the fixed point: a row
+// carrying in_library with a NULL local_*_id.  The upsert's conflict
+// clause is `in_library = MAX(in_library, excluded.in_library)`, so it
+// can only ever raise the flag, and this pass used to be gated on the id
+// being present — which meant nothing in the app could clear such a row,
+// ever.  It is asserted for all three entity types because the gate was
+// written once and used three times, so a fix applied to one is a fix
+// that looks complete.
+//
+// The rows are seeded with raw SQL rather than through seedIndexResult
+// deliberately: upsertBatch writes a zero LocalArtistID as literal 0,
+// not NULL, and 0 satisfies `IS NOT NULL` — so the old gate already
+// caught that shape and a fixture built through the upsert cannot
+// reproduce this at all.  NULL is what the artifact importer and any
+// older writer leave behind, the column being nullable with no default.
+func TestPruneClearsInLibraryWithNoLocalID(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, slog.Default())
+
+	// A genuinely owned artist, to prove the wider gate does not simply
+	// clear everything it now looks at.
+	database.InsertTestTrack(t, db, database.TestTrack{
+		FilePath: "/music/owned.mp3",
+		Artist:   "Owned",
+	})
+
+	artist, err := db.Queries.GetArtistByName(t.Context(), "Owned")
+	if err != nil {
+		t.Fatalf("read seeded artist: %v", err)
+	}
+
+	seedIndexResult(t, db, SearchIndexResult{
+		EntityType:    EntityArtist,
+		MBID:          testMBID("owned"),
+		Title:         "Owned",
+		ArtistName:    "Owned",
+		ArtistMBID:    testMBID("owned"),
+		InLibrary:     true,
+		LocalArtistID: artist.ID,
+	})
+
+	orphans := []struct {
+		name       string
+		entityType string
+		mbid       string
+	}{
+		{"artist", EntityArtist, "orphan-artist"},
+		{"release group", EntityReleaseGroup, "orphan-release-group"},
+		{"recording", EntityRecording, "orphan-recording"},
+	}
+
+	for _, o := range orphans {
+		if _, err := db.ExecContext(
+			`INSERT INTO explore_index
+			     (entity_type, mbid, title, artist_name, artist_mbid,
+			      in_library,
+			      local_artist_id, local_release_group_id, local_recording_id)
+			 VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)`,
+			dbEntityType(o.entityType), dbMBID(testMBID(o.mbid)), o.name, o.name,
+			dbMBID(testMBID(o.mbid)),
+			nil, nil, nil,
+		); err != nil {
+			t.Fatalf("seed %s orphan: %v", o.name, err)
+		}
+	}
+
+	si.pruneStaleLocalCrossReferences()
+
+	inLibrary := func(t *testing.T, mbid string) int {
+		t.Helper()
+
+		var flag int
+		if err := db.QueryRowWriter(
+			"SELECT in_library FROM explore_index WHERE mbid = ?", dbMBID(mbid),
+		).Scan(&flag); err != nil {
+			t.Fatalf("read in_library for %q: %v", mbid, err)
+		}
+
+		return flag
+	}
+
+	for _, o := range orphans {
+		if got := inLibrary(t, testMBID(o.mbid)); got != 0 {
+			t.Errorf("%s with a NULL local id: in_library = %d, want 0", o.name, got)
+		}
+	}
+
+	if got := inLibrary(t, testMBID("owned")); got != 1 {
+		t.Errorf("owned artist: in_library = %d, want 1 (it still has a file)", got)
+	}
+}
+
 // TestUnenrichedLibraryArtistMBIDs_OrdersByOwnedTrackCount verifies the
 // backfill queue prioritizes artists by how many tracks the user actually
 // owns, not by how many duplicate-mbid artist rows happen to exist (the

backend/explore/searchindex.go

@@ -2562,6 +2562,19 @@ func (si *SearchIndex) PopulateLocalCrossReferences() {
 // The row itself is left in place (it may still be part of the shipped
 // catalog, just no longer owned) — only the "this is mine" bookkeeping
 // is cleared.
+//
+// It is gated on the flag *or* the id, not on the id alone.  Gated on
+// the id, `in_library = 1 AND local_*_id IS NULL` is a fixed point: the
+// upsert can only ever raise the flag and this pass skipped such a row
+// by construction, so nothing in the app could clear it — a row claiming
+// to be owned, permanently, with no local row to check the claim
+// against.  Nothing in the tree writes that shape today
+// (collectLibraryEntities sets both together), which is exactly why it
+// is worth closing now: the exposure is a database written by an older
+// version, and the next writer that sets the flag without an id, which
+// nothing structurally prevents.  A NULL id fails the existence test on
+// its own, so the wider gate needs no second clause to say what "not
+// owned" means.
 func (si *SearchIndex) pruneStaleLocalCrossReferences() {
 	type prune struct {
 		entityType string
@@ -2594,7 +2607,8 @@ func (si *SearchIndex) pruneStaleLocalCrossReferences() {
 		result, err := si.db.ExecContext(
 			`UPDATE explore_index
 			 SET in_library = 0, `+p.column+` = NULL
-			 WHERE entity_type = ? AND `+p.column+` IS NOT NULL
+			 WHERE entity_type = ?
+			   AND (`+p.column+` IS NOT NULL OR in_library = 1)
 			   AND NOT EXISTS (`+p.exists+`)`,
 			dbEntityType(p.entityType),
 		)

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/player/buffered_stall_test.go

@@ -0,0 +1,188 @@
+package player
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/gopxl/beep/v2"
+)
+
+// errTestDecode stands in for a decoder blowing up mid-track.
+var errTestDecode = errors.New("decode blew up")
+
+// stalledStreamer never produces a sample and never reports
+// end-of-stream: (0, true), forever. A damaged file that decodes to
+// nothing looks like this, and so does any source whose producer has
+// quietly stopped.
+type stalledStreamer struct{}
+
+func (stalledStreamer) Stream(_ [][2]float64) (int, bool) { return 0, true }
+func (stalledStreamer) Err() error                        { return nil }
+
+// failingStreamer produces n good samples and then fails, which is
+// what a decode error mid-track looks like: the same (0, false) a
+// finished track returns, distinguishable only by Err.
+type failingStreamer struct {
+	remaining int
+	err       error
+}
+
+func (f *failingStreamer) Stream(samples [][2]float64) (int, bool) {
+	if f.remaining <= 0 {
+		return 0, false
+	}
+
+	n := min(len(samples), f.remaining)
+
+	for i := range n {
+		samples[i] = [2]float64{1, 1}
+	}
+
+	f.remaining -= n
+
+	return n, true
+}
+
+func (f *failingStreamer) Err() error { return f.err }
+
+// drainUntilEnd calls Stream until it reports end-of-stream, or gives
+// up. It returns whether the stream ended.
+//
+// The give-up bound is wall clock rather than a call count: the stall
+// budget is a duration, so a tight loop has to actually wait it out.
+func drainUntilEnd(bs *BufferedStreamer, within time.Duration) bool {
+	buf := make([][2]float64, 512)
+	deadline := time.Now().Add(within)
+
+	for time.Now().Before(deadline) {
+		if _, ok := bs.Stream(buf); !ok {
+			return true
+		}
+
+		time.Sleep(time.Millisecond)
+	}
+
+	return false
+}
+
+// A source that stops producing without ever ending is the fault this
+// whole file exists for: Stream used to answer with silence and ok
+// forever, so the chain never ended, the player stayed in Playing
+// with the button showing pause, and the decoder's position never
+// moved -- a frozen seek bar over a track that was not playing.
+func TestAStalledSourceEndsTheStream(t *testing.T) {
+	bs := NewBufferedStreamer(stalledStreamer{}, 2048)
+	defer bs.Close()
+
+	if !drainUntilEnd(bs, maxStarvedDuration+2*time.Second) {
+		t.Fatal(
+			"a stalled source never ended the stream: the player " +
+				"would sit in Playing with a frozen position",
+		)
+	}
+
+	if !errors.Is(bs.Err(), errSourceStalled) {
+		t.Fatalf(
+			"expected the stall to be reported, got %v", bs.Err(),
+		)
+	}
+}
+
+// Close is the other exit that used to leave `done` false, with the
+// same consequence: the ring drains and every call after it is
+// silence that claims to be audio.
+func TestClosingEndsTheStream(t *testing.T) {
+	bs := NewBufferedStreamer(finiteStreamer(1<<20), 2048)
+
+	// Let the read-ahead fill something, so this exercises the drain
+	// after Close rather than a buffer that was empty anyway.
+	time.Sleep(20 * time.Millisecond)
+	bs.Close()
+
+	if !drainUntilEnd(bs, 2*time.Second) {
+		t.Fatal("a closed streamer never reported end-of-stream")
+	}
+}
+
+// A source that fails is not a source that finished, and only Err
+// tells them apart. Before this, the player reported a mid-track
+// decode failure to the queue as a natural end, so the queue
+// auto-advanced in silence and counted the broken track as played.
+func TestAFailedSourceReportsItsError(t *testing.T) {
+	src := &failingStreamer{remaining: 4096, err: errTestDecode}
+
+	bs := NewBufferedStreamer(src, 2048)
+	defer bs.Close()
+
+	if !drainUntilEnd(bs, 2*time.Second) {
+		t.Fatal("a failing source never reported end-of-stream")
+	}
+
+	if !errors.Is(bs.Err(), errTestDecode) {
+		t.Fatalf(
+			"expected the source's error to survive, got %v",
+			bs.Err(),
+		)
+	}
+}
+
+// The ordinary case has to keep working: a source that ends cleanly
+// ends with no error, or every finished track would be reported as a
+// failure and skipped.
+func TestADrainedSourceReportsNoError(t *testing.T) {
+	bs := NewBufferedStreamer(finiteStreamer(4096), 2048)
+	defer bs.Close()
+
+	if !drainUntilEnd(bs, 2*time.Second) {
+		t.Fatal("a finite source never reported end-of-stream")
+	}
+
+	if bs.Err() != nil {
+		t.Fatalf(
+			"a track that finished normally reported %v", bs.Err(),
+		)
+	}
+}
+
+// A slow source is exactly what the read-ahead exists to absorb, so
+// underruns must not be charged cumulatively -- otherwise a file on a
+// slow disk ends itself partway through.
+func TestUnderrunsDoNotAccumulateAcrossASlowSource(t *testing.T) {
+	const total = 8192
+
+	src := &slowStreamer{
+		inner: finiteStreamer(total),
+		delay: 2 * time.Millisecond,
+	}
+
+	bs := NewBufferedStreamer(src, 1024)
+	defer bs.Close()
+
+	buf := make([][2]float64, 256)
+	got := 0
+
+	for {
+		n, ok := bs.Stream(buf)
+		if !ok {
+			break
+		}
+
+		for i := range n {
+			if buf[i][0] != 0 {
+				got++
+			}
+		}
+	}
+
+	if got != total {
+		t.Fatalf(
+			"a slow but healthy source was cut short: got %d of %d "+
+				"samples",
+			got, total,
+		)
+	}
+}
+
+// beep.Streamer is what the player wraps; keep the type honest.
+var _ beep.Streamer = (*BufferedStreamer)(nil)

backend/player/buffered_streamer.go

@@ -1,6 +1,7 @@
 package player
 
 import (
+	"errors"
 	"sync"
 	"time"
 
@@ -34,8 +35,45 @@ type BufferedStreamer struct {
 	done    bool
 	err     error
 	closed  chan struct{}
+
+	// starved counts consecutive Stream calls served with silence
+	// because the ring was empty, and starvedSince is when that run
+	// began.  An underrun is legitimate for a moment -- that is what
+	// the read-ahead exists to absorb -- but it is not legitimate
+	// forever, and "forever" is indistinguishable from healthy
+	// playback everywhere above this type: the chain never ends, so
+	// the player stays in Playing with the button showing pause, and
+	// the decoder's position never moves, so the 1 Hz report pins the
+	// seek bar and suppresses its interpolation.
+	starved      int
+	starvedSince time.Time
 }
 
+// The silence fill is bounded by both a duration and a run of calls,
+// and it needs both.
+//
+// Duration alone is the real measure -- the speaker paces itself, so
+// wall clock is what says whether the source has actually stopped --
+// but a caller draining in a tight loop (a test, a decode-to-buffer)
+// makes hundreds of calls in microseconds and would trip nothing.
+// A call count alone is the opposite failure: the same tight loop
+// spends the whole budget before the read-ahead goroutine has been
+// scheduled once, and ends a perfectly good stream at sample zero.
+//
+// The duration is longer than the 2 s read-ahead it is there to
+// outlast, and the count is short enough that the speaker (~200 ms a
+// call) reaches it well inside that.
+const (
+	maxStarvedDuration = 3 * time.Second
+	minStarvedCalls    = 8
+)
+
+// errSourceStalled is returned by Err when the source stopped
+// producing samples without ever reporting end-of-stream.
+var errSourceStalled = errors.New(
+	"audio source stopped producing samples",
+)
+
 // NewBufferedStreamer creates a BufferedStreamer that pre-fills
 // bufferSize samples from source via a background goroutine.
 // A typical bufferSize is 2× the sample rate (~2 seconds of audio).
@@ -54,8 +92,24 @@ func NewBufferedStreamer(
 	return bs
 }
 
+// finish marks the stream ended, recording err as the reason when
+// there is one.  Every exit from readAhead goes through it: an exit
+// that leaves done false strands Stream in its underrun branch,
+// where it returns silence and ok forever.
+func (bs *BufferedStreamer) finish(err error) {
+	bs.mu.Lock()
+	defer bs.mu.Unlock()
+
+	bs.done = true
+
+	if err != nil && bs.err == nil {
+		bs.err = err
+	}
+}
+
 // readAhead continuously reads from the source into the ring buffer
 // until the source is drained, an error occurs, or Close is called.
+// It always marks the stream done on the way out.
 func (bs *BufferedStreamer) readAhead() {
 	// Temporary buffer for reading from source outside the lock.
 	// 512 samples per chunk keeps the critical section short.
@@ -63,6 +117,13 @@ func (bs *BufferedStreamer) readAhead() {
 
 	tmp := make([][2]float64, chunkSize)
 
+	// Every exit marks the stream done.  An exit that does not is what
+	// stranded Stream in its underrun branch, returning silence and ok
+	// for the rest of the process's life.
+	var exitErr error
+
+	defer func() { bs.finish(exitErr) }()
+
 	for {
 		// Check if closed.
 		select {
@@ -72,6 +133,15 @@ func (bs *BufferedStreamer) readAhead() {
 		}
 
 		bs.mu.Lock()
+
+		// Stream gave up waiting for us.  Nothing downstream is
+		// listening any more, so filling the ring is work for nobody.
+		if bs.done {
+			bs.mu.Unlock()
+
+			return
+		}
+
 		space := len(bs.ring) - bs.count
 
 		if space == 0 {
@@ -115,14 +185,12 @@ func (bs *BufferedStreamer) readAhead() {
 		}
 
 		if !ok {
-			bs.mu.Lock()
-			bs.done = true
-
-			if srcErr := bs.source.Err(); srcErr != nil {
-				bs.err = srcErr
-			}
-
-			bs.mu.Unlock()
+			// A drained source and a failed one both land here and are
+			// not the same event: one is a track that ended, the other
+			// is a track that broke.  Err is what tells them apart, and
+			// it is why the player must ask before treating this as a
+			// natural finish.
+			exitErr = bs.source.Err()
 
 			return
 		}
@@ -154,7 +222,27 @@ func (bs *BufferedStreamer) Stream(
 	}
 
 	if bs.count == 0 {
-		// Buffer temporarily empty — fill with silence.
+		// The read-ahead has not caught up.  Silence buys it time --
+		// but only for a bounded stretch, because "forever" is
+		// reported upward as healthy playback and there is no watchdog
+		// above this to notice otherwise.
+		bs.starved++
+
+		if bs.starvedSince.IsZero() {
+			bs.starvedSince = time.Now()
+		}
+
+		if bs.starved >= minStarvedCalls &&
+			time.Since(bs.starvedSince) > maxStarvedDuration {
+			bs.done = true
+
+			if bs.err == nil {
+				bs.err = errSourceStalled
+			}
+
+			return 0, false
+		}
+
 		for i := range samples {
 			samples[i] = [2]float64{}
 		}
@@ -162,6 +250,9 @@ func (bs *BufferedStreamer) Stream(
 		return len(samples), true
 	}
 
+	// Samples arrived, so whatever the stall was, it is over.
+	bs.resetStarvationLocked()
+
 	// Copy available samples from ring buffer.
 	n := len(samples)
 	if n > bs.count {
@@ -197,6 +288,19 @@ func (bs *BufferedStreamer) Flush() {
 	bs.readPos = 0
 	bs.writPos = 0
 	bs.count = 0
+
+	// A seek empties the ring on purpose, and the refill that follows
+	// is exactly the stall the budget exists to tolerate.  Charging it
+	// against a budget the previous underrun already spent would end
+	// the track on a seek near the end of a slow file.
+	bs.resetStarvationLocked()
+}
+
+// resetStarvationLocked forgets an underrun run.  Must be called with
+// bs.mu held.
+func (bs *BufferedStreamer) resetStarvationLocked() {
+	bs.starved = 0
+	bs.starvedSince = time.Time{}
 }
 
 // LockSource blocks the read-ahead goroutine from touching the

backend/player/loadstate_test.go

@@ -0,0 +1,213 @@
+package player
+
+import (
+	"log/slog"
+	"testing"
+	"time"
+
+	"github.com/wailsapp/wails/v3/pkg/application"
+
+	"yellowjacket/backend/events"
+	"yellowjacket/internal/testfixtures"
+)
+
+// fixtureSampleRate is what cmd/gentestdata writes (audio.go).  It is
+// deliberately not the speaker rate, which is what lets these tests
+// tell the decoder's format from the player's default.
+const fixtureSampleRate = 22050
+
+// newTestPlayer is a player with a context and no database, so the
+// track-metadata lookup cannot succeed.
+func newTestPlayer(t *testing.T) *Player {
+	t.Helper()
+
+	p := NewPlayer(slog.Default(), nil)
+	rec := events.NewRecorder()
+
+	_ = p.ServiceStartup(
+		events.WithSink(t.Context(), rec),
+		application.ServiceOptions{},
+	)
+
+	return p
+}
+
+// loadFileLocked needs no speaker: it decodes, builds the chain and
+// registers it paused. speaker.Play on an uninitialised device is
+// what the integration guard elsewhere is about, so these assert on
+// the state the load computed rather than on playback.
+
+// p.format used to be assigned once, in the constructor, to the
+// *speaker's* rate -- so it claimed 44.1 kHz for every file ever
+// loaded. Play()'s replay-after-finish path resamples from it, so a
+// finished track played again was resampled from a rate the decoder
+// never produced: audibly the wrong speed and pitch, and wrong
+// length and position arithmetic with it.
+//
+// The fixtures are 22050 Hz, which is exactly the point -- any of
+// them disagrees with the speaker rate.
+func TestLoadRecordsTheDecodersOwnFormat(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseCoverDedup)[0]
+
+	p := newTestPlayer(t)
+
+	if got := p.format.SampleRate; got != speakerSampleRate {
+		t.Fatalf(
+			"precondition: a fresh player should hold the speaker "+
+				"rate, got %d",
+			got,
+		)
+	}
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	if p.format.SampleRate == speakerSampleRate {
+		t.Fatalf(
+			"p.format still holds the speaker rate (%d) after "+
+				"loading a %d Hz file: the replay path would "+
+				"resample from the wrong rate",
+			speakerSampleRate, fixtureSampleRate,
+		)
+	}
+
+	if got := int(p.format.SampleRate); got != fixtureSampleRate {
+		t.Errorf(
+			"expected the decoder's rate %d, got %d",
+			fixtureSampleRate, got,
+		)
+	}
+}
+
+// trackLengthMs is written only when the database has a row for the
+// file and cleared only by UnloadTrack, so a track with no row used
+// to inherit whatever the last track's duration was -- and every
+// position report is scaled by it, so the whole seek bar was then
+// reporting one track's progress on another track's scale.
+//
+// There is no database here, so the lookup cannot succeed: exactly
+// the case that used to inherit.
+func TestLoadDoesNotInheritThePreviousTracksDuration(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseCoverDedup)[0]
+
+	p := newTestPlayer(t)
+
+	// Stand in for a previous track whose duration was resolved.
+	p.trackLengthMs = 9_999_000
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	if p.trackLengthMs == 9_999_000 {
+		t.Fatal(
+			"the previous track's duration survived the load: every " +
+				"position report for this track would be scaled by it",
+		)
+	}
+}
+
+// A new chain supersedes the old one's pending finished callback.
+// Without this, a callback that queued for p.mu behind a LoadFile
+// woke up and rewound, stopped and auto-advanced the *new* track.
+func TestANewChainSupersedesTheOldFinishedCallback(t *testing.T) {
+	m := testfixtures.Load(t)
+	paths := m.Case(t, testfixtures.CaseCoverDedup)
+
+	if len(paths) < 2 {
+		t.Skip("need two fixture tracks")
+	}
+
+	p := newTestPlayer(t)
+
+	if err := p.LoadFile(paths[0]); err != nil {
+		t.Fatalf("LoadFile(%s): %v", paths[0], err)
+	}
+
+	stale := p.chainID
+
+	if err := p.LoadFile(paths[1]); err != nil {
+		t.Fatalf("LoadFile(%s): %v", paths[1], err)
+	}
+
+	if p.chainID == stale {
+		t.Fatal("loading a second file did not supersede the chain")
+	}
+
+	called := false
+
+	p.SetPlaybackFinishedHandler(func(error) { called = true })
+
+	// The first track's callback, arriving late.
+	p.onPlaybackFinished(stale, nil)
+
+	if called {
+		t.Error(
+			"a superseded chain's callback drove auto-advance: the " +
+				"track that is loaded now would be skipped",
+		)
+	}
+
+	if p.state == Stopped {
+		t.Error(
+			"a superseded chain's callback stopped the current track",
+		)
+	}
+}
+
+// The decoder is read by the read-ahead goroutine and by every
+// position emit, and those used to be guarded by different mutexes:
+// the read by srcMu, the position by the speaker lock, which
+// read-ahead never takes. Under -race this failed on the emit that
+// LoadFile itself makes.
+//
+// It needs the read-ahead goroutine to actually be running, so it
+// keeps asking for the position for long enough to overlap it.
+func TestPositionReadsDoNotRaceTheReadAhead(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseFLACAlbum)[0]
+
+	p := newTestPlayer(t)
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	for range 200 {
+		if _, err := p.CurrentPositionSeconds(); err != nil {
+			t.Fatalf("CurrentPositionSeconds: %v", err)
+		}
+	}
+}
+
+// Seeking emits the landing position, and that emit reads the
+// decoder -- so the source lock the seek holds must be released
+// before it. A reentrant take here is a deadlock, not a failure,
+// which is why this test exists rather than a comment.
+func TestSeekEmitsWithoutDeadlocking(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseFLACAlbum)[0]
+
+	p := newTestPlayer(t)
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		_ = p.Seek(1)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatal("Seek deadlocked: the position emit re-took the source lock")
+	}
+}

backend/player/player.go

@@ -52,9 +52,17 @@ type Player struct {
 	control                 *beep.Ctrl
 	volume                  *effects.Volume
 	speakerStreamer         beep.Streamer
-	playbackFinishedHandler func()
+	playbackFinishedHandler func(error)
 	trackChangeID           uint64
-	mediaControls           mediacontrols.Handler
+
+	// chainID identifies the streamer chain currently registered with
+	// the speaker.  updateStreamers bumps it, and the finished
+	// callback carries the value it was registered with, so a callback
+	// that queued for p.mu behind a LoadFile can tell that the player
+	// has moved on and return rather than rewinding somebody else's
+	// track.
+	chainID       uint64
+	mediaControls mediacontrols.Handler
 
 	// duckAmount is the attenuation currently applied on top of the
 	// user's volume, in the same base-2 exponent effects.Volume uses.
@@ -180,11 +188,18 @@ func (p *Player) InitSpeaker() error {
 }
 
 // SetPlaybackFinishedHandler sets a callback invoked when a track
-// finishes naturally. This allows the queue to drive auto-advance
+// stops streaming. This allows the queue to drive auto-advance
 // without circular imports.
 //
+// The error says *why* the track stopped: nil for a track that
+// reached its end, non-nil for one that broke partway through.  Both
+// arrive here because both look identical to the speaker, and only
+// the queue holds the metadata a PlaybackFailed needs -- but they are
+// not the same event, and reporting a decode failure as a natural
+// finish is how a broken file used to auto-advance in silence.
+//
 //wails:ignore // internal wiring, not part of the app's IPC surface.
-func (p *Player) SetPlaybackFinishedHandler(handler func()) {
+func (p *Player) SetPlaybackFinishedHandler(handler func(error)) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
@@ -424,6 +439,19 @@ func (p *Player) updateStreamers(
 	newBaseStreamer beep.StreamSeeker,
 	sr beep.SampleRate,
 ) error {
+	// A new chain supersedes the old one, so any finished callback the
+	// old one still owes is stale from here on.
+	p.chainID++
+
+	// The previous read-ahead goroutine reads the same decoder this
+	// one is about to, under its own srcMu -- two goroutines, two
+	// mutexes, one decoder that is not safe for concurrent use.  The
+	// replay-after-finish path rebuilds from p.seeker without going
+	// through LoadFile, which is where that pair could meet.
+	if p.buffered != nil {
+		p.buffered.Close()
+	}
+
 	// set base streamer
 	p.baseStreamer = newBaseStreamer
 	p.seeker = newBaseStreamer
@@ -474,23 +502,57 @@ func (p *Player) startPaused() {
 	p.control.Paused = true
 	speaker.Unlock()
 
+	// Captured, not read at callback time: by then p.chainID names
+	// whatever is loaded *now*, which is the thing the guard exists to
+	// distinguish this chain from.
+	chainID := p.chainID
+	buffered := p.buffered
+
 	// The beep.Callback runs with the speaker mutex held, so we
 	// dispatch to a goroutine that can safely acquire p.mu.
 	speaker.Play(beep.Seq(
 		p.speakerStreamer,
 		beep.Callback(func() {
-			go p.onPlaybackFinished()
+			// Asked here rather than under p.mu: this is the chain that
+			// just ended, and by the time the goroutine holds the lock
+			// p.buffered may be a different one.
+			var err error
+			if buffered != nil {
+				err = buffered.Err()
+			}
+
+			go p.onPlaybackFinished(chainID, err)
 		}),
 	))
 
 	p.state = Paused
 }
 
-// onPlaybackFinished handles the natural end of a track. It is
-// called on a new goroutine from the beep callback (which holds
-// the speaker lock) so that it can safely acquire p.mu.
-func (p *Player) onPlaybackFinished() {
+// onPlaybackFinished handles a track that stopped streaming, whether
+// it ended or broke. It is called on a new goroutine from the beep
+// callback (which holds the speaker lock) so that it can safely
+// acquire p.mu.
+//
+// chainID names the streamer chain the callback fired for and srcErr
+// says why it stopped.
+func (p *Player) onPlaybackFinished(chainID uint64, srcErr error) {
 	p.mu.Lock()
+
+	// The player has moved on while this callback queued for the lock
+	// -- a user pressing Next during the last second of a track is
+	// enough. Everything below is about the *current* track: rewinding
+	// the decoder, saying playback stopped, asking the queue to
+	// advance. Doing any of it now would do it to the wrong track.
+	if chainID != p.chainID {
+		p.mu.Unlock()
+		p.logger.Debug(
+			"Ignoring finished callback for a superseded chain",
+			"chain", chainID, "current", p.chainID,
+		)
+
+		return
+	}
+
 	p.state = Stopped
 	handler := p.playbackFinishedHandler
 	mc := p.mediaControls
@@ -501,10 +563,11 @@ func (p *Player) onPlaybackFinished() {
 	// the Stopped state anyway, so this only moves the decoder.
 	p.rewindLocked()
 	p.emitPositionLocked()
-	p.mu.Unlock()
 
-	// Emit Wails events outside the lock — these are non-blocking
-	// calls that don't need player state.
+	// Emitted under p.mu, like every other transition in this file.
+	// Outside it, a Play() taking the lock in the gap emits `playing`
+	// first and this stale `stopped` lands last -- leaving the button
+	// showing play over a track that is audibly running.
 	p.emitPlaybackFinished()
 
 	events.Emit(
@@ -513,6 +576,8 @@ func (p *Player) onPlaybackFinished() {
 		map[string]string{"state": string(Stopped)},
 	)
 
+	p.mu.Unlock()
+
 	// Notify media controls outside the lock. The track just
 	// ended so position is 0.
 	if mc != nil {
@@ -521,12 +586,19 @@ func (p *Player) onPlaybackFinished() {
 		)
 	}
 
-	p.logger.Info("Playback finished naturally")
+	if srcErr != nil {
+		p.logger.Error(
+			"Playback stopped: the audio source failed",
+			"err", srcErr,
+		)
+	} else {
+		p.logger.Info("Playback finished naturally")
+	}
 
 	// Notify queue for auto-advance. Called without p.mu held
 	// because it re-enters the player via LoadFile/Play.
 	if handler != nil {
-		handler()
+		handler(srcErr)
 	}
 }
 
@@ -587,6 +659,18 @@ func (p *Player) loadFileLocked(filePath string) error {
 
 	p.currentFile = f
 
+	// The decoder's own format, kept for the paths that rebuild the
+	// chain later: Play()'s replay branch resamples from it, so a
+	// stale rate there plays a finished track back at the wrong speed.
+	p.format = format
+
+	// The previous track's duration must not outlive it.  This is set
+	// again by emitTrackChanged below, but only when the database has
+	// a row for the file -- and every position this player reports is
+	// scaled by it, so inheriting means every report is wrong by the
+	// ratio between two unrelated tracks.
+	p.trackLengthMs = 0
+
 	if err := p.updateStreamers(
 		streamer, format.SampleRate,
 	); err != nil {
@@ -906,6 +990,8 @@ func (p *Player) CurrentPosition() (int, error) {
 		return 0, errNoAudioFileLoaded
 	}
 
+	defer p.lockSourceLocked()()
+
 	speaker.Lock()
 	pos := math.Round(
 		100.0 * float64(p.seeker.Position()) /
@@ -924,6 +1010,28 @@ func (p *Player) Seek(targetSeconds int) error {
 	return p.seekLocked(targetSeconds)
 }
 
+// lockSourceLocked blocks the read-ahead goroutine from touching the
+// decoder and returns the function that releases it, so a caller can
+// `defer p.lockSourceLocked()()`.
+//
+// Reading the decoder's position is a read *of the decoder*, and the
+// speaker lock does not exclude the read-ahead goroutine -- it never
+// takes it.  That was a genuine data race on every position emit,
+// once a second for the whole of playback.
+//
+// srcMu is not reentrant, so nothing that already holds it may call
+// this; seekSourceLocked exists to keep that region free of emits.
+// Must be called with p.mu held.
+func (p *Player) lockSourceLocked() func() {
+	if p.buffered == nil {
+		return func() {}
+	}
+
+	p.buffered.LockSource()
+
+	return p.buffered.UnlockSource
+}
+
 // rewindLocked returns the decoder to the start of the track without
 // touching playback state.  Must be called with p.mu held.
 func (p *Player) rewindLocked() {
@@ -959,6 +1067,46 @@ func (p *Player) seekLocked(targetSeconds int) error {
 		return fmt.Errorf("cannot get track length: %w", err)
 	}
 
+	// The source lock is released before anything below is emitted:
+	// emitPositionLocked reads the decoder's position and takes the
+	// same lock, which is not reentrant.
+	seekErr := p.seekSourceLocked(targetSeconds, lengthSecs)
+	if seekErr != nil {
+		p.logger.Warn(
+			"Seek failed, playback will start from "+
+				"the beginning",
+			"target-seconds", targetSeconds,
+			"err", seekErr,
+		)
+
+		// The optimistic move the UI already made has to be taken
+		// back, and only the backend knows it did not happen.
+		events.Emit(p.ctx, events.SeekFailed)
+		p.emitPositionLocked()
+
+		return fmt.Errorf("failed to seek: %w", seekErr)
+	}
+
+	if p.mediaControls != nil {
+		p.mediaControls.NotifySeek(targetSeconds)
+	}
+
+	// Report the landing position immediately rather than leaving the
+	// UI to guess until the next tick — this is the half of H-3 that
+	// desynced the seek bar by 30 s over four keyboard seeks.
+	p.emitPositionLocked()
+
+	return nil
+}
+
+// seekSourceLocked moves the decoder and flushes the stale read-ahead
+// behind it.  It owns the source lock for exactly that long and
+// emits nothing, so its caller is free to read the position
+// afterwards.  Must be called with p.mu held.
+func (p *Player) seekSourceLocked(
+	targetSeconds int,
+	lengthSecs int,
+) error {
 	// Block the read-ahead goroutine from reading the source while
 	// we seek it. The decoder (e.g. FLAC's bufseekio.ReadSeeker) is
 	// not safe for concurrent Read+Seek, and read-ahead runs on its
@@ -1014,19 +1162,11 @@ func (p *Player) seekLocked(targetSeconds int) error {
 	if seekErr != nil {
 		speaker.Unlock()
 
-		p.logger.Warn(
-			"Seek failed, playback will start from "+
-				"the beginning",
-			"target-seconds", targetSeconds,
-			"samples", samples,
-			"err", seekErr,
+		p.logger.Debug(
+			"seek rejected by the decoder",
+			"samples", samples, "err", seekErr,
 		)
 
-		// The optimistic move the UI already made has to be taken
-		// back, and only the backend knows it did not happen.
-		events.Emit(p.ctx, events.SeekFailed)
-		p.emitPositionLocked()
-
 		return fmt.Errorf("failed to seek: %w", seekErr)
 	}
 
@@ -1039,15 +1179,6 @@ func (p *Player) seekLocked(targetSeconds int) error {
 		p.buffered.Flush()
 	}
 
-	if p.mediaControls != nil {
-		p.mediaControls.NotifySeek(targetSeconds)
-	}
-
-	// Report the landing position immediately rather than leaving the
-	// UI to guess until the next tick — this is the half of H-3 that
-	// desynced the seek bar by 30 s over four keyboard seeks.
-	p.emitPositionLocked()
-
 	return nil
 }
 
@@ -1140,6 +1271,10 @@ func (p *Player) seekerLengthSecsLocked() (int, error) {
 		return 0, errNoAudioFileLoaded
 	}
 
+	// Len is fixed for the life of the decoder, so unlike Position it
+	// races with nothing and needs no source lock -- which it must not
+	// take anyway: displayPositionSecsLocked calls this while holding
+	// it, and srcMu is not reentrant.
 	speaker.Lock()
 	length := p.seeker.Len() / int(p.format.SampleRate)
 	speaker.Unlock()
@@ -1156,6 +1291,8 @@ func (p *Player) displayPositionSecsLocked() int {
 		return 0
 	}
 
+	defer p.lockSourceLocked()()
+
 	speaker.Lock()
 	pos := p.seeker.Position()
 	total := p.seeker.Len()

backend/queue/fallback_test.go

@@ -83,7 +83,7 @@ func TestFallback_TriggersOnNaturalFinish(t *testing.T) {
 	q.SetFallbackSource(fake)
 
 	q.SetQueue(seedPaths, 0, false, Source{Type: "album", ID: 1, Label: "Seed Album"})
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	waitUntil(t, func() bool { return fake.callCount() == 1 }, "fallback to be resolved")
 	waitUntil(t, func() bool {
@@ -159,7 +159,7 @@ func TestFallback_EmptyResultLeavesQueueExhausted(t *testing.T) {
 	q.SetFallbackSource(fake)
 
 	q.SetQueue(seedPaths, 0, false, Source{})
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	waitUntil(t, func() bool { return fake.callCount() == 1 }, "fallback to be resolved")
 
@@ -193,7 +193,7 @@ func TestFallback_StaleResolutionDiscarded(t *testing.T) {
 	q.SetFallbackSource(fake)
 
 	q.SetQueue(seedPaths, 0, false, Source{})
-	q.OnPlaybackFinished() // starts resolving, blocked on gate
+	q.OnPlaybackFinished(nil) // starts resolving, blocked on gate
 
 	time.Sleep(20 * time.Millisecond) // let the goroutine reach the gate
 

backend/queue/finished_test.go

@@ -0,0 +1,78 @@
+package queue
+
+import (
+	"errors"
+	"testing"
+
+	"yellowjacket/backend/events"
+)
+
+// errTestDecode stands in for a decoder blowing up mid-track.
+var errTestDecode = errors.New("decode blew up")
+
+// currentIndex == -1 against a non-empty queue is a state this
+// package produces on purpose: onQueueExhausted(false) sets it and
+// deliberately leaves the finished track loaded in the player, so it
+// stays on the now-playing bar. Pressing play from there and letting
+// it finish re-enters OnPlaybackFinished with exactly that pair --
+// which used to index q.tracks[-1] and panic, on a goroutine
+// dispatched from the audio callback with no caller to recover it.
+func TestFinishedWithNoCurrentTrackDoesNotPanic(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		index int
+	}{
+		{"exhausted queue leaves -1", -1},
+		{"index past the end", 3},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			q, _, _ := setupRecordedQueue(t)
+			q.tracks = []Track{
+				{FilePath: "/a.mp3"},
+				{FilePath: "/b.mp3"},
+			}
+			q.currentIndex = tt.index
+
+			// The assertion is that this returns at all.
+			q.OnPlaybackFinished(nil)
+
+			if q.currentIndex != tt.index {
+				t.Errorf(
+					"an out-of-range index was acted on: %d became %d",
+					tt.index, q.currentIndex,
+				)
+			}
+		})
+	}
+}
+
+// A track that broke mid-playback is not a track that was listened
+// to. The player cannot say so itself -- the metadata is here -- so
+// it hands the reason over and this is where it becomes a
+// PlaybackFailed rather than a silent auto-advance.
+func TestAFailedTrackIsReportedAndNotCountedAsAPlay(t *testing.T) {
+	t.Parallel()
+
+	q, _, rec := setupRecordedQueue(t)
+	q.tracks = []Track{
+		{FilePath: "/a.mp3", Title: "A", AudioFileID: 1},
+		{FilePath: "/b.mp3", Title: "B", AudioFileID: 2},
+	}
+	q.currentIndex = 0
+
+	q.OnPlaybackFinished(errTestDecode)
+
+	if _, ok := rec.Last(events.PlaybackFailed); !ok {
+		t.Errorf(
+			"a track that failed mid-playback told the user nothing; "+
+				"got %v",
+			rec.Names(),
+		)
+	}
+}

backend/queue/handlers.go

@@ -1,18 +1,45 @@
 package queue
 
-// OnPlaybackFinished is called when a track finishes playing naturally.
-// This drives the auto-advance behavior and records the play.
-func (q *Queue) OnPlaybackFinished() {
+// OnPlaybackFinished is called when a track stops streaming. This
+// drives the auto-advance behavior and records the play.
+//
+// srcErr says why the track stopped: nil for one that reached its
+// end, non-nil for one that broke partway through.  The player cannot
+// tell the user which, because the metadata lives here -- so a failure
+// is reported as PlaybackFailed and *not* recorded as a play, while
+// the advance happens either way.  Before this, a file that failed
+// mid-track advanced in silence and was counted as listened to.
+//
+//wails:ignore // internal wiring, not part of the app's IPC surface.
+func (q *Queue) OnPlaybackFinished(srcErr error) {
 	q.mu.Lock()
 
-	if len(q.tracks) == 0 {
+	// currentIndex is -1 whenever the queue has been exhausted, and
+	// onQueueExhausted deliberately leaves the finished track loaded
+	// in the player -- so a natural finish can re-enter here against a
+	// queue that is not empty and an index that is not valid.  Every
+	// other path in this package bounds-checks before indexing; this
+	// one panicked, on a goroutine with no caller to recover it.
+	if q.currentIndex < 0 || q.currentIndex >= len(q.tracks) {
 		q.mu.Unlock()
 
 		return
 	}
 
 	// Capture the track that just finished before advancing.
-	finishedID := q.tracks[q.currentIndex].AudioFileID
+	finished := q.tracks[q.currentIndex]
+	finishedID := finished.AudioFileID
+
+	if srcErr != nil {
+		q.emitPlaybackFailed(finished, srcErr)
+	}
+
+	// A track that broke was not listened to.
+	recordFinished := func() {
+		if srcErr == nil {
+			q.recordPlay(finishedID)
+		}
+	}
 
 	// Repeat One: replay the current track.
 	if q.repeatMode == RepeatOne {
@@ -21,7 +48,7 @@ func (q *Queue) OnPlaybackFinished() {
 		}
 
 		q.mu.Unlock()
-		q.recordPlay(finishedID)
+		recordFinished()
 
 		return
 	}
@@ -31,7 +58,7 @@ func (q *Queue) OnPlaybackFinished() {
 		// Queue exhausted — this is the extension point for a future fallback playlist.
 		q.onQueueExhausted(false)
 		q.mu.Unlock()
-		q.recordPlay(finishedID)
+		recordFinished()
 
 		return
 	}
@@ -44,12 +71,12 @@ func (q *Queue) OnPlaybackFinished() {
 	if !q.playCurrentOrSkip(true, q.nextIndex) {
 		q.onQueueExhausted(false)
 		q.mu.Unlock()
-		q.recordPlay(finishedID)
+		recordFinished()
 
 		return
 	}
 
 	q.emitIndexChanged()
 	q.mu.Unlock()
-	q.recordPlay(finishedID)
+	recordFinished()
 }

backend/queue/playbackfailed_test.go

@@ -107,7 +107,7 @@ func TestPlaybackFailed_AutoAdvanceSkipsPastIt(t *testing.T) {
 
 	// The first track finished: auto-advance lands on the missing
 	// file and must step over it rather than stopping dead.
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	if got := q.GetState().CurrentIndex; got != 2 {
 		t.Errorf("currentIndex after skipping: got %d, want 2", got)
@@ -183,7 +183,7 @@ func TestQueueExhausted_KeepsTheFinishedTrackLoaded(t *testing.T) {
 
 	q.SetQueue(paths, 0, false, Source{})
 	q.Play()
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	if q.GetState().CurrentIndex != -1 {
 		t.Errorf(

backend/shortcuts/config.go

@@ -24,10 +24,19 @@ func DefaultBindings() map[string]string {
 		"player.repeat":      "R",
 		"player.mute":        "M",
 
-		// Navigation (Global scope)
+		// Navigation (Global scope).  Back and forward are the browser's
+		// own combination on every platform, which is the whole design
+		// brief for them: the app has one global history and this is the
+		// gesture people already have for it.  The modifier is what keeps
+		// them clear of `player.seekBack`/`seekForward`, which are the
+		// bare arrows -- a binding is matched on its full canonical
+		// string, so "Alt+Left" and "Left" are different keys and not a
+		// conflict.
 		"nav.search":    "/",
 		"nav.searchAlt": "Ctrl+F",
 		"nav.queue":     "Q",
+		"nav.back":      "Alt+Left",
+		"nav.forward":   "Alt+Right",
 
 		// App actions
 		"app.selectAll": "Ctrl+A",

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

build/android/Taskfile.yml

@@ -4,18 +4,28 @@ includes:
   common: ../Taskfile.yml
 
 vars:
-  # The *installed* package name, which every adb-driven task below uses
-  # to uninstall, launch and filter. It must agree with `applicationId`
-  # in app/build.gradle, and nothing enforces that.
+  # APP_ID is an *assertion*, not a setting, and it has no default.
   #
-  # ANDROID.md says to set this in build/config.yml. That does not work
-  # in beta.8, checked both ways: `wails3 task` builds its var set from
-  # CLI KEY=VALUE arguments and the Taskfile tree only -- nothing reads
-  # config.yml -- and even when set it feeds only these adb commands,
-  # never Gradle. So the identity is declared twice, here and in
-  # build.gradle, and a change to one alone means the official run and
-  # deploy tasks address a package that is not installed.
-  APP_ID: '{{.APP_ID | default "app.yellowjacket"}}'
+  # It used to be the id every adb-driven task below uninstalled,
+  # launched and filtered, defaulting to "app.yellowjacket". It could
+  # never have been a setting: `wails3 task` builds its var set from CLI
+  # KEY=VALUE arguments and the Taskfile tree only -- nothing reads
+  # build/config.yml, contrary to ANDROID.md, checked with --dry -- and
+  # even when set it fed only the adb commands, never Gradle. So the
+  # identity was declared twice, here and as `applicationId` in
+  # app/build.gradle, with nothing enforcing that they agree.
+  #
+  # They did not agree. The debug buildType carries
+  # `applicationIdSuffix ".dev"`, so the tasks that assemble a debug APK
+  # addressed the *release* id -- on a device, the user's installed app
+  # and their library (#159).
+  #
+  # The id is now read back from the built APK by scripts/android-
+  # pkgid.sh, so the thing installed and the thing launched agree by
+  # construction. Passing APP_ID= says "this build had better declare
+  # that id", and the deploy refuses before touching anything if it does
+  # not -- which is the check that would have caught #159 statically.
+  APP_ID: '{{.APP_ID | default ""}}'
   MIN_SDK: '21'
   TARGET_SDK: '35'
   # The emulator runs the host architecture; physical devices are arm64
@@ -372,9 +382,7 @@ tasks:
           ARCH: '{{.ARCH | default .HOST_ARCH}}'
     cmds:
       - task: ensure-emulator
-      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
 
   run:
     summary: Build, install and launch a debug build in the Android Emulator
@@ -383,9 +391,7 @@ tasks:
       - task: build
     cmds:
       - task: assemble:apk
-      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
 
   device:list:
     summary: Lists connected Android devices and emulators (serials)
@@ -400,25 +406,7 @@ tasks:
           ARCH: arm64
     cmds:
       - task: assemble:apk
-      - |
-        DEVICE='{{.DEVICE_ID | default ""}}'
-        if [ -z "$DEVICE" ]; then
-          DEVICE="${DEVICE_ID:-}"
-        fi
-        if [ -z "$DEVICE" ]; then
-          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
-        fi
-        if [ -z "$DEVICE" ]; then
-          echo "Error: no connected physical Android device found."
-          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
-          echo "Find connected device serials with: {{.ADB}} devices"
-          exit 1
-        fi
-
-        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
-        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
-        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
-        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target device{{if .DEVICE_ID}} --serial "{{.DEVICE_ID}}"{{end}}{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
     preconditions:
       - sh: '[ -x "{{.ADB}}" ] || command -v adb'
         msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
@@ -430,25 +418,7 @@ tasks:
         vars:
           ARCH: arm64
     cmds:
-      - |
-        DEVICE='{{.DEVICE_ID | default ""}}'
-        if [ -z "$DEVICE" ]; then
-          DEVICE="${DEVICE_ID:-}"
-        fi
-        if [ -z "$DEVICE" ]; then
-          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
-        fi
-        if [ -z "$DEVICE" ]; then
-          echo "Error: no connected physical Android device found."
-          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
-          echo "Find connected device serials with: {{.ADB}} devices"
-          exit 1
-        fi
-
-        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
-        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
-        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
-        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target device{{if .DEVICE_ID}} --serial "{{.DEVICE_ID}}"{{end}}{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
     preconditions:
       - sh: '[ -x "{{.ADB}}" ] || command -v adb'
         msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"

build/android/app/src/main/java/com/wails/app/MainActivity.java

@@ -891,13 +891,41 @@ public class MainActivity extends AppCompatActivity {
         }
     }
 
+    /**
+     * The activity going away is not the app shutting down.
+     *
+     * <p>The scaffold called {@code bridge.shutdown()} here, which is
+     * the natural reading of onDestroy and is wrong for this app twice
+     * over. Android destroys and recreates an activity for a
+     * configuration change the manifest does not declare, under memory
+     * pressure, and on every background if the user has "Don't keep
+     * activities" on -- all **without restarting the process**. And
+     * when the user really does leave, this app's reason for existing
+     * in the background is that a song is playing, which is what the
+     * {@code mediaPlayback} foreground service is holding the process
+     * alive for. Either way, tearing the Go side down here would stop
+     * the music.
+     *
+     * <p>It was harmless only by accident: {@code nativeShutdown} calls
+     * {@code App.Quit()}, whose Android {@code destroy()} is an empty
+     * method, and {@code Run()}'s deferred {@code shutdownServices()}
+     * can never fire because Android's {@code platformRun} is
+     * {@code select{}} and does not return. So no {@code
+     * ServiceShutdown} has ever run on Android, and removing this call
+     * changes nothing today -- it stops the day someone implements
+     * {@code destroy()} from silently killing playback on a rotation.
+     *
+     * <p>There is no callback for "the process is going away"; Android
+     * simply kills it. Durability on this platform is the persist
+     * writers, which submit on every mutation rather than at exit.
+     *
+     * <p>See #52, and CLAUDE.md, "An activity is a view onto the
+     * process".
+     */
     @Override
     protected void onDestroy() {
         super.onDestroy();
         unregisterSystemEventReceivers();
-        if (bridge != null) {
-            bridge.shutdown();
-        }
         if (webView != null) {
             webView.destroy();
         }

build/android/app/src/main/java/com/wails/app/WailsBridge.java

@@ -129,7 +129,24 @@ public class WailsBridge {
     }
 
     /**
-     * Initialize the native Go library
+     * Initialize the native Go library.
+     *
+     * <p><b>{@code initialized} is deliberately per-instance, and making
+     * it {@code static} is the trap this comment exists for.</b> A
+     * recreated activity builds a new bridge and calls this again, in a
+     * process where the native library is already loaded and Go's
+     * {@code main()} is already running -- so "initialise once per
+     * process" looks like exactly the right rule. It is not, because
+     * {@code nativeInit} does <i>two</i> things: it runs
+     * {@code go mainFunc()}, and it stores the global JNI reference to
+     * <i>this</i> bridge. Skip it and Go keeps executing JavaScript
+     * against the destroyed activity's WebView: the app opens, renders,
+     * and never receives another backend event.
+     *
+     * <p>So this is called every time, and the half that must not repeat
+     * is latched on the Go side instead, at the top of {@code main()} --
+     * which is also where the damage was ({@code os.Exit(1)}), and the
+     * only place that can see it. See #52.
      */
     public void initialize() {
         if (initialized) {

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
 

e2e/specs/album-dropdown.spec.ts

@@ -1,6 +1,12 @@
 import { test, expect } from '../support/fixtures.js';
 import type { Page } from '@playwright/test';
 
+/**
+ * How far the scroll test scrolls. One constant, because the guard and
+ * the assertion have to agree about it — they did not, which is #133.
+ */
+const SCROLL_TARGET = 80;
+
 /**
  * Plan 007 phase 5: expanding an album shows its tracks.
  *
@@ -104,20 +110,30 @@ test.describe('the album dropdown', () => {
     await app.setViewportSize({ width: 900, height: 600 });
 
     try {
-      await expect.poll(() => scrollRange(app)).toMatchObject({
-        scrollable: true,
-        overflowY: 'auto',
-      });
+      // The container has to be a scroller at all, which is the thing
+      // the defect behind this spec broke and is a property rather
+      // than a moment.
+      await expect
+        .poll(() => scrollRange(app))
+        .toMatchObject({ overflowY: 'auto' });
 
-      await app.evaluate(() => {
-        const sc = document
-          .querySelector('cover-grid')
-          ?.shadowRoot?.querySelector('.grid-scroll-container');
-
-        if (sc) sc.scrollTop = 80;
-      });
-
-      expect(await scrollTop(app)).toBe(80);
+      // **Scrolling it and reading it back are one round trip** (#151).
+      //
+      // #133 made the guard ask for the range this needs rather than
+      // for "scrollable at all", which was necessary and is not
+      // sufficient: a guard and the write it guards are separate
+      // `evaluate` calls, so the grid can satisfy the range and settle
+      // out of it before the write lands. It still does — observed as
+      // `Expected 80, Received 10` in the second of three consecutive
+      // full-suite runs, with the spec green alone on the same app
+      // straight afterwards.
+      //
+      // Polling harder cannot close a window between two moments; only
+      // removing the window can. So the probe sets `scrollTop` and
+      // returns what it reads back, in one page-side call, and the
+      // poll retries *that* — which also means the assertion is about
+      // what the grid did rather than about what it was ready to do.
+      await expect.poll(() => scrollTo(app, SCROLL_TARGET)).toBe(SCROLL_TARGET);
 
       // And the dropdown it opens is on screen, wherever the manager
       // decides that leaves the scroll. It is *not* "the position is
@@ -248,27 +264,45 @@ async function closeDropdown(app: Page): Promise<void> {
   });
 }
 
-/** Whether the grid can scroll at all, which decides if a probe can move. */
+/** Whether the grid is a scroller at all, which is what the bug broke. */
 async function scrollRange(app: Page) {
-  return app.evaluate(() => {
+  return app.evaluate((target) => {
     const sc = document
       .querySelector('cover-grid')
       ?.shadowRoot?.querySelector('.grid-scroll-container');
 
     return {
-      scrollable: !!sc && sc.scrollHeight > sc.clientHeight + 40,
+      // Reported for the failure message rather than waited on: `room`
+      // was the guard #133 strengthened, and #151 is that a guard in
+      // its own round trip cannot speak for the write in the next one.
+      // `scrollTo` below is the assertion now; this says *why* it did
+      // not reach the target when it does not.
+      room: !!sc && sc.scrollHeight - sc.clientHeight >= target,
       overflowY: sc ? getComputedStyle(sc).overflowY : '',
     };
-  });
+  }, SCROLL_TARGET);
 }
 
-async function scrollTop(app: Page): Promise<number> {
-  return app.evaluate(
-    () =>
-      document
-        .querySelector('cover-grid')
-        ?.shadowRoot?.querySelector('.grid-scroll-container')?.scrollTop ?? -1,
-  );
+/**
+ * Scroll the grid and report where it actually landed, in one call.
+ *
+ * The whole point is that the set and the read share a moment: a
+ * `scrollTop` write is clamped to the range *at the instant it lands*,
+ * so reading it back in a second round trip asks a container that may
+ * have re-laid out in between.
+ */
+async function scrollTo(app: Page, target: number): Promise<number> {
+  return app.evaluate((to) => {
+    const sc = document
+      .querySelector('cover-grid')
+      ?.shadowRoot?.querySelector('.grid-scroll-container');
+
+    if (!sc) return -1;
+
+    sc.scrollTop = to;
+
+    return sc.scrollTop;
+  }, target);
 }
 
 /** Whether the open dropdown is inside the scroll container's viewport. */

e2e/specs/back-navigation.spec.ts

@@ -15,12 +15,49 @@ import { test, expect } from '../support/fixtures.js';
  *
  * What it cannot answer is whether Android's *gesture* reaches the
  * WebView, which is between the OS and the scaffold.
+ *
+ * **And `data-active-view` is not the behaviour.** Every assertion here
+ * used to be that attribute, which the shell sets on every path
+ * including `_isBack` — so this file was green throughout #72, in
+ * which both navs highlighted the view the user had just *left*. The
+ * shell's own bookkeeping was the one thing that was already right;
+ * what a person sees is `aria-current`, and that is asserted below as
+ * well. This is the same trap `layout-overflow.spec.ts` set for #69: a
+ * spec named for the behaviour, measuring the plumbing.
  */
 type Page = import('@playwright/test').Page;
 
 const activeView = (page: Page) =>
   page.getByTestId('main-content');
 
+/** A common phone, where the bottom bar is the primary navigation. */
+const PHONE = { width: 390, height: 844 };
+
+/**
+ * The nav item for a destination, in whichever navigation is on screen.
+ *
+ * Both navs carry a button named `Albums`, and only one of them is ever
+ * in the accessibility tree — the other is `display: none` — so the
+ * role query resolves to the one the user can see at this viewport.
+ * That is the point: the highlight has to be right in both, and #72 was
+ * two different-looking symptoms of one cause.
+ */
+const navItem = (page: Page, label: string) =>
+  page.getByRole('button', { name: label, exact: true });
+
+/**
+ * `aria-current="page"` is the accessible fact and the assertion worth
+ * making; `.active` is a class and could be restyled without breaking
+ * anything real.
+ */
+async function expectHighlighted(page: Page, label: string): Promise<void> {
+  await expect(navItem(page, label)).toHaveAttribute('aria-current', 'page');
+}
+
+async function expectNotHighlighted(page: Page, label: string): Promise<void> {
+  await expect(navItem(page, label)).toHaveAttribute('aria-current', 'false');
+}
+
 /**
  * Open an artist's detail view, which is the deepest ordinary route.
  *
@@ -42,6 +79,114 @@ async function openAnArtist(app: Page): Promise<void> {
   );
 }
 
+/**
+ * The global back/forward control (#6).
+ *
+ * It is desktop chrome — hidden below 900px, where the sidebar has
+ * already given up its labels — so these set a desktop viewport
+ * explicitly rather than trusting the runner's default.
+ */
+const DESKTOP = { width: 1280, height: 800 };
+
+const backButton = (page: Page) =>
+  page.locator('nav-history').getByRole('button', { name: 'Back' });
+
+const forwardButton = (page: Page) =>
+  page.locator('nav-history').getByRole('button', { name: 'Forward' });
+
+test.describe('global back and forward', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DESKTOP);
+  });
+
+  test('offers nothing at launch, in either direction', async ({ app }) => {
+    // The launch entry is *replaced*, not pushed, so there is nothing
+    // of ours behind it — and a Back button that is live at the root
+    // is a press that does nothing on desktop and, on Android, the
+    // press that should have exited the app (#142). This assertion is
+    // what pins that: it failed before the launch navigation stopped
+    // recording two entries.
+    await expect(backButton(app)).toBeDisabled();
+    await expect(forwardButton(app)).toBeDisabled();
+  });
+
+  test('walks the history in both directions, and says which are available', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-albums').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+    await expect(backButton(app)).toBeEnabled();
+    await expect(forwardButton(app)).toBeDisabled();
+
+    await app.getByTestId('nav-tracks').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'tracks');
+
+    await backButton(app).click();
+
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+    // Standing in the middle of the list: both directions live, which
+    // is the state a single depth counter cannot express.
+    await expect(backButton(app)).toBeEnabled();
+    await expect(forwardButton(app)).toBeEnabled();
+
+    await forwardButton(app).click();
+
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'tracks');
+    await expect(forwardButton(app)).toBeDisabled();
+  });
+
+  test('reaches the detail view a tab click left behind', async ({ app }) => {
+    // The report, exactly: the album is one entry away the whole time,
+    // and before this control the only way back to it was a button
+    // that had gone off screen with the view it belonged to.
+    await app.getByTestId('nav-artists').click();
+    await openAnArtist(app);
+
+    await app.getByTestId('nav-tracks').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'tracks');
+
+    await backButton(app).click();
+
+    await expect(activeView(app)).toHaveAttribute(
+      'data-active-view',
+      'explore-artist-details',
+    );
+  });
+
+  test('drops the forward list when the user navigates from the middle', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-albums').click();
+    await app.getByTestId('nav-tracks').click();
+    await backButton(app).click();
+    await expect(forwardButton(app)).toBeEnabled();
+
+    // A browser truncates here, and so does this: what was ahead is no
+    // longer reachable, and a Forward button still offering it would
+    // be pointing at an entry that has been overwritten.
+    await app.getByTestId('nav-genres').click();
+
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'genres');
+    await expect(forwardButton(app)).toBeDisabled();
+    await expect(backButton(app)).toBeEnabled();
+  });
+
+  test('is absent below the desktop band, where nothing needs it', async ({
+    app,
+  }) => {
+    // Alt+Left/Right survive at every width, the detail views keep
+    // their own back buttons and the phone has the platform's gesture
+    // — so this is a control standing down, not an action becoming
+    // unreachable. It is hidden at 899 because the top bar is what
+    // runs out of room first below 900 (#143).
+    await app.setViewportSize({ width: 899, height: 600 });
+    await expect(app.locator('nav-history')).toBeHidden();
+
+    await app.setViewportSize({ width: 390, height: 844 });
+    await expect(app.locator('nav-history')).toBeHidden();
+  });
+});
+
 test.describe('the back gesture', () => {
   test('leaves a detail view for the view it was opened from', async ({
     app,
@@ -71,6 +216,105 @@ test.describe('the back gesture', () => {
     await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
   });
 
+  test('leaves the nav highlighting the view it landed on, not the one it left', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-albums').click();
+    await expectHighlighted(app, 'Albums');
+
+    await app.getByTestId('nav-tracks').click();
+    await expectHighlighted(app, 'Tracks');
+
+    await app.goBack();
+
+    // #72, and the half of it the report did not describe: this is
+    // desktop, and before the shell published the active view *both*
+    // navs stayed on Tracks. An absent highlight reads as a glitch; a
+    // confident wrong one is worse, and any back across two primary
+    // views produced it.
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+    await expectHighlighted(app, 'Albums');
+    await expectNotHighlighted(app, 'Tracks');
+  });
+
+  test('keeps the parent destination lit while a detail view is open', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-artists').click();
+    await expectHighlighted(app, 'Artists');
+
+    await openAnArtist(app);
+
+    // A detail view is not a destination in either nav, and the user is
+    // still inside Artists. `app-sidebar` did this by accident -- it
+    // guarded on its own item list, so an unmatched name left the
+    // highlight alone -- and that accident is why the sidebar looked
+    // right on a detail view while the tab bar lit nothing. This test
+    // therefore passed before the fix and is here to keep the rule from
+    // being lost while the others are made to pass; the *tab bar's*
+    // half of it is the phone test below, which did not.
+    await expectHighlighted(app, 'Artists');
+
+    await app.goBack();
+
+    await expectHighlighted(app, 'Artists');
+  });
+
+  test('the tab bar survives the same journey on a phone', async ({ app }) => {
+    await app.setViewportSize(PHONE);
+
+    // The reported shape: Albums, open an album, press back. The tab
+    // bar had a highlight, then no highlight at all, and never got it
+    // back — `bottom-nav` took the detail view's name, matched it
+    // against no tab, and lit nothing.
+    await navItem(app, 'Albums').click();
+    await expectHighlighted(app, 'Albums');
+
+    await app.locator('cover-grid').getByText('Glass Harbour').first().click();
+    await expect(activeView(app)).toHaveAttribute(
+      'data-active-view',
+      'explore-album-details',
+    );
+    await expectHighlighted(app, 'Albums');
+
+    await app.goBack();
+
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+    await expectHighlighted(app, 'Albums');
+  });
+
+  test('the drawer sidebar opens on the page you are standing on', async ({
+    app,
+  }) => {
+    await app.setViewportSize(PHONE);
+
+    await navItem(app, 'Tracks').click();
+    await expectHighlighted(app, 'Tracks');
+
+    // A third symptom of the same cause, found while measuring #72 and
+    // not in the report: `bottom-nav` mounts its `<app-sidebar>` when
+    // the drawer opens, so that copy had heard no `navigate` at all and
+    // showed its own default — Home, from any page in the app. An event
+    // has no answer for a listener that was not there; a store does.
+    await navItem(app, 'More').click();
+
+    // The element carrying the testid is the `wa-drawer` host, which
+    // always reports hidden -- what is visible is the `<dialog>` in its
+    // shadow root -- so the drawer being open is asserted of the
+    // sidebar it holds rather than of itself.
+    const drawer = app.getByTestId('nav-drawer');
+
+    await expect(drawer.locator('app-sidebar')).toBeVisible();
+    await expect(drawer.getByTestId('nav-tracks')).toHaveAttribute(
+      'aria-current',
+      'page',
+    );
+    await expect(drawer.getByTestId('nav-home')).toHaveAttribute(
+      'aria-current',
+      'false',
+    );
+  });
+
   test('an in-app back button consumes exactly one entry', async ({ app }) => {
     await app.getByTestId('nav-tracks').click();
     await openAnArtist(app);

e2e/specs/bottom-bar.spec.ts

@@ -0,0 +1,147 @@
+import { test, expect, callBinding, NO_QUEUE_SOURCE } from '../support/fixtures.js';
+import type { Page } from '@playwright/test';
+
+/**
+ * The bottom bar's two promises (#23, #42): the transport is centred in
+ * the window, and the volume is a slider rather than a popup.
+ *
+ * **"Centred" is measured against the window, not against the space
+ * left over**, which is the whole of #23. The bar was
+ * `320px 1fr auto`, so the transport sat in the middle of what the
+ * metadata and the queue button did not use — its centre was ~140px
+ * right of the window's at every size, which reads as an alignment
+ * mistake rather than as a layout choice.
+ *
+ * The mechanism is that the outer two columns are the same width, so
+ * this asserts the *outcome* (centre lines up) rather than the CSS. A
+ * spec that checked `grid-template-columns` would pass on any build
+ * that kept the declaration and broke the result.
+ */
+
+/** Where the transport sits, against where the window's centre is. */
+const geometry = (app: Page) =>
+  app.evaluate(() => {
+    const bar = document.querySelector<HTMLElement>('.bottom-bar')!;
+    const player = document.querySelector<HTMLElement>('audio-player')!;
+    const b = bar.getBoundingClientRect();
+    const p = player.getBoundingClientRect();
+
+    const seek = player.shadowRoot
+      ?.querySelector('seek-bar')
+      ?.shadowRoot?.querySelector('wa-slider');
+
+    return {
+      offset: Math.round(p.left + p.width / 2 - (b.left + b.width / 2)),
+      barHeight: Math.round(b.height),
+      seekWidth: seek ? Math.round(seek.getBoundingClientRect().width) : -1,
+    };
+  });
+
+/** Something has to be playing before the transport draws a seek bar. */
+async function play(app: Page): Promise<void> {
+  const paths = await app.evaluate(async () => {
+    const tracks = (await window.__yjEvents.call(
+      'library.Library.GetTracks',
+      [0],
+      10_000,
+    )) as { FilePath: string }[];
+
+    return tracks.slice(0, 3).map((t) => t.FilePath);
+  });
+
+  await callBinding(app, 'queue.Queue.SetQueue', [
+    paths,
+    0,
+    false,
+    NO_QUEUE_SOURCE,
+  ]);
+  await callBinding(app, 'queue.Queue.Play');
+  await expect(app.getByTestId('now-playing-title')).not.toBeEmpty();
+}
+
+test.describe('the bottom bar', () => {
+  test.afterEach(async ({ app }) => {
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {
+      /* already empty */
+    });
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  /**
+   * Four widths, because a centring bug is a function of width: the old
+   * layout was off by half the difference between the two outer
+   * columns, so it was wrong by a different amount at each one and
+   * exactly right at none.
+   */
+  for (const width of [800, 900, 1100, 1440]) {
+    test(`centres the transport in the window at ${width}px`, async ({
+      app,
+    }) => {
+      await app.setViewportSize({ width, height: 700 });
+      await play(app);
+
+      await expect.poll(() => geometry(app).then((g) => g.offset)).toBe(0);
+    });
+  }
+
+  /**
+   * The seek bar is what the centring is *paid for* with, so it is
+   * asserted rather than assumed.
+   *
+   * Reserving the metadata's full width on both sides centres the
+   * transport perfectly and squeezes the control you drag: measured
+   * during this work at **61px of track at 800px**, against 257 before
+   * the change. The side columns are capped at a quarter of the bar for
+   * that reason, and this is the number that says so — 246 at 800px,
+   * which is parity with the uncentred layout.
+   */
+  test('does not pay for the centring with the seek bar', async ({ app }) => {
+    await app.setViewportSize({ width: 800, height: 700 });
+    await play(app);
+
+    await expect
+      .poll(() => geometry(app).then((g) => g.seekWidth))
+      .toBeGreaterThan(200);
+  });
+
+  /**
+   * #42: the slider is simply there. Three gestures — click open, drag,
+   * click closed — is what a bottom bar has room not to ask for.
+   */
+  test('shows the volume slider without a click', async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+
+    const volume = app.locator('.bottom-bar volume-control');
+
+    await expect(volume).toBeVisible();
+    await expect(volume.locator('wa-slider')).toBeVisible();
+  });
+
+  /**
+   * And the inline icon is the mute toggle, because with the slider
+   * beside it there is nothing left to disclose. The name follows the
+   * action rather than the state for the same reason.
+   */
+  test('names the inline icon after what it does', async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+
+    await expect(
+      app.locator('.bottom-bar volume-control').getByRole('button', {
+        name: 'Mute',
+      }),
+    ).toBeVisible();
+  });
+
+  /**
+   * The bar is a fixed 4em row and the transport sits in it. A slider
+   * with a label grows `#slider` by 8px unless `wa-slider-label.css`
+   * suppresses it, which moved the whole bar the last time — so the
+   * height is pinned here rather than left to a screenshot.
+   */
+  test('stays 4em tall', async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+    await play(app);
+
+    await expect.poll(() => geometry(app).then((g) => g.barHeight)).toBe(64);
+  });
+});

e2e/specs/control-names.spec.ts

@@ -29,18 +29,13 @@ test.describe('a control says what it controls', () => {
   });
 
   test('the volume slider is announced as Volume', async ({ app }) => {
-    // The popup renders no slider at all while closed, the same way the
-    // queue panel renders no list — so this has to open it first.
-    await app.getByRole('button', { name: /volume/i }).click();
-
+    // No disclosure to open first, and no state to put back afterwards:
+    // #42 made the slider inline, so it is simply there. The assertion
+    // is unchanged — the *name* is the subject here, and the route to
+    // the control got shorter rather than different.
     await expect(
       app.getByRole('slider', { name: 'Volume' }),
     ).toBeVisible();
-
-    // Leave the transport as it was found: the specs share one page in
-    // file order, and an open popup covers the buttons beneath it.
-    await app.keyboard.press('Escape');
-    await app.locator('body').click({ position: { x: 5, y: 5 } });
   });
 
   test('naming the slider did not move the transport', async ({ app }) => {

e2e/specs/failure-voice.spec.ts

@@ -36,9 +36,16 @@ test.describe('a failed binding says so', () => {
     // Libraries is the one section that starts expanded (H-22), so ask
     // the disclosure what state it is in rather than assuming one — a
     // blind click used to expand it and now collapses it.
+    //
+    // By role and name, not by `.header`: since #27 the section also
+    // contains a `job-panel`, and an open `job-details-drawer` inside
+    // it carries the same class. That only bites once a job exists,
+    // which is why it showed up on the *second* engine of a CI run and
+    // not the first.
     const disclosure = page
       .locator('config-section[heading="Libraries"]')
-      .locator('.header');
+      .getByRole('button', { name: 'Libraries' })
+      .first();
 
     if ((await disclosure.getAttribute('aria-expanded')) === 'false') {
       await disclosure.click();

e2e/specs/header-action-overflow.spec.ts

@@ -0,0 +1,318 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * #69: the Playlists header's buttons could not be reached.
+ *
+ * Three text buttons — Import (91px), New Playlist (122px), New Smart
+ * Playlist (162px), 390px in total — inside a header that gets 700px at
+ * 900×600. "New Smart Playlist" rendered **114 of its 162px**, and at
+ * phone width the Android report was the plain version of it: you
+ * cannot scroll to reach them, and scrolling is not how page controls
+ * should be exposed anyway.
+ *
+ * **`layout-overflow.spec.ts` passes on the broken build**, which is why
+ * this file exists rather than a case being added there. That spec
+ * asserts the *shell* needs no sideways scrolling; clipping *inside* a
+ * component is invisible to it. So the measurement here is per-button
+ * and per-header, against the widths the app promises.
+ *
+ * Plan 018's size matrix is the promise being kept: **no action is ever
+ * unreachable at any supported size.** These are its three bands.
+ */
+
+const VIEWPORTS = [
+  // Desktop's worst case, and not the enforced minimum: the sidebar
+  // collapses to icons *below* 900, so the content area is 843px at 899
+  // and 700px at 900. Testing "the minimum" and stopping misses it.
+  { name: '900×600 (widest sidebar, narrowest content)', width: 900, height: 600 },
+  { name: '800×600 (the enforced minimum)', width: 800, height: 600 },
+  { name: '390×780 (phone)', width: 390, height: 780 },
+  // WCAG 1.4.10's reflow target, which plan 018 promises the app fits.
+  { name: '320×600 (400% zoom)', width: 320, height: 600 },
+];
+
+/** Every action the Playlists header can offer, in declared order. */
+const ACTIONS = ['Import', 'New Playlist', 'New Smart Playlist'];
+
+/**
+ * What the header is actually rendering, measured rather than inferred.
+ *
+ * A shadow query is the wrong tool for *asserting* — that is what
+ * `getByRole` below is for — but it is the right one for a measurement,
+ * because the number this issue is about (a button 48px wider than the
+ * box holding it) is not in the accessibility tree at all.
+ */
+const headerFit = (page: import('@playwright/test').Page) =>
+  page.evaluate(() => {
+    const root = document
+      .querySelector('[data-testid="main-content"] playlist-view')
+      ?.shadowRoot?.querySelector('page-header')?.shadowRoot;
+
+    if (!root) return null;
+
+    const header = root.querySelector<HTMLElement>('.page-header')!;
+    const box = header.getBoundingClientRect();
+    const title = root.querySelector<HTMLElement>('h1')!;
+
+    const clipped = [
+      ...root.querySelectorAll<HTMLElement>('.action, .more-button'),
+    ]
+      .filter((b) => !b.hidden)
+      .filter((b) => {
+        const r = b.getBoundingClientRect();
+
+        return r.right > box.right + 1 || r.left < box.left - 1;
+      })
+      .map((b) => b.dataset['actionId'] ?? 'more');
+
+    return {
+      overflow: header.scrollWidth - header.clientWidth,
+      clipped,
+      titleTruncated: title.scrollWidth > title.clientWidth + 1,
+      buttons: [...root.querySelectorAll<HTMLElement>('.action')]
+        .filter((b) => !b.hidden)
+        .map((b) => b.textContent?.trim() ?? ''),
+      menu: [
+        ...root.querySelectorAll('#page-header-overflow wa-dropdown-item'),
+      ].map((i) => i.textContent?.trim() ?? ''),
+    };
+  });
+
+test.describe('the page header never clips an action', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.getByTestId('nav-playlists').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'playlists',
+    );
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1280, height: 800 });
+  });
+
+  for (const vp of VIEWPORTS) {
+    test(`every action is reachable at ${vp.name}`, async ({ app }) => {
+      await app.setViewportSize({ width: vp.width, height: vp.height });
+
+      // Polled: the fit is decided by a ResizeObserver, so it settles a
+      // frame after the resize rather than with it.
+      await expect
+        .poll(async () => (await headerFit(app))?.clipped)
+        .toEqual([]);
+
+      const fit = (await headerFit(app))!;
+
+      expect(fit.overflow).toBeLessThanOrEqual(0);
+
+      // Between them, buttons and menu account for all three. This is
+      // the assertion the issue asks for: not "it fits" but "nothing
+      // was dropped to make it fit".
+      expect([...fit.buttons, ...fit.menu].sort()).toEqual([...ACTIONS].sort());
+    });
+  }
+
+  /**
+   * The title gives way before an action does.
+   *
+   * Once the heading can ellipsis it absorbs the pressure, and
+   * `scrollWidth` then reports a header that fits perfectly while the
+   * heading reads "Playlis…" — this issue's own failure mode moved from
+   * the button to the title, and invisible to exactly the measurement
+   * that missed it the first time. At the desktop sizes there is always
+   * an action to collapse instead.
+   */
+  test('does not truncate the heading to keep a button', async ({ app }) => {
+    for (const vp of VIEWPORTS.slice(0, 2)) {
+      await app.setViewportSize({ width: vp.width, height: vp.height });
+
+      await expect
+        .poll(async () => (await headerFit(app))?.titleTruncated)
+        .toBe(false);
+    }
+  });
+
+  /**
+   * Asserted through the accessibility tree, never a shadow query. An
+   * overflow menu is exactly the shape that grows a nameless control,
+   * and this repo has shipped one four times — most recently the
+   * queue's own close button.
+   */
+  test('the overflow is a named control that opens a named menu', async ({
+    app,
+  }) => {
+    await app.setViewportSize({ width: 900, height: 600 });
+
+    const more = app.getByRole('button', { name: 'More actions' });
+
+    await expect(more).toBeVisible();
+    await expect(more).toHaveAttribute('aria-expanded', 'false');
+
+    await more.click();
+
+    await expect(more).toHaveAttribute('aria-expanded', 'true');
+
+    const menu = app.getByRole('menu', { name: 'More actions' });
+
+    await expect(menu).toBeVisible();
+
+    // Collapsed at 900×600: Import (lowest priority) and New Smart
+    // Playlist. New Playlist stays a button because it is the drop
+    // target, and a closed menu cannot be one.
+    await expect(
+      menu.getByRole('menuitem', { name: 'Import' }),
+    ).toBeVisible();
+    await expect(
+      app.getByRole('button', { name: 'New Playlist', exact: true }),
+    ).toBeVisible();
+  });
+
+  /**
+   * The phone case is the original report. Every action is in the menu
+   * at 390px, and the menu is reachable by name — which is the whole of
+   * "these need to be reachable in a sensible way".
+   */
+  test('offers every action from the menu on a phone', async ({ app }) => {
+    await app.setViewportSize({ width: 390, height: 780 });
+
+    const more = app.getByRole('button', { name: 'More actions' });
+
+    await expect(more).toBeVisible();
+    await more.click();
+
+    const menu = app.getByRole('menu', { name: 'More actions' });
+
+    for (const label of ACTIONS) {
+      await expect(menu.getByRole('menuitem', { name: label })).toBeVisible();
+    }
+  });
+
+  /**
+   * Escape closes it and focus goes back to the trigger — `MenuKeyboard`
+   * is shared with every other menu in the app precisely so this is not
+   * a second keyboard model, and this is what proves it was wired up
+   * rather than merely imported.
+   */
+  test('takes the keyboard, and gives it back', async ({ app }) => {
+    await app.setViewportSize({ width: 900, height: 600 });
+
+    const more = app.getByRole('button', { name: 'More actions' });
+
+    await more.click();
+
+    const menu = app.getByRole('menu', { name: 'More actions' });
+
+    await expect(menu).toBeVisible();
+
+    // The first item takes focus on open. `wa-dropdown-item` sets its
+    // own role in its own first update, so this is polled rather than
+    // read: a query at the host's updateComplete finds nothing, which
+    // reads exactly like a menu that refused to take focus.
+    await expect
+      .poll(async () =>
+        app.evaluate(() => {
+          // Stops where `MenuKeyboard`'s own `deepActiveElement` stops:
+          // on the *host* whose shadow root has no active element.
+          // Descending unconditionally lands inside the focused
+          // `wa-dropdown-item`'s own shadow root, where nothing is
+          // focused — which reads exactly like a menu that refused the
+          // keyboard, on a build where it did not.
+          let el = document.activeElement;
+
+          while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement;
+
+          return el?.textContent?.trim() ?? null;
+        }),
+      )
+      .toBe('Import');
+
+    await app.keyboard.press('Escape');
+
+    await expect(more).toHaveAttribute('aria-expanded', 'false');
+    await expect(more).toBeFocused();
+  });
+
+  /**
+   * New Playlist is a drop target, and declaring it as data must not
+   * take that away — which is why a `PageAction` carries the drop
+   * handlers rather than the header owning a notion of dropping.
+   *
+   * Nothing covered this before, in either tier, and it is the one
+   * behaviour the migration could plausibly have destroyed silently:
+   * dragging still *looks* fine against a button that no longer
+   * accepts anything.
+   */
+  test('New Playlist still accepts a dropped track', async ({ app }) => {
+    await app.setViewportSize({ width: 1280, height: 800 });
+
+    const button = app.getByRole('button', {
+      name: 'New Playlist',
+      exact: true,
+    });
+
+    await expect(button).toBeVisible();
+
+    const result = await app.evaluate(async () => {
+      const view = document.querySelector(
+        '[data-testid="main-content"] playlist-view',
+      )!;
+      const target = view.shadowRoot!
+        .querySelector('page-header')!
+        .shadowRoot!.querySelector('[data-testid="page-action-new-playlist"]')!;
+
+      const data = new DataTransfer();
+
+      data.setData(
+        'application/x-yj-tracks',
+        JSON.stringify({ filePaths: ['/tmp/dropped.mp3'] }),
+      );
+
+      const fire = (type: string) =>
+        target.dispatchEvent(
+          new DragEvent(type, {
+            bubbles: true,
+            cancelable: true,
+            dataTransfer: data,
+          }),
+        );
+
+      fire('dragover');
+      await new Promise((r) => setTimeout(r, 50));
+
+      // The affordance is the host's state reaching the header's
+      // button, which is the half a plain handler call would not prove.
+      const highlighted = target.classList.contains('drag-over');
+
+      fire('drop');
+      await new Promise((r) => setTimeout(r, 200));
+
+      return {
+        highlighted,
+        opened: view.shadowRoot!.querySelector('.create-form') !== null,
+      };
+    });
+
+    expect(result).toEqual({ highlighted: true, opened: true });
+
+    // Leave the view as it was found.
+    await app.keyboard.press('Escape');
+  });
+
+  /**
+   * An action given back when the window widens again. The collapsed
+   * set is a function of the current width and not of how it got there
+   * — a rule that only ever *added* to it would never widen.
+   */
+  test('gives the buttons back when the window grows', async ({ app }) => {
+    await app.setViewportSize({ width: 390, height: 780 });
+
+    await expect.poll(async () => (await headerFit(app))?.buttons).toEqual([]);
+
+    await app.setViewportSize({ width: 1440, height: 900 });
+
+    await expect
+      .poll(async () => (await headerFit(app))?.buttons)
+      .toEqual(ACTIONS);
+    await expect.poll(async () => (await headerFit(app))?.menu).toEqual([]);
+  });
+});

e2e/specs/jobs-in-settings.spec.ts

@@ -0,0 +1,124 @@
+import { test, expect, waitForEvent } from '../support/fixtures.js';
+
+/**
+ * The Jobs tab folded into the places the work is started (#27).
+ *
+ * The assertion worth making is not that the tab is gone — that is one
+ * line of a table — but that **nothing became unreachable when it
+ * went**. Scanning is the case that mattered: the per-library controls
+ * lived only on that page, and the tab's own comment says they had been
+ * moved there out of Settings in the first place.
+ *
+ * `#24` wrote down one sentence covering all three size bands: *no
+ * action is ever unreachable at any supported size*. Deleting a
+ * destination is exactly the change that can quietly break it.
+ */
+type Page = import('@playwright/test').Page;
+
+const section = (page: Page, heading: string) =>
+  page.locator(`config-page config-section[heading="${heading}"]`);
+
+async function openSettings(page: Page, heading: string): Promise<void> {
+  await page.getByTestId('nav-settings').click();
+
+  // The section's own disclosure, by role rather than by `.header`:
+  // an open Libraries section also contains `job-details-drawer`,
+  // whose own header matches that class and makes it ambiguous.
+  const header = section(page, heading)
+    .getByRole('button', { name: heading })
+    .first();
+
+  await expect(header).toBeVisible();
+
+  if ((await header.getAttribute('aria-expanded')) === 'false') {
+    await header.click();
+  }
+
+  await expect(header).toHaveAttribute('aria-expanded', 'true');
+}
+
+test.describe('background jobs live where the work is started', () => {
+  test('the Jobs destination is gone', async ({ app }) => {
+    await expect(app.getByTestId('nav-jobs')).toHaveCount(0);
+
+    // And it is not offered as a launch page either, which is the copy
+    // of the destination list that is easiest to forget.
+    await openSettings(app, 'General');
+
+    const options = await section(app, 'General')
+      .locator('select')
+      .first()
+      .locator('option')
+      .allTextContents();
+
+    expect(options).not.toContain('Jobs');
+  });
+
+  /**
+   * Scanning is startable from Settings → Libraries, and the job that
+   * results is visible there with its controls. One assertion covers
+   * both halves, because a Scan All that started nothing would leave
+   * the panel empty and read exactly like a panel that does not work.
+   */
+  test('a scan is started and watched in Settings', async ({ app }) => {
+    await openSettings(app, 'Libraries');
+
+    const libraries = section(app, 'Libraries');
+
+    await libraries.getByRole('button', { name: 'Scan All' }).click();
+
+    await waitForEvent(app, 'LibraryScanComplete', { timeoutMs: 60_000 });
+
+    const panel = libraries.locator('job-panel');
+
+    await expect(panel.locator('job-row')).toHaveCount(1, { timeout: 10_000 });
+
+    // The generic affordances are the point of the panel: the tier
+    // list and the progress rings the other surfaces already had
+    // cannot open a log.
+    await expect(
+      panel.getByRole('button', { name: /^Details/ }),
+    ).toBeVisible();
+  });
+
+  /** A finished job dismisses from where it is shown. */
+  test('a finished scan can be dismissed in place', async ({ app }) => {
+    await openSettings(app, 'Libraries');
+
+    const panel = section(app, 'Libraries').locator('job-panel');
+    const dismiss = panel.getByRole('button', { name: /^Dismiss/ }).first();
+
+    await expect(dismiss).toBeVisible({ timeout: 10_000 });
+    await dismiss.click();
+
+    await expect(panel.locator('job-row')).toHaveCount(0);
+  });
+
+  /**
+   * Full rescan is destructive and asks first. It is asserted at the
+   * dialog rather than through it — running one against the seeded app
+   * would delete the library the rest of the suite reads.
+   */
+  test('Full Rescan asks before it does anything', async ({ app }) => {
+    await openSettings(app, 'Libraries');
+
+    await section(app, 'Libraries')
+      .getByRole('button', { name: 'Full Rescan' })
+      .click();
+
+    const dialog = app.getByRole('dialog', { name: 'Full rescan' });
+
+    await expect(dialog).toBeVisible();
+
+    // The message is read off the *host*, not the dialog: a wa-dialog
+    // keeps its slotted content in the host's shadow root, so
+    // `toContainText` on the dialog itself sees only Web Awesome's
+    // chrome.
+    await expect(app.locator('confirm-dialog')).toContainText(
+      'deletes all library data',
+    );
+
+    await app.getByRole('button', { name: 'Cancel' }).click();
+    await expect(dialog).toBeHidden();
+  });
+});

e2e/specs/jobs-on-a-phone.spec.ts

@@ -0,0 +1,204 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * #62. On a phone, background work is shown in the notification band
+ * and the header indicator stands down.
+ *
+ * The report was that the indicator's popover "is obscured by other UI,
+ * so it cannot be read while jobs run". Worth saying plainly: **that
+ * symptom did not reproduce in this tier.** Measured at the device's
+ * own 424x439 viewport, the popover was neither clipped nor covered —
+ * `elementFromPoint` at its centre returned the indicator at every
+ * width tried. So this is not a fix for a stacking bug, and a spec
+ * asserting one would be a spec asserting something that was never
+ * true here.
+ *
+ * What is true regardless, and is what these assert:
+ *
+ * - a popover is a **disclosure**, and it is anchored to a bar 3.25em
+ *   tall on a screen 439px tall. Background work is the one thing a
+ *   phone should not make you open something to see.
+ * - #57 deletes that bar and is *blocked on this issue*, because the
+ *   indicator needs somewhere else to live first. Somewhere else is
+ *   the band, and the test that matters for #57 is that the bar no
+ *   longer holds the indicator at all.
+ *
+ * This is the media-query tier by necessity: a query inside a shadow
+ * root is answered by the viewport, and `notification-host` decides
+ * whether the panel *exists* from `matchMedia`. The component tier
+ * cannot set either.
+ */
+
+type Page = import('@playwright/test').Page;
+
+const JOBS = [
+  {
+    id: 'phone:scan',
+    kind: 'library-scan',
+    state: 'running',
+    title: 'Scanning Music',
+    current: 40,
+    total: 100,
+    caps: { pausable: true, cancellable: true },
+  },
+  {
+    id: 'phone:idx',
+    kind: 'index-build',
+    state: 'running',
+    title: 'Building the search index',
+    current: 2,
+    total: 9,
+    caps: { pausable: true, cancellable: true },
+  },
+];
+
+/** The panel the band renders. Playwright's CSS engine pierces open
+ *  shadow roots, which is what keeps this one line. */
+const bandPanel = (page: Page) => page.locator('job-band').locator('job-panel');
+
+const PHONE = { width: 424, height: 439 };
+const DESKTOP = { width: 1100, height: 800 };
+
+test.describe('background jobs on a phone', () => {
+  test('are shown in the band, without opening anything', async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize(PHONE);
+    await testctl.emit('JobsChanged', JOBS);
+
+    await expect(bandPanel(app)).toBeVisible();
+
+    // Both jobs, drawn by real `job-row`s -- asking the rows what they
+    // hold rather than reading the panel's text, which would pass
+    // whether or not a row rendered. Playwright's CSS engine pierces
+    // open shadow roots, which is what makes this one line;
+    // `querySelectorAll` does not, and stops at `job-panel`.
+    await expect(bandPanel(app).locator('job-row')).toHaveCount(2);
+
+    await expect(
+      bandPanel(app).locator('job-row').first(),
+    ).toContainText('Scanning Music');
+  });
+
+  /**
+   * The #57 assertion. Not "the indicator is invisible" — that could be
+   * true because the bar overflowed — but that the shell's own rule
+   * puts it away at this width.
+   */
+  test('leave the top bar, which is what #57 is waiting for', async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize(PHONE);
+    await testctl.emit('JobsChanged', JOBS);
+    await expect(bandPanel(app)).toBeVisible();
+
+    await expect(app.locator('job-indicator')).toBeHidden();
+  });
+
+  /**
+   * The property the first attempt at this got wrong, so it is the one
+   * worth pinning: the band is **in the layout**, not over it.
+   *
+   * A fixed band reads fine in a screenshot and is unusable -- at
+   * 424x439 a compact panel is ~200px of a 439px screen and it covers
+   * what is under it. Four specs failed on that version, two
+   * phone-shell journeys and the header's action menu, because the
+   * panel was intercepting the taps. So: nothing of the app is
+   * underneath it, and the main panel starts below it.
+   */
+  test('push the content down rather than covering it', async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize(PHONE);
+
+    const before = await app
+      .getByTestId('main-content')
+      .evaluate((el) => el.getBoundingClientRect().top);
+
+    await testctl.emit('JobsChanged', JOBS);
+    await expect(bandPanel(app)).toBeVisible();
+
+    const after = await app.evaluate(() => {
+      const band = document.querySelector('job-band') as HTMLElement;
+      const main = document.querySelector(
+        '[data-testid="main-content"]',
+      ) as HTMLElement;
+      const b = band.getBoundingClientRect();
+      const m = main.getBoundingClientRect();
+
+      // What the browser reports at the band's own centre. If this is
+      // anything but the band, the band is sitting on top of it.
+      const hit = document.elementFromPoint(
+        Math.round(b.x + b.width / 2),
+        Math.round(b.y + b.height / 2),
+      );
+
+      return {
+        mainTop: m.top,
+        bandBottom: b.bottom,
+        withinViewport: b.bottom <= window.innerHeight + 0.5,
+        hit: hit?.tagName.toLowerCase() ?? null,
+      };
+    });
+
+    expect({
+      pushed: after.mainTop > before,
+      mainClearsBand: after.mainTop >= after.bandBottom - 0.5,
+      withinViewport: after.withinViewport,
+      hit: after.hit,
+    }).toEqual({
+      pushed: true,
+      mainClearsBand: true,
+      withinViewport: true,
+      hit: 'job-band',
+    });
+  });
+
+  /**
+   * A running job repaints several times a second. The stack it sits
+   * beside is `role="status" aria-live="polite"`, and a progress bar
+   * inside a live region is a screen reader reading a number out over
+   * and over — so the two are siblings in the band rather than one
+   * list, and this is what says so.
+   */
+  test('are not inside the live region they sit beside', async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize(PHONE);
+    await testctl.emit('JobsChanged', JOBS);
+    await expect(bandPanel(app)).toBeVisible();
+
+    const insideLiveRegion = await app.evaluate(() => {
+      const band = document.querySelector('job-band');
+
+      // Neither the band itself nor anything it is nested in may be a
+      // live region -- `closest` answers both at once.
+      return !!band?.closest('[aria-live]') || band?.hasAttribute('aria-live');
+    });
+
+    expect(insideLiveRegion).toBe(false);
+  });
+
+  /**
+   * `bottom-nav` rendering its duplicate `<app-sidebar>` unconditionally
+   * broke 30 specs with "resolved to 2 elements" on a viewport where it
+   * was not even visible. Settings already holds four `job-panel`s, so
+   * a fifth that answers for *every* kind is the same trap — which is
+   * why the band decides from `matchMedia` whether the element exists
+   * rather than hiding it with CSS.
+   */
+  test('do not leave a second panel behind on a desktop', async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize(DESKTOP);
+    await testctl.emit('JobsChanged', JOBS);
+
+    await expect(app.locator('job-indicator')).toBeVisible();
+    await expect(bandPanel(app)).toHaveCount(0);
+  });
+});

e2e/specs/layout-overflow.spec.ts

@@ -26,7 +26,21 @@ const MIN_VIEWPORT = { width: 800, height: 600 };
 const VIEWPORTS = [
   { name: '1440×900', width: 1440, height: 900 },
   { name: '1024×768', width: 1024, height: 768 },
+  // Not the minimum, and that is the point (#24). The sidebar collapses
+  // to icons *below* 900, so the main panel is 843px at 899 and 700px
+  // at 900 — the narrowest content area any desktop width produces is
+  // here, not at the enforced floor. A list that stopped at the minimum
+  // was missing its own worst case.
+  { name: '900×600 (the widest sidebar, so the narrowest content)', width: 900, height: 600 },
   { name: `the minimum (${MIN_VIEWPORT.width}×${MIN_VIEWPORT.height})`, ...MIN_VIEWPORT },
+  // Below the enforced minimum on purpose, and for the reason 700×480
+  // is below it further down: a scaled display or a large system font
+  // lands the layout here without the window ever being dragged there,
+  // and 600 is the last width before the phone layout takes over. The
+  // *narrowest header* is a different question from the narrowest
+  // content area and has a different answer — this one (#143), where
+  // the bar was 611px inside 600 sitting still.
+  { name: '600×600 (the bottom of the Compact band)', width: 600, height: 600 },
 ];
 
 /**
@@ -87,9 +101,10 @@ test.describe('the app fits in its own window', () => {
       )
       .toBe(true);
 
-    // Settings and Jobs are the two that were unreachable: they are
-    // last in the nav, and the pane used to clip rather than scroll.
-    for (const view of ['jobs', 'settings'] as const) {
+    // Settings is the one that was unreachable: it is last in the nav,
+    // and the pane used to clip rather than scroll. (Jobs was the other
+    // half of this until #27 folded it into Settings.)
+    for (const view of ['explore', 'settings'] as const) {
       const item = app.getByTestId(`nav-${view}`);
 
       await item.scrollIntoViewIfNeeded();
@@ -117,27 +132,45 @@ test.describe('the app fits in its own window', () => {
     // be dragged here, but a scaled display or a large system font can
     // still land the layout in it, and clipping the nav with no scroll
     // is the failure that made Settings unreachable.
-    const reachable = await app.locator('app-sidebar').evaluate((el) => {
-      const settings = el.shadowRoot?.querySelector<HTMLElement>(
-        '[data-testid="nav-settings"]',
-      );
+    //
+    // The scroll and the measurement share one `evaluate` — #151's
+    // rule, which this already had — and the whole probe is polled,
+    // which it did not: a viewport change settles asynchronously, so a
+    // single attempt reads whatever the sidebar happened to be doing.
+    // The probe is safe to repeat because scrolling to the bottom twice
+    // is scrolling to the bottom.
+    await expect
+      .poll(() =>
+        app.locator('app-sidebar').evaluate((el) => {
+          const settings = el.shadowRoot?.querySelector<HTMLElement>(
+            '[data-testid="nav-settings"]',
+          );
 
-      if (!settings) return null;
+          if (!settings) return null;
 
-      el.scrollTop = el.scrollHeight;
+          el.scrollTop = el.scrollHeight;
 
-      const item = settings.getBoundingClientRect();
-      const pane = el.getBoundingClientRect();
+          const item = settings.getBoundingClientRect();
+          const pane = el.getBoundingClientRect();
 
-      return item.bottom <= Math.ceil(pane.bottom) && item.top >= Math.floor(pane.top);
-    });
-
-    expect(reachable).toBe(true);
+          return (
+            item.bottom <= Math.ceil(pane.bottom) &&
+            item.top >= Math.floor(pane.top)
+          );
+        }),
+      )
+      .toBe(true);
   });
 });
 
 test.describe('the title block fits its bar', () => {
   test('the hgroup stays inside the 4em top bar', async ({ app }) => {
+    // Stated rather than inherited from whatever ran last. Since #143
+    // the wordmark is visually hidden at widths where the bar cannot
+    // afford it, so a test about its *vertical* fit has to say which
+    // width it is asking about.
+    await app.setViewportSize({ width: 1440, height: 900 });
+
     // The state a11y.29 landed in. The pair is flex-centred and a UA
     // gives an `h1` a 0.67em top margin, so the block measured 67px
     // inside 64 — pre-existing, and invisible until dropping the h3's
@@ -239,16 +272,26 @@ test.describe('the shell reflows rather than hiding what does not fit', () => {
     test(`no scrollbar appears at ${vp.name}`, async ({ app }) => {
       await app.setViewportSize({ width: vp.width, height: vp.height });
 
-      const excess = await app.evaluate(() => {
-        const de = document.documentElement;
+      // Polled, for the reason the track-row test above is: since #143
+      // the top bar's fit is *measured* — a ResizeObserver decides what
+      // it can afford at this width — so a single read taken straight
+      // after the resize races the observer and reports the frame
+      // before it. Read once, this passed alone and failed in the full
+      // suite, which is the shape of a timing assumption rather than of
+      // a defect.
+      //
+      // The other half of the assertion: at every size this app
+      // promises, the fix costs nothing. A scrollbar that is always
+      // there is a worse answer than the clipping it replaced.
+      await expect
+        .poll(() =>
+          app.evaluate(() => {
+            const de = document.documentElement;
 
-        return de.scrollWidth - de.clientWidth;
-      });
-
-      // The other half: at every size this app promises, the fix costs
-      // nothing. A scrollbar that is always there is a worse answer
-      // than the clipping it replaced.
-      expect(excess).toBe(0);
+            return de.scrollWidth - de.clientWidth;
+          }),
+        )
+        .toBe(0);
     });
   }
 });

e2e/specs/offline-icons.spec.ts

@@ -28,7 +28,7 @@ const EXPECTED_MIN_ICONS = 5;
 
 const VIEWS = [
   'home', 'tracks', 'albums', 'artists', 'genres', 'playlists',
-  'explore', 'downloads', 'jobs', 'settings',
+  'explore', 'downloads', 'autotag', 'settings',
 ];
 
 type IconState = { name: string; hasSvg: boolean };

e2e/specs/page-header.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, navigateTo } from '../support/fixtures.js';
 
 /**
  * H-19: Playlists, Downloads, Jobs, Settings and Home had a page
@@ -21,7 +21,6 @@ const VIEWS: [string, string, boolean][] = [
   ['tracks', 'Tracks', true],
   ['explore', 'Explore', false],
   ['downloads', 'Downloads', false],
-  ['jobs', 'Background jobs', false],
 ];
 
 /** The header lives in the view's shadow root, inside its own. */
@@ -53,13 +52,16 @@ const TAGS: Record<string, string> = {
   tracks: 'track-list',
   explore: 'explore-view',
   downloads: 'downloads-view',
-  jobs: 'jobs-view',
 };
 
 test.describe('every primary view says what it is', () => {
   test('each one has the shared header, with a heading', async ({ app }) => {
+    // By event rather than by nav item: a destination is not
+    // guaranteed to have one any more (#25 — Downloads is absent
+    // without a download client), and every one of these is still a
+    // primary view with a header, which is what this spec is about.
     for (const [view, heading, hasCount] of VIEWS) {
-      await app.getByTestId(`nav-${view}`).click();
+      await navigateTo(app, view);
       await expect(app.getByTestId('main-content')).toHaveAttribute(
         'data-active-view',
         view,

e2e/specs/phone-shell.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, LONG_TRACK } from '../support/fixtures.js';
 
 /**
  * The phone shell (plan 016 B2, phase 1).
@@ -138,6 +138,78 @@ test.describe('the shell on a phone', () => {
       .toHaveAttribute('data-active-view', 'tracks');
   });
 
+  /**
+   * The same journey with a track that has **no cover art** (#150).
+   *
+   * The test above starts the *first* row of the track list, so which
+   * track it plays is the order the scan inserted them in — and the
+   * answer decided whether it passed. A track with artwork renders an
+   * `<img>`, which is no obstacle; one without renders a placeholder
+   * `wa-icon`, which took every click aimed at the button beneath it,
+   * because that button is absolutely positioned with `z-index: auto`
+   * and the art is a *later* sibling. They tied, and the later one won.
+   *
+   * So this picks a track *for* the property that broke it, which is
+   * the only way the assertion means anything: the version above passes
+   * on a broken build roughly two runs in three, which is exactly how
+   * it came to cost three CI cycles across two branches that could not
+   * have caused it.
+   */
+  test('opens the full-screen now playing for a track with no art', async ({
+    app,
+  }) => {
+    // `LONG_TRACK` by name, and not "the first track with no
+    // CoverArt": the *library* model reports that field empty for
+    // every row in this fixture (31 of 31), so filtering on it selects
+    // nothing in particular and picked a 2-second track, which had
+    // finished before the assertions ran. The placeholder check below
+    // is what actually holds the property this test needs.
+    const started = await app.evaluate(async (longTitle) => {
+      const tracks = (await window.__yjEvents.call(
+        'library.Library.GetTracks',
+        [0],
+        10_000,
+      )) as { FilePath: string; TrackName: string }[];
+
+      const bare = tracks.find((t) => t.TrackName === longTitle);
+
+      if (!bare) return null;
+
+      await window.__yjEvents.call(
+        'queue.Queue.SetQueue',
+        [[bare.FilePath], 0, false, { type: '', id: 0, label: '' }],
+        10_000,
+      );
+      await window.__yjEvents.call('queue.Queue.Play', [], 5_000);
+
+      return bare.TrackName;
+    }, LONG_TRACK);
+
+    expect(started).toBe(LONG_TRACK);
+
+    await expect(app.getByTestId('now-playing-title')).not.toBeEmpty();
+
+    // **The placeholder is the whole point**, so it is asserted rather
+    // than assumed: this test is about the thing that renders when
+    // there is no artwork. If the fixture ever gives this album a
+    // cover, this fails and says so instead of passing while measuring
+    // the easy case.
+    //
+    // One selector rather than a chain from the host: Playwright's CSS
+    // engine pierces an open shadow root, and chaining from the host
+    // element does not reach into it.
+    await expect(
+      app.locator('now-playing .cover-placeholder'),
+    ).toBeAttached();
+
+    await app.getByTestId('open-now-playing').click();
+
+    await expect(app.getByTestId('main-content'))
+      .toHaveAttribute('data-active-view', 'now-playing');
+
+    await app.getByTestId('npv-back').click();
+  });
+
   test('offers no way in on a desktop, where the bar is whole', async ({ app }) => {
     await app.setViewportSize({ width: 1440, height: 900 });
 
@@ -154,9 +226,26 @@ test.describe('the shell on a phone', () => {
     await expect(app.locator('now-playing')).toBeVisible();
 
     // Volume is the hardware keys' job on a phone, and a 4px seek bar
-    // is not a thumb target -- both belong to a later phase's
-    // full-screen now-playing view.
-    await expect(app.locator('audio-player volume-control')).toBeHidden();
+    // is not a thumb target -- both belong to the full-screen
+    // now-playing view.
+    //
+    // `.bottom-bar volume-control`, not `audio-player volume-control`:
+    // #42 moved the control out of that component and into the bar, and
+    // **the old locator would have kept passing** — `toBeHidden()` is
+    // satisfied by an element that does not exist, so this assertion
+    // would have gone on reporting success about nothing. Its partner
+    // below is what makes this one mean something.
+    await expect(app.locator('.bottom-bar volume-control')).toBeHidden();
+
+    // The element is there and hidden, rather than absent: the check
+    // above cannot tell those apart on its own.
+    await expect(app.locator('.bottom-bar volume-control')).toHaveCount(1);
+
+    // And the seek bar is still inside the transport, where it stands
+    // down by its own media query.
+    await expect(
+      app.locator('audio-player').locator('seek-bar'),
+    ).toBeHidden();
   });
 });
 

e2e/specs/queue-overlay.spec.ts

@@ -0,0 +1,187 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * #24 — the queue panel does not take the page's width away from it.
+ *
+ * The panel is `flex-shrink: 0` in the flow of `.content-area`, so an
+ * open queue used to be paid for by the main panel. Measured on
+ * Playlists before the fix:
+ *
+ * | viewport | main panel |
+ * |---|---|
+ * | 900×600 | 379px — all three header actions clipped |
+ * | 390×780 | 69px |
+ * | 320×600 | **0px** |
+ *
+ * **900×600 is the worst desktop case, not the 800×600 minimum**, and
+ * that is the trap this file exists to keep closed: the sidebar
+ * collapses to icons *below* 900, so the main panel is 843px at 899 and
+ * 700px at 900. A spec that checks "the minimum" and stops has not
+ * checked the worst case — which is what every viewport list in this
+ * suite did before this.
+ *
+ * These assert the *content's* width rather than the panel's mode
+ * wherever they can, because the mode is the mechanism and the width is
+ * the complaint.
+ */
+
+/** The bands from plan 018's size matrix, plus the pixel above the collapse. */
+const BANDS = [
+  { name: 'a wide desktop (1280×800)', width: 1280, height: 800, inline: true },
+  { name: 'the default window (1100×720)', width: 1100, height: 720, inline: true },
+  { name: 'a laptop (1024×768)', width: 1024, height: 768, inline: true },
+  { name: 'the worst desktop width (900×600)', width: 900, height: 600, inline: false },
+  { name: 'the enforced minimum (800×600)', width: 800, height: 600, inline: false },
+  { name: 'a phone (390×780)', width: 390, height: 780, inline: false },
+  { name: '400% zoom (320×600)', width: 320, height: 600, inline: false },
+];
+
+/**
+ * How much room the content has, and whether the shell needs scrolling
+ * to reach any of itself.
+ */
+const shellGeometry = (page: import('@playwright/test').Page) =>
+  page.evaluate(() => {
+    const main = document.querySelector('#main-content')!.getBoundingClientRect();
+    const panel = document.querySelector('#queue-panel')!;
+
+    return {
+      mainWidth: Math.round(main.width),
+      overlay: panel.hasAttribute('overlay'),
+      open: panel.hasAttribute('open'),
+      bodyScrollWidth: document.body.scrollWidth,
+      bodyClientWidth: document.body.clientWidth,
+    };
+  });
+
+async function openQueue(page: import('@playwright/test').Page) {
+  const toggle = page.locator('#queue-button');
+
+  if ((await toggle.getAttribute('aria-expanded')) !== 'true') {
+    await toggle.click();
+  }
+
+  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+}
+
+test.describe('an open queue leaves the content its width', () => {
+  for (const band of BANDS) {
+    test(`at ${band.name}`, async ({ app }) => {
+      await app.setViewportSize({ width: band.width, height: band.height });
+      await openQueue(app);
+
+      // The mode is settled by a ResizeObserver, so poll rather than
+      // read once: a single read races the resize and reports the
+      // previous viewport's answer.
+      await expect
+        .poll(async () => (await shellGeometry(app)).overlay)
+        .toBe(!band.inline);
+
+      const geo = await shellGeometry(app);
+
+      // The floor is the point of the whole issue. Inline, the queue is
+      // affordable and the content keeps the rest; as an overlay the
+      // content keeps *everything*, which is what makes 0px at 320
+      // impossible rather than merely unlikely.
+      expect(geo.mainWidth).toBeGreaterThanOrEqual(320);
+
+      if (!band.inline) {
+        expect(geo.mainWidth).toBeGreaterThanOrEqual(
+          Math.min(band.width, 320),
+        );
+      }
+
+      // And opening the queue must not make the shell overflow.
+      expect(geo.bodyScrollWidth).toBeLessThanOrEqual(geo.bodyClientWidth);
+    });
+  }
+});
+
+test.describe('an overlaid queue says it is over the content', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize({ width: 900, height: 600 });
+  });
+
+  test('draws a scrim and closes when it is clicked', async ({ app }) => {
+    await openQueue(app);
+
+    const panel = app.locator('#queue-panel');
+
+    await expect(panel).toHaveAttribute('overlay', '');
+
+    // The scrim is `aria-hidden` on purpose — it is a dismissal target,
+    // and the named routes out are the close button and Escape — so it
+    // is located structurally rather than by role.
+    await panel.evaluate((el) =>
+      el.shadowRoot!.querySelector<HTMLElement>('.scrim')!.click(),
+    );
+
+    await expect(app.locator('#queue-button')).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+  });
+
+  /**
+   * `getByRole`, not a shadow-root query: this repo has shipped a
+   * nameless control three times, and a drawer with a scrim is exactly
+   * the shape that grows a fourth.
+   */
+  test('offers a named close button', async ({ app }) => {
+    await openQueue(app);
+
+    const close = app.getByRole('button', { name: 'Close queue' });
+
+    await expect(close).toBeVisible();
+    await close.click();
+
+    await expect(app.locator('#queue-button')).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+  });
+
+  test('closes on Escape and gives focus back to the toggle', async ({
+    app,
+  }) => {
+    const toggle = app.locator('#queue-button');
+
+    await toggle.focus();
+    await toggle.click();
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+    await app.keyboard.press('Escape');
+
+    await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+    await expect(toggle).toBeFocused();
+  });
+});
+
+/**
+ * The inline panel is the mode that already worked, and the one every
+ * other queue spec is written against. It keeps its resize handle and
+ * gains none of the overlay's chrome.
+ */
+test.describe('a wide window keeps the queue beside the content', () => {
+  test('no scrim, no close button, and the content is narrower', async ({
+    app,
+  }) => {
+    await app.setViewportSize({ width: 1280, height: 800 });
+
+    const widthWithoutQueue = (await shellGeometry(app)).mainWidth;
+
+    await openQueue(app);
+
+    await expect(app.locator('#queue-panel')).not.toHaveAttribute(
+      'overlay',
+      '',
+    );
+
+    const geo = await shellGeometry(app);
+
+    expect(geo.mainWidth).toBeLessThan(widthWithoutQueue);
+    await expect(
+      app.getByRole('button', { name: 'Close queue' }),
+    ).toHaveCount(0);
+  });
+});

e2e/specs/queue-selection.spec.ts

@@ -0,0 +1,299 @@
+import {
+  test,
+  expect,
+  callBinding,
+  navigateTo,
+  LONG_TRACK,
+  NO_QUEUE_SOURCE,
+} from '../support/fixtures.js';
+import type { Page } from '@playwright/test';
+
+/**
+ * The queue panel's mouse model (#43): single click selects, ctrl and
+ * shift extend, double click plays from that row.
+ *
+ * **All four already worked, and nothing pinned any of them** — which is
+ * the whole reason the report could be made and could not be settled.
+ * `queue-reorder.spec.ts` covers the keyboard, `queue-overlay.spec.ts`
+ * covers the panel's mode, and the component tier has the reorder
+ * arithmetic; the pointer path had no coverage in either tier, so
+ * "selection is broken here" and "selection is fine here" were equally
+ * consistent with a green suite.
+ *
+ * Two things this spec is deliberately shaped around.
+ *
+ * **The clicks are real.** A `dispatchEvent(new MouseEvent('click'))`
+ * on a row exercises the delegated handler and *not* the question being
+ * asked, which is what the pointer lands on: the rows carry
+ * `explore-link` names that take their own clicks, and a synthetic
+ * event aimed at the row reports a selection the mouse would never have
+ * produced. Every click here goes through Playwright.
+ *
+ * **The playing assertions use the 90-second fixture.** Every other
+ * track is 2–6 seconds, so "double click plays row 3" read against a
+ * 2-second track reports whatever auto-advance moved on to — measured
+ * during this work as row 3 double-clicked and row 4 playing, which
+ * reads exactly like an off-by-one in `PlayIndex` and is not one.
+ */
+
+/**
+ * How long a click may take to show up as a highlight.
+ *
+ * **A poll with the default 5s timeout cannot see this defect**, and
+ * that is the point of naming it. `queue-panel` repaints its rows two
+ * ways — `onSelectionChanged()` calls `virtualizer.requestUpdate()`,
+ * and `.keyFunction` is a per-render arrow, which is itself a changed
+ * property the virtualizer reacts to. With **both** removed the
+ * highlight still arrives, on whatever unrelated render happens next:
+ * measured at 134ms, 3,866ms and 5,816ms for three clicks, against
+ * 5ms, 16ms and 17ms on a healthy build.
+ *
+ * A user cannot tell "four seconds late" from "broken", which is very
+ * close to what this issue reports. So the assertion is that the
+ * highlight is *prompt*, with a bound ~30x the measured healthy case
+ * and an order of magnitude under the degraded one.
+ */
+const HIGHLIGHT_MS = 500;
+
+/** The queue's own answer, never the DOM's. */
+async function playing(app: Page): Promise<{ index: number; title: string }> {
+  const state = await callBinding<{
+    currentIndex: number;
+    tracks: { title: string }[];
+  }>(app, 'queue.Queue.GetState');
+
+  return {
+    index: state.currentIndex,
+    title: state.tracks[state.currentIndex]?.title ?? '',
+  };
+}
+
+/** Which rows are selected, as the accessibility tree sees it. */
+const selected = (app: Page) =>
+  app.evaluate(() =>
+    [
+      ...document
+        .querySelector('queue-panel')!
+        .shadowRoot!.querySelectorAll('[data-index]'),
+    ]
+      .filter((row) => row.getAttribute('aria-selected') === 'true')
+      .map((row) => Number((row as HTMLElement).dataset['index'])),
+  );
+
+/**
+ * Six tracks with the long one in the middle, so a "play from here"
+ * assertion has something to land on that will still be playing when it
+ * is read back.
+ */
+async function queueSixAndOpen(app: Page): Promise<void> {
+  const paths = await app.evaluate(async (longTitle) => {
+    // `TrackName`, not `Title`: the library model names it after the
+    // tag, and the *queue* is what calls it `title`.
+    const tracks = (await window.__yjEvents.call(
+      'library.Library.GetTracks',
+      [0],
+      10_000,
+    )) as { FilePath: string; TrackName: string; Album: string }[];
+
+    const long = tracks.find((t) => t.TrackName === longTitle);
+
+    /**
+     * **Tracks that have an album**, which is a requirement of one of
+     * the tests and was previously left to luck (#156).
+     *
+     * `explore-link` routes a track name to its *album's* page, so a
+     * track with no album renders a name that navigates nowhere — and
+     * the fixture library deliberately contains two (`01 Tone A`,
+     * `02 Tone B`). Which tracks arrive first is `audio_files.id`
+     * order, i.e. the order the **scan** inserted them, which depends
+     * on concurrency and directory traversal: locally the first eight
+     * all had albums and the spec passed twice over, and CI rebuilds
+     * its seed with a real scan and got a different eight.
+     *
+     * Asking for what the test needs is the fix. It is not a
+     * narrowing: every assertion here wants an ordinary track, and
+     * "the first five rows" was never a way to ask for one in a
+     * library whose whole purpose is edge cases.
+     */
+    const rest = tracks
+      .filter((t) => t.TrackName !== longTitle && t.Album !== '')
+      .slice(0, 5);
+
+    // Index 3 is the long one: far enough down that a shift-extend has
+    // room either side of it.
+    return [
+      ...rest.slice(0, 3).map((t) => t.FilePath),
+      long!.FilePath,
+      ...rest.slice(3).map((t) => t.FilePath),
+    ];
+  }, LONG_TRACK);
+
+  await callBinding(app, 'queue.Queue.SetQueue', [
+    paths,
+    0,
+    false,
+    NO_QUEUE_SOURCE,
+  ]);
+
+  // A closed panel renders no list at all.
+  await app.locator('#queue-button').click();
+  await expect(app.locator('queue-panel .track-item').first()).toBeVisible();
+  await expect(app.locator('queue-panel .track-item')).toHaveCount(6);
+}
+
+/** The row at a data-index, not the nth child: see the note in the file. */
+const row = (app: Page, index: number) =>
+  app.locator(`queue-panel .track-item[data-index="${index}"]`);
+
+test.describe('selecting in the queue with a mouse', () => {
+  // The suite shares one backend in file order, and a queue and an open
+  // panel both outlive the page. `queue-reorder.spec.ts` sets the
+  // precedent and the reason: a spec that spends state fails the next
+  // one, in a list that reads like a regression in whatever you hold.
+  test.afterEach(async ({ app }) => {
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {
+      /* an empty queue is the state we were asking for */
+    });
+
+    const open = await app.locator('queue-panel[open]').count();
+
+    if (open > 0) await app.locator('#queue-button').click();
+  });
+
+  test('a single click selects that row and only that row', async ({ app }) => {
+    await queueSixAndOpen(app);
+
+    await row(app, 1).click();
+    await expect
+      .poll(() => selected(app), { timeout: HIGHLIGHT_MS })
+      .toEqual([1]);
+
+    // And it *replaces* rather than accumulating, which is the half a
+    // test of one click cannot see.
+    await row(app, 4).click();
+    await expect
+      .poll(() => selected(app), { timeout: HIGHLIGHT_MS })
+      .toEqual([4]);
+  });
+
+  test('ctrl adds a row and shift extends a range', async ({ app }) => {
+    await queueSixAndOpen(app);
+
+    await row(app, 1).click();
+    await row(app, 3).click({ modifiers: ['Control'] });
+    await expect
+      .poll(() => selected(app), { timeout: HIGHLIGHT_MS })
+      .toEqual([1, 3]);
+
+    // From the last row touched, so 3→5, keeping the ctrl-picked 1.
+    await row(app, 5).click({ modifiers: ['Shift'] });
+    await expect
+      .poll(() => selected(app), { timeout: HIGHLIGHT_MS })
+      .toEqual([1, 3, 4, 5]);
+
+    // A plain click collapses the whole thing back to one.
+    await row(app, 2).click();
+    await expect
+      .poll(() => selected(app), { timeout: HIGHLIGHT_MS })
+      .toEqual([2]);
+  });
+
+  test('a double click plays from that row', async ({ app }) => {
+    await queueSixAndOpen(app);
+
+    // Row 3 is the 90-second track. Asked of the backend, because the
+    // panel's own highlight is a different claim.
+    await row(app, 3).dblclick();
+
+    await expect.poll(() => playing(app)).toEqual({
+      index: 3,
+      title: LONG_TRACK,
+    });
+
+    // Playing is not selecting: the double click clears the selection
+    // it made on the way through, or every play leaves a row looking
+    // picked out for an action the user did not ask for.
+    await expect.poll(() => selected(app)).toEqual([]);
+  });
+
+  /**
+   * The one collision the report is actually about.
+   *
+   * Every track, album and artist name in the app navigates
+   * (`utils/explore-link.ts`), and it does that by **stopping the
+   * click's propagation** — in its own words, "the row must not also
+   * treat it as a selection". So a click that lands on the name text
+   * navigates and selects nothing, in the queue panel and in the track
+   * list alike.
+   *
+   * That is deliberate and it is pinned here rather than argued with,
+   * because the measurement says the queue is not the surface where it
+   * hurts: a horizontal hit-scan of a row at three heights makes the
+   * queue row **12%** link and the track list's row **21%** — the panel
+   * the report calls broken is *less* covered by links than the list it
+   * calls correct. What is left is one deliberate exception, and a
+   * change to it should have to fail a test.
+   */
+  test('a click on a name navigates instead, and that is the exception', async ({
+    app,
+  }) => {
+    await queueSixAndOpen(app);
+
+    await row(app, 1).click();
+    await expect
+      .poll(() => selected(app), { timeout: HIGHLIGHT_MS })
+      .toEqual([1]);
+
+    // `.track-title .explore-link`, not `.explore-link` first(): a row
+    // has two, and which one `first()` finds depends on whether the
+    // *title* is a link at all. It is not, for a track with no album —
+    // `explore-link` renders plain text where it cannot route — so the
+    // loose locator silently clicked the **artist** instead and the
+    // assertion below was about a different destination than the one
+    // being exercised (#156).
+    await row(app, 2).locator('.track-title .explore-link').click();
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'explore-album-details',
+    );
+
+    // Row 2 did not join the selection — the link took the click.
+    await expect.poll(() => selected(app)).toEqual([1]);
+
+    await navigateTo(app, 'tracks');
+  });
+
+  /**
+   * And the other half of that bargain: the link holds its navigation
+   * for one double-click interval and drops it if a second click
+   * arrives, so double-clicking a *name* still plays the row rather
+   * than navigating away from it. That is what makes the exception
+   * above survivable, and it is the part most likely to break silently
+   * if the grace interval is ever removed.
+   */
+  test('a double click on a name plays rather than navigating', async ({
+    app,
+  }) => {
+    await queueSixAndOpen(app);
+
+    // Read rather than assumed: which view the app lands on is the
+    // user's `DefaultPage`, so naming one here would be asserting on a
+    // config value in a test about a double click.
+    const before = await app
+      .getByTestId('main-content')
+      .getAttribute('data-active-view');
+
+    await row(app, 3).locator('.explore-link').first().dblclick();
+
+    await expect.poll(() => playing(app)).toEqual({
+      index: 3,
+      title: LONG_TRACK,
+    });
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      before!,
+    );
+  });
+});

e2e/specs/settings-reach.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, navigateTo } from '../support/fixtures.js';
 
 /**
  * Plan 007 phase 5: a11y.1 and a11y.2, frozen against the real app.
@@ -18,16 +18,19 @@ test.describe('Settings is reachable without a mouse', () => {
   }) => {
     await app.getByTestId('nav-settings').click();
 
-    const headers = app.locator('config-page config-section .header');
+    // Per *section*, not per `.header`: a section holding a
+    // `job-panel` (#27) also contains `job-details-drawer`, whose own
+    // header carries that class and is not a disclosure.
+    const sections = app.locator('config-page config-section');
 
-    await expect(headers.first()).toBeVisible();
+    await expect(sections.first()).toBeVisible();
 
-    const count = await headers.count();
+    const count = await sections.count();
 
     expect(count).toBeGreaterThan(4);
 
     for (let i = 0; i < count; i++) {
-      const header = headers.nth(i);
+      const header = sections.nth(i).locator('.header').first();
 
       expect(await header.evaluate((el) => el.tagName)).toBe('BUTTON');
       expect(['true', 'false']).toContain(
@@ -56,7 +59,9 @@ test.describe('Settings is reachable without a mouse', () => {
 
 test.describe("Downloads' tabs are tabs", () => {
   test('arrow keys move the selection and swap the panel', async ({ app }) => {
-    await app.getByTestId('nav-downloads').click();
+    // By event, not by nav item: with no download client configured
+    // there is no Downloads destination to click (#25).
+    await navigateTo(app, 'downloads');
 
     const view = app.locator('downloads-view');
     const requests = view.getByRole('tab', { name: 'Requests' });

e2e/specs/top-bar-fit.spec.ts

@@ -0,0 +1,223 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * The top bar fits the window it is in (#143).
+ *
+ * **This is measured per child, not on the shell**, which is #69's
+ * lesson repeated one component over: `layout-overflow.spec.ts` asserts
+ * the *document* needs no sideways scrolling, and clipping inside a
+ * component is invisible to it — which is exactly why that spec was
+ * green throughout this defect. What a user sees is a control rendered
+ * past the edge of the bar it belongs to, so that is what is asserted.
+ *
+ * **And it is measured with a job running**, which is the half the
+ * original report missed. `job-indicator` is `hidden` while idle and up
+ * to 235px wide when it is not, so the bar was 611px inside 600 sitting
+ * still and 862px during a scan — 171 to 262px of overflow, arriving
+ * exactly when a user has reason to look at that bar. Nothing else in
+ * this suite has ever measured a layout with work in flight;
+ * `/__test/emit` stages it without staging the scan.
+ */
+type Page = import('@playwright/test').Page;
+
+/**
+ * The widths this asks about.
+ *
+ * 600 is the bottom of the Compact band (#24) and where the defect
+ * lands; 899 and 900 straddle `nav-history` appearing (68px more to
+ * find, at the width that just gained the sidebar's labels); 800 is the
+ * enforced minimum; 390 is a phone, where the answer must be that
+ * nothing collapses because the media queries already did the work.
+ */
+const WIDTHS = [390, 600, 800, 899, 900, 1440];
+
+/**
+ * A scan whose title is as long as a real one gets. The label is capped
+ * at 12rem by the component, so this is the widest the indicator can
+ * be — measuring with "Scanning" instead reports a bar that fits and a
+ * defect that is 100px smaller than it is.
+ */
+const LONG_JOB = {
+  id: 'top-bar-fit',
+  kind: 'library-scan',
+  state: 'running',
+  title: 'Scanning Music from the external drive',
+  current: 40,
+  total: 100,
+};
+
+/**
+ * Every child's right edge against the bar's own content box.
+ *
+ * The content box, not `clientWidth`: the bar has a 2em right gutter,
+ * and a control sitting in the padding is already the failure — it is
+ * simply one that `scrollWidth` under-reports, because `scrollWidth`
+ * counts the left padding and not the right.
+ */
+const overflowingChildren = (page: Page) =>
+  page.evaluate(() => {
+    const bar = document.querySelector<HTMLElement>('header.top-bar')!;
+    const style = getComputedStyle(bar);
+    const box = bar.getBoundingClientRect();
+    const left = box.left + parseFloat(style.paddingLeft);
+    const right = box.right - parseFloat(style.paddingRight);
+
+    return [...bar.children]
+      .filter((child) => {
+        const cs = getComputedStyle(child);
+
+        // Out of flow is out of the question: a collapsed wordmark is
+        // `position: absolute` and 1px wide precisely so it costs the
+        // row nothing.
+        if (cs.display === 'none' || cs.position === 'absolute') return false;
+
+        const r = child.getBoundingClientRect();
+
+        return r.width > 0 && (r.right > right + 0.5 || r.left < left - 0.5);
+      })
+      .map((child) => {
+        const r = child.getBoundingClientRect();
+
+        return `${child.tagName.toLowerCase()}: ${Math.round(r.left)}..${Math.round(r.right)} outside ${Math.round(left)}..${Math.round(right)}`;
+      });
+  });
+
+/** What the fit pass gave up, read back off the DOM it changed. */
+const collapsed = (page: Page) =>
+  page.evaluate(() => ({
+    wordmark: !!document.querySelector('header.top-bar hgroup.yj-collapsed'),
+    jobLabel: !!document.querySelector('job-indicator[compact]'),
+  }));
+
+test.describe('the top bar fits the window', () => {
+  for (const width of WIDTHS) {
+    test(`no control sits outside the bar at ${width}px, idle`, async ({
+      app,
+    }) => {
+      await app.setViewportSize({ width, height: 600 });
+
+      await expect.poll(() => overflowingChildren(app)).toEqual([]);
+    });
+
+    test(`no control sits outside the bar at ${width}px, with a job running`, async ({
+      app,
+      testctl,
+    }) => {
+      await app.setViewportSize({ width, height: 600 });
+      await testctl.emit('JobsChanged', [LONG_JOB]);
+
+      // The indicator has to actually be up, or this test passes by
+      // measuring the idle case under another name.
+      //
+      // Below 600px there is deliberately no indicator to measure:
+      // #62 stands it down and puts the rows in `<job-band>` instead,
+      // in the layout under the bar. So at 390 the assertion is that
+      // it *is* away and the bar still fits -- which is the same
+      // property (the bar has nothing hanging out of it) reached by the
+      // other branch of the same rule, rather than a width quietly
+      // dropped from the list.
+      const phone = width < 600;
+
+      await expect(app.locator('job-indicator'))[
+        phone ? 'toBeHidden' : 'toBeVisible'
+      ]();
+
+      if (phone) {
+        await expect(app.locator('job-band').locator('job-row')).toHaveCount(1);
+      }
+
+      await expect.poll(() => overflowingChildren(app)).toEqual([]);
+    });
+  }
+
+  /**
+   * The other half of "measured, never breakpointed": a rule that
+   * collapses defensively at every narrow width fits just as well and
+   * is a worse app. 1440 is roomy at any job title; 899 was measured to
+   * fit with the longest one, because `nav-history` is not there yet.
+   */
+  test('nothing is given up where there is room for it', async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+    await testctl.emit('JobsChanged', [LONG_JOB]);
+    await expect(app.locator('job-indicator')).toBeVisible();
+
+    await expect.poll(() => collapsed(app)).toEqual({
+      wordmark: false,
+      jobLabel: false,
+    });
+  });
+
+  /**
+   * And it gives them back. The pass starts from all-visible every
+   * time, so this is the property that a rule which only ever *added*
+   * to the collapsed set would fail — the wordmark would be gone for
+   * the rest of the session after one narrow moment.
+   */
+  test('the wordmark comes back when the window does', async ({
+    app,
+    testctl,
+  }) => {
+    await testctl.emit('JobsChanged', [LONG_JOB]);
+    await app.setViewportSize({ width: 600, height: 600 });
+
+    await expect.poll(() => collapsed(app)).toEqual({
+      wordmark: true,
+      jobLabel: true,
+    });
+
+    await app.setViewportSize({ width: 1440, height: 900 });
+
+    await expect.poll(() => collapsed(app)).toEqual({
+      wordmark: false,
+      jobLabel: false,
+    });
+  });
+
+  /**
+   * The wordmark yields its width and not its existence: `display:
+   * none` would take the document from one top-level heading to none.
+   */
+  test('the collapsed wordmark is still the document heading', async ({
+    app,
+    testctl,
+  }) => {
+    await testctl.emit('JobsChanged', [LONG_JOB]);
+    await app.setViewportSize({ width: 600, height: 600 });
+
+    await expect.poll(() => collapsed(app)).toMatchObject({ wordmark: true });
+
+    await expect(
+      app.getByRole('heading', { name: 'YellowJacket', level: 1 }),
+    ).toHaveCount(1);
+  });
+
+  /**
+   * And the indicator keeps saying what it is doing after its visible
+   * label goes — the `sr-only` live region is what announces the state,
+   * which is the same argument the phone's own rule was written on.
+   */
+  test('the job indicator still announces its state without its label', async ({
+    app,
+    testctl,
+  }) => {
+    await testctl.emit('JobsChanged', [LONG_JOB]);
+    await app.setViewportSize({ width: 600, height: 600 });
+
+    await expect.poll(() => collapsed(app)).toMatchObject({ jobLabel: true });
+
+    const spoken = await app
+      .locator('job-indicator')
+      .evaluate(
+        (el) =>
+          el.shadowRoot?.querySelector('[aria-live]')?.textContent?.trim() ?? '',
+      );
+
+    expect(spoken).toContain('Scanning Music from the external drive');
+
+    // Leave the app as the next spec expects to find it.
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+});

e2e/specs/view-lifecycle.spec.ts

@@ -4,6 +4,7 @@ import {
   eventNames,
   resetEvents,
   waitForEvent,
+  navigateTo,
 } from '../support/fixtures.js';
 
 /**
@@ -39,7 +40,9 @@ test.describe('view lifecycle', () => {
   test('a keypress on Settings does not reach the Autotag queue', async ({
     app,
   }) => {
-    await app.getByTestId('nav-autotag').click();
+    // By event, not by nav item: Autotag is hidden by default (#25)
+    // and a hidden view is still reachable.
+    await navigateTo(app, 'autotag');
     await expect(app.getByTestId('main-content')).toHaveAttribute(
       'data-active-view',
       'autotag',
@@ -83,7 +86,9 @@ test.describe('view lifecycle', () => {
     // The other half of the same bug (H-2): two document keydown handlers
     // with no arbitration meant `s` on this page skipped the album *and*
     // toggled shuffle.  As a panel binding it can only mean one thing.
-    await app.getByTestId('nav-autotag').click();
+    // By event, not by nav item: Autotag is hidden by default (#25)
+    // and a hidden view is still reachable.
+    await navigateTo(app, 'autotag');
     await expect
       .poll(() => pendingCount(app))
       .toMatch(/^Pending \(\d+\)$/);

e2e/specs/view-visibility.spec.ts

@@ -0,0 +1,116 @@
+import { test, expect, navigateTo } from '../support/fixtures.js';
+
+/**
+ * Which destinations the navigation offers (#25).
+ *
+ * Eleven sidebar entries is more than most libraries need, so they are
+ * individually toggleable from Settings, Autotag is off until asked for
+ * and Downloads is absent until there is a client to download with.
+ *
+ * **The assertions are about the navigation, not about the setting.**
+ * "The config was saved" is the plumbing, and the two most recent bugs
+ * in this area — #69 and #72 — both shipped green under specs that
+ * measured exactly that. What a person sees is whether the item is in
+ * the accessibility tree, and whether the view is still reachable when
+ * it is not.
+ *
+ * This runs against the seeded app, whose config is defaults and whose
+ * download client list is empty, so the initial state below is what a
+ * fresh install looks like.
+ */
+type Page = import('@playwright/test').Page;
+
+const navItem = (page: Page, label: string) =>
+  page.getByRole('button', { name: label, exact: true });
+
+/** The Navigation section's checkbox for a destination. */
+const viewToggle = (page: Page, label: string) =>
+  page.getByRole('checkbox', { name: `Show ${label} in the navigation` });
+
+async function openNavigationSettings(page: Page): Promise<void> {
+  await page.getByTestId('nav-settings').click();
+
+  const section = page.locator(
+    'config-page config-section[heading="Navigation"] .header',
+  );
+
+  await expect(section).toBeVisible();
+
+  if ((await section.getAttribute('aria-expanded')) === 'false') {
+    await section.click();
+  }
+
+  await expect(section).toHaveAttribute('aria-expanded', 'true');
+}
+
+test.describe('configurable destinations', () => {
+  test('Autotag is off by default and Downloads needs a client', async ({
+    app,
+  }) => {
+    await expect(app.getByTestId('nav-home')).toBeVisible();
+
+    await expect(app.getByTestId('nav-autotag')).toHaveCount(0);
+    await expect(app.getByTestId('nav-downloads')).toHaveCount(0);
+  });
+
+  /**
+   * Hiding takes the item away and nothing else. Detail views navigate
+   * into these and the launch page is one of them, so a destination
+   * with no nav item still has to open.
+   */
+  test('a hidden destination is still reachable', async ({ app }) => {
+    await navigateTo(app, 'autotag');
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'autotag',
+    );
+
+    // And nothing is falsely lit while standing on it -- the same rule
+    // a detail view follows, with no special case for either.
+    await expect(navItem(app, 'Home')).toHaveAttribute('aria-current', 'false');
+  });
+
+  test('switching Autotag on adds it to the sidebar', async ({ app }) => {
+    await openNavigationSettings(app);
+
+    await viewToggle(app, 'Autotag').check();
+
+    await expect(app.getByTestId('nav-autotag')).toBeVisible();
+
+    // Clicking it is the point of having it.
+    await app.getByTestId('nav-autotag').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'autotag',
+    );
+
+    // Put it back, or the next spec against this app sees a library
+    // this one changed.
+    await openNavigationSettings(app);
+    await viewToggle(app, 'Autotag').uncheck();
+    await expect(app.getByTestId('nav-autotag')).toHaveCount(0);
+  });
+
+  /**
+   * Settings has no toggle at all, rather than a toggle that refuses:
+   * a user who hides it cannot get back to unhide it. The backend
+   * refuses it too, because `config.toml` is hand-editable.
+   */
+  test('Settings cannot be switched off', async ({ app }) => {
+    await openNavigationSettings(app);
+
+    await expect(viewToggle(app, 'Settings')).toBeDisabled();
+    await expect(app.getByTestId('nav-settings')).toBeVisible();
+  });
+
+  /**
+   * The launch page is refused while it is the launch page, which is a
+   * state the user can leave by changing the launch page above it.
+   */
+  test('the launch page cannot be switched off', async ({ app }) => {
+    await openNavigationSettings(app);
+
+    await expect(viewToggle(app, 'Home')).toBeDisabled();
+  });
+});

e2e/support/fixtures.ts

@@ -111,6 +111,35 @@ export async function bindingCalls(page: Page): Promise<string[]> {
   return calls.map(nameOf);
 }
 
+/**
+ * Go to a view without going through the navigation.
+ *
+ * `navigate` is the event the shell listens for and every nav item, card
+ * and detail view dispatches, so this is the app's own mechanism rather
+ * than a test-only door. It exists because a destination is not
+ * guaranteed to have a nav item any more (#25): Autotag is hidden until
+ * the user asks for it and Downloads until a client exists, and a spec
+ * about what a *view* does should not also be asserting that the
+ * sidebar offers it.
+ */
+export async function navigateTo(page: Page, view: string): Promise<void> {
+  await page.evaluate(
+    (v) =>
+      void document.dispatchEvent(
+        new CustomEvent('navigate', {
+          detail: { view: v },
+          bubbles: true,
+          composed: true,
+        }),
+      ),
+    view,
+  );
+
+  await page
+    .getByTestId('main-content')
+    .waitFor({ state: 'attached' });
+}
+
 /** Thin client for the dev-only /__test/ surface (backend/testctl). */
 export class TestCtl {
   constructor(private readonly baseURL: string) {}

frontend/bindings/yellowjacket/backend/autotagservice/index.ts

@@ -7,6 +7,7 @@ export {
 };
 
 export type {
+    AlbumMatchView,
     AlignmentView,
     ApplyResultView,
     CandidateView,

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

@@ -1,6 +1,61 @@
 // Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
 // This file is automatically generated. DO NOT EDIT
 
+/**
+ * AlbumMatchView is "the autotagger already has a confident match for
+ * the album you are looking at".
+ * 
+ * It is deliberately not a score. The album page renders a suggestion,
+ * and a suggestion has to be actionable: which release, what it is
+ * called, and whether acting on it here would do the whole album or
+ * only part of it.
+ */
+export interface AlbumMatchView {
+    /**
+     * GroupKey is the tagging group the actions operate on.
+     */
+    "groupKey": string;
+
+    /**
+     * Recommendation is the tier, as a string, for a caller that
+     * wants to render the strength rather than trust the filter.
+     */
+    "recommendation": string;
+
+    /**
+     * Score is the top candidate's raw score, 0..1.
+     */
+    "score": number;
+
+    /**
+     * ReleaseMBID is the release Apply would write.
+     */
+    "releaseMbid": string;
+
+    /**
+     * Title and ArtistCredit name that release, so the banner can say
+     * what it is offering rather than "a match".
+     */
+    "title": string;
+    "artistCredit": string;
+
+    /**
+     * TrackCount is the group's local track count.
+     */
+    "trackCount": number;
+
+    /**
+     * GroupCount is how many tagging groups this album spans.
+     * 
+     * More than one means a multi-disc album (one group per disc), and
+     * it is the reason this is a field rather than an implementation
+     * detail: applying "the album" from a single button would retag
+     * one disc of three and leave the folder holding a mix of old and
+     * new tags. The caller offers review instead.
+     */
+    "groupCount": number;
+}
+
 /**
  * AlignmentView mirrors autotag.TrackAlignment.  LocalIndex of -1
  * means "candidate has this track, folder doesn't" (status=missing).

frontend/bindings/yellowjacket/backend/autotagservice/service.ts

@@ -160,6 +160,39 @@ export function ListPendingFolders(libraryID: number): $CancellablePromise<$mode
     return $Call.ByID(617511590, libraryID);
 }
 
+/**
+ * MatchForAlbum answers "does the autotagger have something confident
+ * to say about this album", for the album detail page.
+ * 
+ * Three things about it are load-bearing.
+ * 
+ * **It costs no MusicBrainz request.** Everything it needs is already
+ * on disk: `tagging_items` carries the top score and release from the
+ * background prefetch, and `tagging_candidates` durably holds the
+ * scored list. The rate limiters here are shared with every page the
+ * user can open, so a lookup that fires on page load must not join
+ * that queue — which also means this returns nothing for a folder
+ * nobody has scored yet, rather than scoring it now. That is the
+ * right trade: the prefetch will get to it, and a page that silently
+ * spends a minute of somebody's MusicBrainz budget to draw a banner
+ * is worse than a page that says nothing.
+ * 
+ * **The tier is computed, not read.** `tagging_items.score` is the raw
+ * number and `Recommend` is what turns it into a claim — capping it
+ * for an ambiguous runner-up, an incomplete alignment or a folder too
+ * small to corroborate itself. Filtering on the raw score would
+ * promise confidence the scorer had explicitly withheld.
+ * 
+ * **Nothing is said about an album the user has already answered
+ * for.** Only a `pending` group qualifies: `confirmed` covers both a
+ * finished apply and an explicit "leave as is", and `skipped` is the
+ * user saying not now. Re-offering either is nagging, and "leave as
+ * is" would be actively wrong to argue with.
+ */
+export function MatchForAlbum(albumID: number): $CancellablePromise<$models.AlbumMatchView | null> {
+    return $Call.ByID(514173221, albumID);
+}
+
 /**
  * RetagGroup flips a group back to 'pending' so the user can
  * re-review after an apply or skip.  Drops the durably-cached

frontend/bindings/yellowjacket/backend/config/config.ts

@@ -69,6 +69,14 @@ export function GetPinDefaultPlaylist(): $CancellablePromise<boolean> {
     return $Call.ByID(3818283301);
 }
 
+/**
+ * GetPopupVolume reports whether the bottom bar's volume control is a
+ * click-to-open popup rather than an inline slider (#42).
+ */
+export function GetPopupVolume(): $CancellablePromise<boolean> {
+    return $Call.ByID(2885777);
+}
+
 /**
  * GetQueueFallback returns what plays, if anything, once the queue
  * runs out.
@@ -112,6 +120,16 @@ export function GetTrackListColumns(): $CancellablePromise<tracklist$0.Column[]
     return $Call.ByID(3426289065);
 }
 
+/**
+ * GetViewVisibility reports which primary views the sidebar should
+ * show, answered for every known view rather than only the ones the
+ * config mentions -- so the frontend filters on a value and never has
+ * to hold a second copy of the defaults.
+ */
+export function GetViewVisibility(): $CancellablePromise<{ [_ in string]?: boolean } | null> {
+    return $Call.ByID(2798108026);
+}
+
 /**
  * Load reads and parses the config file from disk.
  */
@@ -197,6 +215,18 @@ export function SetPinDefaultPlaylist(pin: boolean): $CancellablePromise<void> {
     return $Call.ByID(372446849, pin);
 }
 
+/**
+ * SetPopupVolume saves the volume control's presentation.
+ * 
+ * Nothing to validate: both values are legal at every width, and the
+ * frontend additionally stands the inline slider down below the phone
+ * breakpoint whatever this says, because that is about room rather than
+ * about preference.
+ */
+export function SetPopupVolume(popup: boolean): $CancellablePromise<void> {
+    return $Call.ByID(1430308453, popup);
+}
+
 /**
  * SetQueueFallback validates and saves a new queue-fallback mode.
  */
@@ -247,6 +277,20 @@ export function SetTrackListColumns(columns: tracklist$0.Column[] | null): $Canc
     return $Call.ByID(4226159685, columns);
 }
 
+/**
+ * SetViewVisible shows or hides one primary view.
+ * 
+ * Two refusals, both about a state the user cannot get out of from the
+ * UI they would be left with: Settings is never hideable, and the
+ * launch page is never hideable while it is the launch page (change it
+ * first). Hiding a view does not make it unreachable -- `navigate`
+ * still resolves it, which detail views depend on -- it only takes the
+ * nav item away.
+ */
+export function SetViewVisible(view: string, visible: boolean): $CancellablePromise<void> {
+    return $Call.ByID(1751982648, view, visible);
+}
+
 /**
  * Validate returns errors if there is a breaking issue with the config.
  */

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/bindings/yellowjacket/backend/queue/queue.ts

@@ -113,14 +113,6 @@ export function Next(): $CancellablePromise<void> {
     return $Call.ByID(1968784044);
 }
 
-/**
- * OnPlaybackFinished is called when a track finishes playing naturally.
- * This drives the auto-advance behavior and records the play.
- */
-export function OnPlaybackFinished(): $CancellablePromise<void> {
-    return $Call.ByID(2184869763);
-}
-
 /**
  * Play handles a play request by either resuming the current track or
  * starting playback from the beginning of the queue. When a track is

frontend/index.css

@@ -104,6 +104,51 @@ p {
     flex: 0 1 320px;
 }
 
+/* What the bar gives up when it does not fit is decided by measuring
+   it (`services/top-bar-fit.ts`, #143). Two rules here are what make
+   that measurement mean anything.
+
+   **Nothing but the search box may shrink.** `scrollWidth` reports a
+   perfect fit while a child quietly truncates -- #69's trap, one
+   component over -- and the indicator's label is `text-overflow:
+   ellipsis`, so it would have absorbed the deficit and hidden it. The
+   search box is exempt because it shrinks between its 320px basis and
+   the 200px floor its own stylesheet sets, and a narrower input hides
+   nothing it was showing. */
+.top-bar hgroup,
+.top-bar library-filter,
+.top-bar job-indicator {
+    flex-shrink: 0;
+}
+
+/* **The wordmark yields its width, not its existence.** It is the
+   app's top-level heading as well as its brand, and `display: none`
+   would take a document from one `h1` to none at exactly the widths
+   where the view's own header is the only thing left saying where you
+   are. This is `styles/sr-only.css.ts`'s recipe, written out because
+   that one is a `CSSResult` for shadow roots and this is the light
+   DOM. */
+.top-bar hgroup.yj-collapsed {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+}
+
+/* The bar is `justify-content: space-between`, which with four children
+   spreads them evenly and left back/forward floating in the middle of
+   nothing. Collecting the free space *after* this one puts the pair
+   beside the brand, where a browser keeps them, and leaves the
+   right-hand group exactly as it was. */
+.top-bar nav-history {
+    margin-right: auto;
+}
+
 ul {
     list-style-type: none;
 }
@@ -133,6 +178,23 @@ ul {
     .subtitle {
         display: none;
     }
+
+    /* Back/forward is Desktop-band chrome (#6), and 900 is the same
+       line the sidebar's labels and the subtitle are already given up
+       at -- below it the shell is narrow enough that the header is
+       what runs out of room first. Measured at 600, the bottom of the
+       Compact band: the bar is 611px inside a 600px viewport *before*
+       this component exists (filed separately), and 695px with it, so
+       keeping it here would be widening a violation of the promise
+       that nothing scrolls sideways at a supported size.
+
+       Nothing is unreachable as a result, which is the rule that
+       decides it: Alt+Left / Alt+Right are global and every width has
+       them, the detail views keep their own back buttons, and the
+       phone additionally has the platform's gesture. */
+    .top-bar nav-history {
+        display: none;
+    }
 }
 
 body div.sidebar {
@@ -149,7 +211,39 @@ body div.sidebar {
     padding: 0.25em;
     background-color: var(--yj-bg-elevated, #343a40);
     display: grid;
-    grid-template-columns: var(--now-playing-width, 320px) 1fr auto;
+    /* Three columns whose outer two are the *same* width, which is what
+       centres the middle one (#23). It was `var(--now-playing-width) 1fr
+       auto`, so the transport's centre sat at `W/2 + 140px` — in the
+       middle of the space left over, which is not the same thing and
+       reads as an alignment mistake at every window size.
+
+       The outer width is still `--now-playing-width`, so **the metadata
+       panel's drag handle keeps meaning something**: widening it takes
+       room from the transport on both sides at once, symmetrically. An
+       `1fr … 1fr` pair would have centred the transport just as well and
+       silently made that handle a no-op.
+
+       **The cap is what stops that being a regression**, and it was
+       measured as one first. Reserving the full metadata width on both
+       sides costs the transport twice: at 800px the outer pair wanted
+       640 of 800, and the seek bar's track went from 257px to 61px
+       (and to 0 at 200% text) — the control you drag, squeezed out to
+       centre the buttons above it. So the side tracks are the metadata
+       width *or a quarter of the bar*, whichever is smaller, which
+       leaves the drag handle meaningful everywhere it has room to be
+       and hands the difference to the transport where it does not.
+
+       `minmax(0, …)` on the outer tracks and `min-content` on the middle
+       decide who yields when even that is not enough: the metadata and
+       the end group shrink (both truncate; neither loses an action), and
+       the transport keeps at least its buttons. Without the `min-content`
+       floor the middle collapses first, because a `1fr` track's minimum
+       is `auto` only until something else insists. */
+    --bar-side: min(var(--now-playing-width, 320px), 25%);
+    grid-template-columns:
+        minmax(0, var(--bar-side))
+        minmax(min-content, 1fr)
+        minmax(0, var(--bar-side));
     align-items: center;
     contain: layout style;
 
@@ -177,23 +271,44 @@ body div.sidebar {
             text-wrap-mode: nowrap;
             overflow: hidden;
 
-            p {
+            /* `& p`, not `p`. **A nested rule that begins with a bare
+               element selector is silently dropped before Chrome 120**
+               (relaxed nesting), and the phone this app runs on renders
+               in Chrome 113 -- so this ellipsis, and the two rules
+               below, have never applied on the device. Nothing fails;
+               the text simply overflows there. The `&` form is valid in
+               both, which is why it is used for every element selector
+               in this file's nested blocks. */
+            & p {
                 overflow: hidden;
                 text-overflow: ellipsis;
             }
         }
     }
 
-    now-playing {
+    & now-playing {
         overflow: hidden;
     }
 
-    audio-player {
+    & audio-player {
         margin: 0.5em 1em;
+        min-width: 0;
+    }
+
+    /* The right-hand group, and the thing the left column is matched
+       against. It is one grid cell rather than two columns because the
+       centring rule above compares *columns*: volume and the queue
+       button in separate tracks would make the outer pair unequal by
+       whatever the volume happens to measure. */
+    .bar-end {
+        justify-self: end;
+        display: flex;
+        align-items: center;
+        gap: 0.25em;
+        min-width: 0;
     }
 
     #queue-button {
-        justify-self: end;
         background: none;
         border: none;
         color: inherit;
@@ -231,6 +346,14 @@ body div.sidebar {
     display: flex;
     overflow: hidden;
     contain: layout style;
+
+    /* The containing block for the queue panel's overlay mode (plan
+       018, #24), which spans this box rather than taking width from
+       the main panel beside it. `contain: layout` already establishes
+       one; this says so on purpose, so that removing the containment
+       for a paint reason does not silently reparent the overlay to the
+       viewport. */
+    position: relative;
 }
 
 .main-panel {
@@ -291,6 +414,7 @@ body div.sidebar {
     body {
         grid-template:
             "top-bar" 3.25em
+            "jobs-band" auto
             "main-panel" 1fr
             "bottom-bar" auto
             "bottom-nav" auto
@@ -338,7 +462,13 @@ body div.sidebar {
 
     /* The search box is the one header control worth its width; the
        library filter is a rarely-changed setting and reachable from
-       the drawer's Settings. */
+       the drawer's Settings.
+
+       `nav-history` is already gone from 899 down. It would belong
+       here anyway and for a stronger reason than width: the phone has
+       Back as a gesture or a button the OS owns, and this app hooks it
+       (`popstate`), so a second Back in the chrome duplicates a
+       control the platform provides. */
     .top-bar library-filter {
         display: none;
     }
@@ -364,6 +494,11 @@ body div.sidebar {
 }
 
 @media (max-width: 599px) {
+    /* The phone keeps the two-part bar it had: metadata, then the
+       transport and the queue button. There is no third column to
+       balance because the centring the desktop does is a luxury of
+       having room — at 360px the metadata needs all of the space the
+       controls do not. */
     .bottom-bar {
         grid-template-columns: minmax(0, 1fr) auto auto;
         gap: 0.25em;
@@ -372,4 +507,61 @@ body div.sidebar {
     .bottom-bar audio-player {
         margin: 0.25em;
     }
+
+    /* Volume stands down here whatever the setting says, because this
+       is about room and about the platform rather than about
+       preference: the hardware keys own volume on a phone, which is
+       also why mediacontrols' Android handler implements no volume
+       callback. It moved from `audio-player`'s own media query when
+       #42 moved the control into the bar — same rule, and now stated
+       where the element actually is.
+
+       `.bottom-bar volume-control`, not the one in
+       `now-playing-view`: that view is the phone's transport and is
+       where a slider does belong. */
+    .bottom-bar volume-control {
+        display: none;
+    }
+}
+
+/* Out of the desktop grid entirely.  `job-band` renders nothing above
+   600px anyway, but an in-flow grid child with no named area is
+   auto-placed into a row of the shell -- the same trap the skip link is
+   absolutely positioned to avoid. */
+body job-band {
+    display: none;
+}
+
+/* #62.  The job indicator stands down on the phone, and its work is
+   shown in the notification band instead (notification-host).
+
+   Three reasons, and the first is the report: its popover is anchored
+   to the top bar, which is 3.25em here on a viewport 439 CSS px tall,
+   and it was reported as unreadable behind other UI.  The second is
+   that a popover is a disclosure, and background work is the one thing
+   a phone should not make you disclose.  The third is #57, which
+   deletes this bar entirely and is blocked on the indicator having
+   somewhere else to live -- this is that somewhere.
+
+   `display: none` rather than a fit step: `services/top-bar-fit.ts`
+   already skips children whose computed display is none, so the bar's
+   measurement simply sees one fewer child, and `[compact]` toggling on
+   a hidden element costs nothing. */
+@media (max-width: 599px) {
+    .top-bar job-indicator {
+        display: none;
+    }
+
+    /* ...and its rows appear here, in the grid row above the content.
+       In flow rather than over it: a fixed band reads fine in a
+       screenshot and is unusable, because at 424x439 a compact panel
+       is ~200px of a 439px screen and it *covers* what is under it.
+       Measured, not assumed -- four e2e specs failed on that version,
+       two phone-shell journeys and the header's action menu, because
+       the panel was intercepting the taps. */
+    body job-band {
+        display: block;
+        grid-area: jobs-band;
+        background-color: var(--yj-bg-elevated, #343a40);
+    }
 }

frontend/index.html

@@ -20,10 +20,24 @@
             <!-- a11y.29: a heading level was being used for type size. -->
             <p class="subtitle">Music how it was meant to bee.</p>
         </hgroup>
+        <!-- Global back/forward (#6). Before the library filter so the
+             two navigation controls in this bar are adjacent, and after
+             the brand because that is where a window's chrome ends and
+             the app's begins. Hidden below 600px by index.css: the
+             phone has a system back, and this bar has no room. -->
+        <nav-history></nav-history>
         <library-filter></library-filter>
         <search-bar></search-bar>
         <job-indicator></job-indicator>
     </header>
+    <!-- The phone's view of background work (#62): below 600px the
+         indicator above stands down and its rows appear here instead,
+         in the layout rather than over it.  `display: none` above that
+         width in index.css, which is also what keeps it out of the
+         desktop grid -- an in-flow child with no named area is
+         auto-placed into one of the shell's rows, which is the trap the
+         skip link is absolutely positioned to avoid. -->
+    <job-band></job-band>
     <div class="sidebar">
         <app-sidebar></app-sidebar>
     </div>
@@ -34,13 +48,31 @@
         </main>
         <queue-panel id="queue-panel"></queue-panel>
     </div>
+    <!-- Three columns, and the outer two are the same width, which is
+         what makes the middle one *centred* rather than merely in the
+         middle of what is left (#23). The transport used to sit in a
+         `320px 1fr auto` grid, so its centre was ~140px right of the
+         window's.
+
+         That is also why the volume moved out of `audio-player` and
+         into the bar (#42): the transport column has to contain the
+         transport and nothing else, or "centred" means centred with a
+         slider bolted to one side. It joins the queue button in
+         `.bar-end`, whose width is what the left column is matched
+         against. -->
     <footer class="bottom-bar">
         <now-playing></now-playing>
         <audio-player></audio-player>
-        <button aria-label="Toggle queue" aria-controls="queue-panel" aria-expanded="false"
-            id="queue-button">
-            <wa-icon name="list"></wa-icon>
-        </button>
+        <div class="bar-end">
+            <volume-control></volume-control>
+            <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>
+        </div>
     </footer>
     <!-- The phone's primary navigation, hidden above 600px by
          index.css.  Eager rather than a chunk, for the reason

frontend/index.ts

@@ -18,11 +18,15 @@
 //   track-list — index.html renders one, so it is the first paint.
 // ---------------------------------------------------------------------------
 import '@components/audio-player/audio-player.ts';
+// In the bar rather than inside `audio-player` since #42, so the shell
+// is what has to register it.
+import '@components/audio-player/volume-control/volume-control.ts';
 import '@components/track-list/track-list.ts';
 import '@components/now-playing/now-playing.ts';
 import '@components/sidebar/app-sidebar.ts';
 import '@components/bottom-nav/bottom-nav.ts';
 import '@components/queue-panel/queue-panel.ts';
+import '@components/nav-history/nav-history.ts';
 import '@components/search-bar/search-bar.ts';
 import '@components/library-filter/library-filter.ts';
 import '@components/first-run-wizard/first-run-wizard.ts';
@@ -34,12 +38,19 @@ import '@components/confirm-dialog/confirm-dialog.ts';
 // not know what is going on. It costs a dialog and a table.
 import '@components/shortcuts-overlay/shortcuts-overlay.ts';
 import '@components/jobs/job-indicator.ts';
+// The phone's half of the same thing (#62). Eager because it is part
+// of the shell's first paint below 600px, and because a band that has
+// to fetch a chunk before it can say the app is busy is late by
+// exactly the interval it exists to explain.
+import '@components/jobs/job-band.ts';
 import '@awesome.me/webawesome/dist/styles/themes/default.css';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { setBasePath } from '@awesome.me/webawesome/dist/webawesome.js';
 import { registerBundledIcons } from './src/icons';
 import { queueStore } from '@store/queue-store';
 import { searchStore } from '@store/search-store';
+import { activeViewStore } from '@store/active-view-store';
+import { historyStore } from '@store/history-store';
 import * as Player from '@go/player/player.js';
 import * as Queue from '@go/queue/queue.js';
 import { GetDefaultPage } from '@go/config/config.js';
@@ -51,6 +62,7 @@ import '@store/theme-store';
 import './src/services/keyboard-shortcut-service';
 import { activateView, deactivateView } from '@utils/view-lifecycle';
 import { installLongPressContextMenu } from '@utils/long-press';
+import { installTopBarFit } from './src/services/top-bar-fit';
 import {
     hasTrackPayload,
     getDragPayload,
@@ -70,6 +82,14 @@ registerBundledIcons();
 // on `pointerType === 'touch'` only.
 installLongPressContextMenu();
 
+// The top bar decides what it can afford to show (#143). Here rather
+// than in a component because the bar is light DOM in index.html and
+// its children are five separate elements; the shell is the only thing
+// that can see all five at once.
+const topBar = document.querySelector<HTMLElement>('header.top-bar');
+
+if (topBar) installTopBarFit(topBar);
+
 // ---------------------------------------------------------------------------
 // View caching navigation system
 // ---------------------------------------------------------------------------
@@ -98,7 +118,6 @@ const VIEW_TAGS: Record<string, string> = {
     explore: 'explore-view',
     autotag: 'autotag-view',
     downloads: 'downloads-view',
-    jobs: 'jobs-view',
     settings: 'config-page',
 };
 
@@ -116,7 +135,6 @@ const VIEW_LOADERS: Record<string, () => Promise<unknown>> = {
     explore: () => import('@components/explore-view/explore-view.ts'),
     autotag: () => import('@components/autotag-view/autotag-view.ts'),
     downloads: () => import('@components/downloads-view/downloads-view.ts'),
-    jobs: () => import('@components/jobs/jobs-view.ts'),
     settings: () => import('@components/config-page/config-page.ts'),
 };
 
@@ -214,45 +232,101 @@ document.addEventListener('navigate', (e: Event) => {
 // go through `history.back()` rather than popping `navStack`
 // themselves, so one press cannot consume two entries.
 
-/** The navigation an entry stands for. `undefined` on the entry that
- *  predates the app's own routing, which is the one back exits from. */
-type NavState = { yjNav?: { view: string; [key: string]: any } };
+/** The navigation an entry stands for, and where it sits in this
+ *  session's list. `undefined` on the entry that predates the app's own
+ *  routing, which is the one back exits from. */
+type NavState = { yjNav?: { view: string; [key: string]: any }; yjIdx?: number };
 
 /** Whether the app's first navigation has been recorded. It *replaces*
  *  the launch entry rather than pushing, or every launch would cost one
  *  back press before the app would exit. */
 let historyStarted = false;
 
-/** How many entries this session has pushed beyond that first one --
- *  i.e. how deep back can go while staying inside the app. */
-let pushedEntries = 0;
+// Back and forward are the *same* `popstate` event -- it carries no
+// direction, and the History API exposes neither the current position
+// nor a reachable depth. So the shell numbers its own entries: the
+// index of the one showing, and the highest index reachable from here.
+//
+// The counter this replaced (`pushedEntries`, one number decremented on
+// every pop) could not express forward at all: going forward looked
+// exactly like going back again, so two presses of a Forward button
+// would have claimed the app was at its root.
+
+/** Index of the entry now showing. 0 is the launch entry, which is
+ *  replaced rather than pushed -- so this is also how deep back can go
+ *  while staying inside the app. */
+let currentIndex = 0;
+
+/** The highest index reachable from here: how far forward is left.
+ *  A new navigation truncates the forward list, exactly as a browser
+ *  does, so this is reset to the entry being pushed. */
+let maxIndex = 0;
+
+function publishDepth(): void {
+    historyStore.setDepth(currentIndex > 0, currentIndex < maxIndex);
+}
 
 function recordNavigation(detail: { view: string; [key: string]: any }): void {
-    // `_isBack` is bookkeeping, not destination: keeping it in the entry
-    // would make a replayed navigation claim to be a back-navigation.
-    const { _isBack: _ignored, ...nav } = detail;
-    const state: NavState = { yjNav: nav };
+    // `_isBack` and `_replace` are bookkeeping, not destination: keeping
+    // either in the entry would make a replayed navigation claim to be
+    // one.
+    const { _isBack: _ignored, _replace: replace, ...nav } = detail;
+
+    // Still launching: the configured landing page is not a navigation
+    // *away* from the eager one, it is the same arrival arriving late
+    // (#142). Pushing it left the app one entry deep before the user
+    // had touched anything, so the first back press replayed home over
+    // home -- invisible on desktop until #6 drew a Back button, and on
+    // Android the press that should have exited the app instead did
+    // nothing, because `canGoBack()` was true.
+    //
+    // Guarded on being at the root rather than on a flag, because
+    // `GetDefaultPage()` is a backend call and the user can navigate
+    // while it is in flight: past index 0 this is an ordinary
+    // navigation, or a slow answer would overwrite an entry they made.
+    if (historyStarted && replace && currentIndex === 0) {
+        history.replaceState({ yjNav: nav, yjIdx: 0 }, '');
+        maxIndex = 0;
+        publishDepth();
+
+        return;
+    }
 
     // Same URL, deliberately: the app has no routes, and a path a
     // reload cannot resolve is worse than no path at all.
     if (historyStarted) {
-        history.pushState(state, '');
-        pushedEntries += 1;
+        currentIndex += 1;
+        // Navigating from the middle of the list drops what was ahead
+        // of it -- there is no longer a forward to go to.
+        maxIndex = currentIndex;
+        history.pushState({ yjNav: nav, yjIdx: currentIndex }, '');
     } else {
-        history.replaceState(state, '');
+        currentIndex = 0;
+        maxIndex = 0;
+        history.replaceState({ yjNav: nav, yjIdx: 0 }, '');
         historyStarted = true;
     }
+
+    publishDepth();
 }
 
 window.addEventListener('popstate', (e: PopStateEvent) => {
-    const nav = (e.state as NavState | null)?.yjNav;
+    const state = e.state as NavState | null;
+    const nav = state?.yjNav;
 
     // Before the app's first navigation, or an entry somebody else
     // pushed: nothing to restore, and the activity should be free to
     // finish.
     if (!nav) return;
 
-    pushedEntries = Math.max(0, pushedEntries - 1);
+    // The entry says where it is, so this works in both directions and
+    // across a jump of more than one -- which a long-press on a
+    // browser's back button, and `history.go(-n)`, both produce.
+    // The fallback is for an entry pushed before this numbering
+    // existed; it can only be wrong about a control's disabled state,
+    // never about which view is restored.
+    currentIndex = state?.yjIdx ?? Math.max(0, currentIndex - 1);
+    publishDepth();
 
     void handleNavigate({ ...nav, _isBack: true });
 });
@@ -279,6 +353,20 @@ async function handleNavigate(
     // attribute keeps e2e selectors semantic instead of structural.
     mainContent.dataset.activeView = view;
 
+    // And publishing it as a *value* is what the nav components read.
+    // They used to learn the active view from the `navigate` event,
+    // which only the outbound path dispatches -- so a back-navigation
+    // left both of them highlighting the view it had just left (#72).
+    // Re-dispatching `navigate` here is not the fix: this file is a
+    // document listener for it, so that is an infinite loop, and
+    // "please go to X" is not the statement being made.
+    //
+    // `view in VIEW_TAGS` is the primary/detail split, and it is passed
+    // rather than re-derived because this table is where it is written
+    // down.  A detail view therefore leaves the tab it was opened from
+    // lit, which is what the report asks for.
+    activeViewStore.setView(view, view in VIEW_TAGS);
+
     // --- Primary (cacheable) views ----------------------------------------
     if (view in VIEW_TAGS) {
         // Remove any active detail view first
@@ -308,6 +396,18 @@ async function handleNavigate(
             deactivateView(currentViewEl);
         }
         target.classList.remove('view-hidden');
+
+        // A primary view is cached, so there is no construction to
+        // hand a payload to the way a detail view gets one below.  The
+        // one navigation that carries something is the album page's
+        // "Review in Autotag", which has to land on *that* album: the
+        // request goes on as an attribute and `autotag-view` consumes
+        // it (removes it) once acted on, or every later visit would
+        // reopen a folder the user finished with long ago.
+        if (view === 'autotag' && typeof detail.groupKey === 'string') {
+            target.setAttribute('group-key', detail.groupKey);
+        }
+
         // A freshly created view was appended hidden, so it did not
         // self-activate on connection; a cached one was deactivated on
         // the way out.  Either way this is the call that starts it.
@@ -485,7 +585,18 @@ function schedule(fn: () => void): void {
 // anyway would leave the app: the depth check is what stops a stray
 // `navigate-back` closing it.
 document.addEventListener('navigate-back', () => {
-    if (pushedEntries > 0) history.back();
+    if (currentIndex > 0) history.back();
+});
+
+// Forward: the other half of #6. The stack was always global -- every
+// navigation is an entry and `popstate` restores any of them -- so what
+// was missing is a way to ask for one, and a truthful answer to whether
+// there is one to ask for. It is guarded for the same reason back is:
+// `history.forward()` at the end of the list is silent, so a button
+// that offers it when there is nothing there is a button that does
+// nothing.
+document.addEventListener('navigate-forward', () => {
+    if (currentIndex < maxIndex) history.forward();
 });
 
 // Navigate to the user's configured launch page.  Falls back to 'home'
@@ -495,14 +606,17 @@ GetDefaultPage()
         document.dispatchEvent(new CustomEvent('navigate', {
             bubbles: true,
             composed: true,
-            detail: { view: view || 'home' },
+            // Part of launching, not a navigation away from the eager
+            // 'home' above: it replaces that entry rather than
+            // stacking on it (#142).
+            detail: { view: view || 'home', _replace: true },
         }));
     })
     .catch(() => {
         document.dispatchEvent(new CustomEvent('navigate', {
             bubbles: true,
             composed: true,
-            detail: { view: 'home' },
+            detail: { view: 'home', _replace: true },
         }));
     });
 

frontend/src/assets/icons/fa/solid/arrow-right.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="M502.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-160-160c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L402.7 224 32 224c-17.7 0-32 14.3-32 32s14.3 32 32 32l370.7 0-105.4 105.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0l160-160z"/></svg>

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/assets/icons/fa/solid/ellipsis.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 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 256a56 56 0 1 1 112 0 56 56 0 1 1 -112 0zm168 0a56 56 0 1 1 112 0 56 56 0 1 1 -112 0zm224-56a56 56 0 1 1 0 112 56 56 0 1 1 0-112z"/></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/audio-player.ts

@@ -3,7 +3,6 @@ import { customElement } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import './controls/player-controls';
 import './seekbar/seek-bar';
-import './volume-control/volume-control';
 import '../notifications/inline-notice';
 import { PlayerRegion } from '@store/player-store';
 import { designTokens } from '../../styles/tokens.css';
@@ -30,6 +29,7 @@ export class AudioPlayer extends LitElement {
 
     .player-main {
       flex: 1;
+      min-width: 0;
     }
 
     /* The phone transport (plan 016 B2): the buttons, and nothing
@@ -37,14 +37,17 @@ export class AudioPlayer extends LitElement {
        viewport, not by the host, so this is the component saying what
        it drops at phone width rather than the shell reaching in.
 
-       Volume goes because the hardware keys own it on a phone --
-       Android routes them to the media stream, which is also why
-       mediacontrols' Android handler implements no volume callback.
        The seek bar goes because a 4px-tall target dragged with a thumb
        is not a seek control; seeking belongs to the full-screen
-       now-playing view, which is the next phase. */
+       now-playing view.
+
+       Volume used to go from here too, and now goes from index.css
+       instead: #42 moved the control out of this component and into
+       the bar, so the shell is what can hide it. The reason is
+       unchanged -- the hardware keys own volume on a phone, which is
+       also why mediacontrols' Android handler implements no volume
+       callback. */
     @media (max-width: 599px) {
-      volume-control,
       seek-bar {
         display: none;
       }
@@ -65,7 +68,6 @@ export class AudioPlayer extends LitElement {
             <seek-bar></seek-bar>
           </div>
         </div>
-        <volume-control></volume-control>
       </div>
     `;
   }

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

@@ -22,6 +22,24 @@ export class SeekBar extends LitElement {
   @state()
   private seekValue: number = 0;
 
+  /**
+   * Whether the user is dragging the thumb right now.
+   *
+   * It is `@state` rather than a plain field because `updated()` owns
+   * the interval and only reactive state brings `updated()` round.  A
+   * bare `stopProgress()` in the input handler mutated nothing, so
+   * nothing re-rendered, so the tail of `updated()` that restarts the
+   * interval never ran — and the only things that could restart it
+   * were a `change` event or the next backend report.  Any `input`
+   * without a committed `change` therefore froze the interpolation:
+   * a drag cancelled outside the element, a pointer taken by a scroll,
+   * or a touch on the track treated as a scrub, which on a phone are
+   * ordinary gestures.  While playing, the 1 Hz report papered over it
+   * within a second; with reports not arriving it was permanent.
+   */
+  @state()
+  private dragging: boolean = false;
+
   /** Whether the right-hand clock shows time remaining or total. */
   @state()
   private showRemaining: boolean = true;
@@ -133,6 +151,7 @@ export class SeekBar extends LitElement {
   override disconnectedCallback() {
     super.disconnectedCallback();
     this.stopProgress();
+    this.endDrag();
   }
 
   override updated() {
@@ -154,18 +173,33 @@ export class SeekBar extends LitElement {
     // A report for a track that is no longer loaded is stale by
     // definition: the change id is the only thing that distinguishes
     // it, since the same file can play twice in a row.
+    //
+    // A report arriving mid-drag is deliberately *not* applied: the
+    // thumb belongs to the finger on it, and adopting a report once a
+    // second pulls it back out from under them.  The seq is left
+    // unrecorded too, so the first report after the drag still counts
+    // as fresh.
     const position = this.player.position;
     const forThisTrack =
       position !== null && position.trackChangeId === currentChangeId;
 
-    if (position && forThisTrack && position.seq !== this.previousPositionSeq) {
+    if (
+      position &&
+      forThisTrack &&
+      !this.dragging &&
+      position.seq !== this.previousPositionSeq
+    ) {
       this.previousPositionSeq = position.seq;
       this.seekValue = position.positionSeconds;
       this.stopProgress();
     }
 
-    // Start/stop progress interval based on playback state
-    if (this.isPlaying && this.hasTrack) {
+    // One owner for the interval, and this is it.  Every other place
+    // that wants it started or stopped says so by changing state that
+    // brings us back here, so the timer cannot be left running by a
+    // path that forgot to stop it or stopped by a path that forgot to
+    // start it again.
+    if (this.isPlaying && this.hasTrack && !this.dragging) {
       this.startProgress();
     } else {
       this.stopProgress();
@@ -210,18 +244,48 @@ export class SeekBar extends LitElement {
 
   private handleChange(e: Event) {
     const newSeekVal = (e.target as WaSlider).value;
+    this.endDrag();
     this.setSeekValue(newSeekVal);
     this.player.seek(newSeekVal);
+  }
 
-    if (this.isPlaying) {
-      this.startProgress();
+  /**
+   * The user is moving the thumb.
+   *
+   * This only records that fact; `updated()` decides what it means for
+   * the interval.  `seekValue` follows the slider so the clocks track
+   * the thumb during the drag rather than jumping when it is released.
+   */
+  private handleInput(e: Event) {
+    this.setSeekValue((e.target as WaSlider).value);
+
+    if (this.dragging) {
+      return;
     }
+
+    this.dragging = true;
+
+    // A drag that never commits must not strand the flag, or this fix
+    // turns a stall of up to one second into a permanent one -- which
+    // is the failure it exists to remove.  `change` is the ordinary
+    // end; these are the ones that are not, and they are on the
+    // document because the pointer is routinely released outside the
+    // element it started in.  A drag's listeners belong to the drag,
+    // so they go on with it and come off with it.
+    document.addEventListener('pointerup', this.endDrag);
+    document.addEventListener('pointercancel', this.endDrag);
+    document.addEventListener('touchend', this.endDrag);
+    document.addEventListener('touchcancel', this.endDrag);
   }
 
-  // Stops progress while user is dragging the thumb
-  private handleInput() {
-    this.stopProgress();
-  }
+  private endDrag = () => {
+    document.removeEventListener('pointerup', this.endDrag);
+    document.removeEventListener('pointercancel', this.endDrag);
+    document.removeEventListener('touchend', this.endDrag);
+    document.removeEventListener('touchcancel', this.endDrag);
+
+    this.dragging = false;
+  };
 
   private setSeekValue(val: number) {
     if (val < 0) val = 0;

frontend/src/components/audio-player/volume-control/volume-control.ts

@@ -4,6 +4,7 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/slider/slider.js';
 import type WaSlider from '@awesome.me/webawesome/dist/components/slider/slider.js';
 import { PlayerController } from '@store/controllers/player-controller';
+import { volumeStyleStore } from '@store/volume-style-store';
 import { designTokens } from '../../../styles/tokens.css';
 import { waSliderLabel } from '../../../styles/wa-slider-label.css';
 
@@ -22,6 +23,12 @@ export class VolumeControl extends LitElement {
   @state()
   private showSlider = false;
 
+  /** Whether this is the click-to-open popup rather than a slider. */
+  @state()
+  private popup = volumeStyleStore.popup;
+
+  private unsubscribeStyle?: () => void;
+
   // Locally-tracked volume while the user is actively dragging or scrolling.
   // The store's volume only updates once the backend echoes VolumeChanged
   // (which we debounce), so we track intent here for responsive UI and to let
@@ -86,11 +93,31 @@ export class VolumeControl extends LitElement {
       --thumb-height: 16px;
     }
 
-    wa-slider::part(track) {
+    .volume-popup wa-slider::part(track) {
       background: var(--yj-text-primary, white);
       height: 120px;
     }
 
+    /* The inline slider (#42). It is the default now, so the width is
+       a real layout decision rather than a detail: 5em is wide enough
+       to aim at and narrow enough that the bottom bar's *outer*
+       columns stay equal without squeezing the transport — which is
+       the arrangement #23 depends on.
+
+       flex-shrink: 0 for the reason the top bar's children have it
+       (#143): a control that quietly gets narrower under pressure
+       hides the fact that the bar has run out of room. This one stands
+       down at phone width instead, in index.css, where the shell can
+       see the viewport. */
+    .inline-slider {
+      width: 5em;
+      flex-shrink: 0;
+    }
+
+    .inline-slider::part(track) {
+      background: var(--yj-text-primary, white);
+    }
+
     wa-slider::part(indicator) {
       background: var(--yj-accent, yellow);
     }
@@ -122,8 +149,23 @@ export class VolumeControl extends LitElement {
   // LIFECYCLE
   // ===================================================================
 
+  override connectedCallback() {
+    super.connectedCallback();
+
+    this.unsubscribeStyle = volumeStyleStore.subscribe(() => {
+      this.popup = volumeStyleStore.popup;
+
+      // Switching to the slider while the popup is open would leave the
+      // document listener installed for a popup that no longer renders.
+      if (!this.popup) this.closeSlider();
+    });
+
+    void volumeStyleStore.init();
+  }
+
   override disconnectedCallback() {
     super.disconnectedCallback();
+    this.unsubscribeStyle?.();
     document.removeEventListener('click', this.boundHandleOutsideClick);
     clearTimeout(this.volumeDebounceTimer);
   }
@@ -154,10 +196,12 @@ export class VolumeControl extends LitElement {
   private handleOutsideClick(e: Event) {
     const path = e.composedPath();
 
-    if (!path.includes(this)) {
-      this.showSlider = false;
-      document.removeEventListener('click', this.boundHandleOutsideClick);
-    }
+    if (!path.includes(this)) this.closeSlider();
+  }
+
+  private closeSlider() {
+    this.showSlider = false;
+    document.removeEventListener('click', this.boundHandleOutsideClick);
   }
 
   private handleInput(e: Event) {
@@ -192,18 +236,46 @@ export class VolumeControl extends LitElement {
   override render() {
     const muted = this.player.muted;
 
+    // Inline, the icon is the mute toggle rather than a disclosure:
+    // there is nothing left to disclose, and a button that opens a
+    // popup containing the slider already beside it would be a control
+    // whose only effect is to duplicate its neighbour.
+    const iconAction = this.popup
+      ? this.toggleSlider
+      : () => this.player.toggleMute();
+    const iconLabel = this.popup
+      ? muted
+        ? 'Muted'
+        : `Volume ${this.currentVolume}%`
+      : muted
+        ? 'Unmute'
+        : 'Mute';
+
     return html`
       <button
         class=${muted ? 'muted' : ''}
         title=${muted ? 'Muted — click for volume' : 'Volume'}
-        aria-label=${muted ? 'Muted' : `Volume ${this.currentVolume}%`}
+        aria-label=${iconLabel}
         data-muted=${muted ? 'true' : 'false'}
-        @click="${this.toggleSlider}"
+        @click="${iconAction}"
         @wheel="${this.handleWheel}"
       >
         <wa-icon name=${this.volumeIcon}></wa-icon>
       </button>
-      ${this.showSlider
+      ${!this.popup
+        ? html`
+            <wa-slider
+              class="inline-slider ${muted ? 'muted' : ''}"
+              label="Volume"
+              min="0"
+              max="100"
+              .value="${this.currentVolume}"
+              @input="${this.handleInput}"
+              @wheel="${this.handleWheel}"
+            ></wa-slider>
+          `
+        : ''}
+      ${this.popup && this.showSlider
         ? html`
             <div
               class="volume-popup ${muted ? 'muted' : ''}"

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

@@ -29,6 +29,7 @@ import { nameDialogsIn } from '../../utils/name-dialog';
 import { ViewLifecycleMixin } from '../../utils/view-lifecycle';
 import { confirmAction } from '../confirm-dialog/confirm-dialog';
 import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
+import '@components/jobs/job-panel';
 import { list } from '@utils/binding';
 
 type PendingItem = autotagservice.PendingItem;
@@ -135,8 +136,20 @@ export class AutotagView extends ViewLifecycleMixin(LitElement) {
                 padding: 0.75rem 1rem;
             }
 
-            .header {
+            /* The header and the apply-job panel share the header row.
+               A wrapper rather than a third grid row, because the panel
+               is display:none while nothing is applying and a grid
+               row would still spend the container's gap on it -- the
+               idle case, which is nearly always. */
+            .header-area {
                 grid-area: header;
+                display: flex;
+                flex-direction: column;
+                gap: 0.5rem;
+                min-width: 0;
+            }
+
+            .header {
                 display: flex;
                 align-items: center;
                 gap: 0.75rem;
@@ -1315,13 +1328,40 @@ export class AutotagView extends ViewLifecycleMixin(LitElement) {
         // the page only needs the folder list, which is local and may
         // have moved while the page was away.
         if (this.queueStarted) {
-            void this.loadFolders();
+            void this.loadFolders().then(() => this.openRequestedFolder());
         } else {
             this.queueStarted = true;
-            void this.startQueue();
+            void this.startQueue().then(() => this.openRequestedFolder());
         }
     }
 
+    /**
+     * Open the folder somebody navigated here to look at.
+     *
+     * The album page's "Review in Autotag" has to land on *that*
+     * album. The queue is sorted by score so the intended folder is
+     * often near the top, but "often" is a link that sometimes opens
+     * the wrong album, which is worse than no link.
+     *
+     * It is an attribute rather than a property because this is a
+     * **cached primary view**: `index.ts` creates it once and reuses
+     * it, so there is no construction to pass a value to. Which is
+     * also why the request is *consumed* — the attribute is removed
+     * once acted on, or every later visit to Autotag would reopen an
+     * album the user finished with three navigations ago.
+     */
+    private openRequestedFolder(): void {
+        const requested = this.getAttribute('group-key');
+
+        if (!requested) return;
+
+        this.removeAttribute('group-key');
+
+        if (this.current?.groupKey === requested) return;
+
+        void this.selectFolder(requested);
+    }
+
     protected override onViewDeactivate(): void {
         this.unsubscribeLibraryStore?.();
         this.unsubscribeLibraryStore = undefined;
@@ -3180,7 +3220,20 @@ export class AutotagView extends ViewLifecycleMixin(LitElement) {
         // sees a blank full-screen "Loading\u2026".
         return html`
             <div class="root">
-                ${this.renderHeader()}
+                <div class="header-area">
+                    ${this.renderHeader()}
+                    <!--
+                      Applying rewrites tags on disk, and until #27 the
+                      only way to stop a run was the Jobs tab or the
+                      header popover. The per-album ring says work is
+                      happening; this is what can stop it, and what has
+                      the log when it goes wrong.
+                    -->
+                    <job-panel
+                        kinds="autotag-apply"
+                        heading="Applying tags"
+                    ></job-panel>
+                </div>
                 ${this.renderFolderSidebar()}
                 ${this.renderMain()}
             </div>

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

@@ -6,6 +6,9 @@ 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';
+import { ActiveViewController } from '@store/controllers/active-view-controller';
+import { ViewVisibilityController } from '@store/controllers/view-visibility-controller';
 
 type View = 'home' | 'albums' | 'tracks' | 'playlists';
 
@@ -113,8 +116,35 @@ export class BottomNav extends LitElement {
         }
     `];
 
-    @state()
-    private activeView = 'home';
+    /**
+     * Which tab is lit, read from the shell rather than tracked here.
+     *
+     * This was a `@state()` field set from the `navigate` event, which
+     * only the outbound path dispatches -- so backing out of a detail
+     * view left the highlight wherever it had been (#72). It had no
+     * equivalent of `app-sidebar`'s `navItems.some(...)` guard either,
+     * so a detail view set it to a name matching no tab and *nothing*
+     * was lit; that asymmetry is why one nav looked broken and the
+     * other looked fine. The store answers both: a detail view leaves
+     * the tab it was opened from lit, in both components.
+     */
+    private activeCtrl = new ActiveViewController(this);
+
+    /**
+     * The tab bar honours the sidebar's toggles (#25), and the reason is
+     * inside this component rather than a general rule about phones.
+     * `PHONE_COLUMN_IDS` is the precedent for "what a phone shows is a
+     * different question", and it would apply here too -- except that
+     * "More" opens the *same* `<app-sidebar>`, which filters. An
+     * unfiltered bar would therefore contradict its own drawer, one tap
+     * apart, and a destination the user switched off is off wherever it
+     * is offered.
+     *
+     * Which four tabs remains plan 016's committed subset; this only
+     * removes from it. Hiding all four leaves "More", which is always
+     * present and reaches everything.
+     */
+    private visibilityCtrl = new ViewVisibilityController(this);
 
     /**
      * Whether the drawer has been asked for.
@@ -138,7 +168,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() {
@@ -166,12 +196,9 @@ export class BottomNav extends LitElement {
         nameDialog(this.drawer);
     }
 
-    private onGlobalNavigate = (e: Event) => {
-        const detail = (e as CustomEvent<{ view?: string }>).detail;
-
-        if (detail?.view) this.activeView = detail.view;
-
+    private onGlobalNavigate = () => {
         // A navigation from inside the drawer is the drawer's job done.
+        // The highlight is not this listener's business any more.
         this.drawerOpen = false;
     };
 
@@ -201,13 +228,17 @@ export class BottomNav extends LitElement {
         return html`
             <nav aria-label="Primary">
                 <ul>
-                    ${BottomNav.TABS.map((tab) => html`
+                    ${BottomNav.TABS
+                        .filter((tab) => this.visibilityCtrl.visible(tab.id))
+                        .map((tab) => html`
                         <li>
                             <button
                                 type="button"
-                                class=${this.activeView === tab.id ? 'active' : ''}
+                                class=${this.activeCtrl.isActive(tab.id)
+                                    ? 'active'
+                                    : ''}
                                 data-testid="tab-${tab.id}"
-                                aria-current=${this.activeView === tab.id
+                                aria-current=${this.activeCtrl.isActive(tab.id)
                                     ? 'page'
                                     : 'false'}
                                 @click=${() => this.navigate(tab.id)}